gsd-pi 2.67.0-dev.509bd95 → 2.67.0-dev.6fc2289

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

@@ -70,7 +70,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "templates", desc: "List available workflow templates" },
   { cmd: "extensions", desc: "Manage extensions (list, enable, disable, info)" },
   { cmd: "fast", desc: "Toggle OpenAI service tier (on/off/flex/status)" },
-  { cmd: "mcp", desc: "MCP server status and connectivity check (status, check <server>)" },
+  { cmd: "mcp", desc: "MCP server status, connectivity, and local config bootstrap (status, check, init)" },
   { cmd: "rethink", desc: "Conversational project reorganization — reorder, park, discard, add milestones" },
   { cmd: "workflow", desc: "Custom workflow lifecycle (new, run, list, validate, pause, resume)" },
   { cmd: "codebase", desc: "Generate, refresh, and inspect the codebase map cache (.gsd/CODEBASE.md)" },
@@ -201,6 +201,7 @@ const NESTED_COMPLETIONS: CompletionMap = {
   mcp: [
     { cmd: "status", desc: "Show all MCP server statuses (default)" },
     { cmd: "check", desc: "Detailed status for a specific server" },
+    { cmd: "init", desc: "Write .mcp.json for the local GSD workflow MCP server" },
   ],
   doctor: [
     { cmd: "fix", desc: "Auto-fix detected issues" },

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

@@ -60,7 +60,7 @@ export function showHelp(ctx: ExtensionCommandContext): void {
     "  /gsd hooks          Show post-unit hook configuration",
     "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
     "  /gsd fast           Toggle OpenAI service tier  [on|off|flex|status]",
-    "  /gsd mcp            MCP server status and connectivity  [status|check <server>]",
+    "  /gsd mcp            MCP server status and connectivity  [status|check <server>|init [dir]]",
     "",
     "MAINTENANCE",
     "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",

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

@@ -7,12 +7,15 @@
  *   /gsd mcp             — Overview of all servers (alias: /gsd mcp status)
  *   /gsd mcp status      — Same as bare /gsd mcp
  *   /gsd mcp check <srv> — Detailed status for a specific server
+ *   /gsd mcp init [dir]  — Write project-local GSD workflow MCP config
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
+
+import { ensureProjectWorkflowMcpConfig } from "./mcp-project-config.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -28,6 +31,28 @@ export interface McpServerDetail extends McpServerStatus {
   tools: string[];
 }
 
+export function formatMcpInitResult(
+  status: "created" | "updated" | "unchanged",
+  configPath: string,
+  targetPath: string,
+): string {
+  const summary =
+    status === "created"
+      ? "Created project MCP config."
+      : status === "updated"
+        ? "Updated project MCP config."
+        : "Project MCP config is already up to date.";
+
+  return [
+    summary,
+    "",
+    `Project: ${targetPath}`,
+    `Config:   ${configPath}`,
+    "",
+    "Claude Code can now load the GSD workflow MCP server from this folder.",
+  ].join("\n");
+}
+
 // ─── Config reader (standalone — does not import mcp-client internals) ──────
 
 interface McpServerRawConfig {
@@ -94,6 +119,7 @@ export function formatMcpStatusReport(servers: McpServerStatus[]): string {
       "No MCP servers configured.",
       "",
       "Add servers to .mcp.json or .gsd/mcp.json to enable MCP integrations.",
+      "Tip: run /gsd mcp init . to write the local GSD workflow MCP config.",
       "See: https://modelcontextprotocol.io/quickstart",
     ].join("\n");
   }
@@ -153,12 +179,31 @@ export async function handleMcpStatus(
   args: string,
   ctx: ExtensionCommandContext,
 ): Promise<void> {
-  const trimmed = args.trim().toLowerCase();
+  const trimmed = args.trim();
+  const lowered = trimmed.toLowerCase();
   const configs = readMcpConfigs();
 
+  // /gsd mcp init [dir]
+  if (!lowered || lowered === "status") {
+    // handled below
+  } else if (lowered === "init" || lowered.startsWith("init ")) {
+    const rawPath = trimmed.slice("init".length).trim();
+    const targetPath = resolve(rawPath || ".");
+    try {
+      const result = ensureProjectWorkflowMcpConfig(targetPath);
+      ctx.ui.notify(formatMcpInitResult(result.status, result.configPath, targetPath), "info");
+    } catch (err) {
+      ctx.ui.notify(
+        `Failed to prepare MCP config for ${targetPath}: ${err instanceof Error ? err.message : String(err)}`,
+        "error",
+      );
+    }
+    return;
+  }
+
   // /gsd mcp check <server>
-  if (trimmed.startsWith("check ")) {
-    const serverName = args.trim().slice("check ".length).trim();
+  if (lowered.startsWith("check ")) {
+    const serverName = trimmed.slice("check ".length).trim();
     const config = configs.find((c) => c.name === serverName);
     if (!config) {
       const available = configs.map((c) => c.name).join(", ") || "(none)";
@@ -202,7 +247,7 @@ export async function handleMcpStatus(
   }
 
   // /gsd mcp or /gsd mcp status
-  if (!trimmed || trimmed === "status") {
+  if (!lowered || lowered === "status") {
     // Build status for each server
     const statuses: McpServerStatus[] = [];
 
@@ -239,9 +284,10 @@ export async function handleMcpStatus(
 
   // Unknown subcommand
   ctx.ui.notify(
-    "Usage: /gsd mcp [status|check <server>]\n\n" +
+    "Usage: /gsd mcp [status|check <server>|init [dir]]\n\n" +
     "  status           Show all MCP server statuses (default)\n" +
-    "  check <server>   Detailed status for a specific server",
+    "  check <server>   Detailed status for a specific server\n" +
+    "  init [dir]       Write .mcp.json for the local GSD workflow MCP server",
     "warning",
   );
 }

package/src/resources/extensions/gsd/doctor-git-checks.ts

@@ -10,7 +10,7 @@ import { deriveState, isMilestoneComplete } from "./state.js";
 import { listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js";
 import { abortAndReset } from "./git-self-heal.js";
 import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch, writeIntegrationBranch } from "./git-service.js";
-import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddAllWithExclusions, nativeCommit } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeWorktreeList, nativeWorktreeRemove, nativeBranchList, nativeBranchDelete, nativeLsFiles, nativeRmCached, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { getAllWorktreeHealth } from "./worktree-health.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 
@@ -386,19 +386,19 @@ export async function checkGitHealth(
             code: "stale_uncommitted_changes",
             scope: "project",
             unitId: "project",
-            message: `Uncommitted changes detected with no commit in ${mins} minute${mins === 1 ? "" : "s"} (threshold: ${thresholdMinutes}m). Snapshotting uncommitted changes.`,
+            message: `Uncommitted changes detected with no commit in ${mins} minute${mins === 1 ? "" : "s"} (threshold: ${thresholdMinutes}m). Snapshotting tracked files.`,
             fixable: true,
           });
 
           if (shouldFix("stale_uncommitted_changes")) {
             try {
-              nativeAddAllWithExclusions(basePath, RUNTIME_EXCLUSION_PATHS);
+              nativeAddTracked(basePath);
               const commitMsg = `gsd snapshot: uncommitted changes after ${mins}m inactivity`;
               const result = nativeCommit(basePath, commitMsg);
               if (result) {
                 fixesApplied.push(`created gsd snapshot after ${mins}m of uncommitted changes`);
               } else {
-                fixesApplied.push("gsd snapshot skipped — nothing to commit after staging changes");
+                fixesApplied.push("gsd snapshot skipped — nothing to commit after staging tracked files");
               }
             } catch {
               fixesApplied.push("failed to create gsd snapshot commit");

package/src/resources/extensions/gsd/doctor-proactive.ts

@@ -21,8 +21,8 @@ import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.j
 import { abortAndReset } from "./git-self-heal.js";
 import { rebuildState } from "./doctor.js";
 import { deriveState } from "./state.js";
-import { RUNTIME_EXCLUSION_PATHS, resolveMilestoneIntegrationBranch } from "./git-service.js";
-import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddAllWithExclusions, nativeCommit } from "./native-git-bridge.js";
+import { resolveMilestoneIntegrationBranch } from "./git-service.js";
+import { nativeIsRepo, nativeHasChanges, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeAddTracked, nativeCommit } from "./native-git-bridge.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { runEnvironmentChecks } from "./doctor-environment.js";
 
@@ -312,7 +312,7 @@ export async function preDispatchHealthGate(basePath: string): Promise<PreDispat
         if (minutesSinceCommit >= thresholdMinutes) {
           const mins = Math.floor(minutesSinceCommit);
           try {
-            nativeAddAllWithExclusions(basePath, RUNTIME_EXCLUSION_PATHS);
+            nativeAddTracked(basePath);
             const commitMsg = `gsd snapshot: pre-dispatch, uncommitted changes after ${mins}m inactivity`;
             const result = nativeCommit(basePath, commitMsg);
             if (result) {

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

@@ -8,6 +8,7 @@ import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSl
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
+import { isClosedStatus } from "./status-guards.js";
 
 import type { DoctorIssue, DoctorIssueCode, DoctorReport } from "./doctor-types.js";
 import { GLOBAL_STATE_CODES } from "./doctor-types.js";
@@ -474,15 +475,16 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
     if (!roadmapContent) continue;
 
     // Normalize slices: prefer DB, fall back to parser
-    type NormSlice = RoadmapSliceEntry & { pending?: boolean };
+    type NormSlice = RoadmapSliceEntry & { pending?: boolean; skipped?: boolean };
     let slices: NormSlice[];
     if (isDbAvailable()) {
       const dbSlices = getMilestoneSlices(milestoneId);
       slices = dbSlices.map(s => ({
         id: s.id,
         title: s.title,
-        done: s.status === "complete",
+        done: isClosedStatus(s.status),
         pending: s.status === "pending",
+        skipped: s.status === "skipped",
         risk: (s.risk || "medium") as RoadmapSliceEntry["risk"],
         depends: s.depends,
         demo: s.demo,
@@ -578,8 +580,9 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
       const slicePath = resolveSlicePath(basePath, milestoneId, slice.id);
       if (!slicePath) {
         // Pending slices haven't been planned yet — directories are created
-        // lazily by ensurePreconditions() at dispatch time. Skip them.
-        if (slice.pending) continue;
+        // lazily by ensurePreconditions() at dispatch time. Skipped slices are
+        // intentionally allowed to remain summary-less and directory-less.
+        if (slice.pending || slice.skipped) continue;
         const expectedPath = relSlicePath(basePath, milestoneId, slice.id);
         issues.push({
           severity: slice.done ? "warning" : "error",
@@ -603,7 +606,8 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
       const tasksDir = resolveTasksDir(basePath, milestoneId, slice.id);
       if (!tasksDir) {
         // Pending slices haven't been planned yet — tasks/ is created on demand.
-        if (slice.pending) continue;
+        // Skipped slices may legitimately never create tasks/.
+        if (slice.pending || slice.skipped) continue;
         issues.push({
           severity: slice.done ? "warning" : "error",
           code: "missing_tasks_dir",

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

@@ -16,7 +16,12 @@ import { buildSkillActivationBlock } from "./auto-prompts.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { startAuto } from "./auto.js";
-import { readCrashLock, clearLock, formatCrashInfo } from "./crash-recovery.js";
+import { clearLock } from "./crash-recovery.js";
+import {
+  assessInterruptedSession,
+  formatInterruptedSessionRunningMessage,
+  formatInterruptedSessionSummary,
+} from "./interrupted-session.js";
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import {
@@ -215,17 +220,9 @@ export function checkAutoStartAfterDiscuss(): boolean {
 
   // Gate 4: Discussion manifest process verification (multi-milestone only)
   // The LLM writes DISCUSSION-MANIFEST.json after each Phase 3 gate decision.
-  // If the project is multi-milestone, the manifest is required. When it is
-  // missing, fail closed instead of assuming the discussion finished.
+  // When it exists, validate it before auto-starting. Project history alone is
+  // not a reliable signal for the current discussion mode.
   const manifestPath = join(gsdRoot(basePath), "DISCUSSION-MANIFEST.json");
-  const requiresManifest = projectIds.length > 1 || findMilestoneIds(basePath).length > 1;
-  if (requiresManifest && !existsSync(manifestPath)) {
-    ctx.ui.notify(
-      "Multi-milestone discussion manifest is missing. Auto-start will remain paused until the manifest is written.",
-      "warning",
-    );
-    return false;
-  }
   if (existsSync(manifestPath)) {
     try {
       const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -1322,36 +1319,45 @@ export async function showSmartEntry(
   // ── Self-heal stale runtime records from crashed auto-mode sessions ──
   selfHealRuntimeRecords(basePath, ctx);
 
-  // Check for crash from previous auto-mode session.
-  // Skip if the lock was written by the current process — acquireSessionLock()
-  // writes to the same file, so we'd always false-positive (#1398).
-  const crashLock = readCrashLock(basePath);
-  if (crashLock && crashLock.pid !== process.pid) {
-    clearLock(basePath);
+  const interrupted = await assessInterruptedSession(basePath);
+  if (interrupted.classification === "running") {
+    ctx.ui.notify(formatInterruptedSessionRunningMessage(interrupted), "error");
+    return;
+  }
 
-    // Bootstrap crash with zero completed units = no work was lost.
-    // Auto-discard instead of prompting the user — this commonly happens
-    // when the user exits during init wizard or discuss phase before any
-    // real auto-mode work begins.
-    const isBootstrapCrash = crashLock.unitType === "starting"
-      && crashLock.unitId === "bootstrap";
-
-    if (!isBootstrapCrash) {
-      const resume = await showNextAction(ctx, {
-        title: "GSD — Interrupted Session Detected",
-        summary: [formatCrashInfo(crashLock)],
-        actions: [
-          { id: "resume", label: "Resume with /gsd auto", description: "Pick up where it left off", recommended: true },
-          { id: "continue", label: "Continue manually", description: "Open the wizard as normal" },
-        ],
-      });
-      if (resume === "resume") {
-        await startAuto(ctx, pi, basePath, false);
-        return;
+  if (interrupted.classification === "stale") {
+    clearLock(basePath);
+    if (interrupted.pausedSession) {
+      try {
+        unlinkSync(join(gsdRoot(basePath), "runtime", "paused-session.json"));
+      } catch (e) {
+        logWarning("guided", `stale pause file cleanup failed: ${(e as Error).message}`, { file: "guided-flow.ts" });
       }
     }
+  } else if (interrupted.classification === "recoverable") {
+    if (interrupted.lock) clearLock(basePath);
+    const resumeLabel = interrupted.pausedSession?.stepMode
+      ? "Resume with /gsd next"
+      : "Resume with /gsd auto";
+    const resume = await showNextAction(ctx, {
+      title: "GSD — Interrupted Session Detected",
+      summary: formatInterruptedSessionSummary(interrupted),
+      actions: [
+        { id: "resume", label: resumeLabel, description: "Pick up where it left off", recommended: true },
+        { id: "continue", label: "Continue manually", description: "Open the wizard as normal" },
+      ],
+    });
+    if (resume === "resume") {
+      await startAuto(ctx, pi, basePath, false, {
+        interrupted,
+        step: interrupted.pausedSession?.stepMode ?? false,
+      });
+      return;
+    }
   }
 
+  // Always derive from the project root — the assessment may have derived
+  // state from a worktree path that was cleaned up in the stale branch above.
   const state = await deriveState(basePath);
 
   // Rebuild STATE.md from derived state before any dispatch (#3475).

package/src/resources/extensions/gsd/init-wizard.ts

@@ -235,6 +235,16 @@ export async function showProjectInit(
   // ── Step 9: Bootstrap .gsd/ ────────────────────────────────────────────────
   bootstrapGsdDirectory(basePath, prefs, signals);
 
+  // Initialize SQLite database so GSD starts in full-capability mode (#3880).
+  // Without this, isDbAvailable() returns false and GSD enters degraded
+  // markdown-only mode until a tool handler happens to call ensureDbOpen().
+  try {
+    const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+    await ensureDbOpen(basePath);
+  } catch {
+    // Non-fatal — DB creation failure should not block project init
+  }
+
   // Ensure .gitignore
   ensureGitignore(basePath);
   untrackRuntimeFiles(basePath);
@@ -250,6 +260,35 @@ export async function showProjectInit(
     // Non-fatal — codebase map generation failure should never block project init
   }
 
+  // Write initial STATE.md so it exists before the first /gsd invocation.
+  // The explicit /gsd init path (ops.ts) returns without entering showSmartEntry(),
+  // which would otherwise generate STATE.md at guided-flow.ts:1358.
+  try {
+    const { deriveState } = await import("./state.js");
+    const { buildStateMarkdown } = await import("./doctor.js");
+    const { saveFile } = await import("./files.js");
+    const { resolveGsdRootFile } = await import("./paths.js");
+    const state = await deriveState(basePath);
+    await saveFile(resolveGsdRootFile(basePath, "STATE"), buildStateMarkdown(state));
+  } catch {
+    // Non-fatal — STATE.md will be regenerated on next /gsd invocation
+  }
+
+  if (ctx.model?.provider === "claude-code") {
+    try {
+      const { ensureProjectWorkflowMcpConfig } = await import("./mcp-project-config.js");
+      const result = ensureProjectWorkflowMcpConfig(basePath);
+      if (result.status !== "unchanged") {
+        ctx.ui.notify(`Claude Code MCP prepared at ${result.configPath}`, "info");
+      }
+    } catch (err) {
+      ctx.ui.notify(
+        `Claude Code MCP prep failed: ${err instanceof Error ? err.message : String(err)}`,
+        "warning",
+      );
+    }
+  }
+
   ctx.ui.notify("GSD initialized. Starting your first milestone...", "info");
 
   return { completed: true, bootstrapped: true };
@@ -433,6 +472,7 @@ function bootstrapGsdDirectory(
 
   const gsd = gsdRoot(basePath);
   mkdirSync(join(gsd, "milestones"), { recursive: true });
+  mkdirSync(join(gsd, "runtime"), { recursive: true });
 
   // Write PREFERENCES.md from wizard answers
   const preferencesContent = buildPreferencesFile(prefs);

package/src/resources/extensions/gsd/interrupted-session.ts

@@ -0,0 +1,224 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { verifyExpectedArtifact } from "./auto-recovery.js";
+import {
+  formatCrashInfo,
+  isLockProcessAlive,
+  readCrashLock,
+  type LockData,
+} from "./crash-recovery.js";
+import { gsdRoot } from "./paths.js";
+import {
+  synthesizeCrashRecovery,
+  type RecoveryBriefing,
+} from "./session-forensics.js";
+import { deriveState } from "./state.js";
+import type { GSDState } from "./types.js";
+
+export type InterruptedSessionClassification =
+  | "none"
+  | "running"
+  | "recoverable"
+  | "stale";
+
+export interface PausedSessionMetadata {
+  milestoneId?: string;
+  worktreePath?: string | null;
+  originalBasePath?: string;
+  stepMode?: boolean;
+  pausedAt?: string;
+  sessionFile?: string | null;
+  unitType?: string;
+  unitId?: string;
+  activeEngineId?: string;
+  activeRunDir?: string | null;
+  autoStartTime?: number;
+}
+
+export interface InterruptedSessionAssessment {
+  classification: InterruptedSessionClassification;
+  lock: LockData | null;
+  pausedSession: PausedSessionMetadata | null;
+  state: GSDState | null;
+  recovery: RecoveryBriefing | null;
+  recoveryPrompt: string | null;
+  recoveryToolCallCount: number;
+  artifactSatisfied: boolean;
+  hasResumableDiskState: boolean;
+  isBootstrapCrash: boolean;
+}
+
+export function readPausedSessionMetadata(
+  basePath: string,
+): PausedSessionMetadata | null {
+  const pausedPath = join(gsdRoot(basePath), "runtime", "paused-session.json");
+  if (!existsSync(pausedPath)) return null;
+
+  try {
+    return JSON.parse(readFileSync(pausedPath, "utf-8")) as PausedSessionMetadata;
+  } catch {
+    return null;
+  }
+}
+
+export function isBootstrapCrashLock(lock: LockData | null): boolean {
+  return !!(
+    lock &&
+    lock.unitType === "starting" &&
+    lock.unitId === "bootstrap"
+  );
+}
+
+export function hasResumableDerivedState(state: GSDState | null): boolean {
+  return !!(state?.activeMilestone && state.phase !== "complete");
+}
+
+export async function assessInterruptedSession(
+  basePath: string,
+): Promise<InterruptedSessionAssessment> {
+  const pausedSession = readPausedSessionMetadata(basePath);
+  const worktreeExists = pausedSession?.worktreePath
+    ? existsSync(pausedSession.worktreePath)
+    : false;
+  const assessmentBasePath = worktreeExists ? pausedSession!.worktreePath! : basePath;
+  const rawLock = readCrashLock(basePath);
+  const lock = rawLock && rawLock.pid !== process.pid ? rawLock : null;
+
+  if (!lock && !pausedSession) {
+    return {
+      classification: "none",
+      lock: null,
+      pausedSession: null,
+      state: null,
+      recovery: null,
+      recoveryPrompt: null,
+      recoveryToolCallCount: 0,
+      artifactSatisfied: false,
+      hasResumableDiskState: false,
+      isBootstrapCrash: false,
+    };
+  }
+
+  if (lock && isLockProcessAlive(lock)) {
+    return {
+      classification: "running",
+      lock,
+      pausedSession,
+      state: null,
+      recovery: null,
+      recoveryPrompt: null,
+      recoveryToolCallCount: 0,
+      artifactSatisfied: false,
+      hasResumableDiskState: false,
+      isBootstrapCrash: false,
+    };
+  }
+
+  const isBootstrapCrash = isBootstrapCrashLock(lock);
+  const state = await deriveState(assessmentBasePath);
+  const hasResumableDiskState = hasResumableDerivedState(state);
+  const artifactSatisfied = !!(
+    lock &&
+    !isBootstrapCrash &&
+    verifyExpectedArtifact(lock.unitType, lock.unitId, assessmentBasePath)
+  );
+
+  let recovery: RecoveryBriefing | null = null;
+  if (lock && !isBootstrapCrash && !artifactSatisfied) {
+    recovery = synthesizeCrashRecovery(
+      assessmentBasePath,
+      lock.unitType,
+      lock.unitId,
+      lock.sessionFile,
+      join(gsdRoot(assessmentBasePath), "activity"),
+    );
+  }
+
+  const recoveryToolCallCount = recovery?.trace.toolCallCount ?? 0;
+  const recoveryPrompt = recoveryToolCallCount > 0 ? recovery!.prompt : null;
+
+  if (isBootstrapCrash) {
+    return {
+      classification: pausedSession ? "recoverable" : "stale",
+      lock,
+      pausedSession,
+      state,
+      recovery,
+      recoveryPrompt,
+      recoveryToolCallCount,
+      artifactSatisfied,
+      hasResumableDiskState,
+      isBootstrapCrash: true,
+    };
+  }
+
+  if (!hasResumableDiskState && pausedSession && !lock && recoveryToolCallCount === 0) {
+    return {
+      classification: "stale",
+      lock,
+      pausedSession,
+      state,
+      recovery,
+      recoveryPrompt,
+      recoveryToolCallCount,
+      artifactSatisfied,
+      hasResumableDiskState,
+      isBootstrapCrash: false,
+    };
+  }
+
+  if (lock && artifactSatisfied && !hasResumableDiskState && recoveryToolCallCount === 0) {
+    return {
+      classification: "stale",
+      lock,
+      pausedSession,
+      state,
+      recovery,
+      recoveryPrompt,
+      recoveryToolCallCount,
+      artifactSatisfied,
+      hasResumableDiskState,
+      isBootstrapCrash: false,
+    };
+  }
+
+  const hasStrongRecoverySignal =
+    hasResumableDiskState || recoveryToolCallCount > 0;
+
+  return {
+    classification: hasStrongRecoverySignal ? "recoverable" : "stale",
+    lock,
+    pausedSession,
+    state,
+    recovery,
+    recoveryPrompt,
+    recoveryToolCallCount,
+    artifactSatisfied,
+    hasResumableDiskState,
+    isBootstrapCrash: false,
+  };
+}
+
+export function formatInterruptedSessionSummary(
+  assessment: InterruptedSessionAssessment,
+): string[] {
+  if (assessment.lock) return [formatCrashInfo(assessment.lock)];
+
+  if (assessment.pausedSession?.milestoneId) {
+    return [
+      `Paused auto-mode session detected for ${assessment.pausedSession.milestoneId}.`,
+    ];
+  }
+
+  return ["Paused auto-mode session detected."];
+}
+
+export function formatInterruptedSessionRunningMessage(
+  assessment: InterruptedSessionAssessment,
+): string {
+  const pid = assessment.lock?.pid;
+  return pid
+    ? `Another auto-mode session (PID ${pid}) appears to be running.\nStop it with \`kill ${pid}\` before starting a new session.`
+    : "Another auto-mode session appears to be running.";
+}