gsd-pi 2.76.0-dev.b072ebb73 → 2.76.0-dev.fe143342a

package/src/resources/extensions/gsd/preferences.ts

@@ -68,13 +68,13 @@ 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(): SkillDiscoveryMode {
-  const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillDiscoveryMode(basePath?: string): SkillDiscoveryMode {
+  const prefs = loadEffectiveGSDPreferences(basePath);
   return prefs?.preferences.skill_discovery ?? "suggest";
 }
 
-export function resolveSkillStalenessDays(): number {
-  const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillStalenessDays(basePath?: string): number {
+  const prefs = loadEffectiveGSDPreferences(basePath);
   return prefs?.preferences.skill_staleness_days ?? 60;
 }
 
@@ -109,16 +109,16 @@ function legacyGlobalPreferencesPath(): string {
   return join(homedir(), ".pi", "agent", "gsd-preferences.md");
 }
 
-function projectPreferencesPath(): string {
-  return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+function projectPreferencesPath(basePath: string = process.cwd()): string {
+  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(): string {
   return join(gsdHome(), "preferences.md");
 }
-function legacyProjectPreferencesPathLowercase(): string {
-  return join(gsdRoot(process.cwd()), "preferences.md");
+function legacyProjectPreferencesPathLowercase(basePath: string = process.cwd()): string {
+  return join(gsdRoot(basePath), "preferences.md");
 }
 
 export function getGlobalGSDPreferencesPath(): string {
@@ -129,8 +129,8 @@ export function getLegacyGlobalGSDPreferencesPath(): string {
   return legacyGlobalPreferencesPath();
 }
 
-export function getProjectGSDPreferencesPath(): string {
-  return projectPreferencesPath();
+export function getProjectGSDPreferencesPath(basePath?: string): string {
+  return projectPreferencesPath(basePath);
 }
 
 // ─── Loading ────────────────────────────────────────────────────────────────
@@ -141,14 +141,14 @@ export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null {
     ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
 
-export function loadProjectGSDPreferences(): LoadedGSDPreferences | null {
-  return loadPreferencesFile(projectPreferencesPath(), "project")
-    ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(), "project");
+export function loadProjectGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
+  return loadPreferencesFile(projectPreferencesPath(basePath), "project")
+    ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
 }
 
-export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
+export function loadEffectiveGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
   const globalPreferences = loadGlobalGSDPreferences();
-  const projectPreferences = loadProjectGSDPreferences();
+  const projectPreferences = loadProjectGSDPreferences(basePath);
 
   if (!globalPreferences && !projectPreferences) return null;
 
@@ -603,8 +603,8 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */
-export function getIsolationMode(): "none" | "worktree" | "branch" {
-  const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+export function getIsolationMode(basePath?: string): "none" | "worktree" | "branch" {
+  const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
   if (prefs?.isolation === "worktree") return "worktree";
   if (prefs?.isolation === "branch") return "branch";
   return "none"; // default — no isolation, work on current branch

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -24,6 +24,35 @@ import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { logWarning } from "./workflow-logger.js";
 
+type ExistsFn = (path: string) => boolean;
+
+function hasRequiredExtensionAssets(rootDir: string, exists: ExistsFn = existsSync): boolean {
+  return (
+    exists(join(rootDir, "prompts")) &&
+    exists(join(rootDir, "templates", "task-summary.md"))
+  );
+}
+
+export function resolveExtensionDirFromCandidates(
+  moduleDir: string,
+  agentGsdDir: string,
+  exists: ExistsFn = existsSync,
+): string {
+  const moduleUsable = hasRequiredExtensionAssets(moduleDir, exists);
+  const agentUsable = hasRequiredExtensionAssets(agentGsdDir, exists);
+
+  // Prefer the user-local extension tree when both are valid. This avoids
+  // leaking npm/global-install paths into prompts on Windows.
+  if (agentUsable) return agentGsdDir;
+  if (moduleUsable) return moduleDir;
+
+  // Degraded fallback: if required template is missing in both locations,
+  // keep previous behavior and prefer whichever still has prompts/.
+  if (exists(join(moduleDir, "prompts"))) return moduleDir;
+  if (exists(join(agentGsdDir, "prompts"))) return agentGsdDir;
+  return moduleDir;
+}
+
 /**
  * Resolve the GSD extension directory.
  *
@@ -36,15 +65,9 @@ import { logWarning } from "./workflow-logger.js";
  */
 function resolveExtensionDir(): string {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
-  if (existsSync(join(moduleDir, "prompts"))) return moduleDir;
-
-  // Fallback: user-local agent directory
   const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
   const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
-  if (existsSync(join(agentGsdDir, "prompts"))) return agentGsdDir;
-
-  // Last resort: return the module dir (warmCache will silently handle the miss)
-  return moduleDir;
+  return resolveExtensionDirFromCandidates(moduleDir, agentGsdDir);
 }
 
 const __extensionDir = resolveExtensionDir();

package/src/resources/extensions/gsd/safety/file-change-validator.ts

@@ -100,7 +100,7 @@ function getChangedFilesFromLastCommit(basePath: string): string[] | null {
   try {
     const result = execFileSync(
       "git",
-      ["diff", "--name-only", "HEAD~1", "HEAD"],
+      ["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) : [];

package/src/resources/extensions/gsd/tests/auto-model-selection.test.ts

@@ -341,6 +341,18 @@ test("dynamic routing passes provider-qualified model keys to the router", () =>
   );
 });
 
+test("selectAndApplyModel re-applies captured thinking level after setModel success", () => {
+  const src = readFileSync(join(__dirname, "..", "auto-model-selection.ts"), "utf-8");
+  assert.ok(
+    src.includes("autoModeStartThinkingLevel?: ReturnType<ExtensionAPI[\"getThinkingLevel\"]> | null"),
+    "selectAndApplyModel should accept an autoModeStartThinkingLevel parameter",
+  );
+  assert.ok(
+    src.includes("reapplyThinkingLevel(pi, autoModeStartThinkingLevel)"),
+    "selectAndApplyModel should re-apply captured thinking level after model changes",
+  );
+});
+
 test("resolveModelId: anthropic wins over claude-code when session provider is not claude-code", () => {
   const availableModels = [
     { id: "claude-sonnet-4-6", provider: "claude-code" },

package/src/resources/extensions/gsd/tests/auto-start-model-capture.test.ts

@@ -52,9 +52,7 @@ test("bootstrapAutoSession checks manual session override before preferences", (
     "manual override and preference fallback must be resolved before building startModelSnapshot",
   );
 
-  // The validated preferred model must still appear as one of the snapshot
-  // sources so PREFERENCES.md continues to win over a stale settings.json
-  // default for built-in providers.
+  // Preferred model should still be part of fallback resolution.
   const snapshotBlock = source.slice(snapshotIdx, snapshotIdx + 400);
   assert.ok(
     snapshotBlock.includes("validatedPreferredModel") || snapshotBlock.includes("preferredModel"),
@@ -62,6 +60,22 @@ test("bootstrapAutoSession checks manual session override before preferences", (
   );
 });
 
+test("bootstrapAutoSession prioritizes current session model over PREFERENCES.md default", () => {
+  const snapshotIdx = source.indexOf("const startModelSnapshot = manualSessionOverride");
+  assert.ok(snapshotIdx > -1, "auto-start.ts should build startModelSnapshot");
+
+  const snapshotBlock = source.slice(snapshotIdx, snapshotIdx + 500);
+  const currentIdx = snapshotBlock.indexOf("currentSessionModel");
+  const preferredIdx = snapshotBlock.indexOf("validatedPreferredModel");
+
+  assert.ok(currentIdx > -1, "startModelSnapshot should include currentSessionModel");
+  assert.ok(preferredIdx > -1, "startModelSnapshot should include validatedPreferredModel");
+  assert.ok(
+    currentIdx < preferredIdx,
+    "startModelSnapshot should prefer currentSessionModel before validatedPreferredModel",
+  );
+});
+
 test("bootstrapAutoSession prefers session model over PREFERENCES.md when provider is custom (#4122)", () => {
   // Custom providers (Ollama, vLLM, OpenAI-compatible proxies) live in
   // ~/.gsd/agent/models.json, not PREFERENCES.md.  When the user picks one
@@ -111,3 +125,19 @@ test("bootstrapAutoSession validates preferred model against live registry auth
   const warningIdx = source.indexOf("is not configured; falling back to session default");
   assert.ok(warningIdx > -1, "auto-start.ts should warn when preferred model is unconfigured");
 });
+
+test("bootstrapAutoSession snapshots and persists thinking level for auto-mode lifecycle", () => {
+  const captureIdx = source.indexOf("const startThinkingSnapshot = pi.getThinkingLevel()");
+  assert.ok(captureIdx > -1, "auto-start.ts should snapshot thinking level at bootstrap start");
+
+  const originalThinkingIdx = source.indexOf("s.originalThinkingLevel = startThinkingSnapshot ?? null");
+  assert.ok(originalThinkingIdx > -1, "auto-start.ts should store originalThinkingLevel from snapshot");
+
+  const autoThinkingIdx = source.indexOf("s.autoModeStartThinkingLevel = startThinkingSnapshot ?? null");
+  assert.ok(autoThinkingIdx > -1, "auto-start.ts should store autoModeStartThinkingLevel from snapshot");
+
+  assert.ok(
+    captureIdx < originalThinkingIdx && captureIdx < autoThinkingIdx,
+    "thinking snapshot must be captured before session state assignment",
+  );
+});

package/src/resources/extensions/gsd/tests/auto-thinking-restore.test.ts

@@ -0,0 +1,38 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const autoSrc = readFileSync(join(import.meta.dirname, "..", "auto.ts"), "utf-8");
+const phasesSrc = readFileSync(join(import.meta.dirname, "..", "auto", "phases.ts"), "utf-8");
+
+test("stopAuto restores original thinking level", () => {
+  assert.ok(
+    autoSrc.includes("if (pi && s.originalThinkingLevel)"),
+    "auto.ts should conditionally restore original thinking level in stopAuto",
+  );
+  assert.ok(
+    autoSrc.includes("pi.setThinkingLevel(s.originalThinkingLevel)"),
+    "auto.ts should call pi.setThinkingLevel with originalThinkingLevel",
+  );
+});
+
+test("runUnitPhase threads captured thinking level into selectAndApplyModel", () => {
+  const callIdx = phasesSrc.indexOf("deps.selectAndApplyModel(");
+  assert.ok(callIdx > -1, "phases.ts should call selectAndApplyModel");
+  const callBlock = phasesSrc.slice(callIdx, callIdx + 600);
+  assert.ok(
+    callBlock.includes("s.autoModeStartThinkingLevel"),
+    "runUnitPhase should pass autoModeStartThinkingLevel to selectAndApplyModel",
+  );
+});
+
+test("hook model override preserves captured thinking level", () => {
+  const hookIdx = phasesSrc.indexOf("const hookModelOverride = sidecarItem?.model ?? iterData.hookModelOverride;");
+  assert.ok(hookIdx > -1, "phases.ts should include hook model override handling");
+  const hookBlock = phasesSrc.slice(hookIdx, hookIdx + 600);
+  assert.ok(
+    hookBlock.includes("pi.setThinkingLevel(s.autoModeStartThinkingLevel)"),
+    "hook model override should re-apply captured thinking level after setModel",
+  );
+});

package/src/resources/extensions/gsd/tests/blocked-models.test.ts

@@ -0,0 +1,98 @@
+// GSD — Tests for persistent blocked-models store (issue #4513)
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  blockModel,
+  isModelBlocked,
+  loadBlockedModels,
+} from "../blocked-models.ts";
+
+function mkBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-blocked-models-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+test("blocked-models: round-trip write and read", () => {
+  const base = mkBase();
+  try {
+    assert.equal(isModelBlocked(base, "openai-codex", "gpt-5.1-codex-max"), false);
+    blockModel(base, "openai-codex", "gpt-5.1-codex-max", "not supported for ChatGPT account");
+    assert.equal(isModelBlocked(base, "openai-codex", "gpt-5.1-codex-max"), true);
+
+    const entries = loadBlockedModels(base);
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].provider, "openai-codex");
+    assert.equal(entries[0].id, "gpt-5.1-codex-max");
+    assert.ok(entries[0].blockedAt > 0);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: case-insensitive lookup", () => {
+  const base = mkBase();
+  try {
+    blockModel(base, "OpenAI-Codex", "GPT-5.1-Codex-Max", "reason");
+    assert.equal(isModelBlocked(base, "openai-codex", "gpt-5.1-codex-max"), true);
+    assert.equal(isModelBlocked(base, "OPENAI-CODEX", "GPT-5.1-CODEX-MAX"), true);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: dedupes repeated blocks", () => {
+  const base = mkBase();
+  try {
+    blockModel(base, "openai-codex", "gpt-5", "first");
+    blockModel(base, "openai-codex", "gpt-5", "second");
+    blockModel(base, "openai-codex", "gpt-5", "third");
+    assert.equal(loadBlockedModels(base).length, 1);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: corrupted JSON recovers to empty", () => {
+  const base = mkBase();
+  try {
+    const path = join(base, ".gsd", "runtime", "blocked-models.json");
+    mkdirSync(join(base, ".gsd", "runtime"), { recursive: true });
+    writeFileSync(path, "{not valid json", "utf-8");
+
+    assert.equal(loadBlockedModels(base).length, 0);
+    assert.equal(isModelBlocked(base, "any", "model"), false);
+
+    // A subsequent write should still succeed (overwrites the corrupt file).
+    blockModel(base, "openai-codex", "gpt-5", "reason");
+    assert.equal(loadBlockedModels(base).length, 1);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: returns false for missing provider or id", () => {
+  const base = mkBase();
+  try {
+    blockModel(base, "openai-codex", "gpt-5", "reason");
+    assert.equal(isModelBlocked(base, undefined, "gpt-5"), false);
+    assert.equal(isModelBlocked(base, "openai-codex", undefined), false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("blocked-models: file created under .gsd/runtime/", () => {
+  const base = mkBase();
+  try {
+    blockModel(base, "openai-codex", "gpt-5", "reason");
+    assert.ok(existsSync(join(base, ".gsd", "runtime", "blocked-models.json")));
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/compaction-snapshot.test.ts

@@ -0,0 +1,123 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  buildSnapshot,
+  readCompactionSnapshot,
+  writeCompactionSnapshot,
+  DEFAULT_SNAPSHOT_BYTES,
+} from '../compaction-snapshot.ts';
+import { closeDatabase, openDatabase } from '../gsd-db.ts';
+import { createMemory } from '../memory-store.ts';
+import { executeResume } from '../tools/resume-tool.ts';
+
+function freshBase(): string {
+  return mkdtempSync(join(tmpdir(), 'gsd-snap-'));
+}
+
+function cleanup(dir: string): void {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+test('buildSnapshot: renders memories, exec history, and active context', () => {
+  const snap = buildSnapshot({
+    generatedAt: new Date('2026-04-20T12:00:00.000Z'),
+    activeContext: 'M001 / S01 / T01 — wire gsd_exec',
+    memories: [
+      { id: 'MEM001', category: 'gotcha', content: 'FTS5 needs Porter tokenizer', confidence: 0.9,
+        source_unit_type: null, source_unit_id: null, created_at: '', updated_at: '',
+        superseded_by: null, hit_count: 0, scope: 'project', seq: 1, tags: [], structured_fields: null },
+    ],
+    execHistory: [
+      {
+        id: 'abc',
+        runtime: 'bash',
+        purpose: 'count TODOs',
+        started_at: '', finished_at: '', duration_ms: 10,
+        exit_code: 0, signal: null, timed_out: false,
+        stdout_bytes: 1, stderr_bytes: 0, stdout_truncated: false, stderr_truncated: false,
+        stdout_path: '/tmp/abc.stdout', stderr_path: '/tmp/abc.stderr', meta_path: '/tmp/abc.meta.json',
+      },
+    ],
+  });
+  assert.match(snap, /Active context/);
+  assert.match(snap, /M001 \/ S01 \/ T01/);
+  assert.match(snap, /FTS5 needs Porter tokenizer/);
+  assert.match(snap, /\[abc\] bash exit:0 — count TODOs/);
+});
+
+test('buildSnapshot: enforces the byte cap with a truncation marker', () => {
+  const longMemories = Array.from({ length: 50 }, (_v, i) => ({
+    id: `MEM${String(i).padStart(3, '0')}`,
+    category: 'gotcha',
+    content: 'x'.repeat(200),
+    confidence: 0.8,
+    source_unit_type: null,
+    source_unit_id: null,
+    created_at: '',
+    updated_at: '',
+    superseded_by: null,
+    hit_count: 0,
+    scope: 'project',
+    seq: i,
+    tags: [] as string[],
+    structured_fields: null,
+  }));
+  const snap = buildSnapshot(
+    { generatedAt: new Date(), memories: longMemories, execHistory: [] },
+    { maxBytes: 512, maxMemories: 50 },
+  );
+  assert.ok(Buffer.byteLength(snap, 'utf-8') <= 512, 'should respect cap');
+  assert.match(snap, /\[truncated\]/, 'should include truncation marker');
+});
+
+test('buildSnapshot: handles empty state with an explanatory placeholder', () => {
+  const snap = buildSnapshot({ generatedAt: new Date(), memories: [], execHistory: [] });
+  assert.match(snap, /_No durable memories/);
+  assert.ok(Buffer.byteLength(snap, 'utf-8') <= DEFAULT_SNAPSHOT_BYTES);
+});
+
+test('writeCompactionSnapshot + readCompactionSnapshot + executeResume: end-to-end', () => {
+  const base = freshBase();
+  try {
+    openDatabase(':memory:');
+    createMemory({ category: 'architecture', content: 'Single-writer DB through gsd-db.ts', confidence: 0.95 });
+    createMemory({ category: 'convention', content: 'Prefer typed helpers over raw SQL', confidence: 0.9 });
+
+    const out = writeCompactionSnapshot(base, { activeContext: 'M099 resume check' });
+    assert.ok(out.path.endsWith('last-snapshot.md'));
+    assert.ok(out.bytes > 0);
+    assert.equal(out.memories, 2);
+
+    const contents = readCompactionSnapshot(base);
+    assert.ok(contents);
+    assert.match(contents!, /Single-writer DB through gsd-db\.ts/);
+    assert.match(contents!, /M099 resume check/);
+
+    const tool = executeResume({}, { baseDir: base });
+    assert.ok(!tool.isError);
+    assert.equal(tool.details.found, true);
+    assert.match(tool.content[0].text, /Single-writer DB through gsd-db\.ts/);
+
+    // also verify the file content matches (without trailing newline)
+    const raw = readFileSync(out.path, 'utf-8');
+    assert.ok(raw.endsWith('\n'));
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test('executeResume: reports friendly empty state when no snapshot exists', () => {
+  const base = freshBase();
+  try {
+    const result = executeResume({}, { baseDir: base });
+    assert.equal(result.details.found, false);
+    assert.match(result.content[0].text, /No snapshot found/);
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/complexity-classifier.test.ts

@@ -21,9 +21,9 @@ test("tierOrdinal returns correct ordering", () => {
 
 // ─── Unit Type Classification ────────────────────────────────────────────────
 
-test("complete-slice classifies as light", () => {
+test("complete-slice classifies as standard", () => {
   const result = classifyUnitComplexity("complete-slice", "M001/S01", "/tmp/fake");
-  assert.equal(result.tier, "light");
+  assert.equal(result.tier, "standard");
 });
 
 test("run-uat classifies as light", () => {
@@ -145,7 +145,7 @@ test("budget pressure at 90% downgrades standard to light", () => {
   assert.equal(result.downgraded, true);
 });
 
-test("budget pressure at 90% downgrades light stays light", () => {
+test("budget pressure at 90% downgrades complete-slice standard to light", () => {
   const result = classifyUnitComplexity("complete-slice", "M001/S01", "/tmp/fake", 0.95);
   assert.equal(result.tier, "light");
 });

package/src/resources/extensions/gsd/tests/exec-history.test.ts

@@ -0,0 +1,124 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { listExecHistory, searchExecHistory } from '../exec-history.ts';
+import { executeExecSearch } from '../tools/exec-search-tool.ts';
+
+function freshBase(): string {
+  return mkdtempSync(join(tmpdir(), 'gsd-exec-history-'));
+}
+
+function cleanup(dir: string): void {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+function writeRun(base: string, id: string, overrides: Record<string, unknown> = {}): void {
+  const dir = join(base, '.gsd', 'exec');
+  mkdirSync(dir, { recursive: true });
+  const stdoutPath = join(dir, `${id}.stdout`);
+  const stderrPath = join(dir, `${id}.stderr`);
+  const metaPath = join(dir, `${id}.meta.json`);
+  writeFileSync(stdoutPath, (overrides.stdout as string | undefined) ?? `stdout for ${id}\n`);
+  writeFileSync(stderrPath, '');
+  writeFileSync(
+    metaPath,
+    JSON.stringify({
+      id,
+      runtime: 'bash',
+      purpose: `purpose for ${id}`,
+      started_at: '2026-04-20T12:00:00.000Z',
+      finished_at: '2026-04-20T12:00:00.100Z',
+      duration_ms: 100,
+      exit_code: 0,
+      signal: null,
+      timed_out: false,
+      stdout_bytes: 12,
+      stderr_bytes: 0,
+      stdout_truncated: false,
+      stderr_truncated: false,
+      stdout_path: stdoutPath,
+      stderr_path: stderrPath,
+      ...overrides,
+    }),
+  );
+}
+
+test('listExecHistory: returns empty list when .gsd/exec missing', () => {
+  const base = freshBase();
+  try {
+    assert.deepEqual(listExecHistory(base), []);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('listExecHistory: skips malformed meta files', () => {
+  const base = freshBase();
+  try {
+    const dir = join(base, '.gsd', 'exec');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'bad.meta.json'), '{not-json');
+    writeRun(base, 'ok-1');
+    const list = listExecHistory(base);
+    assert.equal(list.length, 1);
+    assert.equal(list[0]!.id, 'ok-1');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('searchExecHistory: filters by query, runtime, and failing_only', () => {
+  const base = freshBase();
+  try {
+    writeRun(base, 'playwright-run', { purpose: 'playwright snapshot' });
+    writeRun(base, 'grep-run', { purpose: 'grep TODOs' });
+    writeRun(base, 'failing-run', { exit_code: 1, purpose: 'boom' });
+    writeRun(base, 'node-run', { runtime: 'node', purpose: 'dedupe' });
+
+    const playwrightHits = searchExecHistory(base, { query: 'playwright' });
+    assert.equal(playwrightHits.length, 1);
+    assert.equal(playwrightHits[0]!.entry.id, 'playwright-run');
+
+    const failingHits = searchExecHistory(base, { failing_only: true });
+    assert.equal(failingHits.length, 1);
+    assert.equal(failingHits[0]!.entry.id, 'failing-run');
+
+    const nodeHits = searchExecHistory(base, { runtime: 'node' });
+    assert.equal(nodeHits.length, 1);
+    assert.equal(nodeHits[0]!.entry.runtime, 'node');
+
+    const unlimited = searchExecHistory(base, {});
+    assert.equal(unlimited.length, 4);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('executeExecSearch: returns helpful empty-state message when no matches', () => {
+  const base = freshBase();
+  try {
+    const result = executeExecSearch({ query: 'missing' }, { baseDir: base });
+    assert.ok(!result.isError);
+    assert.match(result.content[0].text, /No prior gsd_exec runs/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('executeExecSearch: includes stdout_path and preview in details', () => {
+  const base = freshBase();
+  try {
+    writeRun(base, 'summary-run', { stdout: 'found 42 TODOs\n' });
+    const result = executeExecSearch({ query: 'summary' }, { baseDir: base });
+    const details = result.details as { results: Array<{ id: string; stdout_path: string }> };
+    assert.equal(details.results.length, 1);
+    assert.equal(details.results[0]!.id, 'summary-run');
+    assert.match(details.results[0]!.stdout_path, /summary-run\.stdout$/);
+    assert.match(result.content[0].text, /found 42 TODOs/);
+  } finally {
+    cleanup(base);
+  }
+});