[garrytan]

Why (in your own words)

Revoking a paired agent was a lie twice over. revokeToken deleted only the first Map entry for a clientId, and the spent setup key kept for connection retries always sat first in line: DELETE /token/<agent> returned 200 while the live session kept driving the browser, a leftover unspent setup key could mint a brand-new session for a "revoked" agent inside the key's 5-minute window, and a second DELETE returned 200 again. The documented way out, $B tunnel revoke, did not exist — the CLI forwarded it to the daemon as Unknown command: 'tunnel'. And the pairing docs still promised a read+write sandbox ("Cannot execute arbitrary JavaScript, read cookies, or access storage") three releases after b73f364 deliberately made pairing full-access, so a user following the skill believed they granted a sandboxed session and actually granted JS execution on their logged-in browser.

This PR makes revocation total and verified, makes the documented CLI real, pins the pairing default in one shared constant, and rewrites the docs to the truth. Along the way it closes four adjacent traps found during review: bare --restrict silently granted FULL access (the opposite of intent), a scopes list could smuggle in the control scope, scope typos surfaced as a misleading error to the remote agent at /connect, and rateLimit: 0 (documented "unlimited") silently became 10 on the /pair path.

Live evidence

BEFORE — origin/main @ 9da6692, BROWSE_HEADLESS_SKIP=1 daemon, mallory paired + connected, second setup key pending:

$ DELETE /token/mallory
HTTP 200
$ GET /agents
{"agents":[{"clientId":"mallory","scopes":["read","write","admin","meta"],...}]}   # still listed
$ POST /command with the 'revoked' token
HTTP 403                                                                            # NOT 401 — token still authenticates
$ POST /connect with the leftover setup key (within its 5-min window)
{ "token": true, "scopes": ["read","write","admin","meta"] }                        # new session minted post-revoke
$ DELETE /token/mallory (second call)
HTTP 200                                                                            # false 200, again

AFTER — this branch, same ceremony:

$ browse tunnel agents
mallory  scopes=read,write,admin,meta  domains=any  expires=2026-08-21T04:04:40.869Z  commands=0
mallory  (pending setup key)  scopes=read,write,admin,meta  domains=any  expires=2026-08-20T04:09:40.872Z  commands=0
$ browse tunnel revoke mallory
Revoked "mallory" (3 tokens).
Verified: not in the active agent list.
$ GET /agents
{"agents":[]}
$ POST /command with the revoked token
HTTP 401
$ POST /connect with the leftover setup key
HTTP 401
$ browse tunnel revoke mallory (second call)
No paired agent named "mallory".
No agents are currently paired.
exit: 1
$ POST /pair with a scope typo
{"error":"Invalid scope: raed. Valid: read, write, admin, meta, control"}
$ POST /pair smuggling control in scopes
{"error":"The control scope requires the control flag (--control); it cannot be granted via a scopes list."}

Fail-first: the shape a/b regression tests run against origin/main fail (0 pass, 2 fail — session survives revoke; leftover key re-connects); on this branch the committed versions pass.

(fail) fail-first: revoke-all shapes on origin/main > shape a: revoke kills the session shadowed by a spent setup key
(fail) fail-first: revoke-all shapes on origin/main > shape b: unspent setup key dies with the revoke (no re-grant)
 0 pass
 2 fail

Targeted suite on the branch: bun test browse/test/token-registry.test.ts browse/test/pair-agent-e2e.test.ts browse/test/tunnel-revoke-cli.test.ts browse/test/server-auth.test.ts browse/test/tab-isolation.test.ts browse/test/skill-token.test.ts → 178 pass, 0 fail. bun run gen:skill-docs --host all → zero drift. bun run build → clean.

Scope

• Changed: browse/src/token-registry.ts (revoke-all + count, DEFAULT_PAIR_SCOPES, InvalidScopeError, shared option validation, listTokens({includeSetup}), invariant comment), browse/src/server.ts (/pair control gate + typed 400s, /agents pending keys, DELETE /token decode + tokens_deleted, 403 hint), browse/src/cli.ts (tunnel revoke/tunnel agents with post-revoke verify, validatePairAgentFlags, explicit scopes), browse/src/skill-token.ts (Boolean wrap), docs (pair-agent/SKILL.md.tmpl + regenerated SKILL.md, docs/REMOTE_BROWSER_ACCESS.md, ARCHITECTURE.md), tests (35 new cases incl. a subprocess CLI harness with stub daemons pinning the version-skew net and every CLI error branch), VERSION/CHANGELOG.
• Verified live by: the before/after transcript above, the fail-first run on origin/main, the 178-test targeted loop, the gen-skill-docs drift gate, bun run build, and a pre-push adversarial review (4 lenses, refute-style verification: 13 raw findings, 7 refuted, 6 confirmed and fixed in the final commit — including an --restrict=read equals-form bypass of the new validation).
• Did NOT test: the live ngrok tunnel path (needs an authtoken; the tunnel allowlist code is unchanged — TUNNEL_PATHS still /connect + /command). The full free suite in my sandbox has pre-existing environment failures OUTSIDE browse/ (relink/session-update/skill-validation fail identically or worse on untouched origin/main there — missing file binary, symlink collisions with a live gstack install); all browse/ shards pass locally, and the authoritative full run is this PR's free-tests.yml lane.

Notes for the reviewer:

• The "Revocation incomplete" CLI branch doubles as a deliberate version-skew net: a NEW CLI pointed at a still-running OLD daemon (first-match revoke bug) gets caught by the post-revoke /agents re-read, exits 1, and suggests re-running (which converges on old daemons) or stop. Pinned by a stub-daemon test.
• POST /token (root direct mint) intentionally still accepts explicit control in scopes — root minting explicit scopes is the deliberate path; only the /pair ceremony gates it behind the control flag.
• The re-grant hole is time-boxed by the setup key's 5-minute expiry; the transcript's leftover-key step ran inside that window.

Liveness proof (required)

Maintainer-authored PR, prepared by Claude Code in a cloud sandbox at the owner's request — there is no human screen in the loop to photograph. @garrytan: attach a GSTACK PR screenshot from your machine if you want the ritual observed for maintainer PRs, or waive it.

Checklist

• Liveness screenshot attached: GSTACK PR typed live into a real surface (owner to attach or waive — see above)
• This is not a generated-file-only diff (I edited the source/template and regenerated)
• No ETHOS.md edits, and no changes to voice / founder perspective / YC references
• New public command / external service / host adapter has an accepted issue linked (or N/A — tunnel revoke/tunnel agents implement the already-documented CLI surface)
• Linked issue or reproduction: reported against 1.60.1.0 by the maintainer; reproduction transcript above

🤖 Generated with Claude Code

[trunk-io]

😎 This pull request was merged.

[github-actions]

E2E Evals: ✅ PASS

8/8 tests passed | $1.48 total cost

Suite	Result	Status	Cost
e2e-browse	2/2	✅	$0.16
e2e-deploy	2/2	✅	$0.36
e2e-qa-workflow	1/1	✅	$0.58
llm-judge	1/1	✅	$0.02
e2e-deploy	2/2	✅	$0.36

---

ubicloud-standard-8 runners (Docker: pre-baked toolchain + deps) | wall clock ≈ slowest suite