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

package/dist/resources/extensions/gsd/gsd-db.js

@@ -1156,6 +1156,193 @@ let _exitHandlerRegistered = false;
 let _dbOpenAttempted = false;
 let _lastDbError = null;
 let _lastDbPhase = null;
+/**
+ * Identity key of the workspace whose connection is currently active
+ * (currentDb). Set by openDatabaseByWorkspace(); null when the active
+ * connection was opened via the legacy openDatabase(path) path.
+ */
+let _currentIdentityKey = null;
+/**
+ * Workspace-scoped connection cache.
+ * Key: GsdWorkspace.identityKey (realpath-normalized project root).
+ * Value: the DB path and open adapter for that workspace.
+ *
+ * Sibling worktrees of the same project share the same identityKey (set by
+ * createWorkspace) and therefore reuse the same cached connection, preserving
+ * shared-WAL semantics. Different projects get distinct cache entries.
+ *
+ * NOTE: Only one connection is "active" at a time (currentDb/currentPath).
+ * The cache allows fast re-activation of a previously opened connection when
+ * callers switch between known workspaces via openDatabaseByWorkspace().
+ */
+const _dbCache = new Map();
+/** Test helper: expose the internal cache for inspection. Not for production use. */
+export function _getDbCache() {
+    return _dbCache;
+}
+/**
+ * Close and evict every entry in the workspace connection cache, then call
+ * closeDatabase() to close the active connection.
+ *
+ * Use this for test teardown or process-shutdown paths where every open
+ * connection must be flushed. Normal callers should use closeDatabase() or
+ * closeDatabaseByWorkspace() instead.
+ */
+export function closeAllDatabases() {
+    // Close all non-active cached connections first.
+    for (const [key, entry] of _dbCache) {
+        if (entry.db === currentDb)
+            continue; // handled by closeDatabase() below
+        _dbCache.delete(key);
+        try {
+            entry.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+        }
+        catch { /* best-effort */ }
+        try {
+            entry.db.exec("PRAGMA incremental_vacuum(64)");
+        }
+        catch { /* best-effort */ }
+        try {
+            entry.db.close();
+        }
+        catch { /* best-effort */ }
+    }
+    closeDatabase();
+}
+/**
+ * Open (or reuse) the database connection scoped to the given workspace.
+ *
+ * Uses workspace.identityKey as the cache key, so sibling worktrees of the
+ * same project resolve to the same connection. On a cache hit the existing
+ * adapter is reactivated as the current connection without re-opening the
+ * file. On a cache miss, delegates to openDatabase() for the full
+ * open + schema-init + migration flow, then caches the result.
+ *
+ * When switching to a different workspace, the previously active connection
+ * is preserved in the cache (not closed), so callers can switch back to it
+ * cheaply via a subsequent openDatabaseByWorkspace() call.
+ *
+ * @param workspace A GsdWorkspace created by createWorkspace().
+ * @returns true if the connection is open and ready, false otherwise.
+ */
+export function openDatabaseByWorkspace(workspace) {
+    const key = workspace.identityKey;
+    const dbPath = workspace.contract.projectDb;
+    const cached = _dbCache.get(key);
+    if (cached) {
+        // Reactivate the cached connection as the current singleton.
+        currentDb = cached.db;
+        currentPath = cached.dbPath;
+        currentPid = process.pid;
+        _dbOpenAttempted = true;
+        _currentIdentityKey = key;
+        return true;
+    }
+    // Cache miss — need to open a new connection.
+    //
+    // If there is a currently active workspace connection, stash it in the
+    // cache under its identity key before calling openDatabase(), because
+    // openDatabase() will call closeDatabase() when the path changes (which
+    // would destroy the existing adapter). By nulling out currentDb first,
+    // we prevent openDatabase() from closing the live adapter.
+    let oldDb = null;
+    let oldPath = null;
+    let oldPid = 0;
+    let oldKey = null;
+    if (currentDb !== null && _currentIdentityKey !== null) {
+        // Snapshot the old globals so we can restore them on failure.
+        oldDb = currentDb;
+        oldPath = currentPath;
+        oldPid = currentPid;
+        oldKey = _currentIdentityKey;
+        // Save the current connection so it stays alive in the cache.
+        _dbCache.set(_currentIdentityKey, {
+            dbPath: currentPath,
+            db: currentDb,
+        });
+        // Detach from globals so openDatabase() opens fresh without closing it.
+        currentDb = null;
+        currentPath = null;
+        currentPid = 0;
+        _currentIdentityKey = null;
+    }
+    // Run the full open/schema/migration flow for the new workspace.
+    // openDatabase() can throw on corrupt DB or permission error — catch so we
+    // can restore the previous connection rather than leaving globals null.
+    let opened;
+    try {
+        opened = openDatabase(dbPath);
+    }
+    catch (err) {
+        // Failed to open the new DB. Restore the previous workspace connection so
+        // the caller's workspace remains active (it is still safe in _dbCache).
+        if (oldDb !== null) {
+            currentDb = oldDb;
+            currentPath = oldPath;
+            currentPid = oldPid;
+            _currentIdentityKey = oldKey;
+        }
+        throw err;
+    }
+    if (opened && currentDb) {
+        _dbCache.set(key, { dbPath, db: currentDb });
+        _currentIdentityKey = key;
+    }
+    else if (!opened && oldDb !== null) {
+        // Restore the previous connection so the caller's workspace remains active.
+        // The failed attempt left no live adapter, so the globals stayed null.
+        currentDb = oldDb;
+        currentPath = oldPath;
+        currentPid = oldPid;
+        _currentIdentityKey = oldKey;
+    }
+    return opened;
+}
+/**
+ * Open (or reuse) the database connection scoped to the workspace in a
+ * MilestoneScope. Thin delegation to openDatabaseByWorkspace().
+ */
+export function openDatabaseByScope(scope) {
+    return openDatabaseByWorkspace(scope.workspace);
+}
+/**
+ * Close the database connection for the given workspace and remove it from
+ * the cache. If the workspace's connection is currently active (currentDb),
+ * performs a full closeDatabase() including WAL checkpoint. Otherwise only
+ * removes the cache entry (the adapter was already replaced by a later open).
+ */
+export function closeDatabaseByWorkspace(workspace) {
+    const key = workspace.identityKey;
+    const cached = _dbCache.get(key);
+    if (!cached)
+        return;
+    _dbCache.delete(key);
+    if (currentDb === cached.db) {
+        // This workspace's connection is the active one — full close.
+        closeDatabase();
+    }
+    else {
+        // Connection was displaced by a later open; close the adapter directly.
+        try {
+            cached.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+        }
+        catch (e) {
+            logWarning("db", `WAL checkpoint (byWorkspace) failed: ${e.message}`);
+        }
+        try {
+            cached.db.exec("PRAGMA incremental_vacuum(64)");
+        }
+        catch (e) {
+            logWarning("db", `incremental vacuum (byWorkspace) failed: ${e.message}`);
+        }
+        try {
+            cached.db.close();
+        }
+        catch (e) {
+            logWarning("db", `database close (byWorkspace) failed: ${e.message}`);
+        }
+    }
+}
 export function getDbProvider() {
     loadProvider();
     return providerName;
@@ -1300,6 +1487,13 @@ export function closeDatabase() {
         catch (e) {
             logWarning("db", `database close failed: ${e.message}`);
         }
+        // If this connection was workspace-tracked, evict it from the cache so
+        // subsequent openDatabaseByWorkspace() calls re-open rather than reactivate
+        // a closed adapter.
+        if (_currentIdentityKey !== null) {
+            _dbCache.delete(_currentIdentityKey);
+            _currentIdentityKey = null;
+        }
         currentDb = null;
         currentPath = null;
         currentPid = 0;

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

@@ -150,7 +150,7 @@ export async function showQueueAdd(ctx, pi, basePath, state) {
     ].join(" ");
     // ── Dispatch the queue prompt ───────────────────────────────────────
     // Activate the queue phase so the write-gate applies to CONTEXT.md writes
-    setQueuePhaseActive(true);
+    setQueuePhaseActive(true, basePath);
     const queueInlinedTemplates = inlineTemplate("context", "Context");
     const prompt = loadPrompt("queue", {
         preamble,

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";
@@ -19,7 +19,7 @@ import { assessInterruptedSession, formatInterruptedSessionRunningMessage, forma
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
-import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
+import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, clearPathCache, } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
@@ -43,10 +43,39 @@ 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";
+// ─── 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 +106,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 +143,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 +190,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 +284,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 +359,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 +445,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"));
@@ -486,6 +569,12 @@ export function maybeHandleReadyPhraseWithoutFiles(event) {
     const text = extractAssistantText(lastMsg);
     if (!READY_PHRASE_RE.test(text))
         return false;
+    // Bust paths.ts cached dir listings before checking for fresh writes. The
+    // LLM's Write tool calls do not invalidate paths.ts caches, so a stale
+    // listing taken before the milestone dir or its CONTEXT/ROADMAP files
+    // existed would falsely report the artifacts as missing and trigger the
+    // 3-strike "ready without files" abort even though the writes succeeded.
+    clearPathCache();
     // Gate: artifacts must still be missing — if they exist, the happy path
     // already fired and we have nothing to do.
     const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
@@ -890,7 +979,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
@@ -1056,13 +1145,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`),
@@ -1075,7 +1164,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;
@@ -1329,6 +1418,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);
@@ -1431,7 +1523,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;
     }
@@ -1636,7 +1728,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 {
@@ -1654,7 +1746,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");
             }
         }
@@ -1663,7 +1755,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;
     }
@@ -1691,7 +1783,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") {
@@ -1738,13 +1830,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`),
@@ -1755,7 +1847,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;
@@ -1811,7 +1903,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") {
@@ -1827,7 +1919,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") {