gsd-pi 2.65.0-dev.d0517ff → 2.66.0-dev.1b4e601

package/src/resources/extensions/gsd/tests/finalize-timeout-guard.test.ts

@@ -19,8 +19,10 @@
 import { createTestContext } from "./test-helpers.ts";
 import {
   withTimeout,
+  FINALIZE_PRE_TIMEOUT_MS,
   FINALIZE_POST_TIMEOUT_MS,
 } from "../auto/finalize-timeout.ts";
+import { MAX_FINALIZE_TIMEOUTS } from "../auto/types.ts";
 
 const { assertTrue, assertEq, report } = createTestContext();
 
@@ -78,6 +80,25 @@ const { assertTrue, assertEq, report } = createTestContext();
   assertTrue(caught, "rejection should propagate");
 }
 
+// ═══ Test: FINALIZE_PRE_TIMEOUT_MS is defined and reasonable ═════════════════
+
+{
+  console.log("\n=== #3757: pre-verification timeout constant is defined and reasonable ===");
+
+  assertTrue(
+    typeof FINALIZE_PRE_TIMEOUT_MS === "number",
+    "FINALIZE_PRE_TIMEOUT_MS should be a number",
+  );
+  assertTrue(
+    FINALIZE_PRE_TIMEOUT_MS >= 30_000,
+    `pre timeout should be >= 30s (got ${FINALIZE_PRE_TIMEOUT_MS}ms)`,
+  );
+  assertTrue(
+    FINALIZE_PRE_TIMEOUT_MS <= 120_000,
+    `pre timeout should be <= 120s (got ${FINALIZE_PRE_TIMEOUT_MS}ms)`,
+  );
+}
+
 // ═══ Test: FINALIZE_POST_TIMEOUT_MS is defined and reasonable ═════════════════
 
 {
@@ -113,4 +134,108 @@ const { assertTrue, assertEq, report } = createTestContext();
   assertEq(result.timedOut, false, "should not time out");
 }
 
