@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

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

@@ -0,0 +1,273 @@
+// gsd-pi — Dispatch History module tests (#482 / #442 deepening)
+//
+// Covers: canonical key building and legacy-key normalization, window
+// record/evict semantics, ledger error attachment, cross-session rehydration
+// from unit_dispatches (the #482 regression: a fresh history rehydrated from
+// the DB must detect a re-dispatch loop that spans session restarts),
+// retry-budget suppression, and clearOnRecovery.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+} from "../gsd-db.ts";
+import { registerAutoWorker } from "../db/auto-workers.ts";
+import { claimMilestoneLease } from "../db/milestone-leases.ts";
+import { recordDispatchClaim, markFailed, markCanceled } from "../db/unit-dispatches.ts";
+import {
+  buildDispatchKey,
+  createDispatchHistory,
+  normalizeDispatchKey,
+  parseDispatchKey,
+  STUCK_WINDOW_SIZE,
+} from "../auto/dispatch-history.ts";
+
+function makeBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-dispatch-history-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+}
+
+interface LedgerFixture {
+  base: string;
+  worker: string;
+  token: number;
+  claim(unitType: string, unitId: string): number;
+}
+
+function makeLedgerFixture(t: { after(fn: () => void): void }): LedgerFixture {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "T", status: "active" });
+  const worker = registerAutoWorker({ projectRootRealpath: base });
+  const lease = claimMilestoneLease(worker, "M001");
+  assert.equal(lease.ok, true);
+  if (!lease.ok) throw new Error("lease claim failed");
+  return {
+    base,
+    worker,
+    token: lease.token,
+    claim(unitType: string, unitId: string): number {
+      const claim = recordDispatchClaim({
+        traceId: `${unitType}-${unitId}-${Math.random()}`,
+        workerId: worker,
+        milestoneLeaseToken: lease.token,
+        milestoneId: "M001",
+        unitType,
+        unitId,
+      });
+      assert.equal(claim.ok, true);
+      if (!claim.ok) throw new Error("claim failed");
+      return claim.dispatchId;
+    },
+  };
+}
+
+function historyFor(scopeId: string | null) {
+  return createDispatchHistory({ resolveScopeId: () => scopeId });
+}
+
+// ─── Key format ──────────────────────────────────────────────────────────────
+
+test("buildDispatchKey produces the canonical unitType:unitId format", () => {
+  assert.equal(buildDispatchKey("execute-task", "M001/S01/T01"), "execute-task:M001/S01/T01");
+});
+
+test("normalizeDispatchKey converts legacy slash keys and keeps canonical keys", () => {
+  assert.equal(normalizeDispatchKey("execute-task/M001/S01/T01"), "execute-task:M001/S01/T01");
+  assert.equal(normalizeDispatchKey("execute-task:M001/S01/T01"), "execute-task:M001/S01/T01");
+  assert.equal(normalizeDispatchKey("opaque"), "opaque");
+});
+
+test("parseDispatchKey splits canonical and legacy keys at the unit type", () => {
+  assert.deepEqual(parseDispatchKey("complete-slice:M001/S01"), {
+    unitType: "complete-slice",
+    unitId: "M001/S01",
+  });
+  assert.deepEqual(parseDispatchKey("complete-slice/M001/S01"), {
+    unitType: "complete-slice",
+    unitId: "M001/S01",
+  });
+  assert.equal(parseDispatchKey("opaque"), null);
+});
+
+// ─── Window record/evict ─────────────────────────────────────────────────────
+
+test("recordDispatch caps the window at the window size, evicting oldest-first", () => {
+  const history = historyFor(null);
+  for (let i = 0; i < STUCK_WINDOW_SIZE + 2; i++) {
+    history.recordDispatch("execute-task", `M001/S01/T${i}`);
+  }
+  const window = history.getRecentWindow();
+  assert.equal(window.length, STUCK_WINDOW_SIZE);
+  assert.equal(window[0].key, "execute-task:M001/S01/T2");
+  assert.equal(window[window.length - 1].key, `execute-task:M001/S01/T${STUCK_WINDOW_SIZE + 1}`);
+});
+
+test("countMatching counts entries for the canonical key", () => {
+  const history = historyFor(null);
+  history.recordDispatch("execute-task", "M001/S01/T01");
+  history.recordDispatch("complete-slice", "M001/S01");
+  history.recordDispatch("execute-task", "M001/S01/T01");
+  assert.equal(history.countMatching("execute-task:M001/S01/T01"), 2);
+  assert.equal(history.countMatching("complete-slice:M001/S01"), 1);
+});
+
+test("clearOnRecovery empties the window", () => {
+  const history = historyFor(null);
+  history.recordDispatch("execute-task", "M001/S01/T01");
+  history.recordDispatch("execute-task", "M001/S01/T01");
+  history.clearOnRecovery();
+  assert.equal(history.getRecentWindow().length, 0);
+  assert.equal(history.detectStuck(), null);
+});
+
+// ─── Ledger error attachment + detect-stuck delegation ──────────────────────
+
+test("recordDispatch attaches the latest ledger error on repeats so repeat-error detection fires", (t) => {
+  const f = makeLedgerFixture(t);
+  const dispatchId = f.claim("execute-task", "M001/S01/T01");
+  markFailed(dispatchId, { errorSummary: "boom: deterministic failure" });
+
+  const history = historyFor(f.base);
+  history.recordDispatch("execute-task", "M001/S01/T01");
+  history.recordDispatch("execute-task", "M001/S01/T01");
+  history.recordDispatch("execute-task", "M001/S01/T01");
+
+  const window = history.getRecentWindow();
+  // First dispatch of a unit skips the ledger lookup (zero DB cost on the
+  // common path); repeats attach the latest error.
+  assert.equal(window[0].error, undefined);
+  assert.equal(window[1].error, "boom: deterministic failure");
+  assert.equal(window[2].error, "boom: deterministic failure");
+  const verdict = history.detectStuck();
+  assert.equal(verdict?.stuck, true);
+  assert.match(verdict?.reason ?? "", /Same error repeated/);
+});
+
+test("recordDispatch never attaches another unit type's ledger error for the same unit id", (t) => {
+  const f = makeLedgerFixture(t);
+  const dispatchId = f.claim("plan-slice", "M001/S01");
+  markFailed(dispatchId, { errorSummary: "boom: plan failure" });
+
+  const history = historyFor(f.base);
+  history.recordDispatch("execute-task", "M001/S01");
+  history.recordDispatch("execute-task", "M001/S01");
+
+  assert.ok(history.getRecentWindow().every((entry) => entry.error === undefined));
+  assert.equal(history.detectStuck(), null);
+});
+
+test("detectStuck fires on three consecutive same-key dispatches without errors", () => {
+  const history = historyFor(null);
+  for (let i = 0; i < 3; i++) history.recordDispatch("plan-slice", "M001/S01");
+  const verdict = history.detectStuck();
+  assert.equal(verdict?.stuck, true);
+  assert.match(verdict?.reason ?? "", /plan-slice:M001\/S01 derived 3 consecutive times/);
+});
+
+// ─── Retry-budget suppression ────────────────────────────────────────────────
+
+test("a bare-id ledger row for a different unit type does not suppress the stuck verdict", (t) => {
+  const f = makeLedgerFixture(t);
+  // Retry backoff is open for plan-slice:M001/S01 only (bare-id ledger row).
+  const dispatchId = f.claim("plan-slice", "M001/S01");
+  markFailed(dispatchId, { errorSummary: "", retryAfterMs: 60_000 });
+
+  const history = historyFor(f.base);
+  for (let i = 0; i < 3; i++) history.recordDispatch("execute-task", "M001/S01");
+  const verdict = history.detectStuck();
+  assert.equal(verdict?.stuck, true, "another unit type's backoff must not suppress this unit");
+});
+
+test("consecutive-repeat verdict is suppressed while the retry budget drains", (t) => {
+  const f = makeLedgerFixture(t);
+  // markCanceled leaves error_summary null so the repeat-error rule (which is
+  // never suppressed) cannot fire; the suppression target is rule 2/2b.
+  const first = f.claim("plan-slice", "M001/S01");
+  markCanceled(first, "retry");
+  const second = f.claim("plan-slice", "M001/S01");
+  markFailed(second, { errorSummary: "", retryAfterMs: 60_000 });
+
+  const history = historyFor(f.base);
+  for (let i = 0; i < 3; i++) history.recordDispatch("plan-slice", "M001/S01");
+  assert.equal(history.detectStuck(), null, "stuck verdict must be suppressed inside the retry backoff window");
+});
+
+test("exhausted retry budget does not suppress the stuck verdict", (t) => {
+  const f = makeLedgerFixture(t);
+  const ids: number[] = [];
+  for (let i = 0; i < 3; i++) {
+    const id = f.claim("plan-slice", "M001/S01");
+    markCanceled(id, "retry");
+    ids.push(id);
+  }
+  const last = f.claim("plan-slice", "M001/S01");
+  // attempt_n defaults to 1 here; bump via a fresh claim is unnecessary —
+  // exhaust by omitting next_run_at instead (no scheduled retry → no backoff).
+  markFailed(last, { errorSummary: "" });
+
+  const history = historyFor(f.base);
+  for (let i = 0; i < 3; i++) history.recordDispatch("plan-slice", "M001/S01");
+  const verdict = history.detectStuck();
+  assert.equal(verdict?.stuck, true);
+});
+
+// ─── Rehydration (#482 regression) ───────────────────────────────────────────
+
+test("rehydrate seeds the window from the ledger with normalized canonical keys", (t) => {
+  const f = makeLedgerFixture(t);
+  for (let i = 0; i < 2; i++) {
+    const id = f.claim("execute-task", "M001/S01/T01");
+    markFailed(id, { errorSummary: "" });
+  }
+
+  const history = historyFor(f.base);
+  const count = history.rehydrate();
+  assert.equal(count, 2);
+  assert.deepEqual(
+    history.getRecentWindow().map((e) => e.key),
+    ["execute-task:M001/S01/T01", "execute-task:M001/S01/T01"],
+  );
+});
+
+test("#482 regression: a re-dispatch loop spanning a session restart is detected as stuck", (t) => {
+  const f = makeLedgerFixture(t);
+  // Session 1: the same unit was dispatched twice and never made progress.
+  for (let i = 0; i < 2; i++) {
+    const id = f.claim("execute-task", "M001/S01/T01");
+    markFailed(id, { errorSummary: "" });
+  }
+
+  // Session 2: a brand-new history (fresh orchestrator) rehydrates from the
+  // ledger; the very next decision for the same unit trips the stuck verdict
+  // instead of silently re-dispatching forever.
+  const restarted = historyFor(f.base);
+  restarted.rehydrate();
+  restarted.recordDispatch("execute-task", "M001/S01/T01");
+  const verdict = restarted.detectStuck();
+  assert.equal(verdict?.stuck, true);
+  assert.match(verdict?.reason ?? "", /execute-task:M001\/S01\/T01 derived 3 consecutive times/);
+});
+
+test("rehydrate degrades to an empty window without a scope or ledger", () => {
+  const noScope = historyFor(null);
+  assert.equal(noScope.rehydrate(), 0);
+  assert.equal(noScope.getRecentWindow().length, 0);
+
+  const noDb = historyFor("/nonexistent/scope");
+  assert.equal(noDb.rehydrate(), 0);
+  assert.equal(noDb.getRecentWindow().length, 0);
+});

