@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

package/src/resources/extensions/gsd/quick.ts

@@ -10,8 +10,8 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, relative } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { QUICK_BRANCH_RE } from "./branch-patterns.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
@@ -31,6 +31,7 @@ interface QuickReturnState {
 }
 
 let pendingQuickReturn: QuickReturnState | null = null;
+const pendingQuickReturnMisses = new Map<string, string>();
 
 // ─── Quick Task Helpers ───────────────────────────────────────────────────────
 
@@ -189,12 +190,35 @@ export function buildQuickCommitInstruction(basePath: string, root: string): str
   ].join("\n");
 }
 
+function readHeadBranchName(basePath: string): string | null {
+  try {
+    const gitPath = join(basePath, ".git");
+    if (!existsSync(gitPath)) return null;
+
+    let headPath: string;
+    if (lstatSync(gitPath).isDirectory()) {
+      headPath = join(gitPath, "HEAD");
+    } else {
+      const gitFile = readFileSync(gitPath, "utf-8").trim();
+      if (!gitFile.startsWith("gitdir: ")) return null;
+      headPath = join(resolve(basePath, gitFile.slice("gitdir: ".length)), "HEAD");
+    }
+
+    const head = readFileSync(headPath, "utf-8").trim();
+    if (!head.startsWith("ref: refs/heads/")) return null;
+    return head.slice("ref: refs/heads/".length);
+  } catch {
+    return null;
+  }
+}
+
 function quickReturnStatePath(basePath: string): string {
   return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
 
 function persistPendingReturn(state: QuickReturnState): void {
   pendingQuickReturn = state;
+  pendingQuickReturnMisses.delete(state.basePath);
   mkdirSync(join(gsdRoot(state.basePath), "runtime"), { recursive: true });
   writeFileSync(quickReturnStatePath(state.basePath), JSON.stringify(state) + "\n", "utf-8");
 }
@@ -203,6 +227,13 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
   if (pendingQuickReturn && pendingQuickReturn.basePath === basePath) {
     return pendingQuickReturn;
   }
+  if (pendingQuickReturnMisses.has(basePath)) {
+    const statePath = quickReturnStatePath(basePath);
+    if (!existsSync(statePath) && readHeadBranchName(basePath) === pendingQuickReturnMisses.get(basePath)) {
+      return null;
+    }
+    pendingQuickReturnMisses.delete(basePath);
+  }
 
   try {
     const raw = readFileSync(quickReturnStatePath(basePath), "utf-8");
@@ -216,6 +247,7 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
       && typeof parsed.description === "string"
     ) {
       pendingQuickReturn = parsed as QuickReturnState;
+      pendingQuickReturnMisses.delete(basePath);
       return pendingQuickReturn;
     }
   } catch {
@@ -225,9 +257,14 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
   const inferred = inferQuickReturnFromBranch(basePath);
   if (inferred) {
     pendingQuickReturn = inferred;
+    pendingQuickReturnMisses.delete(basePath);
     return inferred;
   }
 
+  const branchAtMiss = readHeadBranchName(basePath);
+  if (branchAtMiss) {
+    pendingQuickReturnMisses.set(basePath, branchAtMiss);
+  }
   return null;
 }
 
@@ -235,6 +272,10 @@ function clearPendingReturn(basePath: string): void {
   if (pendingQuickReturn?.basePath === basePath) {
     pendingQuickReturn = null;
   }
+  const branchAtMiss = readHeadBranchName(basePath);
+  if (branchAtMiss) {
+    pendingQuickReturnMisses.set(basePath, branchAtMiss);
+  }
   rmSync(quickReturnStatePath(basePath), { force: true });
 }
 

package/src/resources/extensions/gsd/reactive-graph.ts

@@ -12,7 +12,11 @@
 import type { TaskIO, DerivedTaskNode, ReactiveExecutionState } from "./types.js";
 import { loadFile, parseTaskPlanIO } from "./files.js";
 import { isDbAvailable, getSliceTasks } from "./gsd-db.js";
