gsd-pi 2.76.0-dev.82e249f7b → 2.76.0-dev.97f5583d9

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -660,6 +660,55 @@ export function validatePreferences(preferences) {
             errors.push("context_management must be an object");
         }
     }
+    // ─── Context Mode (gsd_exec sandbox) ────────────────────────────────────
+    if (preferences.context_mode !== undefined) {
+        if (typeof preferences.context_mode === "object" && preferences.context_mode !== null) {
+            const cmode = preferences.context_mode;
+            const validCmode = {};
+            if (cmode.enabled !== undefined) {
+                if (typeof cmode.enabled === "boolean")
+                    validCmode.enabled = cmode.enabled;
+                else
+                    errors.push("context_mode.enabled must be a boolean");
+            }
+            if (cmode.exec_timeout_ms !== undefined) {
+                const t = cmode.exec_timeout_ms;
+                if (typeof t === "number" && t >= 1000 && t <= 600_000)
+                    validCmode.exec_timeout_ms = Math.floor(t);
+                else
+                    errors.push("context_mode.exec_timeout_ms must be a number between 1000 and 600000");
+            }
+            if (cmode.exec_stdout_cap_bytes !== undefined) {
+                const b = cmode.exec_stdout_cap_bytes;
+                if (typeof b === "number" && b >= 4096 && b <= 16_777_216)
+                    validCmode.exec_stdout_cap_bytes = Math.floor(b);
+                else
+                    errors.push("context_mode.exec_stdout_cap_bytes must be a number between 4096 and 16777216");
+            }
+            if (cmode.exec_digest_chars !== undefined) {
+                const c = cmode.exec_digest_chars;
+                if (typeof c === "number" && c >= 0 && c <= 4000)
+                    validCmode.exec_digest_chars = Math.floor(c);
+                else
+                    errors.push("context_mode.exec_digest_chars must be a number between 0 and 4000");
+            }
+            if (cmode.exec_env_allowlist !== undefined) {
+                if (Array.isArray(cmode.exec_env_allowlist) &&
+                    cmode.exec_env_allowlist.every((v) => typeof v === "string" && /^[A-Z_][A-Z0-9_]*$/i.test(v))) {
+                    validCmode.exec_env_allowlist = cmode.exec_env_allowlist;
+                }
+                else {
+                    errors.push("context_mode.exec_env_allowlist must be an array of valid env var names");
+                }
+            }
+            if (Object.keys(validCmode).length > 0) {
+                validated.context_mode = validCmode;
+            }
+        }
+        else {
+            errors.push("context_mode must be an object");
+        }
+    }
     // ─── Parallel Config ────────────────────────────────────────────────────
     if (preferences.parallel && typeof preferences.parallel === "object") {
         const p = preferences.parallel;
@@ -716,6 +765,40 @@ export function validatePreferences(preferences) {
             validated.parallel = parallel;
         }
     }
