Alerts and phone approvals#

Lockpin can tell you before and when money runs out, instead of you watching the meter. This page covers the alert kinds, sending them to Slack, Microsoft Teams, ntfy, a webhook or a paired phone, the weekly digest, and answering held calls from a phone or chat. It is for developers and team leads who want spend news where they already look.

Before you begin#

Lockpin is running.
For Slack, an incoming webhook URL. For Teams, a Workflows webhook (“Post to a channel when a webhook request is received”). For ntfy, a topic URL. For a phone, a browser that can add a page to the home screen.

Alert kinds#

Kind	When	How often
`threshold`	A task has spent each `-task-warn-at` percent of its budget (75 and 95 by default), or spend reaches `-alert-at` percent (80 by default) of a key, team, tag, project or per-user limit	Once per step per task; once per limit per period
`key_expiring`, `key_expired`	A Lockpin key ends within 14 days, within 3 days, and when it has ended (team mode)	Once per key, end and stage
`blocked`	The cap stops a call	Once per limit per period
`breaker`	The spend circuit breaker trips	Once per trip
`loop`	A task repeats the same tool call with the same result 3 times	Once per loop
`drift`	Drift tracking flags redone, undone or lost work costing at least `-alert-drift-usd` ($0.50)	Once per finding
`spike`	Today (UTC) a task, key or user has spent `-spike-x` (3) times its usual day, and at least `-spike-min` ($5)	Once per subject per day
`fault`	One of Lockpin’s own parts failed and a call was refused or passed because of it	At most one per part every 10 minutes
`digest`	The weekly digest	Once a week

A raise of a budget or a loosening of the breaker shows as a red loosened alert in the meter.

The “usual day” for a spike is the median of the subject’s days with spend in the last 14; it needs 3 such days.

Where alerts show#

Without any setup, alerts show in the meter (the latest 20), in VS Code’s Problems view, and on the members’ page in team mode. lockpin.alertNotifications in VS Code also pops each one up.

Send alerts to Slack, Teams, ntfy or a webhook#

Set the destinations as environment variables where Lockpin runs. The URLs are secrets: prefer the environment variables to the flags, and keep them out of shared shell history.

Windows

$env:LOCKPIN_ALERT_SLACK = "https://hooks.slack.com/services/..."
$env:LOCKPIN_ALERT_TEAMS = "https://...logic.azure.com/workflows/..."
$env:LOCKPIN_ALERT_NTFY = "https://ntfy.sh/<a long random topic>"
$env:LOCKPIN_ALERT_WEBHOOK = "https://example.com/lockpin"

macOS and Linux

export LOCKPIN_ALERT_SLACK="https://hooks.slack.com/services/..."
export LOCKPIN_ALERT_TEAMS="https://...logic.azure.com/workflows/..."
export LOCKPIN_ALERT_NTFY="https://ntfy.sh/<a long random topic>"
export LOCKPIN_ALERT_WEBHOOK="https://example.com/lockpin"

Set only the ones you use. The flags -alert-slack, -alert-teams, -alert-ntfy and -alert-webhook do the same.

Send one test alert to each destination. It costs nothing:
```
lockpin alerts test
```
Start (or restart) Lockpin so it picks up the destinations.

Warning

Whoever knows an ntfy topic can read its messages. Use a long random topic or your own ntfy server.

What each destination gets#

Slack, Teams, ntfy and paired phones get a plain message that ends with the time the numbers were read (“as of …”).
The webhook gets JSON with kind, subject, period, limit_usd, spent_usd, percent, resets_at, task and message.

How alerts are delivered#

Alerts never slow down or block a call: they wait on a queue and go out in the background, with 3 retries.
Each alert is written to the ledger, so a restart does not send it again.
Lockpin never logs or shows the webhook URLs.
If a destination cannot be reached, calls go on and alerts show as degraded.

Pair a phone#

A paired phone gets Lockpin’s alerts, its weekly digest and, with -ask-remote, its questions about held calls, as end-to-end encrypted notifications. There is no app store: the page installs to the home screen.

Start pairing:
```
lockpin phone pair
```
It shows a link and a QR code, and waits up to 15 minutes (-wait).
On the phone, open the link. Use Share, then Add to Home Screen. On iOS, Web Push works only from a home-screen app, on iOS 16.4 or later.
Open the app from the home screen and tap Turn on notifications.
The command saves the phone and sends a first push.

Manage paired phones:

lockpin phone list       # the paired phones
lockpin phone forget     # unpair them all

The phones are kept next to the ledger. -relay names the relay that serves the phone page (default https://app.lockpin.dev).

Answer held calls from a phone or chat#

With -ask-remote (off by default), a call held at its task’s budget is also asked about in Slack, Teams, ntfy and on paired phones, with Stop, Allow this call and Raise budget. A loop question has Stop and Continue.

lockpin -ask-remote

Answers come back through a relay that sees only the question number and the answer, signed by your machine. Lockpin polls the relay; it never accepts a connection from outside.
While the relay answers, someone counts as watching, so calls are held for up to -ask-at-cap. If nobody answers, the call gets its 402 when the hold ends.
If the relay cannot be reached, nobody counts as watching remotely, and calls are refused at once as before. The relay can never make a call wait longer than -ask-at-cap, and never lets one through on its own.
A yes from a phone, Slack or Teams is marked “not confirmed with a passkey” in the alert.

The weekly digest#

Every Monday at 09:00 on this machine (-digest-at), a running Lockpin posts the last 7 days to the alert destinations: spend against the week before, what Lockpin saved, calls blocked, loops caught and the top tasks. Nothing is sent in a week with no spend.

lockpin digest           # print it now
lockpin digest -send     # post it now
lockpin -digest-at off   # never post it

Tune the thresholds#

Flag	Default	What it does
`-task-warn-at`	`75,95`	Warn at these percents of a task’s budget, once each. Empty: one alert at `-alert-at`.
`-alert-at`	`80`	Alert at this percent of a key, team, tag or project limit. `0`: only when the cap blocks a call.
`-alert-drift-usd`	`0.5`	Drift findings costing at least this alert. `0`: never.
`-spike-x`	`3`	Spike multiple. `0` turns spike alerts off.
`-spike-min`	`5`	Spike alerts only for days of at least this many USD.
`-digest-at`	`mon 09:00`	When to post the weekly digest; `off` never posts it.

Verify#

Run lockpin alerts test. Each configured destination, and each paired phone, gets one message.
Run lockpin phone list to see the paired phones.