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

package/dist/resources/extensions/gsd/engine-hook-contract.js

@@ -0,0 +1,70 @@
+// Project/App: gsd-pi
+// File Purpose: Typed contract for which tool lifecycle hooks fire under which
+// engine, plus the single seam for tool-name normalization.
+//
+// ── Why this contract exists ────────────────────────────────────────────────
+// External engines (claude-code-cli) pre-execute tools inside the vendor CLI
+// and hand the agent loop a `toolCall.externalResult`. The loop short-circuits
+// before `beforeToolCall`/`afterToolCall` ever run for those calls
+// (packages/pi-agent-core/src/agent-loop.ts, prepareToolCall: the
+// externalResult branch returns an "immediate" outcome before the
+// config.beforeToolCall invocation, and "immediate" outcomes skip
+// finalizeExecutedToolCall where config.afterToolCall lives).
+// `beforeToolCall`/`afterToolCall` are exactly what the extension runner maps
+// to the `tool_call`/`tool_result` extension events
+// (packages/gsd-agent-core/src/session/agent-session-extensions.ts,
+// installAgentToolHooks).
+//
+// `tool_execution_start` is emitted unconditionally before prepareToolCall
+// and `tool_execution_end` after every finalized outcome — immediate or
+// executed — so those two are the ONLY tool lifecycle hooks that fire for
+// every tool call on every engine.
+//
+// Consequence: any enforcement attached only to `tool_call` (blocking) or
+// `tool_result` (rewriting) is silently dead under external engines. Safety
+// enforcement must ride `tool_execution_start`/`tool_execution_end`, or
+// mirror across both with toolCallId dedup. See the per-registration contract
+// comments in bootstrap/register-hooks.ts for how each registered hook
+// honors (or knowingly violates) this contract.
+import { stripMcpToolPrefix } from "./mcp-tool-name.js";
+import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+/**
+ * Tool lifecycle hooks that fire for EVERY tool call on EVERY engine,
+ * including external engines (claude-code-cli) that pre-execute tools.
+ * Attach safety-critical enforcement and evidence collection here.
+ */
+export const UNIVERSAL_TOOL_HOOKS = ["tool_execution_start", "tool_execution_end"];
+/**
+ * Tool lifecycle hooks that fire ONLY for natively executed tools. External
+ * engines pre-execute tools (externalResult), short-circuiting the agent
+ * loop's beforeToolCall/afterToolCall — so handlers on these events never run
+ * for those calls. Blocking guards attached only here are dead under external
+ * engines; they need a tool_execution_start mirror to be universal.
+ */
+export const NATIVE_ONLY_TOOL_HOOKS = ["tool_call", "tool_result"];
+// Non-tool lifecycle events (session_start, agent_end, message_update, ...)
+// are intentionally NOT classified here: they are emitted by the session
+// host / extension runner independent of tool execution, so the external
+// engine short-circuit above does not apply to them. Only classify events
+// whose engine behavior has been verified against the agent loop.
+/**
+ * Canonical tool name: strips the `mcp__<server>__` prefix when present,
+ * nothing else. Use for identity checks against host/native tool names and
+ * for any guard that must NOT conflate workflow aliases with their canonical
+ * tools (e.g. write gates, evidence keys).
+ *
+ * Malformed MCP names (empty server or empty tool segment, e.g.
+ * `mcp____tool` or `mcp__server__`) are returned unchanged.
+ */
+export function canonicalToolName(toolName) {
+    return stripMcpToolPrefix(toolName);
+}
+/**
+ * Workflow-aware canonical tool name: strips the MCP prefix AND resolves
+ * workflow tool aliases to their canonical contract names. Use whenever the
+ * name is compared against the workflow tool surface (scoping, presentation,
+ * dispatch) — plain {@link canonicalToolName} would miss alias spellings.
+ */
+export function canonicalWorkflowToolName(toolName) {
+    return canonicalWorkflowSurfaceToolName(toolName);
+}

