flowviant 0.125.28 → 0.125.30

package/bin/lib/robloxStudioBridge.mjs

@@ -0,0 +1,68 @@
+/** Windows Studio through WSL stdio; no Windows daemon or desktop capture. */
+import { createInterface } from 'node:readline';
+import { createHash } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { openBridgePage } from './reviewBridge.mjs';
+import { openRobloxPage, robloxConfiguration } from './robloxReview.mjs';
+import { heldToolArgv } from './heldTool.mjs';
+import { browserAction } from './managedBrowser.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+import { commandOnPath } from './reviewTargets.mjs';
+
+export function openRobloxStudio({ command, cwd, worktree, configuration, ...options }) {
+  const config = robloxConfiguration(configuration);
+  const name = config.studioName.replaceAll('${WORKTREE}', basename(worktree));
+  const flock = commandOnPath('flock', options.env);
+  if (process.platform !== 'linux' || !flock) throw new Error('The first Studio adapter requires a Linux/WSL daemon with flock and a configured Windows Studio MCP launcher.');
+  const directory = join(homedir(), '.flowviant', 'review-studios'); mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const lock = join(directory, createHash('sha256').update(name).digest('hex') + '.lock');
+  return openBridgePage({ ...options, command: [flock, '-n', '-E', '75', lock, process.execPath, ...heldToolArgv('__roblox-studio-bridge')], cwd, worktree,
+    configuration: { ...config, command, cwd, timeoutMs: options.timeoutMs }, requestTimeoutMs: 60_000, closeGraceMs: 30_000,
+  }).catch(error => {
+    if (/exited \(75\)/.test(error.message)) throw new Error('This Studio fixture is already being reviewed by another local turn. Return or stop that review first.');
+    throw error;
+  });
+}
+
+export async function robloxStudioBridgeMain() {
+  const controller = new AbortController();
+  let page, configuration, worktree, epoch = 0, closing = false, shuttingDown;
+  const send = value => { if (!closing) process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...value }) + '\n'); };
+  const shutdown = () => {
+    if (shuttingDown) return shuttingDown;
+    closing = true; controller.abort();
+    shuttingDown = Promise.resolve().then(() => page?.close()).catch(() => { process.exitCode = 1; });
+    return shuttingDown;
+  };
+  process.stdin.once('end', () => { void shutdown(); }); process.stdin.once('error', () => { void shutdown(); }); process.stdout.once('error', () => { void shutdown(); });
+  process.once('SIGTERM', () => { void shutdown(); process.stdin.destroy(); }); process.once('SIGINT', () => { void shutdown(); process.stdin.destroy(); });
+  try {
+    for await (const line of createInterface({ input: process.stdin })) {
+      if (closing) break;
+      let request;
+      try {
+        if (Buffer.byteLength(line) > 128 * 1024) throw new Error('Studio bridge request exceeds its byte bound.');
+        request = JSON.parse(line);
+        const { id, method, params } = request; let result = {};
+        if (method === 'initialize' && !configuration) {
+          configuration = params.configuration; worktree = params.worktree;
+          if (params.protocol !== 1 || !Array.isArray(configuration?.command) || typeof worktree !== 'string') throw new Error('Invalid Studio bridge initialization.');
+          robloxConfiguration(configuration);
+          result = { protocol: 1, isolation: 'consented-window', privateHandoff: true };
+        } else if (method === 'open' && configuration && !page) {
+          const opened = await openRobloxPage({ command: configuration.command, cwd: configuration.cwd, worktree, configuration, env: process.env, signal: controller.signal, timeoutMs: configuration.timeoutMs,
+            onFrame: frame => send({ method: 'frame', params: { ...frame, epoch } }), onChange: patch => send({ method: 'failure', params: { epoch, message: patch.error } }) });
+          page = opened;
+          // Parent EOF may have arrived while Studio was starting play.
+          if (closing) await opened.close();
+        } else if (method === 'snapshot' && page) result = { ...await page.snapshot(), width: 1440, height: 900, epoch };
+        else if (method === 'act' && page && params.epoch === epoch) await page.act(browserAction(params.input));
+        else if (method === 'privacy' && page) { await page.setPrivate(params.private); epoch = params.epoch; result = { epoch, drained: true }; }
+        else throw new Error('Unsupported or stale Studio bridge operation.');
+        send({ id, result });
+      } catch (error) { send({ id: request?.id, error: { message: reviewDiagnostic(error.message) } }); }
+    }
+  } finally { await shutdown(); }
+}

package/bin/lib/runtimeAuth.mjs