+// ═══ Test: runFinalize wraps BOTH pre and post verification with withTimeout ═
+
+{
+  console.log("\n=== #3757: runFinalize wraps preVerification with timeout guard ===");
+
+  const { readFileSync } = await import("node:fs");
+  const phasesSource = readFileSync(
+    new URL("../auto/phases.ts", import.meta.url),
+    "utf-8",
+  );
+
+  // Find the runFinalize function body
+  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
+  assertTrue(fnIdx > 0, "runFinalize function should exist in phases.ts");
+
+  const fnBody = phasesSource.slice(fnIdx, fnIdx + 8000);
+
+  // postUnitPreVerification must be wrapped in withTimeout
+  const preTimeoutIdx = fnBody.indexOf("withTimeout(");
+  assertTrue(preTimeoutIdx > 0, "withTimeout should appear in runFinalize");
+
+  const preVerIdx = fnBody.indexOf("postUnitPreVerification");
+  assertTrue(preVerIdx > 0, "postUnitPreVerification should appear in runFinalize");
+
+  // The first withTimeout should wrap postUnitPreVerification (not postUnitPostVerification)
+  const firstWithTimeout = fnBody.slice(preTimeoutIdx, preTimeoutIdx + 200);
+  assertTrue(
+    firstWithTimeout.includes("postUnitPreVerification"),
+    "first withTimeout in runFinalize should wrap postUnitPreVerification",
+  );
+
+  // postUnitPostVerification must also be wrapped
+  const postVerIdx = fnBody.indexOf("postUnitPostVerification");
+  assertTrue(postVerIdx > 0, "postUnitPostVerification should appear in runFinalize");
+
+  // Count withTimeout occurrences — should be at least 2 (pre + post)
+  const timeoutCount = (fnBody.match(/withTimeout\(/g) || []).length;
+  assertTrue(
+    timeoutCount >= 2,
+    `runFinalize should have at least 2 withTimeout guards (found ${timeoutCount})`,
+  );
+}
+
+// ═══ Test: MAX_FINALIZE_TIMEOUTS is defined and reasonable ═══════════════════
+
+{
+  console.log("\n=== #3757: MAX_FINALIZE_TIMEOUTS is defined and reasonable ===");
+
+  assertTrue(
+    typeof MAX_FINALIZE_TIMEOUTS === "number",
+    "MAX_FINALIZE_TIMEOUTS should be a number",
+  );
+  assertTrue(
+    MAX_FINALIZE_TIMEOUTS >= 2,
+    `threshold should be >= 2 (got ${MAX_FINALIZE_TIMEOUTS})`,
+  );
+  assertTrue(
+    MAX_FINALIZE_TIMEOUTS <= 10,
+    `threshold should be <= 10 (got ${MAX_FINALIZE_TIMEOUTS})`,
+  );
+}
+
+// ═══ Test: timeout handlers escalate after consecutive timeouts ══════════════
+
+{
+  console.log("\n=== #3757: timeout handlers escalate and detach currentUnit ===");
+
+  const { readFileSync } = await import("node:fs");
+  const phasesSource = readFileSync(
+    new URL("../auto/phases.ts", import.meta.url),
+    "utf-8",
+  );
+
+  const fnIdx = phasesSource.indexOf("export async function runFinalize(");
+  const fnBody = phasesSource.slice(fnIdx, fnIdx + 8000);
+
+  // Both timeout handlers should increment consecutiveFinalizeTimeouts
+  const incrementCount = (fnBody.match(/consecutiveFinalizeTimeouts\+\+/g) || []).length;
+  assertTrue(
+    incrementCount >= 2,
+    `should increment consecutiveFinalizeTimeouts in both pre and post handlers (found ${incrementCount})`,
+  );
+
+  // Both timeout handlers should check MAX_FINALIZE_TIMEOUTS for escalation
+  const escalationCount = (fnBody.match(/MAX_FINALIZE_TIMEOUTS/g) || []).length;
+  assertTrue(
+    escalationCount >= 2,
+    `should check MAX_FINALIZE_TIMEOUTS in both handlers (found ${escalationCount})`,
+  );
+
+  // Both timeout handlers should null out s.currentUnit to prevent late mutations
+  const detachCount = (fnBody.match(/s\.currentUnit\s*=\s*null/g) || []).length;
+  assertTrue(
+    detachCount >= 2,
+    `should detach s.currentUnit in both timeout handlers (found ${detachCount})`,
+  );
+
+  // Successful finalize should reset the counter
+  assertTrue(
+    fnBody.includes("consecutiveFinalizeTimeouts = 0"),
+    "should reset consecutiveFinalizeTimeouts on successful finalize",
+  );
+}
+
 report();

package/src/resources/extensions/gsd/tests/format-shortcut.test.ts

@@ -0,0 +1,69 @@
+// GSD Extension — formatShortcut tests
+// Verifies OS-specific keyboard shortcut rendering.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { formatShortcut } from '../files.ts';
+
+// ─── formatShortcut renders per-platform shortcuts ──────────────────────
+
+test('formatShortcut: converts Ctrl+Alt combo on macOS', () => {
+  // formatShortcut uses process.platform at module load time.
+  // We can only test the current platform's behavior.
+  const result = formatShortcut('Ctrl+Alt+G');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃⌥G', 'macOS should use ⌃⌥ symbols');
+  } else {
+    assert.strictEqual(result, 'Ctrl+Alt+G', 'non-macOS should pass through unchanged');
+  }
+});
+
+test('formatShortcut: converts Ctrl+Alt+N', () => {
+  const result = formatShortcut('Ctrl+Alt+N');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃⌥N');
+  } else {
+    assert.strictEqual(result, 'Ctrl+Alt+N');
+  }
+});
+
+test('formatShortcut: converts Ctrl+Alt+B', () => {
+  const result = formatShortcut('Ctrl+Alt+B');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃⌥B');
+  } else {
+    assert.strictEqual(result, 'Ctrl+Alt+B');
+  }
+});
+
+test('formatShortcut: converts standalone Ctrl modifier', () => {
+  const result = formatShortcut('Ctrl+C');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌃C');
+  } else {
+    assert.strictEqual(result, 'Ctrl+C');
+  }
+});
+
+test('formatShortcut: converts Shift modifier', () => {
+  const result = formatShortcut('Shift+Tab');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⇧Tab');
+  } else {
+    assert.strictEqual(result, 'Shift+Tab');
+  }
+});
+
+test('formatShortcut: converts Cmd modifier', () => {
+  const result = formatShortcut('Cmd+S');
+  if (process.platform === 'darwin') {
+    assert.strictEqual(result, '⌘S');
+  } else {
+    assert.strictEqual(result, 'Cmd+S');
+  }
+});
+
+test('formatShortcut: passes through plain key names', () => {
+  assert.strictEqual(formatShortcut('Escape'), 'Escape');
+  assert.strictEqual(formatShortcut('Enter'), 'Enter');
+});