package/dist/resources/extensions/gsd/error-classifier.js

@@ -9,6 +9,7 @@
  *
  * @see https://github.com/open-gsd/gsd-pi/issues/2577
  */
+import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
 export function createRetryState() {
     return { networkRetryCount: 0, consecutiveTransientCount: 0, currentRetryModelId: undefined };
 }
@@ -44,6 +45,10 @@ const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side close
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;
 const RESET_DELAY_RE = /reset in (\d+)s/i;
 const TOOL_SCHEMA_RE = /schema overload|consecutive tool validation failures/i;
+// GSD tool-surface readiness abort (claude-code stream adapter): the workflow
+// MCP server had not registered the Unit's required tools at SDK init. The
+// server typically finishes connecting within seconds — same-model retry.
+const TOOL_SURFACE_NOT_READY_RE = new RegExp(TOOL_SURFACE_NOT_READY, "i");
 // Provider rejected the request shape for the selected model (400 bad request,
 // grammar limits, etc.). Not transient — try a different model/fallback.
 // Context-window 400s stay in SERVER_RE (checked earlier).
@@ -77,6 +82,10 @@ export function classifyError(errorMsg, retryAfterMs) {
     if (TOOL_SCHEMA_RE.test(errorMsg)) {
         return { kind: "tool-schema", retryAfterMs: 0 };
     }
+    // Tool-surface readiness abort — transient; retry the same model shortly.
+    if (TOOL_SURFACE_NOT_READY_RE.test(errorMsg)) {
+        return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 };
+    }
     const isPermanent = PERMANENT_RE.test(errorMsg);
     const isRateLimit = RATE_LIMIT_RE.test(errorMsg) || AFFORDABILITY_RE.test(errorMsg);
     const isUnsupportedModel = UNSUPPORTED_MODEL_MODEL_RE.test(errorMsg) &&

package/dist/resources/extensions/gsd/exec-sandbox.js

