gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

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) ──
@@ -474,17 +480,77 @@ test('write-gate: isDepthConfirmationAnswer works with different label text', ()
   );
 });
 
-// ─── Scenario 18: fallback when options not available ──
+// ─── Scenario 18: fail-closed when options not available (#4950) ──
 
-test('write-gate: isDepthConfirmationAnswer falls back to (Recommended) match without options', () => {
+test('write-gate: isDepthConfirmationAnswer fails closed when options are missing (#4950)', () => {
+  // After #4950 the substring fallback was removed. Without options the gate
+  // can never be unlocked — every input must return false.
   assert.strictEqual(
     isDepthConfirmationAnswer('Yes, you got it (Recommended)'),
-    true,
-    'should accept via fallback when no options provided',
+    false,
+    'no-options + Recommended substring must NOT unlock the gate',
   );
   assert.strictEqual(
     isDepthConfirmationAnswer('Not quite — let me clarify'),
     false,
-    'should reject non-Recommended via fallback',
+    'no-options + non-Recommended must NOT unlock the gate',
   );
 });
+
+// ─── 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

@@ -1,95 +1,81 @@
-import { readFileSync } from "node:fs";
+/**
+ * zombie-gsd-state.test.ts — #2942
+ *
+ * A partially initialized `.gsd/` (symlink exists but neither `PREFERENCES.md`
+ * nor `milestones/` is present) previously caused the init-wizard gate in
+ * `showSmartEntry` to be skipped. The fix introduces
+ * `hasGsdBootstrapArtifacts`, which requires at least one bootstrap artifact
+ * to be present before treating the project as initialized.
+ *
+ * These tests exercise that helper directly over synthetic filesystems and
+ * injected predicates — replacing the old source-grep assertions that only
+ * verified the function's *text* shape.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
-
-import { createTestContext } from "./test-helpers.ts";
-
-const { assertTrue, assertMatch, assertNoMatch, report } = createTestContext();
-
-// ─── #2942: Zombie .gsd state skips init wizard ─────────────────────────────
-//
-// A partially initialized .gsd/ (symlink exists but no PREFERENCES.md or
-// milestones/) causes the init wizard gate in showSmartEntry to be skipped,
-// resulting in an uninitialized project session.
-
-console.log("\n=== #2942: zombie .gsd state must not skip init wizard ===");
-
-// ── guided-flow.ts — init wizard gate must check bootstrap completeness ──
-
-const guidedFlowSrc = readFileSync(
-  join(import.meta.dirname, "..", "guided-flow.ts"),
-  "utf-8",
-);
-
-// Find the showSmartEntry function
-const smartEntryIdx = guidedFlowSrc.indexOf("export async function showSmartEntry(");
-assertTrue(smartEntryIdx >= 0, "guided-flow.ts defines showSmartEntry");
-
-// Extract the region between showSmartEntry and the first showProjectInit call
-// This is where the init wizard gate lives.
-const afterSmartEntry = smartEntryIdx >= 0 ? guidedFlowSrc.slice(smartEntryIdx, smartEntryIdx + 3000) : "";
-
-// The gate must NOT be a bare `!existsSync(gsdRoot(basePath))` check.
-// It must also verify that bootstrap artifacts (PREFERENCES.md or milestones/) exist.
-assertTrue(
-  afterSmartEntry.includes("PREFERENCES.md") || afterSmartEntry.includes("PREFERENCES"),
-  "init wizard gate checks for PREFERENCES.md, not just .gsd/ existence (#2942)",
-);
-
-assertTrue(
-  afterSmartEntry.includes("milestones"),
-  "init wizard gate checks for milestones/ directory, not just .gsd/ existence (#2942)",
-);
-
-// The init wizard should be shown when .gsd/ exists but has no bootstrap artifacts.
-// The old code was: if (!existsSync(gsdRoot(basePath))) { ... showProjectInit ... }
-// The fix should use a compound check so zombie states trigger the wizard.
-// Verify we no longer have the bare existence check as the sole gate.
-
-// Find the specific init wizard gate pattern — the detection preamble block.
-const detectionPreambleIdx = afterSmartEntry.indexOf("Detection preamble");
-const detectionRegion = detectionPreambleIdx >= 0
-  ? afterSmartEntry.slice(detectionPreambleIdx, detectionPreambleIdx + 600)
-  : afterSmartEntry.slice(0, 1500);
-
-// The gate condition must reference PREFERENCES.md or milestones (bootstrap artifacts)
-assertMatch(
-  detectionRegion,
-  /PREFERENCES\.md|milestones/,
-  "detection preamble gate references bootstrap artifacts, not just directory existence (#2942)",
-);
-
-// ── auto-start.ts — milestones/ dir creation must not be dead code ──────────
-
-console.log("\n=== #2942: auto-start milestones/ bootstrap not dead code ===");
-
-const autoStartSrc = readFileSync(
-  join(import.meta.dirname, "..", "auto-start.ts"),
-  "utf-8",
-);
-
-// After ensureGsdSymlink, the code that creates milestones/ must check for
-// the milestones directory specifically (not .gsd/ which ensureGsdSymlink already created).
-const symlinkIdx = autoStartSrc.indexOf("ensureGsdSymlink(base)");
-assertTrue(symlinkIdx >= 0, "auto-start.ts calls ensureGsdSymlink(base)");
-
-const afterSymlink = symlinkIdx >= 0 ? autoStartSrc.slice(symlinkIdx, symlinkIdx + 800) : "";
-
-// The milestones bootstrap must check milestones path, not gsdDir
-// Old (dead) code: if (!existsSync(gsdDir)) { mkdirSync(join(gsdDir, "milestones"), ...) }
-// Fixed code should check: if (!existsSync(milestonesPath)) or similar
-assertTrue(
-  afterSymlink.includes("milestones") && afterSymlink.includes("mkdirSync"),
-  "auto-start.ts creates milestones/ directory after ensureGsdSymlink (#2942)",
-);
-
-// The guard for milestones/ creation should NOT be `!existsSync(gsdDir)` —
-// that's dead code since ensureGsdSymlink already created gsdDir.
-// It should check for the milestones/ dir directly.
-const mkdirRegion = afterSymlink.slice(0, afterSymlink.indexOf("mkdirSync") + 200);
-assertMatch(
-  mkdirRegion,
-  /existsSync\([^)]*milestones/,
-  "milestones bootstrap checks milestones path existence, not .gsd/ (#2942)",
-);
-
-report();
+import { tmpdir } from "node:os";
+
+import { hasGsdBootstrapArtifacts } from "../detection.ts";
+
+function makeGsdDir(t: { after: (fn: () => void) => void }): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-zombie-state-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test("#2942: missing .gsd/ directory entirely → treated as un-bootstrapped", () => {
+  assert.equal(
+    hasGsdBootstrapArtifacts("/nonexistent/path/does/not/exist/.gsd"),
+    false,
+  );
+});
+
+test("#2942: zombie .gsd/ (empty directory) must NOT count as bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  // Only the directory exists — neither PREFERENCES.md nor milestones/
+  assert.equal(
+    hasGsdBootstrapArtifacts(gsd),
+    false,
+    "an empty .gsd/ is a zombie state — init wizard must still run",
+  );
+});
+
+test("#2942: .gsd/ with PREFERENCES.md counts as bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  writeFileSync(join(gsd, "PREFERENCES.md"), "# prefs\n");
+  assert.equal(hasGsdBootstrapArtifacts(gsd), true);
+});
+
+test("#2942: .gsd/ with milestones/ directory counts as bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  mkdirSync(join(gsd, "milestones"));
+  assert.equal(hasGsdBootstrapArtifacts(gsd), true);
+});
+
+test("#2942: both artifacts present → bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  writeFileSync(join(gsd, "PREFERENCES.md"), "# prefs\n");
+  mkdirSync(join(gsd, "milestones"));
+  assert.equal(hasGsdBootstrapArtifacts(gsd), true);
+});
+
+test("#2942: injected existsFn — zombie via predicate is rejected", () => {
+  // Only the .gsd/ directory exists; artifacts are missing.
+  const existsFn = (p: string) => p === "/proj/.gsd";
+  assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), false);
+});
+
+test("#2942: injected existsFn — PREFERENCES.md alone is enough", () => {
+  const existsFn = (p: string) =>
+    p === "/proj/.gsd" || p === "/proj/.gsd/PREFERENCES.md";
+  assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), true);
+});
+
+test("#2942: injected existsFn — milestones/ alone is enough", () => {
+  const existsFn = (p: string) =>
+    p === "/proj/.gsd" || p === "/proj/.gsd/milestones";
+  assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), true);
+});

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/complete-milestone.ts

@@ -7,7 +7,7 @@
  */
 
 import { join } from "node:path";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, existsSync } from "node:fs";
 
 import {
   transaction,
@@ -202,14 +202,20 @@ export async function handleCompleteMilestone(
     summaryPath = join(manualDir, `${params.milestoneId}-SUMMARY.md`);
   }
 
-  try {
-    await saveFile(summaryPath, summaryMd);
-  } catch (renderErr) {
-    // Disk render failed — roll back DB status so state stays consistent
-    logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}`);
-    updateMilestoneStatus(params.milestoneId, 'active', null);
-    invalidateStateCache();
-    return { error: `disk render failed: ${(renderErr as Error).message}` };
+  // Guard (#4598): if SUMMARY.md already exists on disk, do not overwrite it.
+  // This handles re-dispatch scenarios (DB/disk state divergence) where a prior
+  // completion already wrote the file. Overwriting would silently destroy the
+  // richer content the agent produced during the original completion run.
+  if (!existsSync(summaryPath)) {
+    try {
+      await saveFile(summaryPath, summaryMd);
+    } catch (renderErr) {
+      // Disk render failed — roll back DB status so state stays consistent
+      logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}`);
+      updateMilestoneStatus(params.milestoneId, 'active', null);
+      invalidateStateCache();
+      return { error: `disk render failed: ${(renderErr as Error).message}` };
+    }
   }
 
   // Invalidate all caches

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -30,6 +30,7 @@ import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapCheckboxes } from "../markdown-renderer.js";
+import { isStaleWrite } from "../auto/turn-epoch.js";
 import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