package/src/resources/extensions/gsd/tests/journal-integration.test.ts

@@ -216,7 +216,7 @@ test("runDispatch emits dispatch-match with correct rule and flowId", async () =
     mid: "M001",
     midTitle: "Test Milestone",
   };
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const result = await runDispatch(ic, preData, loopState);
 
@@ -248,7 +248,7 @@ test("runDispatch emits dispatch-stop when dispatch returns stop action", async
     mid: "M001",
     midTitle: "Test",
   };
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const result = await runDispatch(ic, preData, loopState);
   assert.equal(result.action, "break");
@@ -303,6 +303,7 @@ test("runDispatch checks prior-slice completion against the project root in work
   const result = await runDispatch(ic, preData, {
     recentUnits: [],
     stuckRecoveryAttempts: 0,
+    consecutiveFinalizeTimeouts: 0,
   });
 
   assert.equal(result.action, "next");
@@ -343,7 +344,7 @@ test("runUnitPhase emits unit-start and unit-end with causedBy reference", async
     isRetry: false,
     previousTier: undefined,
   };
-  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   // Start runUnitPhase (it will block on runUnit internally)
   const unitPromise = runUnitPhase(ic, iterData, loopState);
@@ -400,7 +401,7 @@ test("all events from a mock iteration have monotonically increasing seq and sam
     mid: "M001",
     midTitle: "Test",
   };
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
   const dispatchResult = await runDispatch(ic, preData, loopState);
   assert.equal(dispatchResult.action, "next");
 
@@ -446,7 +447,7 @@ test("dispatch-match events include matchedRule field matching the rule name", a
     midTitle: "Test",
   };
 
-  await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0 });
+  await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 });
 
   const matchEvents = capture.events.filter(e => e.eventType === "dispatch-match");
   assert.equal(matchEvents.length, 1);
@@ -475,7 +476,7 @@ test("pre-dispatch-hook event is emitted when hooks fire", async () => {
     midTitle: "Test",
   };
 
-  await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0 });
+  await runDispatch(ic, preData, { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 });
 
   const hookEvents = capture.events.filter(e => e.eventType === "pre-dispatch-hook");
   assert.equal(hookEvents.length, 1, "should emit one pre-dispatch-hook event");
@@ -497,7 +498,7 @@ test("terminal event is emitted on milestone-complete", async () => {
     }) as any,
   });
   const ic = makeIC(deps);
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const result = await runPreDispatch(ic, loopState);
   assert.equal(result.action, "break");
@@ -521,7 +522,7 @@ test("terminal event is emitted on blocked state", async () => {
     }) as any,
   });
   const ic = makeIC(deps);
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const result = await runPreDispatch(ic, loopState);
   assert.equal(result.action, "break");
@@ -550,7 +551,7 @@ test("milestone-transition event is emitted when milestone changes", async () =>
   const ic = makeIC(deps);
   // Session says current milestone is M001, but state will return M002
   ic.s.currentMilestoneId = "M001";
-  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   await runPreDispatch(ic, loopState);
 
@@ -580,7 +581,7 @@ test("unit-end event contains errorContext when unit is cancelled with structure
     isRetry: false,
     previousTier: undefined,
   };
-  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0 };
+  const loopState: LoopState = { recentUnits: [{ key: "execute-task/M001/S01/T01" }], stuckRecoveryAttempts: 0, consecutiveFinalizeTimeouts: 0 };
 
   const unitPromise = runUnitPhase(ic, iterData, loopState);
   await new Promise(r => setTimeout(r, 50));

