@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.5457a158

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

@@ -43,10 +43,8 @@ import {
 } from "../error-classifier.js";
 import { blockModel, isModelBlocked } from "../blocked-models.js";
 import { getProjectGSDPreferencesPath } from "../preferences.js";
-import {
-  formatProviderErrorGuidance,
-  resolveProviderErrorGuidance,
-} from "../provider-error-guidance.js";
+import { resolveProviderErrorGuidance } from "../provider-error-guidance.js";
+import { formatGuidance } from "../guidance.js";
 
 const retryState = createRetryState();
 const MAX_NETWORK_RETRIES = 2;
@@ -627,7 +625,7 @@ export async function handleAgentEnd(
         preferencesPath: dash.basePath ? getProjectGSDPreferencesPath(dash.basePath) : undefined,
         hasConfiguredFallbacks: (modelConfig?.fallbacks.length ?? 0) > 0,
       });
-      const guidanceText = formatProviderErrorGuidance(guidance);
+      const guidanceText = formatGuidance(guidance);
 
       await pauseForProviderModelRejection(ctx, pi, {
         errorDetail,

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

@@ -12,6 +12,7 @@ import { logWarning } from "../workflow-logger.js";
 import { openWorkflowDatabase } from "../db-workspace.js";
 import { getAutoWorktreePath } from "../auto-worktree.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
+import { worktreesDirs } from "../worktree-placement.js";
 
 export function safeWorkspaceCwd(): string {
   try {
@@ -46,13 +47,15 @@ export function resolveWorkflowToolBasePath(
     const worktree = getAutoWorktreePath(projectRoot, milestoneId);
     if (worktree) return worktree;
   } else {
-    const worktreesDir = join(projectRoot, ".gsd", "worktrees");
-    if (existsSync(worktreesDir)) {
+    const live: string[] = [];
+    for (const worktreesDir of worktreesDirs(projectRoot)) {
+      if (!existsSync(worktreesDir)) continue;
       try {
-        const live = readdirSync(worktreesDir)
-          .map((name) => join(worktreesDir, name))
-          .filter((p) => existsSync(join(p, ".git")));
-        if (live.length === 1) return live[0]!;
+        live.push(
+          ...readdirSync(worktreesDir)
+            .map((name) => join(worktreesDir, name))
+            .filter((p) => existsSync(join(p, ".git"))),
+        );
       } catch (err) {
         logWarning(
           "bootstrap",
@@ -60,6 +63,7 @@ export function resolveWorkflowToolBasePath(
         );
       }
     }
+    if (live.length === 1) return live[0]!;
   }
   return cwd;
 }

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -13,7 +13,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 
 import { buildMilestoneFileName, clearPathCache, milestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { applyAskUserQuestionsGateResult, canonicalToolName, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, isMilestoneDepthVerified, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { applyAskUserQuestionsGateResult, canonicalToolName, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, isApprovalGateVerifiedInSnapshot, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, loadWriteGateSnapshot, markApprovalGateVerified, markDepthVerified, refreshWriteGateStateFromDisk, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -40,6 +40,7 @@ import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecor
 import { parseUnitId } from "../unit-id.js";
 import { classifyCommand } from "../safety/destructive-guard.js";
 import { logWarning as safetyLogWarning } from "../workflow-logger.js";
+import { isUnitCloseoutTool, runInteractiveUnitCloseout } from "../unit-closeout.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
@@ -61,6 +62,8 @@ import { filterToolsForProvider } from "../model-router.js";
 import { mcpToolMatchesBaseName } from "../mcp-tool-name.js";
 import { RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
 import { supportsSourceObservationsForUnit } from "../source-observations.js";
+import { clearPendingAutoStart } from "../pending-auto-start.js";
+import { resolveWorkflowToolBasePath } from "./dynamic-tools.js";
 
 let approvalQuestionAbortInFlight = false;
 
@@ -572,8 +575,13 @@ function isShellExecutionTool(canonicalName: string): boolean {
 
 function activateDeferredApprovalGate(basePath: string): void {
   if (deferredApprovalGate?.basePath !== basePath) return;
-  setPendingGate(deferredApprovalGate.gateId, basePath);
+  const gateId = deferredApprovalGate.gateId;
   deferredApprovalGate = null;
+  const snapshot = refreshWriteGateStateFromDisk(basePath);
+  const milestoneId = extractDepthVerificationMilestoneId(gateId);
+  if (isApprovalGateVerifiedInSnapshot(snapshot, gateId)) return;
+  if (milestoneId && isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId)) return;
+  setPendingGate(gateId, basePath);
 }
 
 function extractGateQuestionId(input: unknown): string | undefined {
@@ -593,6 +601,26 @@ function isContextDraftSummarySave(toolName: string, input: unknown): boolean {
   return (input as { artifact_type?: unknown }).artifact_type === "CONTEXT-DRAFT";
 }
 
+/**
+ * External engines (claude-code-cli) deliver ask_user_questions results as
+ * relayed MCP tool results: the structured round payload arrives in
+ * `result.structuredContent`, not in pi-native `event.details`. Without this
+ * fallback, applyAskUserQuestionsGateResult sees no response for an answered
+ * gate question and lands in the "waiting" branch — leaving a re-armed gate
+ * permanently pending and the discuss→auto handoff blocked.
+ */
+function resolveAskUserQuestionsGateDetails(event: { details?: unknown; result?: unknown }): any {
+  const hasRoundShape = (value: any): boolean =>
+    !!value && typeof value === "object" &&
+    (value.cancelled !== undefined || value.response !== undefined);
+
+  const details = event.details as any;
+  if (hasRoundShape(details)) return details;
+  const structured = (event.result as { structuredContent?: unknown } | undefined)?.structuredContent;
+  if (hasRoundShape(structured)) return structured;
+  return details ?? {};
+}
+
 type StructuredQuestion = {
   id?: string;
   header?: string;
@@ -802,7 +830,7 @@ export function registerHooks(
     }
   });
 
-  pi.on("session_switch", async (_event, ctx) => {
+  pi.on("session_switch", async (event, ctx) => {
     const basePath = contextBasePath(ctx);
     const preserveCloseoutSurface = isAutoCompletionStopInProgress();
     initSessionNotifications(ctx);
@@ -811,6 +839,13 @@ export function registerHooks(
     clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
     clearDiscussionFlowState(basePath);
+    // /clear or /new destroys the conversation holding a discuss interview, so
+    // its pending discuss→auto handoff can never be answered — clear it. Resume
+    // restores the interview transcript, so the entry survives. Auto-mode's own
+    // newSession() calls are safe: the handoff consumes the entry on agent_end.
+    if (event.reason === "new") {
+      clearPendingAutoStart(basePath);
+    }
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
     await applyCompactionThresholdOverride(ctx);
@@ -1368,13 +1403,27 @@ export function registerHooks(
     } else if (isAutoActive()) {
       clearToolInvocationError();
     }
+    // Interactive Closeout adapter (ADR-032): auto-mode owns closeout for its
+    // own units; interactive completions get the durable git subset (commit +
+    // Closeout Git Verdict) instead of silently bypassing git.isolation.
+    if (!event.isError && !isAutoActive() && isUnitCloseoutTool(toolName)) {
+      try {
+        runInteractiveUnitCloseout({
+          basePath: resolveWorkflowToolBasePath(ctx, event.input as { milestone_id?: string }),
+          canonicalToolName: toolName,
+          input: event.input,
+        });
+      } catch (err) {
+        safetyLogWarning("engine", `interactive unit closeout failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
     if (toolName !== "ask_user_questions") return;
     const basePath = contextBasePath(ctx);
     const milestoneId = await getDiscussionMilestoneIdFor(basePath);
 
-    const details = event.details as any;
+    const details = resolveAskUserQuestionsGateDetails(event);
 
-    const questions: any[] = (event.input as any)?.questions ?? [];
+    const questions: any[] = (event.input as any)?.questions ?? details?.questions ?? [];
     const gateResult = applyAskUserQuestionsGateResult({
       basePath,
       questions,
@@ -1415,10 +1464,42 @@ export function registerHooks(
     if (toolName === "ask_user_questions") {
       const questionId = extractGateQuestionId(event.args);
       if (typeof questionId === "string") {
-        setPendingGate(questionId, basePath);
+        // External engines (claude-code-cli) ingest the SDK turn's tool blocks
+        // post-hoc, so this event can fire AFTER the workflow MCP child already
+        // verified this gate and allowed the CONTEXT save. setPendingGate also
+        // revokes verifiedDepthMilestones/verifiedApprovalGates, so an
+        // unconditional re-arm here wipes the child's verification and leaves
+        // the discuss→auto handoff permanently blocked. Skip the re-arm when
+        // the snapshot already records this exact gate as verified — mirrors
+        // activateDeferredApprovalGate's guard. Stale verified state cannot
+        // leak into a later re-discussion: a successful handoff deletes the
+        // snapshot via clearDiscussionFlowState.
+        const snapshot = refreshWriteGateStateFromDisk(basePath);
+        const gateMilestoneId = extractDepthVerificationMilestoneId(questionId);
+        const alreadyVerified =
+          isApprovalGateVerifiedInSnapshot(snapshot, questionId) ||
+          isMilestoneDepthVerifiedInSnapshot(snapshot, gateMilestoneId);
+        if (!alreadyVerified) {
+          setPendingGate(questionId, basePath);
+        }
         clearDeferredApprovalGate(basePath);
       }
     }
+
+    // Safety harness: record evidence here, not only in tool_call. External
+    // engines (claude-code-cli) pre-execute tools, so the agent loop skips
+    // beforeToolCall/tool_call for them — tool_execution_start is the only
+    // event that fires for every tool call. recordToolCall dedupes by
+    // toolCallId, so native tools (which hit both events) record once.
+    safetyRecordToolCall(event.toolCallId, event.toolName, (event.args ?? {}) as Record<string, unknown>);
+    const execDash = getAutoRuntimeSnapshot();
+    if (execDash.basePath && execDash.currentUnit?.type === "execute-task") {
+      const { milestone: xMid, slice: xSid, task: xTid } = parseUnitId(execDash.currentUnit.id);
+      if (xMid && xSid && xTid) {
+        saveEvidenceToDisk(execDash.basePath, xMid, xSid, xTid);
+      }
+    }
+
     if (!isAutoActive()) return;
     markToolStart(event.toolCallId, event.toolName);
   });

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -10,6 +10,7 @@ import { getIsolationMode } from "../preferences.js";
 import { compileSubagentPermissionContract, type ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
+import { worktreesDirs } from "../worktree-placement.js";
 
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
@@ -244,6 +245,27 @@ export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
   }
 }
 
+/**
+ * Merge the persisted write-gate snapshot into the in-process Map entry.
+ * The workflow MCP server runs in a child process and records depth
+ * verification there; without this refresh the extension host keeps stale
+ * pending-gate memory and `activateDeferredApprovalGate` can re-arm a gate
+ * that the subprocess already cleared on disk.
+ *
+ * Returns the snapshot used for the refresh so callers that need to inspect
+ * it (e.g. re-arm guards) avoid a second disk read.
+ */
+export function refreshWriteGateStateFromDisk(basePath: string): WriteGateSnapshot {
+  const snapshot = loadWriteGateSnapshot(basePath);
+  if (!shouldPersistWriteGateSnapshot()) return snapshot;
+  const state = getWriteGateState(basePath);
+  state.pendingGateId = snapshot.pendingGateId;
+  state.activeQueuePhase = snapshot.activeQueuePhase;
+  state.verifiedDepthMilestones = new Set(snapshot.verifiedDepthMilestones);
+  state.verifiedApprovalGates = new Set(snapshot.verifiedApprovalGates ?? []);
+  return snapshot;
+}
+
 export function isDepthVerified(basePath: string = process.cwd()): boolean {
   return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;
 }
@@ -256,6 +278,7 @@ export function isMilestoneDepthVerified(
   basePath: string = process.cwd(),
 ): boolean {
   if (!milestoneId) return false;
+  refreshWriteGateStateFromDisk(basePath);
   return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
 }
 
@@ -357,6 +380,7 @@ export function clearPendingGate(basePath: string): void {
  * Get the currently pending gate, if any.
  */
 export function getPendingGate(basePath: string = process.cwd()): string | null {
+  refreshWriteGateStateFromDisk(basePath);
   return getWriteGateState(basePath).pendingGateId;
 }
 
@@ -1138,10 +1162,12 @@ export function shouldBlockWorktreeWrite(
   const realTarget = realpathOrResolve(absTarget);
   const realRoot = realpathOrResolve(projectRoot);
   const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));
-  const realWorktreesDir = realpathOrResolve(join(projectRoot, ".gsd", "worktrees"));
 
-  // Allow writes inside the legitimate worktrees subtree.
-  if (isPathContained(realTarget, realWorktreesDir)) return { block: false };
+  // Allow writes inside a legitimate worktrees subtree (canonical
+  // .gsd-worktrees/ or legacy .gsd/worktrees/).
+  for (const container of worktreesDirs(projectRoot)) {
+    if (isPathContained(realTarget, realpathOrResolve(container))) return { block: false };
+  }
 
   // Allow writes to .gsd/ planning artifacts, but reject siblings whose name
   // starts with "worktrees" (the worktrees-extra prefix trick — case 4).

package/src/resources/extensions/gsd/branch-patterns.ts

@@ -14,3 +14,6 @@ export const QUICK_BRANCH_RE = /^gsd\/quick\//;
 
 /** Matches GSD-generated workflow template branches, not arbitrary user gsd/* branches. */
 export const WORKFLOW_BRANCH_RE = /^gsd\/(?:hotfix|bugfix|small-feature|refactor|spike|security-audit|dep-upgrade|full-project)\//;
+
+/** Auto-mode milestone branch prefix: milestone/<MID>. */
+export const MILESTONE_BRANCH_PREFIX = "milestone/";

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

@@ -9,9 +9,10 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { gsdRoot } from "./paths.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -59,21 +60,9 @@ const VALID_CLASSIFICATIONS: readonly string[] = [
  * directory that contains `.gsd/worktrees/` — that's the project root.
  */
 export function resolveCapturesPath(basePath: string): string {
-  const resolved = resolve(basePath);
-  // Direct layout: /.gsd/worktrees/
-  const worktreeMarker = `${sep}.gsd${sep}worktrees${sep}`;
-  let idx = resolved.indexOf(worktreeMarker);
-  if (idx === -1) {
-    // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
-    const symlinkRe = new RegExp(
-      `\\${sep}\\.gsd\\${sep}projects\\${sep}[a-f0-9]+\\${sep}worktrees\\${sep}`,
-    );
-    const match = resolved.match(symlinkRe);
-    if (match && match.index !== undefined) idx = match.index;
-  }
-  if (idx !== -1) {
-    // basePath is inside a worktree — resolve to project root
-    const projectRoot = resolved.slice(0, idx);
+  // If basePath is inside a worktree, resolve to the project root.
+  const projectRoot = projectRootFromWorktreePath(resolve(basePath));
+  if (projectRoot) {
     return join(projectRoot, ".gsd", CAPTURES_FILENAME);
   }
   return join(gsdRoot(basePath), CAPTURES_FILENAME);

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

@@ -10,6 +10,7 @@ import { runTurnGitAction, type TurnGitActionMode, type TurnGitActionResult } fr
 import { _getAdapter, upsertTurnGitTransaction } from "./gsd-db.js";
 import { probeGitConflictState } from "./git-conflict-state.js";
 import { parseUnitId } from "./unit-id.js";
+import { worktreePathFor } from "./worktree-placement.js";
 
 export interface CloseoutFailureRecord {
   traceId: string;
@@ -156,7 +157,7 @@ export function resolveCloseoutRecoveryBasePath(projectRoot: string, record: Clo
   const parsed = parseUnitId(record.unitId);
   const milestoneId = parsed.milestone ?? (/^M\d+(?:-[a-z0-9]{6})?/.exec(record.unitId)?.[0] ?? "");
   if (milestoneId) {
-    const worktreePath = existingRealPath(join(projectRoot, ".gsd", "worktrees", milestoneId));
+    const worktreePath = existingRealPath(worktreePathFor(projectRoot, milestoneId));
     if (worktreePath) return worktreePath;
   }
 

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

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 
 import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
 
 
@@ -396,75 +397,12 @@ function getExtensionCompletions(prefix: string, action: string) {
   }
 }
 
-function normalizePathForCompare(path: string): string {
-  return path.replaceAll("\\", "/").replace(/\/+$/, "");
-}
-
-function findWorktreeSegment(normalizedPath: string): { gsdIdx: number; afterWorktrees: number } | null {
-  const directMarker = "/.gsd/worktrees/";
-  const directIdx = normalizedPath.indexOf(directMarker);
-  if (directIdx !== -1) {
-    return { gsdIdx: directIdx, afterWorktrees: directIdx + directMarker.length };
-  }
-
-  const symlinkMatch = normalizedPath.match(/\/\.gsd\/projects\/[a-f0-9]+\/worktrees\//);
-  if (symlinkMatch?.index !== undefined) {
-    return { gsdIdx: symlinkMatch.index, afterWorktrees: symlinkMatch.index + symlinkMatch[0].length };
-  }
-
-  return null;
-}
-
-function resolveProjectRootFromGitFile(worktreePath: string): string | null {
-  try {
-    let dir = worktreePath;
-    for (let i = 0; i < 30; i++) {
-      const gitPath = join(dir, ".git");
-      if (existsSync(gitPath)) {
-        const content = readFileSync(gitPath, "utf8").trim();
-        if (content.startsWith("gitdir: ")) {
-          const gitDir = resolve(dir, content.slice(8));
-          const dotGitDir = resolve(gitDir, "..", "..");
-          if (dotGitDir.endsWith(".git") || dotGitDir.endsWith(".git/") || dotGitDir.endsWith(".git\\")) {
-            return resolve(dotGitDir, "..");
-          }
-          const commonDirPath = join(gitDir, "commondir");
-          if (existsSync(commonDirPath)) {
-            const commonDir = readFileSync(commonDirPath, "utf8").trim();
-            return resolve(resolve(gitDir, commonDir), "..");
-          }
-        }
-        break;
-      }
-      const parent = resolve(dir, "..");
-      if (parent === dir) break;
-      dir = parent;
-    }
-  } catch {
-    // Completion must stay best-effort.
-  }
-  return null;
-}
-
 function resolveProjectRootForCompletion(basePath: string): string {
+  // Completion honors GSD_PROJECT_ROOT unconditionally (worker processes may
+  // complete from any cwd); resolveWorktreeProjectRoot only honors it for
+  // worktree paths.
   if (process.env.GSD_PROJECT_ROOT) return process.env.GSD_PROJECT_ROOT;
-
-  const normalizedPath = normalizePathForCompare(basePath);
-  const segment = findWorktreeSegment(normalizedPath);
-  if (!segment) return basePath;
-
-  const separator = basePath.includes("\\") ? "\\" : "/";
-  const gsdMarker = `${separator}.gsd${separator}`;
-  const gsdIdx = basePath.indexOf(gsdMarker);
-  const candidate = gsdIdx !== -1 ? basePath.slice(0, gsdIdx) : basePath.slice(0, segment.gsdIdx);
-
-  const normalizedGsdHome = normalizePathForCompare(gsdHome());
-  const candidateGsdPath = normalizePathForCompare(join(candidate, ".gsd"));
-  if (candidateGsdPath === normalizedGsdHome || candidateGsdPath.startsWith(`${normalizedGsdHome}/`)) {
-    return resolveProjectRootFromGitFile(basePath) ?? basePath;
-  }
-
-  return candidate;
+  return resolveWorktreeProjectRoot(basePath);
 }
 
 export function getGsdArgumentCompletions(prefix: string) {

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

@@ -39,6 +39,7 @@ import { markLatestActiveForWorkerCanceled, type DispatchStatus } from "./db/uni
 import { getRuntimeKv, setRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
 import { _getAdapter, isDbAvailable } from "./gsd-db.js";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
+import { crashResumeHint } from "./guidance.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { effectiveLockFile } from "./session-lock.js";
 import { isInFlightRuntimePhase, listUnitRuntimeRecords, type AutoUnitRuntimeRecord } from "./unit-runtime.js";
@@ -321,15 +322,8 @@ export function formatCrashInfo(lock: LockData): string {
     `  PID: ${lock.pid}`,
   ];
 
-  if (lock.unitType === "starting" && lock.unitId === "bootstrap") {
-    lines.push(`No work was lost. Run /gsd auto to restart.`);
-  } else if (lock.unitType.includes("research") || lock.unitType.includes("plan")) {
-    lines.push(`The ${lock.unitType} unit may be incomplete. Run /gsd auto to re-run it.`);
-  } else if (lock.unitType.includes("execute")) {
-    lines.push(`Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`);
-  } else if (lock.unitType.includes("complete")) {
-    lines.push(`Slice/milestone completion was interrupted. Run /gsd auto to finish.`);
-  }
+  const hint = crashResumeHint(lock.unitType, lock.unitId);
+  if (hint) lines.push(hint);
 
   return lines.join("\n");
 }