@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

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

@@ -16,7 +16,7 @@ import { registerScheduleWakeupTool } from "./schedule-wakeup-tool.js";
 import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
-import { logWarning } from "../workflow-logger.js";
+import { logWarning, isGsdExtensionStderrEnabled } from "../workflow-logger.js";
 import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.js";
 // Static import so cmux event listeners are registered synchronously during
 // extension bootstrap. Prior implementation used `void import().then()` which
@@ -47,6 +47,7 @@ export const CRITICAL_GSD_WORKFLOW_TOOL_NAMES = [...new Set(
 /** Write to stderr without ever re-throwing — stderr can EPIPE too, which would
  *  re-enter this handler and re-loop. */
 function safeStderr(msg: string): void {
+  if (!isGsdExtensionStderrEnabled()) return;
   try {
     process.stderr.write(msg);
   } catch { /* stderr is also broken; nothing we can do */ }
@@ -140,10 +141,30 @@ export function installEpipeGuard(): void {
   }
 }
 
+/**
+ * Assert that critical GSD workflow tools were registered.
+ *
+ * During extension loading, getAllTools() is a throwing stub
+ * ("Extension runtime not initialized") that only becomes real after
+ * runner.bindCore(). Calling it here used to throw, propagating to index.ts's
+ * catch and firing "Extension setup partially failed" — which, under Claude
+ * Code CLI, left the model's tool surface incomplete and trapped units in a
+ * finalize-retry loop. Tolerate the pre-bind throw and defer the real check to
+ * the first before_agent_start (where applyMinimalGsdToolSurface already
+ * re-reads the registered surface post-bind).
+ */
 function assertCriticalGsdWorkflowToolsRegistered(pi: ExtensionAPI): void {
   if (typeof pi.getAllTools !== "function") return;
 
-  const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+  let registered: Set<string>;
+  try {
+    registered = new Set(pi.getAllTools().map((tool) => tool.name));
+  } catch {
+    // Pre-bind runtime: getAllTools() is not yet wired. The critical-tools
+    // invariant is re-checked post-bind during the first before_agent_start.
+    return;
+  }
+
   const missing = CRITICAL_GSD_WORKFLOW_TOOL_NAMES.filter((toolName) => !registered.has(toolName));
   if (missing.length === 0) return;
 

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, 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, formatPendingAskUserQuestionsGateMessage, formatTimedOutAskUserQuestionsGateMessage, hostWriteGateAdapter, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerified, 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";
@@ -46,7 +46,7 @@ import {
   isDestructiveConfirmGateId,
   requestDestructiveConfirmation,
 } from "../safety/destructive-confirmation.js";
-import { logWarning as safetyLogWarning } from "../workflow-logger.js";
+import { logWarning as safetyLogWarning, setStderrLoggingEnabled } from "../workflow-logger.js";
 import { isUnitCloseoutTool, runInteractiveUnitCloseout } from "../unit-closeout.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
@@ -148,6 +148,15 @@ async function installWelcomeHeader(ctx: ExtensionContext): Promise<void> {
   }
 }
 
+/** Suppress the startup welcome banner without restoring the built-in pi header. */
+function suppressWelcomeHeader(ctx: ExtensionContext): void {
+  if (!ctx.hasUI || typeof ctx.ui?.setHeader !== "function") return;
+  ctx.ui.setHeader(() => ({
+    render(): string[] { return []; },
+    invalidate(): void {},
+  }));
+}
+
 /**
  * Approval gates whose durable arming is deferred until tool execution /
  * agent end, keyed by basePath. A Map (not a single slot) so concurrent
@@ -671,7 +680,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;
@@ -725,8 +734,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();
 
@@ -760,14 +782,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
     ?? [
@@ -819,6 +847,9 @@ function initSessionNotifications(ctx: ExtensionContext): void {
   installNotifyInterceptor(ctx);
   initNotificationWidget(ctx);
   notifyPreferenceDiagnostics(ctx, contextBasePath(ctx), { surface: "session-start" });
+  if (ctx.hasUI) {
+    setStderrLoggingEnabled(false);
+  }
 }
 
 async function prepareWorkflowMcpForHookContext(
@@ -864,6 +895,31 @@ 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",
+            );
+          }
+        }
+      }
+    } 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");
@@ -871,7 +927,14 @@ export function registerHooks(
       process.env.GSD_SHOW_TOKEN_COST = prefs?.preferences.show_token_cost ? "1" : "";
     } catch { /* non-fatal */ }
     if (!preserveCloseoutSurface) {
-      await installWelcomeHeader(ctx);
+      // Per-unit newSession() during auto/step runs fires session_start again.
+      // Keep the welcome banner startup-only — do not overwrite the empty header
+      // that updateProgressWidget installs once work begins.
+      if (isAutoActive() || isAutoPaused()) {
+        suppressWelcomeHeader(ctx);
+      } else {
+        await installWelcomeHeader(ctx);
+      }
     }
     await loadToolApiKeysForSession();
     if (isAutoActive() || preserveCloseoutSurface) {
@@ -1033,6 +1096,10 @@ export function registerHooks(
   pi.on("message_end", async (event) => {
     const { suppressTerminalDeletedWorktreeMessageEnd } = await import("./agent-end-recovery.js");
     suppressTerminalDeletedWorktreeMessageEnd(event);
+    if (isAutoActive()) {
+      const { sanitizePrematureCloseoutMessageEnd } = await import("../auto-closeout-messaging.js");
+      sanitizePrematureCloseoutMessageEnd(event);
+    }
   });
 
   // Squash-merge quick-task branch back to the original branch after the
@@ -1364,6 +1431,16 @@ export function registerHooks(
       if (wtGuard.block) return wtGuard;
     }
 
+    if (isToolCallEventType("bash", event)) {
+      const wtBashGuard = shouldBlockWorktreeBash(
+        event.input.command,
+        dash.basePath ?? discussionBasePath,
+        isAutoActive(),
+        dash.currentUnit?.type,
+      );
+      if (wtBashGuard.block) return wtBashGuard;
+    }
+
     // ── Single-writer engine: block direct writes to STATE.md ──────────
     // Covers write, edit, and bash tools to prevent bypass vectors.
     if (isToolCallEventType("write", event)) {
@@ -1544,6 +1621,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);
     }
@@ -1567,6 +1666,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,10 @@ const DEFAULT_CODEBASE_MAX_CHARS = 8_000;
 const MIN_CONTEXT_MESSAGE_MAX_CHARS = 1_000;
 const MIN_KNOWLEDGE_MAX_CHARS = 1_000;
 
+const contextMaintenanceCompletedForBasePath = new Set<string>();
+const contextMaintenanceInFlightByBasePath = new Map<string, Promise<boolean>>();
+const deferredContextMaintenanceByBasePath = 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 +75,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 +110,158 @@ function warnDeprecatedAgentInstructions(): void {
   }
 }
 
+async function runSessionStartupMaintenanceOnce(
+  basePath: string,
+  ctx: ExtensionContext,
+): Promise<boolean> {
+  if (contextMaintenanceCompletedForBasePath.has(basePath)) {
+    // 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 = contextMaintenanceInFlightByBasePath.get(basePath);
+  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);
+    contextMaintenanceInFlightByBasePath.set(basePath, inFlight);
+    void inFlight.finally(() => {
+      if (contextMaintenanceInFlightByBasePath.get(basePath) === inFlight) {
+        contextMaintenanceInFlightByBasePath.delete(basePath);
+      }
+    });
+  } else {
+    inFlight = existing;
+  }
+
+  const result = await inFlight;
+  return isInitiator ? result : false;
+}
+
+async function performSessionStartupMaintenance(
+  basePath: string,
+  ctx: ExtensionContext,
+): 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.
+  contextMaintenanceCompletedForBasePath.add(basePath);
+  scheduleDeferredContextMaintenance(basePath);
+  return true;
+}
+
+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): void {
+  if (deferredContextMaintenanceByBasePath.has(basePath)) return;
+
+  const task = new Promise<void>((resolve) => {
+    setTimeout(() => {
+      void runDeferredContextMaintenance(basePath).finally(resolve);
+    }, 0);
+  });
+
+  deferredContextMaintenanceByBasePath.set(basePath, task);
+  void task.finally(() => {
+    if (deferredContextMaintenanceByBasePath.get(basePath) === task) {
+      deferredContextMaintenanceByBasePath.delete(basePath);
+    }
+  });
+}
+
+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
+    ? [deferredContextMaintenanceByBasePath.get(basePath)].filter((task): task is Promise<void> => Boolean(task))
+    : [...deferredContextMaintenanceByBasePath.values()];
+  await Promise.allSettled(tasks);
+}
+
 export async function buildBeforeAgentStartResult(
   event: { prompt: string; systemPrompt: string },
   ctx: ExtensionContext,
@@ -134,48 +309,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 +337,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/tool-search-shim.ts

@@ -31,8 +31,26 @@ export function registerToolSearchShim(pi: ExtensionAPI): void {
 		},
 	});
 
