gsd-pi 2.82.0-dev.ed17d078d → 3.0.0-dev.04f5ccf82

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 
 import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
+import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
 
 
 export interface GsdCommandDefinition {
@@ -13,7 +14,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|brief|queue|quick|discuss|capture|triage|dispatch|verdict|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -24,6 +25,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "status", desc: "Progress dashboard" },
   { cmd: "widget", desc: "Cycle widget: full → small → min → off" },
   { cmd: "visualize", desc: "Open 10-tab workflow visualizer (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)" },
+  { cmd: "brief", desc: "Generate a visual HTML brief: diagram, plan, diff review, recap, table, or slides" },
   { cmd: "queue", desc: "Queue and reorder future milestones" },
   { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
   { cmd: "discuss", desc: "Discuss architecture and decisions" },
@@ -31,6 +33,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "changelog", desc: "Show categorized release notes" },
   { cmd: "triage", desc: "Manually trigger triage of pending captures" },
   { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
+  { cmd: "verdict", desc: "Override the recorded milestone validation verdict (pass|needs-attention|needs-remediation)" },
   { cmd: "history", desc: "View execution history" },
   { cmd: "undo", desc: "Revert last completed unit" },
   { cmd: "undo-task", desc: "Reset a specific task's completion state (DB + markdown)" },
@@ -88,6 +91,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
+  brief: VISUAL_BRIEF_MODES.map((mode) => ({ cmd: mode.mode, desc: mode.description })),
   auto: [
     { cmd: "--verbose", desc: "Show detailed execution output" },
     { cmd: "--debug", desc: "Enable debug logging" },
@@ -245,6 +249,11 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "uat", desc: "Run user acceptance testing" },
     { cmd: "replan", desc: "Replan the current slice" },
   ],
+  verdict: [
+    { cmd: "pass", desc: "Override the milestone validation verdict to pass" },
+    { cmd: "needs-attention", desc: "Override the verdict to needs-attention (requires --rationale)" },
+    { cmd: "needs-remediation", desc: "Override the verdict to needs-remediation (requires --rationale)" },
+  ],
   rate: [
     { cmd: "over", desc: "Model was overqualified for this task" },
     { cmd: "ok", desc: "Model was appropriate for this task" },

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@gsd/pi-coding-agent";
 import type { Model } from "@gsd/pi-ai";
 import type { GSDState } from "../../types.js";
+import { createRequire } from "node:module";
 
 import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath, getProjectGSDPreferencesPath } from "../../preferences.js";
@@ -11,6 +12,8 @@ import { handleCmux } from "../../commands-cmux.js";
 import { setSessionModelOverride } from "../../session-model-override.js";
 import { projectRoot } from "../context.js";
 import { formattedShortcutPair } from "../../shortcut-defs.js";
+import { getVisualBriefOutputDir } from "../../../visual-brief/artifact-policy.js";
+import { buildVisualBriefPrompt, parseVisualBriefArgs, VISUAL_BRIEF_USAGE } from "../../../visual-brief/prompts.js";
 
 export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
   const summaryLines = [
@@ -27,6 +30,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     `  /gsd parallel watch Parallel monitor  (${formattedShortcutPair("parallel")})`,
     `  /gsd notifications  Notification history  (${formattedShortcutPair("notifications")})`,
     "  /gsd visualize      Interactive 10-tab TUI",
+    "  /gsd brief <mode>   Visual HTML brief (diagram, plan, diff, recap, table, slides)",
     "  /gsd queue          Show queued/dispatched units",
     "",
     "COURSE CORRECTION",
@@ -67,6 +71,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd new-project    Bootstrap a new project (use --deep for staged project-level discovery)",
     "  /gsd quick          Execute a quick task without full planning overhead",
     "  /gsd dispatch       Dispatch a specific phase directly  [research|plan|execute|complete|uat|replan]",
+    "  /gsd verdict <v>    Override milestone validation verdict  [pass|needs-attention|needs-remediation] [--milestone Mxxx] [--rationale \"...\"]",
     "  /gsd parallel       Parallel milestone orchestration  [start|status|stop|pause|resume|merge|watch]",
     "  /gsd workflow       Custom workflow lifecycle  [new|run|list|validate|pause|resume]",
     "",
@@ -75,6 +80,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     `  /gsd parallel watch Open parallel worker monitor  (${formattedShortcutPair("parallel")})`,
     "  /gsd widget         Cycle status widget  [full|small|min|off]",
     "  /gsd visualize      Interactive 10-tab TUI (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)",
+    "  /gsd brief <mode>   Generate a visual HTML brief  [diagram|plan|diff|recap|table|slides] [topic] [--slides]",
     "  /gsd queue          Show queued/dispatched units and execution order",
     "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
     "  /gsd changelog      Show categorized release notes  [version]",
@@ -203,6 +209,37 @@ export async function handleVisualize(ctx: ExtensionCommandContext): Promise<voi
   }
 }
 
