gsd-pi 2.67.0-dev.1cd1e0f → 2.67.0-dev.2367d7e

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 {
@@ -40,6 +45,10 @@ import { findMilestoneIds, nextMilestoneId, reserveMilestoneId, getReservedMiles
 import { parkMilestone, discardMilestone } from "./milestone-actions.js";
 import { selectAndApplyModel } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
+import {
+  getWorkflowTransportSupportError,
+  getRequiredWorkflowToolsForGuidedUnit,
+} from "./workflow-mcp.js";
 import {
   runPreparation,
   formatCodebaseBrief,
@@ -211,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"));
@@ -318,6 +319,26 @@ async function dispatchWorkflow(
         routing: result.routing,
       });
     }
+
+    const compatibilityError = getWorkflowTransportSupportError(
+      result.appliedModel?.provider ?? ctx.model?.provider,
+      getRequiredWorkflowToolsForGuidedUnit(unitType),
+      {
+        projectRoot: process.cwd(),
+        surface: "guided flow",
+        unitType,
+        authMode: result.appliedModel?.provider
+          ? ctx.modelRegistry.getProviderAuthMode(result.appliedModel.provider)
+          : ctx.model?.provider
+            ? ctx.modelRegistry.getProviderAuthMode(ctx.model.provider)
+            : undefined,
+        baseUrl: result.appliedModel?.baseUrl ?? ctx.model?.baseUrl,
+      },
+    );
+    if (compatibilityError) {
+      ctx.ui.notify(compatibilityError, "error");
+      return;
+    }
   }
 
   // Scope tools for discuss flows (#2949).
@@ -1298,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.";
+}