@@ -40,6 +41,14 @@ export interface CompleteSliceResult {
   milestoneId: string;
   summaryPath: string;
   uatPath: string;
+  /**
+   * True when this call re-completed an already-closed slice from a turn
+   * superseded by timeout recovery or cancellation. Response is shaped like
+   * success so the orphaned LLM tool call unwinds cleanly without mutating
+   * state.
+   */
+  duplicate?: boolean;
+  stale?: boolean;
 }
 
 /**
@@ -283,6 +292,10 @@ export async function handleCompleteSlice(
 
     const slice = getSlice(params.milestoneId, params.sliceId);
     if (slice && isClosedStatus(slice.status)) {
+      if (isStaleWrite("complete-slice")) {
+        guardError = "__stale_duplicate__";
+        return;
+      }
       guardError = `slice ${params.sliceId} is already complete — use gsd_slice_reopen first if you need to redo it`;
       return;
     }
@@ -307,6 +320,31 @@ export async function handleCompleteSlice(
     updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
   });
 
+  if (guardError === "__stale_duplicate__") {
+    // Stale duplicate from a turn superseded by timeout recovery. Return a
+    // non-mutating success so the orphaned LLM tool call unwinds quietly.
+    const sliceDir = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+    const staleSummaryPath = sliceDir
+      ? join(sliceDir, `${params.sliceId}-SUMMARY.md`)
+      : join(
+          basePath,
+          ".gsd",
+          "milestones",
+          params.milestoneId,
+          "slices",
+          params.sliceId,
+          `${params.sliceId}-SUMMARY.md`,
+        );
+    return {
+      sliceId: params.sliceId,
+      milestoneId: params.milestoneId,
+      summaryPath: staleSummaryPath,
+      uatPath: staleSummaryPath.replace(/-SUMMARY\.md$/, "-UAT.md"),
+      duplicate: true,
+      stale: true,
+    };
+  }
+
   if (guardError) {
     return { error: guardError };
   }

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -38,6 +38,7 @@ import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { isStaleWrite } from "../auto/turn-epoch.js";
 import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.js";
 
 export interface CompleteTaskResult {
@@ -45,6 +46,14 @@ export interface CompleteTaskResult {
   sliceId: string;
   milestoneId: string;
   summaryPath: string;
+  /**
+   * True when this call re-completed an already-closed task from a turn that
+   * had been superseded by timeout recovery or cancellation. The underlying
+   * state was not mutated; the response is a no-op shaped like a success so
+   * the orphaned LLM tool call resolves cleanly.
+   */
+  duplicate?: boolean;
+  stale?: boolean;
 }
 
 import type { TaskRow } from "../gsd-db.js";
