flowviant 0.125.29 → 0.125.30

package/bin/lib/managedBrowser.mjs

@@ -70,7 +70,7 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
   let lastRxAt = 0;
   let captures = 0;
   let observationEpoch = 0, pageEpoch = 0;
-  let pageOrigin = null, pageMeasured = null, statusPending = false, statusRetry = null;
+  let pageOrigin = null, pageMeasured = null, pageScope = null, statusPending = false, statusRetry = null;
   let handoff = null, handoffResult = null;
   let transportStarted = false;
   const controller = new AbortController();
@@ -88,7 +88,7 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
   };
   const change = patch => { status = { ...status, ...patch }; statusPending = true; flushStatus(); };
   const frame = message => { if (closed || stopped) return; lastFrame = message; flushStatus(); if (!statusPending) send(message); };
-  const release = () => { pageEpoch++; observationEpoch++; page?.close(); page = null; pageOrigin = null; pageMeasured = null; lastFrame = null; };
+  const release = () => { pageEpoch++; observationEpoch++; page?.close(); page = null; pageOrigin = null; pageMeasured = null; pageScope = null; lastFrame = null; };
   const endHandoff = reason => {
     if (!handoff) return;
     const active = handoff; handoff = null; clearTimeout(active.timer);
@@ -122,12 +122,15 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
     }
     return { content: [text({ page: shot.observation, diagnostics: shot.diagnostics, path: status.path, pendingOrigins: status.pendingOrigins, networkError: status.networkError, ...(artifact ? { artifact } : {}) }), { type: 'image', data: shot.data, mimeType: 'image/jpeg' }] };
   };
