gsd-pi 2.76.0-dev.82e249f7b → 2.76.0-dev.97807402

package/src/resources/extensions/gsd/tests/stash-queued-context-files.test.ts

@@ -378,3 +378,59 @@ test("#2505: back-to-back merges preserve queued CONTEXT files", () => {
     rmSync(repo, { recursive: true, force: true });
   }
 });
+
+// #4573: When `.gsd` is a gitignored symlink (ADR-002 layout) and the project
+// `.gitignore` contains `.gsd`, `git stash push --include-untracked -- <pathspec>`
+// fatals with "The following paths are ignored by one of your .gitignore files".
+// The prior tests used a symlinked `.gsd` but no `.gitignore`, so this failure
+// mode was invisible to CI. Fixture must include BOTH the symlink AND the
+// ignore rule to reproduce the bug on pre-fix code.
+test("#4573: gitignored .gsd symlink does not break pre-merge stash", () => {
+  const repo = realpathSync(mkdtempSync(join(tmpdir(), "wt-4573-ignored-symlink-")));
+  const stateDir = realpathSync(mkdtempSync(join(tmpdir(), "wt-4573-state-")));
+  try {
+    run("git init", repo);
+    run("git config user.email test@test.com", repo);
+    run("git config user.name Test", repo);
+    writeFileSync(join(repo, "README.md"), "# test\n");
+    // Matches what BASELINE_PATTERNS in gitignore.ts writes for real projects.
+    writeFileSync(join(repo, ".gitignore"), ".gsd\n.gsd-id\n");
+    symlinkSync(stateDir, join(repo, ".gsd"));
+    run("git add README.md .gitignore", repo);
+    run("git commit -m init", repo);
+    run("git branch -M main", repo);
+
+    const wtPath = createAutoWorktree(repo, "M001");
+    const worktreeName = wtPath.replaceAll("\\", "/").split("/").pop() || "M001";
+    const sliceBranch = `slice/${worktreeName}/S01`;
+    run(`git checkout -b "${sliceBranch}"`, wtPath);
+    writeFileSync(join(wtPath, "app.ts"), "export const app = true;\n");
+    run("git add app.ts", wtPath);
+    run('git commit -m "add feature"', wtPath);
+    run("git checkout milestone/M001", wtPath);
+    run(`git merge --no-ff "${sliceBranch}" -m "merge S01"`, wtPath);
+
+    // Dirty a tracked file so the pre-merge stash branch actually runs.
+    writeFileSync(join(repo, "README.md"), "# test\n\nDirty.\n");
+
+    const result = mergeMilestoneToMain(
+      repo,
+      "M001",
+      makeRoadmap("M001", "Feature", [{ id: "S01", title: "Feature" }]),
+    );
+
+    assert.ok(
+      result.commitMessage.includes("GSD-Milestone: M001"),
+      "merge must succeed despite gitignored .gsd symlink",
+    );
+    assert.ok(existsSync(join(repo, "app.ts")), "milestone code merged to main");
+    assert.equal(
+      lstatSync(join(repo, ".gsd")).isSymbolicLink(),
+      true,
+      ".gsd symlink remains in place",
+    );
+  } finally {
+    rmSync(repo, { recursive: true, force: true });
+    rmSync(stateDir, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/token-counter.test.ts

@@ -102,7 +102,8 @@ describe("token-counter: estimateTokensForProvider", () => {
 
 describe("token-counter: backward compatibility", () => {
   it("countTokensSync returns heuristic estimate when tiktoken is not loaded", () => {
-    // Without tiktoken loaded, countTokensSync falls back to ceil(len/4)
+    // Without tiktoken loaded, countTokensSync falls back to estimateTokensForProvider.
+    // With no provider (defaults to "unknown", ratio 4.0): ceil(100/4) = 25.
     const text = "A".repeat(100);
     const result = countTokensSync(text);
     // Either tiktoken is loaded (exact count) or heuristic (ceil(100/4) = 25)
@@ -127,3 +128,106 @@ describe("token-counter: backward compatibility", () => {
     assert.equal(result, 0);
   });
 });
+
+// ─── provider-aware fallback (issue #4529) ───────────────────────────────────
+// Regression tests: countTokens/countTokensSync must use provider-specific
+// ratios for their heuristic fallback, not a hardcoded GPT-4o / 4 divisor.
+
+describe("token-counter: provider-aware heuristic fallback", () => {
+  // These tests exercise the heuristic path (no tiktoken or before init).
+  // We call estimateTokensForProvider directly to validate expected values,
+  // then verify countTokens/countTokensSync return the same values when
+  // tiktoken is unavailable.
+
+  it("countTokensSync uses anthropic ratio (3.5) when provider is 'anthropic'", () => {
+    const text = "A".repeat(350);
+    // anthropic: ceil(350 / 3.5) = 100
+    // openai/unknown: ceil(350 / 4.0) = 88
+    // These are different — the provider must matter.
+    const anthropicEstimate = estimateTokensForProvider(text, "anthropic");
+    const unknownEstimate = estimateTokensForProvider(text, "unknown");
+    assert.equal(anthropicEstimate, 100, "anthropic ratio should give 100 tokens for 350 chars");
+    assert.equal(unknownEstimate, 88, "unknown ratio should give 88 tokens for 350 chars");
+    assert.notEqual(
+      anthropicEstimate,
+      unknownEstimate,
+      "anthropic and unknown estimates must differ — if they are equal the provider is being ignored",
+    );
+
+    // Actually call countTokensSync with the anthropic provider.
+    // When tiktoken is not loaded, this must return the provider-aware estimate (100).
+    // When tiktoken is loaded, it returns the tiktoken count (which is also > 0 and
+    // will be in the range [88, 120] for 350 "A" characters with cl100k_base).
+    const syncResult = countTokensSync(text, "anthropic");
+    assert.ok(typeof syncResult === "number", "countTokensSync must return a number");
+    assert.ok(syncResult > 0, "countTokensSync must return a positive count");
+    // If tiktoken is unavailable the result must exactly match the anthropic heuristic.
+    // If tiktoken is available we cannot assert the exact value, but we know it will
+    // not equal the unknown-provider heuristic (88) for 350 identical characters.
+    const tiktokenAvailable = syncResult !== anthropicEstimate;
+    if (!tiktokenAvailable) {
+      assert.equal(
+        syncResult,
+        anthropicEstimate,
+        `countTokensSync with 'anthropic' provider must return ${anthropicEstimate} (not the unknown-provider value ${unknownEstimate}) when tiktoken is unavailable`,
+      );
+    }
+  });
+
+  it("countTokens uses anthropic ratio when provider='anthropic' and tiktoken unavailable", async () => {
+    const text = "A".repeat(350);
+    // anthropic heuristic: ceil(350 / 3.5) = 100
+    // unknown/hardcoded-4 heuristic: ceil(350 / 4.0) = 88
+    const anthropicEstimate = estimateTokensForProvider(text, "anthropic"); // 100
+    const unknownEstimate = estimateTokensForProvider(text, "unknown");     // 88
+    const hardcodedFallback = Math.ceil(text.length / 4);                   // 88
+
+    // The anthropic heuristic must produce more tokens than the old /4 fallback.
+    assert.equal(anthropicEstimate, 100, "anthropic heuristic should give 100 tokens for 350 chars");
+    assert.ok(
+      anthropicEstimate > hardcodedFallback,
+      `anthropic estimate (${anthropicEstimate}) must exceed the hardcoded /4 fallback (${hardcodedFallback})`,
+    );
+    assert.notEqual(
+      anthropicEstimate,
+      unknownEstimate,
+      "anthropic and unknown estimates must differ — provider is being ignored if equal",
+    );
+
+    // Call countTokens with the anthropic provider and verify the result.
+    const result = await countTokens(text, "anthropic");
+    assert.ok(typeof result === "number", "should return a number");
+    assert.ok(result > 0, "should return a positive token count");
+
+    // When tiktoken is unavailable: result must equal the anthropic heuristic (100),
+    // NOT the unknown-provider heuristic (88). This is the core regression guard for #4529.
+    // When tiktoken IS available: result is the tiktoken count, which will differ from
+    // the heuristic — but it must never equal the wrong (unknown) heuristic for this text.
+    if (result === anthropicEstimate || result === unknownEstimate) {
+      // We are on the heuristic path — assert the correct provider ratio was used.
+      assert.equal(
+        result,
+        anthropicEstimate,
+        `countTokens with 'anthropic' provider returned ${result} but expected ${anthropicEstimate} (anthropic heuristic) not ${unknownEstimate} (unknown/hardcoded heuristic)`,
+      );
+    } else {
+      // tiktoken is active — result is an exact BPE count.
+      // For 350 identical "A" characters cl100k_base produces a count in [80, 130].
+      assert.ok(
+        result >= 80 && result <= 130,
+        `tiktoken count ${result} for 350 "A" chars is outside expected range [80, 130]`,
+      );
+    }
+  });
+
+  it("countTokens with provider='anthropic' yields more tokens than provider='openai' (heuristic)", () => {
+    const text = "A".repeat(400);
+    // anthropic: ceil(400/3.5) = 115, openai: ceil(400/4.0) = 100
+    const anthropic = estimateTokensForProvider(text, "anthropic");
+    const openai = estimateTokensForProvider(text, "openai");
+    assert.ok(
+      anthropic > openai,
+      `anthropic estimate (${anthropic}) must exceed openai estimate (${openai}) for same text`,
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/tool-compatibility.test.ts

@@ -14,6 +14,7 @@ import {
   isToolCompatibleWithProvider,
   filterToolsForProvider,
   adjustToolSet,
+  GROQ_MAX_TOOLS,
 } from "../model-router.js";
 
 import {
@@ -197,3 +198,109 @@ describe("adjustToolSet", () => {
     assert.deepEqual(removedTools, ["mcp_complex"]);
   });
 });
+
+// ─── GROQ_MAX_TOOLS constant ─────────────────────────────────────────────────
+
+describe("GROQ_MAX_TOOLS", () => {
+  test("equals 128", () => {
+    assert.equal(GROQ_MAX_TOOLS, 128);
+  });
+});
+
+// ─── Groq tool-count cap (#4376) ────────────────────────────────────────────
+
+describe("filterToolsForProvider — Groq 128-tool cap", () => {
+  beforeEach(() => {
+    resetToolCompatibilityRegistry();
+  });
+
+  test("does not cap when provider is not groq", () => {
+    const toolNames = Array.from({ length: 200 }, (_, i) => `tool_${i}`);
+    const { compatible, filtered } = filterToolsForProvider(toolNames, "openai-completions");
+    assert.equal(compatible.length, 200);
+    assert.equal(filtered.length, 0);
+  });
+
+  test("does not cap when <= 128 tools with groq provider", () => {
+    const toolNames = Array.from({ length: 128 }, (_, i) => `tool_${i}`);
+    const { compatible, filtered } = filterToolsForProvider(toolNames, "openai-completions", "groq");
+    assert.equal(compatible.length, 128);
+    assert.equal(filtered.length, 0);
+  });
+
+  test("caps to 128 when >128 tools with groq provider", () => {
+    const toolNames = Array.from({ length: 200 }, (_, i) => `tool_${i}`);
+    const { compatible, filtered } = filterToolsForProvider(toolNames, "openai-completions", "groq");
+    assert.equal(compatible.length, 128);
+    assert.equal(filtered.length, 72);
+  });
+
+  test("keeps the first 128 tools when capping", () => {
+    const toolNames = Array.from({ length: 200 }, (_, i) => `tool_${i}`);
+    const { compatible } = filterToolsForProvider(toolNames, "openai-completions", "groq");
+    assert.equal(compatible[0], "tool_0");
+    assert.equal(compatible[127], "tool_127");
+  });
+
+  test("trimmed tools appear in filtered list", () => {
+    const toolNames = Array.from({ length: 130 }, (_, i) => `tool_${i}`);
+    const { filtered } = filterToolsForProvider(toolNames, "openai-completions", "groq");
+    assert.equal(filtered.length, 2);
+    assert.equal(filtered[0], "tool_128");
+    assert.equal(filtered[1], "tool_129");
+  });
+
+  test("emits a warning when tools are trimmed", () => {
+    const warnings: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => { warnings.push(String(args[0])); };
+    try {
+      const toolNames = Array.from({ length: 129 }, (_, i) => `tool_${i}`);
+      filterToolsForProvider(toolNames, "openai-completions", "groq");
+      assert.equal(warnings.length, 1);
+      assert.ok(warnings[0].includes("128"), "warning mentions Groq limit");
+    } finally {
+      console.warn = original;
+    }
+  });
+
+  test("does not warn when tools are at the limit", () => {
+    const warnings: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => { warnings.push(String(args[0])); };
+    try {
+      const toolNames = Array.from({ length: 128 }, (_, i) => `tool_${i}`);
+      filterToolsForProvider(toolNames, "openai-completions", "groq");
+      assert.equal(warnings.length, 0);
+    } finally {
+      console.warn = original;
+    }
+  });
+});
+
+describe("adjustToolSet — Groq 128-tool cap", () => {
+  beforeEach(() => {
+    resetToolCompatibilityRegistry();
+  });
+
+  test("caps to 128 tools when provider is groq and >128 tools active", () => {
+    const toolNames = Array.from({ length: 150 }, (_, i) => `tool_${i}`);
+    const { toolNames: result, removedTools } = adjustToolSet(toolNames, "openai-completions", "groq");
+    assert.equal(result.length, 128);
+    assert.equal(removedTools.length, 22);
+  });
+
+  test("does not cap for non-groq providers even with >128 tools", () => {
+    const toolNames = Array.from({ length: 150 }, (_, i) => `tool_${i}`);
+    const { toolNames: result, removedTools } = adjustToolSet(toolNames, "openai-completions", "openai");
+    assert.equal(result.length, 150);
+    assert.equal(removedTools.length, 0);
+  });
+
+  test("does not cap when provider is omitted", () => {
+    const toolNames = Array.from({ length: 150 }, (_, i) => `tool_${i}`);
+    const { toolNames: result, removedTools } = adjustToolSet(toolNames, "openai-completions");
+    assert.equal(result.length, 150);
+    assert.equal(removedTools.length, 0);
+  });
+});

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmSync, readFileSync, existsSync, writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
@@ -11,7 +11,7 @@ import {
   _getAdapter,
   insertGateRow,
 } from "../gsd-db.ts";
-import { markDepthVerified, clearDiscussionFlowState } from "../bootstrap/write-gate.ts";
+import { markDepthVerified, clearDiscussionFlowState, loadWriteGateSnapshot } from "../bootstrap/write-gate.ts";
 import {
   executeCompleteMilestone,
   executePlanMilestone,
@@ -742,3 +742,66 @@ test("executeSummarySave leaves sibling CONTEXT-DRAFT intact for non-CONTEXT art
     cleanup(base);
   }
 });
+
+test("executeSummarySave CONTEXT HARD BLOCK clears after write-gate state file is deleted (#4343)", async () => {
+  const base = makeTmpBase();
+  const originalEnv = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+  process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
+  try {
+    openTestDb(base);
+    clearDiscussionFlowState();
+
+    // First call: CONTEXT artifact without depth verification → HARD BLOCK
+    const blocked = await inProjectDir(base, () => executeSummarySave({
+      milestone_id: "M001",
+      artifact_type: "CONTEXT",
+      content: "# Context\n\ncontent",
+    }, base));
+    assert.equal(blocked.isError, true, "should be blocked without depth verification");
+    assert.match(
+      blocked.content[0].text,
+      /HARD BLOCK/,
+      "blocked result should mention HARD BLOCK",
+    );
+
+    // Verify the state file was written (persist mode is active)
+    const stateFilePath = join(base, ".gsd", "runtime", "write-gate-state.json");
+    // The state file may or may not exist at this point (block doesn't write state).
+    // Write a fake state file simulating stale persisted block state.
+    mkdirSync(join(base, ".gsd", "runtime"), { recursive: true });
+    writeFileSync(stateFilePath, JSON.stringify({
+      verifiedDepthMilestones: [],
+      activeQueuePhase: false,
+      pendingGateId: "depth_verification_M001",
+    }));
+
+    // User deletes the state file to reset the block
+    unlinkSync(stateFilePath);
+    assert.ok(!existsSync(stateFilePath), "state file deleted");
+
+    // The snapshot loaded after deletion should be clean (no pending gate, no block)
+    const snapshot = loadWriteGateSnapshot(base);
+    assert.equal(snapshot.pendingGateId, null, "pendingGateId should be null after file deletion");
+    assert.deepEqual(snapshot.verifiedDepthMilestones, [], "verifiedDepthMilestones should be empty after file deletion");
+
+    // Depth-verify and re-attempt: should succeed after deletion clears stale state
+    markDepthVerified("M001", base);
+
+    const unblocked = await inProjectDir(base, () => executeSummarySave({
+      milestone_id: "M001",
+      artifact_type: "CONTEXT",
+      content: "# Context\n\nfinal content",
+    }, base));
+    assert.equal(unblocked.isError, undefined, "should not be blocked after depth verification");
+    assert.equal(unblocked.details.operation, "save_summary");
+  } finally {
+    if (originalEnv === undefined) {
+      delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    } else {
+      process.env.GSD_PERSIST_WRITE_GATE_STATE = originalEnv;
+    }
+    clearDiscussionFlowState();
+    closeDatabase();
+    cleanup(base);
+  }
+});

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

@@ -11,6 +11,10 @@
 
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdirSync, writeFileSync, unlinkSync, existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
 import {
   isDepthConfirmationAnswer,
   shouldBlockContextWrite,
@@ -20,8 +24,10 @@ import {
   markDepthVerified,
   isMilestoneDepthVerified,
   shouldBlockContextArtifactSave,
+  shouldBlockContextArtifactSaveInSnapshot,
   clearDiscussionFlowState,
   resetWriteGateState,
+  loadWriteGateSnapshot,
 } from '../bootstrap/write-gate.ts';
 
 // ─── Scenario 1: Blocks CONTEXT.md write during discussion without depth verification (absolute path) ──
@@ -488,3 +494,61 @@ test('write-gate: isDepthConfirmationAnswer falls back to (Recommended) match wi
     'should reject non-Recommended via fallback',
   );
 });
+
+// ─── Scenario 29: loadWriteGateSnapshot returns clean state when persist file deleted (#4343) ──
+
+test('write-gate: loadWriteGateSnapshot returns empty default when persist file is deleted (#4343)', () => {
+  const base = join(tmpdir(), `gsd-write-gate-4343-${randomUUID()}`);
+  mkdirSync(join(base, '.gsd', 'runtime'), { recursive: true });
+  const stateFilePath = join(base, '.gsd', 'runtime', 'write-gate-state.json');
+  const originalEnv = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+
+  try {
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = '1';
+
+    // Write a state file with a pending gate and verified milestone
+    writeFileSync(stateFilePath, JSON.stringify({
+      verifiedDepthMilestones: ['M001'],
+      activeQueuePhase: false,
+      pendingGateId: 'depth_verification_M001',
+    }));
+    assert.ok(existsSync(stateFilePath), 'precondition: state file exists');
+
+    // While file exists, snapshot reflects its contents
+    const beforeDeletion = loadWriteGateSnapshot(base);
+    assert.strictEqual(beforeDeletion.pendingGateId, 'depth_verification_M001', 'pending gate from file');
+    assert.deepEqual(beforeDeletion.verifiedDepthMilestones, ['M001'], 'verified milestones from file');
+
+    // User deletes the state file to clear the HARD BLOCK
+    unlinkSync(stateFilePath);
+    assert.ok(!existsSync(stateFilePath), 'state file deleted');
+
+    // After deletion in persist mode, snapshot should be clean (not stale in-memory)
+    const afterDeletion = loadWriteGateSnapshot(base);
+    assert.strictEqual(afterDeletion.pendingGateId, null, 'pendingGateId cleared after file deletion');
+    assert.deepEqual(afterDeletion.verifiedDepthMilestones, [], 'verifiedDepthMilestones cleared after file deletion');
+    assert.strictEqual(afterDeletion.activeQueuePhase, false, 'activeQueuePhase cleared after file deletion');
+
+    // The CONTEXT artifact block check must also resolve to unblocked after deletion+verification
+    // (simulate the re-verify flow users would do: delete → depth verify → save)
+    const stillBlocked = shouldBlockContextArtifactSaveInSnapshot(afterDeletion, 'CONTEXT', 'M001', null);
+    assert.strictEqual(stillBlocked.block, true, 'still blocked without new depth verification');
+
+    const verifiedSnapshot = {
+      ...afterDeletion,
+      verifiedDepthMilestones: ['M001'],
+    };
+    const unblocked = shouldBlockContextArtifactSaveInSnapshot(verifiedSnapshot, 'CONTEXT', 'M001', null);
+    assert.strictEqual(unblocked.block, false, 'unblocked after fresh depth verification');
+  } finally {
+    if (originalEnv === undefined) {
+      delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    } else {
+      process.env.GSD_PERSIST_WRITE_GATE_STATE = originalEnv;
+    }
+    clearDiscussionFlowState();
+    try {
+      rmSync(base, { recursive: true, force: true });
+    } catch { /* swallow */ }
+  }
+});

package/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts

@@ -72,7 +72,9 @@ const autoStartSrc = readFileSync(
 const symlinkIdx = autoStartSrc.indexOf("ensureGsdSymlink(base)");
 assertTrue(symlinkIdx >= 0, "auto-start.ts calls ensureGsdSymlink(base)");
 
-const afterSymlink = symlinkIdx >= 0 ? autoStartSrc.slice(symlinkIdx, symlinkIdx + 800) : "";
+const afterSymlink = symlinkIdx >= 0
+  ? autoStartSrc.slice(symlinkIdx, autoStartSrc.indexOf("Initialize GitServiceImpl", symlinkIdx))
+  : "";
 
 // The milestones bootstrap must check milestones path, not gsdDir
 // Old (dead) code: if (!existsSync(gsdDir)) { mkdirSync(join(gsdDir, "milestones"), ...) }

package/src/resources/extensions/gsd/token-counter.ts

@@ -22,7 +22,11 @@ async function getEncoder(): Promise<TokenEncoder | null> {
 	try {
 		// @ts-ignore — tiktoken may not have type declarations in extensions tsconfig
 		const tiktoken = await import("tiktoken");
-		encoder = tiktoken.encoding_for_model("gpt-4o") as TokenEncoder;
+		// Use cl100k_base — the most conservative and broadly compatible BPE encoding.
+		// It is shared by GPT-3.5/GPT-4 and gives a safer (larger) estimate than
+		// gpt-4o's o200k_base encoding, which produces fewer tokens for the same text
+		// and would cause context windows for non-OpenAI providers to be under-counted.
+		encoder = tiktoken.get_encoding("cl100k_base") as TokenEncoder;
 		return encoder;
 	} catch {
 		encoderFailed = true;
@@ -30,20 +34,33 @@ async function getEncoder(): Promise<TokenEncoder | null> {
 	}
 }
 
-export async function countTokens(text: string): Promise<number> {
+/**
+ * Count tokens in `text` using tiktoken (cl100k_base) when available.
+ *
+ * When tiktoken is not loaded, falls back to a provider-aware character-ratio
+ * estimate via `estimateTokensForProvider`. Passing `provider` is recommended
+ * so the heuristic fallback is as accurate as possible.
+ */
+export async function countTokens(text: string, provider?: TokenProvider): Promise<number> {
 	const enc = await getEncoder();
 	if (enc) {
 		const tokens = enc.encode(text);
 		return tokens.length;
 	}
-	return Math.ceil(text.length / 4);
+	return estimateTokensForProvider(text, provider ?? "unknown");
 }
 
-export function countTokensSync(text: string): number {
+/**
+ * Synchronous token count — only accurate after `initTokenCounter()` resolves.
+ *
+ * Before init, or when tiktoken is unavailable, falls back to a provider-aware
+ * character-ratio estimate. Passing `provider` is recommended.
+ */
+export function countTokensSync(text: string, provider?: TokenProvider): number {
 	if (encoder) {
 		return encoder.encode(text).length;
 	}
-	return Math.ceil(text.length / 4);
+	return estimateTokensForProvider(text, provider ?? "unknown");
 }
 
 export async function initTokenCounter(): Promise<boolean> {

package/src/resources/extensions/gsd/tools/exec-search-tool.ts

@@ -0,0 +1,81 @@
+// GSD Exec Search Tool — lists and filters prior gsd_exec runs.
+//
+// Scans .gsd/exec/*.meta.json and returns a ranked summary so agents can
+// re-discover past runs without re-executing. Read-only; no DB writes.
+
+import { searchExecHistory, type ExecSearchOptions } from "../exec-history.js";
+
+export interface ExecSearchToolParams {
+  query?: string;
+  runtime?: "bash" | "node" | "python";
+  failing_only?: boolean;
+  limit?: number;
+}
+
+export interface ToolExecutionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+}
+
+export function executeExecSearch(
+  params: ExecSearchToolParams,
+  opts: { baseDir: string },
+): ToolExecutionResult {
+  const searchOpts: ExecSearchOptions = {
+    query: typeof params.query === "string" ? params.query : undefined,
+    runtime: params.runtime,
+    failing_only: params.failing_only === true,
+    limit: typeof params.limit === "number" ? params.limit : undefined,
+  };
+  const hits = searchExecHistory(opts.baseDir, searchOpts);
+
+  if (hits.length === 0) {
+    return {
+      content: [{ type: "text", text: "No prior gsd_exec runs match those filters." }],
+      details: { operation: "gsd_exec_search", matches: 0 },
+    };
+  }
+
+  const lines: string[] = [`Found ${hits.length} exec run(s), most recent first:`];
+  for (const hit of hits) {
+    const e = hit.entry;
+    const status = formatStatus(e);
+    const purpose = e.purpose ? ` — ${e.purpose}` : "";
+    const truncated = e.stdout_truncated ? " (stdout truncated)" : "";
+    lines.push(
+      `- [${e.id}] ${e.runtime} ${status} ${e.duration_ms}ms${truncated}${purpose}`,
+      `    stdout: ${e.stdout_path}`,
+    );
+    if (hit.digest_preview) {
+      const preview = hit.digest_preview.replace(/\n/g, "\n      ");
+      lines.push(`    preview:\n      ${preview}`);
+    }
+  }
+
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    details: {
+      operation: "gsd_exec_search",
+      matches: hits.length,
+      results: hits.map((hit) => ({
+        id: hit.entry.id,
+        runtime: hit.entry.runtime,
+        exit_code: hit.entry.exit_code,
+        timed_out: hit.entry.timed_out,
+        duration_ms: hit.entry.duration_ms,
+        purpose: hit.entry.purpose,
+        stdout_path: hit.entry.stdout_path,
+        stderr_path: hit.entry.stderr_path,
+        meta_path: hit.entry.meta_path,
+      })),
+    },
+  };
+}
+
+function formatStatus(entry: { exit_code: number | null; timed_out: boolean; signal: string | null }): string {
+  if (entry.timed_out) return "timeout";
+  if (entry.signal) return `signal:${entry.signal}`;
+  if (entry.exit_code === null) return "exit:null";
+  return `exit:${entry.exit_code}`;
+}