@@ -211,6 +220,18 @@ export async function handleCompleteTask(
 
     const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
     if (existingTask && isClosedStatus(existingTask.status)) {
+      // Stale-turn path: a timed-out turn that was superseded by recovery
+      // can still reach this code when its LLM call eventually returns and
+      // invokes gsd_complete_task. Returning an error would produce noisy
+      // "already complete — use reopen first" logs in the orphaned turn.
+      // Instead, signal the duplicate via a non-mutating success shape that
+      // callers can detect via `duplicate: true` / `stale: true`.
+      if (isStaleWrite("complete-task")) {
+        // Sentinel handled below — outside the transaction — so we don't
+        // render SUMMARY.md or flip plan checkboxes for a stale duplicate.
+        guardError = "__stale_duplicate__";
+        return;
+      }
       guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
       return;
     }
@@ -248,6 +269,34 @@ export async function handleCompleteTask(
     }
   });
 
+  if (guardError === "__stale_duplicate__") {
+    // Orphaned-turn duplicate: the task is already complete from the
+    // superseded turn's earlier (real) call. Return a non-mutating success
+    // so the stale LLM tool call unwinds cleanly. summaryPath is synthesized
+    // from the existing on-disk layout; no file is written.
+    const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+    const staleSummaryPath = tasksDir
+      ? join(tasksDir, `${params.taskId}-SUMMARY.md`)
+      : join(
+          basePath,
+          ".gsd",
+          "milestones",
+          params.milestoneId,
+          "slices",
+          params.sliceId,
+          "tasks",
+          `${params.taskId}-SUMMARY.md`,
+        );
+    return {
+      taskId: params.taskId,
+      sliceId: params.sliceId,
+      milestoneId: params.milestoneId,
+      summaryPath: staleSummaryPath,
+      duplicate: true,
+      stale: true,
+    };
+  }
+
   if (guardError) {
     return { error: guardError };
   }

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}`;
+}