package/src/resources/extensions/gsd/tests/dispatch-run-uat-browser-tools.test.ts

@@ -0,0 +1,89 @@
+// Project/App: gsd-pi
+// File Purpose: Regression coverage for run-uat browser tool availability checks.
+
+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 { DISPATCH_RULES, type DispatchContext } from "../auto-dispatch.ts";
+import type { GSDState } from "../types.ts";
+import { BROWSER_AUTOMATION_CONTRACT_TOOLS } from "./browser-automation-contract-fixture.ts";
+
+type DispatchRuleEntry = (typeof DISPATCH_RULES)[number];
+
+function runUatRule(): DispatchRuleEntry {
+  const rule = DISPATCH_RULES.find((entry) => entry.name === "run-uat (post-completion)");
+  assert.ok(rule, "run-uat dispatch rule must exist");
+  return rule;
+}
+
+function makeState(): GSDState {
+  return {
+    activeMilestone: { id: "M001", title: "Browser UAT" },
+    activeSlice: { id: "S02", title: "Next Slice" },
+    activeTask: null,
+    phase: "verifying",
+    recentDecisions: [],
+    blockers: [],
+    nextAction: "",
+    registry: [],
+  };
+}
+
+function scaffoldRunUatProject(basePath: string): void {
+  const milestoneDir = join(basePath, ".gsd", "milestones", "M001");
+  const sliceDir = join(milestoneDir, "slices", "S01");
+  mkdirSync(sliceDir, { recursive: true });
+
+  writeFileSync(join(milestoneDir, "M001-ROADMAP.md"), [
+    "# M001: Browser UAT",
+    "",
+    "## Slices",
+    "",
+    "- [x] **S01: Completed browser slice** `risk:low` `depends:[]`",
+    "- [ ] **S02: Next slice** `risk:low` `depends:[S01]`",
+    "",
+  ].join("\n"), "utf-8");
+
+  writeFileSync(join(sliceDir, "S01-SUMMARY.md"), "# S01 Summary\n\nDone.\n", "utf-8");
+  writeFileSync(join(sliceDir, "S01-UAT.md"), [
+    "# S01 UAT",
+    "",
+    "## UAT Type",
+    "- UAT mode: human-experience",
+    "",
+    "Open the app in a browser and verify the completed user flow.",
+    "",
+  ].join("\n"), "utf-8");
+}
+
+function makeContext(basePath: string, overrides: Partial<DispatchContext> = {}): DispatchContext {
+  return {
+    basePath,
+    mid: "M001",
+    midTitle: "Browser UAT",
+    state: makeState(),
+    prefs: undefined,
+    activeTools: ["read", "gsd_uat_exec", "gsd_uat_result_save"],
+    ...overrides,
+  };
+}
+
+test("run-uat browser preflight uses registered tools when the active surface is scoped", async (t) => {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-run-uat-browser-tools-"));
+  t.after(() => rmSync(basePath, { recursive: true, force: true }));
+  scaffoldRunUatProject(basePath);
+
+  const blocked = await runUatRule().match(makeContext(basePath));
+  assert.equal(blocked?.action, "stop");
+  assert.match(blocked?.action === "stop" ? blocked.reason : "", /run-uat tool surface has none/);
+
+  const dispatched = await runUatRule().match(makeContext(basePath, {
+    registeredTools: [...BROWSER_AUTOMATION_CONTRACT_TOOLS.piProvider],
+  }));
+  assert.equal(dispatched?.action, "dispatch");
+  assert.equal(dispatched?.action === "dispatch" ? dispatched.unitType : undefined, "run-uat");
+  assert.equal(dispatched?.action === "dispatch" ? dispatched.unitId : undefined, "M001/S01");
+});