-  const call = async (name, input) => {
+  const requireModelControl = () => {
     if (closed || signal?.aborted) throw new Error('This browser turn has ended.');
     if (stopped) throw new Error('A person stopped the browser for this turn.');
     if (status.handoff && name !== 'handoff') throw new Error('The browser is waiting for a person. Continue other work or finish this invocation; the daemon will resume after the handoff.');
     if (status.mode === 'user') throw new Error('A person has control of the shared browser. Continue other work and retry after they return control.');
     if (busy) throw new Error('A browser action is already running.');
+  };
+  const call = async (name, input, scope = wt) => {
+    requireModelControl();
     busy = true;
     let openingNew = false;
     try {
@@ -141,22 +144,22 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
         const path = browserPath(input.path ?? '/');
         if (typeof input.fixture !== 'string' || input.fixture.trim().length < 12 || input.fixture.length > 2000) throw new Error('Describe the disposable test fixtures before opening the browser.');
         if (input.hostname != null && input.hostname !== 'localhost') throw new Error('The optional preview hostname must be localhost.');
-        const measured = measuredOrigin(wt, input.port, undefined, input.scheme);
+        const measured = measuredOrigin(scope, input.port, undefined, input.scheme);
         const upstreamUrl = new URL(measured);
         const connectHost = upstreamUrl.hostname === '[::1]' ? '::1' : upstreamUrl.hostname;
         if (input.hostname === 'localhost') upstreamUrl.hostname = 'localhost';
         const upstream = upstreamUrl.origin;
         if (!transportStarted) { transportStarted = true; openSocket(); }
-        if (!page || status.state !== 'live' || pageOrigin !== upstream || pageMeasured !== measured) {
+        if (!page || status.state !== 'live' || pageOrigin !== upstream || pageMeasured !== measured || pageScope !== scope) {
           openingNew = true;
-          release(); change({ state: 'starting', error: undefined, networkError: undefined, pendingOrigins: [], path });
+          release(); change({ state: 'starting', surface: 'browser', target: undefined, error: undefined, networkError: undefined, pendingOrigins: [], path });
           const opening = pageEpoch;
           page = await openPage({ origin: upstream, connectHost: input.hostname === 'localhost' ? connectHost : undefined, signal: controller.signal, stillOwned: () => {
-            try { return measuredOrigin(wt, input.port, undefined, input.scheme) === measured; } catch { return false; }
+            try { return measuredOrigin(scope, input.port, undefined, input.scheme) === measured; } catch { return false; }
           }, onFrame: message => { if (opening === pageEpoch) frame(message); },
             onChange: patch => { if (opening === pageEpoch && !closed && !stopped) change(patch.error ? { ...patch, state: 'error' } : patch); }, onChild });
           if (opening !== pageEpoch || closed || stopped) { page.close(); page = null; throw new Error('The browser turn has ended.'); }
-          pageOrigin = upstream; pageMeasured = measured;
+          pageOrigin = upstream; pageMeasured = measured; pageScope = scope;
         }
         await page.act({ type: 'navigate', path });
         change({ state: 'live' });
@@ -172,6 +175,39 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
       throw error;
     } finally { busy = false; }
   };
+  /** Runtime adapters share this transport, ownership and private handoff.
+   * The factory is daemon-owned; no raw desktop/debugging API crosses the relay. */
+  const openSurface = async ({ key, target, surface, open }) => {
+    requireModelControl();
+    if (!['desktop', 'engine'].includes(surface) || typeof key !== 'string' || key.length > 300 || !/^[A-Za-z0-9_-]{1,60}$/.test(target)) throw new Error('Invalid runtime surface.');
+    busy = true;
+    try {
+      if (!transportStarted) { transportStarted = true; openSocket(); }
+      if (!page || status.state !== 'live' || pageOrigin !== key) {
+        release(); change({ state: 'starting', surface, target, path: '/', error: undefined, networkError: undefined, pendingOrigins: [] });
+        const opening = pageEpoch;
+        const opened = await open({ signal: controller.signal, onChild,
+          onFrame: message => { if (opening === pageEpoch) frame(message); },
+          onChange: patch => {
+            if (opening !== pageEpoch || closed || stopped) return;
+            if (patch.ended) {
+              release(); change({ state: 'ended', mode: 'agent', private: false, handoff: undefined, error: undefined }); endHandoff('returned');
+            } else if (patch.error) change({ state: 'error', error: reviewDiagnostic(patch.error) });
+          } });
+        if (opening !== pageEpoch || closed || stopped) { opened.close(); throw new Error('The interactive turn has ended.'); }
+        page = opened; pageOrigin = key;
+        if (status.mode === 'user') beginHandoff();
+        if (status.private) await page.setPrivate(true);
+      }
+      change({ state: 'live' });
+      return await observe();
+    } catch (error) {
+      // Taking control while startup is finishing fences this model result;
+      // the newly opened app still belongs to the person holding the frame.
+      if (status.mode !== 'user') { release(); if (!closed && !stopped) change({ state: 'error', error: reviewDiagnostic(error.message) }); }
+      throw error;
+    } finally { busy = false; }
+  };
   const control = async msg => {
     if (msg.type !== 'control' || closed) return;
     if (msg.action === 'refresh') { if (msg.protocol === 2) status.protocol = 2; change({}); if (lastFrame) send(lastFrame); return; }
@@ -254,19 +290,23 @@ export async function createManagedBrowser({ wt, turnId, signal, onChild, openPa
         res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify(result));
       } catch (error) { res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify({ isError: true, content: [text(reviewDiagnostic(error.message))] })); }
     } });