@@ -1,4 +1,4 @@
-/** Claude Code's own auth verdict for the local desktop contract.
+/** Coding tools' own auth verdicts for the local desktop contract.
  *
  * The credential file is only a context clue (claudeAuth.mjs): on some boxes
  * Claude stores a working login in a keychain. Only `claude auth status --json`
@@ -15,6 +15,28 @@ const UNKNOWN = Object.freeze({ signedIn: null, billing: null, subscriptionType:
 const TTL_MS = 90_000;
 const SUBSCRIPTIONS = new Set(['pro', 'max', 'team', 'enterprise']);
 
+function cachedAuth(cachePath, bin, now, refresh) {
+  if (refresh) return null;
+  try {
+    const cached = JSON.parse(readFileSync(cachePath, 'utf8'));
+    if (cached.bin === bin && Number.isFinite(cached.at) && now >= cached.at && now - cached.at < TTL_MS &&
+        cached.result?.checkedAt === new Date(cached.at).toISOString() &&
+        [true, false, null].includes(cached.result?.signedIn) &&
+        [null, 'api', 'subscription'].includes(cached.result?.billing)) return cached.result;
+  } catch { /* No usable cache: ask the CLI, including after an upgrade. */ }
+  return null;
+}
+
+function retainAuth(cachePath, bin, now, result) {
+  const measured = { ...result, checkedAt: new Date(now).toISOString(),
+    expiresAt: result.expiresAt ?? null, expiryKind: result.expiryKind ?? null };
+  try {
+    mkdirSync(dirname(cachePath), { recursive: true, mode: 0o700 });
+    writeFileSync(cachePath, JSON.stringify({ bin, at: now, result: measured }), { mode: 0o600 });
+  } catch { /* Caching is optional; never break status. */ }
+  return measured;
+}
+
 export function parseClaudeAuthStatus(raw) {
   let value;
   try { value = JSON.parse(raw); } catch { return UNKNOWN; }
@@ -31,14 +53,8 @@ export function parseClaudeAuthStatus(raw) {
 
 export function readClaudeAuthStatus({ bin = 'claude', cachePath = join(homedir(), '.flowviant', 'claude-auth-status.json'),
   refresh = false, timeoutMs = 3_000, now = Date.now(), spawn = spawnSync, contextFor = claudeAuthContext } = {}) {
-  if (!refresh) {
-    try {
-      const cached = JSON.parse(readFileSync(cachePath, 'utf8'));
-      if (cached.bin === bin && Number.isFinite(cached.at) && now >= cached.at && now - cached.at < TTL_MS &&
-          [true, false, null].includes(cached.result?.signedIn) &&
-          [null, 'api', 'subscription'].includes(cached.result?.billing)) return cached.result;
-    } catch { /* no cache, or unreadable cache: ask the CLI */ }
-  }
+  const cached = cachedAuth(cachePath, bin, now, refresh);
+  if (cached) return cached;
   let result = UNKNOWN;
   try {
     const child = spawn(bin, ['auth', 'status', '--json'], {
@@ -46,16 +62,40 @@ export function readClaudeAuthStatus({ bin = 'claude', cachePath = join(homedir(
       stdio: ['ignore', 'pipe', 'ignore'],
     });
     if (!child.error && (child.status === 0 || child.status === 1)) result = parseClaudeAuthStatus(child.stdout);
-    if (result.signedIn === true && result.billing === 'subscription' && result.subscriptionType === null) {
+    if (result.signedIn === true && result.billing === 'subscription') {
       const context = contextFor();
-      if (context.source === 'file' && SUBSCRIPTIONS.has(context.subscriptionType)) {
-        result = { ...result, subscriptionType: context.subscriptionType };
+      if (context.source === 'file') {
+        if (result.subscriptionType === null && SUBSCRIPTIONS.has(context.subscriptionType)) {
+          result = { ...result, subscriptionType: context.subscriptionType };
+        }
+        // Access-token expiry is renewable. Only the store's explicit refresh
+        // expiry can describe the end of this login; absent stays unknown.
+        const expiry = Date.parse(context.refreshExpiresAt ?? '');
+        if (Number.isFinite(expiry)) result = { ...result, expiresAt: new Date(expiry).toISOString(), expiryKind: 'refresh' };
       }
     }
   } catch { /* A failed probe means unknown, not signed out. */ }
+  return retainAuth(cachePath, bin, now, result);
+}
+
+/** `codex login status` writes its verdict to stderr. Keep only the verdict,
+ * never its output: API-key mode can include credential material. */
+export function readCodexAuthStatus({ bin = 'codex', cachePath = join(homedir(), '.flowviant', 'codex-auth-status.json'),
+  refresh = false, timeoutMs = 3_000, now = Date.now(), spawn = spawnSync } = {}) {
+  const cached = cachedAuth(cachePath, bin, now, refresh);
+  if (cached) return cached;
+  let result = UNKNOWN;
   try {
-    mkdirSync(dirname(cachePath), { recursive: true, mode: 0o700 });
-    writeFileSync(cachePath, JSON.stringify({ bin, at: now, result }), { mode: 0o600 });
-  } catch { /* Caching is optional; never break status. */ }
-  return result;
+    const child = spawn(bin, ['login', 'status'], {
+      encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const words = `${child.stdout ?? ''}\n${child.stderr ?? ''}`.trim();
+    if (!child.error && child.status === 0 && /^logged in\b/im.test(words)) {
+      result = { signedIn: true, billing: /api.?key/i.test(words) ? 'api' : /chatgpt/i.test(words) ? 'subscription' : null, subscriptionType: null };
+    } else if (!child.error && child.status === 1 && /^not logged in\b/im.test(words)) {
+      result = { ...UNKNOWN, signedIn: false };
+    }
+  } catch { /* Unknown, never a fabricated sign-out. */ }
+  return retainAuth(cachePath, bin, now, result);
 }

package/bin/lib/runtimeReview.mjs

@@ -0,0 +1,185 @@
+/** One model-independent review tool over reusable execution/surface adapters. */
+import { createServer } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { listenHeldTool, heldToolArgv } from './heldTool.mjs';
+import { serveMcpStdio } from './mcpStdio.mjs';
+import { readReviewTargets, reviewCwd, commandOnPath } from './reviewTargets.mjs';
+import { startReviewProcess } from './reviewProcess.mjs';
+import { desktopSupport } from './reviewDesktop.mjs';
+import { openLinuxDesktop } from './linuxDesktopBridge.mjs';
+import { openBridgePage } from './reviewBridge.mjs';
+import { openRobloxStudio } from './robloxStudioBridge.mjs';
+import { reviewedProviderCommand } from './reviewEnvironmentConfig.mjs';
+import { environmentOverlay, readWorktreeEnvironment } from './reviewEnvironment.mjs';
+import { childEnv } from './childEnv.mjs';
+import { measureListeners } from './listeners.mjs';
+import { resolveBrowser } from './shot.mjs';
+import { reviewSourceState, sameReviewSource } from './uiReview.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+import { ensureArtifactDir, ARTIFACT_DIR } from './artifacts.mjs';
+import { learnExtraSecrets, forgetExtraSecrets, scrub } from './uplinkScrub.mjs';
+
+export const RUNTIME_REVIEW_SERVER = 'card_runtime';
+const TOOLS = [
+  { name: 'discover', description: 'List reviewed command, browser, desktop, Roblox Studio and engine review targets and measured prerequisites. Discovery starts no application.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+  { name: 'run', description: 'Run a named reviewed target. Command checks return logs and source-bound evidence; interactive targets open the SAME Live app frame and human control handoff. Never treats a build or sync server as gameplay.', inputSchema: { type: 'object', properties: { target: { type: 'string' }, repository: { type: 'string' } }, required: ['target'], additionalProperties: false } },
+  { name: 'observe', description: 'Capture and retain the current shared runtime surface. Screenshot capture is an observation, not a passing test.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+  { name: 'act', description: 'Interact with the current surface using bounded click, type, key, scroll or browser navigation verbs. Human control pauses model interactions.', inputSchema: { type: 'object', properties: { type: { type: 'string', enum: ['click', 'type', 'key', 'scroll', 'navigate', 'snapshot'] }, x: { type: 'number' }, y: { type: 'number' }, text: { type: 'string' }, key: { type: 'string' }, path: { type: 'string' }, selector: { type: 'string' }, deltaY: { type: 'number' } }, required: ['type'], additionalProperties: false } },
+  { name: 'handoff', description: 'Hold this turn for human private sign-in or native app testing. Waits without model polling and resumes the same conversation.', inputSchema: { type: 'object', properties: { kind: { type: 'string', enum: ['signin', 'control'] }, reason: { type: 'string', maxLength: 300 } }, required: ['kind', 'reason'], additionalProperties: false } },
+  { name: 'stop', description: 'Stop the runtime processes owned by this tool. A person’s Stop prevents reopening for the turn.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+];
+const text = value => ({ content: [{ type: 'text', text: JSON.stringify(value) }] });
+const availablePort = () => new Promise((resolve, reject) => {
+  const server = createServer(); server.once('error', reject);
+  server.listen(0, '127.0.0.1', () => { const port = server.address().port; server.close(() => resolve(port)); });
+});
+
+export async function createRuntimeReview({ wt, repoRoot, baseRef, sources = [], browser, signal, onChild,
+  openDesktop = openLinuxDesktop, openBridge = openBridgePage, openRoblox = openRobloxStudio, desktopProbe = desktopSupport, browserProbe = resolveBrowser }) {
+  const catalog = (sources.length ? sources : [{ wt, repoRoot, baseRef }]).map(source => ({ ...readReviewTargets(source.repoRoot, source.baseRef),
+    wt: source.wt, name: source.name ?? basename(source.repoRoot), id: source.id }));
+  if (catalog.every(source => Object.keys(source.targets).length === 0)) return null;
+  const controller = new AbortController(), reports = [], commands = new Set();
+  let closed = false, busy = false, current = null, app = null;
+  const abort = () => { void close(); };
+  const environmentFor = source => readWorktreeEnvironment(source.wt)?.env ?? process.env;
+  function support(target, env) {
+    if (target.platforms && !target.platforms.includes(process.platform)) return { available: false, reason: `This target requires ${target.platforms.join(' or ')}; this machine is ${process.platform}.` };
+    if (target.adapter === 'browser') {
+      const found = browserProbe();
+      return browser && found && !found.viaWindows ? { available: true } : { available: false, reason: 'No native managed Chromium browser is available on this machine.' };
+    }
+    if (target.adapter === 'desktop') return browser ? desktopProbe(env) : { available: false, reason: 'The interactive surface transport is unavailable on this turn.' };
+    if (target.adapter === 'roblox') {
+      const found = browserProbe();
+      return browser && process.platform === 'linux' && commandOnPath('flock', env) && found && !found.viaWindows ? { available: true } : { available: false, reason: 'Studio viewport review needs a Linux/WSL daemon, flock and native headless Chromium. Studio/MCP runs on the Windows host.' };
+    }
+    if (target.adapter === 'bridge' && !browser) return { available: false, reason: 'The interactive surface transport is unavailable on this turn.' };
+    return { available: true };
+  }
+  const stopApp = async () => { const previous = app; app = null; await previous?.close(); };
+  async function close() {
+    if (closed) return;
+    closed = true; signal?.removeEventListener('abort', abort); controller.abort();
+    if (current) await browser?.close();
+    await Promise.all([stopApp(), ...[...commands].map(command => command.close())]);
+    held.server.close(); held.server.closeAllConnections(); forgetExtraSecrets(secretKey);
+  }
+  const record = (source, target, name, before, result) => {
+    const after = reviewSourceState(source.wt);
+    const report = { target: name, repository: source.name, adapter: target.adapter, ...result,
+      before, after, sourceStable: sameReviewSource(before, after) };
+    reports.push({ source, report });
+    if (ensureArtifactDir(wt)) {
+      const path = `runtime-review-${randomUUID()}.md`;
+      const body = `# Runtime review: ${source.name}/${name}\n\n${scrub(JSON.stringify(report, null, 2))}\n`;
+      writeFileSync(join(wt, ARTIFACT_DIR, path), body, { flag: 'wx', mode: 0o600 });
+      report.artifact = `${ARTIFACT_DIR}/${path}`;
+    }
+    return report;
+  };
+  const call = async (name, input = {}) => {
+    if (closed || controller.signal.aborted) throw new Error('This review turn has ended.');
+    if (name === 'discover') return text({ repositories: catalog.map(source => ({ repository: source.name, targets: Object.entries(source.targets).map(([target, config]) => ({ target, adapter: config.adapter,
+      ...support(config, environmentFor(source)), command: config.command })) })),
+      instruction: 'Use the repository’s existing workflows when no recipe is configured. A missing runtime leaves those checks unverified; code editing can continue. A Roblox/Rojo sync server is not gameplay.' });
+    if (busy) throw new Error('Another runtime review operation is finishing.');
+    busy = true;
+    try {
+      if (name === 'observe') { if (!browser) throw new Error('No interactive runtime is available.'); return await browser.act({ type: 'snapshot' }); }
+      if (name === 'act') { if (!browser) throw new Error('No interactive runtime is available.'); return await browser.act(input); }
+      if (name === 'handoff') { if (!browser) throw new Error('No interactive runtime is available.'); return await browser.handoff(input); }
+      if (name === 'stop') { browser?.stopSurface(); await stopApp(); current = null; return text({ stopped: true }); }
+      if (name !== 'run') throw new Error('Unknown runtime tool.');
+      const source = input.repository == null ? catalog.find(source => source.wt === wt) : catalog.find(source => source.name === input.repository || source.id === input.repository);
+      const target = source && Object.hasOwn(source.targets, input.target) ? source.targets[input.target] : null;
+      if (!target) throw new Error('That reviewed target does not exist. Call discover and use a listed repository/target.');
+      const cwd = reviewCwd(source.wt, target.cwd), env = environmentFor(source), measured = support(target, env);
+      if (!measured.available) throw new Error(measured.reason);
+      if (!commandOnPath(target.command[0], env) && !target.command[0].startsWith('./')) throw new Error(`Review command ${target.command[0]} is not installed on this machine.`);
+      const scoped = readWorktreeEnvironment(source.wt);
+      const interactiveEnv = { ...childEnv({ cwd }), ...Object.fromEntries((target.env ?? []).filter(key => env[key] != null).map(key => [key, env[key]])), ...(scoped ? environmentOverlay(scoped) : {}) };
+      const before = reviewSourceState(source.wt), options = { cwd, env: target.adapter === 'command' ? env : interactiveEnv, onChild, signal: controller.signal, timeoutMs: target.timeoutSeconds * 1000 };
+      if (target.adapter === 'command') {
+        const running = startReviewProcess(target.command, options);
+        commands.add(running);
+        let result;
+        try { result = await running.done; } finally { commands.delete(running); }
+        const report = record(source, target, input.target, before, { status: !result.error && result.code === 0 ? 'passed' : 'failed', exitCode: result.code, output: result.output, ...(result.error ? { error: result.error } : {}) });
+        return text({ ...report, output: result.output.slice(-4000), ...(result.output.length > 4000 ? { outputTruncated: true } : {}) });
+      }
+      browser.assertControl();
+      const key = `${source.wt}:${input.target}`;
+      if (target.adapter === 'browser') {
+        try {
+        if (current?.key !== key || !app?.running()) {
+          await stopApp();
+          const port = target.port || await availablePort();
+          if (measureListeners(source.wt).rows.some(row => row.port === port)) throw new Error('That worktree port is already running. Use card_browser for the existing server, or choose a different review port.');
+          app = startReviewProcess(target.command.map(arg => arg.replaceAll('${PORT}', String(port))), options);
+          current = { key, port };
+          for (let n = 0; n < 100; n++) {
+            if (controller.signal.aborted) throw new Error('The review turn ended during startup.');
+            if (!app.running()) throw new Error(app.result()?.error ?? `The review app exited. ${app.output()}`);
+            if (measureListeners(source.wt).rows.some(row => row.port === port)) break;
+            if (n === 99) throw new Error('No listener was measured for this review target.');
+            await new Promise(resolve => setTimeout(resolve, 100));
+          }
+        }
+        return await browser.open({ port: current.port, hostname: target.hostname, scheme: target.scheme, path: target.path ?? '/', fixture: target.fixture }, source.wt);
+        }
+        catch (error) { await stopApp(); current = null; throw error; }
+      }
+      const result = await browser.openSurface({ key, target: input.target, surface: target.adapter === 'desktop' ? 'desktop' : 'engine',
+        open: async surface => {
+          await stopApp(); current = { key };
+          if (target.adapter === 'desktop') return openDesktop({ ...options, ...surface, command: target.command, support: measured });
+          const command = reviewedProviderCommand({ root: source.root, commit: source.commit, recipe: { database: { command: target.command } } });
+          if (target.adapter === 'roblox') return openRoblox({ ...options, ...surface, command, cwd: source.root, worktree: source.wt, configuration: target.configuration });
+          return openBridge({ ...options, ...surface, command, cwd: source.root, worktree: source.wt, configuration: target.configuration });
+        } });
+      record(source, target, input.target, before, { status: 'observed', note: 'Interactive runtime opened. Captures and input do not establish passing gameplay tests.' });
+      return result;
+    } catch (error) { throw new Error(reviewDiagnostic(error.message)); }
+    finally { busy = false; }
+  };
+  const held = await listenHeldTool({ envPrefix: 'FLOWVIANT_RUNTIME_REVIEW', verb: '__runtime-review-mcp', requestTimeoutMs: 615_000, isClosed: () => closed,
+    respond: async (req, res) => {
+      try {
+        const chunks = []; let size = 0;
+        for await (const bytes of req) { size += bytes.length; if (size > 16_000) throw new Error('Runtime request exceeds its byte bound.'); chunks.push(bytes); }
+        const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (!TOOLS.some(tool => tool.name === input.name)) throw new Error('Unknown runtime tool.');
+        const result = await call(input.name, input.input);
+        res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify(result));
+      } catch (error) { res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify({ isError: true, content: [{ type: 'text', text: reviewDiagnostic(error.message) }] })); }
+    } });
+  const secretKey = `runtime-review:${held.capability.slice(0, 12)}`;
+  learnExtraSecrets(secretKey, [{ name: 'FLOWVIANT_RUNTIME_REVIEW_CAPABILITY', value: held.capability }]);
+  signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) await close();
+  return { env: held.env, config: { command: process.execPath, args: held.args, env: held.env, toolTimeoutSec: 650 }, close,
+    instructions: `Use card_runtime.discover to find reviewed command, browser, desktop or engine targets. Run a named target with card_runtime.run; never treat code compilation or a sync server as a visual/gameplay test. Desktop targets use a private virtual display, never the personal desktop. Native/engine screenshots use the SAME Live app frame and handoff controls as browser review. Human control pauses model observations/input; call handoff before asking for sign-in or manual testing and finish this invocation without polling. Missing capabilities are skipped checks, not passing tests or reasons to stop code work. Keep external services on scoped test bindings. Observe and retain actual captures before delivery. For a runner without MCP, this turn also provides the private shell helper argv ${JSON.stringify([process.execPath, ...heldToolArgv('__runtime-review')])}; pass a JSON request file {name,input}.`,
+    finalize() {
+      return reports.map(({ source, report }) => `Runtime review ${report.repository}/${report.target}: ${report.status}${report.status === 'observed' ? ' (not a passing gameplay test)' : ''}. ${report.sourceStable && sameReviewSource(report.after, reviewSourceState(source.wt)) ? 'Source matches final tracked/nonignored state.' : 'STALE: source changed or could not be measured; this does not verify final source.'}${report.artifact ? ` Evidence: ${report.artifact}.` : ''}`).join('\n');
+    },
+  };
+}
+
+async function requestRuntime(input) {
+  const response = await fetch(process.env.FLOWVIANT_RUNTIME_REVIEW_URL, { method: 'POST', headers: { Authorization: `Bearer ${process.env.FLOWVIANT_RUNTIME_REVIEW_CAPABILITY}`, 'Content-Type': 'application/json' }, body: JSON.stringify(input), signal: AbortSignal.timeout(615_000) });
+  if (!response.ok) throw new Error('The held runtime turn has ended.');
+  return response.json();
+}
+export async function runtimeReviewMain(mcp = false) {
+  if (mcp) return serveMcpStdio({ serverInfo: { name: RUNTIME_REVIEW_SERVER, version: '1.0.0' }, tools: TOOLS, rawResult: true, call: (name, input) => requestRuntime({ name, input }) });
+  try {
+    const { readFileSync } = await import('node:fs');
+    const result = await requestRuntime(JSON.parse(readFileSync(process.argv[3], 'utf8')));
+    // Shell tools are text transports. Never flood a model context with image
+    // base64; observe retains a local artifact that its image tool can inspect.
+    const content = result.content?.map(block => block.type === 'image' ? { type: 'text', text: 'Image shown in Live app. Use observe to retain it, then open the reported artifact with an available image tool. Capture alone does not establish visual inspection.' } : block);
+    process.stdout.write(JSON.stringify({ ...result, ...(content ? { content } : {}) }) + '\n'); process.exitCode = result.isError ? 1 : 0;
+  } catch (error) { process.stderr.write(error.message + '\n'); process.exitCode = 1; }
+}

package/bin/lib/uiReview.mjs

@@ -12,6 +12,7 @@ import { procStat } from './procStat.mjs';
 import { killGroup } from './processGroup.mjs';
 import { unattendedEnv } from './noWindowEnv.mjs';
 import { childEnv } from './childEnv.mjs';
+import { environmentOverlay, readWorktreeEnvironment } from './reviewEnvironment.mjs';
 import { gitRaw } from './git.mjs';
 import { serveMcpStdio } from './mcpStdio.mjs';
 import { scrub, learnExtraSecrets, forgetExtraSecrets } from './uplinkScrub.mjs';
@@ -172,8 +173,10 @@ export async function createUiReview({ wt, signal, capture = captureLocalReview,
       record.folder = `${ARTIFACT_DIR}/${name}`;
       record.artifact = `${record.folder}/report.json`;
       scratch = mkdtempSync(join(tmpdir(), 'flowviant-ui-preview-'));
-      const env = unattendedEnv(childEnv({ cwd }), { browserHome: scratch });
-      // No inherited personal home, SDK credentials or browser sessions.
+      const environment = readWorktreeEnvironment(wt);
+      const env = unattendedEnv({ ...childEnv({ cwd }), ...(environment ? environmentOverlay(environment) : {}) }, { browserHome: scratch });
+      // Only explicit scoped bindings join the minimal preview environment;
+      // no inherited personal home, SDK credentials or browser sessions.
       env.HOME = scratch; env.USERPROFILE = scratch; env.XDG_CONFIG_HOME = scratch;
       env.XDG_DATA_HOME = scratch; env.XDG_CACHE_HOME = scratch;
       let output = '';

package/bin/lib/work.mjs

@@ -67,6 +67,8 @@ import { placeTurnLockedByLivePid } from './turnLock.mjs';
 import { createWorkLocalCleanup } from './workLocalCleanup.mjs';
 import { createManagedLocalCleanup } from './managedLocalCleanup.mjs';
 import { trackedRepositorySetup } from './repositorySetup.mjs';
+import { sweepWorktreeEnvironments } from './reviewEnvironment.mjs';
+import { workLanesStopped } from './standDownGate.mjs';
 import { createRepositoryPlaces } from './repositoryPlaces.mjs';
 import { createAgentRepositories } from './agentRepositories.mjs';
 import { createWorkProcesses } from './workProcesses.mjs';
@@ -395,6 +397,7 @@ export function createWorkManager({
   // The check and the pre-review are built with only what each one uses; the
   // review entry beat is handed the two and owns only their order.
   const { runCheck } = createWorkAgentCheck({
+    baseRef,
     repoRoot,
     postBestEffort,
     workChildren,
@@ -461,6 +464,23 @@ export function createWorkManager({
     sweepMergedSessionBranch,
   });
 
+  let environmentSweep = null, lastEnvironmentSweep = 0;
+  const reconcileEnvironments = () => {
+    if (environmentSweep || workLanesStopped() || Date.now() - lastEnvironmentSweep < 60_000) return;
+    lastEnvironmentSweep = Date.now();
+    environmentSweep = (async () => {
+      const roots = [...new Set(repositories?.list().map(r => r.repoRoot).filter(Boolean) ?? [repoRoot])];
+      for (const root of roots) {
+        if (workLanesStopped()) break;
+        const result = await sweepWorktreeEnvironments(root, {
+          onSpawn: ch => { workChildren.set(ch, null); groupKillChildren.add(ch); },
+          onClose: ch => { workChildren.delete(ch); groupKillChildren.delete(ch); },
+        });
+        for (const failure of result.errors) warn(envScrub(`Environment ${failure.id}: ${failure.error}`));
+      }
+    })().catch(error => warn(envScrub(error.message))).finally(() => { environmentSweep = null; });
+  };
+
   const { processKillJobs } = createWorkProcesses({
     placeDir,
     reportPlaceWorktrees,
@@ -498,7 +518,7 @@ export function createWorkManager({
     workChildren.size > 0 ||
     workAnswering.size > 0 ||
     pendingWorkReports.size > 0 ||
-    pendingShipReports.size > 0 || cleanupBusy();
+    pendingShipReports.size > 0 || cleanupBusy() || environmentSweep !== null;
 
   return {
     flushWorkReports,
@@ -514,6 +534,7 @@ export function createWorkManager({
     retirePreviews,
     shutdownPreviews,
     retireWorkSessions,
+    reconcileEnvironments,
     reportWorktrees,
     reconcileIdleArtifacts,
     reconcileLocalCleanup,

package/bin/lib/workAgentCheck.mjs

@@ -21,6 +21,9 @@ import { scrub as envScrub } from './uplinkScrub.mjs';
 import { agentBrowserHome, openBrowserHome, unattendedEnv } from './noWindowEnv.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
 import { workLanesStopped } from './standDownGate.mjs';
+import { setupRepository } from './repositorySetup.mjs';
+import { readEnvironmentRecipe } from './reviewEnvironmentConfig.mjs';
+import { holdWorktreeEnvironment } from './reviewEnvironment.mjs';
 
 /**
  * CLEAR THE ARTIFACTS DIRECTORY OF ANYTHING THAT IS NOT AN ARTIFACT, BEFORE
@@ -135,6 +138,7 @@ export function readConfiguredCheck(root) {
 
 export function createWorkAgentCheck({
   repoRoot,
+  baseRef = () => 'HEAD',
   postBestEffort,
   workChildren,
   groupKillChildren,
@@ -184,6 +188,24 @@ export function createWorkAgentCheck({
       await postCheck({ agentId, status: 'none', ...(headSha ? { headSha } : {}) });
       return { status: 'none' };
     }
+    let environment = null, releaseEnvironment = () => {};
+    try {
+      const root = repository?.repoRoot ?? repoRoot;
+      const snapshot = readEnvironmentRecipe(root, repository?.baseRef ?? baseRef());
+      if (snapshot) {
+        // A combined merge has a different worktree/database from its input
+        // agents. Migrate its CURRENT integrated source before its checks.
+        environment = await setupRepository(root, wt, { snapshot,
+          onSpawn: ch => { workChildren.set(ch, agentId); groupKillChildren.add(ch); },
+          onClose: ch => { workChildren.delete(ch); groupKillChildren.delete(ch); } });
+        releaseEnvironment = holdWorktreeEnvironment(environment);
+      }
+    } catch (error) {
+      const text = envScrub(error.message);
+      await postCheck({ agentId, status: 'failed', output: text, ...(headSha ? { headSha } : {}) });
+      return { status: 'failed', text };
+    }
+    try {
     const cleared = clearNonArtifacts(wt);
     if (cleared.length)
       warn(
@@ -241,7 +263,7 @@ export function createWorkAgentCheck({
           shell: true,
           detached: true,
           stdio: ['ignore', 'pipe', 'pipe'],
-          env: checkEnv(process.env, browser.dir),
+          env: checkEnv(environment?.env ?? process.env, browser.dir),
         });
         /**
          * …AND IT IS TRACKED, so a stop or a takeover takes it with them.
@@ -330,6 +352,7 @@ export function createWorkAgentCheck({
       ...(headSha ? { headSha } : {}),
     });
     return out;
+    } finally { releaseEnvironment(); }
   };
 
   return { runCheck };

package/bin/lib/workAgentTools.mjs

@@ -28,6 +28,7 @@ import { machineMcpServers } from './claudeMachineMcp.mjs';
 import { ORCHESTRATOR_SERVER } from './orchestratorProtocol.mjs';
 import { VIDEO_SERVER } from './videoRender.mjs';
 import { BROWSER_SERVER } from './managedBrowser.mjs';
+import { RUNTIME_REVIEW_SERVER } from './runtimeReview.mjs';
 
 /** The servers the daemon itself mounts on a card turn, by the names the
  *  agent calls them: a multi-repository card's add_repository, an
@@ -35,7 +36,7 @@ import { BROWSER_SERVER } from './managedBrowser.mjs';
  *  render_video (2026-10-26), and a code turn's managed browser (2026-10-30).
  *  Never a project server's, whatever the base
  *  `.mcp.json` names. */
-export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review', video: VIDEO_SERVER, browser: BROWSER_SERVER });
+export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositories', orchestrator: ORCHESTRATOR_SERVER, uiReview: 'card_ui_review', video: VIDEO_SERVER, browser: BROWSER_SERVER, runtime: RUNTIME_REVIEW_SERVER });
 
 /**
  * The card turn's tools, prepared, and what it is told of them.
@@ -48,13 +49,13 @@ export const CARD_TURN_SERVERS = Object.freeze({ repositories: 'card_repositorie
  * from here), the note, the mount's part of the CLI's `mcpEnv` and whether it
  * needs one, and the keys the runner takes the mount as.
  */
-export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = null, videoConfig = null, browserConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
+export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources = [], repositoryTool = null, orchestratorConfig = null, uiReviewConfig = null, videoConfig = null, browserConfig = null, runtimeConfig = null, orchestrated = false, codexHome = null, env = process.env, machineServers = machineMcpServers }) {
   // A turn reads the base ref afresh. Changes the agent has made to its
   // own worktree cannot silently change the next turn's tools.
   const source = sources.find((r) => r.wt === wt);
-  const snapshot = readBaseTools(source?.repoRoot ?? repoRoot, source?.baseRef ?? baseRef());
+  const snapshot = readBaseTools(source?.repoRoot ?? repoRoot, source?.baseRef ?? baseRef(), env);
   for (const other of sources.filter((r) => r !== source)) {
-    const base = readBaseTools(other.repoRoot, other.baseRef);
+    const base = readBaseTools(other.repoRoot, other.baseRef, env);
     snapshot.instructions.push(...[...base.instructions, ...base.skillFiles].map((file) => ({ ...file, path: `repositories/${other.folder}/${file.path}` })));
   }
   const projectTools = prepareAgentTools(snapshot, rt, env, wt, { codexHome, fenced: posture !== 'build', turnServers: {
@@ -62,6 +63,7 @@ export function prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources =
     ...(orchestratorConfig ? { [CARD_TURN_SERVERS.orchestrator]: orchestratorConfig } : {}),
     ...(posture === 'build' && uiReviewConfig ? { [CARD_TURN_SERVERS.uiReview]: uiReviewConfig } : {}),
     ...(posture === 'build' && browserConfig ? { [CARD_TURN_SERVERS.browser]: browserConfig } : {}),
+    ...(posture === 'build' && runtimeConfig ? { [CARD_TURN_SERVERS.runtime]: runtimeConfig } : {}),
     // A video card's render tool rides its fenced posture (videoRender.mjs).
     ...(videoConfig ? { [CARD_TURN_SERVERS.video]: videoConfig } : {}),
   } });