gsd-pi 2.52.0 → 2.53.0-dev.a67436f

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -157,6 +157,25 @@ function clearProjectRootStateFiles(basePath: string, milestoneId: string): void
   }
 }
 
+// ─── Build Artifact Auto-Resolve ─────────────────────────────────────────────
+
+/** Patterns for machine-generated build artifacts that can be safely
+ * auto-resolved by accepting --theirs during merge. These files are
+ * regenerable and never contain meaningful manual edits. */
+export const SAFE_AUTO_RESOLVE_PATTERNS: RegExp[] = [
+  /\.tsbuildinfo$/,
+  /\.pyc$/,
+  /\/__pycache__\//,
+  /\.DS_Store$/,
+  /\.map$/,
+];
+
+/** Returns true if the file path is safe to auto-resolve during merge.
+ * Covers `.gsd/` state files and common build artifacts. */
+export const isSafeToAutoResolve = (filePath: string): boolean =>
+  filePath.startsWith(".gsd/") ||
+  SAFE_AUTO_RESOLVE_PATTERNS.some((re) => re.test(filePath));
+
 // ─── Dispatch-Level Sync (project root ↔ worktree) ──────────────────────────
 
 /**
@@ -1408,30 +1427,30 @@ export function mergeMilestoneToMain(
         : nativeConflictFiles(originalBasePath_);
 
     if (conflictedFiles.length > 0) {
-      // Separate .gsd/ state file conflicts from real code conflicts.
-      // GSD state files (STATE.md, auto.lock, etc.)
-      // diverge between branches during normal operation — always prefer the
-      // milestone branch version since it has the latest execution state.
-      const gsdConflicts = conflictedFiles.filter((f) => f.startsWith(".gsd/"));
+      // Separate auto-resolvable conflicts (GSD state files + build artifacts)
+      // from real code conflicts. GSD state files diverge between branches
+      // during normal operation. Build artifacts are machine-generated and
+      // regenerable. Both are safe to accept from the milestone branch.
+      const autoResolvable = conflictedFiles.filter(isSafeToAutoResolve);
       const codeConflicts = conflictedFiles.filter(
-        (f) => !f.startsWith(".gsd/"),
+        (f) => !isSafeToAutoResolve(f),
       );
 
-      // Auto-resolve .gsd/ conflicts by accepting the milestone branch version
-      if (gsdConflicts.length > 0) {
-        for (const gsdFile of gsdConflicts) {
+      // Auto-resolve safe conflicts by accepting the milestone branch version
+      if (autoResolvable.length > 0) {
+        for (const safeFile of autoResolvable) {
           try {
-            nativeCheckoutTheirs(originalBasePath_, [gsdFile]);
-            nativeAddPaths(originalBasePath_, [gsdFile]);
+            nativeCheckoutTheirs(originalBasePath_, [safeFile]);
+            nativeAddPaths(originalBasePath_, [safeFile]);
           } catch {
             // If checkout --theirs fails, try removing the file from the merge
             // (it's a runtime file that shouldn't be committed anyway)
-            nativeRmForce(originalBasePath_, [gsdFile]);
+            nativeRmForce(originalBasePath_, [safeFile]);
           }
         }
       }
 
-      // If there are still non-.gsd conflicts, escalate
+      // If there are still real code conflicts, escalate
       if (codeConflicts.length > 0) {
         // Pop stash before throwing so local work is not lost (#2151).
         if (stashed) {
@@ -1480,7 +1499,47 @@ export function mergeMilestoneToMain(
         encoding: "utf-8",
       });
     } catch {
-      // Stash pop conflict is non-fatal — stash entry persists for manual resolution.
+      // Stash pop after squash merge can conflict on .gsd/ state files that
+      // diverged between branches.  Left unresolved, these UU entries block
+      // every subsequent merge.  Auto-resolve them the same way we handle
+      // .gsd/ conflicts during the merge itself: accept HEAD (the just-committed
+      // version) and drop the now-applied stash.
+      const uu = nativeConflictFiles(originalBasePath_);
+      const gsdUU = uu.filter((f) => f.startsWith(".gsd/"));
+      const nonGsdUU = uu.filter((f) => !f.startsWith(".gsd/"));
+
+      if (gsdUU.length > 0) {
+        for (const f of gsdUU) {
+          try {
+            // Accept the committed (HEAD) version of the state file
+            execFileSync("git", ["checkout", "HEAD", "--", f], {
+              cwd: originalBasePath_,
+              stdio: ["ignore", "pipe", "pipe"],
+              encoding: "utf-8",
+            });
+            nativeAddPaths(originalBasePath_, [f]);
+          } catch {
+            // Last resort: remove the conflicted state file
+            nativeRmForce(originalBasePath_, [f]);
+          }
+        }
+      }
+
+      if (nonGsdUU.length === 0) {
+        // All conflicts were .gsd/ files — safe to drop the stash
+        try {
+          execFileSync("git", ["stash", "drop"], {
+            cwd: originalBasePath_,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+          });
+        } catch { /* stash may already be consumed */ }
+      } else {
+        // Non-.gsd conflicts remain — leave stash for manual resolution
+        logWarning("reconcile", "Stash pop conflict on non-.gsd files after merge", {
+          files: nonGsdUU.join(", "),
+        });
+      }
     }
   }
 

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

