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

package/dist/resources/extensions/gsd/guided-flow.js

@@ -7,11 +7,11 @@
  */
 import { showNextAction } from "../shared/tui.js";
 import { loadFile, saveFile } from "./files.js";
-import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
+import { isDbAvailable, getMilestone, getMilestoneSlices } from "./gsd-db.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import { buildCompleteSlicePrompt, buildDiscussMilestonePrompt, buildExecuteTaskPrompt, buildPlanMilestonePrompt, buildPlanSlicePrompt, buildSkillActivationBlock, } from "./auto-prompts.js";
-import { deriveState } from "./state.js";
+import { deriveState, isGhostMilestone } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { startAutoDetached } from "./auto.js";
 import { clearLock } from "./crash-recovery.js";
@@ -43,10 +43,41 @@ import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
+import { createWorkspace, scopeMilestone } from "./workspace.js";
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 export { MILESTONE_ID_RE, generateMilestoneSuffix, nextMilestoneId, extractMilestoneSeq, parseMilestoneId, milestoneIdSort, maxMilestoneNum, findMilestoneIds, reserveMilestoneId, claimReservedId, getReservedMilestoneIds, clearReservedMilestoneIds, } from "./milestone-ids.js";
 export { showQueue, handleQueueReorder, showQueueAdd, buildExistingMilestonesContext, } from "./guided-flow-queue.js";
 import { logWarning } from "./workflow-logger.js";