package/src/resources/extensions/gsd/tests/doctor-git-checks-terminal.test.ts

@@ -0,0 +1,73 @@
+// Project/App: gsd-pi
+// File Purpose: Doctor git checks treat validation-pass closeout as terminal without SUMMARY.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runGSDDoctor } from "../doctor.ts";
+import { openDatabase, insertMilestone, insertSlice, insertAssessment, closeDatabase } from "../gsd-db.js";
+import { createWorktree, worktreePath } from "../worktree-manager.ts";
+
+function runGit(args: string[], cwd: string): string {
+  return execFileSync("git", args, {
+    cwd,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  }).trim();
+}
+
+function makeRepo(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-terminal-"));
+  runGit(["init", "-b", "main"], base);
+  runGit(["config", "user.name", "Test User"], base);
+  runGit(["config", "user.email", "test@example.com"], base);
+  writeFileSync(join(base, "package.json"), "{\"scripts\":{}}\n", "utf-8");
+  runGit(["add", "."], base);
+  runGit(["commit", "-m", "chore: init"], base);
+  return base;
+}
+
+test.after(() => {
+  closeDatabase();
+});
+
+test("doctor flags orphaned worktree for DB-complete milestone without SUMMARY", async (t) => {
+  const base = makeRepo();
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M008", title: "Done", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M008", title: "Slice", status: "complete" });
+  insertAssessment({
+    path: "milestones/M008/M008-VALIDATION.md",
+    milestoneId: "M008",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
+  writeFileSync(
+    join(base, ".gsd", "PREFERENCES.md"),
+    "---\ngit:\n  isolation: worktree\n---\n",
+  );
+  mkdirSync(join(base, ".gsd", "milestones", "M008"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M008", "M008-ROADMAP.md"),
+    "# M008 Roadmap\n\n- [x] **S01: Slice** `risk:low` `depends:[]`\n",
+  );
+
+  createWorktree(base, "M008", { branch: "milestone/M008" });
+  const wtPath = worktreePath(base, "M008");
+  assert.ok(existsSync(wtPath), "worktree should exist for the test");
+
+  const report = await runGSDDoctor(base, { isolationMode: "worktree" });
+
+  assert.ok(
+    report.issues.some((issue) => issue.code === "orphaned_auto_worktree" && issue.unitId === "M008"),
+    "doctor should treat DB-complete milestone without SUMMARY as terminal for cleanup",
+  );
+});

package/src/resources/extensions/gsd/tests/doctor-scope-db-unavailable.test.ts

@@ -26,6 +26,24 @@ test("filterDoctorIssues keeps project and environment issues in scoped reports"
   );
 });
 
