cadet-agent 0.45.0 → 0.47.0

package/src/harness/routing.mjs

@@ -1,153 +1,161 @@
-/**
- * Cadet-Agent tool routing.
- *
- * Applies the tool-selection decision tree (contract §8) and capability
- * fallbacks. Routing never pretends a live capability exists: when MCP is
- * unavailable the call falls back to static context and CLI verification.
- * Live-editor mutation requires explicit user confirmation.
- */
-
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { spawnSync } from 'node:child_process';
-
-export const TOOL_KINDS = Object.freeze(['cli', 'read', 'search', 'mcp', 'write', 'manual']);
-
-export const ROUTING_REASONS = Object.freeze({
-  verification: 'deterministic CLI for verification (exit-code driven)',
-  staticContext: 'repository read/search for static context',
-  liveInspection: 'MCP for live Unity inspection or mutation',
-  unavailable: 'capability unavailable — falling back to a safe alternative',
-});
-
-class RoutingError extends Error {
-  constructor(message, detail = {}) {
-    super(message);
-    this.name = 'RoutingError';
-    Object.assign(this, detail);
-  }
-}
-
-/**
- * Detect the capability set. Nothing here contacts the network or the Editor;
- * it only reports what the environment supports.
- */
-export function detectCapabilities({ targetDir = process.cwd(), env = process.env, runner = defaultRunner } = {}) {
-  const unity = which('unity', { env, runner });
-  const mcpConfigured = existsSync(join(targetDir, '.vscode', 'mcp.json'))
-    || existsSync(join(targetDir, '.cursor', 'mcp.json'))
-    || existsSync(join(targetDir, '.mcp.json'));
-
-  return {
-    cli: true,
-    unityCli: unity.available ? { available: true, path: unity.path, version: unity.version } : { available: false },
-    mcp: mcpConfigured ? { available: true, configured: true } : { available: false, configured: false },
-    hook: {
-      copilot: existsSync(join(targetDir, '.github', 'hooks', 'git-guard.json')),
-      note: 'Cursor, Continue, and Claude Code have no native PreToolUse hook',
-    },
-    tokenTelemetry: { provider: false, source: 'estimate' },
-    costTelemetry: { available: false, reason: 'no model rate card configured' },
-  };
-}
-
-function defaultRunner(cmd, args) {
-  return spawnSync(cmd, args, { encoding: 'utf-8', windowsHide: true, shell: false });
-}
-
-function which(cmd, { env, runner }) {
-  const probe = process.platform === 'win32' ? 'where' : 'which';
-  const res = runner(probe, [cmd]);
-  if (res && res.status === 0 && res.stdout) {
-    const path = String(res.stdout).split(/\r?\n/).map((s) => s.trim()).filter(Boolean)[0];
-    let version = null;
-    try {
-      const v = runner(cmd, ['--version']);
-      if (v && v.status === 0 && v.stdout) version = String(v.stdout).trim().split(/\r?\n/)[0];
-    } catch { /* version is optional */ }
-    return { available: true, path, version };
-  }
-  return { available: false };
-}
-
-/**
- * Decide which tool to use for a task. Returns a routing decision with a reason
- * and the fallback that was applied, if any.
- */
-export function routeTask({ task, capabilities = {} } = {}) {
-  if (!task || !TOOL_KINDS.includes(task.kind)) {
-    throw new RoutingError(`unknown task kind "${task?.kind}"`);
-  }
-
-  const decide = (tool, reason, extra = {}) => ({
-    tool,
-    kind: task.kind,
-    reason,
-    fallbackApplied: false,
-    ...extra,
-  });
-
-  switch (task.kind) {
-    case 'cli':
-    case 'manual':
-      return decide(task.kind, ROUTING_REASONS.verification);
-
-    case 'read':
-    case 'search':
-      return decide(task.kind, ROUTING_REASONS.staticContext);
-
-    case 'write': {
-      // A write to a live Editor is a mutation and needs confirmation.
-      if (task.target === 'live-editor') {
-        if (!task.userConfirmed) {
-          throw new RoutingError('live-editor mutation requires explicit user confirmation', { blocked: true, requiresConfirmation: true });
-        }
-        if (!capabilities.mcp?.available) {
-          return decide('manual', ROUTING_REASONS.unavailable, {
-            fallbackApplied: true,
-            fallback: 'live-editor mutation requested but MCP is unavailable; ask the user to perform it',
-          });
-        }
-        return decide('mcp', ROUTING_REASONS.liveInspection, { userConfirmed: true });
-      }
-      return decide('write', 'repository write within the workspace');
-    }
-
-    case 'mcp': {
-      if (capabilities.mcp?.available) {
-        return decide('mcp', ROUTING_REASONS.liveInspection);
-      }
-      // Never pretend live inspection occurred.
-      const fallback = task.fallback === 'cli' || task.verification
-        ? decide('cli', ROUTING_REASONS.unavailable, { fallbackApplied: true, fallback: 'static context + CLI verification' })
-        : decide('read', ROUTING_REASONS.unavailable, { fallbackApplied: true, fallback: 'static context only' });
-      return { ...fallback, liveInspectionPerformed: false };
-    }
-
-    default:
-      throw new RoutingError(`unhandled task kind "${task.kind}"`);
-  }
-}
-
-/**
- * Record a tool call. Arguments are sanitized by the caller (see redaction.mjs)
- * before persistence; this function only shapes the span.
- */
-export function toolCallSpan({ tool, args = {}, rationale, startedAt, finishedAt, durationMs, resultClass, outputBytes = 0, artifactPath = null, exitCode = null, retryNumber = 0 }) {
-  return {
-    kind: 'tool-call',
-    tool,
-    args,
-    reason: rationale,
-    startedAt,
-    finishedAt,
-    durationMs,
-    result: resultClass,
-    outputBytes,
-    artifactPath,
-    exitCode,
-    retryNumber,
-  };
-}
-
-export { RoutingError };
+/**
+ * Cadet-Agent tool routing.
+ *
+ * Applies the tool-selection decision tree (contract §8) and capability
+ * fallbacks. Routing never pretends a live capability exists: when MCP is
+ * unavailable the call falls back to static context and CLI verification.
+ * Live-editor mutation requires explicit user confirmation.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const TOOL_KINDS = Object.freeze(['cli', 'read', 'search', 'mcp', 'write', 'manual']);
+
+export const ROUTING_REASONS = Object.freeze({
+  verification: 'deterministic CLI for verification (exit-code driven)',
+  staticContext: 'repository read/search for static context',
+  liveInspection: 'MCP for live Unity inspection or mutation',
+  unavailable: 'capability unavailable — falling back to a safe alternative',
+});
+
+class RoutingError extends Error {
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = 'RoutingError';
+    Object.assign(this, detail);
+  }
+}
+
+/**
+ * Detect the capability set. Nothing here contacts the network or the Editor;
+ * it only reports what the environment supports.
+ */
+export function detectCapabilities({ targetDir = process.cwd(), env = process.env, runner = defaultRunner } = {}) {
+  const unity = which('unity', { env, runner });
+  const mcpConfigured = existsSync(join(targetDir, '.vscode', 'mcp.json'))
+    || existsSync(join(targetDir, '.cursor', 'mcp.json'))
+    || existsSync(join(targetDir, '.mcp.json'));
+
+  return {
+    cli: true,
+    unityCli: unity.available ? { available: true, path: unity.path, version: unity.version } : { available: false },
+    mcp: mcpConfigured ? { available: true, configured: true } : { available: false, configured: false },
+    hook: {
+      copilot: existsSync(join(targetDir, '.github', 'hooks', 'git-guard.json')),
+      note: 'Cursor, Continue, and Claude Code have no native PreToolUse hook',
+    },
+    tokenTelemetry: { provider: false, source: 'estimate' },
+    costTelemetry: { available: false, reason: 'no model rate card configured' },
+  };
+}
+
+function defaultRunner(cmd, args) {
+  return spawnSync(cmd, args, { encoding: 'utf-8', windowsHide: true, shell: false });
+}
+
+/**
+ * Every PATH match for `cmd`, in resolution order, or an empty array when it does
+ * not resolve. `where` is used on Windows and `which` elsewhere, with `shell: false`
+ * so a probe can never itself be reinterpreted by a shell.
+ */
+export function whichAll(cmd, { runner = defaultRunner } = {}) {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  const res = runner(probe, [cmd]);
+  if (!res || res.status !== 0 || !res.stdout) return [];
+  return String(res.stdout).split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
+}
+
+function which(cmd, { env, runner }) {
+  const [path] = whichAll(cmd, { runner });
+  if (!path) return { available: false };
+  let version = null;
+  try {
+    const v = runner(cmd, ['--version']);
+    if (v && v.status === 0 && v.stdout) version = String(v.stdout).trim().split(/\r?\n/)[0];
+  } catch { /* version is optional */ }
+  return { available: true, path, version };
+}
+
+/**
+ * Decide which tool to use for a task. Returns a routing decision with a reason
+ * and the fallback that was applied, if any.
+ */
+export function routeTask({ task, capabilities = {} } = {}) {
+  if (!task || !TOOL_KINDS.includes(task.kind)) {
+    throw new RoutingError(`unknown task kind "${task?.kind}"`);
+  }
+
+  const decide = (tool, reason, extra = {}) => ({
+    tool,
+    kind: task.kind,
+    reason,
+    fallbackApplied: false,
+    ...extra,
+  });
+
+  switch (task.kind) {
+    case 'cli':
+    case 'manual':
+      return decide(task.kind, ROUTING_REASONS.verification);
+
+    case 'read':
+    case 'search':
+      return decide(task.kind, ROUTING_REASONS.staticContext);
+
+    case 'write': {
+      // A write to a live Editor is a mutation and needs confirmation.
+      if (task.target === 'live-editor') {
+        if (!task.userConfirmed) {
+          throw new RoutingError('live-editor mutation requires explicit user confirmation', { blocked: true, requiresConfirmation: true });
+        }
+        if (!capabilities.mcp?.available) {
+          return decide('manual', ROUTING_REASONS.unavailable, {
+            fallbackApplied: true,
+            fallback: 'live-editor mutation requested but MCP is unavailable; ask the user to perform it',
+          });
+        }
+        return decide('mcp', ROUTING_REASONS.liveInspection, { userConfirmed: true });
+      }
+      return decide('write', 'repository write within the workspace');
+    }
+
+    case 'mcp': {
+      if (capabilities.mcp?.available) {
+        return decide('mcp', ROUTING_REASONS.liveInspection);
+      }
+      // Never pretend live inspection occurred.
+      const fallback = task.fallback === 'cli' || task.verification
+        ? decide('cli', ROUTING_REASONS.unavailable, { fallbackApplied: true, fallback: 'static context + CLI verification' })
+        : decide('read', ROUTING_REASONS.unavailable, { fallbackApplied: true, fallback: 'static context only' });
+      return { ...fallback, liveInspectionPerformed: false };
+    }
+
+    default:
+      throw new RoutingError(`unhandled task kind "${task.kind}"`);
+  }
+}
+
+/**
+ * Record a tool call. Arguments are sanitized by the caller (see redaction.mjs)
+ * before persistence; this function only shapes the span.
+ */
+export function toolCallSpan({ tool, args = {}, rationale, startedAt, finishedAt, durationMs, resultClass, outputBytes = 0, artifactPath = null, exitCode = null, retryNumber = 0 }) {
+  return {
+    kind: 'tool-call',
+    tool,
+    args,
+    reason: rationale,
+    startedAt,
+    finishedAt,
+    durationMs,
+    result: resultClass,
+    outputBytes,
+    artifactPath,
+    exitCode,
+    retryNumber,
+  };
+}
+
+export { RoutingError };

