Wires the lease + attachToken model end-to-end on the server side. The
client side (extension) lands in the next commit; agent side already
shipped in 449144cd.
Routes:
* POST /pty-session — mints sessionId (stable, loggable) + lease
(server-side bookkeeping) + attachToken (short-lived bearer for the
WS upgrade). Returns the 4-tuple in one round trip. Legacy
ptySessionToken / expiresAt aliases kept for one minor release so
extensions on the v1.43 wire shape keep working.
* POST /pty-session/reattach — validates a sessionId's lease and mints
a FRESH attachToken bound to the same sessionId. Used by Commit 3's
re-attach loop; 410 Gone when the lease has expired so the client
knows to fall back to a brand-new /pty-session.
* POST /pty-restart — one transaction: dispose the caller's existing
PtySession on the agent (via /internal/restart, scoped to one
sessionId — codex T2), revoke the old lease, mint a fresh
sessionId + lease + attachToken, return the 4-tuple. Zero race
window between kill and mint (codex T2 + D8 of the eng review).
* POST /pty-dispose — explicit teardown. sendBeacon-compatible: accepts
auth token in the body so the extension's pagehide handler (Commit 2C)
can fire it without setting custom headers (sendBeacon doesn't
support those). Without this route, every clean browser quit leaves
a zombie PTY alive for the 60s detach window — codex T3 caught it.
* POST /internal/lease-refresh — loopback from terminal-agent on its
25s keepalive cycle (lazy: only when lease is within 5 min of
expiry). Refreshes the lease AND resets the daemon idle timer. T6
of the eng review: PTY activity (not arbitrary SSE consumers) is
what keeps the daemon alive when the sidebar is in use.
Helpers:
* grantPtyToken now accepts optional sessionId and passes it through
to the agent's /internal/grant body. The agent binds token → sessionId
in its validTokens Map so /ws upgrades carry the sessionId for
/internal/restart and Commit 3 re-attach lookups.
* restartPtySession() — new loopback helper that POSTs the agent's
scoped /internal/restart with a sessionId body. Used by /pty-restart
and /pty-dispose.
Auth contract on /pty-dispose deliberately accepts the auth token in
EITHER the Authorization header OR the request body. The body path is
required for sendBeacon (which can't set custom headers); the header
path stays available for non-beacon callers and tests.
Test (browse/test/server-pty-lease-routes.test.ts):
* 7 static-grep tripwires pinning the 4-tuple shape, validate-first
re-attach with 410 fallback, one-transaction restart semantics,
sendBeacon-compatible dispose auth, and the T6 PTY-only idle reset.
* Live route exercises (full mint + grant + WS upgrade cycle) belong
in the e2e tier — they require a real terminal-agent loopback and
take seconds per assertion.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
25ef24e92e