flowviant 0.125.29 → 0.125.31

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

package/bin/lib/reviewEnvironmentConfig.mjs

@@ -0,0 +1,104 @@
+/** Reviewed recipes plus machine-local bindings; never a cloud secret vault. */
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { git } from './git.mjs';
+
+export const ENVIRONMENT_RECIPE = '.flowviant/environment.json';
+export const ENVIRONMENT_LOCAL = '.flowviant/environment.local.json';
+export const environmentHash = value => createHash('sha256').update(value).digest('hex');
+const KEY = /^[A-Za-z_][A-Za-z0-9_]{0,99}$/;
+export const environmentKey = key => KEY.test(key) && !key.startsWith('FLOWVIANT_') && !['HOME', 'PATH', 'CODEX_HOME', 'NODE_OPTIONS', 'LD_PRELOAD'].includes(key);
+const command = value => Array.isArray(value) && value.length > 0 && value.length <= 32 && value.every(v => typeof v === 'string' && v.length > 0 && v.length <= 2000 && !/[\0\r\n]/.test(v));
+const strings = (value, max = 40) => Array.isArray(value) && value.length <= max && value.every(v => typeof v === 'string');
+
+export function repositoryPath(root, path) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || path.includes('\\') || path.split('/').some(p => !p || p === '.' || p === '..') || /[\0\r\n]/.test(path)) throw new Error('Environment paths must be relative repository paths.');
+  const dest = resolve(root, path);
+  // Refuse links in any existing parent, including a linked .flowviant.
+  let current = resolve(root);
+  for (const part of path.split('/')) {
+    current = resolve(current, part);
+    try { if (lstatSync(current).isSymbolicLink()) throw new Error('Environment paths cannot contain symbolic links.'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return dest;
+}
+
+export function readEnvironmentRecipe(root, ref = 'HEAD') {
+  const options = { stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 };
+  let commit;
+  try { commit = git(['rev-parse', '--verify', ref], root, options); }
+  catch (error) {
+    // Existing checks can lack a resolvable optional base ref. Without a
+    // declared recipe there is no environment feature to fail their check.
+    if (!git(['ls-tree', 'HEAD', '--', ENVIRONMENT_RECIPE], root, options)) return null;
+    throw error;
+  }
+  // Absence and a failed read are different. A malformed/unreadable declared
+  // recipe must never fall through to copying the checkout's shared env.
+  const entry = git(['ls-tree', commit, '--', ENVIRONMENT_RECIPE], root, options);
+  if (!entry) return null;
+  if (!entry.startsWith('100644 blob ') && !entry.startsWith('100755 blob ')) throw new Error('The environment recipe must be a regular tracked file.');
+  let recipe;
+  try { recipe = JSON.parse(git(['show', `${commit}:${ENVIRONMENT_RECIPE}`], root, options)); }
+  catch { throw new Error('The reviewed environment recipe is not valid JSON.'); }
+  const db = recipe?.database;
+  if (recipe.version !== 1 || !db || !['postgres', 'command'].includes(db.provider) || !strings(db.bindings) || db.bindings.length === 0 || db.bindings.some(k => !environmentKey(k)) || new Set(db.bindings).size !== db.bindings.length) throw new Error('The environment recipe needs version 1, a database provider and unique environment variable bindings.');
+  if (!command(recipe.migrate) || !command(recipe.seed)) throw new Error('The environment recipe needs migrate and seed argv arrays. Both commands must be retry-safe.');
+  if (db.provider === 'postgres' && (!environmentKey(db.adminUrlEnv ?? '') || db.bindings.includes(db.adminUrlEnv))) throw new Error('PostgreSQL needs a separate adminUrlEnv credential name.');
+  if (db.provider === 'command' && (!command(db.command) || !strings(db.credentials ?? []) || (db.credentials ?? []).some(k => !environmentKey(k) || db.bindings.includes(k)) || typeof db.source !== 'string' || !db.source.trim())) throw new Error('A database adapter needs command argv, credential names and an explicit test-data source.');
+  const files = recipe.envFiles ?? ['.env.local'];
+  if (!strings(files, 12) || new Set(files).size !== files.length) throw new Error('Environment envFiles must be unique repository paths.');
+  for (const file of files) {
+    repositoryPath(root, file);
+    if (!/(^|\/)(?:\.env(?:\.[A-Za-z0-9_-]+)*|\.dev\.vars(?:\.[A-Za-z0-9_-]+)*)$/.test(file)) throw new Error('Generated environment files must use an .env or .dev.vars filename.');
+  }
+  if (recipe.env != null && (!recipe.env || typeof recipe.env !== 'object' || Array.isArray(recipe.env) || Object.entries(recipe.env).some(([k, v]) => !environmentKey(k) || typeof v !== 'string' || v.length > 16_384 || v.includes('\0')))) throw new Error('Recipe env must contain environment variable names and string values.');
+  const ttlHours = recipe.ttlHours ?? 24;
+  if (!Number.isFinite(ttlHours) || ttlHours < 1 || ttlHours > 168) throw new Error('Environment ttlHours must be between 1 and 168.');
+  const connectors = recipe.connectors ?? [];
+  if (!strings(connectors) || connectors.some(n => !/^[A-Za-z0-9_-]{1,80}$/.test(n))) throw new Error('Environment connectors must name reviewed project MCP servers.');
+  return { recipe: { ...recipe, envFiles: files, ttlHours, connectors }, commit, root: realpathSync(root), hash: environmentHash(JSON.stringify(recipe)) };
+}
+
+export function readEnvironmentLocal(root, callerEnv = process.env) {
+  const path = repositoryPath(root, ENVIRONMENT_LOCAL);
+  if (!existsSync(path)) return { ...callerEnv };
+  try { git(['check-ignore', '--quiet', '--', ENVIRONMENT_LOCAL], root); }
+  catch { throw new Error(`${ENVIRONMENT_LOCAL} must be gitignored. Credentials stay on this machine.`); }
+  if (!lstatSync(path).isFile() || lstatSync(path).size > 128 * 1024 || (lstatSync(path).mode & 0o077)) throw new Error(`${ENVIRONMENT_LOCAL} must be a regular owner-only file (chmod 600).`);
+  let local;
+  try { local = JSON.parse(readFileSync(path, 'utf8')); } catch { throw new Error(`${ENVIRONMENT_LOCAL} is not valid JSON.`); }
+  if (!local?.env || typeof local.env !== 'object' || Array.isArray(local.env) || Object.entries(local.env).some(([key, value]) => !environmentKey(key) || typeof value !== 'string' || value.length > 16_384 || value.includes('\0'))) throw new Error(`${ENVIRONMENT_LOCAL} needs an env object with string values.`);
+  return { ...callerEnv, ...local.env };
+}
+
+export function reviewedProviderCommand(snapshot) {
+  const argv = snapshot.recipe.database.command;
+  // Like reviewed MCP launchers, referenced repo files must still be the
+  // reviewed blobs. Run providers from the checkout, never an edited worktree.
+  for (const arg of argv) {
+    if (!arg.startsWith('./') && !arg.startsWith('.flowviant/')) continue;
+    const path = arg.replace(/^\.\//, '');
+    const absolute = repositoryPath(snapshot.root, path);
+    const expected = git(['rev-parse', `${snapshot.commit}:${path}`], snapshot.root, { stdio: ['ignore', 'pipe', 'ignore'] });
+    let actual;
+    try { actual = git(['hash-object', '--no-filters', '--', absolute], snapshot.root, { stdio: ['ignore', 'pipe', 'ignore'] }); }
+    catch { throw new Error('A reviewed database adapter is missing from the checkout.'); }
+    if (actual !== expected) throw new Error('The database adapter differs from its reviewed base copy.');
+  }
+  return argv;
+}
+
+export function validateEnvironmentConnectors(snapshot) {
+  if (!snapshot.recipe.connectors.length) return;
+  let servers;
+  try { servers = JSON.parse(git(['show', `${snapshot.commit}:.mcp.json`], snapshot.root, { stdio: ['ignore', 'pipe', 'ignore'] })).mcpServers; }
+  catch { throw new Error('Environment connectors need a reviewed .mcp.json.'); }
+  for (const name of snapshot.recipe.connectors) {
+    const config = servers?.[name];
+    const values = config && [config.command, config.url, ...(config.args ?? []), ...Object.values(config.env ?? {}), ...Object.values(config.headers ?? {})];
+    if (!values?.some(value => snapshot.recipe.database.bindings.some(key => String(value).includes('${' + key + '}')))) throw new Error(`The ${name} connector must reference an isolated database binding in .mcp.json.`);
+  }
+}

package/bin/lib/reviewEnvironmentMain.mjs

@@ -0,0 +1,38 @@
+/** Private daemon verbs, also usable by runners without MCP. */
+import { spawn } from 'node:child_process';
+import { killGroup, STOP_GRACE_MS } from './processGroup.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { prepareWorktreeEnvironment, readWorktreeEnvironment, releaseWorktreeEnvironment } from './reviewEnvironment.mjs';
+
+export async function reviewEnvironmentMain(argv = process.argv.slice(3)) {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.on('SIGINT', abort); process.on('SIGTERM', abort);
+  try {
+    const [wt, verb, separator, ...command] = argv;
+    const current = readWorktreeEnvironment(wt, process.env, { allowPending: verb === 'refresh' || verb === 'release' });
+    if (!current) throw new Error('No Flowviant environment has been prepared in this worktree.');
+    if (verb === 'refresh' && (argv.length === 2 || (argv.length === 3 && separator === '--seed'))) {
+      const next = await prepareWorktreeEnvironment(current.snapshot.root, wt, { snapshot: current.snapshot, reseed: separator === '--seed', signal: controller.signal });
+      process.stdout.write(JSON.stringify({ environment: next.record.id, state: next.record.phase, fixturesSeeded: next.record.seeded }) + '\n');
+    } else if (verb === 'release' && argv.length === 2) {
+      await releaseWorktreeEnvironment(current.snapshot.root, current.record.id, { signal: controller.signal });
+      process.stdout.write('Disposable environment released.\n');
+    } else if (verb === 'run' && separator === '--' && command.length) {
+      const child = spawn(command[0], command.slice(1), { cwd: wt, env: unattendedEnv(current.env), stdio: 'inherit', detached: true });
+      let stopTimer;
+      const stop = () => {
+        killGroup(child, 'SIGTERM');
+        stopTimer ??= setTimeout(() => killGroup(child), STOP_GRACE_MS);
+        stopTimer.unref?.();
+      };
+      controller.signal.addEventListener('abort', stop, { once: true });
+      if (controller.signal.aborted) stop();
+      await new Promise((resolve, reject) => {
+        child.once('error', () => reject(new Error('The environment command could not start.')));
+        child.once('close', code => { process.exitCode = code ?? 1; resolve(); });
+      }).finally(() => { clearTimeout(stopTimer); controller.signal.removeEventListener('abort', stop); killGroup(child); });
+    } else throw new Error('Use this worktree environment with refresh, release, or run -- <command argv>.');
+  } catch (error) { process.stderr.write(error.message + '\n'); process.exitCode = 1; }
+  finally { process.off('SIGINT', abort); process.off('SIGTERM', abort); }
+}

package/bin/lib/reviewImage.mjs

@@ -0,0 +1,58 @@
+/** One network-disabled headless canvas normalizes native engine images. */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { startReviewProcess } from './reviewProcess.mjs';
+import { chromeFlags, resolveBrowser, sandboxOff } from './shot.mjs';
+import { createCdpClient } from './pinnedCapture.mjs';
+import { childEnv } from './childEnv.mjs';
+
+export async function createReviewImage({ signal, onChild, timeoutMs = 620_000, detached = true, browser = resolveBrowser() } = {}) {
+  if (!browser || browser.viaWindows) throw new Error('Studio viewport review needs native headless Chromium on the daemon host to normalize captured images.');
+  const home = mkdtempSync(join(tmpdir(), 'flowviant-engine-image-'));
+  let process, cdp, closed = false, sessionId;
+  const close = async () => {
+    if (closed) return;
+    closed = true; cdp?.close('Engine image encoder closed.');
+    await process?.close();
+    try { rmSync(home, { recursive: true, force: true }); } catch { /* local cleanup */ }
+  };
+  const send = async (method, params = {}, session) => {
+    let timer;
+    try { return await Promise.race([cdp.send(method, params, session), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Engine image encoding timed out.')), 5000); })]); }
+    catch (error) { await close(); throw error; }
+    finally { clearTimeout(timer); }
+  };
+  try {
+    process = startReviewProcess([browser.bin, ...chromeFlags({ headlessFlag: '--headless=new', noSandbox: sandboxOff(), userDataDir: home, width: 1440, height: 900 }),
+      '--remote-debugging-pipe', '--disable-background-networking', '--disable-sync', '--disable-default-apps', '--proxy-server=http://127.0.0.1:9', '--proxy-bypass-list=<-loopback>', 'about:blank'],
+    { env: { ...childEnv(), HOME: home, USERPROFILE: home, XDG_CONFIG_HOME: home, XDG_DATA_HOME: home, XDG_CACHE_HOME: home }, signal, onChild, timeoutMs, detached, captureStdout: false, stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] });
+    cdp = createCdpClient(process.child.stdio[3], process.child.stdio[4], { maxMessageBytes: 10 * 1024 * 1024 });
+    process.done.then(() => { cdp.close('Engine image encoder exited.'); void close(); });
+    await send('Browser.getVersion');
+    await send('Browser.setDownloadBehavior', { behavior: 'deny' });
+    const { targetInfos } = await send('Target.getTargets');
+    const target = targetInfos.find(t => t.type === 'page');
+    if (!target) throw new Error('No isolated engine image canvas is available.');
+    ({ sessionId } = await send('Target.attachToTarget', { targetId: target.targetId, flatten: true }));
+    await send('Network.enable', {}, sessionId);
+    await send('Network.setBlockedURLs', { urls: ['http://*', 'https://*', 'file://*', 'ws://*', 'wss://*', 'ftp://*'] }, sessionId);
+    return { close, async encode(image) {
+      if (closed) throw new Error('Engine image encoder closed.');
+      if (!image || !['image/png', 'image/jpeg'].includes(image.mimeType) || typeof image.data !== 'string' || image.data.length > 8 * 1024 * 1024 || !/^[A-Za-z0-9+/]+={0,2}$/.test(image.data)) throw new Error('Studio MCP must return one bounded PNG/JPEG image content block.');
+      const encoded = await send('Runtime.evaluate', { awaitPromise: true, returnByValue: true, expression: `new Promise((resolve,reject)=>{
+        const image=new Image();image.onerror=()=>reject(new Error('Invalid engine image'));
+        image.onload=()=>{const width=image.naturalWidth,height=image.naturalHeight;
+          if(!width||!height||width>4096||height>4096){reject(new Error('Engine image exceeds pixel bound'));return;}
+          const scale=Math.min(1440/width,900/height),w=width*scale,h=height*scale,left=(1440-w)/2,top=(900-h)/2;
+          const canvas=document.createElement('canvas');canvas.width=1440;canvas.height=900;
+          const context=canvas.getContext('2d');context.fillStyle='#000';context.fillRect(0,0,1440,900);context.drawImage(image,left,top,w,h);
+          resolve({data:canvas.toDataURL('image/jpeg',0.65).split(',')[1],width,height,left,top,w,h});
+        };image.src=${JSON.stringify(`data:${image.mimeType};base64,${image.data}`)};
+      })` }, sessionId);
+      const result = encoded.result?.value;
+      if (encoded.exceptionDetails || !result || result.data.length > 1_000_000) throw new Error('Studio image could not be normalized within the frame bound.');
+      return result;
+    } };
+  } catch (error) { await close(); throw error; }
+}

package/bin/lib/reviewMcpClient.mjs

@@ -0,0 +1,69 @@
+/** Bounded stdio MCP client for an engine bridge, never a model service. */
+import { StringDecoder } from 'node:string_decoder';
+import { startReviewProcess } from './reviewProcess.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+
+export async function connectReviewMcp({ command, cwd, env, onChild, signal, requestTimeoutMs = 15_000, timeoutMs = 620_000, detached = true }) {
+  const process = startReviewProcess(command, { cwd, env, onChild, signal, timeoutMs, detached, captureStdout: false, stdio: ['pipe', 'pipe', 'pipe'] });
+  const pending = new Map(), decoder = new StringDecoder('utf8');
+  let serial = 0, buffer = '', closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new Error('Studio MCP disconnected.')); }
+    pending.clear(); process.child.stdin.end(); await process.close();
+  };
+  const fail = () => { void close(); };
+  process.done.then(fail);
+  process.child.stdout.on('data', bytes => {
+    if (closed) return;
+    buffer += decoder.write(bytes);
+    if (Buffer.byteLength(buffer) > 10 * 1024 * 1024) { fail(); 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('Invalid MCP protocol.');
+        if (message.id != null && message.method) {
+          // This adapter supplies no sampling, elicitation or filesystem roots.
+          process.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'This review client does not support server requests.' } }) + '\n');
+        } else {
+          const entry = pending.get(message.id); if (!entry) continue;
+          pending.delete(message.id); clearTimeout(entry.timer);
+          message.error ? entry.reject(new Error(reviewDiagnostic(message.error.message))) : entry.resolve(message.result);
+        }
+      } catch { fail(); }
+    }
+  });
+  const request = (method, params, limit = requestTimeoutMs) => new Promise((resolve, reject) => {
+    if (closed) { reject(new Error('Studio MCP is disconnected.')); return; }
+    const id = ++serial;
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`Studio MCP ${method} timed out.`)); }, limit);
+    pending.set(id, { resolve, reject, timer });
+    process.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n', error => { if (error) fail(); });
+  });
+  try {
+    const hello = await request('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'flowviant-runtime-review', version: '1' } });
+    if (!hello?.capabilities?.tools) throw new Error('The configured server exposes no MCP tools.');
+    process.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+    const tools = []; let cursor;
+    for (let page = 0; page < 8; page++) {
+      const result = await request('tools/list', cursor ? { cursor } : {});
+      if (!Array.isArray(result?.tools) || tools.length + result.tools.length > 500) throw new Error('Studio MCP returned an invalid tool catalog.');
+      tools.push(...result.tools); cursor = result.nextCursor;
+      if (!cursor) break;
+      if (page === 7) throw new Error('Studio MCP tool catalog exceeded its page bound.');
+    }
+    return { tools, close, async call(name, args, limit) {
+      if (!tools.some(tool => tool.name === name)) throw new Error(`Studio MCP does not expose ${name}. Update Studio and enable its built-in MCP server.`);
+      const result = await request('tools/call', { name, arguments: args }, limit);
+      if (result?.isError) throw new Error(reviewDiagnostic((result.content ?? []).filter(c => c.type === 'text').map(c => c.text).join('\n')).slice(0, 1000) || `Studio MCP ${name} failed.`);
+      return result;
+    } };
+  } catch (error) { await close(); throw error; }
+}
+
+export function mcpText(result) {
+  return (result?.content ?? []).filter(c => c.type === 'text' && typeof c.text === 'string').map(c => c.text).join('\n');
+}

