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

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

@@ -11,7 +11,8 @@
  */
 import { deriveState } from "./state.js";
 import { parseUnitId } from "./unit-id.js";
-import { assessInterruptedSession, readPausedSessionMetadata, } from "./interrupted-session.js";
+import { assessInterruptedSession, readPausedSessionMetadata, PAUSED_SESSION_KV_KEY, } from "./interrupted-session.js";
+import { setRuntimeKv, deleteRuntimeKv, } from "./db/runtime-kv.js";
 import { getManifestStatus } from "./files.js";
 export { inlinePriorMilestoneSummary } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
@@ -40,7 +41,7 @@ import { setLogBasePath, logWarning } from "./workflow-logger.js";
 import { preflightCleanRoot, postflightPopStash } from "./clean-root-preflight.js";
 import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
-import { readFileSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
@@ -87,6 +88,9 @@ export { STUB_RECOVERY_THRESHOLD, NEW_SESSION_TIMEOUT_MS, } from "./auto/session
 import { autoSession as s } from "./auto-runtime-state.js";
 import { gsdHome } from "./gsd-home.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
+import { registerAutoWorker, markWorkerStopping } from "./db/auto-workers.js";
+import { releaseMilestoneLease } from "./db/milestone-leases.js";
+import { normalizeRealPath } from "./paths.js";
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
 // This file must NOT declare module-level `let` or `var` variables for state.
@@ -101,6 +105,27 @@ import { createWorkspace, scopeMilestone } from "./workspace.js";
 // ─────────────────────────────────────────────────────────────────────────────
 /** Throttle STATE.md rebuilds — at most once per 30 seconds */
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
+/**
+ * Phase B — register this auto-mode process in the workers table so other
+ * workers and janitors can detect liveness via heartbeat. Best-effort: if
+ * the DB is unavailable (e.g. fresh project before init) we skip registration
+ * silently rather than blocking session start.
+ */
+function registerAutoWorkerForSession(session) {
+    if (session.workerId)
+        return; // already registered (e.g. resume re-runs)
+    try {
+        const projectRootRealpath = normalizeRealPath(session.scope?.workspace.projectRoot
+            ?? (session.originalBasePath || session.basePath));
+        session.workerId = registerAutoWorker({ projectRootRealpath });
+    }
+    catch (err) {
+        debugLog("autoLoop", {
+            phase: "register-worker-failed",
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
 function captureProjectRootEnv(projectRoot) {
     if (!s.projectRootEnvCaptured) {
         s.hadProjectRootEnv = Object.prototype.hasOwnProperty.call(process.env, "GSD_PROJECT_ROOT");
@@ -621,6 +646,21 @@ export async function stopAuto(ctx, pi, reason) {
         catch (e) {
             debugLog("stop-cleanup-locks", { error: e instanceof Error ? e.message : String(e) });
         }
+        // ── Step 1b: Coordination cleanup (Phase B) ──
+        // Release any active milestone lease so other workers don't have to
+        // wait for TTL expiry, then mark this worker as stopping. Best-effort:
+        // DB unavailability or stale state must not block shutdown.
+        try {
+            if (s.workerId && s.currentMilestoneId && s.milestoneLeaseToken) {
+                releaseMilestoneLease(s.workerId, s.currentMilestoneId, s.milestoneLeaseToken);
+            }
+            if (s.workerId) {
+                markWorkerStopping(s.workerId);
+            }
+        }
+        catch (e) {
+            debugLog("stop-cleanup-coordination", { error: e instanceof Error ? e.message : String(e) });
+        }
         // ── Step 1b: Flush queued follow-up messages (#3512) ──
         // Late async notifications (async_job_result, gsd-auto-wrapup) can trigger
         // extra LLM turns after stop. Flush them the same way run-unit.ts does.
@@ -799,13 +839,12 @@ export async function stopAuto(ctx, pi, reason) {
             debugLog("stop-cleanup-metrics", { error: e instanceof Error ? e.message : String(e) });
         }
         // ── Step 12: Remove paused-session metadata (#1383) ──
+        // Phase C pt 2: deleteRuntimeKv replaces unlinkSync(paused-session.json).
         try {
-            const pausedPath = join(gsdRoot(s.originalBasePath || s.basePath), "runtime", "paused-session.json");
-            if (existsSync(pausedPath))
-                unlinkSync(pausedPath);
+            deleteRuntimeKv("global", "", PAUSED_SESSION_KV_KEY);
         }
         catch (err) { /* non-fatal */
-            logWarning("engine", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+            logWarning("engine", `paused-session DB delete failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
         }
         // ── Step 13: Restore original model + thinking (before reset clears IDs) ──
         try {
@@ -897,10 +936,12 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
     resolveAgentEndCancelled(_errorContext);
     s.pausedSessionFile = normalizeSessionFilePath(ctx?.sessionManager?.getSessionFile() ?? null);
     // Persist paused-session metadata so resume survives /exit (#1383).
-    // The fresh-start bootstrap checks for this file and restores worktree context.
+    // Phase C pt 2: persisted to runtime_kv (global scope, key
+    // PAUSED_SESSION_KV_KEY) instead of runtime/paused-session.json. The
+    // fresh-start bootstrap below reads from the same key.
     try {
         const pausedMeta = {
-            milestoneId: s.currentMilestoneId,
+            milestoneId: s.currentMilestoneId ?? undefined,
             worktreePath: isInAutoWorktree(s.basePath) ? s.basePath : null,
             originalBasePath: s.originalBasePath,
             stepMode: s.stepMode,
@@ -908,17 +949,16 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
             sessionFile: s.pausedSessionFile,
             unitType: s.currentUnit?.type ?? undefined,
             unitId: s.currentUnit?.id ?? undefined,
-            activeEngineId: s.activeEngineId,
+            activeEngineId: s.activeEngineId ?? undefined,
             activeRunDir: s.activeRunDir,
             autoStartTime: s.autoStartTime,
             milestoneLock: s.sessionMilestoneLock ?? undefined,
         };
-        const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
-        atomicWriteSync(join(runtimeDir, "paused-session.json"), JSON.stringify(pausedMeta, null, 2), "utf-8");
+        setRuntimeKv("global", "", PAUSED_SESSION_KV_KEY, pausedMeta);
     }
     catch (err) {
         // Non-fatal — resume will still work via full bootstrap, just without worktree context
-        logWarning("engine", `paused-session file write failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+        logWarning("engine", `paused-session DB write failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
     // Close out the current unit so its runtime record doesn't stay at "dispatched"
     if (s.currentUnit && ctx) {
@@ -1154,8 +1194,10 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     if (recoverFailedMigration(base)) {
         ctx.ui.notify("Recovered unfinished migration (.gsd.migrating → .gsd).", "info");
     }
-    const freshStartAssessment = interruptedAssessment
-        ?? await assessInterruptedSession(base);
+    const freshStartAssessment = await (interruptedAssessment
+        ?? (() => {
+            return ensureDbOpen(base).then(() => assessInterruptedSession(base));
+        })());
     if (freshStartAssessment.classification === "running") {
         const pid = freshStartAssessment.lock?.pid;
         ctx.ui.notify(pid
@@ -1165,10 +1207,20 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     }
     // If resuming from paused state, just re-activate and dispatch next unit.
     // Check persisted paused-session first (#1383) — survives /exit.
+    // Phase C pt 2: persisted in runtime_kv (global scope) instead of
+    // runtime/paused-session.json. The `clearPausedSession` helper
+    // replaces every prior unlinkSync(pausedPath) call.
+    const clearPausedSession = (logTag) => {
+        try {
+            deleteRuntimeKv("global", "", PAUSED_SESSION_KV_KEY);
+        }
+        catch (err) {
+            logWarning("session", `${logTag}: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+        }
+    };
     if (!s.paused) {
         try {
             const meta = freshStartAssessment.pausedSession ?? readPausedSessionMetadata(base);
-            const pausedPath = join(gsdRoot(base), "runtime", "paused-session.json");
             if (meta?.activeEngineId && meta.activeEngineId !== "dev") {
                 // Custom workflow resume — restore engine state
                 s.activeEngineId = meta.activeEngineId;
@@ -1178,14 +1230,6 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
                 s.autoStartTime = meta.autoStartTime || Date.now();
                 s.sessionMilestoneLock = meta.milestoneLock ?? null;
                 s.paused = true;
-                try {
-                    unlinkSync(pausedPath);
-                }
-                catch (e) {
-                    if (e.code !== "ENOENT") {
-                        logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" });
-                    }
-                }
                 ctx.ui.notify(`Resuming paused custom workflow${meta.activeRunDir ? ` (${meta.activeRunDir})` : ""}.`, "info");
             }
             else if (meta?.milestoneId) {
@@ -1223,14 +1267,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
                         }
                     }
                     if (!mDir || summaryIsTerminal) {
-                        try {
-                            unlinkSync(pausedPath);
-                        }
-                        catch (err) {
-                            if (err.code !== "ENOENT") {
-                                logWarning("session", `pause file cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-                            }
-                        }
+                        clearPausedSession("paused-session DB cleanup failed (milestone gone/complete)");
                         ctx.ui.notify(`Paused milestone ${meta.milestoneId} is ${!mDir ? "missing" : "already complete"}. Starting fresh.`, "info");
                     }
                     else {
@@ -1255,26 +1292,13 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
                                 : (s.originalBasePath || base);
                             rebuildScope(rawForScope, s.currentMilestoneId);
                         }
-                        try {
-                            unlinkSync(pausedPath);
-                        }
-                        catch (e) {
-                            if (e.code !== "ENOENT") {
-                                logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" });
-                            }
-                        }
                         ctx.ui.notify(`Resuming paused session for ${meta.milestoneId}${meta.worktreePath && existsSync(meta.worktreePath) ? ` (worktree)` : ""}.`, "info");
                     }
                 }
-                else if (existsSync(pausedPath)) {
-                    try {
-                        unlinkSync(pausedPath);
-                    }
-                    catch (e) {
-                        if (e.code !== "ENOENT") {
-                            logWarning("session", `stale pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" });
-                        }
-                    }
+                else if (meta) {
+                    // Stale paused-session metadata that the assessment chose not to
+                    // resume — clean it up so the next bootstrap starts fresh.
+                    clearPausedSession("stale paused-session DB cleanup failed");
                 }
             }
         }
@@ -1425,10 +1449,14 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             }
             s.pausedSessionFile = null;
         }
+        captureProjectRootEnv(s.originalBasePath || s.basePath);
+        registerAutoWorkerForSession(s);
         updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
-        writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
+        if (s.workerId) {
+            writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
+            clearPausedSession("paused-session DB cleanup failed (resume activation)");
+        }
         pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", level: "progress" });
-        captureProjectRootEnv(s.originalBasePath || s.basePath);
         startAutoCommandPolling(s.basePath);
         await runAutoLoopWithUok({
             ctx,
@@ -1455,6 +1483,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     // s.currentMilestoneId (including worktree setup inside bootstrapAutoSession).
     rebuildScope(s.basePath, s.currentMilestoneId);
     captureProjectRootEnv(s.originalBasePath || s.basePath);
+    registerAutoWorkerForSession(s);
     try {
         pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync", preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, state: await deriveState(s.basePath) });
     }

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -515,8 +515,13 @@ export function registerHooks(pi, ecosystemHandlers) {
         const currentPendingGate = getPendingGate();
         if (currentPendingGate) {
             if (details?.cancelled || !details?.response) {
-                // Gate stays pending. Return a hard instruction as the tool result so
-                // the model cannot reinterpret a cancelled prompt as prior approval.
+                // Gate stays pending. Direct the agent to the most reliable recovery
+                // path — re-calling ask_user_questions with the same gate id — without
+                // misrepresenting the plain-text path. The plain-text path also works
+                // (isExplicitApprovalResponse on the next before_agent_start clears
+                // the gate when the user replies with an approval keyword), but the
+                // structured re-ask is more deterministic and gives the user a clear UI.
+                resetToolCallLoopGuard();
                 return {
                     content: [{
                             type: "text",
@@ -524,8 +529,8 @@ export function registerHooks(pi, ecosystemHandlers) {
                                 `HARD BLOCK: approval gate "${currentPendingGate}" is still pending.`,
                                 "No user response was received for the confirmation question.",
                                 "Do not infer approval from earlier or prior messages.",
-                                "Do not proceed, write files, save artifacts, or call more tools.",
-                                "Ask the user to confirm in plain chat, then stop and wait for their next message.",
+                                "Do not proceed, write files, save artifacts, or call other tools.",
+                                `Re-call ask_user_questions with the same gate question id ("${currentPendingGate}") and wait for the user's response.`,
                             ].join(" "),
                         }],
                 };

package/dist/resources/extensions/gsd/crash-recovery.js

@@ -1,24 +1,106 @@
 /**
- * GSD Crash Recovery
+ * GSD Crash Recovery (Phase C pt 2 — DB-backed)
  *
- * Detects interrupted auto-mode sessions via a lock file.
- * Written on auto-start, updated on each unit dispatch, deleted on clean stop.
- * If the lock file exists on next startup, the previous session crashed.
+ * Detects interrupted auto-mode sessions via the DB-backed workers +
+ * unit_dispatches + runtime_kv tables. The auto.lock file is gone; the
+ * `LockData` shape is preserved for backward compatibility with callers
+ * (auto.ts, doctor checks, interrupted-session.ts), but the contents are
+ * now synthesized from:
  *
- * The lock records the pi session file path so crash recovery can read the
- * surviving JSONL (pi appends entries incrementally via appendFileSync,
- * so the file on disk reflects every tool call up to the crash point).
+ *   - workers.pid / .started_at / .last_heartbeat_at  → liveness + age
+ *   - unit_dispatches.unit_type / .unit_id / .started_at  → what was running
+ *   - runtime_kv("worker", workerId, "session_file")  → pi session JSONL path
+ *
+ * "Crashed" is detected via workers.status='active' + heartbeat past TTL,
+ * cross-checked with the OS PID via isLockProcessAlive(). When the DB is
+ * unavailable (fresh project before init), all readers return null and
+ * writers no-op — preserving the historical "no lock means no prior
+ * crash" semantics.
+ *
+ * The journal-based emitCrashRecoveredUnitEnd is unchanged from the file
+ * era — it queries the journal independently of the lock mechanism.
  */
+import { emitJournalEvent, queryJournal, } from "./journal.js";
 import { readFileSync, unlinkSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { gsdRoot } from "./paths.js";
+import { findStaleWorkerForProject, getAllAutoWorkers, } from "./db/auto-workers.js";
+import { getRuntimeKv, setRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
+import { _getAdapter, isDbAvailable } from "./gsd-db.js";
+import { gsdRoot, normalizeRealPath } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { effectiveLockFile } from "./session-lock.js";
-import { emitJournalEvent, queryJournal } from "./journal.js";
+const SESSION_FILE_KV_KEY = "session_file";
 function lockPath(basePath) {
     return join(gsdRoot(basePath), effectiveLockFile());
 }
-/** Write or update the lock file with current auto-mode state. */
+function readLegacyLock(basePath) {
+    try {
+        const p = lockPath(basePath);
+        if (!existsSync(p))
+            return null;
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function findActiveWorkerForCurrentProcess(projectRootRealpath) {
+    if (!isDbAvailable())
+        return null;
+    const workers = getAllAutoWorkers();
+    for (const worker of workers) {
+        if (worker.pid === process.pid
+            && worker.project_root_realpath === projectRootRealpath) {
+            return worker;
+        }
+    }
+    return null;
+}
+/**
+ * Look up the most recent dispatch row for a worker, regardless of status.
+ * Returns null if the worker has no dispatch history yet (e.g. crashed
+ * during bootstrap before claiming the first unit).
+ */
+function getLatestDispatchForWorker(workerId) {
+    if (!isDbAvailable())
+        return null;
+    const db = _getAdapter();
+    const row = db.prepare(`SELECT unit_type, unit_id, started_at, status
+     FROM unit_dispatches
+     WHERE worker_id = :worker_id
+     ORDER BY id DESC
+     LIMIT 1`).get({ ":worker_id": workerId });
+    return row ?? null;
+}
+function workerToLockData(worker) {
+    const dispatch = getLatestDispatchForWorker(worker.worker_id);
+    const sessionFile = getRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY) ?? undefined;
+    return {
+        pid: worker.pid,
+        startedAt: worker.started_at,
+        // Pre-Phase-C-pt-2 default: when no dispatch row exists yet (bootstrap
+        // crash), report unitType="starting", unitId="bootstrap" — same shape
+        // the file-based writer used to produce.
+        unitType: dispatch?.unit_type ?? "starting",
+        unitId: dispatch?.unit_id ?? "bootstrap",
+        unitStartedAt: dispatch?.started_at ?? worker.started_at,
+        sessionFile,
+    };
+}
+/**
+ * Write or update the lock state for the current auto-mode session.
+ *
+ * Phase C pt 2: the only persistent state this function adds beyond what
+ * the workers + unit_dispatches tables already track is the pi session
+ * JSONL path, which lands in runtime_kv (worker scope, key
+ * "session_file"). The pid/startedAt/unitType/unitId/unitStartedAt are
+ * recorded by registerAutoWorker / heartbeatAutoWorker / recordDispatchClaim
+ * already.
+ *
+ * basePath is unused by the new implementation (kept as a parameter for
+ * back-compat with the 15+ call sites) — the worker is identified by
+ * pid + project_root_realpath in the workers table.
+ */
 export function writeLock(basePath, unitType, unitId, sessionFile) {
     try {
         const data = {
@@ -29,51 +111,86 @@ export function writeLock(basePath, unitType, unitId, sessionFile) {
             unitStartedAt: new Date().toISOString(),
             sessionFile,
         };
-        const lp = lockPath(basePath);
-        atomicWriteSync(lp, JSON.stringify(data, null, 2));
+        atomicWriteSync(lockPath(basePath), JSON.stringify(data, null, 2));
+    }
+    catch {
+        // Best-effort — never throw from the lock writer.
+    }
+    if (!isDbAvailable() || !sessionFile)
+        return;
+    try {
+        const projectRoot = normalizeRealPath(basePath);
+        const worker = findActiveWorkerForCurrentProcess(projectRoot);
+        if (!worker)
+            return;
+        setRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY, sessionFile);
     }
-    catch (e) { /* non-fatal: lock write failure */
-        void e;
+    catch {
+        // Best-effort — never throw from the lock writer.
     }
 }
-/** Remove the lock file on clean stop. */
+/**
+ * Phase C pt 2: clearLock no longer deletes a file. The cleanup path
+ * (markWorkerStopping in stopAuto) flips the workers row to 'stopping'.
+ * This function additionally drops the session_file runtime_kv row for
+ * the current worker so a follow-up crash detection doesn't pick up a
+ * stale session-file pointer.
+ */
 export function clearLock(basePath) {
     try {
         const p = lockPath(basePath);
         if (existsSync(p))
             unlinkSync(p);
     }
-    catch (e) { /* non-fatal: lock clear failure */
-        void e;
+    catch {
+        // Best-effort.
     }
-}
-/** Check if a crash lock exists and return its data. */
-export function readCrashLock(basePath) {
+    if (!isDbAvailable())
+        return;
     try {
-        const p = lockPath(basePath);
-        if (!existsSync(p))
-            return null;
-        const raw = readFileSync(p, "utf-8");
-        return JSON.parse(raw);
+        const projectRoot = normalizeRealPath(basePath);
+        const worker = findActiveWorkerForCurrentProcess(projectRoot);
+        if (!worker)
+            return;
+        deleteRuntimeKv("worker", worker.worker_id, SESSION_FILE_KV_KEY);
     }
-    catch (e) {
-        /* non-fatal: corrupt or unreadable lock file */ void e;
-        return null;
+    catch {
+        // Best-effort.
+    }
+}
+/**
+ * Detect a previous crashed auto-mode session.
+ *
+ * Phase C pt 2: synthesized from workers (status='active' + lapsed
+ * heartbeat) + unit_dispatches (most recent for that worker) +
+ * runtime_kv (session_file). Returns null when no stale worker exists
+ * or the DB is unavailable.
+ */
+export function readCrashLock(basePath) {
+    if (isDbAvailable()) {
+        try {
+            const projectRoot = normalizeRealPath(basePath);
+            const stale = findStaleWorkerForProject(projectRoot);
+            if (stale)
+                return workerToLockData(stale);
+        }
+        catch {
+            // Fall through to the legacy lock-file compatibility path.
+        }
     }
+    return readLegacyLock(basePath);
 }
 /**
  * Check whether the process that wrote the lock is still running.
  * Uses `process.kill(pid, 0)` which sends no signal but checks liveness.
  * Returns true if the PID matches our own — we are the lock holder (#2470).
+ *
+ * Unchanged from the file-based era — pure stateless OS check.
  */
 export function isLockProcessAlive(lock) {
     const pid = lock.pid;
     if (!Number.isInteger(pid) || pid <= 0)
         return false;
-    // Our own PID means WE hold this lock — we are alive. (#2470)
-    // Callers that need to distinguish "our lock" from "someone else's lock"
-    // (e.g. startAuto checking for a prior crashed session with a recycled PID)
-    // already guard with `crashLock.pid !== process.pid` before calling us.
     if (pid === process.pid)
         return true;
     try {
@@ -81,8 +198,6 @@ export function isLockProcessAlive(lock) {
         return true;
     }
     catch (err) {
-        // EPERM means the process exists but we lack permission — treat as alive.
-        // ESRCH means the process does not exist — treat as dead (stale lock).
         if (err.code === "EPERM")
             return true;
         return false;
@@ -96,7 +211,6 @@ export function formatCrashInfo(lock) {
         `  Started at: ${lock.unitStartedAt}`,
         `  PID: ${lock.pid}`,
     ];
-    // Add recovery guidance based on what was happening when it crashed
     if (lock.unitType === "starting" && lock.unitId === "bootstrap") {
         lines.push(`No work was lost. Run /gsd auto to restart.`);
     }
@@ -113,33 +227,23 @@ export function formatCrashInfo(lock) {
 }
 /**
  * Emit a synthetic unit-end event for a unit that crashed without emitting its own.
- *
- * Queries the journal to find the most recent unit-start for the crashed unit.
- * If a matching unit-end already exists (e.g. the hard timeout fired), this is a
- * no-op. Called during crash recovery, before clearing the stale lock.
- *
- * Addresses the gap reported in #3348 where `unit-start` was emitted but no
- * `unit-end` followed — side effects landed but the worker died before closeout.
+ * Unchanged from the file era — operates on the journal, not the lock.
  */
 export function emitCrashRecoveredUnitEnd(basePath, lock) {
-    // Skip bootstrap / starting pseudo-units — they have no meaningful unit-start event.
     if (!lock.unitType || !lock.unitId || lock.unitType === "starting")
         return;
     try {
         const all = queryJournal(basePath);
-        // Find the most recent unit-start for this unitId
         const starts = all.filter((e) => e.eventType === "unit-start" && e.data?.unitId === lock.unitId);
         if (starts.length === 0)
             return;
         const lastStart = starts[starts.length - 1];
-        // Check if a unit-end was already emitted (e.g. hard timeout fired after the crash)
         const alreadyClosed = all.some((e) => e.eventType === "unit-end" &&
             e.data?.unitId === lock.unitId &&
             e.causedBy?.flowId === lastStart.flowId &&
             e.causedBy?.seq === lastStart.seq);
         if (alreadyClosed)
             return;
-        // Find the highest seq in this flow for monotonic ordering
         const maxSeq = all
             .filter((e) => e.flowId === lastStart.flowId)
             .reduce((max, e) => Math.max(max, e.seq), lastStart.seq);
@@ -158,6 +262,15 @@ export function emitCrashRecoveredUnitEnd(basePath, lock) {
         });
     }
     catch {
-        // Never throw from crash recovery path — journal failure must not block recovery
+        // Never throw from crash recovery path.
     }
 }
+/**
+ * Used by the doctor checks (doctor-runtime-checks.ts, doctor-proactive.ts)
+ * to enumerate stale workers across all projects this DB knows about.
+ * Phase C pt 2 export — surface for the same diagnostics that previously
+ * iterated `auto.lock` files.
+ */
+export function findStaleAutoWorker(basePath) {
+    return readCrashLock(basePath);
+}