+import { deleteRuntimeKv } from "./db/runtime-kv.js";
+import { PAUSED_SESSION_KV_KEY } from "./interrupted-session.js";
+// ─── Scope-based validator wrappers ──────────────────────────────────────────
+// These thin wrappers accept a MilestoneScope so callers that already hold a
+// pinned scope never have to re-derive (basePath, milestoneId) separately.
+// The underlying implementations in auto-recovery.ts / auto-artifact-paths.ts /
+// state.ts are unchanged — only the call surface in guided-flow.ts is migrated.
+/**
+ * Scope-based overload of verifyExpectedArtifact.
+ * Uses scope.workspace.projectRoot as the authoritative base path, making
+ * the check immune to cwd-drift and worktree-path divergence.
+ */
+export function verifyExpectedArtifactForScope(scope, unitType, unitId) {
+    return verifyExpectedArtifact(unitType, unitId, scope.workspace.projectRoot);
+}
+/**
+ * Scope-based overload of resolveExpectedArtifactPath.
+ * Returns the canonical absolute path (or null) using the scope's projectRoot.
+ */
+export function resolveExpectedArtifactPathForScope(scope, unitType, unitId) {
+    return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
+}
+/**
+ * Scope-based overload of isGhostMilestone.
+ * Binds basePath and milestoneId from the scope, ensuring path resolution
+ * uses the canonical project root regardless of the cwd at call time.
+ */
+export function isGhostMilestoneByScope(scope) {
+    return isGhostMilestone(scope.workspace.projectRoot, scope.milestoneId);
+}
 function needsPlanV2Gate(state) {
     return state.phase === "executing"
         || state.phase === "summarizing"
@@ -77,6 +108,10 @@ function buildDocsCommitInstruction(_message) {
 // #4573: cap for how many times we nudge the LLM after a premature ready
 // phrase before giving up and asking the user to re-run /gsd.
 const MAX_READY_REJECTS = 2;
+// H1 (#5012): cap for Gate 1b plan-blocked recovery hints. After this many
+// consecutive recovery attempts the loop is stopped and the user is directed
+// to investigate manually.
+const MAX_PLAN_BLOCKED_RECOVERIES = 3;
 // #4573: matches the canonical ready phrase the discuss prompt asks the LLM
 // to emit. Accepts any M-prefixed milestone ID (three digits + optional
 // suffix) with optional trailing punctuation.
@@ -110,9 +145,9 @@ This stage is running inside the foreground \`/gsd new-project --deep\` intervie
 /**
  * Backward-compat bridge: returns a mutable reference to the entry matching
  * basePath, or the sole entry when only one session exists.
- * Internal use only — external code should use the Map directly.
+ * Exported for testing — internal use only in production code.
  */
-function _getPendingAutoStart(basePath) {
+export function _getPendingAutoStart(basePath) {
     if (basePath)
         return pendingAutoStartMap.get(basePath) ?? null;
     if (pendingAutoStartMap.size === 1)
@@ -157,7 +192,9 @@ function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries) {
  * Exported for testing (#2985).
  */
 export function setPendingAutoStart(basePath, entry) {
-    pendingAutoStartMap.set(basePath, { createdAt: Date.now(), ...entry });
+    const ws = createWorkspace(entry.basePath);
+    const scope = scopeMilestone(ws, entry.milestoneId);
+    pendingAutoStartMap.set(basePath, { createdAt: Date.now(), planBlockedRecoveryCount: 0, ...entry, scope });
 }
 /**
  * Clear pending auto-start state.
@@ -249,6 +286,10 @@ export async function checkDeepProjectSetupAfterTurn(_event, ctx, basePath) {
     if (!entry)
         return false;
     if (entry.currentUnitType && entry.currentUnitId) {
+        // TODO(C-future): PendingDeepProjectSetupEntry does not carry a MilestoneScope
+        // because deep-project-setup units span non-milestone unit types (discuss-project,
+        // discuss-requirements, etc.).  Migrate to verifyExpectedArtifactForScope once
+        // PendingDeepProjectSetupEntry is extended with a scope field.
         const artifactReady = verifyExpectedArtifact(entry.currentUnitType, entry.currentUnitId, entry.basePath);
         if (!artifactReady) {
             return false;
@@ -320,17 +361,61 @@ export function checkAutoStartAfterDiscuss() {
     const { ctx, pi, basePath, milestoneId, step } = entry;
     // Gate 1: Primary milestone must have CONTEXT.md or ROADMAP.md
     // The "discuss" path creates CONTEXT.md; the "plan" path creates ROADMAP.md.
-    const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
-    const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    // Use pinned scope (immune to cwd-drift) for existence checks.
+    const contextFilePath = entry.scope.contextFile();
+    const roadmapFilePath = entry.scope.roadmapFile();
+    const contextFile = existsSync(contextFilePath) ? contextFilePath : null;
+    const roadmapFile = existsSync(roadmapFilePath) ? roadmapFilePath : null;
     if (!contextFile && !roadmapFile)
         return false; // neither artifact yet — keep waiting
+    // Gate 1b: Discriminate plan-blocked from discuss-incomplete when the DB row is queued.
+    // If the DB is available and the row is still "queued" but CONTEXT.md already exists on
+    // disk, the discuss phase completed but gsd_plan_milestone was hard-blocked by the
+    // depth-verification gate.  Emit a recovery hint so the next agent turn can retry
+    // gsd_plan_milestone, then return false (keep blocking auto-start).
+    // If CONTEXT.md does not exist (discuss-incomplete), Gate 1 already blocked above.
+    if (isDbAvailable()) {
+        const dbRow = getMilestone(milestoneId);
+        if (dbRow?.status === "queued" && contextFile) {
+            if (entry.planBlockedRecoveryCount >= MAX_PLAN_BLOCKED_RECOVERIES) {
+                // H1: recovery loop cap reached — stop triggering new turns, escalate to user.
+                logWarning("guided", `Gate 1b: milestone ${milestoneId} plan-blocked recovery limit reached ` +
+                    `(${entry.planBlockedRecoveryCount}/${MAX_PLAN_BLOCKED_RECOVERIES}); escalating to user`);
+                ctx.ui.notify(`Milestone ${milestoneId} plan_milestone has been blocked ${entry.planBlockedRecoveryCount} times. ` +
+                    `Re-run /gsd to reset the recovery counter, or run /gsd-debug to diagnose without resetting.`, "error");
+                return false;
+            }
+            logWarning("guided", `Gate 1b: milestone ${milestoneId} queued with CONTEXT.md present — ` +
+                `plan_milestone was blocked; emitting recovery hint ` +
+                `(attempt ${entry.planBlockedRecoveryCount + 1}/${MAX_PLAN_BLOCKED_RECOVERIES})`);
+            ctx.ui.notify(`Milestone ${milestoneId}: context file exists but milestone is still queued. ` +
+                `Retrying gsd_plan_milestone to complete the blocked planning step.`, "warning");
+            try {
+                pi.sendMessage({
+                    customType: "gsd-plan-milestone-blocked-recovery",
+                    content: `Milestone ${milestoneId} has ${contextFile} on disk but its DB row is still ` +
+                        `"queued". The gsd_plan_milestone tool was previously blocked by the ` +
+                        `depth-verification gate. Call gsd_plan_milestone now to complete the ` +
+                        `planning phase.`,
+                    display: false,
+                }, { triggerTurn: true });
+                // Increment only after a successful dispatch so transient sendMessage
+                // failures do not consume recovery budget.
+                entry.planBlockedRecoveryCount += 1;
+            }
+            catch (e) {
+                logWarning("guided", `Gate 1b recovery sendMessage failed: ${e.message}`);
+            }
+            return false;
+        }
+    }
     // Gate 2: STATE.md must exist — written as the last step in the discuss
     // output phase. This prevents auto-start from firing during Phase 3
     // (sequential readiness gates for remaining milestones) in multi-milestone
     // discussions, where M001-CONTEXT.md exists but M002/M003 haven't been
     // processed yet.
-    const stateFile = resolveGsdRootFile(basePath, "STATE");
-    if (!stateFile)
+    const stateFilePath = entry.scope.stateFile();
+    if (!existsSync(stateFilePath))
         return false; // discussion not finalized yet
     // Gate 3: Multi-milestone completeness warning
     // Parse PROJECT.md for milestone sequence, warn if any are missing context.
@@ -362,7 +447,7 @@ export function checkAutoStartAfterDiscuss() {
     // The LLM writes DISCUSSION-MANIFEST.json after each Phase 3 gate decision.
     // 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 manifestPath = join(entry.scope.workspace.contract.projectGsd, "DISCUSSION-MANIFEST.json");
     if (existsSync(manifestPath)) {
         try {
             const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
@@ -896,7 +981,7 @@ export async function showHeadlessMilestoneCreation(ctx, pi, basePath, seedConte
     // Build and dispatch the headless discuss prompt
     const prompt = buildHeadlessDiscussPrompt(nextId, seedContext, basePath);
     // Set pending auto start (auto-mode triggers on "Milestone X ready." via checkAutoStartAfterDiscuss)
-    pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, createdAt: Date.now() });
+    setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId });
     // Dispatch as discuss-milestone. The LLM writes PROJECT.md, REQUIREMENTS.md,
     // and CONTEXT.md, then calls gsd_plan_milestone — this is semantically the
     // discuss path, just non-interactive. Using "plan-milestone" here caused
@@ -1062,13 +1147,13 @@ export async function showDiscuss(ctx, pi, basePath) {
             const seed = draftContent
                 ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
                 : basePrompt;
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: mid, step: false });
             await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone");
         }
         else if (choice === "discuss_fresh") {
             const discussMilestoneTemplates = inlineTemplate("context", "Context");
             const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: mid, step: false, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: mid, step: false });
             await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
                 milestoneId: mid, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${mid}): milestone context from discuss`),
@@ -1081,7 +1166,7 @@ export async function showDiscuss(ctx, pi, basePath) {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: false, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: false });
             await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         return;
