@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.65546769

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

@@ -11,7 +11,10 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import * as fs from 'node:fs';
 import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { closeDatabase, isDbAvailable, getDecisionById, SCHEMA_VERSION, _getAdapter } from '../gsd-db.ts';
+import { formatWorkflowDatabaseOpenFailure } from '../bootstrap/dynamic-tools.ts';
 
 const _require = createRequire(import.meta.url);
 
@@ -288,6 +291,116 @@ function createLegacyV15Db(dbPath: string): void {
 // ═══════════════════════════════════════════════════════════════════════════
 
 describe('ensure-db-open', () => {
+  test('formatWorkflowDatabaseOpenFailure: open failure without provider gives actionable SQLite guidance', () => {
+    const message = formatWorkflowDatabaseOpenFailure(
+      {
+        ok: false,
+        reason: 'open-failed',
+        location: {
+          projectRoot: '/tmp/example',
+          projectGsd: '/tmp/example/.gsd',
+          projectDb: '/tmp/example/.gsd/gsd.db',
+        },
+      },
+      {
+        available: false,
+        provider: null,
+        attempted: true,
+        lastError: null,
+        lastPhase: null,
+      },
+      '22.15.0',
+    );
+
+    assert.match(message, /\/tmp\/example\/\.gsd\/gsd\.db/);
+    assert.match(message, /No SQLite provider available/);
+    assert.match(message, /node:sqlite/);
+    assert.match(message, /better-sqlite3/);
+  });
+
+  test('formatWorkflowDatabaseOpenFailure: old Node includes upgrade guidance', () => {
+    const message = formatWorkflowDatabaseOpenFailure(
+      {
+        ok: false,
+        reason: 'open-failed',
+        location: {
+          projectRoot: '/tmp/example',
+          projectGsd: '/tmp/example/.gsd',
+          projectDb: '/tmp/example/.gsd/gsd.db',
+        },
+      },
+      {
+        available: false,
+        provider: null,
+        attempted: true,
+        lastError: null,
+        lastPhase: null,
+      },
+      '20.11.1',
+    );
+
+    assert.match(message, />= 22\.0\.0/);
+    assert.match(message, /current: v20\.11\.1/);
+  });
+
+  test('ensureDbOpen: source-mode runtime without node:sqlite records actionable guidance', () => {
+    const loaderPath = fileURLToPath(new URL('./resolve-ts.mjs', import.meta.url));
+    const runningFromDistTest = fileURLToPath(import.meta.url).includes(`${path.sep}dist-test${path.sep}`);
+    const dynamicToolsImportUrl = pathToFileURL(
+      path.resolve(
+        runningFromDistTest
+          ? 'dist-test/src/resources/extensions/gsd/bootstrap/dynamic-tools.js'
+          : 'src/resources/extensions/gsd/bootstrap/dynamic-tools.ts',
+      ),
+    ).href;
+    const loggerImportUrl = pathToFileURL(
+      path.resolve(
+        runningFromDistTest
+          ? 'dist-test/src/resources/extensions/gsd/workflow-logger.ts'
+          : 'src/resources/extensions/gsd/workflow-logger.ts',
+      ),
+    ).href;
+    const script = `
+      const fs = require('node:fs');
+      const os = require('node:os');
+      const path = require('node:path');
+      (async () => {
+        const base = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-missing-sqlite-'));
+        try {
+          fs.mkdirSync(path.join(base, '.gsd'), { recursive: true });
+          const dynamicTools = await import(${JSON.stringify(dynamicToolsImportUrl)});
+          const logger = await import(${JSON.stringify(loggerImportUrl)});
+          await dynamicTools.ensureDbOpen(base);
+          const messages = logger.peekLogs().map((entry) => entry.message);
+          console.log(JSON.stringify(messages));
+        } finally {
+          fs.rmSync(base, { recursive: true, force: true });
+        }
+      })().catch((error) => {
+        console.error(error.stack || error.message || String(error));
+        process.exit(1);
+      });
+    `;
+    const result = spawnSync(
+      process.execPath,
+      [
+        '--no-experimental-sqlite',
+        '--import',
+        loaderPath,
+        '--experimental-strip-types',
+        '-e',
+        script,
+      ],
+      { cwd: process.cwd(), encoding: 'utf-8' },
+    );
+
+    assert.equal(result.status, 0, result.stderr);
+    const messages = JSON.parse(result.stdout.trim()) as string[];
+    assert.ok(messages.some((message) => /No SQLite provider available/.test(message)), result.stdout);
+    assert.ok(messages.some((message) => /node:sqlite/.test(message)), result.stdout);
+    assert.ok(messages.some((message) => /better-sqlite3/.test(message)), result.stdout);
+  });
+
   test('ensureDbOpen: creates empty DB without importing Markdown', async () => {
     const tmpDir = makeTmpDir();
     const gsdDir = path.join(tmpDir, '.gsd');

package/src/resources/extensions/gsd/tests/ensure-preconditions-guard-4996.test.ts

@@ -14,12 +14,13 @@ import {
   closeDatabase,
   insertMilestone,
 } from "../gsd-db.ts";
+import { canonicalPhaseDirName } from "../paths.ts";
 
 import type { GSDState } from "../types.ts";
 
 function makeBase(prefix = "gsd-precond-"): string {
   const base = mkdtempSync(join(tmpdir(), prefix));
-  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  mkdirSync(join(base, ".gsd", "phases"), { recursive: true });
   return base;
 }
 
@@ -50,7 +51,8 @@ describe("ensurePreconditions phantom-dir guard (#4996)", () => {
 
     ensurePreconditions("execute-task", "M003/S01", base, state);
 
-    const milestoneDir = join(base, ".gsd", "milestones", "M003");
+    // Flat-phase: phantom guard must not create any phase dir for an unrecognised milestone.
+    const milestoneDir = join(base, ".gsd", "phases", canonicalPhaseDirName("M003"));
     assert.ok(!existsSync(milestoneDir), "M003 dir must not be created for phantom slice dispatch");
   });
 
@@ -63,22 +65,26 @@ describe("ensurePreconditions phantom-dir guard (#4996)", () => {
 
     ensurePreconditions("execute-task", "M003/S01", base, state);
 
-    const milestoneDir = join(base, ".gsd", "milestones", "M003");
-    assert.ok(existsSync(milestoneDir), "M003 dir must be created when DB row exists");
+    // Flat-phase: dir is created under phases/ using the canonical phase dir name.
+    const milestoneDir = join(base, ".gsd", "phases", canonicalPhaseDirName("M003"));
+    assert.ok(existsSync(milestoneDir), "M003 phase dir must be created when DB row exists");
   });
 
-  it("(c) slice unit ID for existing milestone dir with CONTEXT.md content file uses normal scaffolding", () => {
+  it("(c) slice unit ID for existing milestone dir with CONTEXT.md content file does not clobber it", () => {
     base = makeBase();
     const mid = "M003";
-    const milestoneDir = join(base, ".gsd", "milestones", mid);
+    // Use canonicalPhaseDirName so the dir is found by resolveMilestonePath.
+    const milestoneDir = join(base, ".gsd", "phases", canonicalPhaseDirName(mid));
     mkdirSync(milestoneDir, { recursive: true });
     writeFileSync(join(milestoneDir, `${mid}-CONTEXT.md`), "# Context\n");
     const state = makeMinimalState();
 
     ensurePreconditions("execute-task", "M003/S01", base, state);
 
-    const slicesDir = join(milestoneDir, "slices");
-    assert.ok(existsSync(slicesDir), "existing milestone dir should allow slice scaffolding");
+    // Flat-phase: ensurePreconditions returns early when the phase dir already exists.
+    // Tasks are checkboxes in plan files — no slices/ subdir is created.
+    assert.ok(existsSync(milestoneDir), "existing milestone dir must survive ensurePreconditions");
+    assert.ok(!existsSync(join(milestoneDir, "slices")), "flat-phase must not scaffold slices/ subdir");
   });
 
   it("(d) milestone-only unit ID (no slice) still creates dir even with no DB row", () => {
@@ -87,7 +93,8 @@ describe("ensurePreconditions phantom-dir guard (#4996)", () => {
 
     ensurePreconditions("discuss-milestone", "M003", base, state);
 
-    const milestoneDir = join(base, ".gsd", "milestones", "M003");
-    assert.ok(existsSync(milestoneDir), "M003 dir must be created for milestone-only dispatch");
+    // Flat-phase: dir is created under phases/ using the canonical phase dir name.
+    const milestoneDir = join(base, ".gsd", "phases", canonicalPhaseDirName("M003"));
+    assert.ok(existsSync(milestoneDir), "M003 phase dir must be created for milestone-only dispatch");
   });
 });

package/src/resources/extensions/gsd/tests/evidence-cross-ref.test.ts

@@ -86,6 +86,101 @@ test("stale verification evidence batches are ignored when a newer completion ba
   assert.deepEqual(mismatches, []);
 });
 
+test("WSL bash-spawn failure is not flagged as a falsified passing verification", () => {
+  // Issue #814: on Windows, `gsd_exec runtime=bash` resolves to a WSL with no
+  // /bin/bash. The bash-runtime verification call exits 1 with a spawn-failure
+  // banner (the command never ran); the LLM re-ran via a node runtime (exit 0)
+  // that findMatches does not capture. The infra failure must not block.
+  const command = "npx playwright test e2e/m039-s05-comparison-legibility.spec.ts";
+  const mismatches = crossReferenceEvidence(
+    [{ command, exitCode: 0, verdict: "passed" }],
+    [
+      {
+        kind: "bash",
+        toolCallId: "call-1",
+        command: `${command} --reporter=line 2>&1 | tail -40`,
+        exitCode: 1,
+        outputSnippet:
+          "<3>WSL (12 - Relay) ERROR: CreateProcessCommon:800: execvpe(/bin/bash) failed: No such file or directory",
+        timestamp: 1,
+      },
+    ] as EvidenceEntry[],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "warning");
+  assert.match(mismatches[0].reason, /inconclusive/);
+});
+
+test("missing tool failure (command not found: eslint) is a real error, not an infra spawn failure", () => {
+  // Regression for overly-broad spawn signature: `command not found: eslint`
+  // is a genuine verification failure (eslint not installed), not a missing
+  // shell interpreter. It must produce a blocking error, not a warning.
+  const command = "eslint src/";
+  const mismatches = crossReferenceEvidence(
+    [{ command, exitCode: 0, verdict: "passed" }],
+    [
+      {
+        kind: "bash",
+        toolCallId: "call-1",
+        command,
+        exitCode: 1,
+        outputSnippet: "zsh: command not found: eslint",
+        timestamp: Date.now(),
+      },
+    ] as EvidenceEntry[],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "error");
+  assert.match(mismatches[0].reason, /Claimed exitCode=0/);
+});
+
+test("missing tool failure (command not found: node) is a real error, not an infra spawn failure", () => {
+  // node is not a shell interpreter; its absence is a genuine env problem,
+  // not a shell-spawn infra failure.
+  const command = "node --test tests/verify.test.js";
+  const mismatches = crossReferenceEvidence(
+    [{ command, exitCode: 0, verdict: "passed" }],
+    [
+      {
+        kind: "bash",
+        toolCallId: "call-1",
+        command,
+        exitCode: 127,
+        outputSnippet: "bash: command not found: node",
+        timestamp: Date.now(),
+      },
+    ] as EvidenceEntry[],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "error");
+  assert.match(mismatches[0].reason, /Claimed exitCode=0/);
+});
+
+test("missing shell interpreter (command not found: bash) is treated as an infra spawn failure", () => {
+  // bash itself missing is the shell-spawn infra case; must remain a warning.
+  const command = "npm test";
+  const mismatches = crossReferenceEvidence(
+    [{ command, exitCode: 0, verdict: "passed" }],
+    [
+      {
+        kind: "bash",
+        toolCallId: "call-1",
+        command,
+        exitCode: 1,
+        outputSnippet: "command not found: bash",
+        timestamp: Date.now(),
+      },
+    ] as EvidenceEntry[],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "warning");
+  assert.match(mismatches[0].reason, /inconclusive/);
+});
+
 test("missing recorded bash evidence remains a warning", () => {
   const mismatches = crossReferenceEvidence(
     [{ command: "npm test", exitCode: 0, verdict: "passed" }],

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

@@ -0,0 +1,157 @@
+// Project/App: gsd-pi
+// File Purpose: Regression tests for evidence cross-referencing of gsd_exec /
+// gsd_uat_exec tool calls. Mirrors the live false-positive where an
+// execute-task agent ran its verification commands through gsd_exec (script
+// body in the `script` argument) and the cross-referencer reported
+// "No bash tool call found" despite successful execution.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  resetEvidence,
+  getEvidence,
+  recordToolCall,
+  recordToolResult,
+  isExecutionToolName,
+  type BashEvidence,
+} from "../safety/evidence-collector.ts";
+import { crossReferenceEvidence } from "../safety/evidence-cross-ref.ts";
+
+function gsdExecResult(exitCode: number, id = "4858202d-2ed7-4a0a-9ef7-4e159e65da83"): unknown {
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        operation: "gsd_exec",
+        id,
+        runtime: "bash",
+        exit_code: exitCode,
+        signal: null,
+        timed_out: false,
+        duration_ms: 272,
+        stdout_bytes: 592,
+        stderr_bytes: 0,
+        meta_path: `/tmp/does-not-exist/.gsd/exec/${id}.meta.json`,
+      }),
+    }],
+  };
+}
+
+test("evidence-xref: verification run through gsd_exec script matches the claimed command", () => {
+  resetEvidence();
+
+  // The live false positive: agent runs `node --test tests/verify-s01.test.js`
+  // inside a gsd_exec script with a cd prefix and exit-code echo suffix.
+  recordToolCall("tc-exec-1", "gsd_exec", {
+    script: 'cd /work/.gsd/worktrees/M001 && node --test tests/verify-s01.test.js; echo "EXIT=$?"',
+    purpose: "T02: run node --test contract checks against T01 index.html",
+  });
+  recordToolResult("tc-exec-1", "gsd_exec", gsdExecResult(0), false);
+
+  const mismatches = crossReferenceEvidence(
+    [{ command: "node --test tests/verify-s01.test.js", exitCode: 0, verdict: "passed" }],
+    getEvidence(),
+  );
+
+  assert.deepEqual(mismatches, [], "gsd_exec-executed verification must not be flagged as missing");
+});
+
+test("evidence-xref: multi-line gsd_exec script matches claims for each embedded command", () => {
+  resetEvidence();
+
+  recordToolCall("tc-exec-2", "gsd_exec", {
+    script: [
+      "cd /work/.gsd/worktrees/M001",
+      "sed -i '' \"s/'todos'/'tasks-v1'/\" index.html",
+      "node --test tests/verify-s01.test.js > /dev/null 2>&1",
+      'echo "BROKEN_EXIT=$?"',
+    ].join("\n"),
+    purpose: "T02: deliberate contract break must fail, then restore",
+  });
+  recordToolResult("tc-exec-2", "gsd_exec", gsdExecResult(0), false);
+
+  const mismatches = crossReferenceEvidence(
+    [{ command: "node --test tests/verify-s01.test.js > /dev/null 2>&1", exitCode: 0, verdict: "passed" }],
+    getEvidence(),
+  );
+
+  assert.deepEqual(mismatches, [], "command embedded in a multi-line script must match");
+});
+
+test("evidence-xref: claimed pass with failing gsd_exec exit_code is still an error", () => {
+  resetEvidence();
+
+  recordToolCall("tc-exec-3", "gsd_exec", {
+    script: "node --test tests/verify-s01.test.js",
+    purpose: "verification",
+  });
+  // gsd_exec reports failures via the JSON envelope's exit_code (and isError).
+  recordToolResult("tc-exec-3", "gsd_exec", gsdExecResult(1), true);
+
+  const mismatches = crossReferenceEvidence(
+    [{ command: "node --test tests/verify-s01.test.js", exitCode: 0, verdict: "passed" }],
+    getEvidence(),
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "error");
+  assert.match(mismatches[0].reason, /Claimed exitCode=0 but actual exitCode=1/);
+});
+
+test("evidence-collector: gsd_uat_exec and MCP-namespaced variants are execution tools", () => {
+  assert.equal(isExecutionToolName("gsd_uat_exec"), true);
+  assert.equal(isExecutionToolName("mcp__gsd-workflow__gsd_uat_exec"), true);
+  assert.equal(isExecutionToolName("mcp__gsd-workflow__gsd_exec"), true);
+
+  resetEvidence();
+  recordToolCall("tc-uat-1", "gsd_uat_exec", { script: "curl -fsS http://localhost:3000/health" });
+  const bash = getEvidence().filter((e): e is BashEvidence => e.kind === "bash");
+  assert.equal(bash.length, 1, "gsd_uat_exec must record bash evidence");
+  assert.equal(bash[0].command, "curl -fsS http://localhost:3000/health");
+});
+
+test("evidence-xref: blank-command evidence does not satisfy arbitrary claims", () => {
+  // Before script extraction existed, gsd_exec calls were recorded with
+  // command: "" — and `"x".includes("")` made them match every claim,
+  // masking genuine fabrications. Blank entries must never match.
+  const mismatches = crossReferenceEvidence(
+    [{ command: "node --test tests/verify-s01.test.js", exitCode: 0, verdict: "passed" }],
+    [{
+      kind: "bash",
+      toolCallId: "tc-blank",
+      command: "",
+      exitCode: 0,
+      outputSnippet: "",
+      timestamp: 1,
+    }],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "warning");
+  assert.match(mismatches[0].reason, /No bash tool call found/);
+});
+
+test("evidence-collector: exit code falls back to .gsd/exec meta.json when result text omits it", (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-exec-meta-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  const metaPath = join(dir, "run-1.meta.json");
+  writeFileSync(metaPath, JSON.stringify({ id: "run-1", exit_code: 7 }));
+
+  resetEvidence();
+  recordToolCall("tc-meta-1", "gsd_exec", { script: "exit 7" });
+  // Truncated result: meta_path survives but exit_code was cut off.
+  recordToolResult(
+    "tc-meta-1",
+    "gsd_exec",
+    { content: [{ type: "text", text: `{"operation":"gsd_exec","meta_path":${JSON.stringify(metaPath)}` }] },
+    false,
+  );
+
+  const bash = getEvidence().filter((e): e is BashEvidence => e.kind === "bash");
+  assert.equal(bash[0].exitCode, 7, "exit code must be recovered from meta.json");
+});

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

@@ -0,0 +1,193 @@
+// Project/App: gsd-pi
+// File Purpose: Deterministic timing tests for the exec-sandbox graceful-kill
+// ladder + hard-deadline force-resolve (S04/T02).
+//
+// T01 extended runExecSandbox's timeout path to a graceful
+// SIGTERM -> grace -> SIGKILL ladder (via killProcessTree) plus a caller-side
+// force-resolve hard deadline so a non-closing ("D-state") child can never hang
+// the awaiting promise. A true D-state child is non-portable, so we simulate the
+// exact symptom deterministically:
+//   1. A SIGTERM-cooperative child (trap 'exit 0' TERM) closes promptly on the
+//      first SIGTERM — proving the ladder resolves via `close` well before the
+//      force-resolve deadline.
+//   2. A SIGTERM-ignoring (trap '' TERM) child combined with a LARGE
+//      kill_grace_ms (so SIGKILL never fires in-window) and a SHORT
+//      force_resolve_delay_ms — the only way the promise can settle is the
+//      hard deadline, proving the no-hang guarantee.
+//
+// Unlike the sync bash path (which throws on force-resolve), runExecSandbox
+// always RESOLVES; force-resolve calls finalize(null, "SIGKILL") and preserves
+// timed_out === true so the agent can still distinguish a graceful timeout exit
+// from a forced kill.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { EXEC_DEFAULTS, runExecSandbox, type ExecSandboxOptions } from '../exec-sandbox.ts';
+
+const isWin = process.platform === 'win32';
+
+function freshBase(): string {
+  return mkdtempSync(join(tmpdir(), 'gsd-exec-gracekill-'));
+}
+
+function cleanup(dir: string): void {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+function baseOpts(base: string, overrides: Partial<ExecSandboxOptions> = {}): ExecSandboxOptions {
+  return {
+    baseDir: base,
+    clamp_timeout_ms: EXEC_DEFAULTS.clampTimeoutMs,
+    default_timeout_ms: 10_000,
+    stdout_cap_bytes: 1_024,
+    stderr_cap_bytes: 1_024,
+    digest_chars: 120,
+    env_allowlist: EXEC_DEFAULTS.envAllowlist,
+    ...overrides,
+  };
+}
+
+// Wall-clock guard: reject if the call has not settled by `ms`. Proves no-hang
+// independently of the assertions on timing/markers.
+function wallClockGuard<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      const t = setTimeout(() => reject(new Error(`Call did not settle within ${ms}ms (hang)`)), ms);
+      if (typeof t === 'object' && 'unref' in t) t.unref();
+    }),
+  ]);
+}
+
+// Clean up a detached child (and its process group) that a large kill_grace_ms
+// intentionally leaves alive past the force-resolve deadline.
+function cleanupByPidFile(pidFile: string): void {
+  if (!existsSync(pidFile)) return;
+  const pid = Number.parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
+  if (!Number.isFinite(pid) || pid <= 0) return;
+  if (isWin) return; // best-effort; test is skipped on win32
+  try {
+    process.kill(-pid, 'SIGKILL');
+  } catch {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // already gone
+    }
+  }
+}
+
+test(
+  'runExecSandbox: SIGTERM-cooperative child exits promptly within grace on timeout',
+  { skip: isWin ? 'Unix-primary graceful semantics' : false, timeout: 20_000 },
+  async (t) => {
+    const base = freshBase();
+    t.after(() => cleanup(base));
+
+    const KILL_GRACE_MS = 5_000;
+    const FORCE_RESOLVE_DELAY_MS = 8_000; // grace + hard-deadline; must NOT be reached
+    const TIMEOUT_MS = 300;
+
+    // Child traps SIGTERM and exits 0, then sleeps long. The first SIGTERM from
+    // the ladder ends it immediately -> `close` fires -> finalize via close,
+    // well before the force-resolve deadline.
+    const script = `trap 'exit 0' TERM; sleep 30`;
+
+    const result = await wallClockGuard(
+      runExecSandbox(
+        { runtime: 'bash', script, timeout_ms: TIMEOUT_MS },
+        baseOpts(base, {
+          kill_grace_ms: KILL_GRACE_MS,
+          force_resolve_delay_ms: FORCE_RESOLVE_DELAY_MS,
+        }),
+      ),
+      15_000,
+    );
+
+    // timed_out is preserved even though the child exited cooperatively.
+    assert.equal(result.timed_out, true, 'timeout fired so timed_out must be true');
+    // Proves SIGTERM (close) resolved it, NOT the force-resolve deadline:
+    // a force-resolve would land at ~TIMEOUT_MS + FORCE_RESOLVE_DELAY_MS (~8.3s).
+    assert.ok(
+      result.duration_ms < KILL_GRACE_MS,
+      `expected prompt close well under grace (${KILL_GRACE_MS}ms), got ${result.duration_ms}ms`,
+    );
+    // A clean SIGTERM-trapped exit resolves via `close` with an exit code,
+    // not the force-resolve sentinel (exit_code null / signal SIGKILL).
+    assert.notEqual(
+      result.signal,
+      'SIGKILL',
+      'cooperative child must not be force-resolved as SIGKILL',
+    );
+    assert.equal(result.force_resolved, false, 'a cooperative close must not be flagged as force-resolved');
+  },
+);
+
+test(
+  'runExecSandbox: SIGTERM-ignoring (non-closing) child force-resolves via hard deadline without hanging',
+  { skip: isWin ? 'Unix-primary graceful semantics; force-resolve covered on POSIX' : false, timeout: 20_000 },
+  async (t) => {
+    const base = freshBase();
+    const pidFile = join(base, 'child.pid');
+    t.after(() => {
+      cleanupByPidFile(pidFile);
+      cleanup(base);
+    });
+
+    // Timing seams: SIGKILL never fires in-window (grace huge), so the only way
+    // the promise can settle is the hard deadline -> proves the caller-side
+    // force-resolve.
+    const KILL_GRACE_MS = 30_000;
+    const FORCE_RESOLVE_DELAY_MS = 800;
+    // Generous timeout so the SIGTERM trap is reliably installed before the kill
+    // fires, even under heavy parallel test load. A too-tight timeout can race
+    // the shell's startup: the kill lands before `trap '' TERM` runs, SIGTERM
+    // takes its default action, the child closes on SIGTERM, and the
+    // force-resolve path never runs (flaky 'SIGTERM' instead of 'SIGKILL').
+    const TIMEOUT_MS = 1_500;
+
+    // Install the SIGTERM trap FIRST (before any other command) so the shell is
+    // already immune by the time the kill fires; then record the detached
+    // shell's PID (process-group leader) for cleanup. The shell loops forever
+    // holding its stdout pipe open -> `close` never fires in-window -> the
+    // caller's hard deadline must force-resolve.
+    const script = `trap '' TERM; echo $$ > '${pidFile}'; while true; do sleep 1; done`;
+
+    const start = Date.now();
+    const result = await wallClockGuard(
+      runExecSandbox(
+        { runtime: 'bash', script, timeout_ms: TIMEOUT_MS },
+        baseOpts(base, {
+          kill_grace_ms: KILL_GRACE_MS,
+          force_resolve_delay_ms: FORCE_RESOLVE_DELAY_MS,
+        }),
+      ),
+      8_000,
+    );
+    const elapsed = Date.now() - start;
+
+    // (a) Did not hang and settled well before the SIGKILL grace would fire.
+    assert.ok(
+      elapsed < KILL_GRACE_MS,
+      `expected force-resolve before SIGKILL grace (${KILL_GRACE_MS}ms), took ${elapsed}ms`,
+    );
+    // (b) Settled in the force-resolve band: >= timeout (kill initiated) and
+    //     roughly timeout + force_resolve_delay (generous CI slack, but kept below
+    //     the 8000ms wallClockGuard so the upper bound is actually reachable).
+    assert.ok(
+      elapsed >= TIMEOUT_MS && elapsed <= TIMEOUT_MS + FORCE_RESOLVE_DELAY_MS + 4_000,
+      `expected settle near ${TIMEOUT_MS + FORCE_RESOLVE_DELAY_MS}ms, took ${elapsed}ms`,
+    );
+    // (c) Force-resolve preserves timed_out and surfaces the SIGKILL sentinel
+    //     (exit_code null) plus the explicit force_resolved flag, so the agent can
+    //     tell a forced kill (D-state hard deadline) from a clean SIGKILL exit.
+    assert.equal(result.timed_out, true, 'force-resolve must preserve timed_out');
+    assert.equal(result.exit_code, null, 'force-resolve exit_code must be null');
+    assert.equal(result.signal, 'SIGKILL', 'force-resolve must mark signal SIGKILL');
+    assert.equal(result.force_resolved, true, 'force-resolve must set force_resolved=true');
+  },
+);