+// Explicit degraded-mode fallback ONLY (ADR-017): parsePlan is consulted when
+// the DB is unavailable or has no task rows for the slice; the DB path in
+// loadSliceTaskIO always wins when rows exist, and the fallback logs a warning.
 import { parsePlan } from "./parsers-legacy.js";
+import { logWarning } from "./workflow-logger.js";
 import { resolveTasksDir, resolveTaskFiles } from "./paths.js";
 import { join } from "node:path";
 import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
@@ -224,7 +228,13 @@ export async function loadSliceTaskIO(
   } catch { /* fall through */ }
 
   if (!taskEntries) {
-    // File-based fallback: parse slice plan for task entries
+    // Degraded-mode fallback (ADR-017): no DB task rows for this slice —
+    // parse the PLAN.md projection instead. Warn so silent drift from the
+    // DB-authoritative path is visible in logs.
+    logWarning(
+      "projection",
+      `reactive-graph: DB unavailable or no task rows for ${mid}/${sid}; falling back to PLAN.md parsing`,
+    );
     const parsed = parsePlan(planContent);
     if (parsed.tasks.length > 0) {
       taskEntries = parsed.tasks.map(t => ({

package/src/resources/extensions/gsd/recovery-classification.ts

@@ -1,18 +1,24 @@
 // Project/App: gsd-pi
 // File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
 
+import { isToolUnavailableError } from "./auto-tool-tracking.js";
 import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
+import { recoveryRemediation } from "./guidance.js";
+import { isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
+import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 
 export type RecoveryFailureKind =
   | "tool-schema"
   | "tool-contract"
+  | "tool-unavailable"
   | "deterministic-policy"
   | "lifecycle-progression"
   | "stale-worker"
   | "worktree-invalid"
   | "verification-drift"
   | "reconciliation-drift"
+  | "illegal-transition"
   | "provider"
   | "runtime-unknown";
 
@@ -43,99 +49,59 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
   const failureKind =
     input.error instanceof ReconciliationFailedError
       ? "reconciliation-drift"
-      : input.failureKind ?? inferFailureKind(message);
+      : input.error instanceof IllegalPhaseTransitionError
+        ? "illegal-transition"
+        : input.failureKind ?? inferFailureKind(message);
 
-  switch (failureKind) {
-    case "tool-schema":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Tool schema failure${unitSuffix(input)}: ${message}`,
-        exitReason: "tool-schema",
-        remediation: "Fix the Unit Tool Contract or tool schema before retrying.",
-      };
-    case "tool-contract":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Tool Contract failure${unitSuffix(input)}: ${message}`,
-        exitReason: "tool-contract",
-        remediation: "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
-      };
-    case "deterministic-policy":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Deterministic policy failure${unitSuffix(input)}: ${message}`,
-        exitReason: "deterministic-policy",
-        remediation: "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
-      };
-    case "lifecycle-progression":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Lifecycle progression failure${unitSuffix(input)}: ${message}`,
-        exitReason: "lifecycle-progression",
-        remediation: "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
-      };
-    case "stale-worker":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Stale worker failure${unitSuffix(input)}: ${message}`,
-        exitReason: "stale-worker",
-        remediation: "Clear or reconcile the stale worker before dispatching another Unit.",
-      };
-    case "worktree-invalid":
-      return {
-        failureKind,
-        action: "stop",
-        reason: `Worktree invalid${unitSuffix(input)}: ${message}`,
-        exitReason: "worktree-invalid",
-        remediation: "Repair or recreate the milestone worktree before launching source-writing Units.",
-      };
-    case "verification-drift":
-      return {
-        failureKind,
-        action: "escalate",
-        reason: `Verification drift${unitSuffix(input)}: ${message}`,
-        exitReason: "verification-drift",
-        remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
-      };
-    case "reconciliation-drift":
-      return {
-        failureKind,
-        action: "escalate",
-        reason: `Reconciliation drift${unitSuffix(input)}: ${message}`,
-        exitReason: "reconciliation-drift",
-        remediation:
-          "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
-      };
-    case "provider": {
-      const providerClass = classifyError(message, input.retryAfterMs);
-      return {
-        failureKind,
-        action: isTransient(providerClass) ? "retry" : "escalate",
-        reason: message,
-        exitReason: `provider-${providerClass.kind}`,
-        remediation: isTransient(providerClass)
-          ? "Retry after the provider/network condition clears."
-          : "Inspect provider credentials, model entitlement, or request shape.",
-        providerClass: providerClass.kind,
-      };
-    }
-    case "runtime-unknown":
-      return {
-        failureKind,
-        action: "escalate",
-        reason: message,
-        exitReason: "runtime-unknown",
-        remediation: "Inspect the runtime error and add a dedicated classification if it is repeatable.",
-      };
+  if (failureKind === "provider") {
+    const providerClass = classifyError(message, input.retryAfterMs);
+    const transient = isTransient(providerClass);
+    return {
+      failureKind,
+      action: transient ? "retry" : "escalate",
+      reason: message,
+      exitReason: `provider-${providerClass.kind}`,
+      remediation: recoveryRemediation(transient ? "provider-transient" : "provider-permanent"),
+      providerClass: providerClass.kind,
+    };
   }
+
+  const { action, label } = FAILURE_TAXONOMY[failureKind];
+  return {
+    failureKind,
+    action,
+    reason: label ? `${label}${unitSuffix(input)}: ${message}` : message,
+    exitReason: failureKind,
+    remediation: recoveryRemediation(failureKind),
+  };
 }
 
+/** Per-kind action and reason label. Remediation lives in the Guidance module. */
+const FAILURE_TAXONOMY: Record<
+  Exclude<RecoveryFailureKind, "provider">,
+  { action: RecoveryAction; label: string | null }
+> = {
+  "tool-schema": { action: "stop", label: "Tool schema failure" },
+  "tool-contract": { action: "stop", label: "Tool Contract failure" },
+  "tool-unavailable": { action: "retry", label: "Tool unavailable" },
+  "deterministic-policy": { action: "stop", label: "Deterministic policy failure" },
+  "lifecycle-progression": { action: "stop", label: "Lifecycle progression failure" },
+  "stale-worker": { action: "stop", label: "Stale worker failure" },
+  "worktree-invalid": { action: "stop", label: "Worktree invalid" },
+  "verification-drift": { action: "escalate", label: "Verification drift" },
+  "reconciliation-drift": { action: "escalate", label: "Reconciliation drift" },
+  "illegal-transition": { action: "escalate", label: "Illegal phase transition" },
+  "runtime-unknown": { action: "escalate", label: null },
+};
+
 function inferFailureKind(message: string): RecoveryFailureKind {
+  // A terminal tool-surface failure (workflow MCP server in failed/needs-auth/
+  // disabled) will not self-heal, so it must escalate rather than retry the
+  // same model into the per-unit cost cap. Checked before the generic
+  // tool-unavailable branch, which matches the same readiness prefix and
+  // would otherwise route it to retry. See #783.
+  if (isTerminalToolSurfaceError(message)) return "runtime-unknown";
+  if (isToolUnavailableError(message)) return "tool-unavailable";
   if (/tool contract|auto-unit tool scope|phase-boundary gate|not permitted.*own/i.test(message)) return "tool-contract";
   if (/lifecycle progression|required artifact|missing .*assessment|missing .*closeout|cannot legally (?:advance|progress)/i.test(message)) return "lifecycle-progression";
   if (/schema|invalid.*tool|tool.*invalid|enum/i.test(message)) return "tool-schema";

package/src/resources/extensions/gsd/roadmap-slices.ts

@@ -154,6 +154,29 @@ function parseTableSlices(section: string): RoadmapSliceEntry[] {
   return slices;
 }
 
+function looksLikeTable(section: string): boolean {
+  const lines = section.split("\n");
+
+  // Checkbox format takes precedence — embedded demo tables must not switch mode (#721).
+  if (lines.some(line => /^\s*-\s+\[[ xX]\]/.test(line))) {
+    return false;
+  }
+
+  const pipeLines = lines.filter(line => /^\s*\|/.test(line));
+  if (pipeLines.length < 2) return false;
+
+  const hasSeparatorRow = pipeLines.some((line, index) => {
+    if (index === 0) return false;
+    const cells = line.split("|").map(c => c.trim()).filter(Boolean);
+    return /^\s*\|[\s:-]+\|/.test(line) && cells.length >= 2 && cells.every(c => /^[\s:-]+$/.test(c));
+  });
+
+  if (hasSeparatorRow) return true;
+
+  // Tables without a separator row still expose slice IDs in data rows.
+  return pipeLines.some(line => /\bS\d+\b/.test(line));
+}
+
 export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
   const slicesSection = extractSlicesSection(content);
   if (!slicesSection) {
@@ -165,9 +188,11 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
 
   // Try table format first — if the section contains pipe-delimited rows with
   // slice IDs, parse them as a table (#1736).
-  const tableSlices = parseTableSlices(slicesSection);
-  if (tableSlices.length > 0) {
-    return tableSlices;
+  if (looksLikeTable(slicesSection)) {
+    const tableSlices = parseTableSlices(slicesSection);
+    if (tableSlices.length > 0) {
+      return tableSlices;
+    }
   }
 
   // Standard checkbox format
@@ -176,7 +201,7 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
   let currentSlice: RoadmapSliceEntry | null = null;
 
   for (const line of checkboxItems) {
-    const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/);
+    const cbMatch = line.match(/^\s*-\s+\[([ xX])\]\s+\*\*([\w.-]+):\s+(.+?)\*\*\s*(.*)/);
     if (cbMatch) {
       if (currentSlice) slices.push(currentSlice);
 
@@ -189,9 +214,15 @@ export function parseRoadmapSlices(content: string): RoadmapSliceEntry[] {
       const risk = (riskMatch ? riskMatch[1] : "low") as RiskLevel;
 
       const depsMatch = rest.match(/`depends:\[([^\]]*)\]`/);
-      const depends = depsMatch && depsMatch[1]!.trim()
-        ? expandDependencies(depsMatch[1]!.split(",").map(s => s.trim()))
+      // Recovery fallback: double-bracket form `[[id]]` from serialized bracket-wrapped IDs
+      const fallbackDepsMatch = depsMatch ? null : rest.match(/`depends:\[(\[(?:[^\]]*)\](?:,\[(?:[^\]]*)\])*)\]`/);
+      const rawDepContent = (depsMatch ?? fallbackDepsMatch)?.[1] ?? "";
+      const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+      const RANGE_RE = /^[A-Za-z]+\d+(?:-|\.\.)[A-Za-z]+\d+$/;
+      const rawDepParts = rawDepContent.trim()
+        ? rawDepContent.replace(/\[|\]/g, "").split(",").map(s => s.trim()).filter(s => SLICE_ID_RE.test(s) || RANGE_RE.test(s))
         : [];
+      const depends = expandDependencies(rawDepParts);
 
       // ADR-011: the renderer writes a `[sketch]` badge for sketch slices.
       // Parse it back so the is_sketch flag survives a markdown → DB re-import

package/src/resources/extensions/gsd/safety/content-validator.ts

@@ -46,7 +46,8 @@ export function validateContent(
 
 type ContentValidatorFn = (content: string) => ContentViolation[];
 
-const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+:|#{2,4}\s+T\d+\b)/gm;
+// Matches both legacy "**T01: title**" and flat-phase "**T01**: title" checkbox formats.
+const TASK_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*T\d+(?:\*\*)?:|#{2,4}\s+T\d+\b)/gm;
 const SLICE_MARKER_RE = /^\s*(?:-\s+\[[ xX]\]\s+\*\*S\d+:|#{2,4}\s+S\d+\b)/gm;
 
 const VALIDATORS: Record<string, ContentValidatorFn> = {

package/src/resources/extensions/gsd/safety/destructive-confirmation.ts

@@ -0,0 +1,134 @@
+/**
+ * One-shot confirmation token for destructive bash commands.
+ *
+ * The destructive-command guard hard-blocks classified commands (force push,
+ * rm -rf, SQL drop, etc.) in all modes. The block instructs the model to
+ * confirm via ask_user_questions and re-issue the command. This module is the
+ * missing escape hatch: it records the user's confirmation and lets the exact
+ * confirmed command through exactly once.
+ *
+ * Design constraints:
+ *  - In-memory only, never persisted. A confirmation token written to disk
+ *    could silently auto-approve a destructive command in a later session —
+ *    confirmation must be re-obtained every process lifetime.
+ *  - One-shot. Consuming a token clears it, so a second destructive command
+ *    (even an identical one) re-blocks and re-prompts.
+ *  - Command-bound. The token only matches the exact (normalized) command
+ *    string the user confirmed. A reworded command re-blocks, which is safe.
+ *  - Per basePath, so concurrent workspaces in one process never share tokens.
+ *
+ * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+ */
+
+import { resolve } from "node:path";
+
+/**
+ * Question-id substring that marks an ask_user_questions call as a
+ * destructive-command confirmation. The tool_result handler promotes the
+ * pending command to a confirmed token when an affirmative answer arrives for
+ * a question whose id contains this marker.
+ */
+export const DESTRUCTIVE_CONFIRM_GATE_MARKER = "destructive_confirm";
+
+interface DestructiveConfirmationState {
+  /** Command awaiting confirmation, captured when the guard blocked it. */
+  pendingCommand: string | null;
+  /** Confirmed command cleared on first matching consume. */
+  confirmedCommand: string | null;
+}
+
+const statesByBasePath = new Map<string, DestructiveConfirmationState>();
+
+function stateKey(basePath: string): string {
+  return resolve(basePath);
+}
+
+function getState(basePath: string): DestructiveConfirmationState {
+  const key = stateKey(basePath);
+  let state = statesByBasePath.get(key);
+  if (!state) {
+    state = { pendingCommand: null, confirmedCommand: null };
+    statesByBasePath.set(key, state);
+  }
+  return state;
+}
+
+/**
+ * Normalize a command for stable matching across block → confirm → retry.
+ * Trims surrounding whitespace and collapses internal runs of whitespace so
+ * cosmetic reformatting of the same command still matches the token.
+ */
+export function normalizeDestructiveCommand(command: string): string {
+  return command.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Whether an ask_user_questions question id is a destructive-confirm gate.
+ */
+export function isDestructiveConfirmGateId(questionId: unknown): boolean {
+  return typeof questionId === "string" && questionId.includes(DESTRUCTIVE_CONFIRM_GATE_MARKER);
+}
+
+/**
+ * Record that a destructive command was blocked and is awaiting confirmation.
+ * Called by the guard at block time. Overwrites any prior pending command —
+ * only the most recently blocked command can be confirmed.
+ */
+export function requestDestructiveConfirmation(
+  command: string,
+  basePath: string = process.cwd(),
+): void {
+  const state = getState(basePath);
+  state.pendingCommand = normalizeDestructiveCommand(command);
+  // A fresh request invalidates any stale confirmed token for a different
+  // command so confirmation cannot leak across distinct destructive actions.
+  state.confirmedCommand = null;
+}
+
+/**
+ * Promote the pending command to a confirmed, one-shot token. Called by the
+ * tool_result handler when the user gives an affirmative answer to a
+ * destructive-confirm gate. Returns the confirmed command, or null if there
+ * was nothing pending (e.g. confirmation arrived without a preceding block).
+ */
+export function confirmDestructiveCommand(
+  basePath: string = process.cwd(),
+): string | null {
+  const state = getState(basePath);
+  if (!state.pendingCommand) return null;
+  state.confirmedCommand = state.pendingCommand;
+  state.pendingCommand = null;
+  return state.confirmedCommand;
+}
+
+/**
+ * Check whether the given command has been confirmed, consuming the token if
+ * so. Returns true exactly once per confirmation; subsequent calls (or a
+ * non-matching command) return false. Called by the guard before blocking.
+ */
+export function consumeDestructiveConfirmation(
+  command: string,
+  basePath: string = process.cwd(),
+): boolean {
+  const state = getState(basePath);
+  if (!state.confirmedCommand) return false;
+  if (state.confirmedCommand !== normalizeDestructiveCommand(command)) return false;
+  state.confirmedCommand = null;
+  return true;
+}
+
+/**
+ * Inspect the pending command without consuming it (diagnostics/tests).
+ */
+export function peekPendingDestructiveCommand(
+  basePath: string = process.cwd(),
+): string | null {
+  return getState(basePath).pendingCommand;
+}
+
+/**
+ * Clear all destructive-confirmation state for a basePath (tests / flow reset).
+ */
+export function resetDestructiveConfirmation(basePath: string = process.cwd()): void {
+  statesByBasePath.delete(stateKey(basePath));
+}

package/src/resources/extensions/gsd/safety/evidence-collector.ts

@@ -57,9 +57,10 @@ const EXECUTION_TOOL_NAMES = new Set([
   "functions.exec_command",
   "gsd_exec",
   "gsd_exec_search",
+  "gsd_uat_exec",
   "powershell",
 ]);
-const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_exec(?:_search)?$/;
+const MCP_EXECUTION_TOOL_RE = /^mcp__.+__gsd_(?:uat_)?exec(?:_search)?$/;
 
 // ─── Module State ───────────────────────────────────────────────────────────
 
@@ -206,11 +207,17 @@ export function clearEvidenceFromDisk(
  * Exit codes and output are filled in by recordToolResult after execution.
  */
 export function recordToolCall(toolCallId: string, toolName: string, input: Record<string, unknown>): void {
+  // Idempotent by toolCallId: native tools reach this via both
+  // tool_execution_start and tool_call; external (pre-executed) tools only
+  // via tool_execution_start. First recording wins.
+  if (unitEvidence.some(e => e.toolCallId === toolCallId)) return;
   if (isExecutionToolName(toolName)) {
     unitEvidence.push({
       kind: "bash",
       toolCallId,
-      command: String(input.command ?? input.cmd ?? input.query ?? ""),
+      // gsd_exec / gsd_uat_exec carry the script body in `script` (or `code`);
+      // bash-style tools use `command`/`cmd`; gsd_exec_search uses `query`.
+      command: String(input.command ?? input.script ?? input.cmd ?? input.code ?? input.query ?? ""),
       exitCode: -1,
       outputSnippet: "",
       timestamp: Date.now(),
@@ -249,11 +256,36 @@ export function recordToolResult(
   if (entry.kind === "bash") {
     const text = extractResultText(result);
     entry.outputSnippet = text.slice(0, 500);
-    const exitMatch = text.match(/Command exited with code (\d+)/);
-    entry.exitCode = exitMatch ? Number(exitMatch[1]) : (isError ? 1 : 0);
+    entry.exitCode = resolveExitCode(text, isError);
   }
 }
 
+/**
+ * Resolve the exit code from a tool result's text. Handles the bash tool's
+ * prose marker, the gsd_exec / gsd_uat_exec JSON envelope (`"exit_code": N`),
+ * and a last-resort read of the run's persisted `.gsd/exec/<id>.meta.json`
+ * (covers truncated result text).
+ */
+function resolveExitCode(text: string, isError: boolean): number {
+  const proseMatch = text.match(/Command exited with code (\d+)/);
+  if (proseMatch) return Number(proseMatch[1]);
+
+  const jsonMatch = text.match(/"exit_code"\s*:\s*(-?\d+)/);
+  if (jsonMatch) return Number(jsonMatch[1]);
+
+  const metaMatch = text.match(/"meta_path"\s*:\s*"([^"]+)"/);
+  if (metaMatch) {
+    try {
+      const meta = JSON.parse(readFileSync(metaMatch[1], "utf-8")) as Record<string, unknown>;
+      if (typeof meta.exit_code === "number") return meta.exit_code;
+    } catch {
+      // Fall through to the isError heuristic
+    }
+  }
+
+  return isError ? 1 : 0;
+}
+
 // ─── Internals ──────────────────────────────────────────────────────────────
 
 function extractResultText(result: unknown): string {

package/src/resources/extensions/gsd/safety/evidence-cross-ref.ts

@@ -66,8 +66,28 @@ export function crossReferenceEvidence(
       continue;
     }
 
+    // A shell-spawn/infra failure means the command never ran (e.g. on Windows
+    // `gsd_exec runtime=bash` resolves to a WSL with no /bin/bash). The LLM
+    // typically recovers by re-running via another runtime, and that genuine
+    // run may not even be in the match set. Such a failure is inconclusive, not
+    // a falsified pass — exclude it before judging the exit code.
+    const commandRuns = matches.filter((m) => !isInfraSpawnFailure(m));
+    if (commandRuns.length === 0) {
+      if (claimed.exitCode === 0) {
+        mismatches.push({
+          severity: "warning",
+          claimed,
+          actual: latestMatch(matches),
+          reason:
+            `Matched execution failed to spawn (infrastructure error, not a command failure); ` +
+            `treating as inconclusive`,
+        });
+      }
+      continue;
+    }
+
     // Exit code mismatch: LLM claims success but actual command failed
-    const match = latestMatch(matches);
+    const match = latestMatch(commandRuns);
     if (claimed.exitCode === 0 && match.exitCode !== 0) {
       mismatches.push({
         severity: "error",
@@ -81,6 +101,30 @@ export function crossReferenceEvidence(
   return mismatches;
 }
 
+/**
+ * Runtime-spawn / shell-infra failure signatures. When a bash-runtime call
+ * fails to *spawn* (rather than the command running and exiting non-zero), the
+ * recorded exitCode is an ordinary non-zero but the output carries one of these
+ * markers. Such a call is not evidence that a verification failed.
+ */
+const INFRA_SPAWN_FAILURE_SIGNATURES: readonly RegExp[] = [
+  /execvpe\([^)]*\)\s+failed/i,   // WSL: execvpe(/bin/bash) failed: No such file or directory
+  /WSL \(.*\) ERROR/i,            // WSL relay error banner
+  /command not found:\s*(?:bash|sh|zsh|dash|fish|ash|ksh|wsl)\b/i, // missing shell interpreter only
+];
+
+/**
+ * True when a non-zero bash call looks like a shell-spawn/infra failure (the
+ * command never started) rather than a real command failure. A successful run
+ * (exitCode 0) is never an infra failure.
+ */
+function isInfraSpawnFailure(call: BashEvidence): boolean {
+  if (call.exitCode === 0) return false;
+  const snippet = call.outputSnippet ?? "";
+  if (snippet.length === 0) return false;
+  return INFRA_SPAWN_FAILURE_SIGNATURES.some((re) => re.test(snippet));
+}
+
 // ─── Internals ──────────────────────────────────────────────────────────────
 
 /**
@@ -121,9 +165,14 @@ function findMatches(
   const exact = bashCalls.filter(b => b.command.trim() === normalized);
   if (exact.length > 0) return exact;
 
-  // Substring match: claimed is contained in actual or actual in claimed
+  // Substring match: claimed is contained in actual or actual in claimed.
+  // A claimed verification command typically appears verbatim inside a
+  // larger gsd_exec script body (cd prefix, multi-line scripts), so
+  // script-containing-claim is the common direction. Blank-command entries
+  // must be excluded — `"x".includes("")` is true, so they'd match anything.
   const substring = bashCalls.filter(
-    b => b.command.includes(normalized) || normalized.includes(b.command),
+    b => b.command.trim().length > 0 &&
+      (b.command.includes(normalized) || normalized.includes(b.command)),
   );
   if (substring.length > 0) return substring;