-	const active = pi.getActiveTools();
-	if (!active.includes("ToolSearch")) {
-		pi.setActiveTools([...active, "ToolSearch"]);
+	// Ensure the shim is part of the active tool set. registerTool() is valid
+	// during extension loading, but getActiveTools()/setActiveTools() are stubs
+	// that throw "Extension runtime not initialized" until runner.bindCore() runs
+	// (after all registerExtension() calls return). When the throw was hit, the
+	// catch in register-extension.ts swallowed it — leaving the whole bootstrap
+	// partially failed and, under Claude Code CLI, the workflow tools could end
+	// up missing from the model's surface, which traps plan-milestone in a
+	// finalize-retry loop with no gsd_plan_milestone available.
+	//
+	// The activation here is also redundant post-bind: ToolSearch is in
+	// MINIMAL_AUTO_BASE_TOOL_NAMES, so buildMinimalAutoGsdToolSet adds it during
+	// adjust_tool_set (before_agent_start). Tolerate the loading-stub throw so
+	// the shim always registers; activation is completed by post-bind scoping.
+	try {
+		const active = pi.getActiveTools();
+		if (!active.includes("ToolSearch")) {
+			pi.setActiveTools([...active, "ToolSearch"]);
+		}
+	} catch {
+		// Pre-bind runtime: getActiveTools/setActiveTools are not yet wired.
+		// The tool is registered; activation happens at adjust_tool_set.
 	}
 }