+test("filterDoctorIssues keeps invalid_preferences issues regardless of preferences file scope", () => {
+  // Both global and project preference diagnostics should survive scope filtering.
+  // doctor.ts uses unitId: "project" for all invalid_preferences issues so they
+  // pass through the scope filter the same way other project-level issues do.
+  const issues = [
+    { severity: "error", code: "invalid_preferences", scope: "project", unitId: "project", message: "global PREFERENCES.md parse error", fixable: false },
+    { severity: "error", code: "invalid_preferences", scope: "project", unitId: "project", message: "project PREFERENCES.md parse error", fixable: false },
+    { severity: "error", code: "invalid_preferences", scope: "project", unitId: "global", message: "stale unitId — should be filtered out", fixable: false },
+  ] as const;
+
+  const filtered = filterDoctorIssues([...issues], { scope: "M016", includeWarnings: true });
+  assert.deepEqual(
+    filtered.map((issue) => issue.message),
+    ["global PREFERENCES.md parse error", "project PREFERENCES.md parse error"],
+    "invalid_preferences issues with unitId: project survive scope filtering; unitId: global is dropped",
+  );
+});
+
 test("checkEngineHealth reports db_unavailable when gsd.db exists but the DB is closed", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-doctor-db-unavailable-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));

package/src/resources/extensions/gsd/tests/dynamic-bash-no-cap.test.ts

