@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -1,20 +1,21 @@
 // Project/App: gsd-pi
 // File Purpose: Registers GSD extension runtime hooks and token-saving tool policies.
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { ALWAYS_PRESERVED_SHIM_TOOL_NAMES } from "@gsd/pi-ai";
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
-import { buildMilestoneFileName, clearPathCache, milestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { applyAskUserQuestionsGateResult, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, hostWriteGateAdapter, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeBash, shouldBlockWorktreeWrite, isGateQuestionId, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { buildMilestoneFileName, canonicalPhaseDirName, clearPathCache, milestonesDir, legacyMilestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
+import { applyAskUserQuestionsGateResult, clearDiscussionFlowState, currentWriteGateSnapshot, formatPendingAskUserQuestionsGateMessage, formatTimedOutAskUserQuestionsGateMessage, hostWriteGateAdapter, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeBash, shouldBlockWorktreeWrite, isGateQuestionId, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { canonicalToolName } from "../engine-hook-contract.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
 import { clearAutoCompletionStopInProgress, clearToolInvocationError, getAutoRuntimeSnapshot, getSourceObservationStore, isAutoActive, isAutoCompletionStopInProgress, isAutoPaused, isInteractiveElicitationInFlight, markToolEnd, markToolStart, recordAutoToolSurfaceSnapshot, recordToolInvocationError, } from "../auto-runtime-state.js";
 import { applyProviderPayloadPolicy } from "../provider-payload-policy.js";
-import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
+import { checkToolCallLoop, recordToolCallLoopMutation, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
+import { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 import { maybePauseAutoForApprovalGate, resetPendingGatePauseGuard } from "./pending-gate-pause.js";
 import { saveActivityLog } from "../activity-log.js";
 import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult, saveEvidenceToDisk } from "../safety/evidence-collector.js";
@@ -42,6 +43,7 @@ import { supportsSourceObservationsForUnit } from "../source-observations.js";
 import { clearPendingAutoStart } from "../pending-auto-start.js";
 import { resolveWorkflowToolBasePath } from "./dynamic-tools.js";
 import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.js";
+import { flushAllManifests } from "../workflow-manifest.js";
 let approvalQuestionAbortInFlight = false;
 async function loadWelcomeScreenModule() {
     const candidates = [];
@@ -138,22 +140,7 @@ export const MINIMAL_GSD_TOOL_NAMES = [
     "capture_thought",
     "gsd_capture_thought",
 ];
-export const MINIMAL_AUTO_BASE_TOOL_NAMES = [
-    "ask_user_questions",
-    "bash",
-    "bg_shell",
-    "edit",
-    "find",
-    "glob",
-    "grep",
-    "fetch_page",
-    "search-the-web",
-    "ls",
-    "read",
-    "subagent",
-    "write",
-    "ToolSearch",
-];
+export { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 function withPreservedShimTools(toolNames) {
     return [...new Set([...toolNames, ...ALWAYS_PRESERVED_SHIM_TOOL_NAMES])];
 }
@@ -436,6 +423,9 @@ function deferApprovalGate(gateId, basePath) {
     // workflow MCP child already verified this gate, deferring would block
     // tools for a gate that can never legitimately arm.
     const snapshot = hostWriteGateAdapter.readState(basePath);
+    deferApprovalGateFromSnapshot(gateId, basePath, snapshot);
+}
+function deferApprovalGateFromSnapshot(gateId, basePath, snapshot) {
     if (isApprovalGateVerifiedInSnapshot(snapshot, gateId))
         return;
     const milestoneId = extractDepthVerificationMilestoneId(gateId);
@@ -446,6 +436,16 @@ function deferApprovalGate(gateId, basePath) {
 function contextBasePath(ctx) {
     return typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd();
 }
+const LOOP_GUARD_INTERACTIVE_INSTRUCTIONS = [
+    "Do not retry this tool or call other tools this turn — stop and respond to the user in text.",
+    "Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.",
+];
+const LOOP_GUARD_AUTO_INSTRUCTION = "Do not re-issue this blocked tool. In /gsd auto, stop tool calls for this turn and return control to the auto-mode recovery/replan path.";
+function formatLoopGuardBlockReason(reason) {
+    if (!reason || !getAutoRuntimeSnapshot().active)
+        return reason;
+    return LOOP_GUARD_INTERACTIVE_INSTRUCTIONS.reduce((formatted, instruction) => formatted.replace(instruction, LOOP_GUARD_AUTO_INSTRUCTION), reason);
+}
 function beginSourceObservationStoreForCurrentUnit(ctx) {
     if (!isAutoActive())
         return null;
@@ -526,7 +526,7 @@ function isContextDraftSummarySave(toolName, input) {
  */
 function resolveAskUserQuestionsGateDetails(event) {
     const hasRoundShape = (value) => !!value && typeof value === "object" &&
-        (value.cancelled !== undefined || value.response !== undefined);
+        (value.cancelled !== undefined || value.timed_out !== undefined || value.response !== undefined);
     const details = event.details;
     if (hasRoundShape(details))
         return details;
@@ -566,8 +566,24 @@ function formatQuestionExchange(questions, answers) {
     return lines.join("\n");
 }
 async function ensureMilestoneShell(basePath, milestoneId) {
+    // When no milestone dir exists yet, prefer the legacy container when it has
+    // at least one milestone subdirectory; an empty milestones/ dir (e.g. one
+    // created by an old bootstrapGsdProject) is not a real legacy layout.
+    const legacy = legacyMilestonesDir(basePath);
+    const isLegacyLayout = existsSync(legacy) && (() => {
+        try {
+            return readdirSync(legacy).some(e => statSync(join(legacy, e)).isDirectory());
+        }
+        catch {
+            return false;
+        }
+    })();
+    const container = isLegacyLayout ? legacy : milestonesDir(basePath);
+    const fallbackDirName = isLegacyLayout
+        ? milestoneId
+        : canonicalPhaseDirName(milestoneId, `New milestone ${milestoneId}`);
     const milestoneDir = resolveMilestonePath(basePath, milestoneId)
-        ?? join(milestonesDir(basePath), milestoneId);
+        ?? join(container, fallbackDirName);
     mkdirSync(milestoneDir, { recursive: true });
     clearPathCache();
     try {
@@ -593,10 +609,14 @@ async function saveDiscussionQuestionRound(basePath, milestoneId, questions, det
     const answers = details?.response?.answers;
     const timestamp = new Date().toISOString();
     const exchange = formatQuestionExchange(questions, answers);
-    const discussionPath = join(milestoneDir, buildMilestoneFileName(milestoneId, "DISCUSSION"));
+    // Layout-aware filename: legacy dirs use MID-SUFFIX.md; flat-phase use NN-SUFFIX.md.
+    const legacyBase = legacyMilestonesDir(basePath);
+    const isLegacyDir = milestoneDir.startsWith(legacyBase + "/") || milestoneDir.startsWith(legacyBase + "\\");
+    const milestoneFileName = (suffix) => isLegacyDir ? `${milestoneId}-${suffix}.md` : buildMilestoneFileName(milestoneId, suffix);
+    const discussionPath = join(milestoneDir, milestoneFileName("DISCUSSION"));
     const existingDiscussion = await loadFile(discussionPath) ?? `# ${milestoneId} Discussion Log\n\n`;
     await saveFile(discussionPath, `${existingDiscussion}## Exchange — ${timestamp}\n\n${exchange}---\n\n`);
-    const draftPath = join(milestoneDir, buildMilestoneFileName(milestoneId, "CONTEXT-DRAFT"));
+    const draftPath = join(milestoneDir, milestoneFileName("CONTEXT-DRAFT"));
     const existingDraft = await loadFile(draftPath);
     const draftHeader = existingDraft
         ?? [
@@ -675,6 +695,35 @@ export function registerHooks(pi, ecosystemHandlers) {
         await applyDisabledModelProviderPolicy(ctx);
         await applyCompactionThresholdOverride(ctx);
         await prepareWorkflowMcpForHookContext(ctx, basePath);
+        // Migrate legacy .gsd/milestones/ to flat-phase .gsd/phases/ when detected.
+        // Best-effort — never blocks session startup. Skipped inside auto-worktrees
+        // (migration already ran on the project root before the worktree was created).
+        try {
+            const { isInAutoWorktree } = await import("../auto-worktree.js");
+            if (!isInAutoWorktree(basePath)) {
+                const { needsFlatPhaseMigration } = await import("../flat-phase-migration.js");
+                if (needsFlatPhaseMigration(basePath)) {
+                    const { ensureDbOpen } = await import("./dynamic-tools.js");
+                    const opened = await ensureDbOpen(basePath);
+                    if (opened) {
+                        const { migrateToFlatPhase } = await import("../flat-phase-migration.js");
+                        await migrateToFlatPhase(basePath);
+                    }
+                    else {
+                        safetyLogWarning("bootstrap", "flat-phase migration deferred: legacy .gsd/milestones/ layout detected but the workflow database could not be opened — will retry on next session");
+                    }
+                }
+            }
+            const projectRoot = resolveWorktreeProjectRoot(basePath);
+            const { pruneStaleFlatPhaseBackups } = await import("../flat-phase-migration.js");
+            const pruned = pruneStaleFlatPhaseBackups(projectRoot);
+            if (pruned > 0) {
+                safetyLogWarning("bootstrap", `pruned ${pruned} stale flat-phase migration backup(s) from .gsd-backups/ (retention exceeded)`);
+            }
+        }
+        catch (err) {
+            safetyLogWarning("bootstrap", `flat-phase migration: ${err instanceof Error ? err.message : String(err)}`);
+        }
         // Apply show_token_cost preference (#1515)
         try {
             const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -828,6 +877,17 @@ export function registerHooks(pi, ecosystemHandlers) {
         const { handleAgentEnd } = await import("./agent-end-recovery.js");
         const agentEndBasePath = contextBasePath(ctx);
         try {
+            // The manifest is a non-critical projection (the append-only event log is
+            // the authoritative recovery source), so a flush failure must not skip
+            // agent_end recovery. drainManifestWrites still propagates write failures
+            // to explicit flush callers; here we deliberately log and continue so
+            // handleAgentEnd (and the finally below) always run.
+            try {
+                await flushAllManifests();
+            }
+            catch (err) {
+                safetyLogWarning("manifest", `flushAllManifests on agent_end failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
             await handleAgentEnd(pi, event, ctx);
         }
         finally {
@@ -966,14 +1026,16 @@ export function registerHooks(pi, ecosystemHandlers) {
             return;
         const gateId = approvalGateIdForUnit(unitType, unitId);
         if (gateId) {
+            const basePath = contextBasePath(ctx);
+            const gateSnapshot = currentWriteGateSnapshot(basePath);
             // Skip the gate if this milestone is already depth-verified — the approval
             // pattern matched again on post-verification text (a false-positive re-trigger).
             // Without this guard, the second firing blocks gsd_plan_milestone in the same
             // turn and leaves CONTEXT.md on disk with no DB row (#discuss-milestone-no-db).
             const gateMilestoneId = extractDepthVerificationMilestoneId(gateId);
-            if (gateMilestoneId && isMilestoneDepthVerified(gateMilestoneId, contextBasePath(ctx)))
+            if (gateMilestoneId && isMilestoneDepthVerifiedInSnapshot(gateSnapshot, gateMilestoneId))
                 return;
-            deferApprovalGate(gateId, contextBasePath(ctx));
+            deferApprovalGateFromSnapshot(gateId, basePath, gateSnapshot);
         }
         approvalQuestionAbortInFlight = true;
         ctx.ui.notify(`${unitType ?? "The discussion"}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`, "info");
@@ -1015,7 +1077,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         // ── Loop guard: block repeated identical tool calls ──
         const loopCheck = checkToolCallLoop(toolName, event.input);
         if (loopCheck.block) {
-            return { block: true, reason: loopCheck.reason };
+            return { block: true, reason: formatLoopGuardBlockReason(loopCheck.reason) };
         }
         const deferredGateGuard = shouldBlockDeferredApprovalTool(toolName, event.input, discussionBasePath);
         if (deferredGateGuard.block) {
@@ -1221,6 +1283,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
         if (!event.isError) {
+            recordToolCallLoopMutation(toolName);
             refreshSourceObservationAfterMutation(toolName, event.input, ctx);
             clearSourceObservationsAfterShell(toolName);
         }
@@ -1281,6 +1344,23 @@ export function registerHooks(pi, ecosystemHandlers) {
                     }],
             };
         }
+        if (gateResult.status === "timeout") {
+            // Host elicitation timed out before the user answered. The gate stays
+            // pending (fail-closed), but we reset the loop guard and return a
+            // timeout-specific message so the model does NOT immediately re-ask —
+            // that would just hit the same timeout again. Auto-mode pauses and
+            // waits for the user to respond on a new turn (#852).
+            resetToolCallLoopGuard();
+            if (ctx) {
+                await maybePauseAutoForApprovalGate(ctx, pi, true, "Depth confirmation timed out waiting for a response — pausing auto-mode. Reply to resume.");
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: formatTimedOutAskUserQuestionsGateMessage(gateResult.pendingGateId),
+                    }],
+            };
+        }
         if (gateResult.status === "verified") {
             clearDeferredApprovalGate(basePath);
         }
@@ -1298,6 +1378,16 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
             return;
         }
+        if (roundOutcome === "timeout") {
+            // Non-gate (consent/decision) question timed out at the host elicitation.
+            // Same policy as the gate-timeout branch above: reset the loop guard and
+            // pause-and-wait so the model does not re-ask into the same timeout (#852).
+            resetToolCallLoopGuard();
+            if (ctx) {
+                await maybePauseAutoForApprovalGate(ctx, pi, true, "A user question timed out waiting for a response — pausing auto-mode. Reply to resume.");
+            }
+            return;
+        }
         if (roundOutcome === "waiting") {
             resetToolCallLoopGuard();
             if (ctx) {

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -23,6 +23,10 @@ const DEFAULT_KNOWLEDGE_MAX_CHARS = 12_000;
 const DEFAULT_CODEBASE_MAX_CHARS = 8_000;
 const MIN_CONTEXT_MESSAGE_MAX_CHARS = 1_000;
 const MIN_KNOWLEDGE_MAX_CHARS = 1_000;
+const CONTEXT_MAINTENANCE_KEY_SEPARATOR = "\0";
+const contextMaintenanceCompletedForSession = new Set();
+const contextMaintenanceInFlightBySession = new Map();
+const deferredContextMaintenanceBySession = new Map();
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
  * hardcoding absolute paths in the system prompt template. Only skills
@@ -65,6 +69,24 @@ export const BUNDLED_SKILL_TRIGGERS = [
     { trigger: "Author a YAML workflow definition — steps, triggers, and templates", skill: "create-workflow" },
     { trigger: "Deep code optimization audit — perf anti-patterns, memory leaks, algorithmic complexity, bundle size, I/O, caching, dead code (parallel pattern-based hunt)", skill: "code-optimizer" },
 ];
+/**
+ * Remove the volatile lines from a CODEBASE.md map before it is injected into
+ * the cached system-prompt prefix: the human-readable `Generated: <timestamp>`
+ * header and the `<!-- gsd:codebase-meta {...} -->` comment. Both carry a
+ * per-regeneration timestamp (and fingerprint) that change whenever the map is
+ * refreshed, which would otherwise invalidate the provider KV cache prefix on
+ * every turn even when the underlying file structure is identical. (#847)
+ */
+export function stripVolatileCodebaseMetadata(content) {
+    return content
+        .split("\n")
+        .filter((line) => {
+        const trimmed = line.trimStart();
+        return !trimmed.startsWith("Generated:") && !trimmed.startsWith("<!-- gsd:codebase-meta");
+    })
+        .join("\n")
+        .trim();
+}
 function warnDeprecatedAgentInstructions() {
     const paths = [
         join(gsdHome(), "agent-instructions.md"),
@@ -78,45 +100,93 @@ function warnDeprecatedAgentInstructions() {
         }
     }
 }
-export async function buildBeforeAgentStartResult(event, ctx) {
-    if (!existsSync(join(process.cwd(), ".gsd")))
-        return undefined;
-    const stopContextTimer = debugTime("context-inject");
-    const systemContent = loadPrompt("system", {
-        templatesDir: getTemplatesDir(),
-        shortcutDashboard: formatShortcut("Ctrl+Alt+G"),
-        shortcutShell: formatShortcut("Ctrl+Alt+B"),
-    });
-    let loadedPreferences = loadEffectiveGSDPreferences();
-    try {
-        const { markCmuxPromptShown, shouldPromptToEnableCmux } = await import("../../cmux/index.js");
-        if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
-            markCmuxPromptShown();
-            if (autoEnableCmuxPreferences()) {
-                loadedPreferences = loadEffectiveGSDPreferences();
-                ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
-            }
+async function runSessionStartupMaintenanceOnce(basePath, ctx) {
+    const maintenanceKey = getContextMaintenanceKey(basePath, ctx);
+    if (contextMaintenanceCompletedForSession.has(maintenanceKey)) {
+        // Backfills are session-once, but memory queries and other DB-backed
+        // prompt assembly still need an active adapter on every turn.
+        try {
+            const { ensureDbOpen } = await import("./dynamic-tools.js");
+            await ensureDbOpen(basePath);
         }
+        catch (e) {
+            logWarning("bootstrap", `project DB open failed: ${e.message}`);
+        }
+        return false;
+    }
+    const existing = contextMaintenanceInFlightBySession.get(maintenanceKey);
+    const isInitiator = !existing;
+    // Use a definite Promise<boolean> so `await inFlight` has a known return type.
+    let inFlight;
+    if (isInitiator) {
+        inFlight = performSessionStartupMaintenance(basePath, ctx, maintenanceKey);
+        contextMaintenanceInFlightBySession.set(maintenanceKey, inFlight);
+        void inFlight.finally(() => {
+            if (contextMaintenanceInFlightBySession.get(maintenanceKey) === inFlight) {
+                contextMaintenanceInFlightBySession.delete(maintenanceKey);
+            }
+        });
+    }
+    else {
+        inFlight = existing;
+    }
+    const result = await inFlight;
+    return isInitiator ? result : false;
+}
+async function performSessionStartupMaintenance(basePath, ctx, maintenanceKey) {
+    // DB-backed memory backfills run below. On a cold session the database file
+    // may exist without an active in-process adapter, so open the canonical
+    // project DB before those best-effort operations inspect it.
+    let dbOpen = false;
+    try {
+        const { ensureDbOpen } = await import("./dynamic-tools.js");
+        dbOpen = await ensureDbOpen(basePath);
     }
     catch (e) {
-        logWarning("bootstrap", `cmux prompt setup skipped: ${e.message}`);
+        logWarning("bootstrap", `project DB open failed before memory projection: ${e.message}`);
+    }
+    if (!dbOpen)
+        return false;
+    // These backfills are independent idempotent migrations. Keep them on the
+    // startup path because their rows can affect the MEMORY block for this turn,
+    // but do not make their import/IO latencies add serially.
+    await Promise.allSettled([
+        runDecisionsMemoryBackfill(ctx),
+        runKnowledgeMemoryBackfill(basePath, ctx),
+    ]);
+    // Mark session complete before scheduling deferred work so any concurrent
+    // caller that observes the completed state does not re-enter maintenance.
+    contextMaintenanceCompletedForSession.add(maintenanceKey);
+    scheduleDeferredContextMaintenance(basePath, maintenanceKey);
+    return true;
+}
+function getContextMaintenanceKey(basePath, ctx) {
+    return `${basePath}${CONTEXT_MAINTENANCE_KEY_SEPARATOR}${getContextSessionPart(ctx)}`;
+}
+function getContextSessionPart(ctx) {
+    const sessionManager = ctx.sessionManager;
+    try {
+        const sessionId = sessionManager?.getSessionId?.();
+        if (typeof sessionId === "string" && sessionId.length > 0)
+            return `id:${sessionId}`;
     }
-    const ctxProjectRoot = ctx.projectRoot;
-    const basePath = typeof ctxProjectRoot === "string" && ctxProjectRoot.length > 0
-        ? ctxProjectRoot
-        : process.cwd();
-    let preferenceBlock = "";
-    if (loadedPreferences) {
-        const cwd = basePath;
-        const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
-        preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions, { includeResolvedPaths: false })}`;
-        if (report.warnings.length > 0) {
-            ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
-        }
+    catch (e) {
+        logWarning("bootstrap", `session-id fetch failed: ${e.message}`);
+    }
+    try {
+        const sessionFile = sessionManager?.getSessionFile?.();
+        if (typeof sessionFile === "string" && sessionFile.length > 0)
+            return `file:${sessionFile}`;
     }
+    catch (e) {
+        logWarning("bootstrap", `session-file fetch failed: ${e.message}`);
+    }
+    return "process";
+}
+async function runDecisionsMemoryBackfill(ctx) {
     // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
     // and best-effort — first run absorbs the existing decisions table into
-    // the memory store; subsequent runs are a single sentinel SELECT.
+    // the memory store; repeated turns skip this session-once maintenance.
     try {
         const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
         const written = backfillDecisionsToMemories();
@@ -127,10 +197,11 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
-    // ADR-013 Stage 2b: KNOWLEDGE.md Patterns + Lessons backfill, then
-    // re-render the hybrid projection (manual Rules + projected Patterns +
-    // projected Lessons). Both are idempotent and best-effort — failures here
-    // can't block agent startup.
+}
+async function runKnowledgeMemoryBackfill(basePath, ctx) {
+    // ADR-013 Stage 2b: KNOWLEDGE.md Patterns + Lessons backfill. Idempotent
+    // and best-effort — first run migrates rows into memories; repeated turns
+    // skip this session-once maintenance.
     try {
         const { backfillKnowledgeToMemories } = await import("../knowledge-backfill.js");
         const writtenK = backfillKnowledgeToMemories(basePath);
@@ -141,6 +212,32 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `KNOWLEDGE.md backfill failed: ${e.message}`);
     }
+}
+function scheduleDeferredContextMaintenance(basePath, maintenanceKey) {
+    if (deferredContextMaintenanceBySession.has(maintenanceKey))
+        return;
+    const task = new Promise((resolve) => {
+        setTimeout(() => {
+            void runDeferredContextMaintenance(basePath).finally(resolve);
+        }, 0);
+    });
+    deferredContextMaintenanceBySession.set(maintenanceKey, task);
+    void task.finally(() => {
+        if (deferredContextMaintenanceBySession.get(maintenanceKey) === task) {
+            deferredContextMaintenanceBySession.delete(maintenanceKey);
+        }
+    });
+}
+async function runDeferredContextMaintenance(basePath) {
+    // Projection rendering and consolidation-gap reporting do not contribute to
+    // the returned system prompt. Run them after startup context is assembled so
+    // their DB/file scans do not block the first response.
+    await Promise.allSettled([
+        renderKnowledgeProjectionDeferred(basePath),
+        reportConsolidationGapsDeferred(basePath),
+    ]);
+}
+async function renderKnowledgeProjectionDeferred(basePath) {
     try {
         const { renderKnowledgeProjection } = await import("../knowledge-projection.js");
         renderKnowledgeProjection(basePath);
@@ -148,9 +245,8 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `KNOWLEDGE.md projection render failed: ${e.message}`);
     }
-    // ADR-013 step 6 preflight: warn when decisions / KNOWLEDGE.md rows are not
-    // yet in the memories table. Read-only; never throws. Runs after the two
-    // backfills above so the gap report reflects post-backfill state.
+}
+async function reportConsolidationGapsDeferred(basePath) {
     try {
         const { reportConsolidationGaps } = await import("../memory-consolidation-scanner.js");
         reportConsolidationGaps(basePath);
@@ -158,6 +254,52 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `memory consolidation scan failed: ${e.message}`);
     }
+}
+export async function _flushDeferredContextMaintenanceForTest(basePath) {
+    const tasks = basePath
+        ? [...deferredContextMaintenanceBySession.entries()]
+            .filter(([key]) => key.startsWith(`${basePath}${CONTEXT_MAINTENANCE_KEY_SEPARATOR}`))
+            .map(([, task]) => task)
+        : [...deferredContextMaintenanceBySession.values()];
+    await Promise.allSettled(tasks);
+}
+export async function buildBeforeAgentStartResult(event, ctx) {
+    if (!existsSync(join(process.cwd(), ".gsd")))
+        return undefined;
+    const stopContextTimer = debugTime("context-inject");
+    const systemContent = loadPrompt("system", {
+        templatesDir: getTemplatesDir(),
+        shortcutDashboard: formatShortcut("Ctrl+Alt+G"),
+        shortcutShell: formatShortcut("Ctrl+Alt+B"),
+    });
+    let loadedPreferences = loadEffectiveGSDPreferences();
+    try {
+        const { markCmuxPromptShown, shouldPromptToEnableCmux } = await import("../../cmux/index.js");
+        if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+            markCmuxPromptShown();
+            if (autoEnableCmuxPreferences()) {
+                loadedPreferences = loadEffectiveGSDPreferences();
+                ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
+            }
+        }
+    }
+    catch (e) {
+        logWarning("bootstrap", `cmux prompt setup skipped: ${e.message}`);
+    }
+    const ctxProjectRoot = ctx.projectRoot;
+    const basePath = typeof ctxProjectRoot === "string" && ctxProjectRoot.length > 0
+        ? ctxProjectRoot
+        : process.cwd();
+    let preferenceBlock = "";
+    if (loadedPreferences) {
+        const cwd = basePath;
+        const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
+        preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions, { includeResolvedPaths: false })}`;
+        if (report.warnings.length > 0) {
+            ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
+        }
+    }
+    await runSessionStartupMaintenanceOnce(basePath, ctx);
     const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), basePath);
     if (globalSizeKb > 4) {
         ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
@@ -180,16 +322,21 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     const rawCodebase = readCodebaseMap(process.cwd());
     if (existsSync(codebasePath) && rawCodebase) {
         try {
-            const rawContent = rawCodebase.trim();
+            // Strip the volatile `Generated: <timestamp>` header line and the
+            // machine-readable `gsd:codebase-meta` comment before injecting. Both
+            // embed a per-regeneration timestamp/fingerprint; because this block
+            // rides the cached system-prompt prefix, leaving the timestamp in would
+            // invalidate the provider KV cache on every map refresh even when the
+            // file structure is unchanged. The full map (with timestamp) remains at
+            // .gsd/CODEBASE.md. (#847)
+            const rawContent = stripVolatileCodebaseMetadata(rawCodebase.trim());
             if (rawContent) {
                 // Cap injection size to ~2 000 tokens to avoid bloating every request.
                 // Full map is always available at .gsd/CODEBASE.md.
-                const generatedMatch = rawContent.match(/Generated: (\S+)/);
-                const generatedAt = generatedMatch?.[1] ?? "unknown";
                 const content = rawContent.length > DEFAULT_CODEBASE_MAX_CHARS
                     ? rawContent.slice(0, DEFAULT_CODEBASE_MAX_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
                     : rawContent;
-                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
+                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
             }
         }
         catch (e) {