gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.538325aea

package/src/resources/extensions/gsd/tests/clean-root-preflight.test.ts

@@ -0,0 +1,186 @@
+/**
+ * clean-root-preflight.test.ts — Regression tests for #2909.
+ *
+ * Tests that preflightCleanRoot warns + stashes on dirty trees,
+ * is a no-op on clean trees, and that postflightPopStash restores
+ * stashed changes after a merge.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import { preflightCleanRoot, postflightPopStash } from "../clean-root-preflight.ts";
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+function createTempRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-preflight-test-")));
+  run("git init", dir);
+  run("git config user.email test@example.com", dir);
+  run("git config user.name Test", dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  mkdirSync(join(dir, ".gsd"), { recursive: true });
+  writeFileSync(join(dir, ".gsd", "STATE.md"), "# State\n");
+  run("git add .", dir);
+  run("git commit -m init", dir);
+  run("git branch -M main", dir);
+  return dir;
+}
+
+// ── Clean tree: fast-path returns immediately without stashing ─────────────
+
+test("preflightCleanRoot — clean tree returns stashPushed=false and emits no notifications", () => {
+  const repo = createTempRepo();
+  try {
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M001", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, false, "stashPushed must be false for clean tree");
+    assert.equal(result.summary, "", "summary must be empty for clean tree");
+    assert.equal(notifications.length, 0, "no notifications on clean tree");
+
+    // Verify no stash was created
+    const stashList = run("git stash list", repo);
+    assert.equal(stashList, "", "no stash entry on clean tree");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Dirty tree: warns, stashes, returns stashPushed=true ──────────────────
+
+test("preflightCleanRoot — dirty tree warns user and auto-stashes", () => {
+  const repo = createTempRepo();
+  try {
+    // Dirty an existing tracked file
+    writeFileSync(join(repo, "README.md"), "# locally modified\n");
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M002", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, true, "stashPushed must be true when tree was dirty");
+    assert.ok(result.summary.length > 0, "summary must be non-empty when stash was pushed");
+
+    // A warning notification must have been emitted before stashing
+    assert.ok(
+      notifications.some(n => n.level === "warning" && n.msg.includes("M002")),
+      "warning notification must mention the milestone ID",
+    );
+
+    // Working tree must now be clean (stash pushed)
+    const status = run("git status --porcelain", repo);
+    assert.equal(status, "", "working tree must be clean after stash push");
+
+    // The stash entry must exist
+    const stashList = run("git stash list", repo);
+    assert.ok(stashList.includes("gsd-preflight-stash"), "stash entry must be named gsd-preflight-stash");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Untracked files are also stashed ─────────────────────────────────────
+
+test("preflightCleanRoot — untracked file triggers stash with --include-untracked", () => {
+  const repo = createTempRepo();
+  try {
+    // Add an untracked file
+    writeFileSync(join(repo, "untracked.ts"), "export const x = 1;\n");
+
+    const notifications: Array<{ msg: string; level: string }> = [];
+    const result = preflightCleanRoot(repo, "M003", (msg, level) => {
+      notifications.push({ msg, level });
+    });
+
+    assert.equal(result.stashPushed, true, "stashPushed must be true for untracked file");
+
+    const status = run("git status --porcelain", repo);
+    assert.equal(status, "", "working tree must be clean after stash push");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── postflightPopStash: restores stashed changes ──────────────────────────
+
+test("postflightPopStash — restores stashed changes and emits info notification", () => {
+  const repo = createTempRepo();
+  try {
+    // Dirty the working tree
+    writeFileSync(join(repo, "README.md"), "# stash me\n");
+
+    const preNotifications: Array<{ msg: string; level: string }> = [];
+    const preflight = preflightCleanRoot(repo, "M004", (msg, level) => {
+      preNotifications.push({ msg, level });
+    });
+    assert.equal(preflight.stashPushed, true, "preflight must have stashed");
+
+    // Simulate the merge (just a no-op commit here)
+    writeFileSync(join(repo, "merged.ts"), "export const merged = true;\n");
+    run("git add .", repo);
+    run('git commit -m "simulate merge"', repo);
+
+    const postNotifications: Array<{ msg: string; level: string }> = [];
+    postflightPopStash(repo, "M004", (msg, level) => {
+      postNotifications.push({ msg, level });
+    });
+
+    // The stashed README.md change must be restored
+    const content = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(content.replace(/\r\n/g, "\n"), "# stash me\n", "stashed file must be restored");
+
+    // An info notification must have been emitted
+    assert.ok(
+      postNotifications.some(n => n.level === "info" && n.msg.includes("M004")),
+      "info notification must mention milestone ID after pop",
+    );
+
+    // Stash list must be empty
+    const stashList = run("git stash list", repo);
+    assert.equal(stashList, "", "stash list must be empty after pop");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});
+
+// ── Round-trip: preflight + merge + postflight preserves changes ──────────
+
+test("preflight + merge + postflight round-trip preserves uncommitted changes", () => {
+  const repo = createTempRepo();
+  try {
+    const originalContent = "# my local work\n";
+    writeFileSync(join(repo, "README.md"), originalContent);
+
+    // Preflight: stash
+    const preflight = preflightCleanRoot(repo, "M005", () => {});
+    assert.equal(preflight.stashPushed, true, "must have stashed");
+
+    // Merge: introduce a new file (no overlap with README.md)
+    writeFileSync(join(repo, "feature.ts"), "export const feature = true;\n");
+    run("git add feature.ts", repo);
+    run('git commit -m "feat: add feature"', repo);
+
+    // Postflight: pop stash
+    postflightPopStash(repo, "M005", () => {});
+
+    // README.md must still have our local content
+    const restored = readFileSync(join(repo, "README.md"), "utf-8");
+    assert.equal(restored.replace(/\r\n/g, "\n"), originalContent, "local changes must survive merge");
+
+    // feature.ts must also exist (the merge commit landed)
+    const featureContent = readFileSync(join(repo, "feature.ts"), "utf-8");
+    assert.ok(featureContent.includes("feature"), "merged feature must be present");
+  } finally {
+    try { rmSync(repo, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 }); } catch { /* ignore */ }
+  }
+});

