flowviant 0.125.28 → 0.125.30

package/README.md

@@ -200,6 +200,370 @@ On Claude Code and Codex build turns, `card_ui_review.inspect_screenshot` can su
 
 The agent can fix in-scope findings and rerun up to three attempts per turn, each capped at two minutes including startup. Every attempt stops its owned browser and preview, including on cancellation; teardown also tracks their process groups. Reports and screenshots use `.flowviant/artifacts/`, and the existing delivery Verification retains routes, viewports, actions/outcomes, scrubbed diagnostics and source identity. Tracked/nonignored file bytes and HEAD are remeasured at delivery; later changes mark evidence stale. Ignored build/runtime files are outside that source measurement. The project check, fresh read-only pre-review, human approval and merge remain separate.
 
+## Isolated review environments
+
+Code agents can provision disposable databases natively. This is opt-in: commit
+`.flowviant/environment.json` on the reviewed base branch. Projects without a
+recipe keep their existing setup. This layer works independently of the model
+and whether the project has a browser preview.
+
+For PostgreSQL, use a **dedicated development/review server** with `psql` on the
+daemon's PATH. The administrative role needs permission to create/drop databases,
+create restricted login roles and assign database ownership. Flowviant creates
+an empty database from `template0` and a distinct role for each worktree. It
+does not clone the contents of a shared development or production database.
+
+```json
+{
+  "version": 1,
+  "database": {
+    "provider": "postgres",
+    "adminUrlEnv": "REVIEW_DATABASE_ADMIN_URL",
+    "bindings": ["DATABASE_URL", "DIRECT_DATABASE_URL"]
+  },
+  "migrate": ["npm", "run", "db:migrate"],
+  "seed": ["npm", "run", "db:seed"],
+  "envFiles": [".env.local"],
+  "env": {
+    "NODE_ENV": "development",
+    "CACHE_PREFIX": "review_${ENVIRONMENT_ID}"
+  },
+  "connectors": ["database"],
+  "ttlHours": 24
+}
+```
+
+Use this project's actual migration/fixture scripts and connector names. Commands
+are argv arrays, run without a shell. The migration runner and fixture seeder
+must tolerate retries after partial failure. Each listed project MCP connector
+must reference one of the database bindings, for example `${DATABASE_URL}` in
+its environment configuration. Flowviant expands it from the same scoped values
+the app receives. Unlisted/personal connectors are not rewritten or isolated.
+
+Machine-local values belong in the gitignored
+`.flowviant/environment.local.json`, with mode `0600`, or the admin variable can
+be supplied by the daemon's environment. For example:
+
+```json
+{
+  "env": {
+    "REVIEW_DATABASE_ADMIN_URL": "postgresql://review_admin:LOCAL_PASSWORD@127.0.0.1:5432/postgres",
+    "PAYMENTS_API_KEY": "LOCAL_SANDBOX_KEY"
+  }
+}
+```
+
+This local file stays in the checkout. Its selected runtime values, excluding
+provider administrator credentials, join the isolated database bindings. Generated
+`.env`/`.dev.vars` files and local receipts are owner-only and excluded from Git.
+Existing/tracked/user-edited env files and symlink destinations are preserved;
+choose another path if one conflicts. Use `envFiles: []` for projects that do not
+load dotenv files; the provided command wrapper injects values directly, including
+complex multiline credentials. A recipe disables automatic copying of the
+checkout's ignored `.env*`, including production profiles.
+
+The first configured build allocates the database, runs the existing setup hook
+or lockfile install once, migrates and seeds. Later cards reuse that worktree's
+database, rerun migrations and retain successfully seeded data. The agent gets
+an exact private helper command for `run -- <argv>` and `refresh`. The wrapper
+selects the repository's own bindings even when a multi-repository place has
+several environments. `refresh --seed` explicitly reruns fixtures. The local UI
+self-review and final/combined-merge checks use scoped values too; combined
+worktrees have their own databases and migrate their integrated source before
+validation. These setup receipts do not count as passing application tests.
+
+The daemon keeps local allocation intent before contacting a provider, so retries
+reuse one environment id. Active turns/checks hold a heartbeat lease. Its sweep
+releases inactive environments after `ttlHours` (1–168, default 24) or worktree
+retirement; at most two receipts per repository per sweep. Shutdown retains them
+for restart. Cleanup checks database/role ownership before deleting anything;
+failures retain the receipt for retry. A reviewed recipe change rebuilds disposable
+data after the previous environment is released. Moving a worktree retains its id.
+The daemon must be running for this sweep; a remote provider adapter should also
+set/renew its own expiration as protection while the machine is offline.
+
+To use a database provider's branches, replace the `database` object with:
+
+```json
+{
+  "provider": "command",
+  "command": ["node", ".flowviant/database.mjs"],
+  "credentials": ["DATABASE_PROVIDER_API_KEY"],
+  "source": "SANITIZED_DEVELOPMENT_BRANCH_ID",
+  "bindings": ["DATABASE_URL", "DIRECT_DATABASE_URL"]
+}
+```
+
+This is the native provider-adapter lifecycle, not an AI-generated provisioner
+on every card. The reviewed adapter receives `allocate` or `release` as its last
+argument, with the environment id, original test-data source, known resource id
+and expiration in `FLOWVIANT_ENVIRONMENT_ID`, `FLOWVIANT_ENVIRONMENT_SOURCE`,
+`FLOWVIANT_ENVIRONMENT_RESOURCE_ID` and `FLOWVIANT_ENVIRONMENT_EXPIRES_AT`.
+Stdin also carries JSON `{id, resourceId, source}`. Only the named provider
+credentials and minimal toolchain environment are passed. Allocate must look up
+the original id before creating, renew its expiration and verify ownership;
+a create-success/lost-response retry must never create another branch. It returns
+JSON `{owner, resourceId, connectionString}`. Release must verify ownership and
+reconcile by id even if allocation never returned a resource id, then return
+`{owner}`. Both operations must be idempotent. Output is private and never included
+in error messages. Repository adapter files named with `./` or `.flowviant/`
+must still match the saved reviewed blobs, including during cleanup; keep that
+adapter available until its resources are released. No commercial branch SDK
+or provider credentials are installed automatically.
+
+An allocate response may also return `bindings`, keyed only by declared database
+variable names, when the provider needs distinct pooled and direct URLs for the
+same branch. Other bindings use `connectionString`. The adapter must verify that
+all of these connections target its owned environment.
+
+Database isolation does not configure auth tenants, Redis, queues, object storage,
+email or payment sandboxes. Select their development credentials explicitly and
+namespace them with the environment id where supported. Apps and connector
+processes still run as the user's UID: this is data separation, not a security
+sandbox against repository code reading other local files. An inherited role's
+access to unrelated databases is the PostgreSQL server's policy; use a dedicated
+review server. See PostgreSQL's [database creation documentation](https://www.postgresql.org/docs/current/sql-createdatabase.html).
+
+## Runtime review adapters
+
+Commit `.flowviant/review.json` on the project's reviewed base branch to expose
+repeatable review workflows to code agents. One `card_runtime` interface supports
+command checks, browser apps, Linux desktops, Roblox Studio and native/engine bridges. Projects
+without targets mount no additional tools or processes. The agent's existing
+shell and browser workflows remain available.
+
+```json
+{
+  "version": 1,
+  "targets": {
+    "checks": {
+      "adapter": "command",
+      "command": ["npm", "test"],
+      "timeoutSeconds": 120
+    },
+    "web": {
+      "adapter": "browser",
+      "command": ["npm", "run", "dev", "--", "--port", "${PORT}"],
+      "port": 0,
+      "fixture": "Disposable seeded review database and test account"
+    },
+    "desktop": {
+      "adapter": "desktop",
+      "platforms": ["linux"],
+      "command": ["npm", "run", "desktop:dev"],
+      "fixture": "Disposable local workspace and sandbox service bindings"
+    }
+  }
+}
+```
+
+Use the repository's real commands. A Roblox repository can declare command
+targets for its configured Luau analyzer, standalone logic tests or Rojo build;
+these results do not claim a Studio playtest. The adapters do not install tools
+or infer gameplay from a sync server's listening port. `cwd` defaults to the
+repository root and must resolve inside that worktree. Commands are argv arrays,
+without shell expansion. Timeouts are 1–600 seconds. Browser `port: 0` allocates
+a loopback port and substitutes only `${PORT}`; a fixed port is also supported.
+The listener is attributed to the target worktree before Chrome opens it.
+The runtime MCP server gives Codex a longer tool-call timeout in its private
+build config so the CLI's default does not truncate a configured command.
+
+`discover` reports targets and actual prerequisites without launching apps.
+`run` executes a named target; command results retain exit status, bounded logs
+and source identity. A large log stays in the evidence artifact while only its
+tail enters the model context. Browser/desktop/engine targets use the existing
+Live app frame, private sign-in and take/return/stop control. `observe` retains
+the actual screenshot, `act` supplies bounded input, and `handoff` holds the turn
+without model polling. Screenshots and interactions are observations, not passing
+tests. Source changes invalidate earlier command evidence. The shell helper
+supplied to runners without MCP omits image base64 from text output; the model
+opens the retained screenshot with its own image tool if available.
+
+Only an interactive target launch creates a browser/display or stream. One
+interactive surface occupies the frame per held turn. Native screenshots run at
+a bounded low cadence, with fresh captures after input; the stream invokes no
+model per frame. Adapter-owned app/process groups stop on explicit runtime Stop,
+target replacement, timeout, abort and turn teardown. The browser frame's Stop
+closes its browser; its supervised server also closes when the runtime tool or
+turn closes. A person's Stop prevents reopening an interactive surface in that
+turn. Commands can run alongside an existing surface without replacing its
+owned server. Artifacts use the existing delivery/storage path.
+
+Command checks inherit the normal unattended build environment without the
+machine credential. Interactive apps/helpers start from the minimal toolchain
+environment plus scoped review-environment bindings. A target's optional `env`
+array selects additional variables by name, e.g. `["SANDBOX_API_KEY"]`; values
+stay local and scoped database bindings take precedence. Provider administrator
+credentials remain excluded. Personal/unlisted connectors and other external
+services keep their explicit configuration.
+
+### Linux virtual desktops
+
+The first native backend requires Xvfb, xauth, Openbox, xdotool and ImageMagick's
+`import` executable. On Debian/Ubuntu these are supplied by the `xvfb`, `xauth`,
+`openbox`, `xdotool` and `imagemagick` packages. Install them in the daemon's VM
+image; missing tools are reported on the target. The runner never installs them
+automatically or falls back to the user's display. Chrome headless itself does
+not need these desktop packages or a visible desktop session.
+
+The backend atomically allocates a private X display, disables its TCP listener
+and creates an owner-only Xauthority cookie. It starts a window manager without
+session autostart, then the declared app, waits for a visible client window and
+focuses it. The app has a fresh home/config/runtime directory and private X11
+display; inherited Wayland/WSLg and personal D-Bus sessions are not used. If an
+app needs D-Bus, use a repository-supported `dbus-run-session -- ...` command.
+Capture/input helpers receive only that display's authority. Handoff drains
+capture work before resuming public frames. Natural app exit ends the surface;
+crashes/timeouts report their actual failure. Teardown kills owned groups and
+removes the temporary home and authority files.
+
+The Linux backend runs behind the same stdio bridge used by other host helpers.
+It owns a separate process group and watches its parent pipe: a daemon killed
+without graceful shutdown closes that pipe and the helper reaps its native
+descendants. Normal bridge close first allows cleanup on EOF, with a bounded
+force-stop grace for a stalled helper.
+
+V1 supports left clicks, text, the shared bounded navigation keys and vertical
+scrolling at 1440×900. It does not yet provide drag, key holds, sound or native
+accessibility inspection. Apps needing Wayland-only APIs or GPU acceleration
+need an appropriate host/backend; an Xvfb image is not proof those capabilities
+exist. The session isolates display/cookies and avoids accidental personal
+desktop access, but still runs as the operator's UID. Use a dedicated VM/container
+for execution containment and scoped service credentials for data isolation.
+
+### Native and engine bridges
+
+A target with `adapter: "bridge"` uses the same UI and control ownership. Its
+`command` starts a reviewed host helper over private newline-delimited JSON-RPC
+2.0 stdio; `platforms` can restrict where it runs. `configuration` is a bounded
+object passed to the helper alongside the actual `worktree`. Repository helper
+paths spelled `./...` or `.flowviant/...` must match their reviewed base blobs;
+the helper launches from the checkout, with the target worktree in its scope.
+
+The protocol methods are `initialize`, `open`, `snapshot`, `act` and `privacy`.
+Initialize receives `{protocol:1, worktree, width:1440, height:900, configuration}`
+and returns `{protocol:1, isolation:"owned-session", privateHandoff:true}` or
+`isolation:"consented-window"`. It must bind that owned session or an explicitly
+consented window. Open receives `{epoch:0}`. Snapshot receives the current epoch
+and returns `{epoch,width:1440,height:900,data:"JPEG_BASE64",observation:"..."}`.
+Act receives `{epoch,input}` with the shared bounded input verbs. Frame
+notifications use method `frame` and params `{epoch,width,height,data}`. Frames
+are bounded to one million base64 characters; no debugging socket is exposed.
+An `ended` notification with the current epoch reports normal application exit;
+`failure` with `{epoch,message}` reports an actual backend error. Helpers must
+release their owned children when stdin closes and when terminated.
+Privacy receives `{private,epoch}` and must drain old captures before replying
+`{epoch,drained:true}`. The broker discards every old-epoch frame. Wrong ownership,
+missing private fences, malformed messages/images and timeouts close the helper.
+
+This contract is the extension point for Windows/macOS desktop capture and specialized engines;
+general Windows/macOS desktop capture helpers are not included in this release. Windows capture would
+use an explicitly selected window through Windows Graphics Capture; macOS would
+use ScreenCaptureKit and native input/accessibility permissions. Linux Wayland
+hosts would use their consented portal/PipeWire path. Roblox Studio requires a
+Windows or Mac host; Linux can still edit and check its filesystem sources.
+Engine-specific play/start/assert tools can use project MCP or command targets;
+declaring a bridge alone does not implement those engine semantics. The built-in
+Roblox adapter below uses Studio's own MCP rather than OS desktop capture.
+
+### Roblox Studio through Windows + WSL
+
+Use `adapter: "roblox"` for a Windows Studio fixture reached through a reviewed
+stdio launcher in WSL. Studio must already be installed, signed in, and have its
+built-in MCP server enabled. The daemon needs native Linux headless Chromium and
+`flock`; it creates no personal browser window or Windows daemon. No model service
+is added. [Roblox's MCP guide](https://create.roblox.com/docs/studio/mcp) describes
+the built-in server and its available tools.
+
+```json
+{
+  "version": 1,
+  "targets": {
+    "studio": {
+      "adapter": "roblox",
+      "command": ["./scripts/roblox-studio-mcp"],
+      "env": ["ROBLOX_STUDIO_MCP", "WSL_INTEROP", "WSL_DISTRO_NAME"],
+      "fixture": "Disposable local place with test services and worktree scripts",
+      "configuration": {
+        "studioName": "${WORKTREE}.rbxl",
+        "startPlay": true,
+        "scripts": [
+          {
+            "file": "src/server/Main.server.luau",
+            "path": ["ServerScriptService", "Main"]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Commit the executable launcher on the reviewed base. For an existing Windows
+StudioMCP executable, a small launcher can use the daemon's selected
+`ROBLOX_STUDIO_MCP` environment variable (a WSL `/mnt/c/.../StudioMCP.exe` path):
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+exec "${ROBLOX_STUDIO_MCP:?Set the installed StudioMCP.exe path on this machine}"
+```
+
+Reuse a working launcher if already configured. Keep stdin/stdout attached to the
+MCP process, without shell banners or `start`; do not launch Studio itself from
+this wrapper. The adapter validates the reviewed launcher bytes before running
+it from the checkout. Machine-specific paths stay in the selected environment.
+
+Build/sync a disposable place from the task worktree using the project's actual
+Rojo or Studio workflow, then open it in Windows Studio. `studioName` must equal
+the **exact name returned by `list_roblox_studios`**; `${WORKTREE}` expands to the
+task worktree's folder name. No first-instance or place-id fallback is used.
+In that fixture set the `FlowviantReviewWorktree` attribute on ReplicatedStorage
+to the same folder name, for example in Studio's Command Bar:
+
+```lua
+game:GetService("ReplicatedStorage"):SetAttribute("FlowviantReviewWorktree", "a-TASK-WORKTREE-ID")
+```
+
+The source mappings use worktree-relative Lua/Luau filenames and explicit Studio
+instance path segments. At most forty scripts, each at most 128 KiB, are compared
+before input or play starts; CRLF/LF differences are normalized. Missing,
+ambiguous, escaping or stale mappings and a wrong worktree marker refuse that
+review. Unmapped scripts, assets and other fixtures remain unverified. A marker
+is an explicit fixture binding, not a sandbox or proof of automatic Rojo sync.
+
+`run` requires an unambiguous Edit state before starting play and waits for a
+Client player/camera. A pre-existing play session is left alone; `startPlay:false`
+attaches to an already running fixture and never stops that session. A local OS
+lock prevents simultaneous turns using the same fixture name in that daemon
+environment. This does not coordinate other WSL distros or independent MCP clients.
+Owned play receives a temporary `FlowviantReviewSession` Client attribute; the
+adapter rechecks it before input and cleanup, leaving a replacement play session
+alone. This marker is runtime state, not a saved/published place edit.
+
+Viewport captures, click/text/navigation-key input, Take control and Return use
+the existing Live app frame. PNG/JPEG images are normalized in a network-disabled
+headless canvas, letterboxed to 1440×900, with click coordinates mapped to the
+measured player viewport. Mismatched aspect ratios are refused. The two-second
+capture cadence makes no model calls. Screenshots and input are observations;
+they do not assert gameplay passed. The first version uses the shared bounded
+input vocabulary, without WASD/key holds, mouse drag or full Studio editor control.
+
+Use privately fences old captures; console history is omitted after any private
+control. Studio's Windows login/MFA dialogs are outside the viewport and must be
+completed on the Windows host. Stop review leaves the Studio editor open. The
+helper watches parent EOF and on normal Stop, abort or daemon death attempts to
+stop only play it started, with bounded cleanup time before its processes are
+forced down. A disconnected/unresponsive MCP server can prevent that final stop;
+the editor and any remaining play session stay on the Windows host.
+
+Studio must already have disposable/namespaced DataStores and sandbox service
+bindings. Flowviant's database environment does not rewrite Roblox DataStore,
+Open Cloud, HTTP or game-universe configuration. This adapter does not install
+Studio, publish a place, upload assets, invoke Roblox's AI subagents, import
+personal auth or silently select a live game. Without Studio MCP, Lua changes
+still produce the usual code diff and configured command-check evidence.
+
 ## Modes
 
 | Env | What runs |

package/bin/cli.mjs

@@ -80,6 +80,12 @@
 // answered here before anything else loads: no config, no update check, no
 // output but the hook's. An unknown hook exits 2, which Claude Code reads as a
 // refusal — the read guard's own rule for a hook that cannot judge.
+if (process.argv[2] === '__environment') {
+  await (await import('./lib/reviewEnvironmentMain.mjs')).reviewEnvironmentMain();
+  await new Promise(resolve => process.stdout.write('', resolve));
+  process.exit(process.exitCode ?? 0);
+}
+
 if (process.argv[2] === '__capture-mcp') {
   await (await import('./lib/captureAuthority.mjs')).captureMcpMain();
   process.exit(process.exitCode ?? 0);
@@ -98,6 +104,23 @@ if (process.argv[2] === '__managed-browser-mcp') {
   process.exit(0);
 }
 
+if (['__runtime-review', '__runtime-review-mcp'].includes(process.argv[2])) {
+  await (await import('./lib/runtimeReview.mjs')).runtimeReviewMain(process.argv[2] === '__runtime-review-mcp');
+  await new Promise(resolve => process.stdout.write('', resolve));
+  process.exit(process.exitCode ?? 0);
+}
+
+if (process.argv[2] === '__linux-desktop-bridge') {
+  await (await import('./lib/linuxDesktopBridge.mjs')).linuxDesktopBridgeMain();
+  process.exit(process.exitCode ?? 0);
+}
+
+if (process.argv[2] === '__roblox-studio-bridge') {
+  await (await import('./lib/robloxStudioBridge.mjs')).robloxStudioBridgeMain();
+  await new Promise(resolve => process.stdout.write('', resolve));
+  process.exit(process.exitCode ?? 0);
+}
+
 if (process.argv[2] === '__video-render-mcp') {
   await (await import('./lib/videoRender.mjs')).videoRenderMain();
   process.exit(process.exitCode ?? 0);

package/bin/lib/browserHandoff.mjs

@@ -0,0 +1,25 @@
+/** A human browser handoff holds the existing turn, worktree and browser.
+ * No model process polls while the person signs in. A returned handoff resumes
+ * the same CLI conversation before final delivery/verification can settle. */
+export const BROWSER_HANDOFF_CONTINUATIONS = 2;
+
+export function browserHandoffPrompt({ reason }) {
+  return reason === 'returned'
+    ? 'A person returned control of the SAME managed browser session. Inspect its current page and verify whether sign-in or the requested interaction succeeded, then continue the existing card and its checks. Reuse the running dev server and browser; do not restart them. Report only actual observations and retained evidence.'
+    : `The managed browser handoff ${reason === 'expired' ? 'expired' : 'was stopped by a person'}. This browser is no longer interactive. Respect that stop; report the unfinished browser checks as unverified, complete any other available verification, and finish the existing card. Do not claim sign-in or interactive checks succeeded.`;
+}
+
+export async function completeBrowserReview(initial, { browser, signal, finish, resume }) {
+  let out = initial, finished = false, continuations = 0;
+  for (;;) {
+    if (signal?.aborted) return out;
+    const handoff = await browser?.waitForHandoff?.();
+    if (signal?.aborted || handoff?.reason === 'closed') return out;
+    if (handoff) {
+      if (continuations >= BROWSER_HANDOFF_CONTINUATIONS) throw new Error('The browser handoff continuation limit was reached. Interactive verification is incomplete.');
+      out = await resume(handoff, ++continuations);
+      finished = false;
+    } else if (finished) return out;
+    else { out = await finish(out); finished = true; }
+  }
+}

package/bin/lib/desktopContract.mjs

@@ -12,7 +12,7 @@ import { installChannel } from './launchCommand.mjs';
 import { boxesUrlFrom, classifyMachineResponse, fetchBoxesFor } from './machines.mjs';
 import { daemonLockPid, daemonLogPath, readDaemonState } from './daemonState.mjs';
 import { detectRuntimes } from './runtimeDetection.mjs';
-import { readClaudeAuthStatus } from './runtimeAuth.mjs';
+import { readClaudeAuthStatus, readCodexAuthStatus } from './runtimeAuth.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 
 /**
@@ -42,11 +42,13 @@ export function busyOf(liveState, now = Date.now()) {
 // One home for the channel (launchCommand.mjs); re-exported for views.mjs.
 export { installChannel };
 
-export function desktopStatus({ entries = listStoredProjects(), runtimes = detectRuntimes(), runningFor = daemonRunningFor, stateFor = readDaemonState, pidFor = daemonLockPid, drainFor = drainingFor, nowMs = Date.now(), authFor = readClaudeAuthStatus, refreshAuth = false } = {}) {
+export function desktopStatus({ entries = listStoredProjects(), runtimes = detectRuntimes(), runningFor = daemonRunningFor, stateFor = readDaemonState, pidFor = daemonLockPid, drainFor = drainingFor, nowMs = Date.now(), authFor = readClaudeAuthStatus, codexAuthFor = readCodexAuthStatus, refreshAuth = false } = {}) {
   const runtimeRows = runtimes.map((rt) => ({
     id: rt.id, installed: rt.installed, version: rt.version ?? null, dispatchable: rt.dispatchable,
-    ...(rt.id === 'claude' ? (rt.installed ? authFor({ refresh: refreshAuth }) : { signedIn: null, billing: null, subscriptionType: null }) :
-      { signedIn: null, billing: null, subscriptionType: null }),
+    authSource: 'local',
+    signedIn: null, billing: null, subscriptionType: null, checkedAt: null, expiresAt: null, expiryKind: null,
+    ...(rt.installed && rt.id === 'claude' ? authFor({ refresh: refreshAuth }) :
+      rt.installed && rt.id === 'codex' ? codexAuthFor({ refresh: refreshAuth }) : {}),
   }));
   return {
     schema: 1,
@@ -148,10 +150,10 @@ const refusalWords = (r) =>
 
 export async function desktopStatusRemote({ entries = listStoredProjects(), runtimes = detectRuntimes(),
   runningFor = daemonRunningFor, stateFor = readDaemonState, pidFor = daemonLockPid,
-  authFor = readClaudeAuthStatus, refreshAuth = false,
+  authFor = readClaudeAuthStatus, codexAuthFor = readCodexAuthStatus, refreshAuth = false,
   fetchImpl = fetch, envpub = readStoredPubB64(), fleetUrl = FLEET_URL, host = MACHINE_HOST,
   now = () => new Date().toISOString(), timeoutMs = REMOTE_TIMEOUT_MS, log = console.error } = {}) {
-  const status = desktopStatus({ entries, runtimes, runningFor, stateFor, pidFor, authFor, refreshAuth });
+  const status = desktopStatus({ entries, runtimes, runningFor, stateFor, pidFor, authFor, codexAuthFor, refreshAuth });
   const boxesUrl = boxesUrlFrom(fleetUrl);
   const liveUrl = fleetEndpoint('live-agents', fleetUrl);
   const remotes = await Promise.all(entries.map(async (entry) => {

package/bin/lib/environmentProcess.mjs

@@ -0,0 +1,44 @@
+/** Bounded, tracked setup children. Secrets travel in env/stdin, never argv. */
+import { spawn } from 'node:child_process';
+import { killGroup } from './processGroup.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { workLanesStopped } from './standDownGate.mjs';
+import { scrub } from './uplinkScrub.mjs';
+
+export function environmentCommand(argv, { cwd, env, input = '', signal, onSpawn = () => {}, onClose = () => {}, timeoutMs = 600_000, label = 'Environment command', captureOutput = true, includeDiagnostics = false } = {}) {
+  signal?.throwIfAborted();
+  if (workLanesStopped()) throw new Error('The daemon is stopping. Environment setup has not started.');
+  return new Promise((resolve, reject) => {
+    let child, timer, settled = false, output = '', diagnostics = '';
+    const diagnostic = chunk => { diagnostics = scrub(diagnostics + chunk.toString()).slice(-2000); };
+    const failed = message => new Error(message + (includeDiagnostics && diagnostics ? '\n' + diagnostics : ''));
+    const abort = () => { killGroup(child); finish(signal?.reason ?? new Error(`${label} was interrupted.`)); };
+    const finish = (error) => {
+      if (settled) return;
+      settled = true; clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      if (child) onClose(child);
+      error ? reject(error) : resolve(output);
+    };
+    try {
+      child = spawn(argv[0], argv.slice(1), { cwd, env: unattendedEnv({ ...env, GIT_TERMINAL_PROMPT: '0' }), detached: true, stdio: ['pipe', 'pipe', 'pipe'] });
+      child.once('error', () => finish(new Error(`${label} could not start (${argv[0]}). Check that it is installed.`)));
+      child.once('close', code => finish(code === 0 ? null : failed(`${label} failed (exit ${code ?? 'signal'}).`)));
+      // Provider operations leave diagnostics off: output can contain newly
+      // minted credentials even on failure. Runtime hooks retain scrubbed tails.
+      if (includeDiagnostics) child.stderr.on('data', diagnostic);
+      else child.stderr.resume();
+      child.stdout.on('data', chunk => {
+        if (!captureOutput) { if (includeDiagnostics) diagnostic(chunk); return; }
+        output += chunk;
+        if (Buffer.byteLength(output) > 256 * 1024) { killGroup(child); finish(new Error(`${label} returned too much output.`)); }
+      });
+      child.stdin.on('error', () => {});
+      child.stdin.end(input);
+      onSpawn(child);
+      timer = setTimeout(() => { killGroup(child); finish(failed(`${label} timed out.`)); }, timeoutMs);
+      signal?.addEventListener('abort', abort, { once: true });
+      if (signal?.aborted) abort();
+    } catch (error) { if (child) killGroup(child); finish(error); }
+  });
+}

package/bin/lib/fleet.mjs

@@ -276,6 +276,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     retirePreviews,
     shutdownPreviews,
     retireWorkSessions,
+    reconcileEnvironments,
     reportWorktrees,
     reconcileIdleArtifacts,
     reconcileLocalCleanup,
@@ -597,6 +598,7 @@ export async function runFleetDaemon({ afterLock = null } = {}) {
     // winner is working in — absence would mean "somebody else won" instead of
     // "the tab closed".
     retireWorkSessions(roster.activeWorkSessions, roster.sessionsHeldElsewhere);
+    reconcileEnvironments();
     // Diffs somebody has open and is waiting on. Project-scoped rather than
     // per-session: `git show` runs from the repo ROOT, which can see a closed
     // tab's branch and a shipped commit on main alike.

package/bin/lib/linuxDesktopBridge.mjs

@@ -0,0 +1,62 @@
+/** Linux host helper: parent EOF owns the lifetime of its whole process group. */
+import { createInterface } from 'node:readline';
+import { openBridgePage } from './reviewBridge.mjs';
+import { openDesktopPage } from './reviewDesktop.mjs';
+import { heldToolArgv } from './heldTool.mjs';
+import { killGroup } from './processGroup.mjs';
+import { procStat } from './procStat.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+
+export function openLinuxDesktop({ command, cwd, env, timeoutMs, signal, onChild, onFrame, onChange }) {
+  return openBridgePage({ command: [process.execPath, ...heldToolArgv('__linux-desktop-bridge')], cwd, env, worktree: cwd,
+    configuration: { command, cwd, timeoutMs }, timeoutMs, signal, onChild, onFrame, onChange });
+}
+
+export async function linuxDesktopBridgeMain() {
+  // Never group-kill a caller's terminal if somebody manually invokes this
+  // private verb. The parent starts the helper detached as its group leader.
+  if (process.platform !== 'linux' || procStat(process.pid)?.pgrp !== process.pid) throw new Error('The desktop helper needs its own Linux process group.');
+  const controller = new AbortController();
+  let page, configuration, epoch = 0, closing = false;
+  const send = value => { if (!closing) process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\n'); };
+  const shutdown = () => {
+    if (closing) return;
+    closing = true; controller.abort(); page?.close();
+    // All native descendants inherit this group; this also reaps descendants
+    // of an app launcher after a killed daemon closes the private stdin pipe.
+    setTimeout(() => killGroup(process.pid), 50);
+  };
+  process.stdin.once('end', shutdown); process.stdin.once('error', shutdown);
+  process.stdout.once('error', shutdown);
+  process.once('SIGTERM', shutdown); process.once('SIGINT', shutdown);
+  let bytes = 0;
+  try {
+    for await (const line of createInterface({ input: process.stdin })) {
+      if (closing) break;
+      let request;
+      try {
+        bytes = Buffer.byteLength(line); if (bytes > 128 * 1024) throw new Error('Desktop helper request exceeds its byte bound.');
+        request = JSON.parse(line);
+        const { id, method, params } = request;
+        let result = {};
+        if (method === 'initialize') {
+          configuration = params.configuration;
+          if (params.protocol !== 1 || !configuration || !Array.isArray(configuration.command) || configuration.cwd !== params.worktree) throw new Error('Invalid scoped desktop initialization.');
+          result = { protocol: 1, isolation: 'owned-session', privateHandoff: true };
+        } else if (method === 'open' && configuration && !page) {
+          page = await openDesktopPage({ ...configuration, env: process.env, signal: controller.signal, detachedChildren: false,
+            onFrame: frame => send({ method: 'frame', params: { ...frame, epoch } }),
+            onChange: patch => send({ method: patch.ended ? 'ended' : 'failure', params: { epoch, message: patch.error } }) });
+        } else if (method === 'snapshot' && page) result = { ...await page.snapshot(), width: 1440, height: 900, epoch };
+        else if (method === 'act' && page) await page.act(params.input);
+        else if (method === 'privacy' && page) { await page.setPrivate(params.private); epoch = params.epoch; result = { epoch, drained: true }; }
+        else throw new Error('Unsupported desktop helper operation.');
+        send({ id, result });
+      } catch (error) { send({ id: request?.id, error: { message: reviewDiagnostic(error.message) } }); }
+    }
+  } finally {
+    shutdown();
+    // Do not return to cli.mjs's process.exit before the group cleanup runs.
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+}