flowviant 0.125.28 → 0.125.30

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

package/bin/lib/reviewEnvironment.mjs

@@ -0,0 +1,286 @@
+/** Durable per-worktree test environments, independent of the model/runner. */
+import { appendFileSync, chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { git } from './git.mjs';
+import { environmentCommand } from './environmentProcess.mjs';
+import { environmentHash, readEnvironmentLocal, readEnvironmentRecipe, repositoryPath, validateEnvironmentConnectors } from './reviewEnvironmentConfig.mjs';
+import { allocateReviewDatabase, environmentCredentialNames, newDatabaseReceipt, releaseReviewDatabase } from './reviewDatabase.mjs';
+import { learnExtraSecrets, forgetExtraSecrets } from './uplinkScrub.mjs';
+import { heldToolArgv } from './heldTool.mjs';
+import { workLanesStopped } from './standDownGate.mjs';
+
+const quiet = { stdio: ['ignore', 'pipe', 'ignore'] };
+const ID = /^[0-9a-f]{32}$/;
+function ownDirectory(path) {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  if (!lstatSync(path).isDirectory() || lstatSync(path).isSymbolicLink()) throw new Error('The local environment store must be a real directory.');
+  chmodSync(path, 0o700);
+  return path;
+}
+function storeFor(root) {
+  const common = realpathSync(resolve(root, git(['rev-parse', '--git-common-dir'], root, quiet)));
+  return ownDirectory(join(common, 'flowviant-environments'));
+}
+function pathsFor(root, wt) {
+  const store = storeFor(root);
+  if (storeFor(wt) !== store || realpathSync(root) === realpathSync(wt)) throw new Error('Review environments need a separate worktree of this repository.');
+  const marker = resolve(wt, git(['rev-parse', '--git-path', 'flowviant-environment'], wt, quiet));
+  const key = environmentHash(dirname(marker));
+  return { store, marker, lock: join(store, `${key}.lock`) };
+}
+const save = (path, value) => {
+  const temp = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+  writeFileSync(temp, JSON.stringify(value), { mode: 0o600, flag: 'wx' });
+  renameSync(temp, path);
+};
+const alive = pid => { try { process.kill(pid, 0); return true; } catch (e) { return e.code !== 'ESRCH'; } };
+async function locked(path, action) {
+  try { mkdirSync(path, { mode: 0o700 }); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    let owner;
+    try { owner = JSON.parse(readFileSync(join(path, 'owner'), 'utf8')); } catch { /* a creator may still be writing */ }
+    if ((owner && Number.isInteger(owner.pid) && owner.pid > 1 && !alive(owner.pid)) || (!owner && Date.now() - statSync(path).mtimeMs > 60_000)) rmSync(path, { recursive: true });
+    else throw new Error('This worktree environment is being prepared or cleaned up. Retry after that operation finishes.');
+    mkdirSync(path, { mode: 0o700 });
+  }
+  try { save(join(path, 'owner'), { pid: process.pid }); return await action(); }
+  finally { rmSync(path, { recursive: true, force: true }); }
+}
+function loadRecord(path, root) {
+  const record = JSON.parse(readFileSync(path, 'utf8'));
+  if (record.version !== 1 || !ID.test(record.id) || record.snapshot.root !== realpathSync(root) ||
+      !['postgres', 'command'].includes(record.database.provider) ||
+      (record.database.provider === 'postgres' && (record.database.name !== `fv_${record.id}` || record.database.role !== `fv_${record.id}`))) throw new Error('The local environment ownership receipt is invalid.');
+  return record;
+}
+function teach(record, local) {
+  const values = { ...record.env, password: record.database.password, connectionString: record.database.connectionString };
+  learnExtraSecrets(`environment:${record.id}:runtime`, Object.entries(values).filter(([, value]) => typeof value === 'string').map(([name, value]) => ({ name, value })));
+  const provider = environmentCredentialNames(record.snapshot.recipe).filter(name => typeof local[name] === 'string').map(name => ({ name, value: local[name] }));
+  // A later runtime-only read must not forget the administrator credential
+  // learned while provisioning (or a still-running provider's diagnostics).
+  if (provider.length) learnExtraSecrets(`environment:${record.id}:provider`, provider);
+}
+
+function runtimeBindings(record, local) {
+  const recipe = record.snapshot.recipe, credentials = new Set(environmentCredentialNames(recipe));
+  // Only explicitly selected local runtime values go into files/receipts.
+  let selected = {};
+  const file = repositoryPath(record.snapshot.root, '.flowviant/environment.local.json');
+  if (existsSync(file)) selected = JSON.parse(readFileSync(file, 'utf8')).env;
+  const env = { ...Object.fromEntries(Object.entries(recipe.env ?? {}).map(([key, value]) => [key, value.replaceAll('${ENVIRONMENT_ID}', record.id)])), ...selected };
+  for (const key of credentials) delete env[key];
+  for (const key of recipe.database.bindings) env[key] = record.database.bindings?.[key] ?? record.database.connectionString;
+  // Mask the administrative credential in inherited CLI/check environments.
+  // undefined removes it at spawn; no provider credential is given to hooks.
+  const childEnv = { ...local, ...env };
+  for (const key of credentials) childEnv[key] = undefined;
+  return { env, childEnv };
+}
+
+function envText(env) {
+  return Object.entries(env).map(([key, value]) => {
+    // Real quoted multiline values work in dotenv and Node's env-file reader.
+    // Complex values can always use the command wrapper with envFiles: [].
+    const quote = !value.includes("'") ? "'" : !value.includes('"') && !value.includes('\\') ? '"' : null;
+    if (!quote) throw new Error(`Cannot represent ${key} in a portable .env file. Use envFiles: [] and the environment command wrapper.`);
+    return `${key}=${quote}${value}${quote}`;
+  }).join('\n') + '\n';
+}
+function writeBindings(record, persist) {
+  if (!record.snapshot.recipe.envFiles.length) return;
+  const text = envText(record.env), hash = environmentHash(text);
+  record.files ??= {};
+  record.previousFiles ??= {}; record.pendingFiles ??= {};
+  // Reconcile a crash during a previous atomic replacement before starting
+  // another. Only receipt-owned bytes may be removed.
+  for (const [rel, expected] of Object.entries(record.pendingFiles)) {
+    const file = repositoryPath(record.wt, rel);
+    if (existsSync(file)) {
+      if (!lstatSync(file).isFile() || environmentHash(readFileSync(file)) !== expected) throw new Error('A pending generated environment file was edited. It was left alone.');
+      rmSync(file);
+    }
+    delete record.pendingFiles[rel];
+  }
+  persist();
+  for (const rel of record.snapshot.recipe.envFiles) {
+    const path = repositoryPath(record.wt, rel);
+    const tracked = git(['ls-files', '--', rel], record.wt, quiet);
+    if (tracked) throw new Error(`Generated environment file ${rel} is tracked. Choose an ignored path.`);
+    let current;
+    if (existsSync(path)) {
+      if (!lstatSync(path).isFile()) throw new Error(`Environment file ${rel} is not a regular file.`);
+      current = environmentHash(readFileSync(path));
+      if (current !== record.files[rel] && current !== record.previousFiles[rel]) throw new Error(`Environment file ${rel} already exists or was edited. Choose a different envFiles path; Flowviant will not overwrite it.`);
+      if (current === hash) { chmodSync(path, 0o600); delete record.previousFiles[rel]; persist(); continue; }
+    }
+    const tempRel = `${rel}.${randomBytes(8).toString('hex')}.flowviant-tmp`;
+    record.previousFiles[rel] = current;
+    record.files[rel] = hash; record.pendingFiles[tempRel] = hash; persist();
+    const exclude = resolve(record.wt, git(['rev-parse', '--git-path', 'info/exclude'], record.wt, quiet));
+    mkdirSync(dirname(exclude), { recursive: true });
+    const escaped = value => value.replace(/[\\ !#*?\[\]]/g, char => '\\' + char);
+    appendFileSync(exclude, `\n/${escaped(rel)}\n/${escaped(tempRel)}\n`);
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = repositoryPath(record.wt, tempRel);
+    writeFileSync(temp, text, { flag: 'wx', mode: 0o600 }); renameSync(temp, path);
+    delete record.pendingFiles[tempRel]; delete record.previousFiles[rel]; persist();
+  }
+}
+
+export function readWorktreeEnvironment(wt, callerEnv = process.env, { allowPending = false } = {}) {
+  const marker = resolve(wt, git(['rev-parse', '--git-path', 'flowviant-environment'], wt, quiet));
+  if (!existsSync(marker)) return null;
+  const id = readFileSync(marker, 'utf8').trim();
+  if (!ID.test(id)) throw new Error('The worktree environment marker is invalid.');
+  const store = storeFor(wt), path = join(store, `${id}.json`);
+  const raw = JSON.parse(readFileSync(path, 'utf8'));
+  const record = loadRecord(path, raw.snapshot.root);
+  if (record.wt !== realpathSync(wt) || record.marker !== marker || (!allowPending && record.phase !== 'ready')) throw new Error('This worktree environment is not ready.');
+  const env = { ...callerEnv, ...record.env };
+  for (const key of environmentCredentialNames(record.snapshot.recipe)) env[key] = undefined;
+  teach(record, record.env);
+  return { record, env, path, snapshot: record.snapshot };
+}
+
+/** The recipe and credentials come from the checkout; migrations/fixtures run
+ * against current worktree source. Hooks must be idempotent on partial failure. */
+export async function prepareWorktreeEnvironment(root, wt, { snapshot = readEnvironmentRecipe(root), install = null, env = process.env, now = Date.now, reseed = false, ...options } = {}) {
+  if (!snapshot) return null;
+  validateEnvironmentConnectors(snapshot);
+  wt = realpathSync(wt);
+  const paths = pathsFor(root, wt);
+  if (existsSync(paths.marker)) {
+    const previousId = readFileSync(paths.marker, 'utf8').trim();
+    if (!ID.test(previousId)) throw new Error('The worktree environment marker is invalid.');
+    const previous = loadRecord(join(paths.store, `${previousId}.json`), root);
+    // A reviewed recipe change deliberately rebuilds disposable data. Current
+    // turns retain their lease and cannot have their database replaced.
+    if (previous.snapshot.hash !== snapshot.hash) await releaseWorktreeEnvironment(root, previousId, { ...options, env, now });
+  }
+  return locked(paths.lock, async () => {
+    const local = readEnvironmentLocal(root, env);
+    let record;
+    if (existsSync(paths.marker)) {
+      const id = readFileSync(paths.marker, 'utf8').trim();
+      if (!ID.test(id)) throw new Error('The worktree environment marker is invalid.');
+      record = loadRecord(join(paths.store, `${id}.json`), root);
+      if (record.marker !== paths.marker) throw new Error('The environment belongs to another worktree.');
+      // git worktree move preserves its private git dir and marker. Its data
+      // lease follows that identity, rather than allocating another database.
+      record.wt = wt;
+      if (record.snapshot.hash !== snapshot.hash) throw new Error('The reviewed environment recipe changed during preparation. Retry.');
+    } else {
+      const id = randomBytes(16).toString('hex');
+      record = { version: 1, id, wt, marker: paths.marker, lock: paths.lock, snapshot, phase: 'allocating', createdAt: now(), expiresAt: now() + snapshot.recipe.ttlHours * 3_600_000, database: newDatabaseReceipt(id, snapshot.recipe.database.provider), files: {} };
+      // Intent precedes every provider call; its id survives timeouts/restarts.
+      save(join(paths.store, `${id}.json`), record);
+      writeFileSync(paths.marker, id, { flag: 'wx', mode: 0o600 });
+    }
+    const path = join(paths.store, `${record.id}.json`);
+    const persist = () => save(path, record);
+    record.expiresAt = now() + snapshot.recipe.ttlHours * 3_600_000;
+    record.phase = 'allocating'; persist(); teach(record, local);
+    record.database = await allocateReviewDatabase(record, local, snapshot, options);
+    const bindings = runtimeBindings(record, local);
+    record.env = bindings.env;
+    persist(); teach(record, local);
+    writeBindings(record, persist);
+    if (!record.installed) {
+      record.phase = 'installing'; persist();
+      if (install) await install(bindings.childEnv);
+      record.installed = true; persist();
+    }
+    record.phase = 'migrating'; persist();
+    await environmentCommand(snapshot.recipe.migrate, { ...options, cwd: wt, env: bindings.childEnv, label: 'Review database migration', captureOutput: false, includeDiagnostics: true });
+    record.migrationHead = git(['rev-parse', 'HEAD'], wt, quiet);
+    if (!record.seeded || reseed) {
+      record.phase = 'seeding'; record.seeded = false; persist();
+      await environmentCommand(snapshot.recipe.seed, { ...options, cwd: wt, env: bindings.childEnv, label: 'Review database fixtures', captureOutput: false, includeDiagnostics: true });
+      record.seeded = true;
+    }
+    record.phase = 'ready'; persist();
+    return readWorktreeEnvironment(wt, env);
+  });
+}
+
+/** Held through CLI continuations and final checks. The heartbeat expires
+ * after a crashed daemon, rather than preserving a resource forever by pid. */
+export function holdWorktreeEnvironment(environment) {
+  const { record, path } = environment;
+  const lease = `${path}.${randomBytes(8).toString('hex')}.active`;
+  const beat = () => save(lease, { pid: process.pid, at: Date.now() });
+  beat(); const timer = setInterval(() => { try { beat(); } catch { /* a removed store must not crash the daemon */ } }, 30_000); timer.unref?.();
+  return () => { clearInterval(timer); rmSync(lease, { force: true }); };
+}
+function activeEnvironment(store, id, now) {
+  return readdirSync(store).some(file => {
+    if (!file.startsWith(`${id}.json.`) || !file.endsWith('.active')) return false;
+    try { const lease = JSON.parse(readFileSync(join(store, file), 'utf8')); return now - lease.at < 90_000 && Number.isInteger(lease.pid) && lease.pid > 1 && alive(lease.pid); }
+    catch { return true; } // unknown ownership cannot justify deletion
+  });
+}
+
+function registeredEnvironmentWorktree(record) {
+  try {
+    // git updates this backlink on worktree move. Reading the two tiny files
+    // avoids a git process for every retained environment on every sweep.
+    const gitfile = readFileSync(join(dirname(record.marker), 'gitdir'), 'utf8').trim();
+    if (!lstatSync(gitfile).isFile() || lstatSync(gitfile).isSymbolicLink()) return null;
+    const wt = dirname(gitfile), link = readFileSync(gitfile, 'utf8').trim();
+    if (!link.startsWith('gitdir: ')) return null;
+    return join(resolve(wt, link.slice(8)), 'flowviant-environment') === record.marker ? wt : null;
+  } catch { return null; }
+}
+
+export async function releaseWorktreeEnvironment(root, id, { now = Date.now, ...options } = {}) {
+  if (!ID.test(id)) throw new Error('Invalid environment id.');
+  const store = storeFor(root), path = join(store, `${id}.json`);
+  const record = loadRecord(path, root);
+  return locked(record.lock, async () => {
+    if (activeEnvironment(store, id, now())) throw new Error('This environment is in use by a live turn.');
+    record.wt = registeredEnvironmentWorktree(record) ?? record.wt;
+    const local = readEnvironmentLocal(root, options.env ?? process.env);
+    teach(record, local);
+    await releaseReviewDatabase(record, local, record.snapshot, options);
+    for (const [rel, hash] of Object.entries({ ...record.files, ...record.pendingFiles })) {
+      const file = repositoryPath(record.wt, rel);
+      if (existsSync(file) && lstatSync(file).isFile() && [hash, record.previousFiles?.[rel]].includes(environmentHash(readFileSync(file)))) rmSync(file);
+    }
+    if (existsSync(record.marker) && readFileSync(record.marker, 'utf8').trim() === id) rmSync(record.marker);
+    for (const file of readdirSync(store)) if (file.startsWith(`${id}.json.`) && file.endsWith('.active')) rmSync(join(store, file));
+    rmSync(path); forgetExtraSecrets(`environment:${id}:runtime`); forgetExtraSecrets(`environment:${id}:provider`);
+  });
+}
+
+/** Bounded reconciliation retains receipts after provider/ownership failures.
+ * No database is selected for deletion by its name alone. */
+export async function sweepWorktreeEnvironments(root, { now = Date.now, limit = 2, ...options } = {}) {
+  const store = storeFor(root), result = { released: [], errors: [] };
+  for (const file of readdirSync(store).filter(file => /^[0-9a-f]{32}\.json$/.test(file))) {
+    if (workLanesStopped() || result.released.length + result.errors.length >= limit) break;
+    try {
+      const record = loadRecord(join(store, file), root);
+      if (activeEnvironment(store, record.id, now())) continue;
+      const present = existsSync(record.marker) && readFileSync(record.marker, 'utf8').trim() === record.id && registeredEnvironmentWorktree(record) !== null;
+      if (present && record.expiresAt > now()) continue;
+      await releaseWorktreeEnvironment(root, record.id, { ...options, now });
+      result.released.push(record.id);
+    } catch (error) { result.errors.push({ id: file.slice(0, 32), error: error.message }); }
+  }
+  return result;
+}
+
+export function environmentInstructions(environment) {
+  const { record } = environment;
+  // Exact argv is represented as JSON for the agent to shell-quote, with no
+  // connection string, credential, or model-invented setup step in the prompt.
+  const argv = [process.execPath, ...heldToolArgv('__environment'), record.wt];
+  return `Flowviant prepared disposable environment ${record.id} (${record.database.provider}) for ${record.wt}. Its migrations completed and fixtures were seeded; these are setup facts, not passing application tests. Run app/test commands through this argv prefix, appending ["run", "--", ...commandArgv]: ${JSON.stringify(argv)}. This selects this repository's scoped values even in a multi-repository place. After editing migrations, use the same prefix with ["refresh"] before testing. After editing fixtures, use ["refresh", "--seed"] to rerun the retry-safe seeder. Ordinary refresh retries incomplete seeding, but never resets successfully seeded data. Generated files: ${record.snapshot.recipe.envFiles.join(', ') || 'none'}. The configured project MCP connectors expand the same database bindings. Personal/unlisted connectors and external services are not isolated by this database. Use test identities and sandbox or namespaced services. Never copy shared dev/prod database credentials into this worktree.`;
+}
+
+export function environmentOverlay(environment) {
+  return { ...environment.record.env, ...Object.fromEntries(environmentCredentialNames(environment.snapshot.recipe).map(key => [key, undefined])) };
+}