gsd-pi 2.78.1-dev.e9d88a536 → 2.78.1-dev.eccf86e27

package/src/resources/extensions/gsd/db-writer.ts

@@ -8,7 +8,7 @@
 // Critical invariant: generated markdown must round-trip through
 // parseDecisionsTable() and parseRequirementsSections() with field fidelity.
 
-import { join, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import type { Decision, Requirement } from './types.js';
 import { resolveGsdRootFile } from './paths.js';
@@ -18,6 +18,8 @@ import { logWarning, logError } from './workflow-logger.js';
 import { invalidateStateCache } from './state.js';
 import { clearPathCache } from './paths.js';
 import { clearParseCache } from './files.js';
+import type { MilestoneScope, GsdWorkspace } from './workspace.js';
+import { createWorkspace, scopeMilestone } from './workspace.js';
 
 // ─── Freeform Detection ───────────────────────────────────────────────────
 
@@ -715,28 +717,104 @@ export interface SaveArtifactOpts {
 }
 
 /**
- * Save an artifact to DB and write the corresponding markdown file to disk.
+ * Save a root-level artifact (no milestone) to DB and write to disk,
+ * routing path construction through workspace.contract.projectGsd directly.
+ * Use this instead of saveArtifactToDbByScope when milestone_id is absent.
+ */
+export async function saveArtifactToDbForWorkspace(
+  workspace: GsdWorkspace,
+  opts: SaveArtifactOpts,
+): Promise<void> {
+  try {
+    const db = await import('./gsd-db.js');
+
+    const gsdDir = workspace.contract.projectGsd;
+    const fullPath = resolve(gsdDir, opts.path);
+
+    const rel0 = relative(gsdDir, fullPath);
+    if (rel0.startsWith('..') || isAbsolute(rel0)) {
+      throw new GSDError(GSD_IO_ERROR, `saveArtifactToDbForWorkspace: path escapes .gsd/ directory: ${opts.path}`);
+    }
+
+    let contentToPersist = opts.content;
+    if (opts.artifact_type === 'REQUIREMENTS' && opts.path === 'REQUIREMENTS.md') {
+      const activeRequirements = db.getActiveRequirements();
+      if (activeRequirements.length === 0) {
+        throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDbForWorkspace: REQUIREMENTS final save requires active DB-backed requirements');
+      }
+      contentToPersist = generateRequirementsMd(activeRequirements);
+    }
+
+    let skipDiskWrite = false;
+    if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
+      const existingSize = statSync(fullPath).size;
+      const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
+      if (existingSize > 0 && newSize < existingSize * 0.5) {
+        logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDbForWorkspace', path: opts.path });
+        skipDiskWrite = true;
+      }
+    }
+
+    db.insertArtifact({
+      path: opts.path,
+      artifact_type: opts.artifact_type,
+      milestone_id: null,
+      slice_id: null,
+      task_id: null,
+      full_content: contentToPersist,
+    });
+
+    if (!skipDiskWrite) {
+      try {
+        await saveFile(fullPath, contentToPersist);
+      } catch (diskErr) {
+        logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDbForWorkspace', path: opts.path, error: String((diskErr as Error).message) });
+      }
+    }
+    invalidateStateCache();
+    clearPathCache();
+    clearParseCache();
+  } catch (err) {
+    logError('manifest', 'saveArtifactToDbForWorkspace failed', { fn: 'saveArtifactToDbForWorkspace', error: String((err as Error).message) });
+    throw err;
+  }
+}
+
+/**
+ * Save an artifact to DB and write the corresponding markdown file to disk,
+ * routing all path construction through the workspace contract.
+ *
  * The path is relative to .gsd/ (e.g. "milestones/M001/slices/S06/tasks/T01-SUMMARY.md").
- * The full file path is computed as basePath + '.gsd/' + path.
+ * The full file path is computed as scope.workspace.contract.projectGsd + '/' + path.
  */