package/src/resources/extensions/gsd/tests/orphaned-worktree-audit.test.ts

@@ -0,0 +1,189 @@
+// GSD2 — Tests for auditOrphanedMilestoneBranches bootstrap audit
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+
+import { auditOrphanedMilestoneBranches } from "../auto-start.ts";
+import { openDatabase, closeDatabase, insertMilestone, updateMilestoneStatus } from "../gsd-db.ts";
+
+function run(cmd: string, cwd: string): string {
+  return execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+}
+
+/** Create a temp git repo with .gsd structure and DB. */
+function createRepo(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "orphan-audit-test-")));
+  run("git init", dir);
+  run("git config user.email test@test.com", dir);
+  run("git config user.name Test", dir);
+
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  run("git add .", dir);
+  run("git commit -m init", dir);
+  run("git branch -M main", dir);
+
+  // Create .gsd structure on disk (not tracked in git)
+  mkdirSync(join(dir, ".gsd", "milestones", "M001"), { recursive: true });
+
+  return dir;
+}
+
+describe("auditOrphanedMilestoneBranches", () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = createRepo();
+    openDatabase(join(dir, ".gsd", "gsd.db"));
+  });
+
+  afterEach(() => {
+    closeDatabase();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("no milestone branches → no-op", () => {
+    const result = auditOrphanedMilestoneBranches(dir, "worktree");
+    assert.deepStrictEqual(result.recovered, []);
+    assert.deepStrictEqual(result.warnings, []);
+  });
+
+  test("skips in none isolation mode", () => {
+    // Create a milestone branch that would otherwise be detected
+    run("git branch milestone/M001", dir);
+    insertMilestone({ id: "M001", title: "Test", status: "complete" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "none");
+    assert.deepStrictEqual(result.recovered, []);
+    assert.deepStrictEqual(result.warnings, []);
+
+    // Branch should still exist
+    const branches = run("git branch --list milestone/M001", dir);
+    assert.ok(branches.includes("milestone/M001"), "branch should be preserved in none mode");
+  });
+
+  test("deletes merged branch for completed milestone", () => {
+    // Create milestone branch from main (so it's already merged)
+    run("git branch milestone/M001", dir);
+    insertMilestone({ id: "M001", title: "Test", status: "complete" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree");
+
+    assert.ok(result.recovered.length > 0, "should have recovered actions");
+    assert.ok(
+      result.recovered.some(r => r.includes("Deleted merged branch milestone/M001")),
+      "should report branch deletion",
+    );
+    assert.deepStrictEqual(result.warnings, []);
+
+    // Branch should be gone
+    const branches = run("git branch --list milestone/M001", dir);
+    assert.deepStrictEqual(branches, "", "branch should be deleted");
+  });
+
+  test("warns about unmerged branch for completed milestone", () => {
+    // Create milestone branch with divergent commits (not merged into main)
+    run("git checkout -b milestone/M001", dir);
+    writeFileSync(join(dir, "feature.txt"), "new feature\n");
+    run("git add feature.txt", dir);
+    run("git commit -m \"add feature on milestone branch\"", dir);
+    run("git checkout main", dir);
+
+    insertMilestone({ id: "M001", title: "Test", status: "complete" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree");
+
+    assert.deepStrictEqual(result.recovered, [], "should not delete unmerged branch");
+    assert.ok(result.warnings.length > 0, "should have warnings");
+    assert.ok(
+      result.warnings.some(w => w.includes("NOT merged")),
+      "should warn about unmerged branch",
+    );
+
+    // Branch should still exist (data safety)
+    const branches = run("git branch --list milestone/M001", dir);
+    assert.ok(branches.includes("milestone/M001"), "unmerged branch must be preserved");
+  });
+
+  test("skips active (non-complete) milestone branches", () => {
+    run("git branch milestone/M001", dir);
+    insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree");
+
+    assert.deepStrictEqual(result.recovered, []);
+    assert.deepStrictEqual(result.warnings, []);
+
+    // Branch should still exist
+    const branches = run("git branch --list milestone/M001", dir);
+    assert.ok(branches.includes("milestone/M001"), "active milestone branch should be preserved");
+  });
+
+  test("cleans up orphaned worktree directory for merged milestone", () => {
+    // Create milestone branch (merged — same as main)
+    run("git branch milestone/M001", dir);
+    insertMilestone({ id: "M001", title: "Test", status: "complete" });
+
+    // Create orphaned worktree directory
+    const wtDir = join(dir, ".gsd", "worktrees", "M001");
+    mkdirSync(wtDir, { recursive: true });
+    writeFileSync(join(wtDir, "leftover.txt"), "orphaned file\n");
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree");
+
+    assert.ok(result.recovered.length > 0, "should have recovered actions");
+    assert.ok(
+      result.recovered.some(r => r.includes("worktree directory")),
+      "should report worktree cleanup",
+    );
+
+    // Worktree directory should be cleaned up
+    assert.ok(!existsSync(wtDir), "orphaned worktree directory should be removed");
+  });
+
+  test("handles multiple milestones with mixed states", () => {
+    // M001: complete, branch merged → should clean up
+    run("git branch milestone/M001", dir);
+    insertMilestone({ id: "M001", title: "First", status: "complete" });
+
+    // M002: active, branch exists → should skip
+    run("git branch milestone/M002", dir);
+    insertMilestone({ id: "M002", title: "Second", status: "active" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree");
+
+    // M001 should be cleaned up
+    assert.ok(
+      result.recovered.some(r => r.includes("M001")),
+      "should clean up completed M001",
+    );
+
+    // M002 should not be touched
+    const branches = run("git branch --list milestone/M002", dir);
+    assert.ok(branches.includes("milestone/M002"), "active M002 branch should be preserved");
+  });
+
+  test("works in branch isolation mode", () => {
+    run("git branch milestone/M001", dir);
+    insertMilestone({ id: "M001", title: "Test", status: "complete" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "branch");
+
+    assert.ok(result.recovered.length > 0, "should work in branch mode too");
+    assert.ok(
+      result.recovered.some(r => r.includes("Deleted merged branch")),
+      "should delete branch in branch mode",
+    );
+  });
+
+  test("handles milestone in DB but no branch (no-op)", () => {
+    insertMilestone({ id: "M001", title: "Test", status: "complete" });
+
+    const result = auditOrphanedMilestoneBranches(dir, "worktree");
+
+    assert.deepStrictEqual(result.recovered, []);
+    assert.deepStrictEqual(result.warnings, []);
+  });
+});

package/src/resources/extensions/gsd/tests/pre-execution-checks.test.ts

@@ -1083,11 +1083,77 @@ describe("checkTaskOrdering false positive regression (#3677)", () => {
     const results = checkTaskOrdering(tasks, "/tmp");
     assert.equal(results.length, 0, "Normalized task.files path should not trigger a false positive");
   });
+
+  test("annotated inputs still trigger ordering violations against later plain outputs", () => {
+    const tasks = [
+      createTask({
+        id: "T01",
+        sequence: 0,
+        files: [],
+        inputs: ["`later.ts` — needed first"],
+        expected_output: [],
+      }),
+      createTask({
+        id: "T02",
+        sequence: 1,
+        files: [],
+        inputs: [],
+        expected_output: ["later.ts"],
+      }),
+    ];
+
+    const results = checkTaskOrdering(tasks, "/tmp");
+    assert.equal(results.length, 1, "Annotated inputs should still match later plain expected_output entries");
+    assert.equal(results[0].target, "`later.ts` — needed first");
+    assert.ok(results[0].message.includes("sequence violation"));
+  });
 });
 
 // ─── checkFilePathConsistency additional edge cases ──────────────────────────
 
 describe("checkFilePathConsistency additional edge cases", () => {
+  test("annotated inputs match files that already exist on disk", () => {
+    const tempDir = join(tmpdir(), `pre-exec-test-annotated-input-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+    writeFileSync(join(tempDir, "existing.ts"), "// content");
+
+    try {
+      const tasks = [
+        createTask({
+          id: "T01",
+          files: [],
+          inputs: ["`existing.ts` — file already on disk"],
+          expected_output: [],
+        }),
+      ];
+
+      const results = checkFilePathConsistency(tasks, tempDir);
+      assert.equal(results.length, 0, "Annotated inputs should resolve to the on-disk file path");
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  test("plain inputs match prior annotated expected outputs", () => {
+    const tasks = [
+      createTask({
+        id: "T01",
+        files: [],
+        inputs: [],
+        expected_output: ["`generated.ts` — created earlier"],
+      }),
+      createTask({
+        id: "T02",
+        files: [],
+        inputs: ["generated.ts"],
+        expected_output: [],
+      }),
+    ];
+
+    const results = checkFilePathConsistency(tasks, "/tmp");
+    assert.equal(results.length, 0, "Prior annotated expected_output entries should satisfy later plain inputs");
+  });
+
   test("inputs referencing glob-like patterns should not crash", () => {
     // A glob pattern in inputs is unusual but should be handled gracefully.
     // The file won't exist on disk, so it should produce a blocking result.

package/src/resources/extensions/gsd/tests/subagent-agent-discovery.test.ts

@@ -42,3 +42,50 @@ test("discoverAgents falls back to legacy .pi/agents when needed", (t) => {
 	assert.equal(discovery.projectAgentsDir, agentsDir);
 	assert.deepEqual(discovery.agents.map((agent) => agent.name), ["ping"]);
 });
+
+test("discoverAgents accepts tools frontmatter as a YAML list", (t) => {
+	const root = makeProjectRoot(t);
+	const agentsDir = join(root, ".gsd", "agents");
+	mkdirSync(agentsDir, { recursive: true });
+	writeFileSync(
+		join(agentsDir, "reviewer.md"),
+		[
+			"---",
+			"name: reviewer",
+			"description: review agent",
+			"tools:",
+			"  - bash",
+			"  - read",
+			"---",
+			"Review code",
+			"",
+		].join("\n"),
+	);
+
+	const discovery = discoverAgents(root, "project");
+
+	assert.deepEqual(discovery.agents.map((agent) => agent.name), ["reviewer"]);
+	assert.deepEqual(discovery.agents[0]?.tools, ["bash", "read"]);
+});
+
+test("discoverAgents still accepts comma-separated tools frontmatter", (t) => {
+	const root = makeProjectRoot(t);
+	const agentsDir = join(root, ".gsd", "agents");
+	mkdirSync(agentsDir, { recursive: true });
+	writeFileSync(
+		join(agentsDir, "reviewer.md"),
+		[
+			"---",
+			"name: reviewer",
+			"description: review agent",
+			"tools: bash, read",
+			"---",
+			"Review code",
+			"",
+		].join("\n"),
+	);
+
+	const discovery = discoverAgents(root, "project");
+
+	assert.deepEqual(discovery.agents[0]?.tools, ["bash", "read"]);
+});

package/src/resources/extensions/subagent/agents.ts

@@ -25,6 +25,33 @@ export interface AgentDiscoveryResult {
 	projectAgentsDir: string | null;
 }
 
+interface AgentFrontmatter extends Record<string, unknown> {
+	name?: string;
+	description?: string;
+	tools?: string | string[];
+	model?: string;
+}
+
+function parseAgentTools(value: string | string[] | undefined): string[] | undefined {
+	if (typeof value === "string") {
+		const tools = value
+			.split(",")
+			.map((tool) => tool.trim())
+			.filter(Boolean);
+		return tools.length > 0 ? tools : undefined;
+	}
+
+	if (Array.isArray(value)) {
+		const tools = value
+			.flatMap((tool) => typeof tool === "string" ? tool.split(",") : [])
+			.map((tool) => tool.trim())
+			.filter(Boolean);
+		return tools.length > 0 ? tools : undefined;
+	}
+
+	return undefined;
+}
+
 function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
@@ -51,16 +78,13 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			continue;
 		}
 
-		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		const { frontmatter, body } = parseFrontmatter<AgentFrontmatter>(content);
 
-		if (!frontmatter.name || !frontmatter.description) {
+		if (typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string") {
 			continue;
 		}
 
-		const tools = frontmatter.tools
-			?.split(",")
-			.map((t: string) => t.trim())
-			.filter(Boolean);
+		const tools = parseAgentTools(frontmatter.tools);
 
 		agents.push({
 			name: frontmatter.name,