package/src/resources/extensions/gsd/tests/complete-milestone-false-merge.test.ts

@@ -105,6 +105,21 @@ test("#4175: postUnitPreVerification pauses complete-milestone after retries exh
   );
 });
 
+test("#4658: postUnitPreVerification waits briefly for DB-close on complete-milestone before retrying", () => {
+  assert.ok(
+    /async function waitForMilestoneDbClose/.test(postUnitSrc),
+    "auto-post-unit should define a DB settle helper for complete-milestone",
+  );
+  assert.ok(
+    /setTimeout\(resolve,\s*COMPLETE_MILESTONE_DB_SETTLE_POLL_MS\)/.test(postUnitSrc),
+    "DB settle helper should poll with a bounded timeout window",
+  );
+  assert.ok(
+    /s\.currentUnit\.type\s*===\s*"complete-milestone"[\s\S]*waitForMilestoneDbClose/.test(postUnitSrc),
+    "complete-milestone path should invoke DB settle check before retry flow",
+  );
+});
+
 test("#4175: recoverTimedOutUnit pauses complete-milestone instead of writing a blocker placeholder", () => {
   // The complete-milestone pause branch must sit immediately above the
   // "retries exhausted" writeBlockerPlaceholder call so a failed

package/src/resources/extensions/gsd/tests/complete-milestone.test.ts

@@ -1,11 +1,14 @@
 import { describe, test, afterEach } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { invalidateAllCaches } from '../cache.ts';
 import { parseUnitId } from "../unit-id.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+import { clearPathCache } from "../paths.ts";
+import { clearParseCache } from "../files.ts";
 
 // loadPrompt reads from ~/.gsd/agent/extensions/gsd/prompts/ (main checkout).
 // In a worktree the file may not exist there yet, so we resolve prompts
@@ -404,6 +407,63 @@ describe("complete-milestone", () => {
     }
   });
 
+  test("handleCompleteMilestone does not overwrite existing SUMMARY.md on re-dispatch (#4598)", async () => {
+    // This test verifies that when SUMMARY.md already exists (from a prior completion),
+    // re-calling handleCompleteMilestone does not overwrite it.
+    // Before the fix this test FAILS because the handler unconditionally writes SUMMARY.md.
+    const { handleCompleteMilestone } = await import("../tools/complete-milestone.ts");
+    const base = createFixtureBase();
+    const mid = "M001";
+    const dbPath = join(base, ".gsd", "gsd.db");
+    try {
+      // Set up DB with milestone and a complete slice + task
+      openDatabase(dbPath);
+      insertMilestone({ id: mid, title: "Test Milestone", status: "active" });
+      insertSlice({ id: "S01", milestoneId: mid, title: "Slice One", status: "complete" });
+      insertTask({ id: "T01", sliceId: "S01", milestoneId: mid, title: "Task One", status: "complete" });
+
+      // Pre-write an existing SUMMARY.md to simulate a prior completion
+      const milestoneDir = join(base, ".gsd", "milestones", mid);
+      mkdirSync(milestoneDir, { recursive: true });
+      const summaryPath = join(milestoneDir, `${mid}-SUMMARY.md`);
+      const originalContent = "original content — must not be overwritten";
+      writeFileSync(summaryPath, originalContent, "utf-8");
+
+      // Call handleCompleteMilestone — this is the re-dispatch scenario
+      const params = {
+        milestoneId: mid,
+        title: "Test Milestone",
+        oneLiner: "Re-dispatched",
+        narrative: "This is a re-dispatch",
+        successCriteriaResults: "Met",
+        definitionOfDoneResults: "Done",
+        requirementOutcomes: "Covered",
+        keyDecisions: [],
+        keyFiles: [],
+        lessonsLearned: [],
+        followUps: "",
+        deviations: "",
+        verificationPassed: true,
+      };
+
+      const result = await handleCompleteMilestone(params, base);
+
+      // The call may return an error (milestone already complete) or success
+      // but in either case the SUMMARY.md must NOT be overwritten.
+      const actualContent = readFileSync(summaryPath, "utf-8");
+      assert.strictEqual(
+        actualContent,
+        originalContent,
+        "existing SUMMARY.md must not be overwritten on re-dispatch (#4598)",
+      );
+    } finally {
+      try { closeDatabase(); } catch { /* */ }
+      clearPathCache();
+      clearParseCache();
+      cleanup(base);
+    }
+  });
+
   test("deriveState completing-milestone integration", async () => {
     const { deriveState, isMilestoneComplete } = await import("../state.ts");
     const { invalidateAllCaches: invalidateAllCachesDynamic } = await import("../cache.ts");

package/src/resources/extensions/gsd/tests/complete-slice.test.ts

@@ -125,9 +125,9 @@ console.log('\n=== complete-slice: schema v6 migration ===');
 
   const adapter = _getAdapter()!;
 
-  // Verify schema version is current (v21 — ADR-013 structured_fields column)
+  // Verify schema version is current (v22 — quality_gates DDL fix)
   const versionRow = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assertEq(versionRow?.['v'], 21, 'schema version should be 21');
+  assertEq(versionRow?.['v'], 22, 'schema version should be 22');
 
   // Verify slices table has full_summary_md and full_uat_md columns
   const cols = adapter.prepare("PRAGMA table_info(slices)").all();

package/src/resources/extensions/gsd/tests/complete-task.test.ts

@@ -109,9 +109,9 @@ console.log('\n=== complete-task: schema v5 migration ===');
 
   const adapter = _getAdapter()!;
 
-  // Verify schema version is current (v21 — ADR-013 structured_fields column)
+  // Verify schema version is current (v22 — quality_gates DDL fix)
   const versionRow = adapter.prepare('SELECT MAX(version) as v FROM schema_version').get();
-  assertEq(versionRow?.['v'], 21, 'schema version should be 21');
+  assertEq(versionRow?.['v'], 22, 'schema version should be 22');
 
   // Verify all 4 new tables exist
   const tables = adapter.prepare(

package/src/resources/extensions/gsd/tests/custom-engine-loop-integration.test.ts

@@ -179,6 +179,8 @@ function makeMockDeps(overrides?: Partial<LoopDeps>): LoopDeps & { callLog: stri
     autoWorktreeBranch: () => "auto/M001",
     resolveMilestoneFile: () => null,
     reconcileMergeState: () => "clean",
+    preflightCleanRoot: () => ({ stashPushed: false, summary: "" }),
+    postflightPopStash: () => {},
     getLedger: () => null,
     getProjectTotals: () => ({ cost: 0 }),
     formatCost: (c: number) => `$${c.toFixed(2)}`,

package/src/resources/extensions/gsd/tests/dispatch-complete-milestone-guard.test.ts

@@ -47,21 +47,21 @@ describe("completing-milestone dispatch guard (#4324)", () => {
     assert.ok(dispatchIdx > -1, "complete-milestone dispatch should exist after the skip guard");
   });
 
-  test("imports updateMilestoneStatus for DB reconciliation", () => {
-    assert.match(source, /import\s*\{[^}]*updateMilestoneStatus[^}]*\}\s*from\s*["']\.\/gsd-db/);
-  });
-
-  test("reconciles DB when SUMMARY exists on disk but DB is out of sync", () => {
+  test("classifies SUMMARY outcome and conditionally reconciles DB (#4658)", () => {
     const phaseCheck = source.indexOf('phase !== "completing-milestone"');
     // The SUMMARY-exists reconciliation guard must appear in this rule
     const summaryGuard = source.indexOf('resolveMilestoneFile(basePath, mid, "SUMMARY")', phaseCheck);
     assert.ok(summaryGuard > -1, "SUMMARY file check should exist in the completing-milestone rule");
 
+    const classifyCall = source.indexOf("classifyMilestoneSummaryContent", summaryGuard);
+    assert.ok(classifyCall > -1, "SUMMARY mismatch handling should classify summary content");
+
     const reconcileCall = source.indexOf('updateMilestoneStatus(mid, "complete"', summaryGuard);
-    assert.ok(reconcileCall > -1, "updateMilestoneStatus reconciliation should follow the SUMMARY check");
+    assert.ok(reconcileCall > -1, "successful SUMMARY should reconcile DB to complete");
 
-    // Reconciliation must happen before the dispatch action
-    const dispatchIdx = source.indexOf('unitType: "complete-milestone"', reconcileCall);
-    assert.ok(dispatchIdx > -1, "reconciliation should appear before the dispatch action");
+    const stopAction = source.indexOf('action: "stop"', summaryGuard);
+    assert.ok(stopAction > -1, "SUMMARY mismatch should return stop action");
+    const warningLevel = source.indexOf('level: "warning"', summaryGuard);
+    assert.ok(warningLevel > -1, "SUMMARY mismatch should be warning-level stop (pauses auto-mode)");
   });
 });

package/src/resources/extensions/gsd/tests/dispatch-guard-summary-db-mismatch.test.ts

@@ -0,0 +1,77 @@
+// GSD-2 dispatch-guard regression test: SUMMARY/DB mismatch fail-closed behavior (#4663)
+//
+// Sibling bug to #4658 / PR #4660. A failure-path SUMMARY file on disk
+// must not let the cross-milestone dispatch guard treat an "active"
+// milestone as complete. DB status is authoritative when available.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getPriorSliceCompletionBlocker } from "../dispatch-guard.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice } from "../gsd-db.ts";
+
+function setupRepo(): string {
+  const repo = mkdtempSync(join(tmpdir(), "gsd-dispatch-guard-4663-"));
+  mkdirSync(join(repo, ".gsd"), { recursive: true });
+  openDatabase(join(repo, ".gsd", "gsd.db"));
+  return repo;
+}
+
+function teardownRepo(repo: string): void {
+  closeDatabase();
+  rmSync(repo, { recursive: true, force: true });
+}
+
+test("#4663: dispatch guard blocks when prior milestone has failure SUMMARY but DB is still active", (t) => {
+  const repo = setupRepo();
+  t.after(() => teardownRepo(repo));
+
+  mkdirSync(join(repo, ".gsd", "milestones", "M002"), { recursive: true });
+  mkdirSync(join(repo, ".gsd", "milestones", "M003"), { recursive: true });
+
+  // M002: DB says active with a pending slice, but a failure SUMMARY exists on disk.
+  insertMilestone({ id: "M002", title: "Previous", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M002", title: "Pending", status: "pending", depends: [] });
+
+  insertMilestone({ id: "M003", title: "Current", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M003", title: "First", status: "pending", depends: [] });
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-ROADMAP.md"), "# M002\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M003", "M003-ROADMAP.md"), "# M003\n");
+  writeFileSync(
+    join(repo, ".gsd", "milestones", "M002", "M002-SUMMARY.md"),
+    "# M002 Summary\nverification FAILED — not complete.\n",
+  );
+
+  // Before #4663: SUMMARY presence short-circuited the loop and M002 was skipped,
+  // allowing M003/S01 to dispatch. After: DB status is consulted and M002 still blocks.
+  assert.equal(
+    getPriorSliceCompletionBlocker(repo, "main", "plan-slice", "M003/S01"),
+    "Cannot dispatch plan-slice M003/S01: earlier slice M002/S01 is not complete.",
+  );
+});
+
+test("#4663: dispatch guard allows dispatch when prior milestone has SUMMARY and DB is complete", (t) => {
+  const repo = setupRepo();
+  t.after(() => teardownRepo(repo));
+
+  mkdirSync(join(repo, ".gsd", "milestones", "M002"), { recursive: true });
+  mkdirSync(join(repo, ".gsd", "milestones", "M003"), { recursive: true });
+
+  insertMilestone({ id: "M002", title: "Previous", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M002", title: "Done", status: "complete", depends: [] });
+
+  insertMilestone({ id: "M003", title: "Current", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M003", title: "First", status: "pending", depends: [] });
+
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-ROADMAP.md"), "# M002\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M003", "M003-ROADMAP.md"), "# M003\n");
+  writeFileSync(join(repo, ".gsd", "milestones", "M002", "M002-SUMMARY.md"), "# M002 Summary\nDone.\n");
+
+  assert.equal(
+    getPriorSliceCompletionBlocker(repo, "main", "plan-slice", "M003/S01"),
+    null,
+  );
+});

package/src/resources/extensions/gsd/tests/doctor-providers.test.ts

@@ -768,6 +768,37 @@ test("runProviderChecks detects claude.cmd in PATH on Windows (#4503)", { skip:
   });
 });
 
+test("runProviderChecks detects claude.exe in PATH on Windows (#4548)", { skip: process.platform !== "win32" }, () => {
+  const tmpHome = realpathSync(mkdtempSync(join(tmpdir(), "gsd-providers-cc-exe-home-")));
+  const binDir = join(tmpHome, "bin");
+  mkdirSync(binDir, { recursive: true });
+
+  // Some Windows installs ship a direct claude.exe binary (not a .cmd shim).
+  const fakeClaudeExe = join(binDir, "claude.exe");
+  writeFileSync(fakeClaudeExe, "");
+
+  withEnv({
+    HOME: tmpHome,
+    ANTHROPIC_API_KEY: undefined,
+    ANTHROPIC_OAUTH_TOKEN: undefined,
+    COPILOT_GITHUB_TOKEN: undefined,
+    GH_TOKEN: undefined,
+    GITHUB_TOKEN: undefined,
+    PATH: `${binDir};${process.env.PATH ?? ""}`,
+    PATHEXT: ".COM;.EXE;.BAT;.CMD",
+  }, () => {
+    try {
+      const results = runProviderChecks();
+      const anthropic = results.find(r => r.name === "anthropic");
+      assert.ok(anthropic, "anthropic result should exist");
+      assert.equal(anthropic!.status, "ok", "should be ok when claude.exe is in PATH (#4548)");
+      assert.ok(anthropic!.message.toLowerCase().includes("claude"), "should mention claude-code as source");
+    } finally {
+      rmSync(tmpHome, { recursive: true, force: true });
+    }
+  });
+});
+
 test("PROVIDER_ROUTES includes google-gemini-cli as route for google (#2922)", async () => {
   const { readFileSync: readFS } = await import("node:fs");
   const { dirname: dirn, join: joinPath } = await import("node:path");

package/src/resources/extensions/gsd/tests/double-merge-guard.test.ts

@@ -42,7 +42,7 @@ describe("double mergeAndExit guard (#2645)", () => {
     const allCompleteIdx = phasesSrc.indexOf("incomplete.length === 0");
     assert.ok(allCompleteIdx > 0, "phases.ts should have an all-milestones-complete check");
 
-    const afterAllComplete = phasesSrc.slice(allCompleteIdx, allCompleteIdx + 600);
+    const afterAllComplete = phasesSrc.slice(allCompleteIdx, allCompleteIdx + 800);
     const mergeIdx = afterAllComplete.indexOf("deps.resolver.mergeAndExit");
     const flagIdx = afterAllComplete.indexOf("s.milestoneMergedInPhases = true");
 

package/src/resources/extensions/gsd/tests/ensure-db-open.test.ts

@@ -389,7 +389,7 @@ describe('ensure-db-open', () => {
       assert.ok(db, 'adapter should be available after ensureDbOpen');
       assert.equal(
         db.prepare('SELECT MAX(version) as version FROM schema_version').get()?.version,
-        21,
+        22,
         'legacy DB should migrate to current schema version',
       );
 

package/src/resources/extensions/gsd/tests/escalation.test.ts

@@ -348,7 +348,7 @@ test("ADR-011 P2: schema v20 fresh DB has all escalation columns on tasks + sour
   assert.ok(decCols.includes("source"), "decisions table must have source column");
 
   const version = adapter.prepare("SELECT MAX(version) as v FROM schema_version").get();
-  assert.equal(version?.["v"], 21);
+  assert.equal(version?.["v"], 22);
 });
 
 test("ADR-011 P2: findUnappliedEscalationOverride returns null when escalation_pending=1 (still pending)", (t) => {

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

@@ -122,3 +122,116 @@ test('executeExecSearch: includes stdout_path and preview in details', () => {
     cleanup(base);
   }
 });
+
+// ── Path traversal security tests (issue #4590) ───────────────────────────
+
+test('safeReadMeta: ignores malicious stdout_path in JSON, derives path from meta file location', () => {
+  // Arrange: write a .meta.json whose JSON content has a path-traversal value
+  // in stdout_path / stderr_path. The read-side must silently discard these
+  // and derive sibling paths from the actual .meta.json location instead.
+  const base = freshBase();
+  try {
+    const dir = join(base, '.gsd', 'exec');
+    mkdirSync(dir, { recursive: true });
+    const id = 'traversal-test-run';
+    const metaPath = join(dir, `${id}.meta.json`);
+    const stdoutPath = join(dir, `${id}.stdout`);
+    const stderrPath = join(dir, `${id}.stderr`);
+    // Write real sibling files so digest_preview can succeed.
+    writeFileSync(stdoutPath, 'legitimate stdout content\n');
+    writeFileSync(stderrPath, '');
+    // Write a meta.json that tries to point stdout_path outside the exec dir.
+    writeFileSync(
+      metaPath,
+      JSON.stringify({
+        id,
+        runtime: 'bash',
+        purpose: 'test run',
+        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: 24,
+        stderr_bytes: 0,
+        stdout_truncated: false,
+        stderr_truncated: false,
+        // These malicious values must NEVER be used as filesystem paths.
+        stdout_path: '../../etc/passwd',
+        stderr_path: '../../etc/shadow',
+      }),
+    );
+
+    const entries = listExecHistory(base);
+    assert.equal(entries.length, 1);
+    const entry = entries[0]!;
+
+    // stdout_path must be derived from the meta file location, not from JSON.
+    assert.equal(entry.stdout_path, stdoutPath,
+      `stdout_path must be a sibling of the meta file; got: ${entry.stdout_path}`);
+    assert.equal(entry.stderr_path, stderrPath,
+      `stderr_path must be a sibling of the meta file; got: ${entry.stderr_path}`);
+
+    // Verify neither traversal string leaked into the returned entry.
+    assert.ok(!entry.stdout_path.includes('..'),
+      `stdout_path must not contain path traversal sequences: ${entry.stdout_path}`);
+    assert.ok(!entry.stderr_path.includes('..'),
+      `stderr_path must not contain path traversal sequences: ${entry.stderr_path}`);
+    assert.ok(!entry.stdout_path.includes('etc/passwd'),
+      `stdout_path must not point to /etc/passwd: ${entry.stdout_path}`);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('searchExecHistory: digest_preview is read from derived sibling path, not JSON stdout_path', () => {
+  // Arrange: a .meta.json with a malicious stdout_path pointing to /etc/passwd.
+  // The digest_preview should be read from the real sibling .stdout file,
+  // not from the JSON-supplied path.
+  const base = freshBase();
+  try {
+    const dir = join(base, '.gsd', 'exec');
+    mkdirSync(dir, { recursive: true });
+    const id = 'preview-traversal-run';
+    const metaPath = join(dir, `${id}.meta.json`);
+    const stdoutPath = join(dir, `${id}.stdout`);
+    writeFileSync(stdoutPath, 'safe-sentinel-content\n');
+    writeFileSync(join(dir, `${id}.stderr`), '');
+    writeFileSync(
+      metaPath,
+      JSON.stringify({
+        id,
+        runtime: 'bash',
+        purpose: null,
+        started_at: '2026-04-20T12:00:00.000Z',
+        finished_at: '2026-04-20T12:00:00.100Z',
+        duration_ms: 50,
+        exit_code: 0,
+        signal: null,
+        timed_out: false,
+        stdout_bytes: 21,
+        stderr_bytes: 0,
+        stdout_truncated: false,
+        stderr_truncated: false,
+        // Attacker-controlled path — must be ignored.
+        stdout_path: '/etc/passwd',
+        stderr_path: '/etc/shadow',
+      }),
+    );
+
+    const hits = searchExecHistory(base, {});
+    assert.equal(hits.length, 1);
+    const hit = hits[0]!;
+
+    // The preview must come from the safe sibling, not /etc/passwd.
+    assert.ok(
+      hit.digest_preview?.includes('safe-sentinel-content'),
+      `digest_preview should contain safe-sentinel-content; got: ${hit.digest_preview}`,
+    );
+    // Ensure the entry paths are the derived ones.
+    assert.equal(hit.entry.stdout_path, stdoutPath);
+  } finally {
+    cleanup(base);
+  }
+});