+    // ─── Slice Parallel Config ───────────────────────────────────────────────
+    if (preferences.slice_parallel !== undefined) {
+        if (typeof preferences.slice_parallel === "object" && preferences.slice_parallel !== null) {
+            const sp = preferences.slice_parallel;
+            const validSp = {};
+            if (sp.enabled !== undefined) {
+                if (typeof sp.enabled === "boolean")
+                    validSp.enabled = sp.enabled;
+                else
+                    errors.push("slice_parallel.enabled must be a boolean");
+            }
+            if (sp.max_workers !== undefined) {
+                const maxWorkers = typeof sp.max_workers === "number" ? sp.max_workers : Number(sp.max_workers);
+                if (Number.isFinite(maxWorkers) && maxWorkers >= 1 && maxWorkers <= 8) {
+                    validSp.max_workers = Math.floor(maxWorkers);
+                }
+                else {
+                    errors.push("slice_parallel.max_workers must be a number between 1 and 8");
+                }
+            }
+            const knownSliceParallelKeys = new Set(["enabled", "max_workers"]);
+            for (const key of Object.keys(sp)) {
+                if (!knownSliceParallelKeys.has(key)) {
+                    warnings.push(`unknown slice_parallel key "${key}" — ignored`);
+                }
+            }
+            if (Object.keys(validSp).length > 0) {
+                validated.slice_parallel = validSp;
+            }
+        }
+        else {
+            errors.push("slice_parallel must be an object");
+        }
+    }
     // ─── Reactive Execution ─────────────────────────────────────────────────
     if (preferences.reactive_execution !== undefined) {
         if (typeof preferences.reactive_execution === "object" && preferences.reactive_execution !== null) {

package/dist/resources/extensions/gsd/preferences.js

@@ -26,12 +26,12 @@ export { resolveAllSkillReferences } from "./preferences-skills.js";
 // These lived in preferences-skills.ts but imported loadEffectiveGSDPreferences
 // back from this file, creating a circular dependency. Moved here since they
 // are trivial wrappers over loadEffectiveGSDPreferences.
-export function resolveSkillDiscoveryMode() {
-    const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillDiscoveryMode(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath);
     return prefs?.preferences.skill_discovery ?? "suggest";
 }
-export function resolveSkillStalenessDays() {
-    const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillStalenessDays(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath);
     return prefs?.preferences.skill_staleness_days ?? 60;
 }
 // ─── Re-exports: models ─────────────────────────────────────────────────────
@@ -46,16 +46,16 @@ function globalPreferencesPath() {
 function legacyGlobalPreferencesPath() {
     return join(homedir(), ".pi", "agent", "gsd-preferences.md");
 }
-function projectPreferencesPath() {
-    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+function projectPreferencesPath(basePath = process.cwd()) {
+    return join(gsdRoot(basePath), "PREFERENCES.md");
 }
 // Legacy lowercase files can still exist in older projects. Keep them as a
 // compatibility-only fallback, but route new reads/writes through PREFERENCES.md.
 function legacyGlobalPreferencesPathLowercase() {
     return join(gsdHome(), "preferences.md");
 }
-function legacyProjectPreferencesPathLowercase() {
-    return join(gsdRoot(process.cwd()), "preferences.md");
+function legacyProjectPreferencesPathLowercase(basePath = process.cwd()) {
+    return join(gsdRoot(basePath), "preferences.md");
 }
 export function getGlobalGSDPreferencesPath() {
     return globalPreferencesPath();
@@ -63,8 +63,8 @@ export function getGlobalGSDPreferencesPath() {
 export function getLegacyGlobalGSDPreferencesPath() {
     return legacyGlobalPreferencesPath();
 }
-export function getProjectGSDPreferencesPath() {
-    return projectPreferencesPath();
+export function getProjectGSDPreferencesPath(basePath) {
+    return projectPreferencesPath(basePath);
 }
 // ─── Loading ────────────────────────────────────────────────────────────────
 export function loadGlobalGSDPreferences() {
@@ -72,13 +72,13 @@ export function loadGlobalGSDPreferences() {
         ?? loadPreferencesFile(legacyGlobalPreferencesPathLowercase(), "global")
         ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
-export function loadProjectGSDPreferences() {
-    return loadPreferencesFile(projectPreferencesPath(), "project")
-        ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(), "project");
+export function loadProjectGSDPreferences(basePath) {
+    return loadPreferencesFile(projectPreferencesPath(basePath), "project")
+        ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
 }
-export function loadEffectiveGSDPreferences() {
+export function loadEffectiveGSDPreferences(basePath) {
     const globalPreferences = loadGlobalGSDPreferences();
-    const projectPreferences = loadProjectGSDPreferences();
+    const projectPreferences = loadProjectGSDPreferences(basePath);
     if (!globalPreferences && !projectPreferences)
         return null;
     let result;
@@ -489,8 +489,8 @@ export function resolvePreDispatchHooks() {
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */
-export function getIsolationMode() {
-    const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+export function getIsolationMode(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
     if (prefs?.isolation === "worktree")
         return "worktree";
     if (prefs?.isolation === "branch")

package/dist/resources/extensions/gsd/prompts/discuss-headless.md

@@ -162,6 +162,10 @@ Preserve the specification's exact terminology, emphasis, and specific framing.
 6. For each architectural or pattern decision, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, `{{contextPath}}`, and called `gsd_plan_milestone`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
@@ -234,6 +238,10 @@ For single-milestone projects, do NOT write this file.
 
 7. {{multiMilestoneCommitInstruction}}
 
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have written `.gsd/PROJECT.md`, `.gsd/REQUIREMENTS.md`, the primary `CONTEXT.md`, called `gsd_plan_milestone` for the primary milestone, and written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`. If any is missing, **STOP** — emit the missing tool calls in this same turn. The system rejects premature ready signals and retries are capped.
+
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ## Critical Rules

package/dist/resources/extensions/gsd/prompts/discuss.md

@@ -339,7 +339,20 @@ These sections are in addition to whatever other context the discussion surfaced
 6. For each architectural or pattern decision made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 7. {{commitInstruction}}
 
-After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (step 2)
+- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Written `{{contextPath}}` (step 4)
+- [ ] Called `gsd_plan_milestone` (step 5)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing steps 1–7 above, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
 ### Multi-Milestone
 
@@ -418,6 +431,20 @@ For single-milestone projects, do NOT write this file — it is only for multi-m
 
 7. {{multiMilestoneCommitInstruction}}
 
-After writing the files, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
+### Ready-phrase pre-condition (NON-BYPASSABLE)
+
+Before emitting the ready phrase, verify in the CURRENT turn that you have:
+
+- [ ] Written `.gsd/PROJECT.md` (Phase 1)
+- [ ] Written `.gsd/REQUIREMENTS.md` (Phase 1)
+- [ ] Written primary-milestone `CONTEXT.md` (Phase 2)
+- [ ] Called `gsd_plan_milestone` for the primary milestone (Phase 2)
+- [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total` (Phase 3)
+
+If ANY box is unchecked, **STOP**. Do NOT emit the ready phrase. Emit the missing tool calls in this same turn. The system detects missing artifacts and will reject premature ready signals — you will be asked again and retries are capped.
+
+Do not announce the ready phrase as something you are "about to" do. Do not narrate "now writing the files" as a substitute for actually writing them. The ready phrase is a post-write signal, not an intent signal.
+
+After completing all phases above, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
 
 {{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/parallel-research-slices.md

@@ -15,8 +15,11 @@ Dispatch ALL slices simultaneously using the `subagent` tool in **parallel mode*
 1. Call `subagent` with `tasks: [...]` containing one entry per slice below
 2. Wait for ALL subagents to complete
 3. Verify each slice's RESEARCH file was written (check the `.gsd/{{mid}}/` directory)
-4. If any subagent failed to write its RESEARCH file, re-run it individually
-5. Report which slices completed research and which (if any) failed
+4. If a subagent failed to write its RESEARCH file, retry it **once** individually
+5. If it fails a second time, write a partial RESEARCH file for that slice with a `## BLOCKER` section explaining the failure — do NOT retry again
+6. Report which slices completed research and which (if any) needed a blocker note
+
+**Important**: Each failed slice gets exactly one retry. After that, write the blocker and move on. Never retry the same slice more than once.
 
 ## Subagent Prompts
 

package/dist/resources/extensions/gsd/safety/evidence-collector.js

@@ -3,9 +3,17 @@
  * Tracks every bash command, file write, and file edit during a unit execution.
  * Evidence is compared against LLM completion claims in evidence-cross-ref.ts.
  *
+ * Evidence is persisted to .gsd/safety/evidence-<mid>-<sid>-<tid>.json so it
+ * survives session restarts (pause/resume, crash recovery). On unit start,
+ * call resetEvidence() then loadEvidenceFromDisk(). On every new tool call,
+ * saveEvidenceToDisk() is called automatically by recordToolCall/recordToolResult.
+ *
  * Follows the same module-level Map pattern as auto-tool-tracking.ts.
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, } from "node:fs";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
 // ─── Module State ───────────────────────────────────────────────────────────
 let unitEvidence = [];
 // ─── Public API ─────────────────────────────────────────────────────────────
@@ -27,6 +35,94 @@ export function getFilePaths() {
         .filter((e) => e.kind === "write" || e.kind === "edit")
         .map(e => e.path);
 }
+// ─── Persistence (Bug #4385 — evidence must survive session restarts) ────────
+/**
+ * Build the path for the evidence JSON file for a given unit.
+ * Lives under .gsd/safety/ which is gitignored and session-scoped.
+ */
+function evidencePath(basePath, milestoneId, sliceId, taskId) {
+    return join(basePath, ".gsd", "safety", `evidence-${milestoneId}-${sliceId}-${taskId}.json`);
+}
+/**
+ * Validate that a parsed value is an array of EvidenceEntry objects.
+ * Rejects corrupt / schema-mismatch data rather than letting it poison state.
+ */
+function isEvidenceArray(data) {
+    if (!Array.isArray(data))
+        return false;
+    return data.every((e) => {
+        if (e === null || typeof e !== "object")
+            return false;
+        const rec = e;
+        if (typeof rec.toolCallId !== "string")
+            return false;
+        if (typeof rec.timestamp !== "number")
+            return false;
+        if (rec.kind === "bash") {
+            return (typeof rec.command === "string" &&
+                typeof rec.exitCode === "number" &&
+                typeof rec.outputSnippet === "string");
+        }
+        if (rec.kind === "write" || rec.kind === "edit") {
+            return typeof rec.path === "string";
+        }
+        return false;
+    });
+}
+/**
+ * Persist the current in-memory evidence to disk so it survives a session
+ * restart. Called from saveEvidenceToDisk after recordToolCall/recordToolResult.
+ * Non-fatal — persistence failures must never break unit execution.
+ */
+export function saveEvidenceToDisk(basePath, milestoneId, sliceId, taskId) {
+    try {
+        const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
+        writeFileSync(tmp, JSON.stringify(unitEvidence, null, 2) + "\n", "utf-8");
+        renameSync(tmp, path);
+    }
+    catch {
+        // Non-fatal — don't let persistence failures break unit execution
+    }
+}
+/**
+ * Load persisted evidence from disk into the in-memory array.
+ * Call after resetEvidence() on session resume to restore context for a
+ * partially-executed unit. If the file does not exist (fresh unit), this
+ * is a no-op — getEvidence() will return [] which is correct.
+ */
+export function loadEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
+    try {
+        const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        if (!existsSync(path))
+            return;
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (isEvidenceArray(parsed)) {
+            unitEvidence = parsed;
+        }
+    }
+    catch {
+        // Non-fatal — corrupt / missing file is treated as empty evidence
+    }
+}
+/**
+ * Delete the persisted evidence file for a unit after it has been fully
+ * processed. Prevents stale evidence from affecting future retries of
+ * the same unit ID.
+ */
+export function clearEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
+    try {
+        const path = evidencePath(basePath, milestoneId, sliceId, taskId);
+        if (existsSync(path)) {
+            unlinkSync(path);
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}
 // ─── Recording (called from register-hooks.ts) ─────────────────────────────
 /**
  * Record a tool call at dispatch time (before execution).

package/dist/resources/extensions/gsd/safety/file-change-validator.js

@@ -4,13 +4,18 @@
  *
  * Uses tasks.expected_output (DB column, populated from per-task ## Expected Output)
  * and tasks.files (from slice PLAN.md - Files: subline) as the expected set.
- * Compares against git diff HEAD~1 --name-only after auto-commit.
+ * Compares against `git diff-tree --root --no-commit-id -r --name-only HEAD` after auto-commit.
+ * Using diff-tree --root handles initial commits, shallow clones, and merge commits correctly
+ * (Bug #4385 — git diff HEAD~1 failed on initial commits).
  *
  * Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
  */
+import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
 import { normalizePlannedFileReference } from "../files.js";
 import { logWarning } from "../workflow-logger.js";
+const _require = createRequire(import.meta.url);
+const picomatch = _require("picomatch");
 // ─── Public API ─────────────────────────────────────────────────────────────
 /**
  * Validate file changes after auto-commit for an execute-task unit.
@@ -20,7 +25,7 @@ import { logWarning } from "../workflow-logger.js";
  * @param expectedOutput - JSON array from tasks.expected_output DB column
  * @param plannedFiles - JSON array from tasks.files DB column
  */
-export function validateFileChanges(basePath, expectedOutput, plannedFiles) {
+export function validateFileChanges(basePath, expectedOutput, plannedFiles, fileChangeAllowlist = []) {
     const allExpected = new Set([...expectedOutput, ...plannedFiles]);
     // If no expected files were planned, skip validation
     if (allExpected.size === 0)
@@ -33,8 +38,11 @@ export function validateFileChanges(basePath, expectedOutput, plannedFiles) {
     const projectFiles = actualFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\"));
     // Normalize expected paths (strip leading ./ or /)
     const normalizedExpected = new Set([...allExpected].map((f) => normalizePlannedFileReference(f).replace(/^\.\//, "").replace(/^\//, "")));
-    // Compute symmetric difference
-    const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f));
+    // Build allowlist matchers once (dot: true so patterns like `**/.hidden` work).
+    const allowlistMatchers = fileChangeAllowlist.map(p => picomatch(p, { dot: true }));
+    const isAllowlisted = (f) => allowlistMatchers.some(m => m(f));
+    // Compute symmetric difference, excluding allowlisted files
+    const unexpectedFiles = projectFiles.filter(f => !normalizedExpected.has(f) && !isAllowlisted(f));
     const missingFiles = [...normalizedExpected].filter(f => !projectFiles.includes(f));
     const violations = [];
     for (const f of unexpectedFiles) {
@@ -62,7 +70,7 @@ export function validateFileChanges(basePath, expectedOutput, plannedFiles) {
 // ─── Internals ──────────────────────────────────────────────────────────────
 function getChangedFilesFromLastCommit(basePath) {
     try {
-        const result = execFileSync("git", ["diff", "--name-only", "HEAD~1", "HEAD"], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+        const result = execFileSync("git", ["diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "HEAD"], { cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
         return result ? result.split("\n").filter(Boolean) : [];
     }
     catch (e) {

package/dist/resources/extensions/gsd/safety/safety-harness.js

@@ -23,6 +23,7 @@ const DEFAULTS = {
     checkpoints: true,
     auto_rollback: false,
     timeout_scale_cap: 6,
+    file_change_allowlist: [],
 };
 // ─── Public API ─────────────────────────────────────────────────────────────
 /**
@@ -42,6 +43,9 @@ export function resolveSafetyHarnessConfig(raw) {
         checkpoints: typeof raw.checkpoints === "boolean" ? raw.checkpoints : DEFAULTS.checkpoints,
         auto_rollback: typeof raw.auto_rollback === "boolean" ? raw.auto_rollback : DEFAULTS.auto_rollback,
         timeout_scale_cap: typeof raw.timeout_scale_cap === "number" ? raw.timeout_scale_cap : DEFAULTS.timeout_scale_cap,
+        file_change_allowlist: Array.isArray(raw.file_change_allowlist)
+            ? raw.file_change_allowlist.filter((p) => typeof p === "string")
+            : DEFAULTS.file_change_allowlist,
     };
 }
 /**
@@ -56,7 +60,7 @@ export function isHarnessEnabled(raw) {
     return DEFAULTS.enabled;
 }
 // ─── Re-exports ─────────────────────────────────────────────────────────────
-export { resetEvidence, getEvidence, getBashEvidence, getFilePaths, recordToolCall, recordToolResult, } from "./evidence-collector.js";
+export { resetEvidence, getEvidence, getBashEvidence, getFilePaths, recordToolCall, recordToolResult, saveEvidenceToDisk, loadEvidenceFromDisk, clearEvidenceFromDisk, } from "./evidence-collector.js";
 export { classifyCommand } from "./destructive-guard.js";
 export { validateFileChanges } from "./file-change-validator.js";
 export { crossReferenceEvidence } from "./evidence-cross-ref.js";

package/dist/resources/extensions/gsd/token-counter.js

@@ -16,7 +16,11 @@ async function getEncoder() {
     try {
         // @ts-ignore — tiktoken may not have type declarations in extensions tsconfig
         const tiktoken = await import("tiktoken");
-        encoder = tiktoken.encoding_for_model("gpt-4o");
+        // 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");
         return encoder;
     }
     catch {
@@ -24,19 +28,32 @@ async function getEncoder() {
         return null;
     }
 }
-export async function countTokens(text) {
+/**
+ * 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, provider) {
     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) {
+/**
+ * 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, provider) {
     if (encoder) {
         return encoder.encode(text).length;
     }
-    return Math.ceil(text.length / 4);
+    return estimateTokensForProvider(text, provider ?? "unknown");
 }
 export async function initTokenCounter() {
     const enc = await getEncoder();

package/dist/resources/extensions/gsd/tools/exec-search-tool.js

@@ -0,0 +1,59 @@
+// 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 } from "../exec-history.js";
+export function executeExecSearch(params, opts) {
+    const searchOpts = {
+        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 = [`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) {
+    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}`;
+}