@@ -0,0 +1,132 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { createBashTool } from "@gsd/pi-coding-agent";
+
+import { registerDynamicTools } from "../bootstrap/dynamic-tools.ts";
+import { createAsyncBashTool } from "../../async-jobs/async-bash-tool.ts";
+
+// These tests assert on the runtime tool objects the agent actually receives —
+// the registered GSD bash tool, the core bash tool, and the async_bash tool —
+// not on source text. The behavioral guarantee (an explicit timeout still
+// fires after the silent 120s cap was removed) is exercised by spawning a real
+// process at the bottom of the file.
+
+/** Capture the GSD-registered `bash` tool object from registerDynamicTools. */
+function registerAndCaptureBash(): any {
+  let captured: any = undefined;
+  const pi = {
+    registerTool: (tool: any) => {
+      if (!captured && tool && tool.name === "bash") captured = tool;
+    },
+  };
+  registerDynamicTools(pi as any);
+  assert.ok(captured, "registerDynamicTools must register a tool named 'bash'");
+  return captured;
+}
+
+// 1. Cap removal: the GSD bash tool no longer injects a default timeout. The
+//    schema's timeout stays optional (no `default`), so an omitted timeout
+//    means "no timeout" rather than a silent 120s cap.
+test("GSD bash tool exposes an optional timeout with no injected default", () => {
+  const bash = registerAndCaptureBash();
+  const timeout = bash.parameters?.properties?.timeout;
+  assert.ok(timeout, "bash tool must expose a `timeout` parameter");
+  assert.equal(
+    "default" in timeout,
+    false,
+    "the timeout schema must not carry a default — an omitted timeout means uncapped",
+  );
+  assert.equal(
+    bash.parameters?.required?.includes?.("timeout") ?? false,
+    false,
+    "timeout must remain optional",
+  );
+});
+
+// 2. Watchdog verbiage is GSD-scoped: the core bash tool (reused by non-GSD
+//    embeddings with no watchdog) must NOT claim a watchdog, while the
+//    GSD-registered tool injects it into both description and timeout schema.
+test("core bash tool does not advertise the auto-mode watchdog", () => {
+  const core = createBashTool(process.cwd(), { spawnHook: (c: any) => c });
+  assert.equal(
+    /stalled-tool watchdog/.test(core.description ?? ""),
+    false,
+    "core bash must not advertise a watchdog — non-GSD embeddings have none",
+  );
+  assert.equal(
+    /stalled-tool watchdog/.test(
+      (core.parameters as any)?.properties?.timeout?.description ?? "",
+    ),
+    false,
+    "core bash timeout schema must not advertise a watchdog",
+  );
+});
+
+test("GSD-registered bash tool advertises the stalled-tool watchdog", () => {
+  const bash = registerAndCaptureBash();
+  assert.equal(
+    /stalled-tool watchdog/.test(bash.description ?? ""),
+    true,
+    "the GSD bash description must name the stalled-tool watchdog",
+  );
+  assert.equal(
+    /stalled-tool watchdog/.test(
+      bash.parameters?.properties?.timeout?.description ?? "",
+    ),
+    true,
+    "the GSD bash timeout schema must name the stalled-tool watchdog",
+  );
+});
+
+// 3. async_bash guidance frames itself as a non-blocking/background choice and
+//    no longer implies sync bash is time-capped.
+test("async_bash guidance is non-blocking and drops the sync-cap implication", () => {
+  const asyncTool: any = createAsyncBashTool(
+    () => ({ register: () => "job-0" }) as any,
+    () => process.cwd(),
+  );
+  const guidance = (asyncTool.promptGuidelines ?? []).join("\n");
+  assert.equal(
+    /more than a few seconds/.test(guidance),
+    false,
+    "async_bash guidance must not imply sync bash is time-capped",
+  );
+  assert.equal(
+    /non-blocking/.test(guidance),
+    true,
+    "async_bash guidance must describe itself as non-blocking",
+  );
+});
+
+// 4. Behavioral passthrough: an explicitly-set timeout is still honored after
+//    the cap removal. A 1s timeout on a 5s sleep must fire well under 5s.
+test("GSD bash still forwards an explicit timeout (cap removal did not break passthrough)", async () => {
+  const bash = registerAndCaptureBash();
+
+  const start = Date.now();
+  let resultText = "";
+  try {
+    const result: any = await bash.execute(
+      "t1",
+      { command: "sleep 5", timeout: 1 },
+      undefined,
+      undefined,
+      { cwd: process.cwd() },
+    );
+    resultText = JSON.stringify(result ?? "");
+  } catch (err) {
+    resultText = String(err instanceof Error ? err.message : err);
+  }
+  const elapsed = Date.now() - start;
+
+  assert.equal(
+    /timed out|timeout|exited with code|force-killed/i.test(resultText),
+    true,
+    `explicit 1s timeout should fire before the 5s sleep completes; got: ${resultText}`,
+  );
+  assert.ok(
+    elapsed < 4500,
+    `explicit timeout should fire quickly, not run to completion (elapsed ${elapsed}ms)`,
+  );
+});