package/src/resources/extensions/gsd/mcp-project-config.ts

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assertSafeDirectory } from "./validate-directory.js";
+import { detectWorkflowMcpLaunchConfig } from "./workflow-mcp.js";
+
+export const GSD_WORKFLOW_MCP_SERVER_NAME = "gsd-workflow";
+
+export interface ProjectMcpServerConfig {
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  url?: string;
+}
+
+export interface EnsureProjectWorkflowMcpConfigResult {
+  configPath: string;
+  serverName: string;
+  status: "created" | "updated" | "unchanged";
+}
+
+interface McpConfigFile {
+  mcpServers?: Record<string, ProjectMcpServerConfig>;
+  servers?: Record<string, ProjectMcpServerConfig>;
+  [key: string]: unknown;
+}
+
+export function resolveBundledGsdCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
+  const explicit = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim();
+  if (explicit) return explicit;
+
+  const candidates = [
+    resolve(fileURLToPath(new URL("../../../../scripts/dev-cli.js", import.meta.url))),
+    resolve(fileURLToPath(new URL("../../../../dist/loader.js", import.meta.url))),
+    resolve(fileURLToPath(new URL("../../../loader.js", import.meta.url))),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+export function buildProjectWorkflowMcpServerConfig(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): ProjectMcpServerConfig {
+  const resolvedProjectRoot = resolve(projectRoot);
+  const gsdCliPath = resolveBundledGsdCliPath(env);
+  const launch = detectWorkflowMcpLaunchConfig(resolvedProjectRoot, {
+    ...env,
+    ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath, GSD_BIN_PATH: gsdCliPath } : {}),
+  });
+
+  if (!launch) {
+    throw new Error(
+      "Unable to resolve the GSD workflow MCP server. Build this checkout or install gsd-mcp-server on PATH.",
+    );
+  }
+
+  return {
+    command: launch.command,
+    ...(launch.args && launch.args.length > 0 ? { args: launch.args } : {}),
+    ...(launch.cwd ? { cwd: launch.cwd } : {}),
+    ...(launch.env ? { env: launch.env } : {}),
+  };
+}
+
+function readExistingConfig(configPath: string): McpConfigFile {
+  if (!existsSync(configPath)) return {};
+
+  const raw = readFileSync(configPath, "utf-8");
+  try {
+    const parsed = JSON.parse(raw) as McpConfigFile;
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch (err) {
+    throw new Error(
+      `Failed to parse ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+export function ensureProjectWorkflowMcpConfig(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): EnsureProjectWorkflowMcpConfigResult {
+  const resolvedProjectRoot = resolve(projectRoot);
+  assertSafeDirectory(resolvedProjectRoot);
+
+  const configPath = resolve(resolvedProjectRoot, ".mcp.json");
+  const existing = readExistingConfig(configPath);
+  const desiredServer = buildProjectWorkflowMcpServerConfig(resolvedProjectRoot, env);
+  const previousServers = existing.mcpServers ?? {};
+  const nextServers = {
+    ...previousServers,
+    [GSD_WORKFLOW_MCP_SERVER_NAME]: desiredServer,
+  };
+
+  const alreadyPresent = existsSync(configPath);
+  const unchanged =
+    JSON.stringify(previousServers[GSD_WORKFLOW_MCP_SERVER_NAME] ?? null)
+      === JSON.stringify(desiredServer)
+    && existing.mcpServers !== undefined;
+
+  if (unchanged) {
+    return {
+      configPath,
+      serverName: GSD_WORKFLOW_MCP_SERVER_NAME,
+      status: "unchanged",
+    };
+  }
+
+  const nextConfig: McpConfigFile = {
+    ...existing,
+    mcpServers: nextServers,
+  };
+
+  writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf-8");
+
+  return {
+    configPath,
+    serverName: GSD_WORKFLOW_MCP_SERVER_NAME,
+    status: alreadyPresent ? "updated" : "created",
+  };
+}

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

@@ -47,6 +47,7 @@ import { extractVerdict } from './verdict-parser.js';
 
 import {
   isDbAvailable,
+  wasDbOpenAttempted,
   getAllMilestones,
   getMilestone,
   getMilestoneSlices,
@@ -271,7 +272,12 @@ export async function deriveState(basePath: string): Promise<GSDState> {
       _telemetry.markdownDeriveCount++;
     }
   } else {
-    logWarning("state", "DB unavailable — using filesystem state derivation (degraded mode)");
+    // Only warn when DB initialization was attempted and failed — not when
+    // the DB simply hasn't been opened yet (e.g. during before_agent_start
+    // context injection which runs before any tool invocation opens the DB).
+    if (wasDbOpenAttempted()) {
+      logWarning("state", "DB unavailable — using filesystem state derivation (degraded mode)");
+    }
     result = await _deriveStateImpl(basePath);
     _telemetry.markdownDeriveCount++;
   }

package/src/resources/extensions/gsd/tests/auto-project-root-env.test.ts

@@ -0,0 +1,29 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const sourcePath = join(import.meta.dirname, "..", "auto.ts");
+const source = readFileSync(sourcePath, "utf-8");
+
+test("auto-mode captures GSD_PROJECT_ROOT before entering the dispatch loop", () => {
+  const captureDeclIdx = source.indexOf("function captureProjectRootEnv(projectRoot: string): void {");
+  assert.ok(captureDeclIdx > -1, "auto.ts should define captureProjectRootEnv()");
+
+  const resumeCallIdx = source.indexOf("captureProjectRootEnv(s.originalBasePath || s.basePath);");
+  assert.ok(resumeCallIdx > -1, "auto.ts should capture GSD_PROJECT_ROOT before resume autoLoop");
+
+  const firstAutoLoopIdx = source.indexOf("await autoLoop(ctx, pi, s, buildLoopDeps());");
+  assert.ok(firstAutoLoopIdx > -1, "auto.ts should invoke autoLoop()");
+  assert.ok(
+    resumeCallIdx < firstAutoLoopIdx,
+    "auto.ts must set GSD_PROJECT_ROOT before the first autoLoop() call",
+  );
+});
+
+test("auto-mode restores GSD_PROJECT_ROOT when execution stops or pauses", () => {
+  assert.match(source, /function restoreProjectRootEnv\(\): void \{/);
+  assert.match(source, /cleanupAfterLoopExit\(ctx: ExtensionContext\): void \{[\s\S]*restoreProjectRootEnv\(\);/);
+  assert.match(source, /export async function pauseAuto\([\s\S]*restoreProjectRootEnv\(\);/);
+  assert.match(source, /\} finally \{[\s\S]*restoreProjectRootEnv\(\);[\s\S]*s\.reset\(\);/);
+});