@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.955e4da0

package/src/resources/extensions/gsd/guided-flow.ts

@@ -1582,6 +1582,25 @@ function selfHealRuntimeRecords(basePath: string, ctx: ExtensionContext): { clea
   }
 }
 
+/**
+ * True when an agent turn is currently streaming or a dispatched message is
+ * still queued waiting to trigger one. Used by the pending-auto-start stale
+ * check: a live discuss turn can run for minutes before writing its first
+ * artifact, and deleting its entry as "stale" re-dispatches the workflow —
+ * resetting the interview and producing a duplicate completion turn.
+ */
+function isAgentTurnInFlight(ctx: ExtensionCommandContext): boolean {
+  try {
+    if (typeof ctx.isIdle === "function" && !ctx.isIdle()) return true;
+    if (typeof ctx.hasPendingMessages === "function" && ctx.hasPendingMessages()) return true;
+  } catch {
+    // assertActive() throws on a stale runner context; fall through to
+    // artifact/age staleness signals.
+    logWarning("guided", "isAgentTurnInFlight: ctx method threw (stale runner); assuming no turn in flight");
+  }
+  return false;
+}
+
 // ─── Milestone Actions Submenu ──────────────────────────────────────────────
 
 /**
@@ -1911,12 +1930,18 @@ export async function showSmartEntry(
     // and fires another dispatchWorkflow, resetting the conversation mid-interview.
     if (hasPendingAutoStart(basePath)) {
       // #3274: If /clear interrupted the discussion, the pending entry is stale.
-      // Detect staleness: no manifest, no milestone CONTEXT artifact, AND entry is older than
-      // 30s (avoids race between .set() and LLM writing first artifact).
+      // Detect staleness: no manifest, no milestone CONTEXT/CONTEXT-DRAFT artifact,
+      // the entry is older than 30s (avoids race between .set() and LLM writing the
+      // first artifact), AND no agent turn is in flight. A dispatched discuss turn
+      // can think for well over 30s before its first question round writes any
+      // artifact; deleting the entry while that turn is live re-dispatches the
+      // workflow, which both resets the interview and queues a duplicate turn that
+      // replays the final "context written" message after the real one.
       const entry = _getPendingAutoStart(basePath)!;
       const ageMs = Date.now() - (entry.createdAt || 0);
       const manifestExists = existsSync(join(gsdRoot(basePath), "DISCUSSION-MANIFEST.json"));
       const milestoneHasContext = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT");
+      const milestoneHasDraft = !!resolveMilestoneFile(basePath, entry.milestoneId, "CONTEXT-DRAFT");
       const milestoneHasRoadmap = !!resolveMilestoneFile(basePath, entry.milestoneId, "ROADMAP");
       const milestoneRow = isDbAvailable() ? getMilestone(entry.milestoneId) : null;
       const discussPlanComplete = milestoneHasRoadmap && !!milestoneRow && milestoneRow.status !== "queued";
@@ -1924,7 +1949,13 @@ export async function showSmartEntry(
         // The discuss flow already completed, but pending auto-start cleanup handshake did not run.
         // Clear stale in-memory guard and continue through normal active-milestone routing.
         deletePendingAutoStart(basePath);
-      } else if (!manifestExists && !milestoneHasContext && ageMs > 30_000) {
+      } else if (
+        !manifestExists &&
+        !milestoneHasContext &&
+        !milestoneHasDraft &&
+        ageMs > 30_000 &&
+        !isAgentTurnInFlight(ctx)
+      ) {
         // Stale entry from an interrupted discussion — clear and continue
         deletePendingAutoStart(basePath);
       } else {

package/src/resources/extensions/gsd/migrate/safety.ts

@@ -106,14 +106,22 @@ export function assertMigrationHasSlices(preview: MigrationPreview): void {
 }
 
 function hasWorktreeState(targetRoot: string): boolean {
-  const worktreesDir = join(gsdRoot(targetRoot), "worktrees");
-  if (!existsSync(worktreesDir)) return false;
-  try {
-    return readdirSync(worktreesDir, { withFileTypes: true })
-      .some((entry) => entry.isDirectory() || entry.isFile());
-  } catch {
-    return true;
+  const containers = [
+    join(targetRoot, ".gsd-worktrees"),
+    join(gsdRoot(targetRoot), "worktrees"),
+  ];
+  for (const worktreesDir of containers) {
+    if (!existsSync(worktreesDir)) continue;
+    try {
+      if (readdirSync(worktreesDir, { withFileTypes: true })
+        .some((entry) => entry.isDirectory() || entry.isFile())) {
+        return true;
+      }
+    } catch {
+      return true;
+    }
   }
+  return false;
 }
 
 export async function assertMigrationTargetAvailable(targetRoot: string): Promise<void> {

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -39,6 +39,9 @@ interface HierarchyScan {
   milestones: Set<string>;
   slices: Set<string>;
   tasks: Set<string>;
+  // Markdown milestones whose dir has no ROADMAP (CONTEXT/CONTEXT-DRAFT only
+  // or empty). Always empty for DB scans.
+  milestonesWithoutRoadmap: Set<string>;
 }
 
 function zeroCounts(): HierarchyCounts {
@@ -46,7 +49,13 @@ function zeroCounts(): HierarchyCounts {
 }
 
 function emptyScan(): HierarchyScan {
-  return { counts: zeroCounts(), milestones: new Set(), slices: new Set(), tasks: new Set() };
+  return {
+    counts: zeroCounts(),
+    milestones: new Set(),
+    slices: new Set(),
+    tasks: new Set(),
+    milestonesWithoutRoadmap: new Set(),
+  };
 }
 
 function sameCounts(a: HierarchyCounts, b: HierarchyCounts): boolean {
@@ -109,7 +118,10 @@ export function scanMarkdownHierarchy(basePath: string): HierarchyScan {
     scan.milestones.add(milestoneId);
 
     const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-    if (!roadmapPath || !existsSync(roadmapPath)) continue;
+    if (!roadmapPath || !existsSync(roadmapPath)) {
+      scan.milestonesWithoutRoadmap.add(milestoneId);
+      continue;
+    }
 
     const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
     scan.counts.slices += roadmap.slices.length;
@@ -164,7 +176,6 @@ export async function checkMarkdownHierarchyAgainstDb(
   basePath: string,
 ): Promise<MigrationAutoCheckResult> {
   const markdownScan = scanMarkdownHierarchy(basePath);
-  const markdown = markdownScan.counts;
 
   // Always open the DB before deciding. An empty markdown tree does NOT imply
   // an empty project — the DB may hold authoritative rows whose markdown was
@@ -184,6 +195,20 @@ export async function checkMarkdownHierarchyAgainstDb(
   const dbScan = scanDbHierarchy();
   const beforeDb = dbScan.counts;
 
+  // Discussion-phase scratch: a milestone dir with no ROADMAP and no DB row is
+  // a pre-registration discussion artifact (CONTEXT/CONTEXT-DRAFT only — the
+  // queued DB row is inserted only at discussion handoff). Treating it as
+  // drift would warn on every live discussion and recommend
+  // `/gsd recover --confirm`, an import that materializes abandoned-discussion
+  // dirs as ghost active milestones. Exclude such dirs from this comparison
+  // only; recover preflights use the raw scans and still see them.
+  for (const id of markdownScan.milestonesWithoutRoadmap) {
+    if (dbScan.milestones.has(id)) continue;
+    markdownScan.milestones.delete(id);
+    markdownScan.counts.milestones--;
+  }
+  const markdown = markdownScan.counts;
+
   const markdownEmpty = sameCounts(markdown, zeroCounts());
   const dbEmpty = sameCounts(beforeDb, zeroCounts());
 

package/src/resources/extensions/gsd/model-cost-table.ts

@@ -25,6 +25,7 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
   { id: "claude-opus-4-6", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
   { id: "claude-opus-4-7", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
   { id: "claude-opus-4-8", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-05-28" },
+  { id: "claude-fable-5", inputPer1k: 0.010, outputPer1k: 0.050, updatedAt: "2026-06-09" },
   { id: "claude-sonnet-4-6", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },
   { id: "claude-haiku-4-5", inputPer1k: 0.0008, outputPer1k: 0.004, updatedAt: "2025-03-15" },
   { id: "claude-sonnet-4-5-20250514", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },

package/src/resources/extensions/gsd/model-router.ts

@@ -101,6 +101,7 @@ export const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
   "claude-opus-4-6": "heavy",
   "claude-opus-4-7": "heavy",
   "claude-opus-4-8": "heavy",
+  "claude-fable-5": "heavy",
   "claude-3-opus-latest": "heavy",
   "gpt-4-turbo": "heavy",
   "gpt-5": "heavy",
@@ -129,6 +130,7 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "claude-opus-4-6": 0.005,
   "claude-opus-4-7": 0.005,
   "claude-opus-4-8": 0.005,
+  "claude-fable-5": 0.010,
   "gpt-4o-mini": 0.00015,
   "gpt-4o": 0.0025,
   "gpt-4.1": 0.002,
@@ -164,6 +166,7 @@ export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
   "claude-opus-4-6":              { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
   "claude-opus-4-7":              { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
   "claude-opus-4-8":              { coding: 97, debugging: 92, research: 87, reasoning: 97, speed: 30, longContext: 85, instruction: 92 },
+  "claude-fable-5":               { coding: 97, debugging: 92, research: 87, reasoning: 97, speed: 30, longContext: 85, instruction: 92 },
   "claude-sonnet-4-6":            { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
   "claude-sonnet-4-5-20250514":   { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
   "claude-3-5-sonnet-latest":     { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 70, instruction: 82 },

package/src/resources/extensions/gsd/parallel-merge.ts

@@ -9,6 +9,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { resolveGsdPathContract } from "./paths.js";
+import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { buildWorktreeLifecycleDeps } from "./auto.js";
 import {
@@ -42,7 +43,7 @@ export type MergeOrder = "sequential" | "by-completion";
  * Returns true when milestones.status = 'complete' in project gsd.db.
  */
 export function isMilestoneCompleteInProjectDb(basePath: string, mid: string): boolean {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const workRoot = worktreePathFor(basePath, mid);
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return false;
 
@@ -65,15 +66,17 @@ export function isMilestoneCompleteInProjectDb(basePath: string, mid: string): b
  */
 function discoverDbCompletedMilestones(basePath: string): Set<string> {
   const completed = new Set<string>();
-  const worktreeDir = join(basePath, ".gsd", "worktrees");
-  try {
-    for (const entry of readdirSync(worktreeDir)) {
-      if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
-        completed.add(entry);
+  for (const worktreeDir of worktreesDirs(basePath)) {
+    if (!existsSync(worktreeDir)) continue;
+    try {
+      for (const entry of readdirSync(worktreeDir)) {
+        if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
+          completed.add(entry);
+        }
       }
+    } catch (e) {
+      logWarning("parallel", `readdirSync for completed set failed: ${(e as Error).message}`);
     }
-  } catch (e) {
-    logWarning("parallel", `readdirSync for completed set failed: ${(e as Error).message}`);
   }
   return completed;
 }
@@ -120,7 +123,7 @@ export function determineMergeOrder(
         title: mid,
         pid: 0,
         process: null,
-        worktreePath: basePath ? join(basePath, ".gsd", "worktrees", mid) : "",
+        worktreePath: basePath ? worktreePathFor(basePath, mid) : "",
         startedAt: 0,
         state: "stopped",
         cost: 0,

package/src/resources/extensions/gsd/parallel-monitor-overlay.ts

@@ -11,6 +11,7 @@ import { matchesKey, Key } from "@gsd/pi-tui";
 import { formatDuration } from "../shared/mod.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { resolveGsdPathContract } from "./paths.js";
+import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 import {
   renderBar,
   renderDialogFrame,
@@ -101,7 +102,6 @@ function tailRead(filePath: string, maxBytes: number): string {
 
 function discoverWorkers(basePath: string): string[] {
   const parallelDir = join(basePath, ".gsd", "parallel");
-  const worktreeDir = join(basePath, ".gsd", "worktrees");
   const mids = new Set<string>();
 
   if (existsSync(parallelDir)) {
@@ -114,7 +114,8 @@ function discoverWorkers(basePath: string): string[] {
     } catch { /* skip */ }
   }
 
-  if (existsSync(worktreeDir)) {
+  for (const worktreeDir of worktreesDirs(basePath)) {
+    if (!existsSync(worktreeDir)) continue;
     try {
       for (const d of readdirSync(worktreeDir)) {
         if (d.startsWith("M") && existsSync(join(worktreeDir, d, ".gsd", "auto.lock"))) {
@@ -128,7 +129,7 @@ function discoverWorkers(basePath: string): string[] {
 }
 
 function querySliceProgress(basePath: string, mid: string): SliceProgress[] {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const workRoot = worktreePathFor(basePath, mid);
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
 
@@ -169,7 +170,7 @@ function extractCostFromNdjson(basePath: string, mid: string): number {
 }
 
 function queryRecentCompletions(basePath: string, mid: string): string[] {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const workRoot = worktreePathFor(basePath, mid);
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
   try {
@@ -193,7 +194,7 @@ function collectWorkerData(basePath: string): WorkerView[] {
 
   for (const mid of mids) {
     const status = readJsonSafe<StatusJson>(join(parallelDir, `${mid}.status.json`));
-    const lock = readJsonSafe<AutoLock>(join(basePath, ".gsd", "worktrees", mid, ".gsd", "auto.lock"));
+    const lock = readJsonSafe<AutoLock>(join(worktreePathFor(basePath, mid), ".gsd", "auto.lock"));
     const slices = querySliceProgress(basePath, mid);
 
     const pid = lock?.pid || status?.pid || 0;

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

@@ -17,7 +17,7 @@ import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 import { gsdHome } from "./gsd-home.js";
-import { isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { findWorktreeSegment, isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 
@@ -458,29 +458,16 @@ function assertNotGlobalGsdHome(basePath: string, result: string): void {
  * When gsdRoot() is called with such a path, we must NOT walk up to the
  * project root's .gsd — each worktree manages its own .gsd state (#2594).
  *
- * Matches both forward-slash and platform-native separators to handle
- * Windows paths (path.sep = '\\') and normalized Unix paths.
+ * Layout matching is owned by worktree-root's findWorktreeSegment; this
+ * only adds the requirement that a non-empty worktree name follows the
+ * marker (the worktrees container dir itself is not a worktree).
  */
 function isInsideGsdWorktree(p: string): boolean {
-  // Match /.gsd/worktrees/<name> where <name> is the final segment or
-  // followed by a separator. The <name> segment must be non-empty.
-  const sepFwd = "/";
-  const sepNative = "\\";
-  const markers = [
-    `${sepFwd}.gsd${sepFwd}worktrees${sepFwd}`,
-    `${sepNative}.gsd${sepNative}worktrees${sepNative}`,
-  ];
-  for (const marker of markers) {
-    const idx = p.indexOf(marker);
-    if (idx === -1) continue;
-    // Verify there's a non-empty worktree name after the marker
-    const afterMarker = p.slice(idx + marker.length);
-    // The name is everything up to the next separator (or end of string)
-    const nameEnd = afterMarker.search(/[/\\]/);
-    const name = nameEnd === -1 ? afterMarker : afterMarker.slice(0, nameEnd);
-    if (name.length > 0) return true;
-  }
-  return false;
+  const normalized = p.replaceAll("\\", "/");
+  const segment = findWorktreeSegment(normalized);
+  if (!segment) return false;
+  const name = normalized.slice(segment.afterWorktrees).split("/")[0];
+  return name.length > 0;
 }
 
 function probeGsdRoot(rawBasePath: string): string {

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

@@ -867,6 +867,24 @@ export function getIsolationMode(basePath?: string): "none" | "worktree" | "bran
   return "none"; // default — no isolation, work on current branch
 }
 
+/**
+ * Resolve the isolation mode a unit actually runs under. A session whose
+ * worktree isolation has degraded (worktree creation failed) falls back to
+ * the milestone branch in the project root, so configured "worktree" becomes
+ * effective "branch". A stranded-work recovery session likewise runs under
+ * the adopted mode (`strandedRecoveryIsolationMode`) rather than the
+ * configured one until the recovered milestone merges — adopting the
+ * milestone branch in the project root is intentional, not degraded.
+ */
+export function resolveEffectiveUnitIsolationMode(
+  configuredMode: ReturnType<typeof getIsolationMode>,
+  isolationDegraded: boolean,
+  strandedRecoveryIsolationMode: "worktree" | "branch" | null = null,
+): ReturnType<typeof getIsolationMode> {
+  if (configuredMode === "worktree" && isolationDegraded) return "branch";
+  return strandedRecoveryIsolationMode ?? configuredMode;
+}
+
 export function resolveParallelConfig(prefs: GSDPreferences | undefined): import("./types.js").ParallelConfig {
   return {
     enabled: prefs?.parallel?.enabled ?? false,

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

@@ -3,6 +3,7 @@
 
 import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
 import { ReconciliationFailedError } from "./state-reconciliation.js";
+import { IllegalPhaseTransitionError } from "./state-transition-matrix.js";
 
 export type RecoveryFailureKind =
   | "tool-schema"
@@ -13,6 +14,7 @@ export type RecoveryFailureKind =
   | "worktree-invalid"
   | "verification-drift"
   | "reconciliation-drift"
+  | "illegal-transition"
   | "provider"
   | "runtime-unknown";
 
@@ -43,7 +45,9 @@ 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":
@@ -111,6 +115,15 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
         remediation:
           "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
       };
+    case "illegal-transition":
+      return {
+        failureKind,
+        action: "escalate",
+        reason: `Illegal phase transition${unitSuffix(input)}: ${message}`,
+        exitReason: "illegal-transition",
+        remediation:
+          "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
+      };
     case "provider": {
       const providerClass = classifyError(message, input.retryAfterMs);
       return {

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

@@ -121,9 +121,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;
 

package/src/resources/extensions/gsd/safety/file-change-validator.ts

@@ -39,6 +39,20 @@ export interface FileChangeAudit {
 
 // ─── Public API ─────────────────────────────────────────────────────────────
 
+/**
+ * Build the effective allowlist for a unit's file-change audit.
+ *
+ * When GSD manages .gitignore (manage_gitignore unset or true), ensureGitignore()
+ * appends baseline patterns at auto-start and the edit rides into the task's
+ * auto-commit — so .gitignore changes must not be attributed to the task.
+ */
+export function effectiveFileChangeAllowlist(
+  baseAllowlist: string[],
+  manageGitignore: boolean | undefined,
+): string[] {
+  return manageGitignore === false ? baseAllowlist : [...baseAllowlist, ".gitignore"];
+}
+
 /**
  * Validate file changes after auto-commit for an execute-task unit.
  * Returns null if task data is unavailable or DB is not loaded.

package/src/resources/extensions/gsd/state-transition-matrix.ts

@@ -131,6 +131,48 @@ export function findTransition(
   );
 }
 
+/**
+ * Edge-keyed legality check for the Phase Transition Invariant (ADR-030).
+ * `advance()` derives the next Phase and asserts the (from → to) edge here.
+ *
+ * The matrix is an assertion, not a decision-maker — `deriveState` already
+ * chose the Phase. A self-edge is trivially legal (no transition to assert). An
+ * edge is legal when some matrix entry permits it, honoring the `*` wildcard
+ * rows (e.g. any → blocked via manual-block, any → executing via
+ * retryable-failure).
+ *
+ * Note: the matrix is currently a sparse hardening spec, not a complete
+ * legal-edge graph, so `advance()` consumes this in advisory mode (telemetry
+ * only). It must be expanded to cover every edge `deriveState` emits before
+ * enforcement flips on.
+ */
+export function isLegalEdge(from: Phase, to: Phase): boolean {
+  if (from === to) return true;
+  return STATE_TRANSITION_MATRIX.some(
+    (entry) => (entry.from === from || entry.from === "*") && entry.to === to,
+  );
+}
+
+/**
+ * Thrown when an illegal derived Phase edge survives reconciliation. Carries
+ * both endpoints so Recovery Classification can report them. Recognized by
+ * class in `classifyFailure` and mapped to the `illegal-transition` kind.
+ */
+export class IllegalPhaseTransitionError extends Error {
+  // Explicit fields, not constructor parameter properties — strip-types
+  // consumers (workspace-index subprocess, integration tests) reject the
+  // parameter-property syntax with ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX.
+  readonly from: Phase;
+  readonly to: Phase;
+
+  constructor(from: Phase, to: Phase) {
+    super(`Illegal phase transition ${from} -> ${to} survived reconciliation`);
+    this.name = "IllegalPhaseTransitionError";
+    this.from = from;
+    this.to = to;
+  }
+}
+
 export function validateTransitionMatrix(requiredEvents: readonly string[]): MatrixValidationResult {
   const seen = new Set<string>();
   const duplicateKeys: string[] = [];

package/src/resources/extensions/gsd/status-guards.ts

@@ -1,17 +1,68 @@
 /**
- * Status predicates for GSD state-machine guards.
+ * Status predicates and the canonical status vocabulary for GSD state-machine
+ * guards (ADR-030).
  *
- * The DB stores status as free-form strings. Three values indicate
- * "closed": "complete" (canonical), "done" (legacy / alias),
- * "closed" (legacy/imported), and
- * "skipped" (user-directed skip via rethink or backtrack).
- * Every inline `status === "complete" || status === "done"` should
- * use isClosedStatus() instead.
+ * The DB column is free-form `string` so legacy/imported rows still load. Three
+ * raw values besides canonical "complete"/"skipped" indicate "closed": "done"
+ * (legacy alias), "closed" (legacy/imported), and "skipped" (user-directed skip
+ * via rethink or backtrack). `RAW_CLOSED_STATUSES` is the single source for both
+ * `isClosedStatus()` and the SQL terminal-status fragment
+ * (`db/sql-constants.ts` derives `TERMINAL_STATUS_SQL` from it), replacing the
+ * prior independent definitions.
+ *
+ * `toStatus()` is the single seam where a free-form string becomes the canonical
+ * `Status` vocabulary; the Status Transition Core writes canonical, so the store
+ * converges over time without a forced migration.
+ */
+
+/**
+ * Canonical, normalized entity-status vocabulary across milestones, slices, and
+ * tasks — the single source for both the `Status` type and the runtime
+ * membership set. The in-memory domain speaks `Status`; the DB column stays
+ * free-form.
+ */
+export const CANONICAL_STATUSES = [
+  "pending", "queued", "active", "parked", "in_progress", "blocked", "complete", "skipped", "deferred",
+] as const;
+export type Status = (typeof CANONICAL_STATUSES)[number];
+const CANONICAL_STATUS_SET: ReadonlySet<string> = new Set(CANONICAL_STATUSES);
+
+/**
+ * Raw status values that mean a unit is closed — the single source of truth.
+ * Includes legacy/imported aliases ("done", "closed") alongside canonical
+ * "complete"/"skipped" because the DB column is free-form and older rows /
+ * imports still carry them. Order matters: `TERMINAL_STATUS_SQL` is derived
+ * from this array verbatim.
+ */
+export const RAW_CLOSED_STATUSES = ["complete", "done", "skipped", "closed"] as const;
+const RAW_CLOSED_SET: ReadonlySet<string> = new Set(RAW_CLOSED_STATUSES);
+
+/** Free-form aliases mapped to their canonical Status on read. */
+const ALIAS_TO_CANONICAL: Readonly<Record<string, Status>> = {
+  done: "complete",
+  closed: "complete",
+  planned: "pending",
+  "in-progress": "in_progress",
+};
+
+/**
+ * Normalize a free-form DB status string into the canonical `Status`
+ * vocabulary. Maps known aliases (done/closed → complete, planned → pending,
+ * in-progress → in_progress). An unrecognized/legacy value is **quarantined** —
+ * preserved verbatim rather than silently remapped to a wrong canonical state —
+ * so reads never fail and reconciliation/telemetry can surface it.
  */
+export function toStatus(raw: string): Status {
+  const value = raw.trim();
+  if (CANONICAL_STATUS_SET.has(value)) return value as Status;
+  const alias = ALIAS_TO_CANONICAL[value];
+  if (alias) return alias;
+  return value as Status;
+}
 
 /** Returns true when a milestone, slice, or task status indicates closure. */
 export function isClosedStatus(status: string): boolean {
-  return status === "complete" || status === "done" || status === "skipped" || status === "closed";
+  return RAW_CLOSED_SET.has(status);
 }
 
 /** Returns true when a slice status indicates it was deferred by a decision. */