@@ -11,7 +11,11 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
+import { killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
 const ALWAYS_FORWARD_ENV = ["PATH", "HOME"];
+// SIGKILL_GRACE_MS / HARD_DEADLINE_MS are imported from @gsd/pi-coding-agent
+// (shell.ts) — the single source of truth for the graceful-kill timing ladder —
+// so this sandbox can never drift from the canonical kill path it delegates to.
 export const EXEC_DEFAULTS = {
     clampTimeoutMs: 600_000,
     defaultTimeoutMs: 30_000,
@@ -120,6 +124,7 @@ export function runExecSandbox(request, opts) {
                 exit_code: null,
                 signal: null,
                 timed_out: false,
+                force_resolved: false,
                 duration_ms: duration,
                 stdout_bytes: 0,
                 stderr_bytes: Buffer.byteLength(`spawn error: ${message}\n`),
@@ -172,24 +177,38 @@ export function runExecSandbox(request, opts) {
                 stderrTruncated = true;
             }
         });
+        const effectiveGraceMs = opts.kill_grace_ms ?? SIGKILL_GRACE_MS;
+        const effectiveForceResolveDelay = opts.force_resolve_delay_ms ?? (effectiveGraceMs + HARD_DEADLINE_MS);
         let timedOut = false;
+        let settled = false;
+        let forceResolveTimer;
         const timer = setTimeout(() => {
             timedOut = true;
-            if (useProcessGroup && child.pid != null) {
-                try {
-                    process.kill(-child.pid, "SIGKILL");
-                }
-                catch {
-                    child.kill("SIGKILL");
-                }
+            // killProcessTree handles both platforms and kills the whole tree: on Unix
+            // it signals the process group (SIGTERM -> grace -> SIGKILL); on Windows it
+            // force-kills the tree via taskkill /F /T. Using child.kill("SIGTERM") here
+            // would only terminate the direct child on Windows, orphaning grandchildren.
+            if (child.pid != null) {
+                killProcessTree(child.pid, { graceMs: effectiveGraceMs });
             }
             else {
-                child.kill("SIGKILL");
+                child.kill("SIGTERM");
             }
+            // Arm hard-deadline force-resolve in case child never closes (D-state).
+            // The "SIGKILL" here is a synthetic marker (the process may not have actually
+            // received it); force_resolved=true records that this was a deadline, not an exit.
+            forceResolveTimer = setTimeout(() => {
+                finalize(null, "SIGKILL", true);
+            }, effectiveForceResolveDelay);
+            forceResolveTimer.unref?.();
         }, timeoutMs);
         timer.unref?.();
-        const finalize = (exitCode, signal) => {
+        const finalize = (exitCode, signal, forceResolved = false) => {
+            if (settled)
+                return;
+            settled = true;
             clearTimeout(timer);
+            clearTimeout(forceResolveTimer);
             const duration = Date.now() - started;
             const stdoutBuf = Buffer.concat(stdoutChunks);
             const stderrBuf = Buffer.concat(stderrChunks);
@@ -211,6 +230,7 @@ export function runExecSandbox(request, opts) {
                 exit_code: exitCode,
                 signal,
                 timed_out: timedOut,
+                force_resolved: forceResolved,
                 duration_ms: duration,
                 stdout_bytes: stdoutBytes,
                 stderr_bytes: stderrBytes,
@@ -254,6 +274,7 @@ function writeMeta(path, result, request, now) {
         exit_code: result.exit_code,
         signal: result.signal,
         timed_out: result.timed_out,
+        force_resolved: result.force_resolved,
         duration_ms: result.duration_ms,
         stdout_bytes: result.stdout_bytes,
         stderr_bytes: result.stderr_bytes,
@@ -261,7 +282,6 @@ function writeMeta(path, result, request, now) {
         stderr_truncated: result.stderr_truncated,
         stdout_path: result.stdout_path,
         stderr_path: result.stderr_path,
-        ...(request.metadata ? { metadata: request.metadata } : {}),
     };
     writeFileSync(path, `${JSON.stringify(meta, null, 2)}\n`);
 }

package/dist/resources/extensions/gsd/files.js

@@ -576,38 +576,52 @@ export function parseTaskPlanIO(content) {
         outputFiles: extractPaths(outputSection),
     };
 }
+/** Canonical list of recognised UAT types — uat-policy.ts re-exports this as UAT_TYPES. */
+export const UAT_TYPE_KEYWORDS = [
+    'artifact-driven',
+    'browser-executable',
+    'runtime-executable',
+    'live-runtime',
+    'mixed',
+    'human-experience',
+];
+/** Match a value against the recognised UAT type keywords (leading-keyword-only). */
+function matchUatTypeKeyword(value) {
+    const normalized = value.trim().toLowerCase();
+    return UAT_TYPE_KEYWORDS.find(keyword => normalized.startsWith(keyword));
+}
 /**
  * Extract the UAT type from a UAT file's raw content.
  *
  * UAT files have no YAML frontmatter - pass raw file content directly.
  * Classification is leading-keyword-only: e.g. `mixed (artifact-driven + live-runtime)` → `'mixed'`.
  *
+ * The canonical form is a `- UAT mode: <type>` bullet under `## UAT Type`
+ * (case-insensitive prefix, `**bold**` tolerated). When no such line exists,
+ * a line that itself starts with a recognised keyword — e.g. a bare
+ * `browser-executable` under the heading — is accepted, so agent-authored
+ * format drift does not silently fall back to artifact-driven.
+ *
  * Returns `undefined` when:
  * - the `## UAT Type` section is absent
- * - no `UAT mode:` bullet is found in the section
- * - the value does not start with a recognised keyword
+ * - a `UAT mode:` line exists but its value starts with no recognised keyword
+ * - no line in the section starts with `UAT mode:` or a recognised keyword
  */
 export function extractUatType(content) {
     const sectionText = extractSection(content, 'UAT Type');
     if (!sectionText)
         return undefined;
-    const bullets = parseBullets(sectionText);
-    const modeBullet = bullets.find(b => b.startsWith('UAT mode:'));
-    if (!modeBullet)
-        return undefined;
-    const rawValue = modeBullet.slice('UAT mode:'.length).trim().toLowerCase();
-    if (rawValue.startsWith('artifact-driven'))
-        return 'artifact-driven';
-    if (rawValue.startsWith('browser-executable'))
-        return 'browser-executable';
-    if (rawValue.startsWith('runtime-executable'))
-        return 'runtime-executable';
-    if (rawValue.startsWith('live-runtime'))
-        return 'live-runtime';
-    if (rawValue.startsWith('human-experience'))
-        return 'human-experience';
-    if (rawValue.startsWith('mixed'))
-        return 'mixed';
+    const lines = parseBullets(sectionText).map(line => line.replace(/\*\*/g, ''));
+    for (const line of lines) {
+        const declared = /^uat mode:\s*(.*)$/i.exec(line);
+        if (declared)
+            return matchUatTypeKeyword(declared[1]);
+    }
+    for (const line of lines) {
+        const matched = matchUatTypeKeyword(line);
+        if (matched)
+            return matched;
+    }
     return undefined;
 }
 /**

package/dist/resources/extensions/gsd/gsd-command-home.js

@@ -28,13 +28,17 @@ export function buildGsdHomeModel(state, closeout) {
     const workLabel = activeWorkLabel(state);
     const strandedQuick = closeout?.strandedQuick ?? null;
     const unmergedMilestone = closeout?.unmergedMilestones?.[0];
+    const idleResidueHint = closeout?.idleResidueHint ?? null;
+    const hasIdleResidue = Boolean(idleResidueHint);
     const nextReason = complete
         ? "all milestones are complete"
         : blocked
             ? "the active milestone is blocked"
-            : !hasActiveWork
-                ? "there is no active milestone"
-                : "";
+            : hasIdleResidue
+                ? "milestone git residue needs recovery"
+                : !hasActiveWork
+                    ? "there is no active milestone"
+                    : "";
     const canAdvance = hasActiveWork && !blocked && !complete;
     const unmappedActive = complete ? countUnmappedActiveRequirements() : 0;
     const recommended = strandedQuick
@@ -43,11 +47,13 @@ export function buildGsdHomeModel(state, closeout) {
             ? "finish_milestone"
             : blocked
                 ? "fix_recover"
-                : canAdvance
-                    ? "continue_step"
-                    : complete && unmappedActive > 0
-                        ? "review_requirements_backlog"
-                        : "start_configure";
+                : hasIdleResidue
+                    ? "fix_recover"
+                    : canAdvance
+                        ? "continue_step"
+                        : complete && unmappedActive > 0
+                            ? "review_requirements_backlog"
+                            : "start_configure";
     const completionSummary = complete
         ? appendRequirementsBacklogToSummary(state, [
             `All milestones complete${state.lastCompletedMilestone ? ` after ${state.lastCompletedMilestone.id}: ${state.lastCompletedMilestone.title}` : ""}.`,
@@ -57,7 +63,9 @@ export function buildGsdHomeModel(state, closeout) {
         ? [`Quick task Q${strandedQuick.taskNum} finished on ${strandedQuick.quickBranch} but is not merged to ${strandedQuick.originalBranch}.`]
         : unmergedMilestone
             ? [`${unmergedMilestone.milestoneId} is complete but not merged into ${unmergedMilestone.integrationBranch}.`]
-            : completionSummary;
+            : idleResidueHint
+                ? [idleResidueHint.message]
+                : completionSummary;
     return {
         title: "GSD — What now?",
         summary: [
@@ -130,10 +138,12 @@ export function buildGsdHomeModel(state, closeout) {
                 label: "Fix or recover",
                 description: blocked
                     ? "Review the blocker and recovery commands for the active milestone."
-                    : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
-                enabled: blocked,
+                    : hasIdleResidue
+                        ? "Review stranded milestone worktrees/branches and run the suggested recovery command."
+                        : disabled("This becomes active when closeout, validation, or state recovery is needed.", "no blocker is active"),
+                enabled: blocked || hasIdleResidue,
                 recommended: recommended === "fix_recover",
-                disabledReason: blocked ? undefined : "no blocker is active",
+                disabledReason: blocked || hasIdleResidue ? undefined : "no blocker is active",
             },
             {
                 id: "start_configure",

package/dist/resources/extensions/gsd/gsd-db.js

@@ -169,7 +169,7 @@ export function insertArtifact(a) {
 export function insertMilestone(m) {
     if (!getDbOrNull())
         throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-    getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
+    const result = getDbOrNull().prepare(`INSERT OR IGNORE INTO milestones (
       id, title, status, depends_on, created_at,
       vision, success_criteria, key_risks, proof_strategy,
       verification_contract, verification_integration, verification_operational, verification_uat,
@@ -199,6 +199,7 @@ export function insertMilestone(m) {
         ":requirement_coverage": m.planning?.requirementCoverage ?? "",
         ":boundary_map_markdown": m.planning?.boundaryMapMarkdown ?? "",
     });
+    return (result.changes ?? 0) > 0;
 }
 export function upsertMilestonePlanning(milestoneId, planning) {
     if (!getDbOrNull())

package/dist/resources/extensions/gsd/guidance.js

@@ -0,0 +1,158 @@
+// Project/App: gsd-pi
+// File Purpose: Guidance module — the single catalog mapping typed findings
+// (Recovery kinds, milestone blocker kinds, doctor issue codes, crash unit
+// classes) to user-facing remediation: what happened and what to do next.
+//
+// Emit sites pass the typed finding; phrasing, command names, and step
+// ordering live here. A missing catalog row is a visible gap, not a silent
+// omission scattered across call sites.
+/** Flatten guidance into a notification / pause-banner string. */
+export function formatGuidance(guidance) {
+    if (guidance.steps.length === 0)
+        return guidance.summary;
+    const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
+    return `${guidance.summary}\n\n${numbered}`;
+}
+const RECOVERY_REMEDIATION = {
+    "tool-schema": "Fix the Unit Tool Contract or tool schema before retrying.",
+    "tool-contract": "Fix the Unit Tool Contract or prompt so the Unit is only asked to use tools owned by its phase.",
+    "tool-unavailable": "The tool surface had not finished registering when the Unit called it (workflow MCP startup race). Retry after the surface is ready; escalate if the tool never appears.",
+    "deterministic-policy": "Resolve the policy blocker; retrying the same Unit will repeat the failure.",
+    "lifecycle-progression": "Route to the required owning Unit or restore the missing artifact before advancing lifecycle state.",
+    "stale-worker": "Run `/gsd doctor` to detect and clear the stale worker or lock, then run `/gsd auto` to resume.",
+    "worktree-invalid": "Run `/gsd doctor` to diagnose the milestone worktree (`gsd worktree list` shows its state). Repair it, or merge salvageable work with `gsd worktree merge <name>` before recreating — recreating discards uncommitted work.",
+    "verification-drift": "Run `/gsd status` to see the verification finding, fix or re-run the verification, then run `/gsd auto` to resume. `/gsd doctor` can repair stale state files.",
+    "reconciliation-drift": "Run `/gsd doctor` to surface the persistent or repair-failed drift kinds, apply its fixes, then run `/gsd auto` to resume.",
+    "illegal-transition": "A derived Phase edge rejected by the Phase Transition Invariant survived reconciliation; inspect deriveState and the State Reconciliation Module before resuming.",
+    "runtime-unknown": "Inspect the runtime error and add a dedicated classification if it is repeatable.",
+    "provider-transient": "Retry after the provider/network condition clears.",
+    "provider-permanent": "Inspect provider credentials, model entitlement, or request shape.",
+};
+export function recoveryRemediation(key) {
+    return RECOVERY_REMEDIATION[key];
+}
+// ─── Milestone validation blockers ──────────────────────────────────────
+// NOTE: the first line of each blocker is load-bearing — validation-block-guard
+// matches /milestone validation returned needs-(?:attention|remediation)/i.
+// Keep that phrase intact when editing.
+export function needsAttentionBlockerGuidance(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is blocked because milestone validation returned needs-attention.`,
+        `Fix options:`,
+        `1. Review the validation details: \`/gsd status\``,
+        `2. If you fixed the missing evidence or issue, re-run milestone validation: \`/gsd validate-milestone\``,
+        `3. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+        `4. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+        `After validation or override passes, run \`/gsd auto\` to complete and merge the milestone.`,
+    ].join("\n");
+}
+export function needsRemediationBlockerGuidance(milestoneId) {
+    return [
+        `Milestone ${milestoneId} is blocked because milestone validation returned needs-remediation, but all slices are complete.`,
+        `Fix options:`,
+        `1. Run \`/gsd dispatch reassess\` to add remediation slices, then run \`/gsd auto\``,
+        `2. If the finding is acceptable, override it: \`/gsd verdict pass --rationale "why this is okay"\``,
+        `3. If this should wait, defer it explicitly: \`/gsd park ${milestoneId}\``,
+    ].join("\n");
+}
+// ─── Milestone closeout UAT sign-off blockers ───────────────────────────
+// The first sentence is the blocker finding; the numbered steps are the
+// resolution path. `verdict` is the recorded non-PASS verdict, or undefined
+// when no verdict has been recorded at all.
+export function uatSignoffBlockerGuidance(milestoneId, sliceId, verdict) {
+    const finding = verdict === undefined
+        ? `missing UAT PASS verdict for ${sliceId}`
+        : `UAT verdict for ${sliceId} is "${verdict}"`;
+    const sliceSpecificRerunStep = `If ${sliceId} is not the most recently completed slice, type a chat request to re-run UAT for ${sliceId}; run-uat will record the verdict through \`gsd_uat_result_save\`.`;
+    const steps = verdict === undefined
+        ? [
+            `1. Run UAT for the most recently completed slice to record a verdict: \`/gsd dispatch uat\``,
+            `2. ${sliceSpecificRerunStep}`,
+            `3. Review the UAT criteria and progress: \`/gsd status\``,
+            `4. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ]
+        : [
+            `1. Review the failing UAT findings: \`/gsd status\` (the ${sliceId} ASSESSMENT records what failed)`,
+            `2. Fix the issue, then re-run UAT for the most recently completed slice to record a fresh verdict: \`/gsd dispatch uat\``,
+            `3. ${sliceSpecificRerunStep}`,
+            `4. If the fix needs new implementation work, add remediation slices: \`/gsd dispatch reassess\``,
+            `5. After UAT records PASS, run \`/gsd auto\` to complete the milestone.`,
+        ];
+    return [
+        `Cannot complete milestone ${milestoneId}: ${finding}. Manual UAT sign-off (PASS) is required before milestone closure.`,
+        `Fix options:`,
+        ...steps,
+    ].join("\n");
+}
+// ─── Worktree isolation degradation ─────────────────────────────────────
+// The first sentence of each notice is load-bearing for log matching and
+// tests — keep it intact and append guidance after it.
+function restoreIsolationHint(milestoneId) {
+    return `To restore isolation: close any processes using the old worktree, merge salvageable work with \`/gsd worktree merge ${milestoneId}\` or remove the stale worktree with \`/gsd worktree remove ${milestoneId}\`, then run \`/gsd doctor fix\`.`;
+}
+export function worktreeCreationFailedGuidance(milestoneId, error) {
+    return [
+        `Auto-worktree creation for ${milestoneId} failed: ${error}. Continuing in project root.`,
+        `Worktree isolation is degraded for this session.`,
+        restoreIsolationHint(milestoneId),
+    ].join("\n");
+}
+export function isolationDegradedFallbackGuidance(milestoneId) {
+    return [
+        `Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`,
+        `Work continues safely on the milestone branch in the project root.`,
+        restoreIsolationHint(milestoneId),
+    ].join("\n");
+}
+/** Hard entry blockers from auto-start: bootstrap stopped, user must act. */
+export function milestoneEntryBlockedGuidance(milestoneId, reason) {
+    const finding = reason === "creation-failed"
+        ? `worktree/branch creation failed. Isolation is degraded.`
+        : `isolation is degraded from a prior worktree failure.`;
+    return [
+        `Cannot enter milestone ${milestoneId}: ${finding}`,
+        restoreIsolationHint(milestoneId),
+        `Then run \`/gsd auto\` to retry.`,
+    ].join("\n");
+}
+// ─── Crash recovery resume hints ────────────────────────────────────────
+/** Resume hint for an interrupted auto-mode unit, by unit class. */
+export function crashResumeHint(unitType, unitId) {
+    if (unitType === "starting" && unitId === "bootstrap") {
+        return `No work was lost. Run /gsd auto to restart.`;
+    }
+    if (unitType.includes("research") || unitType.includes("plan")) {
+        return `The ${unitType} unit may be incomplete. Run /gsd auto to re-run it.`;
+    }
+    if (unitType.includes("execute")) {
+        return `Task execution was interrupted. Run /gsd auto to resume — completed work is preserved.`;
+    }
+    if (unitType.includes("complete")) {
+        return `Slice/milestone completion was interrupted. Run /gsd auto to finish.`;
+    }
+    return undefined;
+}
+// ─── Doctor issue fix hints ─────────────────────────────────────────────
+// Partial by design: codes without a row render no hint. Add rows here as
+// guidance is authored — the gap is visible in one place.
+const DOCTOR_FIX_HINTS = {
+    db_unavailable: "The workflow database could not be opened — state derivation is degraded. Restart the session; if it persists, run `/gsd doctor` from the project root.",
+    stale_crash_lock: "Run `/gsd doctor` to clear the stale lock, then `/gsd auto` to resume.",
+    stale_parallel_session: "Run `/gsd doctor` to clear the stale session registration.",
+    unresolved_git_conflicts: "Resolve the conflict markers, commit, then re-run `/gsd auto`.",
+    conflict_markers_in_tracked_files: "Search the listed files for `<<<<<<<` markers, resolve, and commit.",
+    worktree_dirty: "Commit or merge the worktree's changes (`gsd worktree merge <name>`) before removing it.",
+    worktree_branch_merged: "The branch is merged — remove the worktree to reclaim space.",
+    orphaned_auto_worktree: "Run `/gsd doctor` to fix, or merge salvageable work with `gsd worktree merge <name>`.",
+    gitignore_missing_patterns: "Run `/gsd doctor` to append the missing .gitignore patterns.",
+    invalid_preferences: "Edit .gsd/PREFERENCES.md to fix the invalid field, then re-run the command.",
+    provider_key_missing: "Add the provider API key to your environment or provider config, then retry.",
+    provider_key_backedoff: "The key is cooling down after repeated failures — wait, or switch the phase model in .gsd/PREFERENCES.md.",
+    state_file_stale: "Run `/gsd doctor` to rebuild the projection from the database.",
+    state_file_missing: "Run `/gsd doctor` to rebuild the projection from the database.",
+    projection_drift: "Run `/gsd doctor` to rebuild markdown projections from the database (DB is the source of truth).",
+    uat_retry_exhausted: "Review the failing UAT criteria via `/gsd status`, fix the issue, then re-run `/gsd auto`.",
+};
+export function doctorFixHint(code) {
+    return DOCTOR_FIX_HINTS[code];
+}