-export async function saveArtifactToDb(
+export async function saveArtifactToDbByScope(
+  scope: MilestoneScope,
   opts: SaveArtifactOpts,
-  basePath: string,
 ): Promise<void> {
+  // Guard: an empty milestoneId produces malformed paths (milestoneDir = join(gsd, "milestones", "")).
+  // Callers that have no milestone should use saveArtifactToDbForWorkspace instead.
+  if (!scope.milestoneId) {
+    throw new GSDError(GSD_IO_ERROR, `saveArtifactToDbByScope: milestoneId is empty — use saveArtifactToDbForWorkspace for root artifacts`);
+  }
+
   try {
     const db = await import('./gsd-db.js');
 
+    // Use contract.projectGsd as the canonical .gsd directory — never a hand-rolled basePath join.
+    const gsdDir = scope.workspace.contract.projectGsd;
+    const fullPath = resolve(gsdDir, opts.path);
+
     // Guard against path traversal before any reads/writes
-    const gsdDir = resolve(basePath, '.gsd');
-    const fullPath = resolve(basePath, '.gsd', opts.path);
-    if (!fullPath.startsWith(gsdDir)) {
-      throw new GSDError(GSD_IO_ERROR, `saveArtifactToDb: path escapes .gsd/ directory: ${opts.path}`);
+    const rel1 = relative(gsdDir, fullPath);
+    if (rel1.startsWith('..') || isAbsolute(rel1)) {
+      throw new GSDError(GSD_IO_ERROR, `saveArtifactToDbByScope: path escapes .gsd/ directory: ${opts.path}`);
     }
+
     let contentToPersist = opts.content;
     if (opts.artifact_type === 'REQUIREMENTS' && opts.path === 'REQUIREMENTS.md') {
       const activeRequirements = db.getActiveRequirements();
       if (activeRequirements.length === 0) {
-        throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDb: REQUIREMENTS final save requires active DB-backed requirements');
+        throw new GSDError(GSD_STALE_STATE, 'saveArtifactToDbByScope: REQUIREMENTS final save requires active DB-backed requirements');
       }
       contentToPersist = generateRequirementsMd(activeRequirements);
     }
@@ -744,16 +822,13 @@ export async function saveArtifactToDb(
     // Shrinkage guard: if the projection file already exists and the new
     // content is significantly smaller (<50%), preserve the richer file on
     // disk, but keep the DB row authoritative with the caller-provided content.
-    // The disk file is a stale projection until the next explicit render.
-    // Root canonical artifacts are exempt because their content is rendered
-    // from canonical DB state, and cleanup/consolidation is often intentionally
-    // much smaller than a malformed accumulated file.
+    // Root canonical artifacts are exempt (rendered from canonical DB state).
     let skipDiskWrite = false;
     if (!isRootCanonicalArtifact(opts) && existsSync(fullPath)) {
       const existingSize = statSync(fullPath).size;
       const newSize = Buffer.byteLength(contentToPersist, 'utf-8');
       if (existingSize > 0 && newSize < existingSize * 0.5) {
-        logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDb', path: opts.path });
+        logWarning('projection', `new content (${newSize}B) is <50% of existing projection (${existingSize}B), preserving disk file while DB remains authoritative`, { fn: 'saveArtifactToDbByScope', path: opts.path });
         skipDiskWrite = true;
       }
     }
@@ -772,7 +847,7 @@ export async function saveArtifactToDb(
       try {
         await saveFile(fullPath, contentToPersist);
       } catch (diskErr) {
-        logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDb', path: opts.path, error: String((diskErr as Error).message) });
+        logWarning('projection', 'artifact projection write failed; DB artifact remains committed', { fn: 'saveArtifactToDbByScope', path: opts.path, error: String((diskErr as Error).message) });
       }
     }
     // Invalidate file-read caches so deriveState() sees the updated markdown.
@@ -781,7 +856,28 @@ export async function saveArtifactToDb(
     clearPathCache();
     clearParseCache();
   } catch (err) {
-    logError('manifest', 'saveArtifactToDb failed', { fn: 'saveArtifactToDb', error: String((err as Error).message) });
+    logError('manifest', 'saveArtifactToDbByScope failed', { fn: 'saveArtifactToDbByScope', error: String((err as Error).message) });
     throw err;
   }
 }
+
+/**
+ * Save an artifact to DB and write the corresponding markdown file to disk.
+ * The path is relative to .gsd/ (e.g. "milestones/M001/slices/S06/tasks/T01-SUMMARY.md").
+ * The full file path is computed as basePath + '.gsd/' + path.
+ *
+ * @deprecated Use saveArtifactToDbByScope instead, which routes through the
+ * workspace contract for canonical path resolution.
+ * TODO(C-future): remove this legacy wrapper once all callers are migrated.
+ */
+export async function saveArtifactToDb(
+  opts: SaveArtifactOpts,
+  basePath: string,
+): Promise<void> {
+  const workspace = createWorkspace(basePath);
+  const milestoneId = opts.milestone_id;
+  if (milestoneId) {
+    return saveArtifactToDbByScope(scopeMilestone(workspace, milestoneId), opts);
+  }
+  return saveArtifactToDbForWorkspace(workspace, opts);
+}

package/src/resources/extensions/gsd/delegation-policy.ts

@@ -0,0 +1,197 @@
+// Delegation policy — codifies which GSD MCP tools are safe to run as
+// background sub-agents while the foreground /gsd flow continues. Verdicts
+// are derived from the round-1 and round-2 evaluations recorded in this
+// branch's PR description; the rationale field on each entry preserves
+// the reason so future changes have to revisit the analysis explicitly.
+//
+// Default-deny: unknown tools are never backgroundable.
+//
+// ─── Tool-name vs unit-type namespaces ───────────────────────────────────
+// Entries are keyed by canonical MCP tool name (`gsd_*`). The optional
+// `unitType` field is a *secondary* index for the dispatcher's convenience
+// — it bridges this policy to `auto-dispatch.ts`' `DispatchAction.unitType`
+// values. The two namespaces are not 1:1:
+//
+//   - Some tools have no corresponding unit type (e.g. `gsd_doctor`,
+//     `gsd_plan_task`) and intentionally omit `unitType`.
+//   - Some unit types share a tool — e.g. `execute-task`, `execute-task-simple`,
+//     and `reactive-execute` all invoke `gsd_execute`. The current shape
+//     allows only one `unitType` per entry, so those units fall through to
+//     `getVerdictByUnitType() === null` (→ `backgroundable: false`) even
+//     though `gsd_execute` itself is GOOD. This is the intended default-deny
+//     posture until a future PR wires actual background dispatch and
+//     decides whether each unit-level orchestration is safe — the unit
+//     wraps a prompt, harness setup, and post-processing on top of the
+//     tool, and the tool's safety doesn't transfer automatically.
+//
+// Auto-dispatch produces 20 distinct unit types; only 5 are explicitly
+// classified here. The other 15 default-deny:
+//   complete-milestone, complete-slice, discuss-milestone, discuss-project,
+//   discuss-requirements, execute-task, execute-task-simple, gate-evaluate,
+//   reactive-execute, refine-slice, research-decision, research-milestone,
+//   research-project, research-slice, rewrite-docs, run-uat
+//
+// Adding a `unitType` mapping (or a future `unitTypes: string[]`) to an
+// existing entry is the place to lift any of these out of default-deny
+// when the analysis has been done.
+
+export type BackgroundabilityVerdict = "good" | "risky" | "no";
+
+export interface DelegationPolicyEntry {
+  /** Canonical MCP tool name (the verb_object form, e.g. `gsd_plan_slice`). */
+  toolName: string;
+  /** Workflow unit type from auto-dispatch.ts, when one exists. */
+  unitType?: string;
+  verdict: BackgroundabilityVerdict;
+  /** One-line justification grounded in the evaluation findings. */
+  rationale: string;
+  /**
+   * Constraints the caller MUST satisfy when dispatching this unit in the
+   * background. Only populated for `good` and conditional `risky` entries.
+   */
+  constraints?: string[];
+}
+
+const POLICY: Record<string, DelegationPolicyEntry> = {
+  gsd_plan_slice: {
+    toolName: "gsd_plan_slice",
+    unitType: "plan-slice",
+    verdict: "good",
+    rationale:
+      "Self-contained, no user prompts, atomic DB tx; existing slice-parallel-orchestrator pattern transfers cleanly.",
+    constraints: [
+      "Lock the slice from further user discussion once dispatched (context is frozen at dispatch time).",
+      "Foreground must not derive state for that slice while the transaction is in flight.",
+      "Foreground must await background completion before any tool reads the planned tasks/gates.",
+    ],
+  },
+  gsd_execute: {
+    toolName: "gsd_execute",
+    // No `unitType` set on purpose — the underlying tool is safe, but the
+    // unit-level orchestrations that invoke it (`execute-task`,
+    // `execute-task-simple`, `reactive-execute`) wrap additional prompt and
+    // harness work whose safety is a separate analysis. Default-deny those
+    // units until that analysis is recorded; adding `unitType` here would
+    // promote them silently.
+    verdict: "good",
+    rationale:
+      "No DB writes; UUID-isolated stdout/stderr/meta files; existing reactive-execute parallel-subagent precedent.",
+  },
+  gsd_validate_milestone: {
+    toolName: "gsd_validate_milestone",
+    unitType: "validate-milestone",
+    verdict: "good",
+    rationale:
+      "Verdict pre-computed by parallel reviewers; atomic DB tx plus isolated VALIDATION.md write; no user interaction.",
+  },
+  gsd_reassess_roadmap: {
+    toolName: "gsd_reassess_roadmap",
+    unitType: "reassess-roadmap",
+    verdict: "good",
+    rationale:
+      "Narrower mutation scope than plan_milestone; structural guards prevent modification of completed slices.",
+  },
+  gsd_doctor: {
+    toolName: "gsd_doctor",
+    verdict: "risky",
+    rationale:
+      "Diagnostic-only mode (fix=false) is safe to background; fix=true writes STATE.md/ROADMAP.md without session-lock coordination and can race the foreground flow.",
+    constraints: [
+      "Background only with fix=false (diagnostic-only).",
+      "Apply fixes synchronously, only when no foreground unit is dispatched.",
+    ],
+  },
+  gsd_plan_milestone: {
+    toolName: "gsd_plan_milestone",
+    unitType: "plan-milestone",
+    verdict: "risky",
+    rationale:
+      "Inputs require CONTEXT.md from discuss-milestone, so initial questioning is already done by the time it can start; TOCTOU guards and projection coherence make concurrency unsafe.",
+  },
+  gsd_replan_slice: {
+    toolName: "gsd_replan_slice",
+    unitType: "replan-slice",
+    verdict: "risky",
+    rationale:
+      "Blocks the replanning→executing state transition on a gate that waits for S##-REPLAN.md; background failure leaves the flow stuck.",
+  },
+  gsd_plan_task: {
+    toolName: "gsd_plan_task",
+    verdict: "no",
+    rationale:
+      "plan-slice prompt explicitly forbids calling gsd_plan_task separately; per-task granularity multiplies manifest writes and projection re-renders with no payoff.",
+  },
+};
+
+// Alias map keyed on the secondary name; resolves to the canonical entry above.
+// Sourced from packages/mcp-server/src/workflow-tools.ts alias registrations
+// (gsd_milestone_validate, gsd_roadmap_reassess, gsd_slice_replan, gsd_task_plan).
+const ALIASES: Record<string, string> = {
+  gsd_milestone_validate: "gsd_validate_milestone",
+  gsd_roadmap_reassess: "gsd_reassess_roadmap",
+  gsd_slice_replan: "gsd_replan_slice",
+  gsd_task_plan: "gsd_plan_task",
+};
+
+function resolveCanonical(name: string): string {
+  return ALIASES[name] ?? name;
+}
+
+export function getDelegationVerdict(toolName: string): DelegationPolicyEntry | null {
+  return POLICY[resolveCanonical(toolName)] ?? null;
+}
+
+export function isBackgroundable(toolName: string): boolean {
+  const entry = getDelegationVerdict(toolName);
+  return entry?.verdict === "good";
+}
+
+export function listBackgroundableTools(): string[] {
+  return Object.values(POLICY)
+    .filter((entry) => entry.verdict === "good")
+    .map((entry) => entry.toolName)
+    .sort();
+}
+
+export function getVerdictByUnitType(unitType: string): DelegationPolicyEntry | null {
+  for (const entry of Object.values(POLICY)) {
+    if (entry.unitType === unitType) return entry;
+  }
+  return null;
+}
+
+/**
+ * Minimal shape of a dispatch action that the annotator needs to operate on.
+ * Matches the `dispatch` and non-dispatch variants of auto-dispatch.ts'
+ * DispatchAction without depending on it (so this module stays free of
+ * workspace-package transitive imports).
+ */
+export type AnnotatableDispatchAction =
+  | { action: "dispatch"; unitType: string; backgroundable?: boolean; [k: string]: unknown }
+  | { action: "stop"; [k: string]: unknown }
+  | { action: "skip"; [k: string]: unknown };
+
+/**
+ * Annotates a dispatch action in place with `backgroundable: true` when its
+ * unitType has a `good` verdict in the policy. Stop/skip actions pass through
+ * unchanged. Default-deny: unknown unit types resolve to `false`.
+ *
+ * **Mutation contract.** The `backgroundable` field is written directly onto
+ * the passed action object. This is intentional — every dispatch path in
+ * `auto-dispatch.ts` constructs a fresh action object per `where(ctx)` /
+ * `evaluateDispatch(ctx)` invocation, so in-place mutation cannot leak across
+ * dispatch cycles. Future dispatch rules MUST follow that convention: never
+ * cache or share `DispatchAction` objects across calls. If you need to cache,
+ * either freeze the cached object (`Object.freeze`) and clone on read, or
+ * stop calling `annotateBackgroundable` on the shared instance. The annotator
+ * always recomputes from the policy on every call (no internal cache), so
+ * repeated invocations on the same object will overwrite stale values
+ * deterministically — see the `annotateBackgroundable recomputes on each call`
+ * test for the contract pin.
+ */
+export function annotateBackgroundable<T extends AnnotatableDispatchAction>(action: T): T {
+  if (action.action !== "dispatch") return action;
+  const verdict = getVerdictByUnitType(action.unitType);
+  action.backgroundable = verdict?.verdict === "good";
+  return action;
+}

package/src/resources/extensions/gsd/docs/COORDINATION.md

@@ -0,0 +1,42 @@
+# Auto-mode coordination is single-host
+
+The DB-backed coordination tables introduced by Phase B (`workers`,
+`milestone_leases`, `unit_dispatches`, `cancellation_requests`,
+`command_queue`) and the supporting `runtime_kv` table from Phase C all
+rely on **shared SQLite WAL on local disk**. They do not work across
+machines.
+
+## Why single-host only
+
+- SQLite WAL coordination — the locking primitives that make
+  `claimMilestoneLease`, `recordDispatchClaim`, and `claimNextCommand`
+  atomic — is local-disk only. Network filesystems (NFS, SMB, S3FS) and
+  fuse mounts break the lock semantics that the WAL relies on.
+- Heartbeat TTL (`workers.last_heartbeat_at`) compares timestamps written
+  with SQLite wall-clock time (`datetime('now')`). Across machines without
+  wall-clock synchronization (for example NTP/chrony), TTL filtering can
+  produce phantom-active or premature-crashed verdicts. Monotonic clocks
+  are not used for these comparisons.
+- Fencing tokens (`milestone_leases.fencing_token`) are monotonically
+  ordered by SQL within a single transaction. Cross-host races could
+  produce duplicate tokens if two SQLite processes opened the same DB
+  on a network mount.
+
+## What does work
+
+- Multiple `gsd auto` worker processes on the **same machine**, sharing
+  the project's SQLite DB via WAL. The lease check refuses concurrent
+  claims on the same milestone; the dispatch ledger's partial unique
+  index refuses double-claims of the same unit.
+- A single `gsd auto` worker plus arbitrary read-only consumers
+  (dashboards, doctors) on the same machine.
+- Worktree-based parallelism on the same machine, where each worker
+  holds a different milestone lease.
+
+## Multi-host alternatives
+
+If you need to coordinate `gsd auto` workers across machines, you need
+a real coordinator: Postgres for the ledger + a leader-election service
+(etcd, Consul) for the leases. That's out of scope for these phases.
+The schema and module shapes here would need a non-trivial backend
+swap before they could ride on top of either.

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

@@ -25,6 +25,7 @@ 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";
+import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 
 // ── Health Score Tracking ──────────────────────────────────────────────────
 
@@ -219,6 +220,9 @@ export async function preDispatchHealthGate(basePath: string): Promise<PreDispat
   // If a stale lock exists, the crash recovery path should handle it,
   // not a new dispatch. This prevents double-dispatch after crashes.
   try {
+    if (existsSync(join(gsdRoot(basePath), "gsd.db"))) {
+      await ensureDbOpen(basePath);
+    }
     const lock = readCrashLock(basePath);
     if (lock && !isLockProcessAlive(lock)) {
       // Auto-clear it since we're about to dispatch anyway

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

@@ -8,6 +8,8 @@ import { deriveState, isGhostMilestone, isReusableGhostMilestone } from "./state
 import { saveFile } from "./files.js";
 import { nativeIsRepo, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
+import { getActiveAutoWorkers } from "./db/auto-workers.js";
+import { normalizeRealPath } from "./paths.js";
 import { ensureGitignore, isGsdGitignored } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
 import { recoverFailedMigration } from "./migrate-external.js";
@@ -35,6 +37,9 @@ export async function checkRuntimeHealth(
   const root = gsdRoot(basePath);
 
   // ── Stale crash lock ──────────────────────────────────────────────────
+  // Phase C pt 2: the lock state lives in the workers + unit_dispatches
+  // tables now, not auto.lock. readCrashLock synthesizes a LockData from
+  // the DB; isLockProcessAlive is a pure OS PID check.
   try {
     const lock = readCrashLock(basePath);
     if (lock) {
@@ -45,14 +50,14 @@ export async function checkRuntimeHealth(
           code: "stale_crash_lock",
           scope: "project",
           unitId: "project",
-          message: `Stale auto.lock from PID ${lock.pid} (started ${lock.startedAt}, was executing ${lock.unitType} ${lock.unitId}) — process is no longer running`,
-          file: ".gsd/auto.lock",
+          message: `Stale auto-mode worker (PID ${lock.pid}, started ${lock.startedAt}, was executing ${lock.unitType} ${lock.unitId}) — process is no longer running`,
+          file: "<workers table>",
           fixable: true,
         });
 
         if (shouldFix("stale_crash_lock")) {
           clearLock(basePath);
-          fixesApplied.push("cleared stale auto.lock");
+          fixesApplied.push("cleared stale auto-mode worker state");
         }
       }
     }
@@ -70,9 +75,22 @@ export async function checkRuntimeHealth(
     if (existsSync(lockDir)) {
       const statRes = statSync(lockDir);
       if (statRes.isDirectory()) {
-        // Check if any live process actually holds this lock
-        const lock = readCrashLock(basePath);
-        const lockHolderAlive = lock ? isLockProcessAlive(lock) : false;
+        // Phase C pt 2: "any live process holds the lock?" check now means
+        // "is any worker registered with status='active' AND a fresh
+        // heartbeat for this project?" — readCrashLock returns null for
+        // healthy live workers (it surfaces stale ones only), so we must
+        // consult getActiveAutoWorkers directly.
+        const projectRoot = normalizeRealPath(basePath);
+        const activeWorkers = getActiveAutoWorkers().filter(
+          (w) => w.project_root_realpath === projectRoot && isLockProcessAlive({
+            pid: w.pid,
+            startedAt: w.started_at,
+            unitType: "starting",
+            unitId: "bootstrap",
+            unitStartedAt: w.started_at,
+          }),
+        );
+        const lockHolderAlive = activeWorkers.length > 0;
         if (!lockHolderAlive) {
           issues.push({
             severity: "error",

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

@@ -3,8 +3,8 @@ import { join } from "node:path";
 
 import { loadFile, parseSummary, saveFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap, parsePlan as parseLegacyPlan } from "./parsers-legacy.js";
-import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath } from "./paths.js";
+import { isDbAvailable, openDatabase, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTasksDir, milestonesDir, gsdRoot, relMilestoneFile, relSliceFile, relTaskFile, relSlicePath, relGsdRootFile, resolveGsdRootFile, relMilestonePath, resolveGsdPathContract } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { loadEffectiveGSDPreferences, type GSDPreferences } from "./preferences.js";
@@ -336,6 +336,14 @@ export async function runGSDDoctor(basePath: string, options?: { fix?: boolean;
   const dryRun = options?.dryRun === true;
   const fixLevel = options?.fixLevel ?? "all";
 
+  // CLI doctor can run before any tool handler has opened the DB. Runtime
+  // health checks need the existing project DB to surface DB-backed crash
+  // locks, paused sessions, and coordination rows.
+  const dbPath = resolveGsdPathContract(basePath).projectDb;
+  if (existsSync(dbPath)) {
+    try { openDatabase(dbPath); } catch { /* surfaced later as db_unavailable */ }
+  }
+
   // Issue codes that represent completion state transitions — creating summary
   // stubs, marking slices/milestones done in the roadmap. These belong to the
   // dispatch lifecycle (complete-slice, complete-milestone units), not to