@opengsd/gsd-pi 1.3.0 → 1.4.0

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -1,7 +1,7 @@
 // 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";
 
@@ -12,8 +12,8 @@ import { ALWAYS_PRESERVED_SHIM_TOOL_NAMES } from "@gsd/pi-ai";
 import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-extension-api.js";
 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, type WriteGateSnapshot } 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";
@@ -34,7 +34,8 @@ import {
 } 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";
@@ -75,6 +76,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;
 
@@ -178,22 +180,7 @@ export const MINIMAL_GSD_TOOL_NAMES = [
   "gsd_capture_thought",
 ] as const;
 
-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",
-] as const;
+export { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 
 function withPreservedShimTools(toolNames: readonly string[]): string[] {
   return [...new Set([...toolNames, ...ALWAYS_PRESERVED_SHIM_TOOL_NAMES])];
@@ -583,6 +570,10 @@ function deferApprovalGate(gateId: string, basePath: string): void {
   // 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: string, basePath: string, snapshot: WriteGateSnapshot): void {
   if (isApprovalGateVerifiedInSnapshot(snapshot, gateId)) return;
   const milestoneId = extractDepthVerificationMilestoneId(gateId);
   if (milestoneId && isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId)) return;
@@ -593,6 +584,21 @@ function contextBasePath(ctx?: { cwd?: string }): string {
   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: string | undefined): string | undefined {
+  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?: { cwd?: string },
 ): ReturnType<typeof getSourceObservationStore> | null {
@@ -680,7 +686,7 @@ function isContextDraftSummarySave(toolName: string, input: unknown): boolean {
 function resolveAskUserQuestionsGateDetails(event: { details?: unknown; result?: unknown }): any {
   const hasRoundShape = (value: any): boolean =>
     !!value && typeof value === "object" &&
-    (value.cancelled !== undefined || value.response !== undefined);
+    (value.cancelled !== undefined || value.timed_out !== undefined || value.response !== undefined);
 
   const details = event.details as any;
   if (hasRoundShape(details)) return details;
@@ -734,8 +740,21 @@ function formatQuestionExchange(
 }
 
 async function ensureMilestoneShell(basePath: string, milestoneId: string): Promise<string> {
+  // 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();
 
@@ -769,14 +788,20 @@ async function saveDiscussionQuestionRound(
   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: string): string =>
+    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
     ?? [
@@ -876,6 +901,40 @@ export function registerHooks(
     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");
@@ -1037,6 +1096,19 @@ export function registerHooks(
     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 {
       activateDeferredApprovalGate(agentEndBasePath);
@@ -1189,13 +1261,15 @@ export function registerHooks(
 
     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))) return;
-      deferApprovalGate(gateId, contextBasePath(ctx));
+      if (gateMilestoneId && isMilestoneDepthVerifiedInSnapshot(gateSnapshot, gateMilestoneId)) return;
+      deferApprovalGateFromSnapshot(gateId, basePath, gateSnapshot);
     }
 
     approvalQuestionAbortInFlight = true;
@@ -1241,7 +1315,7 @@ export function registerHooks(
     // ── Loop guard: block repeated identical tool calls ──
     const loopCheck = checkToolCallLoop(toolName, event.input as Record<string, unknown>);
     if (loopCheck.block) {
-      return { block: true, reason: loopCheck.reason };
+      return { block: true, reason: formatLoopGuardBlockReason(loopCheck.reason) };
     }
 
     const deferredGateGuard = shouldBlockDeferredApprovalTool(
@@ -1513,6 +1587,7 @@ export function registerHooks(
       }
     }
     if (!event.isError) {
+      recordToolCallLoopMutation(toolName);
       refreshSourceObservationAfterMutation(toolName, event.input, ctx);
       clearSourceObservationsAfterShell(toolName);
     }
@@ -1577,6 +1652,28 @@ export function registerHooks(
         }],
       };
     }
+    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" as const,
+          text: formatTimedOutAskUserQuestionsGateMessage(gateResult.pendingGateId),
+        }],
+      };
+    }
     if (gateResult.status === "verified") {
       clearDeferredApprovalGate(basePath);
     }
@@ -1600,6 +1697,21 @@ export function registerHooks(
       }
       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/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -28,6 +28,11 @@ 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<string>();
+const contextMaintenanceInFlightBySession = new Map<string, Promise<boolean>>();
+const deferredContextMaintenanceBySession = new Map<string, Promise<void>>();
+
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
  * hardcoding absolute paths in the system prompt template. Only skills
@@ -71,6 +76,25 @@ export const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> =
   { 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: string): string {
+  return content
+    .split("\n")
+    .filter((line) => {
+      const trimmed = line.trimStart();
+      return !trimmed.startsWith("Generated:") && !trimmed.startsWith("<!-- gsd:codebase-meta");
+    })
+    .join("\n")
+    .trim();
+}
+
 function warnDeprecatedAgentInstructions(): void {
   const paths = [
     join(gsdHome(), "agent-instructions.md"),
@@ -87,6 +111,191 @@ function warnDeprecatedAgentInstructions(): void {
   }
 }
 
+async function runSessionStartupMaintenanceOnce(
+  basePath: string,
+  ctx: ExtensionContext,
+): Promise<boolean> {
+  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 as Error).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: Promise<boolean>;
+  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: string,
+  ctx: ExtensionContext,
+  maintenanceKey: string,
+): Promise<boolean> {
+  // 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", `project DB open failed before memory projection: ${(e as Error).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: string, ctx: ExtensionContext): string {
+  return `${basePath}${CONTEXT_MAINTENANCE_KEY_SEPARATOR}${getContextSessionPart(ctx)}`;
+}
+
+function getContextSessionPart(ctx: ExtensionContext): string {
+  const sessionManager = (ctx as {
+    sessionManager?: {
+      getSessionId?: () => string | undefined;
+      getSessionFile?: () => string | undefined;
+    };
+  }).sessionManager;
+
+  try {
+    const sessionId = sessionManager?.getSessionId?.();
+    if (typeof sessionId === "string" && sessionId.length > 0) return `id:${sessionId}`;
+  } catch (e) {
+    logWarning("bootstrap", `session-id fetch failed: ${(e as Error).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 as Error).message}`);
+  }
+
+  return "process";
+}
+
+async function runDecisionsMemoryBackfill(ctx: ExtensionContext): Promise<void> {
+  // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
+  // and best-effort — first run absorbs the existing decisions table into
+  // the memory store; repeated turns skip this session-once maintenance.
+  try {
+    const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
+    const written = backfillDecisionsToMemories();
+    if (written > 0) {
+      ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store.`, "info");
+    }
+  } catch (e) {
+    logWarning("bootstrap", `decisions backfill failed: ${(e as Error).message}`);
+  }
+}
+
+async function runKnowledgeMemoryBackfill(
+  basePath: string,
+  ctx: ExtensionContext,
+): Promise<void> {
+  // 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);
+    if (writtenK > 0) {
+      ctx.ui.notify(`GSD: backfilled ${writtenK} KNOWLEDGE.md row${writtenK === 1 ? "" : "s"} into the memory store.`, "info");
+    }
+  } catch (e) {
+    logWarning("bootstrap", `KNOWLEDGE.md backfill failed: ${(e as Error).message}`);
+  }
+}
+
+function scheduleDeferredContextMaintenance(basePath: string, maintenanceKey: string): void {
+  if (deferredContextMaintenanceBySession.has(maintenanceKey)) return;
+
+  const task = new Promise<void>((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: string): Promise<void> {
+  // 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: string): Promise<void> {
+  try {
+    const { renderKnowledgeProjection } = await import("../knowledge-projection.js");
+    renderKnowledgeProjection(basePath);
+  } catch (e) {
+    logWarning("bootstrap", `KNOWLEDGE.md projection render failed: ${(e as Error).message}`);
+  }
+}
+
+async function reportConsolidationGapsDeferred(basePath: string): Promise<void> {
+  try {
+    const { reportConsolidationGaps } = await import("../memory-consolidation-scanner.js");
+    reportConsolidationGaps(basePath);
+  } catch (e) {
+    logWarning("bootstrap", `memory consolidation scan failed: ${(e as Error).message}`);
+  }
+}
+
+export async function _flushDeferredContextMaintenanceForTest(basePath?: string): Promise<void> {
+  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: { prompt: string; systemPrompt: string },
   ctx: ExtensionContext,
@@ -134,48 +343,7 @@ export async function buildBeforeAgentStartResult(
     }
   }
 
-  // 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.
-  try {
-    const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
-    const written = backfillDecisionsToMemories();
-    if (written > 0) {
-      ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store.`, "info");
-    }
-  } catch (e) {
-    logWarning("bootstrap", `decisions backfill failed: ${(e as Error).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.
-  try {
-    const { backfillKnowledgeToMemories } = await import("../knowledge-backfill.js");
-    const writtenK = backfillKnowledgeToMemories(basePath);
-    if (writtenK > 0) {
-      ctx.ui.notify(`GSD: backfilled ${writtenK} KNOWLEDGE.md row${writtenK === 1 ? "" : "s"} into the memory store.`, "info");
-    }
-  } catch (e) {
-    logWarning("bootstrap", `KNOWLEDGE.md backfill failed: ${(e as Error).message}`);
-  }
-  try {
-    const { renderKnowledgeProjection } = await import("../knowledge-projection.js");
-    renderKnowledgeProjection(basePath);
-  } catch (e) {
-    logWarning("bootstrap", `KNOWLEDGE.md projection render failed: ${(e as Error).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.
-  try {
-    const { reportConsolidationGaps } = await import("../memory-consolidation-scanner.js");
-    reportConsolidationGaps(basePath);
-  } catch (e) {
-    logWarning("bootstrap", `memory consolidation scan failed: ${(e as Error).message}`);
-  }
+  await runSessionStartupMaintenanceOnce(basePath, ctx);
 
   const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), basePath);
   if (globalSizeKb > 4) {
@@ -203,16 +371,21 @@ export async function buildBeforeAgentStartResult(
   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) {
       logWarning("bootstrap", `CODEBASE file read failed: ${(e as Error).message}`);

package/src/resources/extensions/gsd/bootstrap/tests/write-gate-basepath.test.ts

@@ -9,13 +9,14 @@
 
 import { test, describe, before, after } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { mkdtempSync, rmSync, existsSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import {
   markDepthVerified,
   loadWriteGateSnapshot,
+  shouldBlockContextArtifactSaveInSnapshot,
   clearDiscussionFlowState,
 } from "../write-gate.js";
 
@@ -100,4 +101,51 @@ describe("write-gate basePath regression", () => {
       "loadWriteGateSnapshot(baseDirB) must not bleed state from baseDirA",
     );
   });
+
+  test("worktree basePath reads depth verification from project-root snapshot", (t) => {
+    const prev = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    t.after(() => {
+      if (prev === undefined) {
+        delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+      } else {
+        process.env.GSD_PERSIST_WRITE_GATE_STATE = prev;
+      }
+    });
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
+
+    const projectRoot = makeTempDir();
+    const worktreePath = join(projectRoot, ".gsd-worktrees", "M020");
+    t.after(() => {
+      rmSync(projectRoot, { recursive: true, force: true });
+    });
+
+    clearDiscussionFlowState(projectRoot);
+    clearDiscussionFlowState(worktreePath);
+
+    // Simulate MCP routing: verification recorded at project root.
+    markDepthVerified("M020", projectRoot);
+
+    // Worktree has a local .gsd projection but no write-gate snapshot file.
+    mkdirSync(join(worktreePath, ".gsd", "runtime"), { recursive: true });
+    mkdirSync(join(projectRoot, ".gsd", "milestones"), { recursive: true });
+
+    const projectSnapshotPath = join(projectRoot, ".gsd", "runtime", "write-gate-state.json");
+    const worktreeSnapshotPath = join(worktreePath, ".gsd", "runtime", "write-gate-state.json");
+    assert.ok(existsSync(projectSnapshotPath), "verification snapshot lives at project root");
+    assert.ok(!existsSync(worktreeSnapshotPath), "worktree must not have its own snapshot file");
+
+    const snapshotFromWorktree = loadWriteGateSnapshot(worktreePath);
+    assert.ok(
+      snapshotFromWorktree.verifiedDepthMilestones.includes("M020"),
+      "loadWriteGateSnapshot(worktree) must inherit project-root verification",
+    );
+
+    const guard = shouldBlockContextArtifactSaveInSnapshot(
+      snapshotFromWorktree,
+      "CONTEXT",
+      "M020",
+      null,
+    );
+    assert.equal(guard.block, false, "CONTEXT save must unblock once project-root gate is verified");
+  });
 });