feat(env-bridge): a global assistant reaches any environment it may see — cloud by canRunCode parity, local by the owner's opt-in, both by a mandatory opaque envId

[2witstudios]

The one-sentence proof

A dashboard conversation can run in any cloud environment the person could already run code in, plus any local machine they switched on — and cannot run anywhere by omission or by a guessed id.

Base and target are pu/local-env-ga, not master. Do not merge — #2590 is the founder's.

---

Scope correction: CLOUD environments, by canRunCode parity

This PR originally shipped local-only. That was the wrong deliverable and it is corrected here (c72c4996a, f7b4a24df). The founder's ask was "any of the sandboxes", and a Sprite env is the cloud sandbox.

Founder ruling (2026-09-12): "if the user can, their global assistant should be able to." Exact parity with what the person can already do inside the drive — nothing more, nothing less.

• A CLOUD env has no owner, so there is nothing to opt in to: the drive permission IS the visibility. decideEnvReach gains a sprite arm keyed on an injected mayRunCodeInEnvDrive, computed as canRunCode({ userId, driveId: env.driveId }) — same kill switch, same payer tier (the drive's owner), same drive access and canEdit. A VIEWER is refused exactly as in-drive. Used verbatim, never re-derived.
• The parity promise is a TEST, not a comment. For every verdict canRunCode can produce, the reach verdict must equal it; neither a stray visibility flag nor the actor's identity can make them diverge.
• LOCAL_ENVS_ENABLED gates local machines only. It is the opt-in for exposing personal hardware to a shared drive, applied per substrate in one place so discovery, resolution and the eligibility strip share one answer. Gating cloud on it made the whole correction a no-op in production — see the review round below.
• Local machines are unchanged: owner + visibleToGlobalAssistant + [D-6] bind, and a drive permission substitutes for neither half.

The session shape, which is what keeps every Sprite invariant intact rather than relaxed: a cloud env's session is bound to that env's drive. So spawnAgentSession's env.driveId !== driveId comparison is satisfied, not bypassed; the negative that a driveless spawn is refused a Sprite env stays true and unmodified; decideAgentSessionAccess still derives access from the drive; billing still resolves to that drive's owner. Only a local machine's session is driveless.

Still not here: switching a conversation's default environment (it keeps its own sandbox and names a target per call), and session-level taint (R-16).

The new blast radius is named, not buried (R-20): injection in a global conversation can act in any cloud env the person can edit. That is parity, not escalation — their own in-drive agents already can — but it aggregates, reachable from one conversation instead of many, by the agent that reads the most untrusted content.

Leaf A — visibility, default off (LOCAL machines)

What. drive_envs.visibleToGlobalAssistant (NOT NULL, DEFAULT false), owner-only to change through PATCH .../envs/[envId], with a toggle on Settings → Local environments. The pure decideEnvReach decides reach.

Why. The global assistant's context spans every drive the person belongs to, so what it may reach is a deliberate choice rather than a consequence of ownership. The flag lives on drive_envs, not the local sibling, so both substrates answer one question through one column — the schema docblock says why. The write's owner predicate is a correlated EXISTS on drive_env_local.ownerId, never a drive role, so a drive admin who did not enrol the machine is refused exactly as a stranger is.

Visibility is not authority: a test asserts decideBind still refuses a non-owner on a fully visible env. It is re-read on every call, so switching it off refuses the next call rather than honouring an earlier reach. decideEnvReach's three refusals surface one sentence, so an id that does not exist and one the caller may not see are indistinguishable.

Tests. 8 service/pure rows + 5 route rows + 4 Postgres integration rows (cross-table CAS, byte-identical row for a non-owner, Sprite env and unknown env both refused).
Mutation. 10/10 killed, 2 no-op controls survived.

Leaf B — list_environments

What. A discovery tool plus GET /api/env-bridge/environments (404 with the flag off). listVisibleToGlobalAssistantByOwner applies two conditions in SQL: the caller owns the machine AND it is visible. Revoked machines excluded.

Why. The mandatory id in leaf C is only safe if the model gets it from somewhere. Ownership is the real access filter and deliberately not drive membership — a drive relationship is not an entitlement to every row in it (PR #2609) — which is also why a machine in a drive the owner has since left is still listed: it is their computer. The conversation's own sandbox is a row like any other, addressed by the conversation's own id, so leaf C leaves no implicit path. An empty list is never returned as an empty list: a model handed [] with a mandatory field to fill has every incentive to invent one, so the answer says in words that there is nothing to copy.

Tests. 10 pure/tool rows + 4 route rows + 3 Postgres integration rows (someone else's visible machine absent; the caller's machine in a drive they left still present).
Mutation. 7/7 killed, 2 controls survived.

Leaf C — a mandatory, opaque environmentId

What. Required on all four tools. The zod boundary constrains the shape; productionResolveEnvironmentTarget resolves it server-side.

Why. Three properties, each the fix for a different way July's target went wrong (cf576fbc1):

• Mandatory — omission is a schema error the model sees, never a fallback. Removed at every layer: acquireSandbox refuses missing_environment rather than picking a default, and the two deliberately-unaddressed consumers (git/gh toolkit, copy_content) now name the conversation's own target explicitly.
• Opaque — isCuid alone accepts main, staging and prod, precisely the values the post-mortem saw invented, so the schema also requires 20–32 characters. The length floor is the half that works.
• Described — every description says copy, never construct. The post-mortem records that the prompt and descriptions encouraged the bad value, so the wording is asserted by a test.

Unknown / not-yours / not-visible / flag-off all surface one sentence naming list_environments.

Leaves C and D are INSEPARABLE — neither ships alone. Reading the commits in order, C lands the mandatory id and its refusals but deliberately leaves one branch unfinished: a valid, reachable NAMED environment resolves and is then refused environment_routing_not_enabled at acquire, rather than running somewhere the caller did not name. That is a safe intermediate, not a releasable one — with C alone the only environment that works is the conversation's own sandbox. D replaces exactly that branch with real routing. A reviewer should not conclude C was releasable on its own, and neither commit should be cherry-picked without the other.

Tests. 9 tool rows + 7 runtime resolver rows + 4 schema rows.
Mutation. 10/10 killed, 3 controls survived.

Leaf D — routing, and the driveless bind

What. spawnAgentSession branches on substrate; agent_workspaces_env_needs_drive_check dropped (migration 0296); a named environment runs in its own session via findActiveByOwnerAndEnv. This is the other half of leaf C (see above): it is what turns C's environment_routing_not_enabled refusal into a run.

Why. The CHECK could not express the distinction it needed to. It was right about a Sprite env — drive-owned, drive-paid, no owner of its own, and decideAgentSessionAccess derives access from driveId alone — and that arm is unchanged and still enforced in the service, with a test pinning that a driveless spawn is still refused a Sprite env. It was wrong about a local env, where [D-6] already makes binding structurally owner-only, so relaxing the comparison removed a redundant scoping check rather than an ownership one ([D-4]). The schema docblock records where the guarantee now lives; a test asserts a non-owner is still refused a local env with and without a drive, so this cannot have made the bind gate the only thing standing between a stranger and someone's hardware.

One session per environment, never one re-pointed — re-pointing is the predecessor's switch_machine: it races every concurrent call in the session and silently moves work a previous call believed was elsewhere. Billing and authorization follow the environment: the resolver returns payer coordinates alongside the target, the gate runs on those, and resolveBillingSession resolves the same session through the same find-or-spawn, so a drive environment bills that drive's owner exactly as it does today and a credit-exhausted payer is refused before a sandbox wakes. No new refusal vocabulary; reconnect still carries the acting principal, so a mis-addressed call at the owner's machine still waits for their passkey-verified click.

Tests. 6 spawn rows + 9 routing/billing rows + 1 click-path row; the DB integration row that asserted the CHECK now asserts its absence.
Mutation. 7/7 killed, 2 controls survived.

Leaf E — results name the environment

What. Every result and every post-resolution refusal carries environment: { id, label }, stamped once at the tool boundary.

Why. With a mandatory id the remaining failure is copying a real id for the wrong environment. Both fields come from the server's resolved row and are never echoed from the model's input — a test names a different id than the resolver returns and asserts the result reports the resolver's. A refusal that never resolved an environment names none: naming one would be inventing it. It records nothing new; drive_env_grant_audit already carries envId, and the test asserts the audit-write count stays at one.

Tests. 7 rows. Mutation. 4/4 killed, 1 control survived.

Leaf F — docs

Posture doc: a new section, four layer rows — including one for the drive agreement naming both branches — prose on the dropped agent_workspaces_env_needs_drive_check (why it was right about a Sprite env, wrong about a local one, and where the guarantee lives now), R-16 (session-level taint), R-17 (a real id for the wrong environment) and R-18 (the constraint-to-code-branch trade, and the rule that any new writer of agent_workspaces.envId must go through spawnAgentSession), two flag-on checklist items, [D-4] rewritten from deferred to resolved. Customer page and changelog carry the same limits and no capability the internal document does not. A documentation test pins all of it.

Mutation. 8/8 killed, 1 control survived.

---

Review round 1 — three Codex findings, all real, all fixed

Each as its own commit, red first, mutation-checked.

P1 — discovery and resolution were not gated to global conversations (f2d37238e). The most serious one: it broke a promise made in three places. buildSandboxTools() is constructed once and shared by every turn, and decideEnvReach took only { actorId, env }, so by construction nothing could tell a dashboard turn from a page turn — a sandbox-enabled page agent could list and address the machine someone had switched on for their global assistant. conversationKind now rides the actor context (failing closed: only an explicit 'global' is global) and decideEnvReach refuses not_global first, before the row is read, so a page turn cannot probe for an id's existence. The rule is one shared predicate because there are two call sites. The toggle copy is unchanged — the promise was already the narrow one, and the code now matches it.

P1 — discovery gated on the wrong payer (f69171ad2). list_environments runs no code but went through the run gate on the conversation's payer, so a free-tier person who owns a visible machine in a Pro-owned drive could never obtain the id of the one place they can run — contradicting canRunCode's own rule that the tier leg keys on the payer. gateDiscovery asks "may this actor run anywhere they can reach?", never second-guessing the kill switch, and the pipeline strip (sandbox-tool-eligibility.ts) got the same fallback — without it, fixing the tool alone would have changed nothing, because the family is stripped before the tool can be called.

P2 — the owner-after-departure case always failed (36678d864). The directory deliberately lists a machine in a drive its owner has left — it is their computer — and every call on it refused no_drive_access; the bind gate had it too, so the spawn failed as well. A local env authorizes on machine ownership ([D-6], decideBind, and decideEnvReach immediately before), so the drive is now the billing coordinate only: gateDriveId is absent for a local target, and the bind gate calls canRunCode with no driveId. Kill switch and tier leg untouched; a non-owner falls to bind_policy, the accurate reason. Consequence written down rather than discovered (R-19 + a layers row): a departed member can run on their own machine and that drive's owner is still metered, because the env row is drive-owned and drive-paid — the drive's remedy is the Delete/Revoke [D-6] already gives it.

Two CI failures on the previous head, both fixed in f69171ad2 and neither caused by the fixes: a new unused export (LIST_ENVIRONMENTS_TOOL_NAME — used rather than ignored, per the ratchet's own instruction), and a stale integration row asserting the rationale leaf D deliberately inverted. That row is re-pointed and re-titled, with three siblings so it proves the new intent rather than accepting a new string: the same env binds once connected (asserting the session's and the env's drives genuinely differ), a non-owner is still refused bind_policy, and a driveless global session binds a connected local env it owns — the case [D-4] blocked.

Two repo-wide gates caught the new surface (df2723a80)

Found by running the full web suite against a real Postgres rather than only the directories the diff touched — neither of these lives near the code it guards, and both were doing their job:

• registry-coverage — every AI tool must have a rich renderer, and list_environments had none, so it would have rendered as raw JSON. It gets a real one: the label above the id for each row, plus the notice. That is also the one place a person can see which of their machines the assistant can currently reach, and by absence which they have not switched on.
• the env-bridge route inventory (in list-route.test.ts's "no code path sends an approval TO the machine" invariant) — it pins the exact set of api/env-bridge/* directories so a new route family must be acknowledged on purpose. environments is added with the reasoning stated: a GET over rows the caller owns, returning no frame to any machine.

These are the same shape as the GDPR coverage gate and the @pagespace/lib exports map: a change that adds a member to a set the product enumerates trips a test three directories away.

Review round 2 — the dedup held to the standard the PR set itself

f5991fad1 — the per-drive dedup in 3fcaaab17 was correct but written twice (discovery gate and pipeline eligibility strip) and asserted in neither. That is the shape this PR already rejected once: when discovery and resolution had to agree, the rule became one predicate with a row pinning that they cannot drift. Same standard applied — anyReachableEnvironmentPayerAllows owns the iteration; each caller keeps its own authorizer, and that difference is genuine and now stated: the strip stands where tool registration stands and asks canRunCodeForSession, the gate stands where a call stands and asks the full call-time gate. Sharing it is the point — fixing one alone changes nothing, because the strip removes the tool before the gate can allow it. Rows: two machines in one drive resolve the payer once; two drives ask twice; a drive whose payer does not resolve is skipped without refusing the others; the first allowing drive stops the loop; every uncertainty fails closed. Plus a source scan pinning that neither caller has regrown its own loop.

One of those rows initially survived its mutant: the flag-off case was asserted with a throwing authorizer, which the fail-closed catch swallowed, so it held with the flag check deleted. It now asserts the observable consequence — nothing listed, nothing authorized — and kills it.

7547f2f89 — knip.json ignores src/**/__tests__/**, so the two new exports consumed only by that test would have read as dead code (the same gate that failed Lint earlier). Both are module-private now, with the test deriving the deps shape from the function's own signature — stricter than the import it replaces, since the fake cannot drift from the real parameter.

72db9a541 — openAt was spreading the whole payer object onto the actor context, so gateDriveId (a gate input, not a fact about the actor) rode along as an undeclared field on an object handed to every runner. Inert today — nothing spreads ctx wholesale, and TypeScript will not surface it — but it would reach an audit row the first time someone writes ...ctx. Split off where it is produced, so the property cannot exist rather than merely being unused.

Review round 3 — one BLOCKING defect: cloud reach was dead in production (f7b4a24df)

LOCAL_ENVS_ENABLED is off on every deployment, and it was short-circuiting the cloud path in three places — the discovery gate's fallback, the pipeline eligibility strip, and (not in the report, and worse) resolution itself, which refused before it had even looked the environment up. So the ruling failed for exactly the case it exists for: a person whose own tier cannot run a personal sandbox, but who has edit access to a paid team drive, got no tools, no discovery and no resolution.

The flag now applies per substrate, in the one place that decides it: local rows are not listed and not even read while it is off; cloud rows are never gated on it; resolution asks it only after the lookup and only for a local env, because the question cannot be answered without knowing the substrate. The refusal is still the single message.

Red first against the flag's real reader (process.env.LOCAL_ENVS_ENABLED), never an injected stub — which is precisely why this was invisible before: every existing test injected true while production is always off.

Also fixed, the minor: discovery and resolution asked canRunCode with different origins, so an agent-origin call could see a laxer list than the next call would honour. The origin is threaded and asserted.

Gates

• Exports-map sweep — every @pagespace/lib/* subpath touched by the diff has a packages/lib/package.json entry; two new ones added (env-bridge/decide-env-reach, services/sandbox/environment-directory). No new @pagespace/db subpath.
• db:generate is a no-op — migrations 0295 (add column) and 0296 (drop constraint) both generated, never hand-edited; a second run prints "No schema changes, nothing to migrate" and drizzle-kit check prints "Everything's fine". drive_envs is table-level excluded from the GDPR export, so the new column needs no collector.
• tsc --noEmit clean in packages/lib, packages/db, apps/web, apps/marketing.
• bunx eslint clean on all 19 touched apps/web files and on the touched marketing file.
• Mutation: 73/73 real mutants killed, 19 no-op controls survived, by line index, rebuilding packages/lib dist between mutate and run. (Correction: commit 36678d864's message says "4/4" for that fix; the sweep was 3 real mutants and 1 control. The total above is the accurate one.)
• Verified against a real Postgres, not blind — the previous head's one genuine test failure was a DB-backed suite I could not run locally, so I stood one up. Migrations 0295 and 0296 apply to a clean database: visibleToGlobalAssistant is NOT NULL DEFAULT false, agent_workspaces_env_needs_drive_check is absent, and its sibling agent_workspaces_env_no_sprite_check is still there. env-sessions.integration 23/23, the DB-backed lib suites 857/857, web agent-workspaces + ai 5153/5153.
• bun run knip:check reports a handful of findings in this worktree that CI does not see (a known pu-worktree artefact — all in files the diff never touched); the one issue CI did report is fixed by using the constant rather than ignoring it.
• The full web suite passes against a real Postgres apart from two known local-only classes: the tiptap/ESM module-load failures and chat-mutation-matrix, both of which pass in CI and neither of which this branch touches.

Exit criterion

All six leaves green and mutation-checked; an environment with visibility off is unreachable; a missing or guessed environment id refuses; a mis-addressed call at the owner's machine still needs the click; db:generate a no-op; leaves flipped on the board.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CTEebBGVxXnTZ9S6xAn646

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 5388e6b7-679e-4f9f-a808-113fc2e674c1

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

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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: 6bbb449c17

ℹ️ 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".