Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.
JavaScript agentic-codingai-agentsai-governanceautonomous-agentsclaude-codeclicode-reviewcodexcoding-agentsdeveloper-toolsgit-hooksllmlocal-firstmulti-agentsoftware-factoryspec-driven-developmentverificationvibe-coding
docs(relay): explain fresh copies after explicit unlink [H17]
Corey Olson2ffdbe4dac00
diff --git a/docs/api.md b/docs/api.mdindex 1c33d964..53f5f2c7 100644--- a/docs/api.md+++ b/docs/api.md@@ -343,6 +343,8 @@ Residual: tokens on disk, in the repository's shared `relay.json`, are readable`GET /auth/machines?board=<id>` returns `{version, machines: [{machine, host, created, seen}]}` for the live computer credentials on that board, with duplicate computer ids listed once. `host` is the host name the computer sent when it joined, or null; `created` is its first join and `seen` its last relay contact, which moves at most once a minute. It requires that board's machine credential or a person session with current repository write access; agent tokens and credentials from another board are refused. `relay off` excludes its own computer from the list and warns which joined computers lose the shared copy if the phone approves deletion. The warning names each computer by its host name, or by the end of its id when the relay has no host for it. JSON also returns those ids in `affectedMachines` and the names in `joined`. Local unlink still succeeds when the relay cannot supply the list.+After explicit `relay off`, `relay on` creates a fresh board id and key from the complete local board. It does not rejoin or replace the old remote board; the first successful relink says that the old copy remains until the person deletes it from the phone. Interrupted linking retries the saved new identity and key. Old encrypted outbox obligations and their key-free board/relay/sequence context remain beside the local board as separate private archives; they are not replayed under the new key or reported as remotely accepted. Only their actual native effects enter the new baseline. Rejoining the original remote board requires its key from a member device.+After phone-approved deletion, a previously live scoped credential receives HTTP 410 / `RELAY_BOARD_DELETED` for that deleted copy. The relay retains only its hash, board id and original expiry as a deletion receipt, prunes expired receipts, and grants no access through them. Unknown, already revoked and already expired credentials receive `AUTH_REQUIRED` as before. Only a versioned deletion response naming this link's own board turns a joined computer back into a local board. The CLI removes the inert link and its device key, excludes the project from automatic relinking, and retains a private credential-free notice that the relay copy was deleted; native board contents remain local. A successful explicit `relay on` starts a new link and clears that notice. A network outage or ordinary credential refusal does not authorize this transition. Before forgetting a deleted copy, the CLI commits any pending native move and its durable receipt locally. The notice keeps only the receipt id and intent digests, so interrupted cleanup or an explicit repeat can return the original outcome without applying that move twice; different local work can continue beside it.A machine publishes an opaque approval with `POST /api/v1/devices/approvals {context,sealed}`. The publishing machine may GET only its own requests. The paired phone reads `/api/v1/devices/:deviceId/approvals`, explicitly POSTs `/:requestId/authorize {}` and completes the encrypted reply through `/:requestId/complete {response}`. The publishing machine executes a native revocation through `/:requestId/execute {grant}`; the two-minute grant binds the entire context and is atomically consumed once. Native reply keys and grants never persist. A refused foreground approval fails immediately with the original refusal code and reason plus its request id. A refused remote approval makes local unlinking or registration exit nonzero while retaining the completed local work: one line names that completion, the refusal code and reason, the request id and the next action. The JSON result preserves the local outcome and includes `remote: {code, reason, requestId}`. New-board linking uses a durable non-person reply key and returns only a board-scoped machine credential. `relay off` immediately unlinks locally even offline or in an agent shell, reports that the relay copy remains, and queues a separate one-tap phone deletion request when possible.