gsd-pi 2.82.0-dev.9d5798940 → 2.82.0-dev.dfbc5f58f

package/src/resources/GSD-WORKFLOW.md

@@ -448,6 +448,13 @@ What differed from the plan and why (or "None").
 
 The one-liner must be substantive: "JWT auth with refresh rotation using jose" not "Authentication implemented."
 
+When `key_files` or `key_decisions` are empty, render them as empty YAML lists:
+
+```yaml
+key_files: []
+key_decisions: []
+```
+
 **Slice summary:** Written when all tasks in a slice complete. Compresses all task summaries. Includes `drill_down_paths` to each task summary. During slice completion, review task summaries for `key_decisions` and ensure any significant ones are captured in `.gsd/DECISIONS.md`.
 
 **Milestone summary:** Updated each time a slice completes. Compresses all slice summaries. This is what gets injected into later slice planning instead of loading many individual summaries.

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

@@ -47,12 +47,20 @@ export interface DispatchAdapter {
     sessionProvider?: string;
     /** Model registry for executor-model lookups inside the budget engine. */
     modelRegistry?: MinimalModelRegistry;
-  }): Promise<{
-    unitType: string;
-    unitId: string;
-    reason: string;
-    preconditions: string[];
-  } | null>;
+  }): Promise<
+    | {
+        kind: "blocked";
+        reason: string;
+        action: "pause" | "stop";
+      }
+    | {
+        unitType: string;
+        unitId: string;
+        reason: string;
+        preconditions: string[];
+      }
+    | null
+  >;
 }
 
 export interface RecoveryAdapter {

package/src/resources/extensions/gsd/auto/infra-errors.ts

@@ -7,9 +7,14 @@
  */
 
 /**
- * Error codes indicating infrastructure failures that cannot be recovered by
- * retrying. Each retry re-dispatches the unit at full LLM cost, so we bail
- * immediately rather than burning budget on guaranteed failures.
+ * Error codes indicating infrastructure-level failures from the OS,
+ * filesystem, or network. This set includes permanent resource failures
+ * (ENOSPC, ENOMEM, EROFS), transient resource exhaustion (EAGAIN, ENOBUFS),
+ * and network/offline errors (ECONNREFUSED, ENOTFOUND, ENETUNREACH).
+ *
+ * Transient git failures are retried separately through
+ * TRANSIENT_GIT_RETRY_CODES in native-git-bridge.ts before escalating to the
+ * auto-loop.
  */
 export const INFRA_ERROR_CODES: ReadonlySet<string> = new Set([
   "ENOSPC",   // disk full
@@ -19,6 +24,7 @@ export const INFRA_ERROR_CODES: ReadonlySet<string> = new Set([
   "EMFILE",   // too many open files (process)
   "ENFILE",   // too many open files (system)
   "EAGAIN",       // resource temporarily unavailable (resource exhaustion)
+  "ENOBUFS",      // no buffer space available (transient pipe exhaustion)
   "ECONNREFUSED", // connection refused (offline / local server down)
   "ENOTFOUND",    // DNS lookup failed (offline / no network)
   "ENETUNREACH",  // network unreachable (offline / no route)

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

@@ -78,7 +78,10 @@ import { createWorkflowTurnReporter } from "./workflow-turn-reporter.js";
 import { validateWorkflowSessionLock } from "./workflow-session-lock.js";
 import { dequeueSidecarItem } from "./workflow-sidecar-queue.js";
 import { maintainWorkerHeartbeat } from "./workflow-worker-heartbeat.js";
-import { measureMemoryPressure } from "./workflow-memory-pressure.js";
+import {
+  measureMemoryPressure,
+  shouldCheckMemoryPressure,
+} from "./workflow-memory-pressure.js";
 import { buildSidecarIterationData } from "./workflow-sidecar-iteration.js";
 import {
   createExecutionGraphUnitDispatchDeps,
@@ -203,9 +206,9 @@ function logCustomVerifyRetrySaveFailure(err: unknown): void {
 }
 
 // ── Memory pressure monitoring (#3331) ──────────────────────────────────
-// Check heap usage every N iterations and trigger graceful shutdown before
-// the OS OOM killer sends SIGKILL. The threshold is 90% of the V8 heap
-// limit (--max-old-space-size or default ~1.5-4GB depending on platform).
+// Check heap usage on session startup, then every N iterations, and trigger
+// graceful shutdown before the OS OOM killer sends SIGKILL. The threshold is
+// 90% of the V8 heap limit (--max-old-space-size or default ~1.5-4GB depending on platform).
 const MEMORY_CHECK_INTERVAL = 5; // check every 5 iterations
 const MAX_CUSTOM_ENGINE_VERIFY_RETRIES = 3;
 
@@ -372,7 +375,7 @@ export async function autoLoop(
 
     // ── Memory pressure check (#3331) ──
     // Graceful shutdown before OOM killer sends SIGKILL.
-    if (iteration % MEMORY_CHECK_INTERVAL === 0) {
+    if (shouldCheckMemoryPressure(iteration, MEMORY_CHECK_INTERVAL)) {
       const mem = measureMemoryPressure();
       debugLog("autoLoop", { phase: "memory-check", ...mem });
       const memoryDecision = decideMemoryPressure({ ...mem, iteration });

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

@@ -128,6 +128,17 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         await this.deps.health.postAdvanceRecord(stopped);
         return stopped;
       }
+      if (!("unitType" in decision)) {
+        const blocked: AutoAdvanceResult = {
+          kind: "blocked",
+          reason: decision.reason,
+          action: decision.action,
+          stateSnapshot: reconciliation.stateSnapshot,
+        };
+        await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
+        await this.deps.health.postAdvanceRecord(blocked);
+        return blocked;
+      }
 
       const nextKey = `${decision.unitType}:${decision.unitId}`;
 

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

@@ -1327,9 +1327,15 @@ export async function runDispatch(
   }
 
   const guardBasePath = _resolveDispatchGuardBasePath(s);
+  let mainBranch = "main";
+  try {
+    mainBranch = deps.getMainBranch(guardBasePath);
+  } catch (err) {
+    debugLog("autoLoop", { phase: "getMainBranch-failed", error: String(err) });
+  }
   const priorSliceBlocker = deps.getPriorSliceCompletionBlocker(
     guardBasePath,
-    deps.getMainBranch(guardBasePath),
+    mainBranch,
     unitType,
     unitId,
   );

package/src/resources/extensions/gsd/auto/workflow-memory-pressure.ts

@@ -19,6 +19,19 @@ export interface MeasureMemoryPressureDeps {
   heapLimitBytes: () => number;
 }
 
+/**
+ * Returns true on auto-mode startup, then every configured interval.
+ *
+ * Iteration 1 is checked explicitly so early session memory pressure cannot
+ * bypass the periodic interval guard.
+ */
+export function shouldCheckMemoryPressure(iteration: number, interval: number): boolean {
+  if (!Number.isInteger(interval) || interval <= 0) {
+    throw new Error("Memory pressure check interval must be a positive integer");
+  }
+  return iteration === 1 || iteration % interval === 0;
+}
+
 function defaultHeapLimitBytes(): number {
   const v8 = require("node:v8") as {
     getHeapStatistics?: () => { heap_size_limit?: number };

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -615,10 +615,11 @@ export async function selectAndApplyModel(
  * Handles formats: "provider/model", "bare-id", "org/model-name" (OpenRouter).
  */
 export function resolveModelId<T extends { id: string; provider: string }>(
-  modelId: string,
+  modelId: string | undefined,
   availableModels: T[],
   currentProvider: string | undefined,
 ): T | undefined {
+  if (!modelId) return undefined;
   const slashIdx = modelId.indexOf("/");
 
   if (slashIdx !== -1) {

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -164,7 +164,7 @@ async function buildTaskCommitContextForUnit(
     sliceTitle: stripKnownIdPrefix(slice?.title, sid),
     oneLiner: summary?.oneLiner || task?.one_liner || undefined,
     keyFiles:
-      summary?.frontmatter.key_files?.filter(f => !f.includes("{{")) ??
+      summary?.frontmatter.key_files?.filter(f => !f.includes("{{") && f.trim() !== "(none)") ??
       task?.key_files ??
       undefined,
     issueNumber: ghIssueNumber,

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

@@ -44,6 +44,7 @@ import {
   nativeDetectMainBranch,
   nativeCheckoutBranch,
   nativeBranchList,
+  nativeBranchExists,
   nativeBranchListMerged,
   nativeBranchDelete,
   nativeWorktreeRemove,
@@ -64,7 +65,7 @@ import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
 import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactive.js";
 import { snapshotSkills } from "./skill-discovery.js";
-import { isDbAvailable, getMilestone, openDatabase, getDbStatus } from "./gsd-db.js";
+import { isDbAvailable, getMilestone, getAllMilestones, openDatabase, getDbStatus } from "./gsd-db.js";
 import { isClosedStatus } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { auditOrphanedPreflightStashes } from "./orphan-stash-audit.js";
@@ -101,6 +102,7 @@ import { getSessionModelOverride } from "./session-model-override.js";
 export interface BootstrapDeps {
   shouldUseWorktreeIsolation: (basePath?: string) => boolean;
   registerSigtermHandler: (basePath: string) => void;
+  registerAutoWorkerForSession: (basePath: string) => void;
   lockBase: () => string;
   buildLifecycle: () => WorktreeLifecycle;
 }
@@ -202,9 +204,15 @@ export function decideSurvivorAction(
 export function auditOrphanedMilestoneBranches(
   basePath: string,
   isolationMode: "worktree" | "branch" | "none",
+  gitDeps: {
+    branchList?: typeof nativeBranchList;
+    branchExists?: typeof nativeBranchExists;
+  } = {},
 ): { recovered: string[]; warnings: string[] } {
   const recovered: string[] = [];
   const warnings: string[] = [];
+  const branchList = gitDeps.branchList ?? nativeBranchList;
+  const branchExists = gitDeps.branchExists ?? nativeBranchExists;
 
   // Skip in none mode — no milestone branches are created
   if (isolationMode === "none") return { recovered, warnings };
@@ -213,15 +221,16 @@ export function auditOrphanedMilestoneBranches(
   if (!isDbAvailable()) return { recovered, warnings };
 
   let milestoneBranches: string[];
+  let milestoneBranchListAvailable = true;
   try {
-    milestoneBranches = nativeBranchList(basePath, "milestone/*");
+    milestoneBranches = branchList(basePath, "milestone/*");
   } catch {
-    // git branch list failed — skip audit
-    return { recovered, warnings };
+    milestoneBranchListAvailable = false;
+    // git branch list failed — fall through with an empty branch set so the
+    // branch-less orphan pass can still run after per-milestone verification.
+    milestoneBranches = [];
   }
 
-  if (milestoneBranches.length === 0) return { recovered, warnings };
-
   // Detect main branch for merge-check
   let mainBranch: string;
   try {
@@ -354,6 +363,74 @@ export function auditOrphanedMilestoneBranches(
     }
   }
 
+  // Second pass (#5879): catch worktree directories stranded by a previous
+  // audit that deleted the milestone/* branch but failed to remove the
+  // directory (or the dir was orphaned by a separate path entirely, e.g.
+  // postflight-stash-restore-failed during closeout). The branch-keyed loop
+  // above is invisible to these cases — `nativeBranchList` returns nothing
+  // for the milestone, so the dir-cleanup block at line ~310 is never
+  // reached.
+  //
+  // Keyed on milestones whose DB status is `complete`. We do not iterate
+  // over arbitrary directories under .gsd/worktrees/ to avoid touching
+  // dirs that belong to an in-progress milestone whose branch was deleted
+  // separately — those are handled by the in-progress orphan path above
+  // when the branch is present, and by `/gsd doctor` when it is not.
+  const seenMilestoneIds = new Set(
+    milestoneBranches.map((branch) => branch.replace(/^milestone\//, "")),
+  );
+  let completedMilestones: readonly { id: string; status: string }[] = [];
+  try {
+    completedMilestones = getAllMilestones();
+  } catch {
+    // DB read failure — skip the second pass; the first pass is still useful.
+    completedMilestones = [];
+  }
+  for (const m of completedMilestones) {
+    if (m.status !== "complete") continue;
+    if (seenMilestoneIds.has(m.id)) continue; // already processed in the branch loop
+    if (!milestoneBranchListAvailable) {
+      try {
+        if (branchExists(basePath, `milestone/${m.id}`)) continue;
+      } catch (err) {
+        warnings.push(
+          `Could not verify whether milestone/${m.id} still exists; skipping branch-less worktree cleanup for safety: ${err instanceof Error ? err.message : String(err)}`,
+        );
+        continue;
+      }
+    }
+    const wtDir = getWorktreeDir(basePath, m.id);
+    if (!existsSync(wtDir)) continue;
+    if (!isInsideWorktreesDir(basePath, wtDir)) {
+      warnings.push(
+        `Orphaned worktree directory for ${m.id} is outside .gsd/worktrees/ — skipping removal for safety.`,
+      );
+      continue;
+    }
+    // Try `git worktree remove` first in case the dir is still registered
+    // (defensive — usually it is not when we reach this branch-less pass).
+    try {
+      nativeWorktreeRemove(basePath, wtDir, true);
+    } catch (e) {
+      logWarning(
+        "engine",
+        `worktree remove failed (expected for branch-less orphans): ${e instanceof Error ? e.message : String(e)}`,
+      );
+    }
+    if (existsSync(wtDir)) {
+      try {
+        rmSync(wtDir, { recursive: true, force: true });
+        recovered.push(`Removed orphaned worktree directory for ${m.id} (branch already deleted).`);
+      } catch (err) {
+        warnings.push(
+          `Failed to remove orphaned worktree directory for ${m.id}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    } else {
+      recovered.push(`Removed orphaned worktree directory for ${m.id} (branch already deleted).`);
+    }
+  }
+
   return { recovered, warnings };
 }
 
@@ -533,6 +610,7 @@ export async function bootstrapAutoSession(
   const {
     shouldUseWorktreeIsolation,
     registerSigtermHandler,
+    registerAutoWorkerForSession,
     lockBase,
     buildLifecycle,
   } = deps;
@@ -722,6 +800,7 @@ export async function bootstrapAutoSession(
     // consult DB status and avoid clearing runtime units for milestones that
     // only have a failure-path SUMMARY on disk (#4663).
     await openProjectDbIfPresent(base);
+    registerAutoWorkerForSession(base);
 
     // Clean stale runtime unit files for completed milestones (#887).
     // DB-authoritative: when DB is available, require DB status to be closed

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

@@ -252,7 +252,17 @@ function gitPathspecForWorktreePath(basePath: string, targetPath: string): strin
   let base = basePath;
   let target = targetPath;
   try {
-    base = realpathSync.native(basePath);
+    base = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf-8",
+    }).trim() || basePath;
+  } catch {
+    /* keep original */
+    void base;
+  }
+  try {
+    base = realpathSync.native(base);
   } catch {
     /* keep original */
     void base;
@@ -269,6 +279,10 @@ function gitPathspecForWorktreePath(basePath: string, targetPath: string): strin
   return rel.replaceAll("\\", "/");
 }
 
+export function _gitPathspecForWorktreePath(basePath: string, targetPath: string): string | null {
+  return gitPathspecForWorktreePath(basePath, targetPath);
+}
+
 function gitRemoteExists(basePath: string, remote: string): boolean {
   try {
     execFileSync("git", ["remote", "get-url", remote], {

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

@@ -58,6 +58,7 @@ import {
 import {
   writeLock,
   clearLock,
+  clearStaleWorkerLock,
   readCrashLock,
   isLockProcessAlive,
   formatCrashInfo,
@@ -240,7 +241,7 @@ import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { validateDirectory } from "./validate-directory.js";
 import { createAutoOrchestrator } from "./auto/orchestrator.js";
-import type { AutoOrchestrationModule, AutoOrchestratorDeps, DispatchAdapter } from "./auto/contracts.js";
+import type { AutoAdvanceResult, AutoOrchestrationModule, AutoOrchestratorDeps, DispatchAdapter } from "./auto/contracts.js";
 import { reconcileBeforeDispatch } from "./state-reconciliation.js";
 import { compileUnitToolContract } from "./tool-contract.js";
 import { createWorktreeSafetyModule } from "./worktree-safety.js";
@@ -1044,6 +1045,7 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
   // visible so the user still has a resumable auto-mode signal on screen.
   if (!s.paused) {
     ctx.ui.setStatus("gsd-auto", undefined);
+    ctx.ui.setWidget("gsd-progress", undefined);
     if (s.completionStopInProgress) {
       s.completionStopInProgress = false;
     }
@@ -1839,6 +1841,13 @@ export function createWiredDispatchAdapter(
         modelRegistry,
       });
 
+      if (action.action === "stop") {
+        return {
+          kind: "blocked",
+          reason: action.reason,
+          action: action.level === "warning" ? "pause" : "stop",
+        };
+      }
       if (action.action !== "dispatch") return null;
       return {
         unitType: action.unitType,
@@ -2065,6 +2074,18 @@ export function createWiredAutoOrchestrationModule(
   return createAutoOrchestrator(deps);
 }
 
+function notifyResumeBlocked(ctx: ExtensionContext, result: Extract<AutoAdvanceResult, { kind: "blocked" }>): void {
+  const resumeCmd = s.stepMode ? "/gsd next" : "/gsd auto";
+  ctx.ui.notify(`Auto-mode blocked: ${result.reason}. Fix and run ${resumeCmd} to resume.`, "warning");
+  setLifecycleOutcome(ctx, {
+    status: "blocked",
+    title: "Auto-mode blocked",
+    detail: result.reason,
+    nextAction: `Fix the blocker, then run ${resumeCmd} to resume.`,
+    commands: ["/gsd status for overview", `${resumeCmd} to resume`, "/gsd doctor to diagnose"],
+  });
+}
+
 function ensureOrchestrationModule(ctx: ExtensionContext, pi: ExtensionAPI, basePath: string): void {
   s.orchestration = createWiredAutoOrchestrationModule(ctx, pi, basePath, lockBase());
 }
@@ -2402,7 +2423,7 @@ export async function startAuto(
     // This closes the journal gap reported in #3348 where the worker wrote side
     // effects (SUMMARY.md, DB updates) but died before emitting unit-end.
     emitCrashRecoveredUnitEnd(base, freshStartAssessment.lock);
-    clearLock(base);
+    clearStaleWorkerLock(base);
   }
 
   if (!s.paused) {
@@ -2473,6 +2494,8 @@ export async function startAuto(
     s.unitLifetimeDispatches.clear();
     if (!getLedger()) initMetrics(base);
     if (s.currentMilestoneId) setActiveMilestoneId(base, s.currentMilestoneId);
+    await openProjectDbIfPresent(base);
+    registerAutoWorkerForSession(s, base);
 
     // Re-register health level notification callback lost across process restart
     setLevelChangeCallback((_from, to, summary) => {
@@ -2580,7 +2603,12 @@ export async function startAuto(
     pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", level: "progress" });
 
     try {
-      await s.orchestration?.resume();
+      const resumeResult = await s.orchestration?.resume();
+      if (resumeResult?.kind === "blocked") {
+        notifyResumeBlocked(ctx, resumeResult);
+        await cleanupAfterLoopExit(ctx);
+        return;
+      }
     } catch (err) {
       debugLog("resume-orchestration-resume", { error: err instanceof Error ? err.message : String(err) });
     }
@@ -2601,6 +2629,7 @@ export async function startAuto(
   const bootstrapDeps: BootstrapDeps = {
     shouldUseWorktreeIsolation,
     registerSigtermHandler,
+    registerAutoWorkerForSession: (projectRoot) => registerAutoWorkerForSession(s, projectRoot),
     lockBase,
     buildLifecycle,
   };

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -487,17 +487,18 @@ export function registerDbTools(pi: ExtensionAPI): void {
     promptGuidelines: [
       "Use gsd_plan_milestone for milestone planning instead of writing ROADMAP.md directly.",
       "Keep parameters flat and provide the full milestone planning payload, including slices.",
+      "Milestone and slice titles must not contain forward slash (/), en dash, or em dash characters.",
       "The tool validates input, writes milestone and slice planning data transactionally, renders ROADMAP.md from DB, and clears both state and parse caches after success.",
       "Use the canonical name gsd_plan_milestone; gsd_milestone_plan is only an alias.",
     ],
     parameters: Type.Object({
       // ── Core identification + content (required) ──────────────────────
       milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
-      title: Type.String({ description: "Milestone title" }),
+      title: Type.String({ description: "Milestone title; must not contain forward slash (/), en dash, or em dash characters" }),
       vision: Type.String({ description: "Milestone vision" }),
       slices: Type.Array(Type.Object({
         sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
-        title: Type.String({ description: "Slice title" }),
+        title: Type.String({ description: "Slice title; must not contain forward slash (/), en dash, or em dash characters" }),
         risk: Type.String({ description: "Slice risk" }),
         depends: Type.Array(Type.String(), { description: "Slice dependency IDs" }),
         demo: Type.String({ description: "Roadmap demo text / After this" }),
@@ -570,10 +571,10 @@ export function registerDbTools(pi: ExtensionAPI): void {
         title: Type.String({ description: "Task title" }),
         description: Type.String({ description: "Task description / steps block" }),
         estimate: Type.String({ description: "Task estimate string" }),
-        files: Type.Array(Type.String(), { description: "Files likely touched" }),
+        files: Type.Array(Type.String(), { description: "Array<string> of files likely touched; pass [\"path\"] or [], never a single string" }),
         verify: Type.String({ description: "Verification command or block" }),
-        inputs: Type.Array(Type.String(), { description: "Input files or references" }),
-        expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
+        inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
+        expectedOutput: Type.Array(Type.String(), { description: "Array<string> of expected output files or artifacts; pass [\"path\"] or [], never a single string" }),
         observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
       }), { description: "Planned tasks for the slice" }),
       // ── Enrichment metadata (optional — defaults to empty) ────────────
@@ -650,10 +651,10 @@ export function registerDbTools(pi: ExtensionAPI): void {
       title: Type.String({ description: "Task title" }),
       description: Type.String({ description: "Task description / steps block" }),
       estimate: Type.String({ description: "Task estimate string" }),
-      files: Type.Array(Type.String(), { description: "Files likely touched" }),
+      files: Type.Array(Type.String(), { description: "Array<string> of files likely touched; pass [\"path\"] or [], never a single string" }),
       verify: Type.String({ description: "Verification command or block" }),
-      inputs: Type.Array(Type.String(), { description: "Input files or references" }),
-      expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
+      inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
+      expectedOutput: Type.Array(Type.String(), { description: "Array<string> of expected output files or artifacts; pass [\"path\"] or [], never a single string" }),
       observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
       // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
       actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),

package/src/resources/extensions/gsd/bootstrap/subagent-input.ts

@@ -4,7 +4,9 @@ export function extractSubagentAgentClasses(input: unknown): string[] {
   const agentClasses: string[] = [];
   const visited = new WeakSet<object>();
   const addAgentClass = (value: unknown): void => {
-    if (typeof value === "string" && value.trim().length > 0) agentClasses.push(value.trim());
+    if (typeof value !== "string") return;
+    const normalized = value.trim().replace(/\.md$/i, "");
+    if (normalized.length > 0) agentClasses.push(normalized);
   };
 
   const visitItems = (value: unknown): void => {

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

@@ -30,9 +30,10 @@ import { join } from "node:path";
 import {
   findStaleWorkerForProject,
   getAllAutoWorkers,
+  markWorkerCrashed,
   type AutoWorkerRow,
 } from "./db/auto-workers.js";
-import { getLatestForUnit, type DispatchStatus } from "./db/unit-dispatches.js";
+import { markLatestActiveForWorkerCanceled, type DispatchStatus } from "./db/unit-dispatches.js";
 import { getRuntimeKv, setRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
 import { _getAdapter, isDbAvailable } from "./gsd-db.js";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
@@ -56,6 +57,15 @@ function lockPath(basePath: string): string {
   return join(gsdRoot(basePath), effectiveLockFile());
 }
 
+function clearLegacyLockFile(basePath: string): void {
+  try {
+    const p = lockPath(basePath);
+    if (existsSync(p)) unlinkSync(p);
+  } catch {
+    // Best-effort.
+  }
+}
+
 function readLegacyLock(basePath: string): LockData | null {
   try {
     const p = lockPath(basePath);
@@ -204,18 +214,34 @@ export function writeLock(
  * stale session-file pointer.
  */
 export function clearLock(basePath: string): void {
+  clearLegacyLockFile(basePath);
+
+  if (!isDbAvailable()) return;
   try {
-    const p = lockPath(basePath);
-    if (existsSync(p)) unlinkSync(p);
+    const projectRoot = normalizeRealPath(basePath);
+    const worker = findActiveWorkerForCurrentProcess(projectRoot);
+    if (!worker) return;
+    deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
   } catch {
     // Best-effort.
   }
+}
+
+/**
+ * Clear a stale DB-backed worker lock after readCrashLock/findStaleWorkerForProject
+ * has identified a dead worker. Unlike clearLock(), this targets the stale
+ * worker row instead of the current process's active worker.
+ */
+export function clearStaleWorkerLock(basePath: string): void {
+  clearLegacyLockFile(basePath);
 
   if (!isDbAvailable()) return;
   try {
     const projectRoot = normalizeRealPath(basePath);
-    const worker = findActiveWorkerForCurrentProcess(projectRoot);
+    const worker = findStaleWorkerForProject(projectRoot);
     if (!worker) return;
+    markLatestActiveForWorkerCanceled(worker.worker_id, "crash-recovered");
+    markWorkerCrashed(worker.worker_id);
     deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
   } catch {
     // Best-effort.

package/src/resources/extensions/gsd/db/unit-dispatches.ts

@@ -528,6 +528,7 @@ export function getRecentUnitKeysForProjectRoot(
      FROM unit_dispatches ud
      INNER JOIN workers w ON w.worker_id = ud.worker_id
      WHERE w.project_root_realpath = :project_root_realpath
+       AND w.status != 'crashed'
      ORDER BY ud.started_at DESC, ud.id DESC
      LIMIT :limit`,
   ).all({

package/src/resources/extensions/gsd/dispatch-guard.ts

@@ -5,7 +5,7 @@ import { findMilestoneIds } from "./guided-flow.js";
 import { parseUnitId } from "./unit-id.js";
 import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
 import { parseRoadmap } from "./parsers-legacy.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, isSkippedForDispatch } from "./status-guards.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
 
@@ -58,7 +58,7 @@ export function getPriorSliceCompletionBlocker(
     //      DB-backed projects must not treat SUMMARY.md as authoritative.
     if (isDbAvailable()) {
       const milestoneRow = getMilestone(mid);
-      if (milestoneRow && isClosedStatus(milestoneRow.status)) continue;
+      if (milestoneRow && isSkippedForDispatch(milestoneRow.status)) continue;
     } else {
       const summaryPath = resolveMilestoneFile(base, mid, "SUMMARY");
       let summaryContent: string | null = null;