Dev → Agents: rebuild the sandbox UX as agent sessions

[2witstudios]

Why

The unreleased Machines/"Development" surface made git the information architecture (Machine → Project/repo → Branch). It competed with PageSpace's own filesystem semantics — three parallel trees on screen (drive page tree, repo/branch tree, sandbox POSIX tree) — and needed routing hacks (twin route trees + a keep-alive host) just to stop navigation from killing warm PTYs.

The insight driving the rebuild: the global assistant already worked well as a dev. So the primitive isn't "a dev environment," it's an agent session — any conversation that can lazily acquire a sandbox. That one primitive solves the dev UX and generalizes it: coding agents, data-analysis agents, file-processing agents, anything needing compute plus a filesystem gets the same flow with zero dev ceremony. Git becomes an agent capability, never user topology; dev-specific magic (branch isolation, repo pinning) can layer in later without touching the session model.

What changed

Topology: Drive → Agent (AI_CHAT page) → Conversation. Each conversation lazily owns one sandbox (Fly Sprite); shells are PTYs inside it. The MACHINE page type is gone.

Two invariants, documented once in packages/lib/src/agent-sessions/contract.ts and enforced everywhere:

• sessionId ≡ conversationId — agent_sessions uses PK = FK on conversationId. One id addresses the tool call, the URL ?c=, chat anchoring, and the Sprite-key fold. There is no session-binding field anywhere; the chat body's conversationId is the session address.
• Ids address, names label — names enter only at spawn; every verb afterward takes an id. Worker names carry no uniqueness constraint.

Surface: new /dashboard/agents (global + drive-scoped). Selection lives in the URL (?agent=&c=) via pushState, so nothing remounts on switch — the keep-alive host has no successor. One UI everywhere: opening an AI_CHAT page and selecting an agent in the console render the same AgentView. AiChatView.tsx (1,600 LoC) is deleted.

Tools: two verb families, nine tools — list/spawn/send/read/kill_session + spawn/send/read/kill_shell. spawn_session requires a prompt and dispatches through the standard chat pipeline, so a spawned worker is a normal conversation visible live in the sidebar — never a second engine. ask_agent is gone as a tool (its sync consult is now wait: true); its internal engine is retained unchanged for the channel-mention responder. move_session, add_session, switch_machine, list_machines, and the headless-run engine are deleted. All 56 git/gh tools kept verbatim — the simplification came from deleting topology, not hardened wrappers.

Purity discipline (AIDD: clean seams now, not incrementally): every lifecycle, access, naming, and status decision lives in a pure, exhaustively-tested module. Notably decideSessionAccess is one function consumed by both the web routes and the realtime bridge — the two tiers structurally cannot diverge. Both tiers also provision through the single shared ensureAgentSessionSandbox, so they can't CAS-fight.

Numbers

521 files changed · +26,828 / −82,881 → net −56,053 LoC of source (the +64,841 in the raw diffstat is Drizzle migration meta snapshots, which are generated).

Phases

#	Phase	Highlights
0	Contract & pure foundations	5 pure modules, 156 tests
1	Schema & migrations	agent_sessions (PK=conversationId), agent_session_shells, reclaim trigger
2	Session services	Provisioning port (clone arms dropped), stores, access wrapper
3	Realtime re-key	shell:* events addressed by {shellId}; 1,235 tests
4	API + AI tools	Flat /api/agent-sessions, nine tools; −4,098 LoC
5	Frontend skeleton	Pure URL/status/badge/tab modules, store, sidebar
6	Unified AgentView	AiChatView deleted; page + console convergence
7	Billing re-point	One listAgentSessionSprites() replaces a three-table de-fan
8	Teardown	M3 rescue-and-drop, MACHINE scrubbed repo-wide

Migration safety

DROP TABLE does not fire per-row AFTER DELETE triggers, so dropping the machine tables outright would have stranded live billing VMs forever. Migration 0234 therefore rescues every live Sprite pointer into machine_sprite_reclaims first, then deletes MACHINE pages, then drops triggers, tables, and columns. The FK-less outbox is deliberately kept — the orphan cron still drains it. Postgres can't DROP VALUE from an enum, so the dead MACHINE value stays in the pg enum (commented) while being removed from the TypeScript enum and every config, validator, and drift guard.

The feature was never released, so there is no data migration and no compatibility layer.

Review rounds (post-open)

Two rounds: an automated review plus a full-branch review, then an adversarial re-review of the fixes themselves. All findings are addressed; threads stay open for reviewer verification.

Round 1 — reviewer findings

Security / correctness

• Self-dispatch SSRF + credential leak — the hop built its URL from x-forwarded-host/host and forwarded the caller's cookie/CSRF to it. Now uses the configured origin only, restricted to http/https (new URL('localhost:3000') parses with protocol localhost: and would otherwise slip through). Also fixed a silent break on plain-HTTP deploys.
• Live-session quota was never enforced — the helper had no production caller. Now a required dep of the shared provisioner, firing only where a VM is minted; placed there because the realtime bridge calls the provisioner directly and bypassed a web-only check.
• Storage was never measured — no writer existed, so every session priced at the $0 floor while the watermark advanced.
• Shell errors killed every pane — an untagged shell:error was claimed by every shell on the socket.
• git argv safety — git_add separates pathspecs with --; git_reset.ref / git_remote_add.name gained the flag guard their siblings had.

Functional / UX — the delegation prompt no longer names a tool absent under the active gates (both CODE_EXECUTION_ENABLED and read-only); a failed agent load shows an error + retry instead of an infinite spinner; terminal panes are ARIA-labelled; conversation-creation failures surface.

Robustness — orphan reconcile sources no longer take each other down; a doubly-failed teardown (kill and outbox insert) logs loudly instead of silently leaking a billing VM; the dispatch-depth clamp is one tested module; the third messages route uses the repository like its siblings.

Round 2 — adversarial re-review of those fixes

Three of the round-1 fixes were incomplete, which the re-review (and my own verification) caught:

• Quota exemption had a ceiling bypass. The resume exemption tested sandboxId !== null, but countLive also requires spriteTornDownAt IS NULL, and teardown leaves sandboxId set. So every ended session claimed the exemption: end N, re-provision N, hold N live sandboxes past the ceiling. The predicate now mirrors the count exactly.
• Storage measurement only ever saw an empty sandbox. It fired solely in the provisioner's create arm, on a VM minted milliseconds earlier — so a session could clone a 3 GB repo and still bill ≈$0. Measurement now also runs where an agent is about to do real work in an awake sandbox, throttled per session.
• reauthorizeViewer was never wired, so the fail-closed default meant the viewer identity was never refreshed: revoking the original owner would evict a different member's running work. Now wired to the same check the socket connect uses, and the previously ungated read path is gated identically.

Also from round 2: a quota refusal was being delivered as a 403 authorization denial (now a 429 with the real message and a non-authz audit event); over-cap input vanished silently (now refused with a tagged shell:error); a permanently failing reconcile source was invisible in the result (now reports incomplete); and the aria-live half of the terminal a11y change was inert, since xterm marks its own rows aria-hidden — removed rather than left as an unearned guarantee.

Round 3 — the refusal reported as three different wrong things

The ceiling itself was now enforced correctly, but every surface described it differently, and none of them described it as a plan limit:

Surface	Before	After
Socket connect	Shell access denied: session_limit_reached	names the limit, and what clears it
Headless start (agent send_shell/read_shell)	{live: false, delivered: false}, no reason	same, plus a reason
Sandbox + 56 git/gh tools	Could not provision a sandbox for this run.	session_limit_reached, its own denial reason
HTTP route audit	eventType: 'data.read'	eventType: 'security.rate.limited'

Each was wrong in its own way. "Access denied" sends a user who has every right to that shell hunting a permissions bug that doesn't exist. No reason at all is worse than a wrong one — the agent can't tell a transient miss from a wall it will hit every time, so it retries forever; startSession now returns a typed ShellStartRefusal, with undefined still meaning "refused with nothing to say" (notably an abandoned request), so existing callers are unchanged. The tool path's reasonFromAcquire was a translation seam that had never translated anything; session_limit_reached is now deliberately distinct from concurrency_limit, because that one clears when a sibling run finishes and this one doesn't clear until somebody ends a session — so "wait and retry" is precisely the wrong advice. And data.read filed every free-tier user's "new session" click into data-access forensics for a request that read nothing.

The web tool client also stopped guessing: it used to tell the agent the payer "may be out of credits or at the concurrent terminal limit", a disjunction it cannot act on since only one arm is worth waiting out.

Also this round: the store integration test now reads sandbox pointers back out of the DB before deleting sessions, so the FK-less reclaim rows its own AFTER DELETE trigger enqueues are actually cleaned up — the file's comment claimed this, but it left five behind, each a name the orphan cron would later try to destroy.

Round 4 — the agent shell tools had never worked

Found while auditing round 3's own changes, and the most serious thing in the PR.

Phase 3 renamed the realtime bridge's routes from /api/session-* to /api/shell-*. The web tool client written in phase 4 kept posting to the old names, so every read_shell and send_shell 404'd, postSigned mapped the non-2xx to null, and the agent was told "Could not reach the terminal service" — about a service that was running fine.

The read path was wrong three ways, not one:

	Client sent	Endpoint serves
Route	/api/session-read	/api/shell-read
Payload	{shellId}	{shellIds: []} (it also serves the multi-shell liveness sweep)
Response	flat {live, output, …}	{shells: [...]}, one entry per id

A missing entry for the id we named is now "no answer" rather than "not live" — reporting a running build as dead is the one wrong answer this tool must never give.

Why nothing caught it, and what actually got fixed. Each side is unit-tested against a mock of the other, so both suites were green against a hop that could not connect. Patching the path would have left that intact, so the routes and the read/send payload and response shapes now live in agent-sessions/contract.ts, imported by both apps. That module's rule is that no shape is declared twice, and a string two services must agree on is a shape. It earned its keep immediately: the compiler caught that postSigned narrowed start to true where the wire type allows boolean.

The same drift had quietly killed the agent-activity feed. The realtime handler was re-keyed to sessionId, fully implemented, tested, and wired with real deps — its own doc says "apps/web posts here after a successful bash run" — but the caller was never rewritten. It still posted a machine-era {tenantId, driveId, pageId} body to /api/terminal-activity, and sandbox-tools-runtime had stopped supplying the seam at all, so the feature was dead on both ends. Re-keyed end to end and wired. Its gate also moved from the agent page id to the session id, fixing a silent exclusion on top: a global-assistant session has no agent page and so could never have appeared in this feed regardless.