@@ -1335,6 +1420,9 @@ function selfHealRuntimeRecords(basePath, ctx) {
         for (const record of records) {
             const { unitType, unitId, phase } = record;
             // Clear records whose expected artifact already exists (completed but not cleaned up)
+            // TODO(C-future): selfHealRuntimeRecords iterates across all unit types (not just milestone
+            // units), so it cannot be converted to resolveExpectedArtifactPathForScope without
+            // first establishing a per-record scope.  Migrate once unit runtime records carry scope info.
             const artifactPath = resolveExpectedArtifactPath(unitType, unitId, basePath);
             if (artifactPath && existsSync(artifactPath)) {
                 clearUnitRuntimeRecord(basePath, unitType, unitId);
@@ -1437,7 +1525,7 @@ async function handleMilestoneActions(ctx, pi, basePath, milestoneId, milestoneT
         const milestoneIds = findMilestoneIds(basePath);
         const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
         const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-        pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+        setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
         await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         return true;
     }
@@ -1535,11 +1623,13 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     if (interrupted.classification === "stale") {
         clearLock(basePath);
         if (interrupted.pausedSession) {
+            // Phase C pt 2: paused-session.json migrated to runtime_kv
+            // (global scope, key PAUSED_SESSION_KV_KEY).
             try {
-                unlinkSync(join(gsdRoot(basePath), "runtime", "paused-session.json"));
+                deleteRuntimeKv("global", "", PAUSED_SESSION_KV_KEY);
             }
             catch (e) {
-                logWarning("guided", `stale pause file cleanup failed: ${e.message}`, { file: "guided-flow.ts" });
+                logWarning("guided", `stale paused-session DB cleanup failed: ${e.message}`, { file: "guided-flow.ts" });
             }
         }
     }
@@ -1642,7 +1732,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
         const isFirst = milestoneIds.length === 0;
         if (isFirst) {
             // First ever — skip wizard, just ask directly
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
             await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New project, milestone ${nextId}. Do NOT read or explore .gsd/ — it's empty scaffolding.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         else {
@@ -1660,7 +1750,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 notYetMessage: "Run /gsd when ready.",
             });
             if (choice === "new_milestone") {
-                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+                setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
                 await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
             }
         }
@@ -1669,7 +1759,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     const milestoneId = state.activeMilestone.id;
     const milestoneTitle = state.activeMilestone.title;
     if (planV2GateDecision === "recover-missing-context") {
-        pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+        setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
         await dispatchWorkflow(pi, await buildDiscussMilestonePrompt(milestoneId, milestoneTitle, basePath, getStructuredQuestionsAvailability(pi, ctx)), "gsd-discuss", ctx, "discuss-milestone");
         return;
     }
@@ -1697,7 +1787,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
             await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         else if (choice === "status") {
@@ -1744,13 +1834,13 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const seed = draftContent
                 ? `${basePrompt}\n\n## Prior Discussion (Draft Seed)\n\n${draftContent}`
                 : basePrompt;
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
             await dispatchWorkflow(pi, seed, "gsd-discuss", ctx, "discuss-milestone");
         }
         else if (choice === "discuss_fresh") {
             const discussMilestoneTemplates = inlineTemplate("context", "Context");
             const structuredQuestionsAvailable = getStructuredQuestionsAvailability(pi, ctx);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
             await dispatchWorkflow(pi, loadPrompt("guided-discuss-milestone", {
                 milestoneId, milestoneTitle, inlinedTemplates: discussMilestoneTemplates, structuredQuestionsAvailable,
                 commitInstruction: buildDocsCommitInstruction(`docs(${milestoneId}): milestone context from discuss`),
@@ -1761,7 +1851,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const milestoneIds = findMilestoneIds(basePath);
             const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
             const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-            pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+            setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
             await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
         }
         return;
@@ -1817,7 +1907,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 notYetMessage: "Run /gsd when ready.",
             });
             if (choice === "plan") {
-                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+                setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
                 await dispatchWorkflow(pi, await buildPlanMilestonePrompt(milestoneId, milestoneTitle, basePath), "gsd-run", ctx, "plan-milestone");
             }
             else if (choice === "discuss") {
@@ -1833,7 +1923,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
                 const milestoneIds = findMilestoneIds(basePath);
                 const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
                 const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
-                pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode, createdAt: Date.now() });
+                setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
                 await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId, `New milestone ${nextId}.`, basePath), "gsd-run", ctx, "discuss-milestone");
             }
             else if (choice === "discard_milestone") {

package/dist/resources/extensions/gsd/interrupted-session.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { formatCrashInfo, isLockProcessAlive, readCrashLock, } from "./crash-recovery.js";
@@ -6,6 +6,7 @@ import { gsdRoot } from "./paths.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { synthesizeCrashRecovery, } from "./session-forensics.js";
 import { deriveState } from "./state.js";
+import { getRuntimeKv, deleteRuntimeKv } from "./db/runtime-kv.js";
 const LEGACY_DEEP_SETUP_UNITS = new Set([
     "workflow-preferences:WORKFLOW-PREFS",
     "discuss-project:PROJECT",
@@ -32,24 +33,26 @@ function isStalePseudoMilestonePause(meta) {
         && typeof meta.unitId === "string"
         && LEGACY_DEEP_SETUP_UNITS.has(`${meta.unitType}:${meta.unitId}`);
 }
+/**
+ * runtime_kv key (global scope) that stores the most recent paused-session
+ * metadata. Phase C pt 2: replaces runtime/paused-session.json. The key is
+ * project-wide (not worker-scoped) because the paused state represents the
+ * last time auto-mode paused on this project — there is at most one paused
+ * session per project at a time.
+ */
+export const PAUSED_SESSION_KV_KEY = "paused_session";
 export function readPausedSessionMetadata(basePath) {
-    const pausedPath = join(gsdRoot(basePath), "runtime", "paused-session.json");
-    if (!existsSync(pausedPath))
+    // basePath is unused now (the DB is workspace-scoped via the connection
+    // openDatabase opened on it) but kept in the signature for callers.
+    void basePath;
+    const meta = getRuntimeKv("global", "", PAUSED_SESSION_KV_KEY);
+    if (!meta)
         return null;
-    try {
-        const meta = JSON.parse(readFileSync(pausedPath, "utf-8"));
-        if (isStalePseudoMilestonePause(meta)) {
-            try {
-                unlinkSync(pausedPath);
-            }
-            catch { /* non-fatal */ }
-            return null;
-        }
-        return meta;
-    }
-    catch {
+    if (isStalePseudoMilestonePause(meta)) {
+        deleteRuntimeKv("global", "", PAUSED_SESSION_KV_KEY);
         return null;
     }
+    return meta;
 }
 export function isBootstrapCrashLock(lock) {
     return !!(lock &&