@opengsd/gsd-pi 1.2.0-dev.fb12b103 → 1.2.0-dev.fbdca60b

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

@@ -0,0 +1,328 @@
+// 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,
+  lookupLatestLedgerError,
+  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("lookupLatestLedgerError matches the bare unit id, not the compound key", (t) => {
+  const f = makeLedgerFixture(t);
+  const dispatchId = f.claim("execute-task", "M001/S01/T01");
+  markFailed(dispatchId, { errorSummary: "boom: deterministic failure" });
+
+  // The ledger keys rows by the bare unit id with the unit type in its own
+  // column. The shared lookup (also used by dispatch.ts's runDispatch path)
+  // must use the bare id; a compound `unitType/unitId` value misses entirely,
+  // which previously silently dropped repeat-error detection on that path.
+  assert.equal(
+    lookupLatestLedgerError("execute-task", "M001/S01/T01"),
+    "boom: deterministic failure",
+  );
+  assert.equal(
+    lookupLatestLedgerError("execute-task", "execute-task/M001/S01/T01"),
+    undefined,
+    "a compound key must not match the bare-id ledger row",
+  );
+  assert.equal(
+    lookupLatestLedgerError("plan-slice", "M001/S01/T01"),
+    undefined,
+    "a different unit type on the same id must not be attached",
+  );
+});
+
+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 mirrors recordDispatch error attachment so repeat-error detection fires after the next dispatch", (t) => {
+  const f = makeLedgerFixture(t);
+  // Session 1: two failed dispatches for the same unit, same error summary.
+  for (let i = 0; i < 2; i++) {
+    const id = f.claim("execute-task", "M001/S01/T01");
+    markFailed(id, { errorSummary: "boom: deterministic failure" });
+  }
+
+  // Session 2: fresh history rehydrates from the ledger. Just like the live
+  // recordDispatch path, the first occurrence of a unit skips the ledger
+  // lookup; only repeats carry the error. So rehydration alone does not trip
+  // Rule 1 — keeping the post-restart window no more aggressive than the live
+  // one (Rule 1 has no retry-budget suppression).
+  const restarted = historyFor(f.base);
+  const count = restarted.rehydrate();
+  assert.equal(count, 2);
+  const window = restarted.getRecentWindow();
+  assert.equal(window[0].error, undefined);
+  assert.equal(window[1].error, "boom: deterministic failure");
+  assert.equal(restarted.detectStuck(), null);
+
+  // The next dispatch of the same unit attaches the error again, giving two
+  // consecutive matching errors → Rule 1 fires, exactly as in the live path.
+  restarted.recordDispatch("execute-task", "M001/S01/T01");
+  const verdict = restarted.detectStuck();
+  assert.equal(verdict?.stuck, true);
+  assert.match(verdict?.reason ?? "", /Same error repeated/);
+});
+
+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/dist-redirect.mjs

@@ -7,6 +7,10 @@ const require = createRequire(import.meta.url);
 const ROOT = new URL("../../../../../", import.meta.url);
 
 export function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith('node:')) {
+    return { url: specifier, format: 'builtin', shortCircuit: true };
+  }
+
   // 1. Redirect all workspace package bare imports to source.
   //    CI portability runs don't build any packages/ dist artifacts, so every
   //    @gsd/* specifier (including transitive ones pulled in by pi-coding-agent