-  learnExtraSecrets([held.capability]);
+  const secretKey = `browser:${held.capability.slice(0, 12)}`;
+  learnExtraSecrets(secretKey, [{ name: 'FLOWVIANT_BROWSER_CAPABILITY', value: held.capability }]);
   const close = async () => {
     if (closed) return;
     closed = true; signal?.removeEventListener('abort', abort);
     clearTimeout(reconnect); clearInterval(ping); clearTimeout(statusRetry); statusRetry = null; endHandoff('closed');
     controller.abort(); release(); change({ state: 'ended', mode: 'agent' });
     ws?.close(1000); held.server.close(); held.server.closeAllConnections();
-    forgetExtraSecrets([held.capability]);
+    forgetExtraSecrets(secretKey);
   };
   const abort = () => { void close(); };
   signal?.addEventListener('abort', abort, { once: true });
   if (signal?.aborted) await close();
   return { env: held.env, config: { command: process.execPath, args: held.args, env: held.env }, close,
+    open: (input, scope = wt) => call('open', input, scope), act: input => call('act', input), handoff: input => call('handoff', input), openSurface,
+    assertControl: requireModelControl,
+    stopSurface() { requireModelControl(); release(); change({ state: 'ended', mode: 'agent', private: false, handoff: undefined }); },
     async waitForHandoff() {
       for (;;) {
         const result = handoff ? await handoff.promise : handoffResult;

package/bin/lib/mergeBatch.mjs

@@ -65,7 +65,7 @@ export async function integrateMergeBatch({ spec, progress = {}, previousError,
   await report(states);
   for (const r of rows) {
     const stamp = resolve(r.wt, git(['rev-parse', '--git-path', 'flowviant-batch-setup'], r.wt));
-    if (!existsSync(stamp)) { await setup(r.repoRoot, r.wt); writeFileSync(stamp, 'ready'); }
+    if (!existsSync(stamp)) { await setup(r.repoRoot, r.wt, { baseRef: r.baseRef }); writeFileSync(stamp, 'ready'); }
   }
   const worktrees = rows.map((r) => ({ wt: r.wt, branch: r.branch, repoRoot: r.repoRoot }));
   if (spec.prMode && pr.ghReady()) throw new Error('This project merges through pull requests. GitHub CLI is not installed or signed in on this machine.');

package/bin/lib/noWindowEnv.mjs

@@ -67,8 +67,10 @@ export function withoutWindows(env, browserHome = null) {
 /**
  * EVERY CLI CHILD THE DAEMON SPAWNS UNATTENDED, ONE RULE (2026-10-10, the
  * audit): no machine credential (machineEnv.mjs), and no way to a window
- * unless a person at the keyboard asked for one (`display: true`, a Terminal
- * tab's alone). It was composed by hand twice — a turn's `cliEnv`
+ * unless a person at the keyboard asked for one (a Terminal tab), or the
+ * runtime-review daemon leaf supplied its own private X display/authority.
+ * `display: true` is never used to inherit a personal display on a code-agent
+ * CLI. It was composed by hand twice — a turn's `cliEnv`
  * (runTurn.mjs) and the project check's `checkEnv` (workAgentCheck.mjs) — and
  * skipped outright by the two spawns the daemon makes for its own purposes:
  * the startup skills probe (runtimeCapabilities.mjs), whose `claude` started

package/bin/lib/projectToolRuntimes.mjs

@@ -80,6 +80,7 @@ function codexServerTables(servers) {
   let out = '';
   for (const [name, server] of Object.entries(servers ?? {})) {
     out += `\n[mcp_servers.${name}]\n`;
+    if (Number.isInteger(server.toolTimeoutSec) && server.toolTimeoutSec > 0) out += `tool_timeout_sec = ${server.toolTimeoutSec}\n`;
     const approve = 'default_tools_approval_mode = "approve"\n';
     if (typeof server.command === 'string') {
       out += `command = ${toml(server.command)}\nargs = [${(server.args ?? []).map(toml).join(', ')}]\n${approve}`;
@@ -282,7 +283,8 @@ function reviewedClaudePlugin(dir, snapshot) {
  * turn)` returns the runner-specific part of prepareAgentTools' result — under
  * `dir`, which dies with the turn, except what `turn.codexHome` names a
  * lasting place for. `turn.mcpServers` is the base branch's servers this
- * runtime takes, expanded; `turn.fenced` a posture that reads no config file
+ * runtime takes, expanded; `turn.turnServers` retains daemon-owned metadata
+ * omitted from Claude's file; `turn.fenced` a posture that reads no config file
  * of the runner's own.
  */
 const TOOL_RUNTIMES = {
@@ -301,7 +303,7 @@ const TOOL_RUNTIMES = {
     // dies with the turn, as every home did before. A fenced turn ignores the
     // home's config.toml, so no server is written into it (2026-10-17).
     prepare: (dir, _snapshot, env, worktree, turn) => {
-      const isolated = isolatedCodexHome(turn?.codexHome ?? join(dir, 'codex-home'), env, worktree, turn?.fenced ? {} : turn?.mcpServers);
+      const isolated = isolatedCodexHome(turn?.codexHome ?? join(dir, 'codex-home'), env, worktree, turn?.fenced ? {} : { ...turn?.mcpServers, ...turn?.turnServers });
       return { codexHome: isolated.path, personalDeveloperInstructions: isolated.personalDeveloperInstructions, codexApprovals: turn?.fenced ? [] : isolated.approvals, codexMachineServers: turn?.fenced ? null : isolated.machineServers };
     },
     // A fenced posture ignores that home's config.toml (2026-10-10).

package/bin/lib/projectTools.mjs

@@ -220,7 +220,7 @@ export function prepareAgentTools(snapshot, runner, callerEnv = process.env, wor
     }
   }
   // Daemon-owned names cannot be replaced by project config. A turn server's
-  // `toolTimeoutSec` is the Codex mount's alone (codexFencedMount.mjs); it is
+  // `toolTimeoutSec` belongs to Codex's config.toml or fenced mount; it is
   // no key of Claude's mcp.json.
   for (const [name, { toolTimeoutSec: _codexOnly, ...config }] of Object.entries(turnServers)) mcpServers[name] = config;
   const mcpPath = join(dir, 'mcp.json');
@@ -238,7 +238,7 @@ export function prepareAgentTools(snapshot, runner, callerEnv = process.env, wor
   ].filter(Boolean).join('\n\n');
   let prepared;
   try {
-    prepared = prepareForRunner(runner, dir, snapshot, env, worktree, { codexHome: keptCodexHome, mcpServers, fenced });
+    prepared = prepareForRunner(runner, dir, snapshot, env, worktree, { codexHome: keptCodexHome, mcpServers, turnServers, fenced });
   } catch (error) {
     rmSync(dir, { recursive: true, force: true });
     throw error;

package/bin/lib/repositoryPlaces.mjs

@@ -137,7 +137,7 @@ export function createRepositoryPlaces({ repoRoot, baseDir, repositories, setup
       const repo = catalog.find((r) => r.id === item.id);
       if (!repo?.repoRoot) throw new Error(`Repository ${item.name} is not checked out on this machine.`);
       setupOptions.signal?.throwIfAborted();
-      await setup(repo.repoRoot, join(home, item.folder), setupOptions);
+      await setup(repo.repoRoot, join(home, item.folder), { ...setupOptions, baseRef: repo.baseRef });
       item.setup = true;
       save(home, state);
     }

package/bin/lib/repositorySetup.mjs

@@ -2,15 +2,25 @@
  * A checked-in .flowviant/setup.sh replaces the default dependency install. */
 import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { spawn } from 'node:child_process';
-import { killGroup } from './processGroup.mjs';
 import { git } from './git.mjs';
-import { unattendedEnv } from './noWindowEnv.mjs';
 import { workLanesStopped } from './standDownGate.mjs';
+import { environmentCommand } from './environmentProcess.mjs';
+import { readEnvironmentRecipe } from './reviewEnvironmentConfig.mjs';
+import { prepareWorktreeEnvironment } from './reviewEnvironment.mjs';
 
-export async function setupRepository(root, wt, { signal, onSpawn = () => {}, onClose = () => {} } = {}) {
+export async function setupRepository(root, wt, { signal, onSpawn = () => {}, onClose = () => {}, baseRef = 'HEAD', snapshot = readEnvironmentRecipe(root, baseRef) } = {}) {
   signal?.throwIfAborted();
   if (workLanesStopped()) throw new Error('The daemon is stopping. Repository setup has not started.');
+  const command = existsSync(join(wt, '.flowviant/setup.sh')) ? ['sh', '.flowviant/setup.sh'] :
+    ['bun.lock', 'bun.lockb'].some((f) => existsSync(join(wt, f))) ? ['bun', 'install', '--frozen-lockfile'] :
+    existsSync(join(wt, 'pnpm-lock.yaml')) ? ['pnpm', 'install', '--frozen-lockfile'] :
+    existsSync(join(wt, 'package-lock.json')) ? ['npm', 'ci'] :
+    existsSync(join(wt, 'yarn.lock')) ? ['yarn', 'install', '--frozen-lockfile'] : null;
+  const options = { signal, onSpawn, onClose };
+  // An explicit recipe replaces blind environment copying. Allocate first so
+  // even an install/setup hook receives the worktree's scoped database.
+  if (snapshot) return prepareWorktreeEnvironment(root, wt, { ...options, snapshot,
+    install: command ? env => environmentCommand(command, { ...options, cwd: wt, env, label: 'Repository setup', captureOutput: false, includeDiagnostics: true }) : null });
   const copyEnv = (relative = '') => {
     for (const name of readdirSync(join(root, relative))) {
       if (['.git', 'node_modules', '.flowviant', 'dist', 'target', '.next', '.cache', '.venv'].includes(name)) continue;
@@ -28,27 +38,8 @@ export async function setupRepository(root, wt, { signal, onSpawn = () => {}, on
     }
   };
   copyEnv();
-  const command = existsSync(join(wt, '.flowviant/setup.sh')) ? ['sh', '.flowviant/setup.sh'] :
-    ['bun.lock', 'bun.lockb'].some((f) => existsSync(join(wt, f))) ? ['bun', 'install', '--frozen-lockfile'] :
-    existsSync(join(wt, 'pnpm-lock.yaml')) ? ['pnpm', 'install', '--frozen-lockfile'] :
-    existsSync(join(wt, 'package-lock.json')) ? ['npm', 'ci'] :
-    existsSync(join(wt, 'yarn.lock')) ? ['yarn', 'install', '--frozen-lockfile'] : null;
   if (!command) return;
-  await new Promise((resolve, reject) => {
-    const child = spawn(command[0], command.slice(1), { cwd: wt, env: unattendedEnv({ ...process.env, GIT_TERMINAL_PROMPT: '0' }), detached: true, stdio: ['ignore', 'ignore', 'pipe'] });
-    const abort = () => killGroup(child);
-    signal?.addEventListener('abort', abort, { once: true });
-    if (signal?.aborted) abort();
-    onSpawn(child);
-    let tail = '';
-    child.stderr.on('data', (s) => { tail = (tail + s).slice(-2000); });
-    const timer = setTimeout(() => { killGroup(child); }, 10 * 60_000);
-    child.once('error', (e) => { clearTimeout(timer); reject(e); });
-    child.once('close', (code) => {
-      clearTimeout(timer); signal?.removeEventListener('abort', abort); onClose(child);
-      code === 0 ? resolve() : reject(new Error(`${command.join(' ')} failed in ${wt}: ${tail}`));
-    });
-  });
+  await environmentCommand(command, { ...options, cwd: wt, env: process.env, label: 'Repository setup', captureOutput: false, includeDiagnostics: true });
 }
 
 /** Installs are daemon children too: shutdown must drain their process groups. */

package/bin/lib/reviewBridge.mjs

@@ -0,0 +1,110 @@
+/** Native/engine helpers speak bounded JSON-RPC over a private stdio pipe. */
+import { startReviewProcess } from './reviewProcess.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+import { StringDecoder } from 'node:string_decoder';
+
+function image(value) {
+  if (!value || value.width !== 1440 || value.height !== 900 || typeof value.data !== 'string' || value.data.length > 1_000_000 || !/^[A-Za-z0-9+/]+={0,2}$/.test(value.data)) throw new Error('The runtime bridge returned an invalid bounded frame.');
+  const bytes = Buffer.from(value.data, 'base64');
+  if (bytes[0] !== 0xff || bytes[1] !== 0xd8) throw new Error('Runtime bridge frames must be JPEG images.');
+  return { type: 'frame', data: value.data, width: 1440, height: 900 };
+}
+
+export async function openBridgePage({ command, cwd, worktree, configuration = {}, env, signal, timeoutMs = 600_000, onChild, onFrame = () => {}, onChange = () => {}, requestTimeoutMs = 20_000, closeGraceMs = 500 }) {
+  signal?.throwIfAborted();
+  // Engine helpers may need to end their own play session over MCP before
+  // their child can be killed. Cancellation therefore closes the parent pipe.
+  const child = startReviewProcess(command, { cwd, env, onChild, timeoutMs: timeoutMs + closeGraceMs, stdio: ['pipe', 'pipe', 'pipe'], captureStdout: false });
+  const pending = new Map();
+  let serial = 0, epoch = 0, closed = false, ready = false, buffer = '', closeTimer, lifetime;
+  const decoder = new StringDecoder('utf8');
+  const close = (reason = new Error('The runtime bridge closed.')) => {
+    if (closed) return child.done;
+    closed = true;
+    clearTimeout(lifetime); signal?.removeEventListener('abort', abort);
+    for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(reason); }
+    pending.clear(); child.child.stdin.end();
+    // Let a well-behaved host helper release its session on parent-pipe EOF.
+    // A stalled helper still loses its owned group within a bounded grace.
+    closeTimer = setTimeout(() => { void child.close(); }, closeGraceMs); closeTimer.unref?.();
+    if (!child.running()) clearTimeout(closeTimer);
+    return child.done;
+  };
+  const exited = result => new Error(result.error ?? `The runtime bridge exited (${result.code}).`);
+  const abort = () => { void close(); };
+  const fail = error => { if (!closed) { onChange({ error: reviewDiagnostic(error.message) }); close(error); } };
+  lifetime = setTimeout(() => fail(new Error('The runtime bridge reached its time limit.')), timeoutMs); lifetime.unref?.();
+  signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort();
+  child.done.then(result => { clearTimeout(closeTimer); if (!closed) fail(exited(result)); });
+  child.child.stdout.on('data', bytes => {
+    if (closed) return;
+    buffer += decoder.write(bytes);
+    if (Buffer.byteLength(buffer) > 1_400_000) { fail(new Error('The runtime bridge exceeded its message bound.')); return; }
+    let newline;
+    while (!closed && (newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+      try {
+        const message = JSON.parse(line);
+        if (message.jsonrpc !== '2.0') throw new Error('The runtime bridge protocol is invalid.');
+        if (message.id != null) {
+          const entry = pending.get(message.id); if (!entry) continue;
+          pending.delete(message.id); clearTimeout(entry.timer);
+          if (message.error) entry.reject(new Error(reviewDiagnostic(message.error.message ?? 'Runtime bridge operation failed.')));
+          else entry.resolve(message.result);
+        } else if (ready && message.params?.epoch === epoch) {
+          if (message.method === 'frame') onFrame(image(message.params));
+          else if (message.method === 'ended') onChange({ ended: true });
+          else if (message.method === 'failure') fail(new Error(reviewDiagnostic(message.params.message)));
+        }
+      } catch (error) { fail(error); }
+    }
+  });
+  const request = (method, params) => {
+    if (closed) return Promise.reject(new Error('The runtime bridge is closed.'));
+    const id = ++serial;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { pending.delete(id); const error = new Error('The runtime bridge did not answer in time.'); reject(error); fail(error); }, requestTimeoutMs);
+      pending.set(id, { resolve, reject, timer });
+      child.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n', error => {
+        if (!error || closed) return;
+        // A fast launcher refusal (e.g. a held flock) can close stdin before
+        // Node observes its exit. Preserve that measured refusal over EPIPE.
+        void (async () => {
+          let timer;
+          try {
+            const result = await Promise.race([child.done, new Promise(resolve => { timer = setTimeout(() => resolve(null), 250); })]);
+            fail(result ? exited(result) : error);
+          } finally { clearTimeout(timer); }
+        })();
+      });
+    });
+  };
+  try {
+    const hello = await request('initialize', { protocol: 1, worktree, width: 1440, height: 900, configuration });
+    if (hello?.protocol !== 1 || !['owned-session', 'consented-window'].includes(hello.isolation) || hello.privateHandoff !== true) throw new Error('The bridge must bind an owned session or consented window and support private handoff fences.');
+    await request('open', { epoch }); ready = true;
+    return { kind: 'engine', pid: child.child.pid, close,
+      async setPrivate(privateInput) {
+        ready = false; const next = ++epoch;
+        const ack = await request('privacy', { private: privateInput, epoch: next });
+        if (ack?.epoch !== next || ack.drained !== true) { close(); throw new Error('The bridge did not acknowledge its private capture fence.'); }
+        ready = true;
+      },
+      async act(input) {
+        if (input.type === 'snapshot') return;
+        if (input.selector || ['navigate', 'retry'].includes(input.type)) throw new Error('Use this runtime’s coordinate input or engine tools; browser navigation is unavailable.');
+        await request('act', { input, epoch });
+      },
+      async snapshot() {
+        const current = epoch, shot = await request('snapshot', { epoch: current });
+        // A deliberate handoff invalidates this model observation, not the
+        // native session the person just took control of.
+        if (current !== epoch || !ready) throw new Error('Runtime control changed during capture.');
+        try {
+          if (shot?.epoch !== current) throw new Error('The runtime bridge returned a stale snapshot epoch.');
+          return { data: image(shot).data, observation: reviewDiagnostic(shot.observation ?? 'Native runtime observation.'), diagnostics: [] };
+        } catch (error) { fail(error); throw error; }
+      },
+    };
+  } catch (error) { close(); throw error; }
+}

package/bin/lib/reviewDatabase.mjs

@@ -0,0 +1,112 @@
+/** Database allocation is deterministic from a durable ownership receipt. */
+import { randomBytes } from 'node:crypto';
+import { environmentCommand } from './environmentProcess.mjs';
+import { reviewedProviderCommand } from './reviewEnvironmentConfig.mjs';
+
+const quote = value => `'${String(value).replaceAll("'", "''")}'`;
+const credentialNames = recipe => recipe.database.provider === 'postgres' ? [recipe.database.adminUrlEnv] : recipe.database.credentials ?? [];
+export { credentialNames as environmentCredentialNames };
+
+export function newDatabaseReceipt(id, provider) {
+  return provider === 'postgres' ? { provider, name: `fv_${id}`, role: `fv_${id}`, password: randomBytes(32).toString('hex') } : { provider, owner: id };
+}
+
+function postgresEnv(value) {
+  let url;
+  try { url = new URL(value); } catch { throw new Error('The review PostgreSQL admin URL is invalid.'); }
+  if (!['postgres:', 'postgresql:'].includes(url.protocol) || !url.hostname || !url.username || !url.pathname.slice(1) || url.hash) throw new Error('The review PostgreSQL admin URL must name a host, user and database.');
+  const env = { PGHOST: url.hostname.replace(/^\[|\]$/g, ''), PGPORT: url.port || '5432', PGUSER: decodeURIComponent(url.username), PGPASSWORD: decodeURIComponent(url.password), PGDATABASE: decodeURIComponent(url.pathname.slice(1)), PGCONNECT_TIMEOUT: '15' };
+  const options = { sslmode: 'PGSSLMODE', sslrootcert: 'PGSSLROOTCERT', sslcert: 'PGSSLCERT', sslkey: 'PGSSLKEY', channel_binding: 'PGCHANNELBINDING', connect_timeout: 'PGCONNECT_TIMEOUT', application_name: 'PGAPPNAME' };
+  for (const [key, v] of url.searchParams) {
+    if (!Object.hasOwn(options, key)) throw new Error(`Unsupported review PostgreSQL connection option: ${key}.`);
+    env[options[key]] = v;
+  }
+  return env;
+}
+
+const providerEnv = local => Object.fromEntries(['PATH', 'TMPDIR', 'LANG', 'LC_ALL', 'LD_LIBRARY_PATH', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'PGSYSCONFDIR'].filter(key => local[key] != null).map(key => [key, local[key]]));
+const pgCommand = async (sql, local, snapshot, options) => {
+  const admin = local[snapshot.recipe.database.adminUrlEnv];
+  if (!admin) throw new Error(`Set ${snapshot.recipe.database.adminUrlEnv} on this machine to provision review databases.`);
+  return environmentCommand(['psql', '-X', '-q', '-A', '-t', '-w', '-v', 'ON_ERROR_STOP=1'], { ...options, cwd: snapshot.root, timeoutMs: 30_000, label: 'Review PostgreSQL operation', env: { ...providerEnv(local), ...postgresEnv(admin) }, input: sql });
+};
+
+async function postgresState(record, local, snapshot, options) {
+  const db = record.database;
+  const answer = await pgCommand(`SELECT json_build_object(
+    'role', (SELECT json_build_object('marker', shobj_description(oid, 'pg_authid'), 'superuser', rolsuper, 'createdb', rolcreatedb, 'createrole', rolcreaterole, 'replication', rolreplication, 'bypassrls', rolbypassrls, 'login', rolcanlogin, 'memberships', EXISTS(SELECT 1 FROM pg_auth_members WHERE member = pg_roles.oid)) FROM pg_roles WHERE rolname = ${quote(db.role)}),
+    'database', (SELECT json_build_object('marker', shobj_description(oid, 'pg_database'), 'owner', pg_get_userbyid(datdba)) FROM pg_database WHERE datname = ${quote(db.name)}));`, local, snapshot, options);
+  try { return JSON.parse(answer); } catch { throw new Error('PostgreSQL did not return the review database ownership measurement.'); }
+}
+
+function ownedPostgres(state, record) {
+  const marker = `flowviant:${record.id}`;
+  const role = state.role;
+  if (role && (role.marker !== marker || role.superuser || role.createdb || role.createrole || role.replication || role.bypassrls || role.memberships || !role.login)) throw new Error('The review database role has unexpected ownership or privileges. It was left alone.');
+  if (state.database && (!role || state.database.owner !== record.database.role || (state.database.marker != null && state.database.marker !== marker))) throw new Error('The review database has unexpected ownership. It was left alone.');
+}
+
+async function allocatePostgres(record, local, snapshot, options) {
+  const db = record.database, marker = `flowviant:${record.id}`;
+  let state = await postgresState(record, local, snapshot, options);
+  ownedPostgres(state, record);
+  if (!state.role) {
+    await pgCommand(`BEGIN;
+      CREATE ROLE ${db.role} LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION NOBYPASSRLS PASSWORD ${quote(db.password)};
+      COMMENT ON ROLE ${db.role} IS ${quote(marker)};
+      COMMIT;`, local, snapshot, options);
+  }
+  if (!state.database) await pgCommand(`CREATE DATABASE ${db.name} WITH OWNER ${db.role} TEMPLATE template0;`, local, snapshot, options);
+  // Re-read after creation, also recovering a crash between CREATE DATABASE
+  // and COMMENT. Only a database owned by our marked, restricted role qualifies.
+  state = await postgresState(record, local, snapshot, options);
+  ownedPostgres(state, record);
+  if (!state.role || !state.database) throw new Error('The review database could not be measured after creation.');
+  await pgCommand(`COMMENT ON DATABASE ${db.name} IS ${quote(marker)};
+    REVOKE CONNECT ON DATABASE ${db.name} FROM PUBLIC;
+    GRANT CONNECT ON DATABASE ${db.name} TO ${db.role};`, local, snapshot, options);
+  const url = new URL(local[snapshot.recipe.database.adminUrlEnv]);
+  url.username = db.role; url.password = db.password; url.pathname = `/${db.name}`;
+  return { ...db, connectionString: url.toString() };
+}
+
+async function commandOperation(operation, record, local, snapshot, options) {
+  const credentials = {};
+  for (const name of credentialNames(snapshot.recipe)) {
+    if (!local[name]) throw new Error(`Set ${name} on this machine for the review database adapter.`);
+    credentials[name] = local[name];
+  }
+  const output = await environmentCommand([...reviewedProviderCommand(snapshot), operation], {
+    ...options, cwd: snapshot.root, timeoutMs: 120_000, label: `Review database ${operation}`,
+    env: { ...providerEnv(local), ...credentials,
+      FLOWVIANT_ENVIRONMENT_ID: record.id, FLOWVIANT_ENVIRONMENT_SOURCE: snapshot.recipe.database.source,
+      FLOWVIANT_ENVIRONMENT_RESOURCE_ID: record.database.resourceId ?? '',
+      FLOWVIANT_ENVIRONMENT_EXPIRES_AT: new Date(record.expiresAt).toISOString() },
+    input: JSON.stringify({ id: record.id, resourceId: record.database.resourceId ?? null, source: snapshot.recipe.database.source }),
+  });
+  let answer;
+  try { answer = JSON.parse(output); } catch { throw new Error(`The review database adapter must return JSON for ${operation}.`); }
+  if (answer?.owner !== record.id) throw new Error('The database adapter returned a different environment owner.');
+  return answer;
+}
+
+export async function allocateReviewDatabase(record, local, snapshot, options) {
+  if (record.database.provider === 'postgres') return allocatePostgres(record, local, snapshot, options);
+  const answer = await commandOperation('allocate', record, local, snapshot, options);
+  if (typeof answer.resourceId !== 'string' || !answer.resourceId || answer.resourceId.length > 200 || typeof answer.connectionString !== 'string' || !answer.connectionString || answer.connectionString.length > 16_384 || /[\0\r\n]/.test(answer.connectionString)) throw new Error('The database adapter must return a resourceId and connectionString.');
+  if (answer.bindings != null && (typeof answer.bindings !== 'object' || Array.isArray(answer.bindings) || Object.entries(answer.bindings).some(([key, value]) => !snapshot.recipe.database.bindings.includes(key) || typeof value !== 'string' || !value || value.length > 16_384 || /[\0\r\n]/.test(value)))) throw new Error('Database adapter bindings must name declared database variables with bounded connection strings.');
+  return { provider: 'command', owner: record.id, resourceId: answer.resourceId, connectionString: answer.connectionString, ...(answer.bindings ? { bindings: answer.bindings } : {}) };
+}
+
+export async function releaseReviewDatabase(record, local, snapshot, options) {
+  if (record.database.provider === 'command') {
+    // An interrupted allocation has no resource id. The adapter must reconcile
+    // by the original id, including create-success/response-lost crashes.
+    await commandOperation('release', record, local, snapshot, options);
+    return;
+  }
+  const state = await postgresState(record, local, snapshot, options);
+  ownedPostgres(state, record);
+  if (state.database) await pgCommand(`DROP DATABASE ${record.database.name} WITH (FORCE);`, local, snapshot, options);
+  if (state.role) await pgCommand(`DROP ROLE ${record.database.role};`, local, snapshot, options);
+}