agentxchain 2.155.72 → 2.155.73

package/README.md

@@ -55,19 +55,15 @@ npx --yes -p agentxchain@latest -c "agentxchain demo"
 
 ## Testing
 
-The CLI currently uses two runners on purpose: a 36-file Vitest coexistence slice for fast feedback and `node --test` for the full suite.
+The CLI test suite runs under Vitest. Test files import Vitest directly, and `npm test` is the single CI contract.
 
 ```bash
-npm run test:vitest
-npm run test:node
 npm test
+npm run test:watch
 ```
 
-- `npm run test:vitest`: the current 36-file Vitest slice
-- `npm run test:node`: full integration, subprocess, and E2E suite
-- `npm test`: both runners in sequence; this is the CI requirement today
-
-Duplicate execution remains intentional for the current 36-file slice until a later slice explicitly changes the redundancy model. For watch mode, run `npx vitest`.
+- `npm test`: full Vitest suite, including integration, subprocess, E2E, and beta scenario coverage
+- `npm run test:watch`: Vitest watch mode for local TDD
 
 ## Quick Start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.155.72",
+  "version": "2.155.73",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -26,10 +26,8 @@
   ],
   "scripts": {
     "dev": "node bin/agentxchain.js",
-    "test": "npm run test:vitest && npm run test:node",
-    "test:vitest": "vitest run --reporter=verbose",
-    "test:beta": "node --test test/beta-tester-scenarios/*.test.js",
-    "test:node": "node --test --test-timeout=60000 --test-concurrency=4 test/*.test.js test/beta-tester-scenarios/*.test.js",
+    "test": "vitest run --reporter=verbose",
+    "test:watch": "vitest --reporter=verbose",
     "preflight:release": "bash scripts/release-preflight.sh",
     "preflight:release:strict": "bash scripts/release-preflight.sh --strict",
     "check:release-alignment": "node scripts/check-release-alignment.mjs",

package/scripts/migrate-node-test-to-vitest.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = fileURLToPath(new URL('.', import.meta.url));
+const CLI_ROOT = join(SCRIPT_DIR, '..');
+const TEST_ROOT = process.argv[2] ? resolve(process.argv[2]) : join(CLI_ROOT, 'test');
+
+function walk(dir) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const absolute = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walk(absolute));
+    } else if (entry.isFile() && entry.name.endsWith('.test.js')) {
+      files.push(absolute);
+    }
+  }
+  return files;
+}
+
+function parseNamedSpecifiers(specifiers) {
+  return specifiers
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function migrateNamedSpecifiers(specifiers) {
+  let importsBefore = false;
+  let importsAfter = false;
+  const migrated = parseNamedSpecifiers(specifiers).map((specifier) => {
+    if (specifier === 'before') {
+      importsBefore = true;
+      return 'beforeAll';
+    }
+    if (specifier === 'after') {
+      importsAfter = true;
+      return 'afterAll';
+    }
+    return specifier;
+  });
+  return {
+    importsBefore,
+    importsAfter,
+    importLine: `import { ${migrated.join(', ')} } from 'vitest';`,
+  };
+}
+
+function migrateSource(source) {
+  let importsBefore = false;
+  let importsAfter = false;
+  let changed = false;
+
+  let next = source.replace(
+    /^import\s+test\s+from\s+['"]node:test['"];$/gm,
+    () => {
+      changed = true;
+      return "import { test } from 'vitest';";
+    },
+  );
+
+  next = next.replace(
+    /^import\s+\{([^}]+)\}\s+from\s+['"]node:test['"];$/gm,
+    (_match, specifiers) => {
+      const migrated = migrateNamedSpecifiers(specifiers);
+      importsBefore ||= migrated.importsBefore;
+      importsAfter ||= migrated.importsAfter;
+      changed = true;
+      return migrated.importLine;
+    },
+  );
+
+  if (importsBefore) {
+    next = next.replace(/\bbefore(?=\s*\()/g, 'beforeAll');
+  }
+  if (importsAfter) {
+    next = next.replace(/\bafter(?=\s*\()/g, 'afterAll');
+  }
+
+  return { changed, source: next };
+}
+
+const changedFiles = [];
+for (const file of walk(TEST_ROOT)) {
+  const source = readFileSync(file, 'utf8');
+  const migrated = migrateSource(source);
+  if (!migrated.changed || migrated.source === source) continue;
+  writeFileSync(file, migrated.source);
+  changedFiles.push(relative(CLI_ROOT, file));
+}
+
+console.log(`Migrated ${changedFiles.length} test files from node:test to vitest.`);
+for (const file of changedFiles) {
+  console.log(file);
+}

package/scripts/release-postflight.sh

@@ -78,7 +78,7 @@ FAIL=0
 TARBALL_URL=""
 REGISTRY_CHECKSUM=""
 PACKAGE_NAME="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).name)")"
-PACKAGE_BIN_NAME="$(node -e "const pkg = JSON.parse(require('fs').readFileSync('package.json', 'utf8')); if (typeof pkg.bin === 'string') { console.log(pkg.name); process.exit(0); } const names = Object.keys(pkg.bin || {}); if (names.length !== 1) { console.error('package.json bin must declare exactly one entry'); process.exit(1); } console.log(names[0]);")"
+PACKAGE_BIN_NAME="$(node -e "const pkg = JSON.parse(require('fs').readFileSync('package.json', 'utf8')); if (typeof pkg.bin === 'string') { console.log(pkg.name); process.exit(0); } const bins = pkg.bin || {}; if (bins[pkg.name]) { console.log(pkg.name); process.exit(0); } const names = Object.keys(bins); if (names.length === 1) { console.log(names[0]); process.exit(0); } console.error('package.json bin must declare the primary package bin'); process.exit(1);")"
 RUNNER_INTERFACE_VERSION_EXPECTED="$(node --input-type=module -e "import('./src/lib/runner-interface.js').then((mod) => { console.log(mod.RUNNER_INTERFACE_VERSION); }).catch((error) => { console.error(error.message); process.exit(1); });")"
 ADAPTER_INTERFACE_VERSION_EXPECTED="$(node --input-type=module -e "import('./src/lib/adapter-interface.js').then((mod) => { console.log(mod.ADAPTER_INTERFACE_VERSION); }).catch((error) => { console.error(error.message); process.exit(1); });")"
 

package/scripts/release-preflight.sh

@@ -179,15 +179,15 @@ if [[ "$PUBLISH_GATE" -eq 1 ]]; then
       fail "No beta-tester scenario tests found for release-gate verification"
       TEST_OUTPUT=""
       TEST_STATUS=1
-    elif run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 node --test "${GATE_TEST_ARGS[@]}"; then
+    elif run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 npm test -- "${GATE_TEST_ARGS[@]}"; then
       TEST_STATUS=0
     else
       TEST_STATUS=$?
     fi
-    NODE_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ tests / { print $3; exit }')"
-    NODE_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ fail / { print $3; exit }')"
-    if [ "$TEST_STATUS" -eq 0 ] && [ "${NODE_FAIL:-0}" = "0" ]; then
-      pass "${NODE_PASS:-?} release-gate tests passed, 0 failures"
+    VITEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed/ { for (i = 1; i <= NF; i++) if ($i ~ /^[0-9]+$/) { print $i; exit } }')"
+    VITEST_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+failed/ { for (i = 1; i <= NF; i++) if ($i ~ /^[0-9]+$/) { print $i; exit } }')"
+    if [ "$TEST_STATUS" -eq 0 ] && [ "${VITEST_FAIL:-0}" = "0" ]; then
+      pass "${VITEST_PASS:-?} release-gate tests passed, 0 failures"
     else
       fail "Release-gate tests failed"
       printf '%s\n' "$TEST_OUTPUT" | tail -20

package/scripts/verify-post-publish.sh

@@ -21,7 +21,7 @@ TARGET_VERSION=""
 
 FORMULA_PATH="${CLI_DIR}/homebrew/agentxchain.rb"
 PACKAGE_NAME="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).name)")"
-PACKAGE_BIN_NAME="$(node -e "const pkg = JSON.parse(require('fs').readFileSync('package.json','utf8')); if (typeof pkg.bin === 'string') { console.log(pkg.name); process.exit(0); } const names = Object.keys(pkg.bin || {}); if (names.length !== 1) { console.error('package.json bin must declare exactly one entry'); process.exit(1); } console.log(names[0]);")"
+PACKAGE_BIN_NAME="$(node -e "const pkg = JSON.parse(require('fs').readFileSync('package.json','utf8')); if (typeof pkg.bin === 'string') { console.log(pkg.name); process.exit(0); } const bins = pkg.bin || {}; if (bins[pkg.name]) { console.log(pkg.name); process.exit(0); } const names = Object.keys(bins); if (names.length === 1) { console.log(names[0]); process.exit(0); } console.error('package.json bin must declare the primary package bin'); process.exit(1);")"
 
 formula_url() {
   local formula_path="$1"

package/src/commands/run.js

@@ -362,6 +362,9 @@ export async function executeGovernedRun(context, opts = {}) {
         turnId: turn.turn_id,
         onSpawnAttached: ({ pid, at }) => ensureStartingState(pid, at),
         onFirstOutput: ({ at, stream }) => ensureRunningState(stream, at),
+        onStartupHeartbeat: ({ elapsed_since_spawn_ms }) => {
+          tracker.heartbeat(`Adapter keepalive (${Math.round((elapsed_since_spawn_ms || 0) / 1000)}s since spawn)`);
+        },
       };
 
       const recordOutputActivity = (stream, text) => {

package/src/commands/step.js

@@ -22,7 +22,7 @@
  */
 
 import chalk from 'chalk';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { loadProjectContext, loadProjectState } from '../lib/config.js';
 import {
@@ -76,6 +76,7 @@ import { evaluateApprovalSlaReminders } from '../lib/notification-runner.js';
 import { consumeNextApprovedIntent } from '../lib/intake.js';
 import { failTurnStartup, reconcileStaleTurns } from '../lib/stale-turn-watchdog.js';
 import { isKnownTurnRunningProofStream } from '../lib/dispatch-streams.js';
+import { getDispatchProgressRelativePath } from '../lib/dispatch-progress.js';
 
 export async function stepCommand(opts) {
   const context = loadProjectContext();
@@ -192,6 +193,7 @@ export async function stepCommand(opts) {
         process.exit(1);
       }
 
+      guardResumeWorkerLiveness(root, targetTurn);
       skipAssignment = true;
       console.log(chalk.yellow(`Resuming active turn: ${targetTurn.turn_id}`));
     } else if (activeCount >= maxConcurrent) {
@@ -272,6 +274,7 @@ export async function stepCommand(opts) {
         process.exit(1);
       }
 
+      guardResumeWorkerLiveness(root, targetTurn);
       console.log(chalk.yellow(`Re-dispatching blocked turn: ${targetTurn.turn_id}`));
       const reactivated = reactivateGovernedRun(root, state, { via: 'step --resume', notificationConfig: config });
       if (!reactivated.ok) {
@@ -1039,6 +1042,49 @@ export async function stepCommand(opts) {
   }
 }
 
+function guardResumeWorkerLiveness(root, turn) {
+  if (!turn || turn.worker_pid == null) {
+    return;
+  }
+
+  if (isWorkerAlive(turn.worker_pid)) {
+    console.log(chalk.red(`Worker process (PID ${turn.worker_pid}) is still alive.`));
+    console.log(chalk.dim('The previous dispatch appears to still be running.'));
+    console.log(chalk.dim('Wait for it to complete, or kill it first, then retry.'));
+    process.exit(1);
+  }
+
+  console.log(chalk.yellow(`Detected crashed worker (PID ${turn.worker_pid}). Re-dispatching turn ${turn.turn_id}...`));
+  cleanupStaleDispatchProgress(root, turn.turn_id);
+}
+
+function isWorkerAlive(pid) {
+  const numericPid = Number(pid);
+  if (!Number.isInteger(numericPid) || numericPid <= 0) {
+    return false;
+  }
+
+  try {
+    process.kill(numericPid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function cleanupStaleDispatchProgress(root, turnId) {
+  const progressPath = join(root, getDispatchProgressRelativePath(turnId));
+  if (!existsSync(progressPath)) {
+    return;
+  }
+
+  try {
+    unlinkSync(progressPath);
+  } catch {
+    // Best-effort cleanup: resume can still proceed and rewrite fresh progress.
+  }
+}
+
 function printGhostTurnRecovery(ghostTurns) {
   console.log(chalk.red.bold('Ghost turn detected — subprocess never started.'));
   console.log('');

package/src/lib/adapters/local-cli-adapter.js

@@ -34,7 +34,9 @@ import {
   getClaudeSubprocessAuthIssue,
   hasClaudeAuthenticationFailureText,
   hasClaudeNodeIncompatibilityText,
+  hasCodexAuthenticationFailureText,
   isClaudeLocalCliRuntime,
+  isCodexLocalCliRuntime,
   resolveClaudeCompatibleNodeBinary,
 } from '../claude-local-auth.js';
 
@@ -49,6 +51,7 @@ const DIAGNOSTIC_ENV_KEYS = [
 const DIAGNOSTIC_STDERR_EXCERPT_LIMIT = 800;
 const DEFAULT_STARTUP_WATCHDOG_MS = 180_000;
 const DEFAULT_STARTUP_WATCHDOG_SIGKILL_GRACE_MS = 10_000;
+const DEFAULT_STARTUP_HEARTBEAT_MS = 30_000;
 
 /**
  * Launch a local CLI subprocess for a governed turn.
@@ -97,6 +100,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
   }
   const startupWatchdogMs = startupWatchdogOverrideMs ?? resolveStartupWatchdogMs(config, runtime);
   const startupWatchdogKillGraceMs = resolveStartupWatchdogKillGraceMs(options.startupWatchdogKillGraceMs);
+  const startupHeartbeatMs = resolveStartupHeartbeatMs(config, runtime, options.startupHeartbeatMs);
 
   // Read the dispatch bundle prompt
   const promptPath = join(root, getDispatchPromptPath(turn.turn_id));
@@ -116,8 +120,28 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     return { ok: false, error: `Cannot resolve CLI command for runtime "${runtimeId}". Expected "command" field in runtime config.` };
   }
 
-  // Compute timeout from deadline or default (20 minutes)
-  const timeoutMs = turn.deadline_at
+  const compatibility = validateLocalCliCommandCompatibility({ command, args, runtimeId });
+  if (!compatibility.ok) {
+    const logs = [];
+    appendDiagnostic(logs, 'command_compatibility_failed', compatibility.diagnostic);
+    return {
+      ok: false,
+      blocked: true,
+      classified: {
+        error_class: compatibility.error_class,
+        recovery: compatibility.recovery,
+      },
+      error: compatibility.error,
+      logs,
+    };
+  }
+
+  // Compute timeout from explicit dispatch deadline, turn deadline, or default (20 minutes).
+  const timeoutMs = options.dispatchTimeoutMs != null
+    ? options.dispatchTimeoutMs
+    : options.dispatchDeadlineAt
+      ? Math.max(0, new Date(options.dispatchDeadlineAt).getTime() - Date.now())
+      : turn.deadline_at
     ? Math.max(0, new Date(turn.deadline_at).getTime() - Date.now())
     : 1200000;
 
@@ -201,6 +225,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     let firstOutputLatencyMs = null;
     let startupWatchdog = null;
     let startupSigkillHandle = null;
+    let startupHeartbeat = null;
     let startupTimedOut = false;
     let startupFailureType = null;
     let stdoutBytes = 0;
@@ -224,6 +249,43 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       }
     };
 
+    const clearStartupHeartbeat = () => {
+      if (startupHeartbeat) {
+        clearInterval(startupHeartbeat);
+        startupHeartbeat = null;
+      }
+    };
+
+    const armStartupHeartbeat = () => {
+      if (startupHeartbeat || !(startupHeartbeatMs > 0 && Number.isFinite(startupHeartbeatMs))) {
+        return;
+      }
+      startupHeartbeat = setInterval(() => {
+        if (firstOutputAt || settled) {
+          clearStartupHeartbeat();
+          return;
+        }
+        const payload = {
+          startup_heartbeat_ms: startupHeartbeatMs,
+          startup_watchdog_ms: startupWatchdogMs,
+          pid: child.pid ?? null,
+          spawn_confirmed_at: spawnConfirmedAt,
+          elapsed_since_spawn_ms: spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs),
+          stdout_bytes: stdoutBytes,
+          stderr_bytes: stderrBytes,
+        };
+        appendDiagnostic(logs, 'startup_heartbeat', payload);
+        if (options.onStartupHeartbeat) {
+          try {
+            options.onStartupHeartbeat(payload);
+          } catch {}
+        }
+      }, startupHeartbeatMs);
+      if (typeof startupHeartbeat.unref === 'function') {
+        startupHeartbeat.unref();
+      }
+    };
+
     const armStartupWatchdog = () => {
       if (startupWatchdog || !(startupWatchdogMs > 0 && Number.isFinite(startupWatchdogMs))) {
         return;
@@ -269,6 +331,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
       firstOutputStream = stream;
       firstOutputLatencyMs = spawnConfirmedAtMs == null ? null : Math.max(0, Date.now() - spawnConfirmedAtMs);
       clearStartupWatchdog();
+      clearStartupHeartbeat();
       appendDiagnostic(logs, 'first_output', {
         at: firstOutputAt,
         stream,
@@ -296,6 +359,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
         } catch {}
       }
       armStartupWatchdog();
+      armStartupHeartbeat();
     });
 
     // Collect stdout/stderr
@@ -369,6 +433,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     const onAbort = () => {
       logs.push('[adapter] Abort signal received. Sending SIGTERM.');
       clearStartupWatchdog();
+      clearStartupHeartbeat();
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
       clearTimeout(abortSigkillHandle);
@@ -389,6 +454,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
     // Process exit
     child.on('close', (exitCode, killSignal) => {
       clearStartupWatchdog();
+      clearStartupHeartbeat();
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
       clearTimeout(abortSigkillHandle);
@@ -453,6 +519,22 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
           error: `Claude local_cli authentication failed. ${recovery}`,
           logs,
         });
+      } else if (isCodexLocalCliRuntime(runtime) && hasCodexAuthFailureOutput(logs)) {
+        const recovery = 'Refresh OpenAI credentials before resuming: export a valid OPENAI_API_KEY, then run agentxchain step --resume.';
+        settle({
+          ok: false,
+          blocked: true,
+          exitCode,
+          timedOut: false,
+          aborted: false,
+          firstOutputAt,
+          classified: {
+            error_class: 'codex_auth_failed',
+            recovery,
+          },
+          error: `Codex local_cli authentication failed. ${recovery}`,
+          logs,
+        });
       } else if (isClaudeLocalCliRuntime(runtime) && hasClaudeNodeRuntimeIncompatibilityOutput(logs)) {
         const recovery = 'Run AgentXchain with Node.js 20.5+ available to the Claude local_cli runtime, then resume continuous mode.';
         settle({
@@ -524,6 +606,7 @@ export async function dispatchLocalCli(root, state, config, options = {}) {
 
     child.on('error', (err) => {
       clearStartupWatchdog();
+      clearStartupHeartbeat();
       clearTimeout(timeoutHandle);
       clearTimeout(sigkillHandle);
       clearTimeout(abortSigkillHandle);
@@ -653,6 +736,19 @@ function resolveStartupWatchdogMs(config, runtime) {
   return DEFAULT_STARTUP_WATCHDOG_MS;
 }
 
+function resolveStartupHeartbeatMs(config, runtime, override) {
+  if (Number.isInteger(override) && override > 0) {
+    return override;
+  }
+  if (runtime?.type === 'local_cli' && Number.isInteger(runtime?.startup_heartbeat_ms) && runtime.startup_heartbeat_ms > 0) {
+    return runtime.startup_heartbeat_ms;
+  }
+  if (Number.isInteger(config?.run_loop?.startup_heartbeat_ms) && config.run_loop.startup_heartbeat_ms > 0) {
+    return config.run_loop.startup_heartbeat_ms;
+  }
+  return DEFAULT_STARTUP_HEARTBEAT_MS;
+}
+
 function resolveStartupWatchdogKillGraceMs(value) {
   if (Number.isInteger(value) && value >= 0) {
     return value;
@@ -660,6 +756,80 @@ function resolveStartupWatchdogKillGraceMs(value) {
   return DEFAULT_STARTUP_WATCHDOG_SIGKILL_GRACE_MS;
 }
 
+function validateLocalCliCommandCompatibility({ command, args = [], runtimeId = null }) {
+  const tokens = [command, ...args].filter((token) => typeof token === 'string');
+  const binaryName = command ? command.split('/').filter(Boolean).pop() || command : '';
+  const runtimeShape = { command: tokens };
+  const outputFormatIndex = tokens.findIndex((token) => token === '--output-format');
+  const outputFormatValue = outputFormatIndex >= 0 ? tokens[outputFormatIndex + 1] : null;
+  const usesStreamJson = tokens.includes('--output-format=stream-json')
+    || outputFormatValue === 'stream-json';
+  const usesPrint = tokens.includes('--print') || tokens.includes('-p');
+  const hasVerbose = tokens.includes('--verbose');
+  const usesCodex = isCodexLocalCliRuntime(runtimeShape);
+  const usesCodexExec = tokens.includes('exec');
+  const hasCodexJson = tokens.includes('--json');
+
+  if (binaryName === 'claude' && usesPrint && usesStreamJson && !hasVerbose) {
+    const runtimeLabel = runtimeId ? `Runtime "${runtimeId}"` : 'Claude local_cli runtime';
+    const recovery = `${runtimeLabel} uses "claude --print --output-format stream-json" without "--verbose". Add "--verbose" to the command array before dispatching again.`;
+    return {
+      ok: false,
+      error_class: 'local_cli_command_incompatible',
+      recovery,
+      error: recovery,
+      diagnostic: {
+        runtime_id: runtimeId,
+        binary: binaryName,
+        rule: 'claude_print_stream_json_requires_verbose',
+        has_print: usesPrint,
+        has_stream_json: usesStreamJson,
+        has_verbose: hasVerbose,
+        recovery,
+      },
+    };
+  }
+
+  if (usesCodex && !usesCodexExec) {
+    const runtimeLabel = runtimeId ? `Runtime "${runtimeId}"` : 'Codex local_cli runtime';
+    const recovery = `${runtimeLabel} uses "codex" without the "exec" subcommand. Governed local runs require "codex exec" for non-interactive execution.`;
+    return {
+      ok: false,
+      error_class: 'local_cli_command_incompatible',
+      recovery,
+      error: recovery,
+      diagnostic: {
+        runtime_id: runtimeId,
+        binary: binaryName,
+        rule: 'codex_requires_exec',
+        has_exec: usesCodexExec,
+        recovery,
+      },
+    };
+  }
+
+  if (usesCodex && usesCodexExec && !hasCodexJson) {
+    const runtimeLabel = runtimeId ? `Runtime "${runtimeId}"` : 'Codex local_cli runtime';
+    const recovery = `${runtimeLabel} uses "codex exec" without "--json". Add "--json" so subprocess output is machine-readable diagnostics while turn results remain staged on disk.`;
+    return {
+      ok: false,
+      error_class: 'local_cli_command_incompatible',
+      recovery,
+      error: recovery,
+      diagnostic: {
+        runtime_id: runtimeId,
+        binary: binaryName,
+        rule: 'codex_exec_requires_json',
+        has_exec: usesCodexExec,
+        has_json: hasCodexJson,
+        recovery,
+      },
+    };
+  }
+
+  return { ok: true };
+}
+
 /**
  * Check if the staged result file exists and has meaningful content.
  * Delegates to the shared `hasMeaningfulStagedResult` helper so watchdog,
@@ -687,6 +857,11 @@ function hasClaudeAuthFailureOutput(logs) {
   return logs.some((line) => hasClaudeAuthenticationFailureText(line));
 }
 
+function hasCodexAuthFailureOutput(logs) {
+  if (!Array.isArray(logs)) return false;
+  return logs.some((line) => hasCodexAuthenticationFailureText(line));
+}
+
 function hasClaudeNodeRuntimeIncompatibilityOutput(logs) {
   if (!Array.isArray(logs)) return false;
   return hasClaudeNodeIncompatibilityText(logs.join('\n'));
@@ -777,3 +952,5 @@ function appendDiagnosticExcerpt(existing, chunk, limit) {
 export { resolveCommand };
 export { resolvePromptTransport };
 export { resolveStartupWatchdogMs };
+export { resolveStartupHeartbeatMs };
+export { validateLocalCliCommandCompatibility };

package/src/lib/claude-local-auth.js

@@ -12,6 +12,7 @@ const CLAUDE_ENV_AUTH_KEYS = [
 const DEFAULT_SMOKE_PROBE_TIMEOUT_MS = 10_000;
 const DEFAULT_SMOKE_PROBE_STDIN = 'ok';
 const CLAUDE_AUTH_FAILURE_RE = /authentication_failed|authentication_error|invalid authentication credentials|unauthorized|API Error:\s*401/i;
+const CODEX_AUTH_FAILURE_RE = /unauthorized|invalid api key|invalid_api_key|authentication failed|authentication_failed|openai[\s\S]{0,200}401|api[_ -]?key[\s\S]{0,200}invalid|401[\s\S]{0,200}(openai|invalid|unauthorized)/i;
 const CLAUDE_NODE_INCOMPATIBILITY_RE =
   /TypeError:\s*Object not disposable|TypeError\(["']Object not disposable["']\)|Object not disposable[\s\S]{0,2000}Node\.js v(?:1[0-9]|20\.[0-4]\.)/i;
 const CLAUDE_COMPATIBLE_NODE_MIN = { major: 20, minor: 5, patch: 0 };
@@ -37,10 +38,23 @@ export function isClaudeLocalCliRuntime(runtime) {
   return head === 'claude' || head.endsWith('/claude');
 }
 
+export function isCodexLocalCliRuntime(runtime) {
+  const tokens = normalizeCommandTokens(runtime);
+  if (tokens.length === 0) {
+    return false;
+  }
+  const head = tokens[0].toLowerCase();
+  return head === 'codex' || head.endsWith('/codex');
+}
+
 export function hasClaudeAuthenticationFailureText(text) {
   return typeof text === 'string' && CLAUDE_AUTH_FAILURE_RE.test(text);
 }
 
+export function hasCodexAuthenticationFailureText(text) {
+  return typeof text === 'string' && CODEX_AUTH_FAILURE_RE.test(text);
+}
+
 export function hasClaudeNodeIncompatibilityText(text) {
   return typeof text === 'string' && CLAUDE_NODE_INCOMPATIBILITY_RE.test(text);
 }