@@ -100,6 +104,10 @@ export function resolve(specifier, context, nextResolve) {
 }
 
 export function load(url, context, nextLoad) {
+  if (url.startsWith('node:') || context.format === 'builtin') {
+    return { format: 'builtin', source: '', shortCircuit: true };
+  }
+
   // jiti/CJS may still enter through stale packages/*/dist/index.js — redirect to src.
   if (url.includes('/packages/pi-ai/dist/index.js')) {
     url = url.replace('/dist/index.js', '/src/index.ts');

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/engine-hook-contract.test.ts

@@ -0,0 +1,148 @@
+// Engine hook contract: which tool lifecycle hooks fire under which engine,
+// and the consolidated tool-name normalizer seam.
+//
+// 1. Pins the contract arrays (engine-hook-contract.ts) so a change to the
+//    fire matrix is a deliberate, reviewed act.
+// 2. Source-scans register-hooks.ts (in the style of
+//    single-writer-invariant.test.ts) to assert that the concerns documented
+//    as universally mirrored — evidence collection and write-gate (re-)arming —
+//    actually live inside a tool_execution_start handler, not only in the
+//    native-only tool_call handlers.
+// 3. Pins normalizer parity: canonicalHeadlessToolName delegates to
+//    canonicalToolName (strip-only), and canonicalWorkflowToolName adds alias
+//    resolution on top of the same strip.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  UNIVERSAL_TOOL_HOOKS,
+  NATIVE_ONLY_TOOL_HOOKS,
+  canonicalToolName,
+  canonicalWorkflowToolName,
+} from "../engine-hook-contract.js";
+import { canonicalHeadlessToolName } from "../../../../headless-events.js";
+import { WORKFLOW_TOOL_ALIAS_PAIRS } from "../workflow-tool-surface.js";
+
+test("contract arrays pin the verified fire matrix", () => {
+  assert.deepEqual([...UNIVERSAL_TOOL_HOOKS], ["tool_execution_start", "tool_execution_end"]);
+  assert.deepEqual([...NATIVE_ONLY_TOOL_HOOKS], ["tool_call", "tool_result"]);
+});
+
+// ---------------------------------------------------------------------------
+// Source scan: register-hooks.ts must mirror safety concerns universally
+// ---------------------------------------------------------------------------
+
+const registerHooksSource = readFileSync(
+  join(process.cwd(), "src/resources/extensions/gsd/bootstrap/register-hooks.ts"),
+  "utf8",
+);
+
+/**
+ * Extract the body of every `pi.on("<eventName>", ...)` registration by
+ * scanning balanced parentheses from each registration site.
+ */
+function hookBodies(source: string, eventName: string): string[] {
+  const bodies: string[] = [];
+  const marker = `pi.on("${eventName}"`;
+  let from = 0;
+  for (;;) {
+    const start = source.indexOf(marker, from);
+    if (start < 0) break;
+    let depth = 0;
+    let end = -1;
+    // Scan from pi.on's own opening paren so the whole registration is balanced.
+    for (let i = start + "pi.on".length; i < source.length; i++) {
+      const ch = source[i];
+      if (ch === "(") depth++;
+      else if (ch === ")") {
+        depth--;
+        if (depth === 0) {
+          end = i;
+          break;
+        }
+      }
+    }
+    assert.ok(end > start, `unbalanced pi.on("${eventName}") registration`);
+    bodies.push(source.slice(start, end + 1));
+    from = end + 1;
+  }
+  return bodies;
+}
+
+test("tool_execution_start handler mirrors evidence collection and write-gate arming", () => {
+  const bodies = hookBodies(registerHooksSource, "tool_execution_start");
+  assert.ok(bodies.length >= 1, "register-hooks.ts must register a tool_execution_start handler");
+  const merged = bodies.join("\n");
+
+  // Evidence collection: the safety harness records the call on the universal
+  // hook (deduped by toolCallId against the native-only tool_call recording).
+  assert.match(merged, /safetyRecordToolCall\(/);
+  assert.match(merged, /saveEvidenceToDisk\(/);
+
+  // Write-gate (re-)arming: external engines never reach the tool_call
+  // deferApprovalGate path, so the durable pending gate must be armed here.
+  assert.match(merged, /hostWriteGateAdapter\.setPending\(/);
+});
+
+test("mirrored concerns also exist on the native-only tool_call side (dedup pairing)", () => {
+  const bodies = hookBodies(registerHooksSource, "tool_call");
+  assert.ok(bodies.length >= 1, "register-hooks.ts must register tool_call handlers");
+  const merged = bodies.join("\n");
+  assert.match(merged, /safetyRecordToolCall\(/);
+  assert.match(merged, /deferApprovalGate\(/);
+});
+
+test("tool_execution_end handler mirrors error classification and evidence persistence", () => {
+  const bodies = hookBodies(registerHooksSource, "tool_execution_end");
+  assert.ok(bodies.length >= 1, "register-hooks.ts must register a tool_execution_end handler");
+  const merged = bodies.join("\n");
+  assert.match(merged, /recordToolInvocationError\(/);
+  assert.match(merged, /safetyRecordToolResult\(/);
+});
+
+// ---------------------------------------------------------------------------
+// Normalizer parity
+// ---------------------------------------------------------------------------
+
+test("canonicalHeadlessToolName matches canonicalToolName on the edge-case table", () => {
+  const cases: Array<{ input: string; expected: string }> = [
+    { input: "mcp__server__tool", expected: "tool" },
+    { input: "mcp__gsd-workflow__gsd_status", expected: "gsd_status" },
+    { input: "plain", expected: "plain" },
+    { input: "ask_user_questions", expected: "ask_user_questions" },
+    // Nested underscores: only the first server/tool delimiter splits.
+    { input: "mcp__s__a__b", expected: "a__b" },
+    { input: "", expected: "" },
+    { input: "mcp__", expected: "mcp__" },
+    // Malformed names stay unchanged (strict parser: empty server/tool → no strip).
+    { input: "mcp____tool", expected: "mcp____tool" },
+    { input: "mcp__server__", expected: "mcp__server__" },
+  ];
+  for (const { input, expected } of cases) {
+    assert.equal(canonicalToolName(input), expected, `canonicalToolName(${JSON.stringify(input)})`);
+    assert.equal(
+      canonicalHeadlessToolName(input),
+      canonicalToolName(input),
+      `headless/strip parity for ${JSON.stringify(input)}`,
+    );
+  }
+  assert.equal(canonicalHeadlessToolName(undefined), "");
+});
+
+test("canonicalWorkflowToolName = prefix strip + workflow alias resolution", () => {
+  // Non-alias names behave exactly like canonicalToolName.
+  for (const name of ["mcp__server__tool", "plain", "mcp__s__a__b"]) {
+    assert.equal(canonicalWorkflowToolName(name), canonicalToolName(name));
+  }
+  // Alias names additionally resolve to the canonical workflow tool.
+  assert.ok(WORKFLOW_TOOL_ALIAS_PAIRS.length > 0, "expected at least one workflow alias");
+  for (const { alias, canonical } of WORKFLOW_TOOL_ALIAS_PAIRS) {
+    assert.equal(canonicalWorkflowToolName(alias), canonical);
+    assert.equal(canonicalWorkflowToolName(`mcp__gsd-workflow__${alias}`), canonical);
+    // Plain strip must NOT resolve aliases — that distinction is the seam.
+    assert.equal(canonicalToolName(alias), alias);
+  }
+});