package/bin/lib/reviewProcess.mjs

@@ -0,0 +1,51 @@
+/** Own every runtime child and bound its output, cancellation and lifetime. */
+import { spawn } from 'node:child_process';
+import { killGroup } from './processGroup.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { scrub } from './uplinkScrub.mjs';
+import { workLanesStopped } from './standDownGate.mjs';
+
+export function startReviewProcess(argv, { cwd, env = process.env, display = false, input, signal, onChild = () => () => {}, timeoutMs = 600_000, binary = false, maxBytes = 64 * 1024, stdio, captureStdout = true, detached = true } = {}) {
+  signal?.throwIfAborted();
+  if (workLanesStopped()) throw new Error('The daemon is stopping. Review has not started.');
+  const child = spawn(argv[0], argv.slice(1), { cwd, env: unattendedEnv(env, { display }), detached, stdio: stdio ?? ['pipe', 'pipe', 'pipe'] });
+  let timer, untrack = () => {}, settled = false, total = 0, stdout = [], tail = '', exit;
+  let resolveExit;
+  const done = new Promise(resolve => { resolveExit = resolve; });
+  const finish = result => {
+    if (settled) return;
+    settled = true; exit = result; clearTimeout(timer); signal?.removeEventListener('abort', abort); untrack();
+    killGroup(child);
+    resolveExit({ ...result, output: tail, data: binary ? Buffer.concat(stdout) : undefined });
+  };
+  const terminate = reason => { killGroup(child); child.stdout?.destroy(); child.stderr?.destroy(); finish({ code: null, error: reason }); };
+  const abort = () => terminate('Review was interrupted.');
+  const diagnostics = bytes => { tail = scrub(tail + bytes.toString()).slice(-maxBytes); };
+  child.stdout?.on('data', bytes => {
+    if (!captureStdout) return;
+    if (binary) {
+      total += bytes.length;
+      if (total > maxBytes) { terminate('Review capture exceeded its byte bound.'); return; }
+      stdout.push(bytes);
+    } else diagnostics(bytes);
+  });
+  child.stderr?.on('data', diagnostics);
+  child.once('error', () => finish({ code: null, error: `Could not start ${argv[0]}. Check that it is installed.` }));
+  child.once('close', code => finish({ code }));
+  child.stdin?.on('error', () => {});
+  if (input !== undefined) child.stdin?.end(input);
+  else if (stdio == null) child.stdin?.end();
+  try { untrack = onChild(child) ?? (() => {}); }
+  catch (error) { terminate('The review process could not be tracked.'); throw error; }
+  timer = setTimeout(() => terminate('Review reached its time limit.'), timeoutMs); timer.unref?.();
+  signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort();
+  return { child, done, running: () => !settled, result: () => exit, output: () => tail,
+    async close() { terminate('Review stopped.'); await done; } };
+}
+
+export async function reviewExec(argv, options) {
+  const process = startReviewProcess(argv, options);
+  const result = await process.done;
+  if (result.error || result.code !== 0) throw new Error(result.error ?? `Review command exited ${result.code}. ${result.output}`);
+  return result;
+}