[allisonmahmood]

Stacked on #916 (then #914, #913). Merge those first; the onboarding stack ships together.

What changed

The Final step panel could only notice the end of each step: any new computer of the person's, then a patch of theirs. Nothing moved for about a minute after the paste, and any old laptop counted.

The panel's line now carries a one-time setup link: Set up Patchy using <instance>/llms.txt?s=<link>.

• The agent's fetch marks the line picked up, within seconds of the paste.
• /llms.txt prints patchy login --setup <link>.
• The first login that line starts binds to it; a second contests it.
• The mint records which key it made and who confirmed it.

The panel follows those facts. When a setup can't finish, it says why and offers Get a new line. Events carry a separate setup id, so one person's setup reads as a single funnel in PostHog.

Closes #910. Part of #906.

Look at

• packages/auth/src/SetupLinks.ts and migration 0027.
  • A link is 128 random bits as 26 base32 characters, one live per person for 30 minutes, reused across reloads.
  • It keeps how its login ended: pending, denied, expired, contested, connected, or confirmed by another account. Device logins are deleted when they finish, so the outcome has to live here. A login that mints after its line ran out ends expired.
  • device_logins.setup_link_id is nullable and ON DELETE SET NULL.
• DeviceLogins. start binds, deny marks denied, a login that runs out marks expired before it is deleted, and the mint records the key and the confirming user in its own transaction. token.minted gains setupId.
• The front door. A narrow SetupPickup port, which apps/server/src/SetupPickup.ts provides. The SDK gains no Auth dependency. Pickups spend a per-address minute's budget (rate.setupPickup.perMinute) before reaching the database. An unknown, expired, over-budget or failing link serves the plain /llms.txt, so setup never breaks.
• The CLI.
  • patchy login --setup <link> keeps the link in its pending login.
  • A rerun with the same link resumes. A rerun with a different link (or a link when none was pending) starts afresh and says the earlier code no longer applies.
  • --setup with --complete is refused.
  • ADR-0004 and the README record this.
• The panel's states, in a real browser. Each moved on by itself on a dev instance: the agent's fetch, then a login started with the link, confirmed in another tab, then its key collected.

Picked up	Login waiting	Confirmed, key not yet collected

Connected: this setup's key	Two logins used one line

How it was verified

• pnpm exec vitest run across packages/portal, packages/auth, the front door, the CLI's login, packages/api, packages/limits, packages/core, Patches and the server's migration record: 1,121 tests pass. New ones cover:
  • links: one live per person, pickup once, retire;
  • binding, contested, denied, expired (by poll, and by a mint after the line ran out), a contested line's mint, and the owner's mint against another account's;
  • token.minted's setupId;
  • the front door's live, unknown and failing links, and the pickup budget per address;
  • the CLI's same-link, new-link and legacy reruns;
  • the panel following a line through every state, including a login that runs out with nothing polling, plus Get a new line's origin and stale-account refusals.
• pnpm typecheck and pnpm lint pass. docs/API.md and docs/limits.md are regenerated, and the skill's lock hash is refreshed.
• Not run locally: pnpm verify and the rollback rehearsal. CI runs both.

Release impact

• Breaking — requires action from anyone already running this
• Not breaking — no action required

The API field and the CLI flag are optional and additive. The migration adds a table and a nullable column.

• What does a revert leave behind? The setup_links table and device_logins.setup_link_id. Old code never reads them.
• Does the release before it still work with that? Yes. Agents holding the new --setup command would need the matching CLI, but /llms.txt installs the instance's own release first.

Made by Claude Opus 5.5 in Claude Code, running in T3 Code.

[allisonmahmood]

Review (GPT 6.1 Sol, xhigh): six fixed in 23c0af4, one dismissed

1. Dismissed: "any live machine token overrides the setup link's outcome". The panel exists to answer one question: can this person's agent act as them yet? A live key of their own says yes, however it was made. The cases Sol raises don't give the person a wrong answer:

   • A contested line where they confirm one of the two logins: they now hold a working key, so "connected" is true. The contested warning matters before they confirm, and it shows until then.
   • "Confirmed by another account": that key belongs to someone else. If the person also has a key of their own, they're connected; if not, the panel shows the other-account fallback.
   • A revoked bound key: revoked keys aren't listed. With no other key, the panel falls back to the line; with one, they're connected.

   Deriving "connected" only from the bound token would tell someone holding a working key that setup failed. The bound token still decides which first publication counts (publishedWith([bound])).

2. Fixed: expiry is recorded and checked. expired is a new outcome, migration 0027 allows it, and both the start's purge and the poll write it before deleting the login. The panel also reads the login's deadline on the app clock, so an unanswered login shows expired with no later poll or start. Tested in PortalPages.test.ts ("A login left unanswered…") and SetupLinks.test.ts.

3. Fixed: a login that mints after its line ran out ends expired, not connected (SetupLinks.minted). Tested.

4. Fixed: /llms.txt pickups spend a per-address bucket (rate.setupPickup.perMinute, 30, host scope) before reaching SQL, keyed by the trusted client address. Past it, the agent gets the plain page and setup still works. Tested in apps/server/src/SetupPickup.test.ts, and docs/limits.md is regenerated.

5. Fixed: a contested line's bound mint still records its key and who confirmed it, and returns the setup id, so token.minted keeps setupId. The outcome stays contested. Tested (contest, confirm the original, poll).

6. Fixed: patchy login --setup says when it abandons a pending login: in human output and at the front of agentNextSteps. next stays executable. Asserted for a legacy pending login and for a different line.

7. Fixed: values are 26 lowercase base32 characters (128 random bits). The parser, the migration's CHECK, the glossary and the assertions are updated together.

Checks: typecheck, lint and 94 affected test files (1,121 tests) pass locally.

[allisonmahmood]

Follow-up from #918's security review: a deadlock this PR introduced, fixed in 4a03a91.

The expiry fix above made start's cleanup write the expired outcome to a setup line before deleting its login. The poll and every answer lock the login first, then the line. So cleanup racing a poll of the same expired login could deadlock (Postgres 40P01). Cleanup now locks the expiring logins first, in user_code order, then writes their lines, then deletes.

Red then green: SetupLinks.test.ts › "cleans up an expired bound login without deadlocking an answer to it" holds the login, waits until start is blocked on it, then takes the line.

• On the old cleanup: Error: deadlock detected … code: '40P01'.
• On the fix: passes.

[allisonmahmood]

Follow-up from #918's second security round: one more lock-order inversion, fixed in 2455397.

SetupLinks.current prunes lines more than a day past expiry. If an abandoned login still named one, deleting the line made the foreign key's ON DELETE SET NULL lock that login after the line. That is the reverse of cleanup, the poll and every answer, and Sol reproduced 40P01. Pruning now skips a line any device login still names. It goes once that login's own cleanup has run.

Red then green: SetupLinks.test.ts › "prunes a day-old line only once no login names it".

• On the old pruning: expected [] to have a length of 1.
• On the fix: passes.