@@ -414,6 +414,13 @@ export function stopAutoRemote(projectRoot: string): {
   const lock = readCrashLock(projectRoot);
   if (!lock) return { found: false };
 
+  // Never SIGTERM ourselves — a stale lock with our own PID is not a remote
+  // session, it is leftover from a prior loop exit in this process. (#2730)
+  if (lock.pid === process.pid) {
+    clearLock(projectRoot);
+    return { found: false };
+  }
+
   if (!isLockProcessAlive(lock)) {
     // Stale lock — clean it up
     clearLock(projectRoot);
@@ -445,6 +452,10 @@ export function checkRemoteAutoSession(projectRoot: string): {
   const lock = readCrashLock(projectRoot);
   if (!lock) return { running: false };
 
+  // Our own PID is not a "remote" session — it is a stale lock left by this
+  // process (e.g. after step-mode exit without full cleanup). (#2730)
+  if (lock.pid === process.pid) return { running: false };
+
   if (!isLockProcessAlive(lock)) {
     // Stale lock from a dead process — not a live remote session
     return { running: false };
@@ -548,6 +559,16 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
   s.active = false;
   clearUnitTimeout();
 
+  // Clear crash lock and release session lock so the next `/gsd next` does
+  // not see a stale lock with the current PID and treat it as a "remote"
+  // session (which would cause it to SIGTERM itself). (#2730)
+  try {
+    if (lockBase()) clearLock(lockBase());
+    if (lockBase()) releaseSessionLock(lockBase());
+  } catch {
+    /* best-effort — mirror stopAuto cleanup */
+  }
+
   ctx.ui.setStatus("gsd-auto", undefined);
   ctx.ui.setWidget("gsd-progress", undefined);
   ctx.ui.setFooter(undefined);

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -107,16 +107,9 @@ export async function handleAgentEnd(
       ctx.ui.notify(`Network retries exhausted for ${currentModelId}. Attempting model fallback.`, "warning");
     }
 
-    // --- Rate limit: skip model fallback, go straight to pause ---
-    // Rate-limiting is a provider issue, not a model issue.
-    // Switching models won't help if the provider is throttling you.
-    if (cls.kind === "rate-limit") {
-      await pauseTransientWithBackoff(cls, pi, ctx, errorDetail, true);
-      return;
-    }
-
-    // --- Server/connection/stream errors: try model fallback first ---
-    if (cls.kind === "network" || cls.kind === "server" || cls.kind === "connection" || cls.kind === "stream") {
+    // --- Transient errors: try model fallback first, then pause ---
+    // Rate limits are often per-model, so switching models can bypass them.
+    if (cls.kind === "rate-limit" || cls.kind === "network" || cls.kind === "server" || cls.kind === "connection" || cls.kind === "stream") {
       // Try model fallback
       const dash = getAutoDashboardData();
       if (dash.currentUnit) {
@@ -161,7 +154,7 @@ export async function handleAgentEnd(
 
     // --- Transient fallback: pause with auto-resume ---
     if (isTransient(cls)) {
-      await pauseTransientWithBackoff(cls, pi, ctx, errorDetail, false);
+      await pauseTransientWithBackoff(cls, pi, ctx, errorDetail, cls.kind === "rate-limit");
       return;
     }
 

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -390,7 +390,7 @@ async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string,
   const gitBooleanFields = [
     { key: "auto_push", label: "Auto-push commits after committing", defaultVal: false },
     { key: "push_branches", label: "Push milestone branches to remote", defaultVal: false },
-    { key: "snapshots", label: "Create WIP snapshot commits during long tasks", defaultVal: false },
+    { key: "snapshots", label: "Create WIP snapshot commits during long tasks", defaultVal: true },
   ] as const;
 
   for (const field of gitBooleanFields) {
@@ -423,7 +423,7 @@ async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string,
   // pre_merge_check
   const currentPreMerge = git.pre_merge_check !== undefined ? String(git.pre_merge_check) : "";
   const preMergeChoice = await ctx.ui.select(
-    `Pre-merge check${currentPreMerge ? ` (current: ${currentPreMerge})` : " (default: false)"}:`,
+    `Pre-merge check${currentPreMerge ? ` (current: ${currentPreMerge})` : " (default: auto)"}:`,
     ["true", "false", "auto", "(keep current)"],
   );
   if (preMergeChoice && preMergeChoice !== "(keep current)") {
@@ -588,7 +588,7 @@ export async function configureMode(ctx: ExtensionCommandContext, prefs: Record<
     if (modeStr.startsWith("solo")) {
       prefs.mode = "solo";
       ctx.ui.notify(
-        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=false, merge_strategy=squash, isolation=worktree, unique_milestone_ids=false",
+        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=auto, merge_strategy=squash, isolation=worktree, unique_milestone_ids=false",
         "info",
       );
     } else if (modeStr.startsWith("team")) {

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -126,8 +126,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `auto_push`: boolean — automatically push commits to the remote after committing. Default: `false`.
   - `push_branches`: boolean — push the milestone branch to the remote after commits. Default: `false`.
   - `remote`: string — git remote name to push to. Default: `"origin"`.
-  - `snapshots`: boolean — create snapshot commits (WIP saves) during long-running tasks. Default: `false`.
-  - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a worktree back to the integration branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `false`.
+  - `snapshots`: boolean — create snapshot commits (WIP saves) during long-running tasks. Default: `true`.
+  - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a worktree back to the integration branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `"auto"`.
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.

package/src/resources/extensions/gsd/git-service.ts

@@ -605,11 +605,12 @@ export class GitServiceImpl {
 
   /**
    * Create a snapshot ref for the given label (typically a slice branch name).
-   * Gated on prefs.snapshots === true. Ref path: refs/gsd/snapshots/<label>/<timestamp>
+   * Enabled by default; opt out with prefs.snapshots === false.
+   * Ref path: refs/gsd/snapshots/<label>/<timestamp>
    * The ref points at HEAD, capturing the current commit before destructive operations.
    */
   createSnapshot(label: string): void {
-    if (this.prefs.snapshots !== true) return;
+    if (this.prefs.snapshots === false) return;
 
     const now = new Date();
     const ts = now.getFullYear().toString()
@@ -631,7 +632,7 @@ export class GitServiceImpl {
    * Stub: to be implemented in T03.
    */
   runPreMergeCheck(): PreMergeCheckResult {
-    if (this.prefs.pre_merge_check === false || this.prefs.pre_merge_check === undefined) {
+    if (this.prefs.pre_merge_check === false) {
       return { passed: true, skipped: true };
     }
 

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

@@ -517,8 +517,9 @@ export async function showDiscuss(
 
   const state = await deriveState(basePath);
 
-  // No active milestone — check for pending milestones to discuss instead
-  if (!state.activeMilestone) {
+  // No active milestone (or corrupted milestone with undefined id) —
+  // check for pending milestones to discuss instead
+  if (!state.activeMilestone?.id) {
     const pendingMilestones = state.registry.filter(m => m.status === "pending");
     if (pendingMilestones.length === 0) {
       ctx.ui.notify("No active milestone. Run /gsd to create one first.", "warning");
@@ -1043,7 +1044,7 @@ export async function showSmartEntry(
 
   const state = await deriveState(basePath);
 
-  if (!state.activeMilestone) {
+  if (!state.activeMilestone?.id) {
     // Guard: if a discuss session is already in flight, don't re-inject the prompt.
     // Both /gsd and /gsd auto reach this branch when no milestone exists yet.
     // Without this guard, every subsequent /gsd call overwrites pendingAutoStart

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -9,6 +9,7 @@
 // parseRoadmap(), parsePlan(), parseSummary() in files.ts.
 
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { isClosedStatus } from "./status-guards.js";
 import { join, relative } from "node:path";
 import { createRequire } from "node:module";
 import {
@@ -337,7 +338,7 @@ function renderSlicePlanMarkdown(slice: SliceRow, tasks: TaskRow[], gates: GateR
   lines.push("## Tasks");
   lines.push("");
   for (const task of tasks) {
-    const done = task.status === "done" || task.status === "complete" ? "x" : " ";
+    const done = isClosedStatus(task.status) ? "x" : " ";
     const estimate = task.estimate.trim() ? ` \`est:${task.estimate.trim()}\`` : "";
     lines.push(`- [${done}] **${task.id}: ${task.title || task.id}**${estimate}`);
     if (task.description.trim()) {
@@ -573,7 +574,7 @@ export async function renderPlanCheckboxes(
   // Apply checkbox patches for each task
   let updated = content;
   for (const task of tasks) {
-    const isDone = task.status === "done" || task.status === "complete";
+    const isDone = isClosedStatus(task.status);
     const tid = task.id;
 
     if (isDone) {
@@ -857,7 +858,7 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
           const parsed = parsePlan(content);
 
           for (const task of tasks) {
-            const isDoneInDb = task.status === "done" || task.status === "complete";
+            const isDoneInDb = isClosedStatus(task.status);
             const planTask = parsed.tasks.find((t: { id: string }) => t.id === task.id);
             if (!planTask) continue;
 
@@ -880,7 +881,7 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
 
       // Check missing task summary files
       for (const task of tasks) {
-        if ((task.status === "done" || task.status === "complete") && task.full_summary_md) {
+        if (isClosedStatus(task.status) && task.full_summary_md) {
           const slicePath = resolveSlicePath(basePath, milestone.id, slice.id);
           if (slicePath) {
             const tasksDir = join(slicePath, "tasks");

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

@@ -196,7 +196,17 @@ function appendWorkerLog(basePath: string, milestoneId: string, chunk: string):
 }
 
 function restoreRuntimeState(basePath: string): boolean {
-  if (state?.active) return true;
+  if (state?.active) {
+    // Verify at least one worker is alive — if all are in terminal states,
+    // the cached state is stale and we should fall through to cleanup.
+    const hasLiveWorker = [...state.workers.values()].some(
+      (w) => w.state !== "error" && w.state !== "stopped",
+    );
+    if (hasLiveWorker) return true;
+
+    // All workers dead — clear stale state so restoreState() can clean up.
+    state = null;
+  }
 
   const restored = restoreState(basePath);
   if (restored && restored.workers.length > 0) {
@@ -932,6 +942,18 @@ export function refreshWorkerStatuses(
     state.totalCost += worker.cost;
   }
 
+  // If all workers are in a terminal state (error/stopped), the orchestration
+  // is finished — deactivate and clean up so zombie workers don't persist.
+  const allDead = [...state.workers.values()].every(
+    (w) => w.state === "error" || w.state === "stopped",
+  );
+  if (allDead) {
+    state.active = false;
+    removeStateFile(basePath);
+    state = null;
+    return;
+  }
+
   // Persist updated state for crash recovery
   persistState(basePath);
 }

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

@@ -33,7 +33,7 @@ export const MODE_DEFAULTS: Record<WorkflowMode, Partial<GSDPreferences>> = {
     git: {
       auto_push: true,
       push_branches: false,
-      pre_merge_check: false,
+      pre_merge_check: "auto",
       merge_strategy: "squash",
       isolation: "none",
     },

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

@@ -36,6 +36,7 @@ import {
 
 import { findMilestoneIds } from './milestone-ids.js';
 import { loadQueueOrder, sortByQueueOrder } from './queue-order.js';
+import { isClosedStatus } from './status-guards.js';
 import { nativeBatchParseGsdFiles, type BatchParsedFile } from './native-parser-bridge.js';
 
 import { join, resolve } from 'path';
@@ -89,18 +90,13 @@ export function isMilestoneComplete(roadmap: Roadmap): boolean {
 }
 
 /**
- * Check whether a VALIDATION file's verdict is terminal (pass or needs-attention).
- * A non-terminal verdict (needs-remediation) means validation must re-run
- * after remediation slices are executed.
+ * Check whether a VALIDATION file's verdict is terminal.
+ * Any successfully extracted verdict (pass, needs-attention, needs-remediation,
+ * fail, etc.) means validation completed. Only return false when no verdict
+ * could be parsed — i.e. extractVerdict() returns undefined (#2769).
  */
 export function isValidationTerminal(validationContent: string): boolean {
-  const v = extractVerdict(validationContent);
-  if (!v) return false;
-  // 'pass' and 'needs-attention' are always terminal.
-  // 'needs-remediation' is treated as terminal to prevent infinite loops
-  // when no remediation slices exist in the roadmap (#832). The validation
-  // report is preserved on disk for manual review.
-  return v === 'pass' || v === 'needs-attention' || v === 'needs-remediation';
+  return extractVerdict(validationContent) != null;
 }
 
 // ─── State Derivation ──────────────────────────────────────────────────────
@@ -272,13 +268,6 @@ function extractContextTitle(content: string | null, fallback: string): string {
 
 // ─── DB-backed State Derivation ────────────────────────────────────────────
 
-/**
- * Helper: check if a DB status counts as "done" (handles K002 ambiguity).
- */
-function isStatusDone(status: string): boolean {
-  return status === 'complete' || status === 'done';
-}
-
 /**
  * Derive GSD state from the milestones/slices/tasks DB tables.
  * Flag files (PARKED, VALIDATION, CONTINUE, REPLAN, REPLAN-TRIGGER, CONTEXT-DRAFT)
@@ -368,7 +357,7 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
       continue;
     }
 
-    if (isStatusDone(m.status)) {
+    if (isClosedStatus(m.status)) {
       completeMilestoneIds.add(m.id);
       continue;
     }
@@ -382,7 +371,7 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
 
     // Check roadmap: all slices done means milestone is complete
     const slices = getMilestoneSlices(m.id);
-    if (slices.length > 0 && slices.every(s => isStatusDone(s.status))) {
+    if (slices.length > 0 && slices.every(s => isClosedStatus(s.status))) {
       // All slices done but no summary — still counts as complete for dep resolution
       // if a summary file exists
       // Note: without summary file, the milestone is in validating/completing state, not complete
@@ -404,7 +393,7 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
 
     // Ghost milestone check: no slices in DB AND no substantive files on disk
     const slices = getMilestoneSlices(m.id);
-    if (slices.length === 0 && !isStatusDone(m.status)) {
+    if (slices.length === 0 && !isClosedStatus(m.status)) {
       // Check disk for ghost detection
       if (isGhostMilestone(basePath, m.id)) continue;
     }
@@ -427,7 +416,7 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
     }
 
     // Not complete — determine if it should be active
-    const allSlicesDone = slices.length > 0 && slices.every(s => isStatusDone(s.status));
+    const allSlicesDone = slices.length > 0 && slices.every(s => isClosedStatus(s.status));
 
     // Get title — prefer DB, fall back to context file extraction
     let title = stripMilestonePrefix(m.title) || m.id;
@@ -582,7 +571,7 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
   // Guard: [].every() === true (vacuous truth). Without the length check,
   // an empty slice array causes a premature phase transition to
   // validating-milestone. See: https://github.com/gsd-build/gsd-2/issues/2667
-  const allSlicesDone = activeMilestoneSlices.length > 0 && activeMilestoneSlices.every(s => isStatusDone(s.status));
+  const allSlicesDone = activeMilestoneSlices.length > 0 && activeMilestoneSlices.every(s => isClosedStatus(s.status));
   if (allSlicesDone) {
     const validationFile = resolveMilestoneFile(basePath, activeMilestone.id, "VALIDATION");
     const validationContent = validationFile ? await loadFile(validationFile) : null;
@@ -615,19 +604,19 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
 
   // ── Find active slice (first incomplete with deps satisfied) ─────────
   const sliceProgress = {
-    done: activeMilestoneSlices.filter(s => isStatusDone(s.status)).length,
+    done: activeMilestoneSlices.filter(s => isClosedStatus(s.status)).length,
     total: activeMilestoneSlices.length,
   };
 
   const doneSliceIds = new Set(
-    activeMilestoneSlices.filter(s => isStatusDone(s.status)).map(s => s.id)
+    activeMilestoneSlices.filter(s => isClosedStatus(s.status)).map(s => s.id)
   );
 
   let activeSlice: ActiveRef | null = null;
   let activeSliceRow: SliceRow | null = null;
 
   for (const s of activeMilestoneSlices) {
-    if (isStatusDone(s.status)) continue;
+    if (isClosedStatus(s.status)) continue;
     if (s.depends.every(dep => doneSliceIds.has(dep))) {
       activeSlice = { id: s.id, title: s.title };
       activeSliceRow = s;
@@ -670,7 +659,7 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
   // causing the dispatcher to re-dispatch the same completed task forever.
   let reconciled = false;
   for (const t of tasks) {
-    if (isStatusDone(t.status)) continue;
+    if (isClosedStatus(t.status)) continue;
     const summaryPath = resolveTaskFile(basePath, activeMilestone.id, activeSlice.id, t.id, "SUMMARY");
     if (summaryPath && existsSync(summaryPath)) {
       try {
@@ -693,11 +682,11 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
   }
 
   const taskProgress = {
-    done: tasks.filter(t => isStatusDone(t.status)).length,
+    done: tasks.filter(t => isClosedStatus(t.status)).length,
     total: tasks.length,
   };
 
-  const activeTaskRow = tasks.find(t => !isStatusDone(t.status));
+  const activeTaskRow = tasks.find(t => !isClosedStatus(t.status));
 
   if (!activeTaskRow && tasks.length > 0) {
     // All tasks done but slice not marked complete → summarizing
@@ -758,7 +747,7 @@ export async function deriveStateFromDb(basePath: string): Promise<GSDState> {
   }
 
   // ── Blocker detection: check completed tasks for blocker_discovered ──
-  const completedTasks = tasks.filter(t => isStatusDone(t.status));
+  const completedTasks = tasks.filter(t => isClosedStatus(t.status));
   let blockerTaskId: string | null = null;
   for (const ct of completedTasks) {
     if (ct.blocker_discovered) {

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

@@ -0,0 +1,13 @@
+/**
+ * Status predicates for GSD state-machine guards.
+ *
+ * The DB stores status as free-form strings. Two values indicate
+ * "closed": "complete" (canonical) and "done" (legacy / alias).
+ * Every inline `status === "complete" || status === "done"` should
+ * use isClosedStatus() instead.
+ */
+
+/** Returns true when a milestone, slice, or task status indicates closure. */
+export function isClosedStatus(status: string): boolean {
+  return status === "complete" || status === "done";
+}

package/src/resources/extensions/gsd/tests/active-milestone-id-guard.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Regression test for #2773 — activeMilestone.id guard
+ *
+ * When activeMilestone is a non-null object with `id: undefined` (corrupted
+ * state), the old `!state.activeMilestone` truthiness check passed through,
+ * causing a downstream crash when code assumed `.id` was a valid string.
+ *
+ * The fix uses optional chaining (`!state.activeMilestone?.id`) so all three
+ * "no usable milestone" shapes are caught:
+ *   1. activeMilestone === null
+ *   2. activeMilestone === undefined
+ *   3. activeMilestone === { id: undefined, title: "..." }
+ */
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import type { GSDState, ActiveRef } from '../types.ts'
+
+// ─── Guard Under Test ────────────────────────────────────────────────────────
+// Extracted guard logic identical to headless-query.ts (line 74) and
+// guided-flow.ts (lines 522, 1047).
+
+function activeMilestoneIsUsable(activeMilestone: ActiveRef | null | undefined): boolean {
+  return !!activeMilestone?.id
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('activeMilestone?.id guard (#2773)', () => {
+  it('rejects null activeMilestone', () => {
+    assert.equal(activeMilestoneIsUsable(null), false)
+  })
+
+  it('rejects undefined activeMilestone', () => {
+    assert.equal(activeMilestoneIsUsable(undefined), false)
+  })
+
+  it('rejects malformed activeMilestone with id: undefined', () => {
+    // This is the crash case from #2773 — object exists but id is undefined
+    const malformed = { id: undefined, title: 'Ghost Milestone' } as unknown as ActiveRef
+    assert.equal(activeMilestoneIsUsable(malformed), false)
+  })
+
+  it('rejects malformed activeMilestone with id: empty string', () => {
+    const malformed = { id: '', title: 'Empty ID Milestone' } as unknown as ActiveRef
+    assert.equal(activeMilestoneIsUsable(malformed), false)
+  })
+
+  it('accepts valid activeMilestone with a real id', () => {
+    const valid: ActiveRef = { id: 'M001', title: 'Real Milestone' }
+    assert.equal(activeMilestoneIsUsable(valid), true)
+  })
+})
+
+describe('headless-query stop behavior with corrupted milestone', () => {
+  // Simulates the decision logic from handleQuery (headless-query.ts:74-78)
+  function deriveNextAction(activeMilestone: ActiveRef | null | undefined, phase: string) {
+    if (!activeMilestone?.id) {
+      return {
+        action: 'stop' as const,
+        reason: phase === 'complete' ? 'All milestones complete.' : 'No active milestone.',
+      }
+    }
+    return { action: 'dispatch' as const, unitId: activeMilestone.id }
+  }
+
+  it('returns stop when activeMilestone is null', () => {
+    const result = deriveNextAction(null, 'pre-planning')
+    assert.equal(result.action, 'stop')
+  })
+
+  it('returns stop when activeMilestone has undefined id', () => {
+    const corrupted = { id: undefined, title: 'Corrupted' } as unknown as ActiveRef
+    const result = deriveNextAction(corrupted, 'executing')
+    assert.equal(result.action, 'stop')
+    assert.equal(result.reason, 'No active milestone.')
+  })
+
+  it('returns dispatch with valid milestone id', () => {
+    const valid: ActiveRef = { id: 'M001', title: 'Valid' }
+    const result = deriveNextAction(valid, 'executing')
+    assert.equal(result.action, 'dispatch')
+  })
+
+  it('returns correct stop reason when phase is complete', () => {
+    const result = deriveNextAction(null, 'complete')
+    assert.equal(result.action, 'stop')
+    assert.equal(result.reason, 'All milestones complete.')
+  })
+})