package/src/harness/verification.mjs

@@ -7,13 +7,14 @@
  * Contract: docs/core/HarnessContract.md §4 (retry classifier), §5 (commands), §6 (loop).
  */
 
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createEvidence, computeInputTreeHash } from './state.mjs';
 import { hashCriteria, sha256Bytes, timestamp, newId } from './util.mjs';
 import { BudgetTracker, budgetExhaustedResult, evaluateHardStop } from './budget.mjs';
 import { redactString } from './redaction.mjs';
+import { whichAll } from './routing.mjs';
 
 export const RETRY_CLASSES = Object.freeze(['deterministic', 'transient', 'repair', 'unknown']);
 export const RESULT_STATUSES = Object.freeze(['passed', 'failed', 'flaky', 'blocked', 'timed-out']);
@@ -52,6 +53,151 @@ const DETERMINISTIC_SIGNATURES = Object.freeze([
 
 const TRANSIENT_SIGNATURES = DEFAULT_FLAKY_SIGNATURES;
 
+/**
+ * A command that never launched produced no test result, so it can never be a red.
+ *
+ * These are shell- and launcher-level signatures for "the program was not found",
+ * as distinct from "the program ran and reported failure". They matter most on
+ * Windows, where `shell: true` hands the command string to `cmd.exe`: a bare `bash`
+ * resolves through Windows PATH to the Windows Subsystem for Linux stub, which
+ * fails without ever exec'ing a shell. The command looks like it ran and failed;
+ * nothing ran at all.
+ */
+export const LAUNCH_FAILURE_SIGNATURES = Object.freeze([
+  // cmd.exe: the shell could not find the program on PATH.
+  'is not recognized as an internal or external command',
+  // POSIX shells: the shell could not find the program.
+  'command not found',
+  // The WSL launcher could not exec the distribution's shell.
+  'execvpe(',
+  'has no installed distributions',
+  'wsl (',
+]);
+
+/** POSIX shell conventions: 126 = found but not executable, 127 = command not found. */
+export const LAUNCH_FAILURE_EXIT_CODES = Object.freeze([126, 127]);
+
+/**
+ * Decide whether a result means the command never actually ran. Returns
+ * `{ launchFailed, reason }`; `reason` is a concrete diagnostic, never generic.
+ *
+ * The bias is deliberate: a launch failure must be *blocked*, never *failed*,
+ * because `failed` is the record that satisfies red-before-green. When in doubt
+ * the safe direction is "no test result", not "the tests failed".
+ */
+export function detectLaunchFailure({ exitCode = null, timedOut = false, stdout = '', stderr = '', errorMessage = '' } = {}) {
+  // A timed-out process did launch; it is not a launch failure.
+  if (timedOut) return { launchFailed: false, reason: null };
+
+  // A spawn-level error means the process was never created at all.
+  if (errorMessage) {
+    return { launchFailed: true, reason: `the process was never created (${errorMessage})` };
+  }
+
+  const haystack = `${stderr}\n${stdout}`.toLowerCase();
+  const signature = LAUNCH_FAILURE_SIGNATURES.find((s) => haystack.includes(s));
+  if (signature) {
+    return { launchFailed: true, reason: `the shell reported "${signature}"` };
+  }
+
+  if (LAUNCH_FAILURE_EXIT_CODES.includes(exitCode)) {
+    return {
+      launchFailed: true,
+      reason: `exit ${exitCode} is the shell convention for an interpreter that could not be found or executed`,
+    };
+  }
+
+  return { launchFailed: false, reason: null };
+}
+
+/**
+ * POSIX interpreters whose bare name is ambiguous under `cmd.exe`: Windows ships a
+ * `bash.exe` stub that resolves but cannot run without a WSL distribution.
+ */
+export const POSIX_INTERPRETERS = Object.freeze(['bash', 'sh', 'dash', 'zsh', 'ksh']);
+
+/** The command's first token, unwrapped from quotes. */
+export function commandInterpreter(command) {
+  if (typeof command !== 'string') return null;
+  const trimmed = command.trim();
+  if (!trimmed) return null;
+  const m = trimmed.match(/^(?:"([^"]+)"|'([^']+)'|(\S+))/);
+  return m ? (m[1] ?? m[2] ?? m[3]) : null;
+}
+
+/** Whether a resolved path is one of the Windows shims for `bash`/`wsl`. */
+export function isWslShim(path) {
+  if (typeof path !== 'string' || !path) return false;
+  const p = path.replace(/\//g, '\\').toLowerCase();
+  if (/(^|\\)system32\\bash\.exe$/.test(p)) return true;
+  if (/(^|\\)system32\\wsl\.exe$/.test(p)) return true;
+  return /(^|\\)windowsapps\\/.test(p);
+}
+
+function probeRunnable(path) {
+  // `--version` is not universal (dash's `sh` rejects it), so fall back to a
+  // trivial execution: the question is only whether this binary can run at all.
+  for (const args of [['--version'], ['-c', 'exit 0']]) {
+    try {
+      const res = spawnSync(path, args, { encoding: 'utf-8', windowsHide: true, shell: false, timeout: 10000 });
+      if (res.status === 0) return true;
+    } catch { /* try the next probe */ }
+  }
+  return false;
+}
+
+function defaultCandidates(name) {
+  return whichAll(name);
+}
+
+/**
+ * Resolve the command's interpreter before running it. Only a command led by a POSIX
+ * interpreter is checked, and only on Windows, so a `cmd` builtin or an ordinary
+ * executable is never second-guessed. The command string is not rewritten — the
+ * declaration stays the auditable record.
+ *
+ * `candidates` and `probe` are injectable so the decision is testable without
+ * depending on the host's PATH.
+ */
+export function resolveCommandInterpreter(command, {
+  platform = process.platform,
+  candidates = null,
+  probe = probeRunnable,
+} = {}) {
+  const interpreter = commandInterpreter(command);
+  const raw = interpreter ? interpreter.split(/[\\/]/).pop().toLowerCase() : null;
+  // `bash.exe` is the same ambiguity as `bash`, and `where` reports the suffixed form.
+  const base = raw ? raw.replace(/\.exe$/, '') : null;
+
+  if (!base || !POSIX_INTERPRETERS.includes(base)) {
+    return { required: false, ok: true, interpreter, usable: [], shims: [], reason: null };
+  }
+  if (platform !== 'win32') {
+    return { required: true, ok: true, interpreter, usable: [], shims: [], reason: null };
+  }
+
+  const found = (candidates ?? defaultCandidates)(base);
+  const shims = found.filter(isWslShim);
+  const usable = found.filter((p) => !isWslShim(p) && probe(p));
+  if (usable.length) {
+    return { required: true, ok: true, interpreter, usable, shims, reason: null };
+  }
+
+  let detail;
+  if (found.length === 0) {
+    detail = 'no installed copy on PATH';
+  } else if (shims.length === found.length) {
+    detail = `only the Windows Subsystem for Linux stub (${shims.join(', ')})`;
+  } else {
+    detail = 'the copy on PATH is not runnable';
+  }
+
+  return {
+    required: true, ok: false, interpreter, usable, shims,
+    reason: `'${base}' cannot be run: ${detail}. Install Git for Windows (which provides a real bash) or declare a command that does not need a POSIX interpreter.`,
+  };
+}
+
 /**
  * Classify a command result. The classifier is the single source of truth for
  * retry behavior — nothing else may decide to retry.
@@ -103,7 +249,7 @@ export function classifyRepair({ failedEvidenceId, changedFiles = [] } = {}) {
  * Run a command and capture bounded output. Never buffers unbounded output:
  * output beyond `maxInlineBytes` is written to an artifact.
  *
- * Returns `{ exitCode, signal, timedOut, stdout, stderr, durationMs, outputBytes, artifactPath, artifactHash, preview }`.
+ * Returns `{ exitCode, signal, timedOut, stdout, stderr, durationMs, outputBytes, artifactPath, artifactHash, preview, launchFailed, launchFailureReason }`.
  */
 export function runCommand(command, {
   cwd = process.cwd(),
@@ -125,6 +271,7 @@ export function runCommand(command, {
         exitCode: null, signal: null, timedOut: false, stdout: '', stderr: '',
         durationMs: Date.now() - startedAt, outputBytes: 0, artifactPath: null,
         artifactHash: null, preview: '', errorMessage: err.message,
+        launchFailed: true, launchFailureReason: `the process was never created (${err.message})`,
       });
       return;
     }
@@ -177,9 +324,11 @@ export function runCommand(command, {
         }
       }
       const preview = redactString((stdout + stderr).slice(0, previewBytes));
+      const failure = detectLaunchFailure({ exitCode, timedOut, stdout, stderr, errorMessage });
       resolve({
         exitCode, signal, timedOut, stdout, stderr, durationMs, outputBytes,
         artifactPath, artifactHash, preview, errorMessage,
+        launchFailed: failure.launchFailed, launchFailureReason: failure.reason,
       });
     };
 
@@ -265,6 +414,7 @@ export async function runVerificationLoop({
   flakySignatures = DEFAULT_FLAKY_SIGNATURES,
   priorEvidence = [],
   requireRedFirst = null,
+  resolveInterpreterImpl = resolveCommandInterpreter,
   now = () => new Date(),
 } = {}) {
   const tracker = budgets || new BudgetTracker(policy);
@@ -273,6 +423,47 @@ export async function runVerificationLoop({
   const criteriaHash = hashCriteria(criteria);
   const perStepLimit = maxAttemptsOverride ?? (policy?.budgets?.maxRetriesPerStep?.hard ?? 2) + 1;
 
+  // Refuse a command whose interpreter cannot run, before executing anything. The
+  // declared command is not rewritten — the point is that a run which never starts
+  // must not leave behind a record that could later be read as a red.
+  const interpreter = resolveInterpreterImpl(command, {});
+  if (interpreter?.required && !interpreter.ok) {
+    const detail = `command never launched: ${interpreter.reason}`;
+    const evidence = createEvidence({
+      evidenceId: newId(),
+      workItemId,
+      acceptanceCriterionId,
+      phase,
+      gate,
+      status: 'blocked',
+      command,
+      result: detail,
+      exitCode: null,
+      inputTreeHash,
+      criteriaHash,
+      relevantFiles,
+      commit,
+      createdAt: now(),
+      source: 'automated',
+    });
+    attempts.push({
+      attempt: 1,
+      spanId: newId(),
+      tool,
+      command,
+      exitCode: null,
+      durationMs: 0,
+      outputBytes: 0,
+      artifactPath: null,
+      artifactHash: null,
+      status: 'blocked',
+      retryClass: 'deterministic',
+      retryReason: 'interpreter not runnable',
+      evidence,
+    });
+    return finalize({ status: 'blocked', attempts, tracker, inputTreeHash, criteriaHash, stopReason: 'launch-failed', diagnostic: detail });
+  }
+
   // Red-before-green: a testable gate must not be satisfied by green evidence
   // unless a prior failed (red) record exists for the same work item and gate.
   // `requireRedFirst` may be set explicitly; otherwise it applies to
@@ -309,6 +500,12 @@ export async function runVerificationLoop({
     // configured budget (e.g. cost) could not be measured.
     if (hardStop.exhausted || hardStop.blocked) gatePassed = false;
 
+    // `runCommand` reports this directly; an injected runner may not, so fall back
+    // to the same detection over its result. A timed-out process did launch.
+    const launch = result.launchFailed === true
+      ? { launchFailed: true, reason: result.launchFailureReason || 'the command did not launch' }
+      : detectLaunchFailure(result);
+
     const evidence = createEvidence({
       evidenceId: newId(),
       workItemId,
@@ -317,11 +514,13 @@ export async function runVerificationLoop({
       gate,
       status: hardStop.exhausted || hardStop.blocked
         ? 'blocked'
-        : (gatePassed ? 'passed' : (result.timedOut ? 'blocked' : 'failed')),
+        : (gatePassed ? 'passed' : (result.timedOut ? 'blocked' : (launch.launchFailed ? 'blocked' : 'failed'))),
       command,
       result: hardStop.exhausted
         ? `budget-exhausted: ${hardStop.reason}`
-        : (hardStop.blocked ? `budget-blocked: ${hardStop.reason}` : describeResult(result)),
+        : (hardStop.blocked
+          ? `budget-blocked: ${hardStop.reason}`
+          : (launch.launchFailed ? `launch-failed: ${launch.reason}` : describeResult(result))),
       exitCode: result.exitCode,
       artifactPath: result.artifactPath,
       artifactHash: result.artifactHash,
@@ -343,7 +542,7 @@ export async function runVerificationLoop({
       outputBytes: result.outputBytes,
       artifactPath: result.artifactPath,
       artifactHash: result.artifactHash,
-      status: result.timedOut ? 'timed-out' : (gatePassed ? 'passed' : 'failed'),
+      status: result.timedOut ? 'timed-out' : (gatePassed ? 'passed' : (launch.launchFailed ? 'blocked' : 'failed')),
       retryClass: classification.retryClass,
       retryReason: classification.reason,
       evidence,
@@ -351,6 +550,21 @@ export async function runVerificationLoop({
 
     lastResult = result;
 
+    // A command that never launched is not a red, and is not retried: a missing or
+    // unrunnable interpreter does not appear on a second attempt. It must never reach
+    // the retry machinery or the red-before-green check, so it stops here as blocked.
+    if (launch.launchFailed) {
+      return finalize({
+        status: 'blocked',
+        attempts,
+        tracker,
+        inputTreeHash,
+        criteriaHash,
+        stopReason: 'launch-failed',
+        diagnostic: `command never launched: ${command} — ${launch.reason}`,
+      });
+    }
+
     if (hardStop.exhausted || hardStop.blocked) {
       return finalize({
         status: 'failed',