flowviant 0.125.29 → 0.125.31

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/prompts.mjs

@@ -1,3 +1,4 @@
+import { CONVERSATION_OUTPUT } from './conversationOutput.mjs';
 import { TESTS_SCOPE, TESTS_REPORT } from './testFindingsContract.mjs';
 import { randomBytes } from 'node:crypto';
 import { REGRESSION_INVESTIGATION } from './discoveryContract.mjs';
@@ -28,13 +29,14 @@ import { ARTIFACT_CONTRACT_TAIL, HELP_THEM_DECIDE, LOOK_HEADLESS, SYSTEM_AGENT_D
 import { isLibraryReference } from './knowledgeLibrary.mjs';
 import { readCardThread } from './cardThread.mjs';
 import { AGENT_FILE_LINE_MAX, AGENT_FILES_PER_MESSAGE_MAX, CARD_FILES_PER_TURN_MAX } from './agentFiles.mjs';
+import { SYSTEM_ARCHITECTURE_CONTRACT } from './architectureContract.mjs';
 
 // Wiki-gen turn: the local Claude READS the repo (cwd) and writes/maintains the
 // knowledge VAULT — a plain directory of markdown files with [[wikilinks]]
 // (Obsidian-style). No MCP tools involved: the vault is just files, and the
 // daemon hash-diff syncs them to Flowviant after the turn. The repo itself is
 // strictly read-only.
-const WIKI_MAINTENANCE = `
+const WIKI_MAINTENANCE = `${SYSTEM_ARCHITECTURE_CONTRACT}
 OWNERSHIP AND PROVENANCE — this directory is a disposable draft of GENERATED
 output, separate from project Knowledge, uploaded/reference vault snapshots and
 human standing Instructions. Never write to any original source. In this draft,
@@ -2037,12 +2039,12 @@ XHR, sockets, forms and popups are all closed. Never commit these files.`;
 /**
  * The system prompt a turn actually runs under: the contract it picked, plus
  * whatever project context this box holds. `knowledgeDir` null or absent and
- * `artifacts` false leave the contract byte-for-byte what it was, which is what
- * every turn did before either existed — and what an older server still gets.
- * Knowledge first, artifacts after: what to READ, then where to WRITE.
+ * `artifacts` false omit their paragraphs. The shared conversation output guide
+ * always follows the base contract. Knowledge then says what to READ, and the
+ * artifact paragraph says where to WRITE when that surface accepts files.
  */
 export const withProjectContext = (system, { knowledgeDir, artifacts = false } = {}) => {
-  let out = system;
+  let out = `${system}\n\n${CONVERSATION_OUTPUT}`;
   if (knowledgeDir) out = `${out}\n\n${KNOWLEDGE_PARAGRAPH(knowledgeDir)}`;
   if (artifacts) out = `${out}\n\n${ARTIFACTS_PARAGRAPH}`;
   return out;

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);
+}

package/bin/lib/reviewDesktop.mjs

@@ -0,0 +1,153 @@
+/** Linux native apps on an owned X server. Never attach to DISPLAY/WSLg. */
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir, platform } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { commandOnPath } from './reviewTargets.mjs';
+import { startReviewProcess } from './reviewProcess.mjs';
+import { learnExtraSecrets, forgetExtraSecrets } from './uplinkScrub.mjs';
+
+export function desktopSupport(env = process.env) {
+  if (platform() !== 'linux') return { available: false, reason: 'The built-in isolated desktop needs Linux. Configure a native host bridge on this OS.' };
+  const tools = Object.fromEntries(['Xvfb', 'xauth', 'openbox', 'xdotool', 'import'].map(name => [name, commandOnPath(name, env)]));
+  const missing = Object.keys(tools).filter(name => !tools[name]);
+  return missing.length ? { available: false, reason: `Isolated desktop tools missing: ${missing.join(', ')}.` } : { available: true, tools };
+}
+
+export async function openDesktopPage({ command, cwd, env, timeoutMs = 600_000, signal, onChild, onFrame = () => {}, onChange = () => {}, support = desktopSupport(env), frameIntervalMs = 750, detachedChildren = true }) {
+  if (!support.available) throw new Error(support.reason);
+  signal?.throwIfAborted();
+  const scratch = mkdtempSync(join(tmpdir(), 'flowviant-desktop-'));
+  const authority = join(scratch, 'Xauthority');
+  const cookie = randomBytes(16).toString('hex'), secretKey = `desktop:${cookie}`;
+  learnExtraSecrets(secretKey, [{ name: 'XAUTHORITY_COOKIE', value: cookie }]);
+  writeFileSync(authority, '', { mode: 0o600 });
+  const runtime = join(scratch, 'run'); mkdirSync(runtime, { mode: 0o700 });
+  const tools = support.tools;
+  const privateEnv = { ...env, HOME: scratch, USERPROFILE: scratch, XDG_CONFIG_HOME: scratch, XDG_DATA_HOME: scratch,
+    XDG_CACHE_HOME: scratch, XDG_RUNTIME_DIR: runtime, XAUTHORITY: authority,
+    WAYLAND_DISPLAY: '', WAYLAND_SOCKET: undefined, DBUS_SESSION_BUS_ADDRESS: 'disabled:', BROWSER: 'none',
+    XDG_SESSION_TYPE: 'x11', GDK_BACKEND: 'x11', QT_QPA_PLATFORM: 'xcb', SDL_VIDEODRIVER: 'x11' };
+  let xserver, manager, app, display, timer, failure, closed = false, seenImage = false, privateUsed = false, epoch = 0, queue = Promise.resolve();
+  const controller = new AbortController();
+  const abort = () => close();
+  const processes = new Set();
+  const options = { cwd, env: privateEnv, signal: controller.signal, onChild, detached: detachedChildren };
+  const exec = async (argv, extra = {}) => {
+    const process = startReviewProcess(argv, { ...options, timeoutMs: 5000, ...extra });
+    processes.add(process);
+    try {
+      const result = await process.done;
+      if (result.error || result.code !== 0) throw failure ?? new Error(result.error ?? `The isolated desktop operation failed (${result.code}). ${privateUsed ? '' : result.output.slice(-800)}`);
+      return result;
+    } finally { processes.delete(process); }
+  };
+  function close() {
+    if (closed) return;
+    closed = true; epoch++; clearTimeout(timer); signal?.removeEventListener('abort', abort); controller.abort();
+    const children = [app, manager, xserver, ...processes].filter(Boolean);
+    void Promise.all(children.map(child => child.close())).finally(() => {
+      // A process may still have Xauthority or its runtime files open until exit.
+      try { rmSync(scratch, { recursive: true, force: true }); } catch { /* a failed local unlink must not crash the daemon */ }
+      forgetExtraSecrets(secretKey);
+    });
+  }
+  const fail = error => { if (!closed) { failure = error; onChange({ error: error.message }); close(); } };
+  const captured = () => {
+    const run = queue.catch(() => {}).then(async () => {
+      if (closed) throw new Error('The isolated desktop has ended.');
+      const { data } = await exec([tools.import, '-display', display, '-window', 'root', '-quality', '65', 'jpeg:-'], { display: true, binary: true, maxBytes: 750_000 });
+      if (data[0] !== 0xff || data[1] !== 0xd8) throw new Error('The desktop capture did not return a JPEG.');
+      return data.toString('base64');
+    });
+    queue = run; return run;
+  };
+  const stream = async () => {
+    const current = epoch;
+    try { const data = await captured(); if (!closed && current === epoch) onFrame({ type: 'frame', data, width: 1440, height: 900 }); }
+    catch (error) { if (!closed && current === epoch) fail(error); }
+    finally { if (!closed && current === epoch) timer = setTimeout(stream, frameIntervalMs); }
+  };
+  signal?.addEventListener('abort', abort, { once: true });
+  try {
+    // The X server reads this cookie independent of the display number. Once
+    // -displayfd allocates a free display atomically, add the client's entry.
+    await exec([tools.xauth, '-f', authority, 'source', '-'], { input: `add :0 MIT-MAGIC-COOKIE-1 ${cookie}\n` });
+    xserver = startReviewProcess([tools.Xvfb, '-displayfd', '3', '-screen', '0', '1440x900x24', '-nolisten', 'tcp', '-auth', authority], {
+      ...options, timeoutMs, stdio: ['ignore', 'pipe', 'pipe', 'pipe'],
+    });
+    display = await new Promise((resolve, reject) => {
+      let text = '';
+      const deadline = setTimeout(() => reject(new Error('The private X server did not start.')), 5000);
+      const finish = (error, value) => { clearTimeout(deadline); error ? reject(error) : resolve(value); };
+      xserver.child.stdio[3].on('data', bytes => {
+        text += bytes.toString();
+        if (text.length > 20) finish(new Error('The X server returned an invalid display.'));
+        else if (/^\d+\n$/.test(text)) finish(null, `:${Number(text.trim())}`);
+      });
+      xserver.done.then(result => finish(new Error(result.error ?? `The private X server exited. ${result.output.slice(-1500)}`)));
+    });
+    privateEnv.DISPLAY = display;
+    await exec([tools.xauth, '-f', authority, 'source', '-'], { input: `add ${display} MIT-MAGIC-COOKIE-1 ${cookie}\n` });
+    if (closed || signal?.aborted) throw new Error('The desktop turn has ended.');
+    // Start only the window manager, never a desktop session's autostart apps.
+    // It provides normal click-to-focus and window behavior on the private X server.
+    manager = startReviewProcess([tools.openbox, '--sm-disable'], { ...options, env: privateEnv, display: true, timeoutMs });
+    manager.done.then(result => { if (!closed) fail(new Error(result.error ?? `The private window manager exited (${result.code}). ${!seenImage && !privateUsed ? result.output.slice(-1000) : ''}`)); });
+    app = startReviewProcess(command, { ...options, env: privateEnv, display: true, timeoutMs });
+    app.done.then(result => {
+      if (closed) return;
+      if (result.code === 0 && !result.error && seenImage) { onChange({ ended: true }); close(); }
+      else fail(new Error(result.error ?? `The desktop app exited (${result.code}). ${!seenImage && !privateUsed ? result.output.slice(-1000) : ''}`));
+    });
+    xserver.done.then(result => { if (!closed) fail(new Error(result.error ?? 'The private X server exited.')); });
+    // A live X server alone is not an application preview. Wait for a mapped
+    // client window in this owned display and give it ordinary keyboard focus.
+    let window, startupError;
+    const startupUntil = Date.now() + 10_000;
+    while (Date.now() < startupUntil && !closed) {
+      try {
+        const result = await exec([tools.xdotool, 'search', '--onlyvisible', '--class', '.'], { display: true });
+        window = result.output.split(/\s+/).find(value => /^\d+$/.test(value));
+        if (window) {
+          await exec([tools.xdotool, 'windowactivate', '--sync', window], { display: true, timeoutMs: 1000 });
+          // _NET_ACTIVE_WINDOW can arrive before the window manager sets X
+          // input focus. Do not accept the first key into that startup gap.
+          await exec([tools.xdotool, 'windowfocus', '--sync', window], { display: true, timeoutMs: 1000 });
+          break;
+        }
+      } catch (error) { startupError = error; window = null; if (closed) break; }
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    if (!window || closed) throw failure ?? new Error(`No visible application window opened in the private desktop.${startupError ? ` ${startupError.message}` : ''}`);
+    timer = setTimeout(stream, frameIntervalMs);
+    return { kind: 'desktop', display, pid: app.child.pid, displayPid: xserver.child.pid, managerPid: manager.child.pid, close,
+      async setPrivate(privateInput) {
+        if (privateInput) privateUsed = true;
+        epoch++; clearTimeout(timer);
+        // Discard captures already queued before the handoff. A fresh capture
+        // begins after the drain and cannot carry a prior private frame.
+        await queue.catch(() => {});
+        if (!closed) timer = setTimeout(stream, frameIntervalMs);
+      },
+      async snapshot() {
+        const current = epoch;
+        const data = await captured();
+        if (current !== epoch || closed) throw new Error('Desktop control changed during capture.');
+        seenImage = true;
+        return { data, observation: 'Isolated native application. Use screen coordinates; DOM selectors are unavailable. A screenshot is an observation, not a passing gameplay or integration test.', diagnostics: [] };
+      },
+      async act(input) {
+        if (closed) throw new Error('The isolated desktop has ended.');
+        if (input.type === 'snapshot') return;
+        if (input.selector || ['navigate', 'retry'].includes(input.type)) throw new Error('This native desktop supports coordinate input; browser navigation and DOM selectors do not apply.');
+        if (input.type === 'click') await exec([tools.xdotool, 'mousemove', String(input.x), String(input.y), 'click', '1'], { display: true });
+        else if (input.type === 'type') await exec([tools.xdotool, 'type', '--clearmodifiers', '--delay', '0', '--file', '-'], { display: true, input: input.text });
+        else if (input.type === 'key') await exec([tools.xdotool, 'key', '--clearmodifiers', ({ Enter: 'Return', Backspace: 'BackSpace', ArrowUp: 'Up', ArrowDown: 'Down', ArrowLeft: 'Left', ArrowRight: 'Right' })[input.key] ?? input.key], { display: true });
+        else if (input.type === 'scroll' && input.deltaY !== 0) await exec([tools.xdotool, 'click', '--repeat', String(Math.max(1, Math.min(10, Math.ceil(Math.abs(input.deltaY) / 100)))), '--delay', '20', input.deltaY < 0 ? '4' : '5'], { display: true });
+        else if (input.type === 'scroll') return;
+        else throw new Error('Unsupported native input.');
+      },
+    };
+  } catch (error) { close(); throw error; }
+}