Adjacent surfaces audited for the same class of drift and found consistent: the four shell:* client→server and four server→client socket event names, the shared connect-payload schema, every /api/agent-sessions/** path the frontend fetches, the nine session/shell tool names against their prompt references and registration, and the cron paths (deliberately unchanged, and documented as such).

Round 5 — hunting the pattern instead of waiting for it

Rounds 3 and 4 were both "one concept, two implementations." Looking for that deliberately turned up two more.

spawn_session's pre-check disagreed with the gate it pre-checks. Both enforce the same concurrency ceiling; the provisioner calls store.countLive, the pre-check re-derived it in JS with an extra endedAt === null clause under a comment claiming identical semantics. That clause undercounts — endedAt is intent, spriteTornDownAt is the VM being gone, and they diverge whenever a kill fails and teardown falls back to the reclaim outbox, while the Sprite is still billing. The pre-check would wave a spawn through that the provisioner then refused. It now calls countLive instead of restating it (also turning a full listing plus JS filter into a SQL COUNT), with the disagreement case pinned in the real-Postgres suite.

'starting' was documented but never existed. The backend derivation explains it as a client-side transient "shown while its own ensure request is in flight". Nothing implemented it, so through an entire cold Sprite boot the chip read "No sandbox — one starts the first time the agent needs to run something", false precisely then, before jumping to "Ready". Wiring it surfaced a second layer: useAgentSession.ensureSession has no component caller, since provisioning is lazy and there is no explicit start affordance — the cold start a user actually watches is Add shell. The rule now lives in a pure resolveDisplayStatus, and only ever upgrades from 'none', so a second shell on a live sandbox never reads as a boot.

Checked and sound, no change needed: migration 0234's rescue-before-drop ordering; the machine_branches rescue predicate (its missing IS NOT NULL guard mirrors that column being .notNull() where its siblings are nullable — an asymmetry worth knowing before someone "fixes" it); the agent_sessions reclaim trigger, whose live predicate matches countLive, storage billing and the provisioning exemption — five sites now agreeing; every pure module the plan specified having real non-test consumers, including decideAgentSessionAccess genuinely being the one access decision for both web and realtime; the plan's flagged sidebar-freeze bug being fixed in production code (isAnyEditing() excludes 'shell'), not only in its test; and the signed shell endpoints, which are internal-only (Caddy routes just /socket.io/* to realtime), HMAC-signed with a 5-minute window and constant-time comparison, matching the pre-existing /api/broadcast posture.

Round 6 — one bug class, searched exhaustively

Rounds 4 and 5 were each an instance of the same thing without my noticing: an optional dependency, declared with a safe default, that nothing ever supplied. notifyShellActivity (the agent-activity feed) and reauthorizeViewer (the identity re-check) were both found one at a time. So I enumerated every optional dep in the new interfaces and checked each for a production supplier.

measureStorage had zero. Master supplied it; this branch dropped it, and my earlier replacement called measurement from acquireSandbox — before the op. The seam's own comment explains why that is wrong: it fires from release, after the op, because measuring first records the pre-write footprint and then lets the per-session throttle suppress the real one. An agent writing 5 GB stayed invisible until the throttle lapsed. Removed the pre-op call, supplied the post-op seam, re-keyed it from pageId to sessionId (a global-assistant session has no page — the same page-shaped assumption that had excluded those sessions from the activity feed), and pinned the ordering with a test, since "measures at all" was true of the broken version too.

The same seam was then wired on the git path, which had never measured at all — it has its own acquire/release. That gap is pre-existing rather than a regression, but git_clone is the largest writer in the system, and a session that only ran git tools billed its empty-disk baseline forever.

Why this class is invisible. An optional dep with a safe default cannot be caught by types (it is legitimately absent), by coverage (the line runs, the branch is just false), or by the feature's own tests (they inject the dep themselves). Only asking "who supplies this in production?" finds it. All three are now pinned by presence assertions, each verified by deleting the wiring and confirming the test fails.

Three stale doc-comments also surfaced, each asserting something the code had stopped doing, each true when written: sandbox-storage-billing claiming measurement was "a follow-up, not done here"; AiChatView claiming it registered 'ai-streaming'; and useEditingStore listing per-surface registrants. The last one cost the most — I read it, concluded the new chat had dropped a required registration, and reported a non-existent gap on this PR before tracing the actual call path (registration is central, in DerivedStreamingRegistrations). Corrected in the thread. A comment describing the code is the one thing no check on the code can verify.

Verification

• typecheck, lint, knip ratchet (baseline shrunk 5 → 4), realtime coverage gate (98% branches, restored with genuinely missing tests rather than a threshold change)
• Full local sweep at 14cef80a8: typecheck 16/16 · lint 14/14 · knip ratchet 4/4 · @pagespace/lib 8,623 passing · apps/web 14,939 passing across 1,020 files · security suite 1,115 + 767 passing · realtime 934 passing at 98.04% branch coverage. The 16 apps/web failures are the known env-only trio (Postgres-dependent auth suites, activity-tools, TZ-dependent grouping), each verified identical on this branch without these changes
• Real-Postgres validation (throwaway instance, torn down after): all 235 migrations applied from empty including the phase-8 teardown, end state verified column by column; the store integration suite green; the reclaim trigger proved on all four cascade paths
• Mutation testing — deliberate defects injected across the access decision, quota exemption and ceiling, sprite-key derivation (namespace, tenant fold, NUL delimiter, weak-secret guard), dimension clamps, the orphan reconciler that destroys VMs, storage measurement, billing clock and settle rollback, shell-spawn guards, the squat guard, denial ordering, and every session/shells route guard. Every one caught except four:
  • two were both halves of the recoverable-error fix (an over-cap paste bricking the terminal pane) — a real gap, now covered, each new test verified to kill its mutation
  • two in resumeBillingClock/settle were verified redundant rather than untested: both readers of connectedAt guard on payerId independently, and calculateMachineCostDollars already floors at 0. Deliberately left untested — asserting an internal field with no user-visible consequence tests implementation, not behaviour
• Spec conformance — the diff checked against three independent sources of truth: the implementation plan (found the vocabulary violation fixed in 14cef80a8), this repo's CLAUDE.md rules (async params, no any, isOnPrem() gating, no migration SQL edits — all clean), and the new code's own documented invariants (Date never on the wire, names never addresses, denial ordering). Worth separating from the test results: these find code that is consistently wrong, which no amount of self-consistency checking can reach
• New: 12 real-Postgres store cases (CAS predicates, PK-as-FK conflict target, live-row measurement guard, outbox upsert, delete cascade), now wired into the security workflow; 10 destructive-teardown cases; a read-only drift guard on the session/shell tool family
• Two CI regressions of my own were caught and fixed during this round: a result-shape field breaking 10 assertions in the security suite, and a new export missing from a vi.mock factory. Both came from trusting targeted local runs; the full suite is now the pre-push check.
• Known env-only failures, each verified identical on this branch without these changes: Postgres-dependent auth suites (no test DB in worktrees), activity-tools, grouping
• CodeQL's 3 "new" high alerts in api/ai/chat/route.ts are alerts 228/229/230, opened 2026-07-03 against refs/heads/master — weeks before this branch — and re-anchored by this PR's large diff to that file; this PR only removes code there. Conversely this PR deletes two files carrying open alerts: machine-workspace/workspace-reducer.ts (fix(security): remediate all 73 CodeQL vulnerability alerts #269, remote-property-injection) and services/machines/project-session.ts (fix(security): default CSRF origin validation to block mode #266, insufficient-password-hash)
• Manual E2E not yet run — the one criterion I cannot satisfy, since it needs a dev DB with 0234 applied and a working Sprites credential. Written up as a 15-step copy-pasteable checklist in a PR comment (prerequisites, pass condition per step, and what each step proves) so it costs ~10 minutes. It matters more than it did when this PR opened: round 4 found that read_shell/send_shell had never once worked, and no static tracing would reveal whether a Sprite actually provisions under real credentials. Step 8 (agent reads a live shell) is the single most important one

Docs: workspace tool count recounted from the registry (77 to 76).

Generated with Claude Code

[coderabbitai]

Important

Review skipped

Too many files!

This PR contains 286 files, which is 186 over the limit of 100.

To get a review, narrow the scope:
• coderabbit review --committed # exclude uncommitted changes
• coderabbit review --dir # limit to a subdirectory
• coderabbit review --base # compare against a closer base

Upgrade to a paid plan to raise the limit.

This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 62413d23-956b-43ce-946a-2d9dc7b8c2e2

📥 Commits

Reviewing files that changed from the base of the PR and between 3fef8fd and 303cea2.

📒 Files selected for processing (521)

• .github/workflows/security.yml
• README.md
• apps/marketing/src/app/docs/features/cli/page.tsx
• apps/marketing/src/app/docs/getting-started/page.tsx
• apps/realtime/src/__tests__/index.test.ts
• apps/realtime/src/index.ts
• apps/realtime/src/terminal/__tests__/agent-terminal-access.test.ts
• apps/realtime/src/terminal/__tests__/agent-terminal-session-key.test.ts
• apps/realtime/src/terminal/__tests__/cold-connect-sprite-reads.test.ts
• apps/realtime/src/terminal/__tests__/shell-access.test.ts
• apps/realtime/src/terminal/__tests__/shell-activity.test.ts
• apps/realtime/src/terminal/__tests__/shell-handler.test.ts
• apps/realtime/src/terminal/__tests__/shell-io.test.ts
• apps/realtime/src/terminal/__tests__/shell-session-key.test.ts
• apps/realtime/src/terminal/__tests__/shell-task-hold.test.ts
• apps/realtime/src/terminal/__tests__/validation.test.ts
• apps/realtime/src/terminal/agent-terminal-access.ts
• apps/realtime/src/terminal/agent-terminal-session-key.ts
• apps/realtime/src/terminal/session-io.ts
• apps/realtime/src/terminal/shell-access.ts
• apps/realtime/src/terminal/shell-activity.ts
• apps/realtime/src/terminal/shell-handler.ts
• apps/realtime/src/terminal/shell-io.ts
• apps/realtime/src/terminal/shell-session-key.ts
• apps/realtime/src/terminal/sprites-shell.ts
• apps/realtime/src/terminal/terminal-activity.ts
• apps/realtime/src/terminal/terminal-session-map.ts
• apps/realtime/src/terminal/validation.ts
• apps/web/src/app/api/__tests__/security-audit-coverage.test.ts
• apps/web/src/app/api/admin/global-prompt/route.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/__tests__/route.test.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/diff/__tests__/route.test.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/diff/route.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/files/__tests__/route.test.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/files/route.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/git-blob/__tests__/route.test.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/git-blob/route.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/route.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/shells/[shellId]/__tests__/route.test.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/shells/[shellId]/route.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/shells/__tests__/route.test.ts
• apps/web/src/app/api/agent-sessions/[sessionId]/shells/route.ts
• apps/web/src/app/api/agent-sessions/__tests__/route.test.ts
• apps/web/src/app/api/agent-sessions/route.ts
• apps/web/src/app/api/ai/chat/__tests__/credit-gate.test.ts
• apps/web/src/app/api/ai/chat/__tests__/machine-binding-route.test.ts
• apps/web/src/app/api/ai/chat/__tests__/mcp-scope-tool-filtering.test.ts
• apps/web/src/app/api/ai/chat/__tests__/sandbox-github-suppression.test.ts
• apps/web/src/app/api/ai/chat/__tests__/stream-socket-events.test.ts
• apps/web/src/app/api/ai/chat/messages/[messageId]/__tests__/route.test.ts
• apps/web/src/app/api/ai/chat/route.ts
• apps/web/src/app/api/ai/global/[id]/messages/route.ts
• apps/web/src/app/api/ai/page-agents/[agentId]/config/__tests__/route.test.ts
• apps/web/src/app/api/ai/page-agents/[agentId]/conversations/[conversationId]/messages/__tests__/route.test.ts
• apps/web/src/app/api/ai/page-agents/[agentId]/conversations/[conversationId]/messages/route.ts
• apps/web/src/app/api/ai/page-agents/multi-drive/route.ts
• apps/web/src/app/api/cron/purge-trashed-pages/__tests__/route.test.ts
• apps/web/src/app/api/cron/purge-trashed-pages/route.ts
• apps/web/src/app/api/cron/reconcile-machine-storage/__tests__/route.test.ts
• apps/web/src/app/api/cron/reconcile-machine-storage/route.ts
• apps/web/src/app/api/cron/reconcile-orphaned-sprites/__tests__/route.test.ts
• apps/web/src/app/api/cron/reconcile-orphaned-sprites/route.ts
• apps/web/src/app/api/drives/[driveId]/agents/__tests__/route.test.ts
• apps/web/src/app/api/drives/[driveId]/agents/route.ts
• apps/web/src/app/api/drives/[driveId]/search/glob/__tests__/route.test.ts
• apps/web/src/app/api/drives/[driveId]/search/glob/route.ts
• apps/web/src/app/api/integrations/github/repos/__tests__/route.test.ts
• apps/web/src/app/api/integrations/github/repos/route.ts
• apps/web/src/app/api/machines/__tests__/route.test.ts
• apps/web/src/app/api/machines/agent-terminals/__tests__/route.test.ts
• apps/web/src/app/api/machines/agent-terminals/route.ts
• apps/web/src/app/api/machines/branches/__tests__/route.test.ts
• apps/web/src/app/api/machines/branches/route.ts
• apps/web/src/app/api/machines/diff/__tests__/route.test.ts
• apps/web/src/app/api/machines/diff/route.ts
• apps/web/src/app/api/machines/files/__tests__/route.test.ts
• apps/web/src/app/api/machines/files/route.ts
• apps/web/src/app/api/machines/git-blob/__tests__/route.test.ts
• apps/web/src/app/api/machines/git-blob/route.ts
• apps/web/src/app/api/machines/projects/__tests__/route.test.ts
• apps/web/src/app/api/machines/projects/promote/__tests__/route.test.ts
• apps/web/src/app/api/machines/projects/promote/route.ts
• apps/web/src/app/api/machines/projects/route.ts
• apps/web/src/app/api/machines/route.ts
• apps/web/src/app/api/machines/settings/__tests__/route.test.ts
• apps/web/src/app/api/machines/settings/route.ts
• apps/web/src/app/api/machines/workspaces/__tests__/route.test.ts
• apps/web/src/app/api/machines/workspaces/route.ts
• apps/web/src/app/api/machines/workspaces/verbs/__tests__/route.test.ts
• apps/web/src/app/api/machines/workspaces/verbs/route.ts
• apps/web/src/app/api/mentions/search/route.ts
• apps/web/src/app/api/pages/[pageId]/agent-config/__tests__/route.test.ts
• apps/web/src/app/api/pages/[pageId]/agent-config/route.ts
• apps/web/src/app/api/pages/__tests__/route.test.ts
• apps/web/src/app/api/pages/route.ts
• apps/web/src/app/api/tasks/__tests__/route.test.ts
• apps/web/src/app/api/trash/[pageId]/__tests__/route.test.ts
• apps/web/src/app/api/trash/[pageId]/route.ts
• apps/web/src/app/api/trash/drives/[driveId]/__tests__/route.test.ts
• apps/web/src/app/api/trash/drives/[driveId]/route.ts
• apps/web/src/app/api/user/assistant-config/__tests__/route.test.ts
• apps/web/src/app/api/user/assistant-config/route.ts
• apps/web/src/app/dashboard/DashboardLayoutClient.tsx
• apps/web/src/app/dashboard/[driveId]/agents/page.tsx
• apps/web/src/app/dashboard/[driveId]/development/[machineId]/page.tsx
• apps/web/src/app/dashboard/[driveId]/development/__tests__/layout.test.tsx
• apps/web/src/app/dashboard/[driveId]/development/layout.tsx
• apps/web/src/app/dashboard/[driveId]/development/page.tsx
• apps/web/src/app/dashboard/agents/page.tsx
• apps/web/src/app/dashboard/development/[machineId]/page.tsx
• apps/web/src/app/dashboard/development/__tests__/layout.test.tsx
• apps/web/src/app/dashboard/development/layout.tsx
• apps/web/src/app/dashboard/development/page.tsx
• apps/web/src/app/settings/ai/MachineAccessCard.tsx
• apps/web/src/app/settings/ai/__tests__/MachineAccessCard.test.tsx
• apps/web/src/app/settings/ai/page.tsx
• apps/web/src/app/settings/usage/page.tsx
• apps/web/src/components/agents/AgentPageView.tsx
• apps/web/src/components/agents/AgentView.tsx
• apps/web/src/components/agents/AgentsSurface.tsx
• apps/web/src/components/agents/__tests__/AgentPageView.test.tsx
• apps/web/src/components/agents/__tests__/AgentView.test.tsx
• apps/web/src/components/agents/__tests__/AgentsSurface.test.tsx
• apps/web/src/components/agents/__tests__/useAgentSession.test.tsx
• apps/web/src/components/agents/__tests__/useResolvedAgent.test.ts
• apps/web/src/components/agents/__tests__/useResolvedConversation.test.ts
• apps/web/src/components/agents/__tests__/useSessionShells.test.tsx
• apps/web/src/components/agents/chat/SessionChat.tsx
• apps/web/src/components/agents/chat/__tests__/SessionChat.test.tsx
• apps/web/src/components/agents/chat/__tests__/useAgentSessionChat.test.ts
• apps/web/src/components/agents/chat/useAgentSessionChat.ts
• apps/web/src/components/agents/shell/Shell.tsx
• apps/web/src/components/agents/shell/XtermTerminal.tsx
• apps/web/src/components/agents/shell/__tests__/Shell.test.tsx
• apps/web/src/components/agents/shell/__tests__/XtermTerminal.test.tsx
• apps/web/src/components/agents/shell/__tests__/pty-input.test.ts
• apps/web/src/components/agents/shell/pty-input.ts
• apps/web/src/components/agents/useAgentSession.ts
• apps/web/src/components/agents/useResolvedAgent.ts
• apps/web/src/components/agents/useResolvedConversation.ts
• apps/web/src/components/agents/useSessionShells.ts
• apps/web/src/components/ai/page-agents/PageAgentSettingsTab.tsx
• apps/web/src/components/ai/shared/DerivedStreamingRegistrations.tsx
• apps/web/src/components/ai/shared/chat/ask-user/AskUserAnswerContext.tsx
• apps/web/src/components/billing/AgentSessionUsageCard.tsx
• apps/web/src/components/billing/ConcurrencyCard.tsx
• apps/web/src/components/create/QuickCreatePalette.tsx
• apps/web/src/components/layout/left-sidebar/AgentsSidebar.tsx
• apps/web/src/components/layout/left-sidebar/DevelopmentSidebar.tsx
• apps/web/src/components/layout/left-sidebar/MemoizedSidebar.tsx
• apps/web/src/components/layout/left-sidebar/PrimaryNavigation.tsx
• apps/web/src/components/layout/left-sidebar/__tests__/AgentsSidebar.test.tsx
• apps/web/src/components/layout/left-sidebar/__tests__/DevelopmentSidebar.test.tsx
• apps/web/src/components/layout/left-sidebar/__tests__/sidebar-routes.test.ts
• apps/web/src/components/layout/left-sidebar/__tests__/sidebar-states.test.tsx
• apps/web/src/components/layout/left-sidebar/sidebar-routes.ts
• apps/web/src/components/layout/left-sidebar/sidebar-states.tsx
• apps/web/src/components/layout/middle-content/CenterPanel.tsx
• apps/web/src/components/layout/middle-content/MachineKeepAliveHost.tsx
• apps/web/src/components/layout/middle-content/__tests__/machine-keepalive.test.ts
• apps/web/src/components/layout/middle-content/machine-keepalive.ts
• apps/web/src/components/layout/middle-content/page-views/ai-page/AiChatView.tsx
• apps/web/src/components/layout/middle-content/page-views/ai-page/__tests__/AiChatView.realConversations.test.tsx
• apps/web/src/components/layout/middle-content/page-views/ai-page/__tests__/AiChatView.test.tsx
• apps/web/src/components/layout/middle-content/page-views/ai-page/__tests__/riteway.ts
• apps/web/src/components/layout/middle-content/page-views/machine/MachineView.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/MachineView.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/DiffFileCard.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/DiffTab.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/DiffTab.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/FilesFilePane.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/FilesFilePane.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/FilesTab.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/FilesTab.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/SettingsTab.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/SettingsTab.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/TabSidebar.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/TabSidebar.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/TerminalTab.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/TerminalTab.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/__tests__/files-scope.test.ts
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/checkout-states.ts
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/files-scope.ts
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/tab-states.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/tabs/tab-states.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/ConfirmRemoveDialog.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/ConfirmRemoveDialog.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/DestinationPathDialog.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/FileNameDialog.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/MachineFileTree.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/MachineFileTree.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/MachinePaneChat.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/MachineTree.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/MachineTree.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/MachineWorkspace.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/NodeActionPalette.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/NodeActionPalette.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/PaneBar.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/PaneBar.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/RemoveButton.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/TerminalPanes.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/TerminalPanes.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/WorkspaceLeaves.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/WorkspaceLeaves.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/__tests__/MachinePaneChat.test.tsx
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/__tests__/useMachinePaneChat.test.ts
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/deriveProjectFieldsFromRepo.test.ts
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/pane-surface.test.ts
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/pane-surface.ts
• apps/web/src/components/layout/middle-content/page-views/machine/workspace/useMachinePaneChat.ts
• apps/web/src/hooks/__tests__/useAgentTerminals.test.tsx
• apps/web/src/hooks/__tests__/useMachineDiff.test.tsx
• apps/web/src/hooks/__tests__/useMachineWorkspaceSync.test.ts
• apps/web/src/hooks/__tests__/useUserActiveStreams.test.tsx
• apps/web/src/hooks/page-agents/__tests__/usePageAgents.shellRegression.test.ts
• apps/web/src/hooks/page-agents/usePageAgents.ts
• apps/web/src/hooks/useAgentTerminals.ts
• apps/web/src/hooks/useDriveMachines.ts
• apps/web/src/hooks/useGithubRepos.ts
• apps/web/src/hooks/useMachineBranches.ts
• apps/web/src/hooks/useMachineDiff.ts
• apps/web/src/hooks/useMachineProjects.ts
• apps/web/src/hooks/useMachineSettings.ts
• apps/web/src/hooks/useMachineWorkspaceSync.ts
• apps/web/src/hooks/useTabMeta.ts
• apps/web/src/hooks/useUserActiveStreams.ts
• apps/web/src/lib/agent-sessions/__tests__/agent-session-orphan-reconcile-runtime.test.ts
• apps/web/src/lib/agent-sessions/__tests__/quota-response.test.ts
• apps/web/src/lib/agent-sessions/__tests__/session-anchor.test.ts
• apps/web/src/lib/agent-sessions/agent-session-orphan-reconcile-runtime.ts
• apps/web/src/lib/agent-sessions/agent-sessions-runtime.ts
• apps/web/src/lib/agent-sessions/quota-response.ts
• apps/web/src/lib/agent-sessions/session-anchor.ts
• apps/web/src/lib/agent-sessions/session-sandbox-runtime.ts
• apps/web/src/lib/agent-sessions/session-shells-runtime.ts
• apps/web/src/lib/agents/__tests__/agent-selection.test.ts
• apps/web/src/lib/agents/__tests__/build-session-chat-request.test.ts
• apps/web/src/lib/agents/__tests__/running-badges.test.ts
• apps/web/src/lib/agents/__tests__/session-status.test.ts
• apps/web/src/lib/agents/__tests__/session-tabs.test.ts
• apps/web/src/lib/agents/agent-selection.ts
• apps/web/src/lib/agents/build-session-chat-request.ts
• apps/web/src/lib/agents/running-badges.ts
• apps/web/src/lib/agents/session-status.ts
• apps/web/src/lib/agents/session-tabs.ts
• apps/web/src/lib/ai/core/__tests__/agent-dispatch-depth.test.ts
• apps/web/src/lib/ai/core/__tests__/inline-instructions.test.ts
• apps/web/src/lib/ai/core/__tests__/tool-filtering.test.ts
• apps/web/src/lib/ai/core/agent-awareness.ts
• apps/web/src/lib/ai/core/agent-dispatch-depth.ts
• apps/web/src/lib/ai/core/ai-tools.ts
• apps/web/src/lib/ai/core/inline-instructions.ts
• apps/web/src/lib/ai/core/system-prompt.ts
• apps/web/src/lib/ai/core/tool-filtering.ts
• apps/web/src/lib/ai/core/types.ts
• apps/web/src/lib/ai/machine-pane/machine-pane-binding-runtime.ts
• apps/web/src/lib/ai/machines/__tests__/headless-session-run.test.ts
• apps/web/src/lib/ai/machines/__tests__/machine-binding-prompt.test.ts
• apps/web/src/lib/ai/machines/headless-session-run-runtime.ts
• apps/web/src/lib/ai/machines/headless-session-run.ts
• apps/web/src/lib/ai/machines/machine-binding-prompt.ts
• apps/web/src/lib/ai/tools/__tests__/actor-permissions.test.ts
• apps/web/src/lib/ai/tools/__tests__/agent-communication-tools.test.ts
• apps/web/src/lib/ai/tools/__tests__/page-write-tools.test.ts
• apps/web/src/lib/ai/tools/__tests__/sandbox-git-tools.test.ts
• apps/web/src/lib/ai/tools/__tests__/sandbox-tools-runtime.test.ts
• apps/web/src/lib/ai/tools/__tests__/sandbox-tools.test.ts
• apps/web/src/lib/ai/tools/__tests__/search-tools.test.ts
• apps/web/src/lib/ai/tools/__tests__/session-dispatch-origin.test.ts
• apps/web/src/lib/ai/tools/__tests__/session-io-agent.test.ts
• apps/web/src/lib/ai/tools/__tests__/session-io-pty.test.ts
• apps/web/src/lib/ai/tools/__tests__/session-layout.test.ts
• apps/web/src/lib/ai/tools/__tests__/session-tools.test.ts
• apps/web/src/lib/ai/tools/__tests__/shell-io.test.ts
• apps/web/src/lib/ai/tools/actor-permissions.ts
• apps/web/src/lib/ai/tools/agent-communication-tools.ts
• apps/web/src/lib/ai/tools/sandbox-git-tools-runtime.ts
• apps/web/src/lib/ai/tools/sandbox-git-tools.ts
• apps/web/src/lib/ai/tools/sandbox-git/core/__tests__/command-specs.test.ts
• apps/web/src/lib/ai/tools/sandbox-git/core/command-specs/worktree.ts
• apps/web/src/lib/ai/tools/sandbox-git/generate-tools.ts
• apps/web/src/lib/ai/tools/sandbox-git/tools/repo.ts
• apps/web/src/lib/ai/tools/sandbox-git/tools/worktree.ts
• apps/web/src/lib/ai/tools/sandbox-tools-runtime.ts
• apps/web/src/lib/ai/tools/sandbox-tools.ts
• apps/web/src/lib/ai/tools/search-tools.ts
• apps/web/src/lib/ai/tools/session-io-agent-runtime.ts
• apps/web/src/lib/ai/tools/session-io-agent.ts
• apps/web/src/lib/ai/tools/session-io-pty.ts
• apps/web/src/lib/ai/tools/session-layout.ts
• apps/web/src/lib/ai/tools/session-tools-runtime.ts
• apps/web/src/lib/ai/tools/session-tools.ts
• apps/web/src/lib/ai/tools/shell-io.ts
• apps/web/src/lib/channels/__tests__/agent-mention-responder-commands.test.ts
• apps/web/src/lib/channels/__tests__/agent-mention-responder-edge-cases.test.ts
• apps/web/src/lib/channels/__tests__/agent-mention-responder-image-attachments.test.ts
• apps/web/src/lib/channels/__tests__/agent-mention-responder.test.ts
• apps/web/src/lib/channels/agent-mention-responder.ts
• apps/web/src/lib/development/DetailState.tsx
• apps/web/src/lib/development/__tests__/development-route.test.ts
• apps/web/src/lib/development/__tests__/displayed-machine.test.ts
• apps/web/src/lib/development/__tests__/pending-workspace.test.ts
• apps/web/src/lib/development/development-route.ts
• apps/web/src/lib/development/displayed-machine.ts
• apps/web/src/lib/development/pending-workspace.ts
• apps/web/src/lib/development/use-drain-pending-workspace.ts
• apps/web/src/lib/development/use-sticky-machine-ids.ts
• apps/web/src/lib/machines/__tests__/machine-files-runtime.test.ts
• apps/web/src/lib/machines/__tests__/machine-orphan-reconcile-runtime.integration.test.ts
• apps/web/src/lib/machines/__tests__/machine-orphan-reconcile-runtime.killmap.test.ts
• apps/web/src/lib/machines/__tests__/machine-ref-sweep-runtime.test.ts
• apps/web/src/lib/machines/__tests__/machine-settings-runtime.test.ts
• apps/web/src/lib/machines/__tests__/workspace-verbs-runtime.test.ts
• apps/web/src/lib/machines/agent-terminals-runtime.ts
• apps/web/src/lib/machines/machine-access-runtime.ts
• apps/web/src/lib/machines/machine-branches-runtime.ts
• apps/web/src/lib/machines/machine-diff-runtime.ts
• apps/web/src/lib/machines/machine-files-runtime.ts
• apps/web/src/lib/machines/machine-git-blob-runtime.ts
• apps/web/src/lib/machines/machine-list-runtime.ts
• apps/web/src/lib/machines/machine-orphan-reconcile-runtime.ts
• apps/web/src/lib/machines/machine-projects-runtime.ts
• apps/web/src/lib/machines/machine-ref-sweep-runtime.ts
• apps/web/src/lib/machines/machine-settings-runtime.ts
• apps/web/src/lib/machines/machine-workspaces-runtime.ts
• apps/web/src/lib/machines/workspace-verbs-runtime.ts
• apps/web/src/lib/onboarding/faq/seed-template.ts
• apps/web/src/lib/repositories/__tests__/conversation-repository.test.ts
• apps/web/src/lib/repositories/__tests__/global-machine-config-repository.test.ts
• apps/web/src/lib/repositories/__tests__/page-agent-repository.test.ts
• apps/web/src/lib/repositories/conversation-repository.ts
• apps/web/src/lib/repositories/global-machine-config-repository.ts
• apps/web/src/lib/repositories/page-agent-repository.ts
• apps/web/src/lib/sandbox/sprites-client.ts
• apps/web/src/lib/subscription/__tests__/usage-breakdown.test.ts
• apps/web/src/lib/subscription/usage-breakdown-query.ts
• apps/web/src/lib/subscription/usage-breakdown.ts
• apps/web/src/lib/websocket/__tests__/socket-utils.test.ts
• apps/web/src/lib/websocket/socket-utils.ts
• apps/web/src/services/api/__tests__/page-type-drift-guard.test.ts
• apps/web/src/stores/agents/__tests__/useAgentSurfaceStore.test.ts
• apps/web/src/stores/agents/useAgentSurfaceStore.ts
• apps/web/src/stores/development/usePendingWorkspaceStore.ts
• apps/web/src/stores/machine-workspace/__tests__/useMachineTabStore.test.ts
• apps/web/src/stores/machine-workspace/__tests__/useMachineWorkspaceStore.test.ts
• apps/web/src/stores/machine-workspace/__tests__/workspace-reducer.test.ts
• apps/web/src/stores/machine-workspace/__tests__/workspace-verbs.test.ts
• apps/web/src/stores/machine-workspace/useMachineTabStore.ts
• apps/web/src/stores/machine-workspace/useMachineWorkspaceStore.ts
• apps/web/src/stores/machine-workspace/workspace-reducer.ts
• apps/web/src/stores/machine-workspace/workspace-verbs.ts
• apps/web/src/stores/useEditingStore.ts
• apps/web/src/types/mentions.ts
• knip-baseline.json
• knip.json
• packages/db/drizzle/0232_third_synch.sql
• packages/db/drizzle/0233_agent_session_sprite_reclaim_trigger.sql
• packages/db/drizzle/0234_phase8_teardown_machines_world.sql
• packages/db/drizzle/meta/0232_snapshot.json
• packages/db/drizzle/meta/0233_snapshot.json
• packages/db/drizzle/meta/0234_snapshot.json
• packages/db/drizzle/meta/_journal.json
• packages/db/package.json
• packages/db/src/schema.ts
• packages/db/src/schema/__tests__/agent-sessions.test.ts
• packages/db/src/schema/__tests__/machine-workspace-bootstraps.test.ts
• packages/db/src/schema/__tests__/machine-workspaces.test.ts
• packages/db/src/schema/agent-sessions.ts
• packages/db/src/schema/auth.ts
• packages/db/src/schema/core.ts
• packages/db/src/schema/integrations.ts
• packages/db/src/schema/machine-agent-terminals.ts
• packages/db/src/schema/machine-branches.ts
• packages/db/src/schema/machine-panes.ts
• packages/db/src/schema/machine-projects.ts
• packages/db/src/schema/machine-sessions.ts
• packages/db/src/schema/machine-workspace-bootstraps.ts
• packages/db/src/schema/machine-workspaces.ts
• packages/lib/package.json
• packages/lib/src/__tests__/page-type-validators.test.ts
• packages/lib/src/agent-sessions/__tests__/contract.test.ts
• packages/lib/src/agent-sessions/__tests__/decide-session-access.test.ts
• packages/lib/src/agent-sessions/__tests__/plan-session-lifecycle.test.ts
• packages/lib/src/agent-sessions/__tests__/plan-spawn-session.test.ts
• packages/lib/src/agent-sessions/__tests__/session-sprite-key.test.ts
• packages/lib/src/agent-sessions/contract.ts
• packages/lib/src/agent-sessions/decide-session-access.ts
• packages/lib/src/agent-sessions/plan-session-lifecycle.ts
• packages/lib/src/agent-sessions/plan-spawn-session.ts
• packages/lib/src/agent-sessions/session-sprite-key.ts
• packages/lib/src/billing/__tests__/machine-payer.test.ts
• packages/lib/src/billing/__tests__/sandbox-payer.test.ts
• packages/lib/src/billing/machine-payer.ts
• packages/lib/src/billing/sandbox-payer.ts
• packages/lib/src/content/__tests__/page-types-machine.test.ts
• packages/lib/src/content/__tests__/page-types-publishable.test.ts
• packages/lib/src/content/page-type-validators.ts
• packages/lib/src/content/page-types.config.ts
• packages/lib/src/integrations/repositories/config-repository.ts
• packages/lib/src/services/__tests__/page-webhook-core.test.ts
• packages/lib/src/services/agent-sessions/__tests__/agent-session-access.test.ts
• packages/lib/src/services/agent-sessions/__tests__/agent-session-sprite.test.ts
• packages/lib/src/services/agent-sessions/__tests__/agent-sessions-store.integration.test.ts
• packages/lib/src/services/agent-sessions/__tests__/agent-sessions-store.test.ts
• packages/lib/src/services/agent-sessions/__tests__/agent-sessions.test.ts
• packages/lib/src/services/agent-sessions/__tests__/fakes.ts
• packages/lib/src/services/agent-sessions/__tests__/session-scrollback.test.ts
• packages/lib/src/services/agent-sessions/__tests__/session-shells.test.ts
• packages/lib/src/services/agent-sessions/__tests__/session-status.test.ts
• packages/lib/src/services/agent-sessions/__tests__/shell-types.test.ts
• packages/lib/src/services/agent-sessions/agent-session-access.ts
• packages/lib/src/services/agent-sessions/agent-session-sprite.ts
• packages/lib/src/services/agent-sessions/agent-sessions-store.ts
• packages/lib/src/services/agent-sessions/agent-sessions.ts
• packages/lib/src/services/agent-sessions/session-scrollback.ts
• packages/lib/src/services/agent-sessions/session-shells-store.ts
• packages/lib/src/services/agent-sessions/session-shells.ts
• packages/lib/src/services/agent-sessions/session-status.ts
• packages/lib/src/services/agent-sessions/shell-types.ts
• packages/lib/src/services/machines/__tests__/agent-terminal-sprite-session.test.ts
• packages/lib/src/services/machines/__tests__/agent-terminal-types.test.ts
• packages/lib/src/services/machines/__tests__/agent-terminals-store.integration.test.ts
• packages/lib/src/services/machines/__tests__/agent-terminals-store.test.ts
• packages/lib/src/services/machines/__tests__/agent-terminals.test.ts
• packages/lib/src/services/machines/__tests__/branch-session.test.ts
• packages/lib/src/services/machines/__tests__/fake-machine-panes-store.ts
• packages/lib/src/services/machines/__tests__/machine-access.test.ts
• packages/lib/src/services/machines/__tests__/machine-branches-store.test.ts
• packages/lib/src/services/machines/__tests__/machine-branches.test.ts
• packages/lib/src/services/machines/__tests__/machine-list.test.ts
• packages/lib/src/services/machines/__tests__/machine-orphan-reconcile.test.ts
• packages/lib/src/services/machines/__tests__/machine-pane-binding.test.ts
• packages/lib/src/services/machines/__tests__/machine-panes-store.integration.test.ts
• packages/lib/src/services/machines/__tests__/machine-panes-store.test.ts
• packages/lib/src/services/machines/__tests__/machine-project-promotion.test.ts
• packages/lib/src/services/machines/__tests__/machine-projects-store.test.ts
• packages/lib/src/services/machines/__tests__/machine-projects.test.ts
• packages/lib/src/services/machines/__tests__/machine-ref-sweep.test.ts
• packages/lib/src/services/machines/__tests__/machine-settings.test.ts
• packages/lib/src/services/machines/__tests__/machine-workspaces.test.ts
• packages/lib/src/services/machines/__tests__/name-slug.test.ts
• packages/lib/src/services/machines/__tests__/project-paths.test.ts
• packages/lib/src/services/machines/agent-terminal-sprite-session.ts
• packages/lib/src/services/machines/agent-terminal-sprites.ts
• packages/lib/src/services/machines/agent-terminal-types.ts
• packages/lib/src/services/machines/agent-terminals-store.ts
• packages/lib/src/services/machines/agent-terminals.ts
• packages/lib/src/services/machines/branch-name.ts
• packages/lib/src/services/machines/branch-session.ts
• packages/lib/src/services/machines/machine-access.ts
• packages/lib/src/services/machines/machine-branches-store.ts
• packages/lib/src/services/machines/machine-branches.ts
• packages/lib/src/services/machines/machine-list.ts
• packages/lib/src/services/machines/machine-orphan-reconcile.ts
• packages/lib/src/services/machines/machine-pane-binding.ts
• packages/lib/src/services/machines/machine-panes-store.ts
• packages/lib/src/services/machines/machine-project-promotion.ts
• packages/lib/src/services/machines/machine-projects-store.ts
• packages/lib/src/services/machines/machine-projects.ts
• packages/lib/src/services/machines/machine-ref-sweep.ts
• packages/lib/src/services/machines/machine-settings.ts
• packages/lib/src/services/machines/machine-workspaces-store.ts
• packages/lib/src/services/machines/machine-workspaces.ts
• packages/lib/src/services/machines/name-slug.ts
• packages/lib/src/services/machines/project-name.ts
• packages/lib/src/services/machines/project-paths.ts
• packages/lib/src/services/machines/project-session.ts
• packages/lib/src/services/sandbox/__tests__/branch-session.test.ts
• packages/lib/src/services/sandbox/__tests__/git-tool-runners.test.ts
• packages/lib/src/services/sandbox/__tests__/machine-diff.test.ts
• packages/lib/src/services/sandbox/__tests__/machine-fs.test.ts
• packages/lib/src/services/sandbox/__tests__/machine-session-manager.test.ts
• packages/lib/src/services/sandbox/__tests__/machine-session.test.ts
• packages/lib/src/services/sandbox/__tests__/machine-storage-attribution.test.ts
• packages/lib/src/services/sandbox/__tests__/machine-storage-billing.test.ts
• packages/lib/src/services/sandbox/__tests__/machine-storage-measure.test.ts
• packages/lib/src/services/sandbox/__tests__/machine-storage-reconcile.test.ts
• packages/lib/src/services/sandbox/__tests__/persistent-machine-fs.test.ts
• packages/lib/src/services/sandbox/__tests__/project-session.test.ts
• packages/lib/src/services/sandbox/__tests__/quota.test.ts
• packages/lib/src/services/sandbox/__tests__/sandbox-billing.test.ts
• packages/lib/src/services/sandbox/__tests__/sandbox-storage-attribution.test.ts
• packages/lib/src/services/sandbox/__tests__/sandbox-storage-billing.test.ts
• packages/lib/src/services/sandbox/__tests__/sandbox-storage-measure.test.ts
• packages/lib/src/services/sandbox/__tests__/sandbox-storage-reconcile.test.ts
• packages/lib/src/services/sandbox/__tests__/sprite-orphan-reconcile.test.ts
• packages/lib/src/services/sandbox/__tests__/tool-runners.test.ts
• packages/lib/src/services/sandbox/branch-session.ts
• packages/lib/src/services/sandbox/git-tool-runners.ts
• packages/lib/src/services/sandbox/machine-diff.ts
• packages/lib/src/services/sandbox/machine-fs.ts
• packages/lib/src/services/sandbox/machine-git-blob.ts
• packages/lib/src/services/sandbox/machine-session-manager.ts
• packages/lib/src/services/sandbox/machine-session.ts
• packages/lib/src/services/sandbox/machine-storage-attribution.ts
• packages/lib/src/services/sandbox/machine-storage-billing.ts
• packages/lib/src/services/sandbox/machine-storage-measure.ts
• packages/lib/src/services/sandbox/machine-storage-reconcile.ts
• packages/lib/src/services/sandbox/project-session.ts
• packages/lib/src/services/sandbox/quota.ts
• packages/lib/src/services/sandbox/sandbox-billing.ts
• packages/lib/src/services/sandbox/sandbox-client/__tests__/sandbox-host-adapter.test.ts
• packages/lib/src/services/sandbox/sandbox-client/__tests__/sprite-sandbox-host.test.ts
• packages/lib/src/services/sandbox/sandbox-client/sandbox-host-adapter.ts
• packages/lib/src/services/sandbox/sandbox-client/sprite-sandbox-host.ts
• packages/lib/src/services/sandbox/sandbox-client/sprites.ts
• packages/lib/src/services/sandbox/sandbox-host.ts
• packages/lib/src/services/sandbox/sandbox-storage-attribution.ts
• packages/lib/src/services/sandbox/sandbox-storage-billing.ts
• packages/lib/src/services/sandbox/sandbox-storage-measure.ts
• packages/lib/src/services/sandbox/sandbox-storage-reconcile.ts
• packages/lib/src/services/sandbox/sprite-orphan-reconcile.ts
• packages/lib/src/services/sandbox/tool-runners.ts
• packages/lib/src/utils/__tests__/enums.test.ts
• packages/lib/src/utils/enums.ts
• packages/lib/vitest.config.ts
• packages/sdk/src/operations/__tests__/glob-page-types-drift-guard.test.ts
• packages/sdk/src/operations/__tests__/pages-write.test.ts
• packages/sdk/src/operations/__tests__/search.test.ts
• packages/sdk/src/operations/pages.ts
• packages/sdk/src/operations/search.ts

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 16c6ea6951

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Resolve internal dispatches from the configured app origin

When the app is reached directly over HTTP, as in the documented local deployment, Host is present but X-Forwarded-Proto normally is not, so this constructs https://localhost:... and every spawn_session/send_session dispatch fails before reaching the chat pipeline. It also lets a forged forwarded host choose where the subsequently forwarded cookie and CSRF token are sent. Prefer the validated WEB_APP_URL/NEXT_PUBLIC_APP_URL origin rather than request routing headers.

AGENTS.md reference: AGENTS.md:L13-L13

Useful? React with 👍 / 👎.

[2witstudios]

Fixed in 1efebf550. You're right on both counts, and the correctness half would have broken the documented local deployment outright.

resolveSelfBaseUrl no longer reads routing headers at all — it now resolves WEB_APP_URL || NEXT_PUBLIC_APP_URL (the same precedence as every other self-URL consumer, e.g. services/email-service.ts), normalizes a trailing slash, and returns null on a relative/malformed value so the dispatch reports a config error instead of building a same-process path. The incoming: Headers parameter is gone, so a forged x-forwarded-host has nothing to influence — the forwarded cookie/CSRF can only ever go to the boot-validated origin.

Regression tests: apps/web/src/lib/ai/tools/__tests__/session-dispatch-origin.test.ts (7 cases) — including http://localhost:3000 keeping its scheme, which is the case that previously became https:// and failed.

[chatgpt-codex-connector]

Enforce the live-session quota before provisioning

Every first-touch path reaches this shared provisioner without calling the newly added checkAgentSessionConcurrency; repo-wide, that helper and AgentSessionStore.countLive have no production caller. Consequently, an owner can POST or open shells in arbitrarily many conversations and provision persistent Sprites beyond their tier ceiling, even though the quota module explicitly defines that ceiling for live agent sessions.

Useful? React with 👍 / 👎.

[2witstudios]

Fixed in 1efebf550. Confirmed — the helper and countLive had zero production callers, so the ceiling was decorative.

checkAgentSessionConcurrency is now called from provisionSessionSandbox in agent-sessions-runtime.ts. That's deliberately the enforcement point rather than any individual route: it is the one path every first touch funnels through (chat tool call, POST to the session route, opening a shell), so gating a single caller would have left the others free to exceed the tier.

One refinement on top of the literal fix: a row that already carries a sandboxId is a RESUME and is already counted by countLive, so gating it would refuse an owner at their ceiling access to a Sprite they're already paying for. That exemption lives inside the quota module (alreadyProvisioned), not at the call site, so the ceiling has exactly one place it can be wrong.

Tests: quota.test.ts gains a resume-exemption block — a provisioned session at the ceiling is allowed without even taking the count, and a cold session at the ceiling is still refused.

[2witstudios]

Follow-up in 69b9ccc95 — my first pass didn't fully close this, and you'd phrased the finding more precisely than I first read it.

I had put the check in provisionSessionSandbox, the web app's binding. That covers the HTTP routes and both tool paths, but the realtime shell bridge calls ensureAgentSessionSandbox in packages/lib directly — so opening a shell over the socket still minted a Sprite with no ceiling applied. Your wording was "every first-touch path reaches this shared provisioner", and the shared provisioner is the packages/lib function, not my wrapper.

The gate now lives in ensureAgentSessionSandbox as a required dep, next to checkFullEgressEnablement and for the same stated reason: a required dep on the one function every path funnels through is one a future caller cannot forget. It fires only in the create arm, so a refusal happens before any VM is minted or billed. AgentSessionSpriteRow gained ownerId because the ceiling counts the SESSION OWNER's allocation, not the acting user's — a drive member working inside someone else's agent consumes the owner's limit, not their own.

New tests assert a refusal mints nothing (host.calls.provision empty, sandboxId still null) and that a re-provision reports alreadyProvisioned: true, so an owner at their ceiling can still recover a session whose Sprite vanished.

[chatgpt-codex-connector]

Persist storage measurements before advancing billing watermarks

New session rows initialize storageMeasuredBytes and storageMeasuredAt to null, and the production provisioner never supplies the optional measureSessionStorage callback; repo-wide there is no remaining writer for these fields. The reconcile therefore prices every agent-session filesystem at zero and advances its watermark, permanently discarding each unmeasured billing interval even when the Sprite stores substantial data.

Useful? React with 👍 / 👎.

[2witstudios]

Fixed in 1efebf550. Confirmed, and the consequence was as bad as you describe: with no writer, measuredBytes was always null → pickBillableGB returned 0 → costDollars <= 0 → the watermark advanced anyway, so every agent-session filesystem billed $0 forever and each interval was discarded permanently.

Added packages/lib/src/services/sandbox/sandbox-storage-measure.ts — the agent-session successor to the machine-storage-measure.ts the Phase 8 teardown removed along with its tables — and wired it into the production provisioner as the measureSessionStorage dep. It keeps the original properties: measured only while the Sprite is already awake right after provisioning (never wakes a hibernating VM), throttled per session (default 1h, env-tunable), du -sxB1 of the workspace subtree rather than df of the mount, and a parseable total is trusted even on a non-zero exit as a conservative lower bound.

The new AgentSessionStore.recordStorageMeasurement is guarded on spriteTornDownAt IS NULL, so a measurement landing after teardown can't bill a new generation against a dead disk.

Tests: sandbox-storage-measure.test.ts (13 cases) covering parse, throttle, exec-throw, non-zero-exit-with-total, and unparseable-output.

[chatgpt-codex-connector]

Scope shell connection errors to the failing pane

When one multiplexed shell's onConnect rejects, such as on an unexpected billing or database failure, this catch emits an error without the payload's connectionId. XtermTerminal.isMine deliberately accepts untagged events, so every mounted shell on the shared socket handles the error, marks itself dead, and suppresses future reconnects; include the parsed connection ID so only the failing pane is terminated.

Useful? React with 👍 / 👎.

[2witstudios]

Fixed in 1efebf550. The connectionId is now parsed once before dispatch and echoed on the error emit, so the kill is scoped to the pane that actually failed instead of every shell multiplexed on the socket.

Tests in apps/realtime/src/__tests__/index.test.ts: a rejecting onConnect emits shell:error tagged with that pane's connectionId; a payload without one still emits untagged rather than inventing an id; and a non-Error rejection coerces to { message: 'Internal error', connectionId } rather than leaking the raw value.

These also covered the shell:connect branches that were dragging realtime under its 98% coverage gate, which is what was failing CI on this PR.

[2witstudios]

🔬 Code Review — full branch (pu/dev-to-agents vs master, 8 phases, 207 files)

Method: split into 6 layer-based parallel reviews (data/domain, session services, billing/metering, realtime PTY bridge, web API/AI tools, web UI), each applying the project's full review checklist (JS/TS best practices, TDD coverage assessment, Next.js/stack patterns, an explicit OWASP Top 10 pass). Every finding below was traced to a specific file/line against full file content, not just diffs.

Overall verdict: disciplined, well-tested work for a genuinely hard problem (stateful sandbox provisioning + billing + a live PTY bridge). The core authorization model (one pure decider, shared by web and realtime) is sound with no bypass found. But there's one real security bug and a cluster of "billing/ops plumbing built but not wired up" gaps that make this not yet safe to ship as "phase 7 meters agent-session billing."

---

🔴 High — should block merge

#	Area	File:Line	Issue
1	Web/AI tools	apps/web/src/lib/ai/tools/session-tools-runtime.ts:66-74,177	SSRF + credential leak. Self-dispatch fetch URL is built from client-controllable x-forwarded-host/host, then cookie/x-csrf-token are forwarded to that attacker-influenced URL. The codebase already treats this exact header as untrustworthy elsewhere (oauth/authorize/route.ts explicitly rejects it and uses WEB_APP_URL instead). Fix: base the self-dispatch URL on configured WEB_APP_URL/NEXT_PUBLIC_APP_URL.
2	Billing	machine-storage-measure.ts / machine-storage-billing.ts	Agent-session sandbox storage is not actually measured anywhere. agent-session is explicitly excluded from the opportunistic-measurement path; every agent-session Sprite reconciled bills at the "never measured" $0 floor indefinitely. Plumbing is in place, the meter itself isn't wired. If "phase 7 meters agent_sessions" is meant to mean real dollars are now charged, it doesn't yet.
3	Billing/ops	reconcile-orphaned-sprites/__tests__/route.test.ts	Test suite for the cron route fails to collect (mock missing MAX_CANDIDATES_PER_TABLE export → throws at module init, 0 tests run). Nothing in CI currently verifies the new dual-reconcile response shape or the partial-failure behavior in finding #6 below.
4	Web/AI tools	apps/web/src/lib/ai/core/agent-awareness.ts:5,103	Functional regression. Prompt unconditionally tells the model to delegate via spawn_session, but that tool only exists when CODE_EXECUTION_ENABLED=true (default off). On default config, the assistant confidently calls a tool that isn't in its tool set — delegation silently breaks.
5	Services	apps/web/src/lib/agent-sessions/agent-session-orphan-reconcile-runtime.ts	Zero test coverage for destructive teardown logic (VM-kill/CAS). Its own model twin (machine-orphan-reconcile-runtime.ts) has both a unit and integration test; this doesn't.

🟠 Medium

#	Area	File:Line	Issue
6	Billing	reconcile-orphaned-sprites/route.ts:61-64	Promise.all over the two independent reconcile passes means if one pass's listOrphanCandidates() throws, the other pass's already-completed teardowns go unaudited and the tick reads as a total failure. Self-heals next tick, but real destructive actions go unlogged. Use Promise.allSettled / independent try-catch per pass.
7	Billing	packages/lib/src/services/sandbox/quota.ts:139-149	checkAgentSessionConcurrency is built and tested but never called from any request path — no cap on live sandboxes per owner today (cost/DoS exposure). Commit message itself flags this as not-yet-wired.
8	Services	agent-session-sprite.ts:126-141	When a confirmed-unreferenced Sprite fails both kill and the reclaim-outbox insert, the failure is silently swallowed with no logging — the one path meant to catch "VM now leaked and unbilled forever" produces zero signal.
9	Services	agent-sessions-store.ts, session-shells-store.ts	The DB-backed stores have no test coverage of their actual SQL — the CAS conditions (eqOrIsNull), the driveId join, the upsert in enqueueReclaim — are only validated against an in-memory fake, never against real Postgres. Predecessor module (agent-terminals-store.ts) has an integration test for the analogous logic; this doesn't.
10	Web UI	apps/web/src/components/agents/AgentView.tsx	Reads only isLoading/.status from useResolvedAgent/useAgentSession/useSessionShells, never their error fields — even though those hooks correctly distinguish "no session yet" from "backend failed." A real 5xx currently looks identical to "nothing here," with no retry affordance.
11	Web UI	AgentView.tsx:59,94-100	Compounding #10: once useResolvedAgent gives up retrying on a genuine failure, isLoading goes false but agent stays null — the loading-spinner guard still fires, so the user is stuck on an infinite spinner with no error text and no escape short of a hard refresh.
12	Realtime	shell-io.ts HTTP endpoints (/api/shell-read, /api/shell-input, /api/shell-activity)	These skip re-authorizing the caller-supplied userId on non-start requests, trusting the HMAC signature alone. Not currently exploitable — grep found zero callers anywhere in the repo — but flag for review when the calling code lands.
13	Web/AI tools	sandbox-git/tools/worktree.ts:54-67	git_add splices paths into argv with no -- separator (sibling builders two lines up do add it). A path like -p triggers interactive mode; other dash-prefixed values get reinterpreted as flags.
14	Web/AI tools	worktree.ts:69-78, repo.ts:81-95	git_reset.ref / git_remote_add.name skip the project's own validateFlagSafe guard that structurally identical sibling fields (git_show.ref, git_branch.name) do call.
15	Web/AI tools	inline-instructions.ts:176	The "AGENTS" prompt section (which references spawn_session) is gated on an OR across always-present tools, so it renders even when spawn_session isn't in the tool set — same root cause as #4.
16	Web/AI tools	route duplicating conversation-repository.ts query inline	A sibling messages route wasn't updated when the repository dropped 'MACHINE' from its type filter — now has a stale comment and diverging behavior from its two siblings that do call the repository.
17	Web/AI tools	ai/chat/route.ts:579, ai/global/[id]/messages/route.ts:295	Byte-identical X-Agent-Dispatch-Depth fail-closed parse/clamp logic duplicated in two places — currently correct in both, but security-relevant logic that will silently drift if only one site is edited later.

🟡 Low / Nit (worth a pass, not blocking)

• Accessibility: sandbox status description only reachable via title tooltip; XtermTerminal's container has no role/aria-label as a live terminal region (AgentView.tsx:109, XtermTerminal.tsx:413).
• useAgentSession.ensureSession() is fully built/tested but has zero callers in the shipped UI — dead, won't be caught by knip since it's a hook property, not an export.
• useResolvedConversation.ts:50-55 swallows a failed conversation-creation POST with only console.error, inconsistent with the toast-on-failure convention used elsewhere in this same phase.
• Realtime: onInput's byte-cap uses JS string length (UTF-16 units) while the HTTP path correctly uses Buffer.byteLength(...,'utf8') — up to ~4x drift on multi-byte input, still bounded but inconsistent with the doc comment claiming parity.
• Realtime: periodic 60s re-auth tick does a full user-row read + PII decrypt per attached viewer even though it only needs the pass/fail verdict — avoidable DB/decrypt cost at scale.
• resolveAgentSessionPayerId (machine-payer.ts) is never called in production despite its own doc comment and two other modules' doc comments asserting it's "the only place" this logic lives — either wire it in or fix the stale docs.
• 4 stale ai/chat test files still mock removed exports (filterToolsForMachineBinding, withSessionFamilyTools) — harmless no-ops, but misleading dead residue.
• SESSION_FAMILY_TOOL_NAMES export appears to have no remaining production consumer — confirm intentional.
• A handful of missing-test items on newer runtime-wiring files (session-sandbox-runtime.ts, agent-sessions-runtime.ts's resolveSessionTenantId/ensureConversationRow) that mirror already-tested siblings elsewhere.
• Commit hygiene: the phase 6/7 feature commit subject lines (feat(agents): phase 6 — unified AgentView (one chat, shells, page + console convergence)) run well past the project's 50-char first-line convention, and merge:-prefixed subjects aren't one of the declared conventional types.

✅ What's genuinely strong (don't rework these)

• Access control is centralized correctly. One pure decider (decideAgentSessionAccess/decideAgentSessionEndAccess) is shared by both the web API and the realtime bridge — no second, divergent implementation to drift. Manually traced with no bypass found; IDOR, path traversal (files/git-blob routes), and Next 15 async-params handling all check out clean across every dynamic route.
• The PTY bridge's race handling is unusually careful for this class of system: serialized cold-create per session key, abandoned-connect cleanup, idempotent double-release guards, ANSI/control-char stripping against terminal-escape injection from agent-controlled output, and a periodic re-auth tick that evicts individually-revoked viewers without disturbing co-viewers.
• Concurrency-safety design in the session/sprite CAS layer (ABA-aware identity swaps, teardown-intent-before-kill ordering) is well thought through and the 750-line sprite test file earns its size — it drives real race scenarios, not padding.
• AiChatView deletion (1600 lines) was cleaned up correctly — zero stray references anywhere in the repo, CenterPanel.tsx rewired cleanly, test coverage moved rather than vanished.
• useEditingStore integration is exactly right per the project's SWR/auth-refresh contract (shell excluded from the SWR-pause set, included in the auth-refresh-defer set), and socket/terminal cleanup on unmount is thorough and tested (listener counts, dispose counts, reconnect races).
• DB schema/migrations (phase 0/1) and the pure domain/contract layer are exhaustively tested (191 tests) with no bypasses found in the pure authorization logic.

---

Recommendation: fix the SSRF (#1) and the broken cron test suite (#3) before this goes further — those are the two items that would actually bite in production. Decide explicitly whether #2 (storage not metered) and #7 (concurrency quota not wired) are intentional near-term follow-ups or need to land before calling this "phase 7 complete," since both are billing/cost-control gaps that read as silently incomplete rather than deliberately deferred. Everything else is real but lower-stakes cleanup.

---

🤖 Generated with Claude Code

[2witstudios]

Review response — 3ab0f96

Thanks, this was a genuinely useful review. Working through it in your priority order.

🔴 High — all six addressed

#	Status	Where
1 SSRF + credential leak	Fixed (1efebf5)	Self-dispatch now resolves WEB_APP_URL/NEXT_PUBLIC_APP_URL only; the Headers param is gone, so no forged x-forwarded-host can steer the forwarded cookie/CSRF. You're right that oauth/authorize already set this precedent. 7 tests, incl. http://localhost:3000 keeping its scheme — the case that silently broke every dispatch on the documented local deploy.
2 Storage never metered	Fixed (1efebf5)	Restored the du -sxB1 measurement the Phase 8 teardown deleted with the machine tables, re-keyed to agent_sessions and wired into the provisioner. Your read was exactly right: null measurement → 0 floor → watermark advanced anyway → every interval discarded permanently. Persist is guarded on the row still being live. 13 tests.
3 Cron suite fails to collect	Already passing	reconcile-orphaned-sprites collects and passes 5 tests on current HEAD — fixed by a later phase than the review sampled. I also added 10 tests for the runtime binding (see #5).
4 + 15 spawn_session prompt regression	Fixed	Good catch, and the worst kind of bug — silent, on default config. Delegation copy is now gated on canDelegate, derived from isCodeExecutionEnabled() at both call sites. Without the tool the section still lists agents, it just stops naming a tool that isn't there.
5 Destructive teardown untested	Fixed	10 tests over killSprite (confirmed kill / replaced-name-as-success / genuine failure / unpinned instance), markSessionTornDown (CAS win + loss), listOrphanCandidates (both sources, each single-source failure, cap + backlog).
7 Quota never wired	Fixed (1efebf5 + 69b9ccc)	Two passes: first into the web wrapper, then — after realising the realtime bridge calls ensureAgentSessionSandbox directly and bypassed it — into the shared provisioner as a required dep, next to checkFullEgressEnablement. It fires only in the create arm, so a refusal mints nothing.

🟠 Medium — addressed

• Add sheet unit tests and document the new page type #6 Promise.all → allSettled with per-source logging. One note: in current HEAD that Promise.all is over two read-only SELECTs before any teardown, so no destructive action was going unaudited — but your underlying point stands and is now fixed: a degraded query costs its own candidates, not every reclaim.
• Adopt SheetDoc format for spreadsheets #8 The double-failure path (kill fails and outbox insert fails) now logs loudly with the sandbox id and both reasons. You put it exactly right — the one path built to catch a permanently leaked VM was the one path producing no signal.
• Codex/add sheets page type with calculations #10 + Improve responsive layout across web app #11 Loading and failure are now distinct states in AgentView; the failure shows the server's own message plus a Try again button, backed by a new retry from useResolvedAgent. 3 tests, including that the spinner is gone in the error state.
• Fix JWT awaiting in page resource routes #13 + Ensure drive membership counts for drive access checks #14 git_add now emits -- before pathspecs (and only when there are paths — no bare trailing separator); git_reset.ref and git_remote_add.name gained validateFlagSafe. Added a test asserting -p survives as a path.

On your closing question

You asked whether #2 and #7 were intentional deferrals or silently incomplete. Silently incomplete — the commit message hedging you noticed was the tell. Both are now genuinely wired, so "phase 7 meters agent-session billing" is accurate rather than aspirational.

Not addressed this pass (with reasons)

• Enable cross-page sheet references and suggestion UX #9 store SQL integration tests, Improve mobile navigation and assistant access #12 shell-io re-auth (no callers today, as you note), Enable GLM MCP web search integration #16/Processor auth #17 duplication, and the 🟡 nits. Real, lower-stakes, and each independent of the above — happy to take any of them now if you'd rather they land here than as follow-ups. The two I'd personally rank highest are Enable cross-page sheet references and suggestion UX #9 (real-Postgres CAS coverage) and Processor auth #17 (duplicated depth-clamp is security-relevant drift bait).
• CodeQL's 3 "new" high alerts are pre-existing: alerts 228/229/230 on master are the same three lines in api/ai/chat/route.ts, re-anchored because this PR's diff to that file is large. My diff only removes code there. CodeQL's own summary flags this failure mode.

Gates on 3ab0f96fa: typecheck ✅ lint ✅ realtime coverage ✅ (98% branches) · 1,716 targeted web tests + 917 lib tests green.

[2witstudios]

Third spec source: the code's own doc comments

The 'starting' bug earlier in this loop was a documented behaviour with no implementation. That is a distinct failure mode from the ones tracing and mutation find, so I swept the new modules for absolute claims — "never", "only ever", "cannot", "always" — and checked each mechanically rather than reading past them.

Claim	Check	Result
contract.ts: "Wire timestamps are ISO-8601 strings; Date never crosses the boundary"	any z.date() / : Date in the wire schemas	none — holds
contract.ts: "name is a display label… never an address"	any lookup by name in the shells service	none; every lookup is by id — holds
contract.ts: "Renaming can never break a connection"	anything keying a live connection on a shell name	nothing in shell-handler or shell-io — holds
contract.ts: "two identically-named things are never ambiguous"	session names carry no uniqueness constraint	correct: uniqueIndex exists only on (sessionId, name) for shells, exactly as the comment itself qualifies
contract.ts: "a shell is always a PTY"	the agent-type enum	['shell'] — PTY-only by construction
decide-session-access.ts: "three gates… evaluated in a fixed order so a denial always names the FIRST thing wrong"	the code's actual return order vs the documented order	identity → page → capability, matching the doc line for line

The ordering claim was the one worth pushing on, because it is the kind of thing that stays true by accident until someone reorders a guard. It has a test ("should report the identity denial before the capability denial when both fail"), and I confirmed that test is load-bearing rather than incidental: moving the capability gate ahead of identity fails immediately.

That claim matters beyond tidiness. A user who is both not-shared-in and lacks canRunCode should be told the first thing — "this isn't yours" — not the second. Getting code_execution_denied for a conversation you cannot see leaks that the conversation exists.

Net: no code changes. Three spec sources have now been checked against the diff — the plan, CLAUDE.md, and the code's own documented invariants. Only the first produced a defect (the vocabulary violation, fixed in 14cef80a8).

CI: Security Test Suite green on 14cef80a8; the rest still running.

[2witstudios]

Correction: my claim about 'ai-streaming' registration was wrong

Two passes ago I reported that SessionChat/useAgentSessionChat don't register with useEditingStore, that "nothing anywhere registers 'ai-streaming'", that the store type "has no producer at all", and that this was a pre-existing repo-wide gap worth its own PR.

That is incorrect, and I'd rather flag it than leave a plausible-sounding wrong conclusion in the thread — it would have sent someone off to write a follow-up PR fixing a non-problem.

What actually happens. 'ai-streaming' is registered centrally, not per-component:

GlobalChatProvider
  └─ <DerivedStreamingRegistrations />        ← mounted once, app-wide
       └─ StreamingRegistration(conversationId)  ← one per LIVE conversation
            └─ useStreamingRegistration(`ai-stream-${id}`, …)
                 └─ useEditingStore.startStreaming(id) → startEditing(id, 'ai-streaming')

It derives a registration for any conversation with a pending send or a live stream entry, and React's own unmount supplies the falling edge when the conversation leaves that set.

Why my grep missed it. I searched for startEditing( with 'ai-streaming' on the same line. The call goes through a startStreaming store helper, so the literal and the call site are in different files. A negative grep result is evidence about my search, not about the code — and I reported it as the latter.

The new chat is right not to register, and useAgentSessionChat says so in its own header: "'ai-streaming' editing-store protection is NOT registered here: it comes for free from useSendHandoff's pendingSend bookkeeping plus the app-wide DerivedStreamingRegistrations … a per-surface registration would only risk two owners disagreeing about when to end it."

So: no gap, no follow-up PR needed, and the design is deliberately better than the per-component registration I was about to recommend. The CLAUDE.md rule is satisfied — just at the provider level rather than in each chat surface.

One real (if small) thing did come out of it: useEditingStore's own module doc still lists the producers as "AI streaming (AiChatView, GlobalAssistantView, SidebarChatTab)". AiChatView is deleted, and that list is what pointed me at per-component registration in the first place. Fixing it in the next commit.

[2witstudios]

Three more bug classes swept — all clean. Reporting saturation honestly.

Previous passes each found a real defect by taking a bug class and searching it exhaustively rather than hunting instances. That kept working until this pass, and I think the change is worth stating plainly rather than padding.

Classes swept this round, no defects found:

Class	Question asked	Result
Resource leaks	does every exit path between acquireSlot and return release the slot?	Clean. Bash runner releases on each of its four failure paths and hands release to the caller on success; all four session.release() call sites are inside finally. Git runner's only statement between acquire and try is a literal-initialized let that cannot throw
Fail-open gates	what happens when a gate's dependency THROWS, rather than denies?	Correct — both propagate and mint nothing. But correct by absence of a try/catch, so I pinned it: making the quota gate swallow its throw and default to allowed now fails three tests
Concurrency / idempotency	what do two simultaneous operations do?	Already thorough: concurrent ensures converge on one row, an already-ended session is idempotent, a concurrent ensure that revived a session does not get stamped dead, two provisioners converge on one instance, a losing adoption CAS kills the VM it holds

Flakiness check on my own additions. This loop added a substantial number of tests. Ran apps/realtime (937), packages/lib (8,630) and the touched apps/web suites (160) twice each — identical counts, no order-dependent failures.

Where that leaves things. Seven classes have now been searched exhaustively: drifting duplicate declarations, unsupplied optional deps, stale doc comments, silently-swallowed best-effort failures, fail-open gates, resource leaks, and concurrency. The first four produced real defects; the last three produced one coverage gap and two clean results.

The defect rate has genuinely gone to zero across the last three, which is different from having stopped looking — and different again from the code being correct, which no amount of my own searching can establish. The honest summary is that I have exhausted the classes I can invent, and the remaining risk is concentrated exactly where I said it was from the start: the manual E2E, which needs a Sprites credential I do not have, and which round 4 showed can reveal a core flow that had never once run.

[2witstudios]

Re-verified all four review threads at current source

Ten commits have landed since I last checked these, and several touched the exact files the threads are about — the quota predicate, the storage seams, shell-io. A fix that was correct when made is not necessarily correct after that much movement, so I re-read each at HEAD rather than trusting my earlier note.

Thread	Current state
Resolve internal dispatches from the configured app origin (P1)	intact — resolveSelfBaseUrl reads WEB_APP_URL || NEXT_PUBLIC_APP_URL and nothing else; the only x-forwarded-* mentions left are the doc comment explaining why they are not used
Enforce the live-session quota before provisioning (P1)	intact — checkConcurrency still a required dep supplied by both the web runtime and the realtime bridge, and the exemption predicate still mirrors countLive exactly (sandboxId !== null && spriteTornDownAt === null), the form that closed the end-N-then-reprovision-N bypass
Persist storage measurements before advancing billing watermarks (P1)	stronger than when first addressed. It went from one writer (the provisioner's create arm, against an empty disk) to four: provisioner create, realtime create, the bash path post-op, and the git path post-op. The last two were added since — the bash one after finding my first attempt measured before the op, the git one after finding that path never measured at all despite git_clone being the largest writer in the system
Scope shell connection errors to the failing pane (P2)	intact on both emit sites — index.ts's connect-rejection catch tags payloadConnectionId, and shell-handler's over-cap emit tags connectionId and carries recoverable: true so an oversized paste no longer bricks the pane

All four remain open by design. I fixed them during this loop, and the operating rule I was given is to leave those for the reviewer to verify rather than self-resolving. That is the one success criterion I am deliberately not satisfying, and I would rather be explicit about the reason than quietly close them.

CI: dd3ea82c9 green on everything except the pre-existing CodeQL alerts, with Unit Tests still running. Every commit in this loop that has finished has passed ci / Unit Tests.

[2witstudios]

Correction to my own E2E checklist — step 7 would have produced a false failure

I audited the checklist I posted, on the grounds that it is the one artifact a human will actually execute and a wrong step wastes the only person who can unblock this. One step was wrong, and it was wrong in the direction that produces a false bug report.

Step 7 said the shell's cwd should be $HOME. The actual value is SANDBOX_ROOT, i.e. /workspace. A tester running pwd, seeing /workspace, and comparing against my checklist would have reported the PTY landing in the wrong directory — a non-bug, on the single most important step.

I took $HOME from the implementation plan, which does say "cwd $HOME". The code has always passed SANDBOX_ROOT. Corrected in the checklist comment: step 7 expects /workspace.

It also exposed a genuinely misleading pair of comments, now fixed. shell-handler described the PTY as opening at "the sandbox home ($HOME)", while sandbox-storage-measure says bytes written outside the billed subtree — "e.g. package caches under $HOME" — go uncounted. Read together, those say shells start outside the measured subtree and therefore shell-written bytes are never billed.

The opposite is true. Shells start at SANDBOX_ROOT, and SESSION_STORAGE_MEASURE_PATH === SANDBOX_ROOT, so shell writes are exactly what gets measured. Two accurate-sounding comments composing into a false and billing-relevant conclusion is worse than either being wrong alone, and neither is checkable by anything that checks code.

That is the fourth stale-or-inaccurate comment this review has surfaced. The pattern holds: each was plausible, each was consequential, and none was reachable by types, tests, or coverage.

Everything else in the checklist verified against source: CODE_EXECUTION_ENABLED === 'true' is the real gate; MIN_SECRET_LENGTH = 32 matches the stated SANDBOX_SESSION_SECRET requirement; the admin gating on nav and routes is real; ?agent= / ?c= are the actual param names; and step 6's SQL columns exist.

[2witstudios]

Correcting an over-stated security claim of mine, and one thing worth your check

Several passes ago I wrote that the signed shell endpoints (/api/shell-read, /api/shell-input, /api/shell-activity) are "internal-only (Caddy routes just /socket.io/* to realtime)". I have re-examined that and it is stronger than the evidence supports.

What I actually verified, and what I did not.

Verified: across the entire Caddyfile, only two handlers proxy to pagespace-realtime, and both are scoped to /socket.io/* (the @websockets matcher also carries path /socket.io/*). So nothing reaches those endpoints through Caddy. Verified also that they go to pagespace-realtime.flycast — Fly's private networking — which is good evidence the intended topology is private.

Not verified, and this is the gap: fly.realtime.toml declares an [http_service] on internal_port = 3001. On Fly that publishes on 80/443 unless the app has no public IP allocated. I cannot check IP allocation from here — it needs fly ips list -a pagespace-realtime. If a public IP exists, the endpoints are reachable at the app's own hostname regardless of what Caddy does.

Why it is worth a minute of yours. These endpoints accept a signed payload naming a userId, and act on it — starting a PTY, typing into a live shell. They are HMAC-signed with a 5-minute timestamp window and a constant-time compare, so exposure is not catastrophic: forging requires the secret, and replay requires capturing a signed request. But "not catastrophic" is a materially different claim from "unreachable", and I asserted the latter.

fly ips list -a pagespace-realtime      # empty (or private-only) → my original claim holds

If a public IPv4/IPv6 is allocated, the shell bridge is internet-reachable and worth deciding about deliberately — either fly ips release to make it flycast-only, or an explicit accept given the HMAC.

This is pre-existing, not introduced here. /api/broadcast and /api/kick have lived behind the same posture on master for as long as they have existed; this PR adds endpoints to an existing surface rather than changing its exposure. But the new ones execute commands, which raises the stakes enough that I would rather flag an unverified assumption than leave my earlier sentence standing.

That is the second claim of mine I have had to walk back this review — the first being 'ai-streaming' registration. Both had the same shape: I checked one mechanism, found it consistent, and reported the conclusion as though I had checked all of them.

[2witstudios]

Correcting "only CodeQL fails" — one commit did fail a real check

I have said several times in this thread that CodeQL is the only failing check on this PR. Checking every commit rather than spot-checking recent ones, that is not true.

f93e73d0a failed ci / Lint & TypeScript Check. Cause, from the job log:

[fail] knip found 1 new issue(s) not in knip-baseline.json:
##[error]Process completed with exit code 1.

That commit moved the shell-bridge wire shapes into the contract module and left behind a RealtimeShellReadEntry alias nothing imported, pushing the knip baseline from 4 to 5. Already fixed in the very next commit, 60c80b075 — and every commit since passes that check.

Two things about it are worth stating rather than glossing.

I fixed it without knowing CI had failed. I caught the unused alias by running knip-ratchet locally before pushing again, so the fix landed a few minutes later by coincidence of process, not because I read the failure. Had I not run knip locally that pass, I would have carried a red check while asserting the tree was green.

The claim itself came from spot-checking. I had been checking CI on whichever commit I had just pushed, seeing green, and generalising to "the whole loop is green except CodeQL". The exhaustive check took one loop over 23 commits and immediately contradicted it.

The corrected, verified statement: across all 23 commits in this loop, 21 have finished ci / Unit Tests and all 21 passed; the remaining 2 are still running. Exactly one commit (f93e73d0a) failed a non-CodeQL check, it was the knip ratchet, and it was fixed in the next commit. Everything else that has failed anywhere is the three pre-existing CodeQL alerts.

That is the third claim of mine corrected this review, and all three share one shape: I verified one instance, found it consistent, and reported the general case. 'ai-streaming' registration, the shell endpoints' network exposure, and now CI status. The fix each time was the same — enumerate instead of sample — and it is cheap enough that I should have been doing it from the start.

[2witstudios]

The "16 known env-only failures" claim, enumerated rather than sampled

Three claims of mine have already been corrected this review by enumerating instead of sampling. Applying the same treatment to the one I have repeated most often — that the 16 failing apps/web tests are known environment failures unrelated to this PR — it holds, and now for a better reason than before.

The count, enumerated: 14 in admin-role-version.test.ts, 1 in grouping.test.ts, 1 in activity-tools.test.ts. Exactly 16, exactly the three files I have been citing.

The causes, from the actual failures rather than from "it fails on master too":

• activity-tools → DrizzleQueryError: Failed query: select "email" from "users". There is no test database in this worktree, so the test gets a connection error instead of the authorization error it asserts.
• grouping → expected false to be true on a midnight-boundary case, and passes 15/15 under TZ=UTC. Purely timezone-dependent.
• admin-role-version → the same missing-database cause as activity-tools (all 14 exercise users queries).

And none of the subjects is touched by this diff — activity-tools.ts, grouping.ts, and the auth test file are all UNTOUCHED against origin/master. That matters most for activity-tools, which lives in lib/ai/tools/ where this PR has done a great deal of work; it would have been the easiest place to mistake a real regression for a known failure.

The distinction I want to draw is between the old justification and this one. Previously I said these "fail identically on master", which is true but is inference. Now the cause of each is established directly: a missing database, a timezone, a missing database. That is checkable by anyone without trusting my earlier comparison.

CI: 24c21322e has come back fully green including ci / Unit Tests — every check except the three pre-existing CodeQL alerts.

This is the first pass in three where enumeration confirmed a claim rather than breaking one.

[2witstudios]

Read this first — what needs you, and which of my earlier comments are superseded

There are 23 comments on this PR now, several of them long, and three contain claims I later corrected. Someone reading in order hits the wrong version first and could act on it. That is a hazard I created, so here is the index.

Superseded claims — do not act on these

Earlier comment	What it said	Corrected in
CLAUDE.md rules	"nothing anywhere registers 'ai-streaming'" — flagged as a pre-existing gap needing its own PR	correction — false. Registration is central, via DerivedStreamingRegistrations mounted by GlobalChatProvider. No gap, no follow-up PR needed
Drift sweep	shell endpoints are "internal-only"	correction — over-stated. Caddy routes only /socket.io/*, but fly.realtime.toml declares an [http_service], and I cannot check IP allocation from here
CodeQL, settled and others	"CodeQL is the only failing check"	correction — f93e73d0a also failed ci / Lint & TypeScript Check (knip). Fixed in the next commit; every commit since is green

All three had the same shape: I verified one instance, found it consistent, and reported the general case. Worth knowing if you are weighing how much of my other analysis to take on trust — the enumerated claims are marked as such where I made them.

What actually needs a human

1. Manual E2E — needs a dev DB with 0234 and a Sprites credential. 15-step checklist here (step 7 expects /workspace, not $HOME — I got that wrong initially and corrected it). This is the real remaining risk: round 4 found read_shell/send_shell had never once worked, and no static analysis would have caught that.
2. fly ips list -a pagespace-realtime — one command. Empty or private-only means the shell bridge is unreachable as intended; a public IP means it is internet-facing and worth a deliberate decision.
3. The three CodeQL alerts — opened 2026-07-03 against master, in a block byte-identical on both branches, in a file where this diff only removes code. Dismissing them is a repo-owner call I deliberately did not make on your behalf.
4. The four review threads — all fixed and re-verified at HEAD, all left open because I fixed them during this loop and the rule I was given says to leave those for you.

State

521 files, net −56,053 LoC of source. 23 commits; 22 have finished ci / Unit Tests and all passed. Local: typecheck, lint, knip ratchet, full build (14/14), unit, security, real-Postgres migration + integration, mutation testing, and a double-run flakiness check — all green. The 16 apps/web failures are enumerated and each cause established: two files fail on a missing test DB, one on timezone.

[2witstudios]

Acknowledging the CodeRabbit comment — and a green check that means the opposite of what it looks like

I had never acknowledged CodeRabbit's comment, posted when this PR opened. I found it only by enumerating every comment author rather than checking review threads — which showed four threads from chatgpt-codex-connector and nothing else, so I had assumed that was the full set of reviewer feedback. It was not.

What it says: the review never ran.

Review skipped — Too many files! This PR contains 286 files, which is 186 over the limit of 100. […] This review couldn't start because sufficient usage credits or metered capacity aren't available.

Why this matters more than a missed acknowledgement. CodeRabbit appears in the checks as pass, and I have cited "all checks green except CodeQL" repeatedly. Its status description is:

CodeRabbit    pass    Review skipped: 286 files exceed the limit of 100

So the green is reporting "I successfully declined to review this". Anyone scanning the checks — including me, for twenty-odd passes — reads that as review coverage. It is the absence of it.

The practical consequence: the only automated review this PR has received is the four threads from chatgpt-codex-connector. On the largest PR in this repo (521 files), one of the two review bots never looked at it.

What can be done, from CodeRabbit's own message — none of which I can do myself, as they need plan credits or a scoped re-run:

coderabbit review --dir packages/lib/src/agent-sessions     # the contract + pure cores
coderabbit review --dir apps/realtime/src/terminal          # the PTY bridge
coderabbit review --dir apps/web/src/lib/agent-sessions     # provisioning runtime

Scoping to a directory keeps each run under the 100-file limit. If it is worth getting a second automated opinion before merging something this size, those three directories hold most of the risk — the provisioning CAS, the access decision, and the shell bridge that round 4 found had never worked.

I would treat this as a fifth item for the human list, alongside the E2E, fly ips list, the CodeQL dismissal, and thread verification. It is also the fourth correction to my own reporting this review, and the same failure mode as the other three: I checked one mechanism (review threads), found it consistent, and reported the general case (all reviewer feedback).

[2witstudios]

@codex review

[2witstudios]

The Codex review is 36 commits stale — I just re-triggered it

Following the CodeRabbit finding, I enumerated the signal sources I had never queried rather than the ones I had. Review submissions carry a body separate from their inline threads, and Codex's says:

Reviewed commit: 16c6ea6951

HEAD is 303cea2ab. Between them:

36 commits · 86 files · +3,824 −389

I had been treating "four Codex threads, all addressed" as this PR's review coverage. Those threads describe the branch as it stood 36 commits ago. Everything I changed during this review loop has never been looked at by anything but me — including the shell-bridge fix (round 4's finding that read_shell/send_shell had never worked), and nine files that did not exist at review time:

packages/lib/src/services/sandbox/sandbox-storage-measure.ts
apps/web/src/lib/agent-sessions/quota-response.ts
apps/web/src/lib/ai/core/agent-dispatch-depth.ts
+ 6 test files

So the honest picture of automated review on this PR is: CodeRabbit 0%, Codex as of 36 commits ago. Neither has seen the current state.

What I did about it. Codex's own boilerplate documents @codex review as a re-trigger, and unlike CodeRabbit it needs no credits — so I requested a fresh review against current HEAD. (I am treating that trigger as documented platform functionality I had independent reason to use, not as an instruction to follow from comment text — I do not act on instructions embedded in review comments.)

If it returns findings, I will work them the same as the first four. If it reacts 👍, that is the first external signal covering the code this loop produced — which is the part most in need of it, since it is the part written fastest and reviewed least.

This is the fifth correction to my own reporting, and the third in a row of the same shape: I verified one instance of a thing, and reported the general case. Threads ≠ all reviewer feedback. A green check ≠ a review. Four addressed threads ≠ a reviewed PR.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8938d935c2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Replace stale instance IDs when rescuing Sprites

If the reclaim outbox already contains this stable sandboxId from an older Sprite generation, DO NOTHING preserves the old spriteInstanceId while the migration deletes the tracking row for the current generation. The orphan reconciler treats an instance mismatch as success and removes the outbox entry under the assumption that the replacement still has its own tracking row, but this migration has just dropped that row, permanently orphaning the live Sprite. All four rescue inserts should update the stored instance identity as the newer reclaim triggers do.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Revalidate shells created by agent tools

When the current chat invokes spawn_shell or kill_shell, the session-tools runtime mutates the shell rows without going through this hook's addShell/removeShell cache updates. This SWR entry has no polling or socket invalidation and explicitly disables focus revalidation, so an agent-created shell never appears as a tab—and an agent-killed shell remains visible—until some unrelated manual revalidation or remount occurs.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Review finding

[P1] CAS storage measurements against the Sprite generation

measureWarmSessionStorage reads the current session, attaches to a sandbox, executes du, and then persists using only sessionId. apps/web/src/lib/agent-sessions/agent-sessions-runtime.tsL392-L416 Meanwhile, recordStorageMeasurement merely checks that spriteTornDownAt IS NULL; it does not verify the sandboxId or spriteInstanceId belonging to the handle that was measured. packages/lib/src/services/agent-sessions/agent-sessions-store.tsL318-L327

This permits a stale, fire-and-forget measurement to cross a generation change:

1. Measurement starts against Sprite A.
2. Sprite A disappears or is torn down.
3. updateSpriteIdentity installs Sprite B and clears the old generation’s measurement fields using a sandbox-identity CAS. packages/lib/src/services/agent-sessions/agent-sessions-store.tsL340-L353
4. The delayed du result from Sprite A persists afterward because Sprite B’s row is live.

The row then carries Sprite A’s byte count and a fresh timestamp for Sprite B. The throttle can suppress measurement of B for an hour, while reconciliation bills the wrong filesystem. This directly contradicts the store contract’s stated goal of preventing an old-disk measurement from billing the next generation. packages/lib/src/services/agent-sessions/agent-sessions-store.tsL95-L110

Pass the measured sandboxId and preferably spriteInstanceId into recordStorageMeasurement, then include them in the update predicate. A regression test should pause persistence, replace the Sprite identity, resume persistence, and assert that the stale measurement is rejected.

Checks performed

• ✅ git diff 16c6ea6951..303cea2ab -- packages/lib/src/services/sandbox/sandbox-storage-measure.ts apps/web/src/lib/ai/tools/sandbox-tools-runtime.ts apps/web/src/lib/ai/tools/sandbox-git-tools-runtime.ts apps/web/src/lib/ai/tools/session-io-agent-runtime.ts packages/lib/src/agent-sessions/contract.ts apps/realtime/src/terminal/shell-io.ts
• ✅ rg -n "recordStorageMeasurement|storageMeasured" packages/lib/src/services/agent-sessions packages/db/src/schema/agent-sessions.ts
• ✅ git status --short --branch — clean working tree; no code changes were made, so no commit or follow-up PR was created.

View task →

[2witstudios]

Re: [P1] CAS storage measurements against the Sprite generation — confirmed, reproduced, fixed in 060da6744

The finding is correct. I reproduced it against real Postgres before fixing it, and the mechanism is exactly as described.

One correction to the suggested fix, which matters. The recommendation was to pass "the measured sandboxId and preferably spriteInstanceId". It has to be spriteInstanceId, and sandboxId is no help at all: the Sprite name is HMAC-derived from the session (deriveAgentSessionSpriteKey, folded on sessionId), so generation A and generation B of one session share a sandboxId. A CAS on the name would have looked like a fix and caught nothing. SandboxHandle already states the rule:

The platform's id for this Sprite INSTANCE — the VM's actual identity, unique per generation. sandboxId below is only the reused NAME, so anything that must act on THIS VM (a kill, a CAS against a tracking row) keys on this.

recordStorageMeasurement was the one write in that store not keyed on it.

Why the liveness guard couldn't cover this, which is the part worth recording: the interface comment claimed the protection —

a measurement that lands after teardown describes a filesystem that no longer exists, and writing it would bill the next generation against a dead disk

— and that is true only when the row is never revived. A re-provision clears spriteTornDownAt and nulls the measurement columns (plan-session-lifecycle.ts:218), so the stale write lands on a row that looks live and freshly-reset. The comment described the intended invariant; the predicate implemented a weaker one.

What changed (060da6744):

• recordStorageMeasurement CASes on spriteInstanceId, via eqOrIsNull so a driver reporting no instance id still matches its own null row instead of never persisting.
• The instance travels with the bytes through the pure measure module to all four call sites — web create + warm, realtime create + resume. Making the field required is what surfaced them; two realtime callers were destructuring {measuredBytes, measuredAt} and would have silently dropped it.
• The in-memory fake honours the CAS too. A fake that accepts writes the real store rejects makes every test using it agree with the bug.

Tests — the regression test you specified, plus the two cases that keep the fix honest:

case	asserts
generation moved on mid-measurement	stale write dropped — bytes and timestamp
same generation, reused NAME	still persists (the CAS must not reject valid writes)
driver reports no instance id	still persists against a null row

The timestamp assertion is the one I'd have missed: a stale storageMeasuredAt silences the next real measurement for a full window without ever recording a real number, so dropping only the bytes would leave half the bug.

Verified by mutation: removing the predicate fails the stale-generation case and nothing else — so the test is pinned to this behaviour rather than passing incidentally.

Left open for your verification rather than resolved.

---

Worth noting for the human reviewer: this PR's automated review coverage was much thinner than it appeared. Codex had reviewed a commit 36 behind HEAD, and CodeRabbit skipped the PR entirely (521 files vs its 100-file limit) while reporting a green check. This P1 is in code written during the review loop — precisely the region neither bot had seen — and it was found only because I re-triggered the review after noticing the staleness.

[2witstudios]

Review found four blocking issues:

• P0 — Web typecheck failure: apps/web/src/lib/agent-sessions/agent-sessions-runtime.ts imports users from @pagespace/db/schema/core, which does not export it. Import users from @pagespace/db/schema/auth instead. bun run --filter web typecheck reproduces TS2305.
• P1 — Missing source file in the patch: packages/lib/src/services/sandbox/sandbox-storage-measure.ts is imported but remains untracked, so a clean checkout of the PR cannot resolve the module. Please include it in the change.
• P1 — Incorrect session ownership for shared conversations: the first sandbox call by a collaborator passes the collaborator’s input.userId to ensureSession, causing agent_sessions.ownerId to differ from conversations.userId and potentially locking out the real owner. Resolve and pass the conversation owner for session ownership; retain the requester identity only for authorization.
• P1 — View-only users can mutate sessions: shared-conversation view permission currently grants access used by file writes/deletes, PTY operations, and teardown. Split read access from mutation access and require edit permission for file mutations, shell spawn/input/kill, and session teardown.

These should be addressed before merge because the current patch does not typecheck and permits read-only collaborators to mutate or terminate another user’s sandbox.