flowviant 0.125.29 → 0.125.30

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 } : {}),
   } });

package/bin/lib/workAgentTurnExecution.mjs

@@ -73,6 +73,11 @@ import { createVideoRender } from './videoRender.mjs';
 import { createManagedBrowser } from './managedBrowser.mjs';
 import { completeBrowserReview, browserHandoffPrompt } from './browserHandoff.mjs';
 import { withUiReview, appendUiReviewEvidence } from './uiReviewTurn.mjs';
+import { setupRepository } from './repositorySetup.mjs';
+import { readEnvironmentRecipe } from './reviewEnvironmentConfig.mjs';
+import { environmentInstructions, environmentOverlay, holdWorktreeEnvironment } from './reviewEnvironment.mjs';
+import { environmentCredentialNames } from './reviewDatabase.mjs';
+import { createRuntimeReview } from './runtimeReview.mjs';
 
 export function createAgentTurnExecution({
   admit,
@@ -105,6 +110,7 @@ export function createAgentTurnExecution({
   makeUiReview = createUiReview,
   makeVideoRender = createVideoRender,
   makeManagedBrowser = createManagedBrowser,
+  makeRuntimeReview = createRuntimeReview,
 }) {
   const reportDelivery = createDeliveryReporter();
   /** How long the final flush may hold the settle. Bounded because the settle
@@ -126,6 +132,7 @@ export function createAgentTurnExecution({
    *  `interruptAgentTurns`); absent, nothing can interrupt it. */
   const runAgentTurnInPlace = async (job, { turnId, agentId, place, releaseSlot, postAgentTurn, measured, run = { interrupted: false } }) => {
     let repositoryRun = null;
+    const environmentReleases = [];
     const setupController = new AbortController();
     run.abortSetup = () => setupController.abort();
     if (run.interrupted) setupController.abort();
@@ -417,6 +424,8 @@ export function createAgentTurnExecution({
     let browserNote = '';
     let uiReviewNote = '';
     let uiReviewEvidence = '';
+    let environmentNote = '', reviewEnv = null;
+    let runtimeReview = null, runtimeNote = '', runtimeEvidence = '';
     // A video card's render tool (videoRender.mjs), and the words a turn
     // gets when it could not be held, so it stops rather than guesses.
     let videoRender = null;
@@ -430,6 +439,8 @@ export function createAgentTurnExecution({
       args = withUiReview(args, uiReviewNote, uiReview?.env);
       args = withUiReview(args, videoNote);
       args = withUiReview(args, browserNote, managedBrowser?.env);
+      args = withUiReview(args, environmentNote, reviewEnv);
+      args = withUiReview(args, runtimeNote, runtimeReview?.env);
       args.managedBrowser = Boolean(managedBrowser);
       return runTurnImpl(args);
     };
@@ -480,6 +491,22 @@ export function createAgentTurnExecution({
     let orchestrator = null;
     let intermediateDelivery = null;
     try {
+      if (posture === 'build') {
+        const sources = repositoryRun?.sources ?? [{ wt, repoRoot: worktreeRepo, baseRef: baseRef() }];
+        const administrativeNames = new Set();
+        for (const source of sources) {
+          const snapshot = readEnvironmentRecipe(source.repoRoot, source.baseRef);
+          if (!snapshot) continue;
+          const environment = await setupRepository(source.repoRoot, source.wt, { snapshot, signal: setupController.signal,
+            onSpawn: ch => { workChildren.set(ch, agentId); groupKillChildren?.add(ch); },
+            onClose: ch => { workChildren.delete(ch); groupKillChildren?.delete(ch); } });
+          environmentReleases.push(holdWorktreeEnvironment(environment));
+          environmentNote += '\n' + environmentInstructions(environment);
+          for (const name of environmentCredentialNames(snapshot.recipe)) administrativeNames.add(name);
+          if (source.wt === wt) reviewEnv = environmentOverlay(environment);
+        }
+        if (administrativeNames.size) reviewEnv = { ...reviewEnv, ...Object.fromEntries([...administrativeNames].map(name => [name, undefined])) };
+      }
       if (posture === 'build' && job.kind !== 'merge_resolve' && ['claude', 'codex'].includes(rt)) {
         try {
           managedBrowser = await makeManagedBrowser({ wt, turnId, signal: setupController.signal, onChild: ch => {
@@ -490,6 +517,14 @@ export function createAgentTurnExecution({
         } catch (error) { browserNote = `The managed browser could not start: ${envScrub(error.message)}. Report interactive browser checks unavailable.`; }
       }
       if (posture === 'build' && job.kind !== 'merge_resolve') {
+        try {
+          runtimeReview = await makeRuntimeReview({ wt, repoRoot: worktreeRepo, baseRef: baseRef(), sources: repositoryRun?.sources ?? [],
+            browser: managedBrowser, signal: setupController.signal, onChild: ch => {
+              workChildren.set(ch, agentId); groupKillChildren?.add(ch);
+              return () => { workChildren.delete(ch); groupKillChildren?.delete(ch); };
+            } });
+          runtimeNote = runtimeReview?.instructions ?? '';
+        } catch (error) { runtimeNote = `Configured runtime review is unavailable: ${envScrub(error.message)}. Use the repository’s existing checks and report unavailable runtime verification.`; }
         try {
           uiReview = await makeUiReview({ wt, signal: setupController.signal, onChild: ch => {
             workChildren.set(ch, agentId); groupKillChildren?.add(ch);
@@ -515,7 +550,9 @@ export function createAgentTurnExecution({
           notify: message => liveInput ? run.live?.inject(message) === true : false,
           taken: id => run.live?.onTaken(id) });
       }
-      const tools = prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources: repositoryRun?.sources ?? [], repositoryTool: repositoryRun?.tool ?? null, orchestratorConfig: orchestrator?.config ?? null, uiReviewConfig: uiReview?.config, videoConfig: videoRender?.config ?? null, browserConfig: managedBrowser?.config, orchestrated: Boolean(orchestrator), codexHome: agentResume.codexHome });
+      const tools = prepareCardTools({ rt, posture, wt, repoRoot, baseRef, sources: repositoryRun?.sources ?? [], repositoryTool: repositoryRun?.tool ?? null, orchestratorConfig: orchestrator?.config ?? null, uiReviewConfig: uiReview?.config, videoConfig: videoRender?.config ?? null, browserConfig: managedBrowser?.config, orchestrated: Boolean(orchestrator), codexHome: agentResume.codexHome,
+        runtimeConfig: runtimeReview?.config,
+        ...(reviewEnv ? { env: { ...process.env, ...reviewEnv } } : {}) });
       projectTools = tools.projectTools;
       localCleanup?.begin(turnId);
       const { toolsNote } = tools;
@@ -794,12 +831,15 @@ export function createAgentTurnExecution({
       // owned by its review tool, then bind evidence to the final source
       // before the existing artifact upload and delivery settlement.
       try { await videoRender?.close(); } catch { /* a closed listener */ }
+      try { await runtimeReview?.close(); } catch { /* turn teardown continues */ }
       try { await managedBrowser?.close(); } catch { /* turn teardown continues */ }
       try { await uiReview?.close(); }
       finally {
         try { uiReviewEvidence = uiReview?.finalize() ?? uiReviewEvidence; }
         catch (error) { uiReviewEvidence = `Local UI review final source/evidence measurement unavailable: ${envScrub(error.message)}. Earlier checks do not establish the final source.`; }
       }
+      try { runtimeEvidence = runtimeReview?.finalize() ?? ''; }
+      catch { runtimeEvidence = 'Runtime review final source could not be measured; earlier results do not verify final source.'; }
       await run.live?.stop();
       await orchestrator?.close(run.interrupted);
       await brief?.stop();
@@ -910,6 +950,7 @@ export function createAgentTurnExecution({
       modelExports: intermediateDelivery?.modelExports,
     });
     appendUiReviewEvidence(body, uiReviewEvidence);
+    appendUiReviewEvidence(body, runtimeEvidence);
     // The agent's own account of what it did not deliver, for the pre-review.
     if (job.kind === 'task' && job.task && body.outcome === 'delivered' && res?.gaps)
       stashGaps(sessionMetaPath(wt, 'flowviant-agent-cards', agentId), job.task.id, res.gaps);
@@ -965,7 +1006,10 @@ export function createAgentTurnExecution({
     // hold the lock on — see `runReviewEntry`. Only after the settle that may
     // say delivered: the three `nothing` settles never opened it.
     if (final && reply?.review === true) await runReviewEntry(agentId, wt, job.agentName, undefined, job);
-    } finally { await repositoryRun?.tool?.close(); }
+    } finally {
+      for (const release of environmentReleases) release();
+      await repositoryRun?.tool?.close();
+    }
   };
 
   return { runAgentTurnInPlace };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.125.29",
+  "version": "0.125.30",
   "description": "Run your own coding CLIs as build agents for Flowviant \u2014 Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {