atris 3.42.0 → 3.44.0

package/lib/fleet.js

@@ -15,7 +15,7 @@ const fs = require('fs');
 const crypto = require('crypto');
 const os = require('os');
 const path = require('path');
-const { spawnSync } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const {
   appendBriefRecord,
   mirrorBriefRecord,
@@ -33,6 +33,14 @@ const { listWorktrees } = require('../commands/worktree');
 const { isConductorStatusLine } = require('./conductor-artifacts');
 const { matchLessons } = require('./lesson-preflight');
 const { matchTaste } = require('./taste-lessons');
+const { buildVerifiedScoutPack, appendVerifiedScoutPack } = require('./dispatch-scout');
+const {
+  applySecretGrantEnvironment,
+  buildGatewaySupervisorScript,
+  spawnBlocking,
+  PROXY_ENV_KEYS: SECRET_GATEWAY_PROXY_ENV_KEYS,
+} = require('./secret-gateway');
+const { appendEngineLiveLogChunk, createEngineLiveLog, engineTerminalReason } = require('./engine-job-lifecycle');
 
 // Lanes a fleet may never staff on its own: the human keeps irreversible
 // calls. Mirrors the autoland denied lanes.
@@ -66,6 +74,15 @@ const METHOD_KERNEL = [
   'Smallest diff that satisfies Done wins; prefer deleting code over adding it.',
 ];
 
+const ATRIS_BUILD_PROCESS_PREAMBLE = [
+  'you are set up to do this well.',
+  'use the atris process:',
+  'claim the task, read the map, and work only the named contract.',
+  'run every gate bare and read its real exit code.',
+  'report honestly, including failures, and stop at the named stop point.',
+  'never use --no-verify.',
+].join('\n');
+
 // The bounded prompt every engine gets. Same contract the manual flight used:
 // isolated worktree, commit never push, MAP first, focused verify, report.
 function buildFleetPrompt(task, { worktreePath, yolo = false } = {}) {
@@ -79,6 +96,8 @@ function buildFleetPrompt(task, { worktreePath, yolo = false } = {}) {
   const lines = [
     'First, run `atris worktree guard`; if it fails, stop immediately, report back, and do not edit anything. Do this before any file edit.',
     '',
+    ATRIS_BUILD_PROCESS_PREAMBLE,
+    '',
     `You are working task ${ref} in this repo checkout (an isolated git worktree${worktreePath ? ` at ${worktreePath}` : ''} — commit here, NEVER push).`,
     '',
     `Task: ${title}`,
@@ -141,6 +160,9 @@ const YOLO_ENGINE_FLAGS = Object.freeze({
   claude: '--dangerously-skip-permissions',
 });
 const DISPATCH_SELF_LAND_TARGET = 'origin/master';
+const DEFAULT_DISPATCH_TIMEOUT_MS = 900000;
+const CODEX_DISPATCH_TIMEOUT_MS = 3660000;
+const CODEX_WATCHDOG_SOURCE = path.join(__dirname, '..', 'scripts', 'det', 'codex-watchdog.js');
 
 function realpathOrResolve(value) {
   const resolved = path.resolve(String(value));
@@ -164,7 +186,16 @@ function assertIsolatedWorktree(worktreePath, root = process.cwd()) {
   return { worktreePath: resolvedWorktree, primaryRoot };
 }
 
-function buildEngineCommand(engineName, promptFile, { yolo = false, sealed = false, allowedTools = FLEET_ALLOWED_TOOLS } = {}) {
+function wrapCodexWithWatchdog(cmd, watchdogPath = CODEX_WATCHDOG_SOURCE, receiptPath = '') {
+  // Codex hangs forever at startup when stdin is an open pipe (three real
+  // flights on 2026-08-11 sat 50-100 minutes at zero CPU). Force every fleet
+  // codex spawn through the silent-start / runtime-cap watchdog with stdin
+  // sealed, so orchestrator prompts cannot forget the convention.
+  const receiptArg = receiptPath ? ` --receipt ${shellSingleQuote(receiptPath)}` : '';
+  return `${shellSingleQuote(process.execPath)} ${shellSingleQuote(watchdogPath)} --startup-deadline 90 --max-runtime 3600${receiptArg} -- sh -c ${shellSingleQuote(cmd)} </dev/null`;
+}
+
+function buildEngineCommand(engineName, promptFile, { yolo = false, sealed = false, allowedTools = FLEET_ALLOWED_TOOLS, watchdogPath = CODEX_WATCHDOG_SOURCE, watchdogReceiptPath = '' } = {}) {
   if (!RUNNER_PROFILE_DEFS[engineName]) throw new Error(`unknown engine "${engineName}"`);
   const prev = process.env.ATRIS_RUNNER_PROFILE;
   process.env.ATRIS_RUNNER_PROFILE = engineName;
@@ -187,6 +218,7 @@ function buildEngineCommand(engineName, promptFile, { yolo = false, sealed = fal
     if (engineName === 'devin') return cmd.replace(/^devin -p /, 'devin -p --permission-mode dangerous ');
     if (yolo && engineName === 'codex') cmd = cmd.replace(/\bexec\b/, `exec ${YOLO_ENGINE_FLAGS.codex}`);
     if (yolo && engineName === 'claude') cmd = `${cmd} ${YOLO_ENGINE_FLAGS.claude}`;
+    if (engineName === 'codex') cmd = wrapCodexWithWatchdog(cmd, watchdogPath, watchdogReceiptPath);
     return cmd;
   } finally {
     if (prev === undefined) delete process.env.ATRIS_RUNNER_PROFILE;
@@ -246,65 +278,173 @@ function terminateSameSandboxProfile(executable, args, options) {
   });
 }
 
+function spawnWithOutputChunks(executable, args, options = {}) {
+  const {
+    encoding,
+    input,
+    onOutputChunk,
+    timeout,
+    ...childOptions
+  } = options;
+  const child = spawn(executable, args, {
+    ...childOptions,
+    stdio: [input == null ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+  });
+  if (input != null && child.stdin) {
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  }
+
+  const stdoutChunks = [];
+  const stderrChunks = [];
+  let spawnError = null;
+  let timeoutError = null;
+  const capture = (chunks, stream) => (chunk) => {
+    chunks.push(Buffer.from(chunk));
+    if (typeof onOutputChunk === 'function') onOutputChunk(chunk, stream);
+  };
+  child.stdout.on('data', capture(stdoutChunks, 'stdout'));
+  child.stderr.on('data', capture(stderrChunks, 'stderr'));
+  child.on('error', (error) => { spawnError = error; });
+
+  return new Promise((resolve) => {
+    const timer = Number(timeout) > 0
+      ? setTimeout(() => {
+        timeoutError = new Error('spawn ETIMEDOUT');
+        timeoutError.code = 'ETIMEDOUT';
+        try { child.kill('SIGKILL'); } catch {}
+      }, Number(timeout))
+      : null;
+    child.once('close', (status, signal) => {
+      if (timer) clearTimeout(timer);
+      const encode = (chunks) => {
+        const output = Buffer.concat(chunks);
+        return encoding ? output.toString(encoding) : output;
+      };
+      resolve({
+        pid: child.pid,
+        status,
+        signal,
+        stdout: encode(stdoutChunks),
+        stderr: encode(stderrChunks),
+        error: timeoutError || spawnError,
+      });
+    });
+  });
+}
+
 function runInReapedProcessGroup(executable, args, options, controlDir, statusFile) {
   if (!controlDir || !statusFile) throw new Error('sealed execution requires isolated control and status paths');
   const supervisor = path.join(controlDir, 'sandbox-supervisor.js');
   const stateFile = path.join(controlDir, 'sandbox-process.json');
   const leaseFile = path.join(controlDir, 'sandbox-process.lease');
-  fs.writeFileSync(supervisor, [
-    "'use strict';",
-    "const fs = require('node:fs');",
-    "const { spawn, spawnSync } = require('node:child_process');",
-    "const [stateFile, leaseFile, statusFile, executable, ...args] = process.argv.slice(2);",
-    "const leaseFd = fs.openSync(leaseFile, 'w', 0o600);",
-    "const statusFd = fs.openSync(statusFile, 'w', 0o600);",
-    "const child = spawn(executable, args, { cwd: process.cwd(), env: process.env, detached: true, stdio: ['ignore', 'inherit', 'inherit', leaseFd, statusFd] });",
-    "fs.closeSync(leaseFd);",
-    "fs.closeSync(statusFd);",
-    "fs.writeFileSync(stateFile, JSON.stringify({ pgid: child.pid, cwd: process.cwd() }) + '\\n', { mode: 0o600 });",
-    "let stopping = false;",
-    "const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));",
-    "function trackedPids() {",
-    "  const pids = new Set();",
-    "  for (const [bin, argv] of [['/usr/bin/pgrep', ['-g', String(child.pid)]], ['/usr/sbin/lsof', ['-t', leaseFile]], ['/usr/sbin/lsof', ['-a', '-d', 'cwd', '+D', process.cwd(), '-t']]]) {",
-    "    const found = spawnSync(bin, argv, { encoding: 'utf8' });",
-    "    for (const value of String(found.stdout || '').trim().split(/\\s+/)) {",
-    "      const pid = Number(value);",
-    "      if (Number.isInteger(pid) && pid > 0) pids.add(pid);",
-    "    }",
-    "  }",
-    "  pids.delete(process.pid);",
-    "  return [...pids];",
-    "}",
-    "async function stop(code) {",
-    "  if (stopping) return;",
-    "  stopping = true;",
-    "  if (executable === '/usr/bin/sandbox-exec' && args[0] === '-p' && args[1]) {",
-    "    spawnSync(executable, ['-p', args[1], '/bin/kill', '-KILL', '-1'], { cwd: process.cwd(), env: process.env, stdio: 'ignore', timeout: 5000 });",
-    "  }",
-    "  for (const [signal, delay] of [['SIGTERM', 100], ['SIGKILL', 100], ['SIGKILL', 100]]) {",
-    "    try { process.kill(-child.pid, signal); } catch {}",
-    "    for (const pid of trackedPids()) { try { process.kill(pid, signal); } catch {} }",
-    "    await wait(delay);",
-    "  }",
-    "  let exitCode = Number.isInteger(code) ? code : 128;",
-    "  try {",
-    "    const savedText = fs.readFileSync(statusFile, 'utf8').trim();",
-    "    const saved = Number(savedText);",
-    "    if (savedText && Number.isInteger(saved) && saved >= 0 && saved <= 255) exitCode = saved;",
-    "  } catch {}",
-    "  process.exit(exitCode);",
-    "}",
-    "child.once('error', () => { void stop(1); });",
-    "child.once('exit', (code) => { void stop(code); });",
-    "for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => { void stop(143); });",
-    '',
-  ].join('\n'), { mode: 0o700 });
+  const { onOutputChunk, ...baseSpawnOptions } = options;
+  const spawnEnv = { ...(baseSpawnOptions.env || {}) };
+  const gatewayPlanRaw = spawnEnv.ATRIS_ONE_LAP_SECRET_GATEWAY;
+  let gatewayInput = null;
+  if (gatewayPlanRaw) {
+    let plan;
+    try { plan = JSON.parse(gatewayPlanRaw); } catch {
+      throw new Error('secret gateway plan is not valid json');
+    }
+    const secretEnv = String(plan && plan.grant && plan.grant.secretEnv || '');
+    const secret = String(process.env[secretEnv] || '');
+    if (!secretEnv || !secret) throw new Error('secret grant requires the parent secret value on stdin path');
+    gatewayInput = JSON.stringify({
+      grant: plan.grant,
+      placeholder: plan.placeholder,
+      secret,
+      upstreamPort: plan.upstreamPort,
+      upstreamAddress: plan.upstreamAddress,
+      rejectUnauthorized: plan.rejectUnauthorized,
+    });
+    delete spawnEnv.ATRIS_ONE_LAP_SECRET_GATEWAY;
+    spawnEnv.ATRIS_ONE_LAP_SECRET_GATEWAY_STDIN = '1';
+    fs.writeFileSync(supervisor, buildGatewaySupervisorScript(require.resolve('./secret-gateway')), { mode: 0o700 });
+  } else {
+    fs.writeFileSync(supervisor, [
+      "'use strict';",
+      "const fs = require('node:fs');",
+      "const { spawn, spawnSync } = require('node:child_process');",
+      "const [stateFile, leaseFile, statusFile, executable, ...args] = process.argv.slice(2);",
+      "const leaseFd = fs.openSync(leaseFile, 'w', 0o600);",
+      "const statusFd = fs.openSync(statusFile, 'w', 0o600);",
+      "const child = spawn(executable, args, { cwd: process.cwd(), env: process.env, detached: true, stdio: ['ignore', 'inherit', 'inherit', leaseFd, statusFd] });",
+      "fs.closeSync(leaseFd);",
+      "fs.closeSync(statusFd);",
+      "fs.writeFileSync(stateFile, JSON.stringify({ pgid: child.pid, cwd: process.cwd() }) + '\\n', { mode: 0o600 });",
+      "let stopping = false;",
+      "const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));",
+      "function trackedPids() {",
+      "  const pids = new Set();",
+      "  for (const [bin, argv] of [['/usr/bin/pgrep', ['-g', String(child.pid)]], ['/usr/sbin/lsof', ['-t', leaseFile]], ['/usr/sbin/lsof', ['-a', '-d', 'cwd', '+D', process.cwd(), '-t']]]) {",
+      "    const found = spawnSync(bin, argv, { encoding: 'utf8' });",
+      "    for (const value of String(found.stdout || '').trim().split(/\\s+/)) {",
+      "      const pid = Number(value);",
+      "      if (Number.isInteger(pid) && pid > 0) pids.add(pid);",
+      "    }",
+      "  }",
+      "  pids.delete(process.pid);",
+      "  return [...pids];",
+      "}",
+      "async function stop(code) {",
+      "  if (stopping) return;",
+      "  stopping = true;",
+      "  if (executable === '/usr/bin/sandbox-exec' && args[0] === '-p' && args[1]) {",
+      "    spawnSync(executable, ['-p', args[1], '/bin/kill', '-KILL', '-1'], { cwd: process.cwd(), env: process.env, stdio: 'ignore', timeout: 5000 });",
+      "  }",
+      "  for (const [signal, delay] of [['SIGTERM', 100], ['SIGKILL', 100], ['SIGKILL', 100]]) {",
+      "    try { process.kill(-child.pid, signal); } catch {}",
+      "    for (const pid of trackedPids()) { try { process.kill(pid, signal); } catch {} }",
+      "    await wait(delay);",
+      "  }",
+      "  let exitCode = Number.isInteger(code) ? code : 128;",
+      "  try {",
+      "    const savedText = fs.readFileSync(statusFile, 'utf8').trim();",
+      "    const saved = Number(savedText);",
+      "    if (savedText && Number.isInteger(saved) && saved >= 0 && saved <= 255) exitCode = saved;",
+      "  } catch {}",
+      "  process.exit(exitCode);",
+      "}",
+      "child.once('error', () => { void stop(1); });",
+      "child.once('exit', (code) => { void stop(code); });",
+      "for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(signal, () => { void stop(143); });",
+      '',
+    ].join('\n'), { mode: 0o700 });
+  }
+  const spawnOptions = { ...baseSpawnOptions, env: spawnEnv };
+  if (gatewayInput) spawnOptions.input = gatewayInput;
+  if (gatewayInput) {
+    const exitFile = path.join(controlDir, 'sandbox-supervisor.exit');
+    return spawnBlocking(
+      process.execPath,
+      [supervisor, exitFile, stateFile, leaseFile, statusFile, executable, ...args],
+      {
+        ...spawnOptions,
+        exitFile,
+        onStdoutChunk: onOutputChunk ? (chunk) => onOutputChunk(chunk, 'stdout') : undefined,
+        onStderrChunk: onOutputChunk ? (chunk) => onOutputChunk(chunk, 'stderr') : undefined,
+      },
+    ).finally(() => {
+      terminateSameSandboxProfile(executable, args, spawnOptions);
+      terminateTrackedSandbox(stateFile, leaseFile);
+    });
+  }
+  if (onOutputChunk) {
+    return spawnWithOutputChunks(
+      process.execPath,
+      [supervisor, stateFile, leaseFile, statusFile, executable, ...args],
+      { ...spawnOptions, onOutputChunk },
+    ).finally(() => {
+      terminateSameSandboxProfile(executable, args, spawnOptions);
+      terminateTrackedSandbox(stateFile, leaseFile);
+    });
+  }
   let result;
   try {
-    result = spawnSync(process.execPath, [supervisor, stateFile, leaseFile, statusFile, executable, ...args], options);
+    result = spawnSync(process.execPath, [supervisor, stateFile, leaseFile, statusFile, executable, ...args], spawnOptions);
   } finally {
-    terminateSameSandboxProfile(executable, args, options);
+    terminateSameSandboxProfile(executable, args, spawnOptions);
     terminateTrackedSandbox(stateFile, leaseFile);
   }
   return result;
@@ -338,10 +478,14 @@ function dispatchResultOutput(result) {
 }
 
 function dispatchResultExitCode(result) {
-  if (!result || typeof result !== 'object') return 0;
-  if (Object.prototype.hasOwnProperty.call(result, 'exitCode')) return result.exitCode;
-  if (Object.prototype.hasOwnProperty.call(result, 'status')) return result.status;
-  return 0;
+  if (!result || typeof result !== 'object') return null;
+  if (Object.prototype.hasOwnProperty.call(result, 'exitCode')) {
+    return Number.isInteger(result.exitCode) ? result.exitCode : null;
+  }
+  if (Object.prototype.hasOwnProperty.call(result, 'status')) {
+    return Number.isInteger(result.status) ? result.status : null;
+  }
+  return null;
 }
 
 // A child killed by a signal comes back either with spawnSync's `signal` field
@@ -400,13 +544,19 @@ function stampDispatchBrief(root, briefId, result, note) {
 }
 
 function detectDeadEngineDispatch(result) {
-  const exitCode = dispatchResultExitCode(result);
-  if (exitCode === 0) return null;
-  const output = dispatchResultOutput(result).toLowerCase();
-  const pattern = DEAD_ENGINE_OUTPUT_PATTERNS.find((p) => output.includes(p));
-  if (pattern) return { reason: 'usage_limit', pattern };
+  const terminal = dispatchResultToTerminal({}, result);
+  const exitCode = terminal.exit_code;
   const signal = dispatchResultSignal(result);
   if (signal) return { reason: 'signalled', signal, exitCode };
+  if (terminal.reason === 'ok') return null;
+  const output = dispatchResultOutput(result).toLowerCase();
+  const pattern = Number.isInteger(exitCode) && exitCode !== 0
+    ? DEAD_ENGINE_OUTPUT_PATTERNS.find((p) => output.includes(p))
+    : null;
+  if (pattern) return { reason: 'usage_limit', pattern };
+  if (terminal.reason === 'no_output' || terminal.reason === 'unknown' || terminal.reason === 'timeout' || terminal.reason === 'cancelled') {
+    return { reason: terminal.reason, exitCode };
+  }
   return { reason: 'nonzero_exit', exitCode };
 }
 
@@ -468,6 +618,7 @@ function failedDispatchLeg(result, engineName) {
     leg.signal = signal;
     if (!report) leg.report = `(no report: killed by ${signal})`;
   }
+  if (result && result.watchdog_receipt) leg.watchdog_receipt = result.watchdog_receipt;
   return leg;
 }
 
@@ -478,9 +629,23 @@ async function dispatchEntryWithRestaff({
   dispatch,
   installedEngines = null,
   restaffState,
+  scoutAsk,
 }) {
+  const basePrompt = entry.prompt || buildFleetPrompt(entry.task, { worktreePath: entry.worktreePath, yolo: entry.yolo });
+  let scoutPackPromise = null;
+  const scoutPack = () => {
+    if (scoutAsk === false) return Promise.resolve(null);
+    if (!scoutPackPromise) {
+      scoutPackPromise = buildVerifiedScoutPack({
+        task: entry.task,
+        worktreePath: entry.worktreePath,
+        ask: typeof scoutAsk === 'function' ? scoutAsk : undefined,
+      });
+    }
+    return scoutPackPromise;
+  };
   const runOnce = async (engineName) => {
-    const prompt = entry.prompt || buildFleetPrompt(entry.task, { worktreePath: entry.worktreePath, yolo: entry.yolo });
+    const prompt = appendVerifiedScoutPack(basePrompt, await scoutPack(), { worktreePath: entry.worktreePath });
     const brief = captureDispatchBrief({
       root,
       task: entry.task,
@@ -538,7 +703,7 @@ async function dispatchEntryWithRestaff({
 // injectable for tests. `prompt` is injectable too: a caller-supplied prompt
 // (e.g. `atris engine dispatch --prompt-file`) skips the generated
 // buildFleetPrompt text entirely.
-function dispatchToEngine({ task, engine, worktreePath, root = process.cwd(), timeoutMs = 900000, runner = null, prompt: promptOverride = '', yolo = false, sealed = false, briefId = '', skipBriefCapture = false, environment = null, allowedTools = FLEET_ALLOWED_TOOLS }) {
+function dispatchToEngine({ task, engine, worktreePath, root = process.cwd(), timeoutMs = null, runner = null, prompt: promptOverride = '', yolo = false, sealed = false, briefId = '', skipBriefCapture = false, environment = null, allowedTools = FLEET_ALLOWED_TOOLS, liveLogPath = '' }) {
   assertIsolatedWorktree(worktreePath, root);
   const prompt = promptOverride || buildFleetPrompt(task, { worktreePath, yolo });
   let capturedBriefId = briefId;
@@ -547,9 +712,28 @@ function dispatchToEngine({ task, engine, worktreePath, root = process.cwd(), ti
   }
   const runtimeDir = String(environment && environment.ATRIS_ONE_LAP_RUNTIME_DIR || '');
   const promptFile = path.join(sealed && runtimeDir ? runtimeDir : path.join(worktreePath, '.atris'), `fleet-prompt-${task.display_id || 'task'}.md`);
-  fs.mkdirSync(path.dirname(promptFile), { recursive: true });
+  const runtimePath = path.dirname(promptFile);
+  fs.mkdirSync(runtimePath, { recursive: true });
   fs.writeFileSync(promptFile, prompt);
-  const command = buildEngineCommand(engine, promptFile, { yolo, sealed, allowedTools });
+  let watchdogPath = CODEX_WATCHDOG_SOURCE;
+  let watchdogArtifact = '';
+  if (engine === 'codex') {
+    watchdogPath = path.join(runtimePath, 'codex-watchdog.js');
+    fs.copyFileSync(CODEX_WATCHDOG_SOURCE, watchdogPath);
+    const artifactDir = path.join(worktreePath, '.atris');
+    fs.mkdirSync(artifactDir, { recursive: true });
+    watchdogArtifact = path.join(artifactDir, `codex-watchdog-${task.display_id || 'task'}-${crypto.randomBytes(4).toString('hex')}.json`);
+  }
+  const command = buildEngineCommand(engine, promptFile, {
+    yolo,
+    sealed,
+    allowedTools,
+    watchdogPath,
+    watchdogReceiptPath: watchdogArtifact,
+  });
+  const dispatchTimeoutMs = timeoutMs === null || timeoutMs === undefined
+    ? (engine === 'codex' ? CODEX_DISPATCH_TIMEOUT_MS : DEFAULT_DISPATCH_TIMEOUT_MS)
+    : timeoutMs;
   const exec = runner || ((cmd) => {
     const childEnv = sealed && environment
       ? { ...environment }
@@ -564,6 +748,11 @@ function dispatchToEngine({ task, engine, worktreePath, root = process.cwd(), ti
     delete childEnv.ATRIS_ONE_LAP_CONTROL_DIR;
     delete childEnv.ATRIS_ONE_LAP_LIFECYCLE_WRAPPER;
     delete childEnv.ATRIS_ONE_LAP_STATUS_FILE;
+    let deferredCleanup = false;
+    const cleanup = () => {
+      if (cleanupRuntimeDir) fs.rmSync(cleanupRuntimeDir, { recursive: true, force: true });
+      if (cleanupControlDir) fs.rmSync(cleanupControlDir, { recursive: true, force: true });
+    };
     try {
       const executable = sandboxProfile ? '/usr/bin/sandbox-exec' : 'sh';
       const args = sandboxProfile
@@ -573,29 +762,49 @@ function dispatchToEngine({ task, engine, worktreePath, root = process.cwd(), ti
         cwd: worktreePath,
         env: childEnv,
         encoding: 'utf8',
-        timeout: timeoutMs,
+        timeout: dispatchTimeoutMs,
       };
-      return sandboxProfile
+      if (liveLogPath) {
+        fs.mkdirSync(path.dirname(liveLogPath), { recursive: true });
+        spawnOptions.onOutputChunk = (chunk) => appendEngineLiveLogChunk(liveLogPath, chunk);
+      }
+      const run = sandboxProfile
         ? runInReapedProcessGroup(executable, args, spawnOptions, cleanupControlDir, statusFile)
-        : spawnSync(executable, args, spawnOptions);
+        : (liveLogPath ? spawnWithOutputChunks(executable, args, spawnOptions) : spawnSync(executable, args, spawnOptions));
+      if (run && typeof run.then === 'function') {
+        deferredCleanup = true;
+        return run.finally(cleanup);
+      }
+      return run;
     } finally {
-      if (cleanupRuntimeDir) fs.rmSync(cleanupRuntimeDir, { recursive: true, force: true });
-      if (cleanupControlDir) fs.rmSync(cleanupControlDir, { recursive: true, force: true });
+      if (!deferredCleanup) cleanup();
     }
   });
-  const result = exec(command);
-  return {
-    task: task.display_id || task.id,
-    engine,
-    worktreePath,
-    promptFile,
-    brief_id: capturedBriefId || null,
-    command,
-    exitCode: result.status,
-    signal: result.signal || null,
-    report: String(result.stdout || '').slice(-8000),
-    stderr: String(result.stderr || '').slice(-2000),
+  const result = exec(command, { timeoutMs: dispatchTimeoutMs });
+  const toDispatch = (run) => {
+    let watchdogReceipt = null;
+    if (watchdogArtifact && fs.existsSync(watchdogArtifact)) {
+      try { watchdogReceipt = JSON.parse(fs.readFileSync(watchdogArtifact, 'utf8')); } catch {}
+    }
+    return {
+      task: task.display_id || task.id,
+      engine,
+      worktreePath,
+      promptFile,
+      brief_id: capturedBriefId || null,
+      command,
+      watchdog_artifact: watchdogArtifact || null,
+      watchdog_receipt: watchdogReceipt,
+      exitCode: Number.isInteger(run.status) ? run.status : null,
+      signal: run.signal || null,
+      timed_out: Boolean(run.error && run.error.code === 'ETIMEDOUT'),
+      cancelled: Boolean(run.cancelled),
+      report: String(run.stdout || '').slice(-8000),
+      stderr: String(run.stderr || '').slice(-2000),
+    };
   };
+  if (result && typeof result.then === 'function') return result.then(toDispatch);
+  return toDispatch(result);
 }
 
 // ---------------------------------------------------------------------------
@@ -686,6 +895,21 @@ function clipHeadTail(text, { head = 400, tail = 300 } = {}) {
   return `${s.slice(0, head)}\n...\n${s.slice(-tail)}`;
 }
 
+function dispatchResultToTerminal(entry = {}, result = {}) {
+  const payload = {
+    engine: result.engine || entry.engine || '',
+    task: entry.taskId || (entry.task && entry.task.display_id) || '',
+    exit_code: dispatchResultExitCode(result),
+    timed_out: Boolean(result.timed_out),
+    cancelled: Boolean(result.cancelled),
+    stdout: [result.report, result.stdout].map((value) => String(value || '')).join('\n'),
+    stderr: result.stderr || '',
+  };
+  payload.reason = engineTerminalReason(payload);
+  payload.ok = payload.reason === 'ok';
+  return payload;
+}
+
 // Fleet landings always target master. Without the explicit --target, ship
 // falls back to the launcher branch's atris-base — a flight launched from a
 // feature-branch checkout would merge PRs into that branch while the receipt
@@ -838,6 +1062,7 @@ module.exports = {
   DENIED_TAGS,
   DEAD_ENGINE_OUTPUT_PATTERNS,
   reviewOnlyEngineEnvironment,
+  runInReapedProcessGroup,
   shipWithRetry,
   shipFailureDetail,
   get FLEET_CAPABLE() { return FLEET_CAPABLE; },
@@ -850,6 +1075,7 @@ module.exports = {
   DISPATCH_SELF_LAND_TARGET,
   parseDoneCheck,
   METHOD_KERNEL,
+  ATRIS_BUILD_PROCESS_PREAMBLE,
   buildFleetPrompt,
   assertIsolatedWorktree,
   buildEngineCommand,
@@ -867,6 +1093,7 @@ module.exports = {
   assignEngines,
   landArrival,
   detectDeadEngineDispatch,
+  dispatchResultToTerminal,
   failedDispatchLeg,
   fleetShipArgs,
   clipHeadTail,
@@ -1130,7 +1357,7 @@ function reviewOnlyEngineEnvironment(worktreePath, options = {}) {
     ATRIS_ONE_LAP_LIFECYCLE_WRAPPER: lifecycle.wrapper,
     ATRIS_ONE_LAP_STATUS_FILE: lifecycle.statusFile,
   };
-  for (const key of [
+  const inheritKeys = [
     'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM', 'NO_COLOR', 'USER', 'LOGNAME', 'SHELL',
     'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY', 'SSL_CERT_FILE', 'SSL_CERT_DIR',
     'NODE_EXTRA_CA_CERTS', 'NODE_NO_WARNINGS', 'DISABLE_AUTOUPDATER',
@@ -1138,9 +1365,23 @@ function reviewOnlyEngineEnvironment(worktreePath, options = {}) {
     'ATRIS_VALIDATOR_MODE', 'ATRIS_VALIDATOR_COUNT', 'ATRIS_VALIDATOR_PROMPT',
     'ATRIS_PUSH_RESULT', 'ATRIS_PUSH_URL', 'ATRIS_PUSH_CONFIG', 'ATRIS_BOUNDARY_DUMP',
     'ATRIS_REAL_GIT', 'ATRIS_TASKS_DB',
-  ]) {
+  ];
+  for (const key of inheritKeys) {
     if (process.env[key] !== undefined) environment[key] = String(process.env[key]);
   }
+  if (options.secretGrant) {
+    const grantOptions = {};
+    if (options.secretGrantUpstreamPort !== undefined) grantOptions.upstreamPort = options.secretGrantUpstreamPort;
+    if (options.secretGrantUpstreamAddress !== undefined) grantOptions.upstreamAddress = options.secretGrantUpstreamAddress;
+    if (options.secretGrantRejectUnauthorized !== undefined) {
+      grantOptions.rejectUnauthorized = options.secretGrantRejectUnauthorized;
+    }
+    applySecretGrantEnvironment(environment, options.secretGrant, grantOptions);
+    for (const key of SECRET_GATEWAY_PROXY_ENV_KEYS) {
+      if (key.toUpperCase() === 'NO_PROXY') environment[key] = '127.0.0.1,localhost';
+      else environment[key] = '';
+    }
+  }
   return environment;
 }
 
@@ -1968,8 +2209,7 @@ function dispatchReceiptResult(flight, { ids, reviewOnly, enforceRemoteBoundary
   return result;
 }
 
-function writeDispatchReceipt(flight, receiptPath, resultOptions) {
-  flight.result = dispatchReceiptResult(flight, resultOptions);
+function atomicWriteFlightReceipt(flight, receiptPath) {
   flight.receipt = receiptPath;
   fs.mkdirSync(path.dirname(receiptPath), { recursive: true });
   const tempPath = `${receiptPath}.tmp-${process.pid}`;
@@ -1977,6 +2217,21 @@ function writeDispatchReceipt(flight, receiptPath, resultOptions) {
   fs.renameSync(tempPath, receiptPath);
 }
 
+function startLiveFlight(root, receiptPath, flight) {
+  const liveLogPath = createEngineLiveLog(receiptPath);
+  flight.status = 'running';
+  flight.pid = process.pid;
+  flight.started_at = flight.started_at || flight.at || new Date().toISOString();
+  flight.live_log = path.relative(root, liveLogPath) || liveLogPath;
+  atomicWriteFlightReceipt(flight, receiptPath);
+  return liveLogPath;
+}
+
+function writeDispatchReceipt(flight, receiptPath, resultOptions) {
+  flight.result = dispatchReceiptResult(flight, resultOptions);
+  atomicWriteFlightReceipt(flight, receiptPath);
+}
+
 function stampDispatchResultVerification(flight, taskId, engine, startedAtMs, verifierResult) {
   if (!verifierResult || typeof verifierResult.passed !== 'boolean') return;
   const row = flight.results.find((result) => result.task === taskId);
@@ -2110,19 +2365,76 @@ function defaultTrustedVerifyRunner(command, cwd) {
   };
 }
 
-function defaultSelfLandCheck({ worktreePath, targetRef = DISPATCH_SELF_LAND_TARGET, git = null } = {}) {
+function defaultDispatchStartCommit({ worktreePath, git = null } = {}) {
+  const run = git || ((args) => spawnSync('git', args, { cwd: worktreePath, encoding: 'utf8' }));
+  const head = run(['rev-parse', '--verify', 'HEAD^{commit}']);
+  if (!head || head.status !== 0) return '';
+  return String(head.stdout || '').trim();
+}
+
+function defaultSelfLandCheck({ worktreePath, targetRef = DISPATCH_SELF_LAND_TARGET, startCommit = '', entry = null, git = null } = {}) {
   const run = git || ((args) => spawnSync('git', args, { cwd: worktreePath, encoding: 'utf8' }));
+  const recordedStart = String(startCommit || (entry && entry.startCommit) || '').trim();
+  if (!recordedStart) {
+    return { ok: false, stage: 'self_land_check', reason: 'unknown_start_commit', target: targetRef, detail: 'dispatch start commit was not recorded' };
+  }
+  const headResult = run(['rev-parse', '--verify', 'HEAD^{commit}']);
+  if (!headResult || headResult.status !== 0) {
+    return {
+      ok: false,
+      stage: 'self_land_check',
+      reason: 'unknown_head',
+      target: targetRef,
+      start_commit: recordedStart,
+      detail: String(headResult && (headResult.stderr || headResult.stdout) || '').trim(),
+    };
+  }
+  const head = String(headResult.stdout || '').trim();
+  if (head === recordedStart) {
+    return {
+      ok: false,
+      stage: 'no_work_landed',
+      reason: 'no_work_landed',
+      target: targetRef,
+      start_commit: recordedStart,
+      head,
+      detail: 'no work landed because HEAD still matches the dispatch start commit',
+    };
+  }
+  const diff = run(['diff', '--quiet', recordedStart, head, '--']);
+  if (diff.status === 0) {
+    return {
+      ok: false,
+      stage: 'no_work_landed',
+      reason: 'no_work_landed',
+      target: targetRef,
+      start_commit: recordedStart,
+      head,
+      detail: 'no work landed because the commit changed without changing the tree',
+    };
+  }
+  if (diff.status !== 1) {
+    return {
+      ok: false,
+      stage: 'self_land_check',
+      reason: 'diff_check_failed',
+      target: targetRef,
+      start_commit: recordedStart,
+      head,
+      detail: String(diff.stderr || diff.stdout || '').trim(),
+    };
+  }
   const branch = String(targetRef || '').startsWith('origin/') ? String(targetRef).slice('origin/'.length) : '';
   const fetch = run(branch ? ['fetch', 'origin', `${branch}:refs/remotes/origin/${branch}`] : ['fetch', 'origin']);
   if (fetch.status !== 0) {
-    return { ok: false, stage: 'self_land_check', target: targetRef, detail: String(fetch.stderr || fetch.stdout || '').trim() };
+    return { ok: false, stage: 'self_land_check', target: targetRef, start_commit: recordedStart, head, detail: String(fetch.stderr || fetch.stdout || '').trim() };
   }
   const ancestor = run(['merge-base', '--is-ancestor', 'HEAD', targetRef]);
-  if (ancestor.status === 0) return { ok: true, stage: 'self_landed', target: targetRef };
+  if (ancestor.status === 0) return { ok: true, stage: 'self_landed', target: targetRef, start_commit: recordedStart, head };
   if (ancestor.status === 1) {
-    return { ok: false, stage: 'self_land_missing', target: targetRef, detail: `HEAD is not an ancestor of ${targetRef}` };
+    return { ok: false, stage: 'self_land_missing', target: targetRef, start_commit: recordedStart, head, detail: `HEAD is not an ancestor of ${targetRef}` };
   }
-  return { ok: false, stage: 'self_land_check', target: targetRef, detail: String(ancestor.stderr || ancestor.stdout || '').trim() };
+  return { ok: false, stage: 'self_land_check', target: targetRef, start_commit: recordedStart, head, detail: String(ancestor.stderr || ancestor.stdout || '').trim() };
 }
 
 // One flight. Staff -> dispatch in parallel -> land serially -> receipt.
@@ -2140,6 +2452,7 @@ async function runFleetFlight({
   rebase = null,
   checkoutBase = 'origin/master',
   guardCliLink = guardGlobalCliLink,
+  scoutAsk = null,
 } = {}) {
   const cli = ownCli || defaultOwnCli(root);
   // Staff first, rank second: every task staffFlight returns already cleared
@@ -2188,6 +2501,8 @@ async function runFleetFlight({
     return flight;
   }
 
+  const liveLogPath = startLiveFlight(root, receiptPath, flight);
+
   // Claim + cut a worktree per assignment, then dispatch all in parallel.
   const dispatch = dispatcher || ((entry) => new Promise((resolve) => {
     resolve(dispatchToEngine({
@@ -2198,6 +2513,7 @@ async function runFleetFlight({
       prompt: entry.prompt,
       briefId: entry.brief_id,
       skipBriefCapture: true,
+      liveLogPath,
     }));
   }));
   const restaffState = { used: false };
@@ -2211,7 +2527,13 @@ async function runFleetFlight({
   const startBaseArgs = checkoutBase ? ['--base', checkoutBase] : [];
   const prepared = [];
   for (const entry of staffed) {
-    cli(['task', 'claim', String(entry.task.display_id), '--as', `fleet-${entry.engine}`]);
+    const claimed = cli(['task', 'claim', String(entry.task.display_id), '--as', `fleet-${entry.engine}`]);
+    if (!claimed || claimed.status !== 0) {
+      const detail = String(claimed && (claimed.stderr || claimed.stdout) || 'claim failed').trim().slice(0, 300);
+      flight.paused.push({ task: entry.task.display_id, engine: entry.engine, stage: 'claim', detail });
+      log(`    ${entry.engine.padEnd(8)} ⏸ paused ${entry.task.display_id} at claim${detail ? ` — ${detail}` : ''}`);
+      continue;
+    }
     const started = cli(['worktree', 'start', '--agent', entry.engine, '--task', `fleet-${String(entry.task.display_id).toLowerCase()}`, ...startBaseArgs]);
     const wt = (started.stdout.match(/next: cd (.+)/) || [])[1];
     if (!wt) {
@@ -2230,6 +2552,7 @@ async function runFleetFlight({
       dispatch,
       installedEngines: roster,
       restaffState,
+      scoutAsk: scoutAsk === null && dispatcher ? false : (scoutAsk || undefined),
     }).then((result) => ({ entry, result }))
   ));
   flight.results = results.map(({ entry, result }) => {
@@ -2257,8 +2580,15 @@ async function runFleetFlight({
     const activeEngine = result.engine || entry.engine;
     const landingEntry = { ...entry, engine: activeEngine };
     if (result.restaffed) log(`    restaffed ${entry.task.display_id}: ${result.restaffed.from} -> ${result.restaffed.to} (${result.restaffed.reason})`);
-    if (result.exitCode !== 0) {
-      const paused = { task: entry.task.display_id, engine: activeEngine, stage: 'build', detail: (result.stderr || '').slice(0, 200) };
+    const buildFailure = detectDeadEngineDispatch(result);
+    if (buildFailure) {
+      const paused = {
+        task: entry.task.display_id,
+        engine: activeEngine,
+        stage: 'build',
+        reason: buildFailure.reason,
+        detail: String(result.stderr || buildFailure.reason).slice(0, 200),
+      };
       if (result.restaffed) paused.restaffed = result.restaffed;
       if (result.deadEngine) paused.deadEngine = result.deadEngine;
       flight.paused.push(paused);
@@ -2301,9 +2631,9 @@ async function runFleetFlight({
       : `  alert: global atris link was ${cliLink.reason}; repoint attempted at ${cliLink.restoredTo} but the cli still fails, so every cron/loop/mission is down`);
   }
 
-  fs.mkdirSync(path.dirname(receiptPath), { recursive: true });
-  flight.receipt = receiptPath;
-  fs.writeFileSync(flight.receipt, `${JSON.stringify(flight, null, 2)}\n`);
+  flight.status = flight.paused.length ? 'failed' : 'completed';
+  flight.finished_at = new Date().toISOString();
+  atomicWriteFlightReceipt(flight, receiptPath);
   log('');
   log(`  flight over: ${flight.landed.length} landed, ${flight.paused.length} paused · receipt: ${path.relative(root, flight.receipt)}`);
   log('');
@@ -2335,6 +2665,7 @@ async function runDispatchFlight({
   checkoutBase = 'origin/master',
   installedEngines = null,
   selfLandCheck = null,
+  startCommitReader = null,
   yolo = false,
   reviewOnly = false,
   verifierCommand = '',
@@ -2344,6 +2675,7 @@ async function runDispatchFlight({
   validatorEngines = null,
   validatorDispatcher = null,
   validatorStateInspector = null,
+  scoutAsk = null,
 } = {}) {
   if (!engine) throw new Error('runDispatchFlight: engine is required');
   if (!FLEET_CAPABLE.includes(engine)) {
@@ -2368,6 +2700,7 @@ async function runDispatchFlight({
   const cli = ownCli || defaultOwnCli(root);
   const verify = verifier || (trustedVerifier ? defaultTrustedVerifyRunner : defaultVerifyRunner);
   const inspectChange = changeInspector || inspectReviewChange;
+  const readStartCommit = startCommitReader || defaultDispatchStartCommit;
   const enforceRemoteBoundary = reviewOnly && !dispatcher;
   const explicitActor = String(actor || '').trim();
   const taskActor = explicitActor || `fleet-${engine}`;
@@ -2388,6 +2721,7 @@ async function runDispatchFlight({
   flight.actor = taskActor;
   if (receiptContext && typeof receiptContext === 'object') flight.context = receiptContext;
   const requiresIndependentValidator = reviewOnly && flight.context && flight.context.source === 'one_lap';
+  const liveLogPath = startLiveFlight(root, receiptPath, flight);
 
   log('');
   log(`  dispatch — ${ids.length} task${ids.length === 1 ? '' : 's'} -> ${engine}`);
@@ -2436,6 +2770,7 @@ async function runDispatchFlight({
       continue;
     }
     const worktreePath = enforceRemoteBoundary ? remoteBoundary.worktreePath : landingWorktreePath;
+    const startCommit = yolo ? readStartCommit({ worktreePath }) : '';
     const basePrompt = promptOverride || buildFleetPrompt(task, { worktreePath, yolo });
     const safetyPrompt = reviewOnly
       ? `${basePrompt}\n\nSafety boundary: edit and test this checkout only. Do not push, merge, deploy, publish, send messages, change cloud state, install dependencies, or use credentials.`
@@ -2451,6 +2786,7 @@ async function runDispatchFlight({
       engine,
       remoteBoundary,
       remoteMasterBefore: remoteBoundary ? remoteBoundary.protectedMaster : '',
+      startCommit,
       ...(trustedPrompt ? { prompt: trustedPrompt } : {}),
     });
     log(`    building ${taskId} in ${path.basename(worktreePath)}`);
@@ -2472,6 +2808,7 @@ async function runDispatchFlight({
       yolo,
       briefId: entry.brief_id,
       skipBriefCapture: true,
+      liveLogPath,
     }));
   }));
   const restaffState = { used: false };
@@ -2485,6 +2822,7 @@ async function runDispatchFlight({
       dispatch,
       installedEngines,
       restaffState,
+      scoutAsk: scoutAsk === null && dispatcher ? false : (scoutAsk || undefined),
     }).then((result) => {
       const completedAtMs = Date.now();
       return {
@@ -2492,7 +2830,7 @@ async function runDispatchFlight({
         result,
         startedAtMs,
         completedAtMs,
-        candidate: enforceRemoteBoundary && result.exitCode === 0
+        candidate: enforceRemoteBoundary && !detectDeadEngineDispatch(result)
           ? reviewCandidateSnapshot(entry.remoteBoundary)
           : null,
       };
@@ -2508,6 +2846,7 @@ async function runDispatchFlight({
       at: new Date(completedAtMs).toISOString(),
       exitCode: result.exitCode,
     };
+    if (entry.startCommit) row.start_commit = entry.startCommit;
     if (result.brief_id) row.brief_id = result.brief_id;
     if (result.restaffed) row.restaffed = result.restaffed;
     if (result.deadEngine) row.deadEngine = result.deadEngine;
@@ -2602,12 +2941,14 @@ async function runDispatchFlight({
     const readyActor = explicitActor || `fleet-${activeEngine}`;
     const landingEntry = { ...entry, engine: activeEngine, candidate };
     if (result.restaffed) log(`    restaffed ${entry.taskId}: ${result.restaffed.from} -> ${result.restaffed.to} (${result.restaffed.reason})`);
-    if (result.exitCode !== 0) {
+    const buildFailure = detectDeadEngineDispatch(result);
+    if (buildFailure) {
       const paused = {
         task: entry.taskId,
         engine: activeEngine,
         stage: 'build',
-        detail: String(result.stderr || '').slice(0, 300),
+        reason: buildFailure.reason,
+        detail: String(result.stderr || buildFailure.reason).slice(0, 300),
         worktree: entry.worktreePath,
       };
       if (result.restaffed) paused.restaffed = result.restaffed;
@@ -2649,7 +2990,13 @@ async function runDispatchFlight({
     }
     if (yolo) {
       log(`    checking self-land ${entry.taskId}...`);
-      const selfLanded = checkSelfLand({ entry, result, worktreePath: entry.worktreePath, targetRef: DISPATCH_SELF_LAND_TARGET });
+      const selfLanded = checkSelfLand({
+        entry,
+        result,
+        worktreePath: entry.worktreePath,
+        targetRef: DISPATCH_SELF_LAND_TARGET,
+        startCommit: entry.startCommit,
+      });
       if (selfLanded.ok) {
         const target = selfLanded.target || DISPATCH_SELF_LAND_TARGET;
         flight.landed.push({
@@ -2658,10 +3005,10 @@ async function runDispatchFlight({
           landing: 'self',
           target,
           verifier_result: {
-            command: `git merge-base --is-ancestor HEAD ${target}`,
+            command: `HEAD and its tree differ from dispatch start commit; git merge-base --is-ancestor HEAD ${target}`,
             passed: true,
             status: 0,
-            output: `HEAD is an ancestor of ${target}`,
+            output: `HEAD ${selfLanded.head || ''} differs from ${selfLanded.start_commit || entry.startCommit} and is an ancestor of ${target}`,
           },
           ...(result.brief_id ? { brief_id: result.brief_id } : {}),
         });
@@ -2676,8 +3023,12 @@ async function runDispatchFlight({
           target: selfLanded.target || DISPATCH_SELF_LAND_TARGET,
           detail: selfLanded.detail || '',
         });
-        stampDispatchBrief(root, result.brief_id, 'partial', `self-land check paused ${entry.taskId} at ${stage}`);
-        log(`    ⏸ paused ${entry.taskId} at ${stage}`);
+        stampDispatchBrief(root, result.brief_id, 'partial', stage === 'no_work_landed'
+          ? `no work landed for ${entry.taskId}`
+          : `self-land check paused ${entry.taskId} at ${stage}`);
+        log(stage === 'no_work_landed'
+          ? `    ⏸ no work landed for ${entry.taskId}`
+          : `    ⏸ paused ${entry.taskId} at ${stage}`);
       }
       continue;
     }
@@ -2973,6 +3324,8 @@ async function runDispatchFlight({
     }
   }
 
+  flight.status = flight.paused.length ? 'failed' : 'completed';
+  flight.finished_at = new Date().toISOString();
   writeDispatchReceipt(flight, receiptPath, { ids, reviewOnly, enforceRemoteBoundary });
   log('');
   const completedLabel = reviewOnly ? `${flight.ready.length} proof ready` : `${flight.landed.length} landed`;