+export async function handleBrief(args: string, ctx: ExtensionCommandContext, pi?: ExtensionAPI): Promise<void> {
+  const request = parseVisualBriefArgs(args);
+  if (!request) {
+    ctx.ui.notify(VISUAL_BRIEF_USAGE, "info");
+    return;
+  }
+
+  if (!pi?.sendUserMessage) {
+    ctx.ui.notify("Visual brief generation is unavailable in this context.", "warning");
+    return;
+  }
+
+  const outputDir = getVisualBriefOutputDir();
+  const version = resolveGsdVersion();
+  pi.sendUserMessage(buildVisualBriefPrompt(request, { outputDir, version }));
+}
+
+const briefRequire = createRequire(import.meta.url);
+
+function resolveGsdVersion(): string | undefined {
+  const envVersion = process.env.GSD_VERSION?.trim();
+  if (envVersion) return envVersion;
+  try {
+    const pkg = briefRequire("../../../../../../package.json") as { version?: unknown };
+    const fromPkg = typeof pkg.version === "string" ? pkg.version.trim() : "";
+    return fromPkg || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function handleSetup(args: string, ctx: ExtensionCommandContext, pi?: ExtensionAPI): Promise<void> {
   const { detectProjectState, hasGlobalSetup } = await import("../../detection.js");
   const { isOnboardingComplete, readOnboardingRecord } = await import("../../onboarding-state.js");
@@ -429,6 +466,10 @@ export async function handleCoreCommand(
     await handleVisualize(ctx);
     return true;
   }
+  if (trimmed === "brief" || trimmed.startsWith("brief ")) {
+    await handleBrief(trimmed.replace(/^brief\s*/, "").trim(), ctx, pi);
+    return true;
+  }
   if (trimmed === "widget" || trimmed.startsWith("widget ")) {
     const { cycleWidgetMode, setWidgetMode, getWidgetMode } = await import("../../auto-dashboard.js");
     const arg = trimmed.replace(/^widget\s*/, "").trim();

package/src/resources/extensions/gsd/commands/handlers/ops.ts

@@ -20,6 +20,22 @@ import { handlePrBranch } from "../../commands-pr-branch.js";
 import { currentDirectoryRoot, projectRoot } from "../context.js";
 
 export async function handleOpsCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
+  const directDispatchAlias = new Map<string, string>([
+    ["research-milestone", "research"],
+    ["research-slice", "research"],
+    ["plan-milestone", "plan"],
+    ["plan-slice", "plan"],
+    ["execute-task", "execute"],
+    ["complete-slice", "complete"],
+    ["validate-milestone", "uat"],
+    ["complete-milestone", "complete"],
+  ]);
+  const aliasPhase = directDispatchAlias.get(trimmed);
+  if (aliasPhase) {
+    await dispatchDirectPhase(ctx, pi, aliasPhase, projectRoot());
+    return true;
+  }
+
   if (trimmed === "init") {
     const { detectProjectState } = await import("../../detection.js");
     const { handleReinit, showProjectInit } = await import("../../init-wizard.js");
@@ -188,6 +204,11 @@ Examples:
     await dispatchDirectPhase(ctx, pi, phase, projectRoot());
     return true;
   }
+  if (trimmed === "verdict" || trimmed.startsWith("verdict ")) {
+    const { handleVerdict } = await import("../../commands-verdict.js");
+    await handleVerdict(trimmed.replace(/^verdict\s*/, "").trim(), ctx, projectRoot());
+    return true;
+  }
   if (trimmed === "notifications" || trimmed.startsWith("notifications ")) {
     const { handleNotificationsCommand } = await import("./notifications-handler.js");
     await handleNotificationsCommand(trimmed.replace(/^notifications\s*/, "").trim(), ctx, pi);

package/src/resources/extensions/gsd/commands-bootstrap.ts

@@ -1,4 +1,5 @@
 import { importExtensionModule, type ExtensionAPI, type ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { VISUAL_BRIEF_MODES } from "../visual-brief/prompts.js";
 
 const TOP_LEVEL_SUBCOMMANDS = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -8,6 +9,7 @@ const TOP_LEVEL_SUBCOMMANDS = [
   { cmd: "pause", desc: "Pause auto-mode (preserves state, /gsd auto to resume)" },
   { cmd: "status", desc: "Progress dashboard" },
   { cmd: "visualize", desc: "Open workflow visualizer" },
+  { cmd: "brief", desc: "Generate a visual HTML brief" },
   { cmd: "queue", desc: "Queue and reorder future milestones" },
   { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
   { cmd: "discuss", desc: "Discuss architecture and decisions" },
@@ -87,6 +89,14 @@ function getGsdArgumentCompletions(prefix: string) {
     ], "next");
   }
 
+  if (parts[0] === "brief" && parts.length <= 2) {
+    return filterStartsWith(
+      partial,
+      VISUAL_BRIEF_MODES.map((mode) => ({ cmd: mode.mode, desc: mode.description })),
+      "brief",
+    );
+  }
+
   if ((parts[0] === "new-project" || parts[0] === "new-milestone") && parts.length <= 2) {
     return filterStartsWith(partial, [
       { cmd: "--deep", desc: "Enable deep planning mode (staged project-level discovery)" },

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -123,6 +123,8 @@ export async function handleDoctor(args: string, ctx: ExtensionCommandContext, p
   const { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope } = parseDoctorArgs(args);
   const scope = await selectDoctorScope(projectRoot(), requestedScope);
   const effectiveScope = mode === "audit" ? requestedScope : scope;
+  const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+  await ensureDbOpen(projectRoot());
   const report = await runGSDDoctor(projectRoot(), {
     fix: mode === "fix" || mode === "heal" || dryRun || fixFlag,
     dryRun,

package/src/resources/extensions/gsd/commands-mcp-status.ts

@@ -32,6 +32,11 @@ export interface McpServerDetail extends McpServerStatus {
   tools: string[];
 }
 
+export function hasHostMcpTool(systemPrompt: string, serverName: string): boolean {
+  const marker = `mcp__${serverName}__`;
+  return systemPrompt.includes(marker);
+}
+
 export function formatMcpInitResult(
   status: "created" | "updated" | "unchanged",
   configPath: string,
@@ -184,6 +189,7 @@ export async function handleMcpStatus(
   const trimmed = args.trim();
   const lowered = trimmed.toLowerCase();
   const configs = readMcpConfigs();
+  const systemPrompt = ctx.getSystemPrompt();
 
   // /gsd mcp init [dir]
   if (!lowered || lowered === "status") {
@@ -233,6 +239,7 @@ export async function handleMcpStatus(
     } catch {
       // mcp-client may not expose status helpers — that's fine
     }
+    if (!connected && !error && hasHostMcpTool(systemPrompt, serverName)) connected = true;
 
     ctx.ui.notify(
       formatMcpServerDetail({
@@ -270,6 +277,7 @@ export async function handleMcpStatus(
       } catch {
         // Fall back to unknown state
       }
+      if (!connected && !error && hasHostMcpTool(systemPrompt, config.name)) connected = true;
 
       statuses.push({
         name: config.name,

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

@@ -17,6 +17,7 @@ import {
   loadGlobalGSDPreferences,
   loadProjectGSDPreferences,
   loadEffectiveGSDPreferences,
+  normalizePreferencesShape,
   resolveAllSkillReferences,
 } from "./preferences.js";
 import { loadFile, saveFile, splitFrontmatter, parseFrontmatterMap } from "./files.js";
@@ -587,10 +588,18 @@ async function configureModels(ctx: ExtensionCommandContext, prefs: Record<strin
   const models: Record<string, unknown> = (prefs.models as Record<string, unknown>) ?? {};
 
   const availableModels = ctx.modelRegistry.getAvailable();
-  if (availableModels.length > 0) {
+  // Call getAllWithDiscovered as a method so `this` stays bound to the
+  // registry — invoking a detached reference loses `this` and the method's
+  // internal `this.models` access throws.
+  const registry = ctx.modelRegistry as { getAllWithDiscovered?: () => typeof availableModels };
+  const availableProviders = new Set(availableModels.map((m) => m.provider));
+  const selectableModels = typeof registry.getAllWithDiscovered === "function"
+    ? registry.getAllWithDiscovered().filter((m) => availableProviders.has(m.provider))
+    : availableModels;
+  if (selectableModels.length > 0) {
     // Group models by provider, sorted alphabetically
-    const byProvider = new Map<string, typeof availableModels>();
-    for (const m of availableModels) {
+    const byProvider = new Map<string, typeof selectableModels>();
+    for (const m of selectableModels) {
       let group = byProvider.get(m.provider);
       if (!group) {
         group = [];
@@ -1563,8 +1572,12 @@ export async function handlePrefsWizard(
   // Order: existing-on-disk values, overlaid with prefill (caller's seeded answers).
   // Callers like /gsd init pass freshly-collected init answers as prefill so the
   // wizard menu shows them populated and writeable in one place.
+  // `normalizePreferencesShape` tolerates a missing preferences file, a malformed
+  // wrapper (`{ preferences: undefined }`), or a bare prefs object so the wizard
+  // never reaches the category menu with a half-formed root. See issue: /gsd setup
+  // prefs crashed with "Cannot read properties of undefined (reading 'models')".
   const prefs: Record<string, unknown> = {
-    ...(existing?.preferences ?? {}),
+    ...normalizePreferencesShape(existing),
     ...(prefill ?? {}),
   };
 

package/src/resources/extensions/gsd/commands-verdict.ts

@@ -0,0 +1,202 @@
+import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+
+import { loadFile } from "./files.js";
+import { resolveMilestoneFile } from "./paths.js";
+import { deriveState } from "./state.js";
+import { executeValidateMilestone } from "./tools/workflow-tool-executors.js";
+import {
+  VALIDATION_VERDICTS,
+  extractVerdict,
+  isValidMilestoneVerdict,
+  type ValidationVerdict,
+} from "./verdict-parser.js";
+
+const USAGE =
+  'Usage: /gsd verdict <pass|needs-attention|needs-remediation> [--milestone Mxxx] [--rationale "..."]';
+
+interface ParsedArgs {
+  verdict?: ValidationVerdict;
+  milestoneId?: string;
+  rationale?: string;
+}
+
+interface ParsedValidation {
+  verdict: string | undefined;
+  remediationRound: number;
+  successCriteriaChecklist: string;
+  sliceDeliveryAudit: string;
+  crossSliceIntegration: string;
+  requirementCoverage: string;
+  verificationClasses?: string;
+  verdictRationale: string;
+  remediationPlan?: string;
+}
+
+function tokenize(raw: string): string[] {
+  const tokens: string[] = [];
+  const re = /"([^"]*)"|(\S+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(raw)) !== null) {
+    tokens.push(match[1] ?? match[2]);
+  }
+  return tokens;
+}
+
+function parseArgs(raw: string): ParsedArgs | { error: string } {
+  const tokens = tokenize(raw);
+  const out: ParsedArgs = {};
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t === "--milestone") {
+      const next = tokens[++i];
+      if (!next) return { error: "--milestone requires a milestone ID" };
+      out.milestoneId = next;
+    } else if (t === "--rationale") {
+      const next = tokens[++i];
+      if (next == null) return { error: "--rationale requires a value" };
+      out.rationale = next;
+    } else if (!out.verdict) {
+      if (!isValidMilestoneVerdict(t)) {
+        return {
+          error: `Invalid verdict "${t}". Must be one of: ${VALIDATION_VERDICTS.join(", ")}`,
+        };
+      }
+      out.verdict = t;
+    } else {
+      return { error: `Unexpected argument: ${t}` };
+    }
+  }
+  return out;
+}
+
+function extractRemediationRound(content: string): number {
+  const fm = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return 0;
+  const m = fm[1].match(/^remediation_round:\s*(\d+)/im);
+  return m ? Number.parseInt(m[1], 10) : 0;
+}
+
+function extractSection(content: string, heading: string): string | undefined {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  // Match section bodies bounded by the next "## " heading or end-of-string.
+  // Leading "\n" prefix lets a single pattern handle first-line headings too.
+  // No /m flag — we want `$` to mean end-of-string, not end-of-line.
+  const re = new RegExp(`\\n## ${escaped}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`);
+  const m = ("\n" + content).match(re);
+  if (!m) return undefined;
+  return m[1].replace(/\s+$/, "");
+}
+
+export function parseValidationFile(content: string): ParsedValidation {
+  return {
+    verdict: extractVerdict(content),
+    remediationRound: extractRemediationRound(content),
+    successCriteriaChecklist: extractSection(content, "Success Criteria Checklist") ?? "",
+    sliceDeliveryAudit: extractSection(content, "Slice Delivery Audit") ?? "",
+    crossSliceIntegration: extractSection(content, "Cross-Slice Integration") ?? "",
+    requirementCoverage: extractSection(content, "Requirement Coverage") ?? "",
+    verificationClasses: extractSection(content, "Verification Class Compliance"),
+    verdictRationale: extractSection(content, "Verdict Rationale") ?? "",
+    remediationPlan: extractSection(content, "Remediation Plan"),
+  };
+}
+
+export async function handleVerdict(
+  rawArgs: string,
+  ctx: ExtensionCommandContext,
+  basePath: string,
+): Promise<void> {
+  if (!rawArgs.trim()) {
+    ctx.ui.notify(USAGE, "warning");
+    return;
+  }
+
+  const parsed = parseArgs(rawArgs);
+  if ("error" in parsed) {
+    ctx.ui.notify(`${parsed.error}\n${USAGE}`, "warning");
+    return;
+  }
+  if (!parsed.verdict) {
+    ctx.ui.notify(USAGE, "warning");
+    return;
+  }
+
+  let milestoneId = parsed.milestoneId;
+  if (!milestoneId) {
+    const state = await deriveState(basePath);
+    if (!state.activeMilestone) {
+      ctx.ui.notify(
+        "No active milestone — pass --milestone Mxxx to target a specific milestone.",
+        "warning",
+      );
+      return;
+    }
+    milestoneId = state.activeMilestone.id;
+  }
+
+  const validationPath = resolveMilestoneFile(basePath, milestoneId, "VALIDATION");
+  if (!validationPath) {
+    ctx.ui.notify(
+      `No VALIDATION file found for ${milestoneId}. Run gsd_validate_milestone first to produce one.`,
+      "warning",
+    );
+    return;
+  }
+  const existing = await loadFile(validationPath);
+  if (!existing) {
+    ctx.ui.notify(
+      `Could not read VALIDATION file for ${milestoneId} (${validationPath}).`,
+      "warning",
+    );
+    return;
+  }
+
+  const current = parseValidationFile(existing);
+
+  if (parsed.verdict !== "pass" && !parsed.rationale) {
+    ctx.ui.notify(
+      `--rationale is required when overriding to ${parsed.verdict}.`,
+      "warning",
+    );
+    return;
+  }
+
+  const verdictRationale =
+    parsed.rationale ?? "Manually overridden via /gsd verdict";
+
+  const result = await executeValidateMilestone(
+    {
+      milestoneId,
+      verdict: parsed.verdict,
+      remediationRound: current.remediationRound,
+      successCriteriaChecklist: current.successCriteriaChecklist,
+      sliceDeliveryAudit: current.sliceDeliveryAudit,
+      crossSliceIntegration: current.crossSliceIntegration,
+      requirementCoverage: current.requirementCoverage,
+      verificationClasses: current.verificationClasses,
+      verdictRationale,
+      remediationPlan: current.remediationPlan,
+    },
+    basePath,
+  );
+
+  if (result.isError) {
+    const msg =
+      result.content[0]?.type === "text" ? result.content[0].text : "Unknown error";
+    ctx.ui.notify(msg, "error");
+    return;
+  }
+
+  const prevVerdict = current.verdict ?? "unknown";
+  ctx.ui.notify(
+    `Milestone ${milestoneId} verdict: ${prevVerdict} -> ${parsed.verdict}`,
+    "success",
+  );
+
+  if (parsed.verdict === "needs-remediation") {
+    ctx.ui.notify(
+      "Follow up with gsd_reassess_roadmap to add remediation slices, then re-run /gsd auto.",
+      "info",
+    );
+  }
+}

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

@@ -30,9 +30,13 @@ import { join } from "node:path";
 import {
   findStaleWorkerForProject,
   getAllAutoWorkers,
+  markWorkerCrashed,
+  markWorkerStopping,
+  markWorkerStoppingByPid,
   type AutoWorkerRow,
 } from "./db/auto-workers.js";
-import { getLatestForUnit, type DispatchStatus } from "./db/unit-dispatches.js";
+import { forceReleaseLeasesForWorker } from "./db/milestone-leases.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 +60,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);
@@ -185,12 +198,18 @@ export function writeLock(
     // Best-effort — never throw from the lock writer.
   }
 
-  if (!isDbAvailable() || !sessionFile) return;
+  if (!isDbAvailable()) return;
   try {
     const projectRoot = normalizeRealPath(basePath);
     const worker = findActiveWorkerForCurrentProcess(projectRoot);
     if (!worker) return;
-    setRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY, sessionFile);
+    if (sessionFile) {
+      setRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY, sessionFile);
+    } else {
+      // Preliminary unit locks (before runUnit/newSession settles) must clear
+      // any prior pointer so crash recovery cannot ingest stale cross-unit context.
+      deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
+    }
   } catch {
     // Best-effort — never throw from the lock writer.
   }
@@ -204,18 +223,48 @@ 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 staleWorker = findStaleWorkerForProject(projectRoot);
+    if (staleWorker) {
+      markWorkerCrashed(staleWorker.worker_id);
+      forceReleaseLeasesForWorker(staleWorker.worker_id);
+      deleteRuntimeKv("worker", staleWorker.worker_id, SESSION_FILE_KV_KEY);
+      return;
+    }
+    const lock = readLegacyLock(basePath);
+    if (lock?.pid) markWorkerStoppingByPid(projectRoot, lock.pid);
+    const worker = findActiveWorkerForCurrentProcess(projectRoot);
+    if (worker) deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
+
+    const stale = findStaleWorkerForProject(projectRoot);
+    if (stale) {
+      markWorkerStopping(stale.worker_id);
+      deleteRuntimeKv("worker", stale.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/auto-workers.ts

@@ -157,6 +157,31 @@ export function markWorkerStopping(workerId: string): void {
   });
 }
 
+/**
+ * Mark the active worker row for a specific PID/project root as stopping.
+ * Used when we detect a dead PID from lock metadata before heartbeat expiry.
+ */
+export function markWorkerStoppingByPid(
+  projectRootRealpath: string,
+  pid: number,
+): void {
+  if (!isDbAvailable()) return;
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  const db = _getAdapter()!;
+  transaction(() => {
+    db.prepare(
+      `UPDATE workers
+       SET status = 'stopping'
+       WHERE pid = :pid
+         AND project_root_realpath = :project_root
+         AND status = 'active'`,
+    ).run({
+      ":pid": pid,
+      ":project_root": projectRootRealpath,
+    });
+  });
+}
+
 /**
  * Return all workers whose status is 'active' AND whose heartbeat is within
  * the TTL window. Workers older than the TTL are NOT auto-marked crashed
@@ -242,6 +267,18 @@ export function findStaleWorkerForProject(
   const db = _getAdapter()!;
   const cutoffMs = Date.now() - HEARTBEAT_TTL_SECONDS * 1000;
   const cutoffIso = new Date(cutoffMs).toISOString();
+
+  const latestActiveRow = db.prepare(
+    `SELECT worker_id, host, pid, started_at, version,
+            last_heartbeat_at, status, project_root_realpath
+     FROM workers
+     WHERE project_root_realpath = :project_root
+       AND status = 'active'
+     ORDER BY started_at DESC
+     LIMIT 1`,
+  ).get({ ":project_root": projectRootRealpath }) as AutoWorkerRow | undefined;
+  if (latestActiveRow && !isWorkerProcessAlive(latestActiveRow)) return latestActiveRow;
+
   const row = db.prepare(
     `SELECT worker_id, host, pid, started_at, version,
             last_heartbeat_at, status, project_root_realpath