@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.5fc22c6f

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");
+  });
 });

package/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts

@@ -1,18 +1,32 @@
 /**
  * Tool-call loop guard.
  *
- * Detects when a model calls the same tool with identical arguments
- * repeatedly within a single agent turn. Works in both auto-mode and
- * interactive sessions by hooking into the `tool_call` event, which
- * fires before execution and can block the call.
+ * Detects when a model repeats tool calls within a single Agent Turn.
+ * Works in both auto-mode and interactive sessions by hooking into the
+ * native engine's `tool_call` event, which fires before execution and can
+ * block the call.
  *
- * The guard uses a sliding window: it tracks the last N tool signatures
- * and blocks when the same signature appears more than MAX_CONSECUTIVE
- * times in a row. Resets on each agent turn (session_start, agent_end)
- * and when a different tool call breaks the streak.
+ * The guard has two independent checks: a sliding window for identical
+ * tool signatures, and a per-tool-name cap for repeated calls with varied
+ * arguments. State resets at Agent Turn boundaries (session_start,
+ * agent_end) and the identical-signature streak also resets when a
+ * different tool call breaks the streak. Block messages instruct the model
+ * to stop tooling for the rest of that turn and answer in text.
+ *
+ * The per-tool-name check (#783 Brief C) tracks call counts within a
+ * turn regardless of args, decaying after successful state-mutating tools.
+ * This catches improvisation
+ * loops where the model attempts the same missing workflow tool through
+ * varied surfaces (bash → `node -e` → CLI), each with a different
+ * signature, so the identical-args streak never trips, while allowing
+ * tool-heavy turns that are making file-mutation progress. Whichever guard
+ * trips first blocks.
  */
 
 import { createHash } from "node:crypto";
+import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
 
 const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 
@@ -20,11 +34,31 @@ const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
 const MAX_CONSECUTIVE_STRICT = 1;
 
+/**
+ * Per-turn cap on calls to the SAME tool name, regardless of args (#783).
+ *
+ * General-purpose execution tools are routinely called many times per turn
+ * (touching multiple files, running several commands), so they get a higher
+ * ceiling. Everything else — workflow one-shot tools (e.g. gsd_complete_milestone)
+ * and any non-allowlisted tool — gets the default cap. The default is generous
+ * enough to absorb legitimate retries but catches the reported improvisation
+ * loop (~51 calls) well before a cost spike.
+ */
+const PER_TOOL_DEFAULT_CAP = 6;
+const PER_TOOL_REPEATABLE_CAP = 15;
+const PER_TOOL_CAP_EXEMPT_TOOLS = new Set(["find", "glob", "grep", "ls", "read", "search_and_read"]);
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
+
 let consecutiveCount = 0;
 let lastSignature = "";
 let lastToolName = "";
 let enabled = true;
 
+/** Per-tool-name call counts within the current turn (#783 Brief C). */
+const perToolCounts = new Map<string, number>();
+let mutationEpoch = 0;
+const perToolLastMutationEpoch = new Map<string, number>();
+
 /** Hash tool name + args into a compact signature for comparison. */
 function hashToolCall(toolName: string, args: Record<string, unknown>): string {
   const h = createHash("sha256");
@@ -46,6 +80,13 @@ function hashToolCall(toolName: string, args: Record<string, unknown>): string {
  *
  * Returns `{ block: false }` for allowed calls.
  * Returns `{ block: true, reason }` when the loop threshold is exceeded.
+ *
+ * Two independent guards run; whichever trips first blocks:
+ *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
+ *     ask_user_questions).
+ *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
+ *     independent of args, reset after file-mutation progress — catches
+ *     improvisation loops (#783).
  */
 export function checkToolCallLoop(
   toolName: string,
@@ -63,6 +104,7 @@ export function checkToolCallLoop(
     lastToolName = toolName;
   }
 
+  // ── Guard 1: identical-signature streak ──
   const threshold = STRICT_LOOP_TOOLS.has(toolName)
     ? MAX_CONSECUTIVE_STRICT
     : MAX_CONSECUTIVE_IDENTICAL_CALLS;
@@ -71,22 +113,73 @@ export function checkToolCallLoop(
     return {
       block: true,
       reason:
-        `Tool loop detected: ${toolName} called ${consecutiveCount} times ` +
+        `Tool loop detected (identical args): ${toolName} called ${consecutiveCount} times ` +
         `with identical arguments. Blocking to prevent infinite loop. ` +
-        `Try a different approach or modify your arguments.`,
+        `Do not retry this tool or call other tools this turn — stop and respond to the user in text.`,
       count: consecutiveCount,
     };
   }
 
+  // ── Guard 2: per-tool-name cap, independent of args (#783 Brief C) ──
+  // Catches improvisation loops where the same tool is invoked many times with
+  // varied args (e.g. retrying a missing workflow tool via bash/node -e/CLI).
+  const priorPerToolCount =
+    (perToolLastMutationEpoch.get(toolName) ?? mutationEpoch) < mutationEpoch
+      ? 0
+      : (perToolCounts.get(toolName) ?? 0);
+  const perToolCount = priorPerToolCount + 1;
+  perToolCounts.set(toolName, perToolCount);
+  perToolLastMutationEpoch.set(toolName, mutationEpoch);
+
+  // Read-only navigation tools are normal context gathering; Guard 1 still
+  // catches true reread loops with identical arguments. Browser Automation
+  // Contract tools (browser_*) are the same shape: a browser-backed UAT makes
+  // many distinct-arg calls (read a message, count edits, inspect a card, …),
+  // so the arg-independent per-tool cap misfires on legitimate verification;
+  // Guard 1's identical-signature streak still catches a genuinely stuck
+  // browser loop.
+  if (
+    PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName) ||
+    hasBrowserContractPrefix(canonicalToolName(toolName))
+  ) {
+    return { block: false, count: consecutiveCount };
+  }
+
+  const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
+    ? PER_TOOL_REPEATABLE_CAP
+    : PER_TOOL_DEFAULT_CAP;
+
+  if (perToolCount > perToolCap) {
+    return {
+      block: true,
+      reason:
+        `Tool loop detected (repeated tool): ${toolName} called ${perToolCount} times ` +
+        `this turn (cap ${perToolCap}). Blocking to prevent infinite loop. ` +
+        `The tool may be unavailable or failing repeatedly. ` +
+        `Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.`,
+      count: perToolCount,
+    };
+  }
+
   return { block: false, count: consecutiveCount };
 }
 
+/** Record successful mutation progress so Guard 2 can decay on the next count. */
+export function recordToolCallLoopMutation(toolName: string): void {
+  if (!enabled) return;
+  if (!STATE_MUTATING_TOOL_SET.has(toolName)) return;
+  mutationEpoch++;
+}
+
 /** Reset the guard state. Call at agent turn boundaries. */
 export function resetToolCallLoopGuard(): void {
   consecutiveCount = 0;
   lastSignature = "";
   lastToolName = "";
   enabled = true;
+  perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Disable the guard (e.g. during shutdown). */
@@ -95,9 +188,20 @@ export function disableToolCallLoopGuard(): void {
   consecutiveCount = 0;
   lastSignature = "";
   lastToolName = "";
+  perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Get current consecutive count for diagnostics. */
 export function getToolCallLoopCount(): number {
   return consecutiveCount;
 }
+
+/**
+ * Get the per-tool-name call count for the current turn (#783 Brief C).
+ * Returns 0 for tools not yet called. Diagnostic only.
+ */
+export function getToolCallCountForTool(toolName: string): number {
+  return perToolCounts.get(toolName) ?? 0;
+}

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.
 	}
 }