@opengsd/gsd-pi 1.2.0-dev.4c756166 → 1.2.0-dev.6ccd27b3

package/src/resources/extensions/gsd/tests/state-transition-matrix.test.ts

@@ -5,6 +5,8 @@ import {
   STATE_TRANSITION_MATRIX,
   findTransition,
   validateTransitionMatrix,
+  isLegalEdge,
+  IllegalPhaseTransitionError,
 } from "../state-transition-matrix.ts";
 
 test("state transition matrix covers required swarm hardening events", () => {
@@ -42,3 +44,37 @@ test("state transition matrix entries all have guard and reason codes", () => {
     assert.ok(entry.reasonCode.length > 0, `${entry.event} must include reason code`);
   }
 });
+
+// ─── ADR-030: Phase Transition Invariant ───────────────────────────────────
+
+test("isLegalEdge treats a self-edge as trivially legal", () => {
+  assert.equal(isLegalEdge("executing", "executing"), true);
+  assert.equal(isLegalEdge("planning", "planning"), true);
+});
+
+test("isLegalEdge accepts edges enumerated in the matrix", () => {
+  assert.equal(isLegalEdge("planning", "executing"), true);
+  assert.equal(isLegalEdge("executing", "summarizing"), true);
+  assert.equal(isLegalEdge("summarizing", "validating-milestone"), true);
+  assert.equal(isLegalEdge("completing-milestone", "complete"), true);
+});
+
+test("isLegalEdge honors the * wildcard rows (any -> blocked, any -> executing)", () => {
+  assert.equal(isLegalEdge("planning", "blocked"), true);
+  assert.equal(isLegalEdge("summarizing", "executing"), true);
+});
+
+test("isLegalEdge rejects an edge no matrix entry permits", () => {
+  // executing -> complete skips validation — exactly the illegal jump the
+  // invariant exists to catch.
+  assert.equal(isLegalEdge("executing", "complete"), false);
+  assert.equal(isLegalEdge("planning", "summarizing"), false);
+});
+
+test("IllegalPhaseTransitionError carries both endpoints and a descriptive message", () => {
+  const err = new IllegalPhaseTransitionError("executing", "complete");
+  assert.equal(err.from, "executing");
+  assert.equal(err.to, "complete");
+  assert.equal(err.name, "IllegalPhaseTransitionError");
+  assert.match(err.message, /executing -> complete/);
+});

package/src/resources/extensions/gsd/tests/status-guards.test.ts

@@ -9,7 +9,10 @@ import {
   isDeferredStatus,
   isInactiveStatus,
   isSkippedForDispatch,
+  toStatus,
+  RAW_CLOSED_STATUSES,
 } from '../status-guards.ts';
+import { TERMINAL_STATUS_SQL } from '../db/sql-constants.ts';
 
 test('isClosedStatus: "complete" returns true', () => {
   assert.equal(isClosedStatus('complete'), true);
@@ -95,3 +98,38 @@ test('isSkippedForDispatch does NOT skip pending/active/planned', () => {
     assert.equal(isSkippedForDispatch(s), false, `${s} should block dispatch ordering`);
   }
 });
+
+// ─── ADR-030: canonical Status vocabulary + normalization ──────────────────
+
+test('toStatus passes canonical values through unchanged', () => {
+  for (const s of ['pending', 'queued', 'active', 'parked', 'in_progress', 'blocked', 'complete', 'skipped', 'deferred']) {
+    assert.equal(toStatus(s), s, `${s} is canonical and should be returned verbatim`);
+  }
+});
+
+test('toStatus maps known aliases to canonical', () => {
+  assert.equal(toStatus('done'), 'complete');
+  assert.equal(toStatus('closed'), 'complete');
+  assert.equal(toStatus('planned'), 'pending');
+  assert.equal(toStatus('in-progress'), 'in_progress');
+});
+
+test('toStatus trims surrounding whitespace before matching', () => {
+  assert.equal(toStatus('  complete  '), 'complete');
+  assert.equal(toStatus(' done '), 'complete');
+});
+
+test('toStatus quarantines unknown values verbatim (tolerant read, no throw)', () => {
+  assert.equal(toStatus('weird-legacy-value'), 'weird-legacy-value');
+});
+
+test('RAW_CLOSED_STATUSES is the single source: every member is closed', () => {
+  for (const s of RAW_CLOSED_STATUSES) {
+    assert.equal(isClosedStatus(s), true, `${s} is in RAW_CLOSED_STATUSES so must be closed`);
+  }
+});
+
+test('TERMINAL_STATUS_SQL is derived from RAW_CLOSED_STATUSES and renders identically', () => {
+  assert.equal(TERMINAL_STATUS_SQL, "'complete', 'done', 'skipped', 'closed'");
+  assert.equal(TERMINAL_STATUS_SQL, RAW_CLOSED_STATUSES.map((s) => `'${s}'`).join(', '));
+});

package/src/resources/extensions/gsd/tests/stop-auto-race-null-unit.test.ts

@@ -3,7 +3,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 
-import { _resolveCurrentUnitStartedAtForTest } from "../auto/phases.ts";
+import { _resolveCurrentUnitStartedAtForTest } from "../auto/phase-helpers.ts";
 
 test("unit started-at resolver tolerates stopAuto clearing currentUnit", () => {
   assert.equal(_resolveCurrentUnitStartedAtForTest(null), undefined);

package/src/resources/extensions/gsd/tests/stop-notice.test.ts

@@ -0,0 +1,70 @@
+// GSD Extension — Stop Notice module tests
+// Locks the emitter↔detector round-trip: every notice the formatters produce
+// must be recognized by the classifiers the headless host uses for exit codes.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  formatStopNoticePrefix,
+  isBlockedStopReason,
+  stopNoticeDisplayReason,
+  stopNoticeKind,
+  isTerminalNotice,
+  isPauseNotice,
+  isBlockedNoticeMessage,
+  isManualResolutionNotice,
+  PAUSED_NOTICE_PREFIXES,
+  TERMINAL_NOTICE_PREFIXES,
+} from "../stop-notice.js";
+
+describe("stop notice formatting", () => {
+  test("plain stop has no reason suffix", () => {
+    assert.equal(formatStopNoticePrefix(), "Auto-mode stopped");
+    assert.equal(formatStopNoticePrefix(null), "Auto-mode stopped");
+  });
+
+  test("reason is appended after an em-dash", () => {
+    assert.equal(formatStopNoticePrefix("user request"), "Auto-mode stopped — user request");
+  });
+
+  test("Blocked: marker switches the prefix and is stripped from display", () => {
+    assert.equal(formatStopNoticePrefix("Blocked: validation gate"), "Auto-mode blocked — validation gate");
+    assert.equal(stopNoticeKind("Blocked: x"), "blocked");
+    assert.equal(stopNoticeKind("stop"), "stopped");
+    assert.ok(isBlockedStopReason("blocked: lowercase too"));
+    assert.equal(stopNoticeDisplayReason("Blocked:  spaced "), "spaced");
+  });
+});
+
+describe("emitter↔detector round-trip", () => {
+  test("formatted stop notices classify as terminal", () => {
+    for (const reason of [undefined, "user request"]) {
+      const message = formatStopNoticePrefix(reason).toLowerCase();
+      assert.ok(isTerminalNotice(message), `not terminal: ${message}`);
+    }
+  });
+
+  test("pause prefixes classify as pause and as blocked (operator intervention)", () => {
+    for (const prefix of PAUSED_NOTICE_PREFIXES) {
+      assert.ok(isPauseNotice(`${prefix}: provider error`));
+      assert.ok(isBlockedNoticeMessage(`${prefix}: provider error`));
+    }
+  });
+
+  test("idempotent-advance pauses are non-blocking", () => {
+    assert.equal(isBlockedNoticeMessage("auto-mode paused (idempotent advance: unit already active)"), false);
+  });
+
+  test("manual-resolution notices classify as blocked", () => {
+    const message = "merge conflict — resolve manually and re-run /gsd auto";
+    assert.ok(isManualResolutionNotice(message));
+    assert.ok(isBlockedNoticeMessage(message));
+  });
+
+  test("terminal prefixes cover the known stop vocabulary", () => {
+    for (const message of ["auto-mode stopped.", "auto-mode complete", "auto-mode idle", "no active milestone"]) {
+      assert.ok(TERMINAL_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix)), message);
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/teardown-chdir-failure-clears-registry.test.ts

@@ -159,4 +159,21 @@ describe("teardown chdir failure clears registry", () => {
     assert.strictEqual(getAutoWorktreeOriginalBase(), null, "registry null after successful teardown");
     assert.strictEqual(getActiveAutoWorktreeContext(), null, "context null after successful teardown");
   });
+
+  test("teardown survives when current working directory was deleted", () => {
+    repoDir = createTempRepo();
+    seedMilestone(repoDir, "M003");
+
+    const worktreePath = createAutoWorktree(repoDir, "M003");
+    process.chdir(worktreePath);
+    rmSync(worktreePath, { recursive: true, force: true });
+
+    assert.doesNotThrow(
+      () => teardownAutoWorktree(repoDir, "M003"),
+      "teardownAutoWorktree should not call process.cwd() unguarded from a deleted cwd",
+    );
+
+    assert.strictEqual(getAutoWorktreeOriginalBase(), null, "registry null after deleted-cwd teardown");
+    assert.strictEqual(getActiveAutoWorktreeContext(), null, "context null after deleted-cwd teardown");
+  });
 });

package/src/resources/extensions/gsd/tests/token-tool-gating.test.ts

@@ -10,6 +10,7 @@ import { DISCUSS_TOOLS_ALLOWLIST } from "../constants.ts";
 import { buildMinimalAutoGsdToolSet, buildMinimalGsdToolSet, buildMinimalGsdWorkflowToolSet, buildRequestScopedGsdToolSet, MINIMAL_AUTO_BASE_TOOL_NAMES, MINIMAL_GSD_TOOL_NAMES, requestHasGsdCustomType, restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch } from "../bootstrap/register-hooks.ts";
 import { filterToolsForProvider } from "../model-router.ts";
 import { applyUnitSkillVisibility } from "../skill-scope.ts";
+import { drainLogs } from "../workflow-logger.ts";
 
 test("buildMinimalGsdToolSet preserves non-GSD tools and replaces broad GSD surface", () => {
   const result = buildMinimalGsdToolSet([
@@ -17,6 +18,7 @@ test("buildMinimalGsdToolSet preserves non-GSD tools and replaces broad GSD surf
     "read",
     "browser_open",
     "gsd_plan_milestone",
+    "gsd_plan_slice",
     "gsd_task_complete",
     "gsd_exec",
     "gsd_exec_search",
@@ -103,6 +105,40 @@ test("buildMinimalAutoGsdToolSet keeps unit-specific completion tools without al
   assert.ok(!result.includes("gsd_complete_slice"));
 });
 
+test("buildMinimalAutoGsdToolSet warns when plan-milestone required tools are unresolved", () => {
+  drainLogs();
+  const result = buildMinimalAutoGsdToolSet(
+    [
+      "ask_user_questions",
+      "bash",
+      "read",
+      "gsd_milestone_status",
+      "gsd_plan_milestone",
+    ],
+    "plan-milestone",
+    [
+      "ask_user_questions",
+      "bash",
+      "read",
+      "gsd_milestone_status",
+      "gsd_plan_milestone",
+    ],
+  );
+
+  assert.ok(result.includes("gsd_plan_milestone"));
+  assert.ok(!result.includes("gsd_plan_slice"));
+
+  const logs = drainLogs();
+  assert.ok(
+    logs.some((entry) =>
+      entry.component === "bootstrap" &&
+      entry.message.includes("buildMinimalAutoGsdToolSet(plan-milestone)") &&
+      entry.message.includes("gsd_plan_slice")
+    ),
+    `expected missing gsd_plan_slice bootstrap warning, got ${JSON.stringify(logs)}`,
+  );
+});
+
 test("buildMinimalAutoGsdToolSet scopes run-uat to UAT-specific and read-only tools", () => {
   const active = ["ask_user_questions", "bash", "read", "edit", "write", "gsd_summary_save"];
   const registered = [
@@ -329,13 +365,14 @@ test("buildMinimalAutoGsdToolSet includes closeout tool for complete-slice", ()
     "gsd_complete_slice",
     "memory_query",
     "capture_thought",
+    "gsd_capture_thought",
   ], "complete-slice");
 
   assert.ok(result.includes("gsd_slice_complete"));
   assert.ok(result.includes("gsd_task_reopen"));
   assert.ok(result.includes("gsd_replan_slice"));
   assert.ok(result.includes("subagent"));
-  assert.ok(result.includes("capture_thought"));
+  assert.ok(result.includes("gsd_capture_thought"));
   assert.ok(!result.includes("gsd_task_complete"));
   assert.ok(!result.includes("gsd_complete_slice"));
 });
@@ -351,6 +388,7 @@ test("buildMinimalAutoGsdToolSet preserves workflow MCP-namespaced closeout tool
     "mcp__gsd-workflow__gsd_exec",
     "mcp__gsd-workflow__memory_query",
     "mcp__gsd-workflow__capture_thought",
+    "mcp__gsd-workflow__gsd_capture_thought",
   ], "complete-slice");
 
   assert.ok(result.includes("mcp__gsd-workflow__gsd_task_reopen"));
@@ -359,7 +397,7 @@ test("buildMinimalAutoGsdToolSet preserves workflow MCP-namespaced closeout tool
   assert.ok(!result.includes("mcp__gsd-workflow__gsd_complete_slice"));
   assert.ok(result.includes("mcp__gsd-workflow__gsd_exec"));
   assert.ok(result.includes("mcp__gsd-workflow__memory_query"));
-  assert.ok(result.includes("mcp__gsd-workflow__capture_thought"));
+  assert.ok(result.includes("mcp__gsd-workflow__gsd_capture_thought"));
 });
 
 test("buildMinimalAutoGsdToolSet covers execute-task-simple", () => {
@@ -613,6 +651,46 @@ test("buildMinimalAutoGsdToolSet resolves MCP-scoped gsd_memory_query and gsd_ca
   );
 });
 
+// ── Regression #627: auto-mode cannot run plan-milestone because gsd_plan_slice is missing ──
+// gsd_plan_slice is in AUTO_UNIT_SCOPED_TOOLS["plan-milestone"] (via unit-tool-contracts).
+// buildMinimalAutoGsdToolSet must expose it when unitType is "plan-milestone".
+
+test("buildMinimalAutoGsdToolSet includes gsd_plan_slice for plan-milestone (regression #627)", () => {
+  const result = buildMinimalAutoGsdToolSet([
+    "bash",
+    "read",
+    "gsd_plan_milestone",
+    "gsd_plan_slice",
+    "gsd_milestone_status",
+    "gsd_checkpoint_db",
+    "memory_query",
+    "capture_thought",
+  ], "plan-milestone");
+
+  assert.ok(
+    result.includes("gsd_plan_slice"),
+    "gsd_plan_slice must be included in plan-milestone auto-mode tool set",
+  );
+});
+
+test("buildMinimalAutoGsdToolSet resolves MCP-scoped gsd_plan_slice for plan-milestone when subprocess only registers prefixed variant (regression #627)", () => {
+  const result = buildMinimalAutoGsdToolSet([
+    "bash",
+    "read",
+    "mcp__gsd-workflow__gsd_plan_milestone",
+    "mcp__gsd-workflow__gsd_plan_slice",
+    "mcp__gsd-workflow__gsd_milestone_status",
+    "mcp__gsd-workflow__gsd_checkpoint_db",
+    "mcp__gsd-workflow__memory_query",
+    "mcp__gsd-workflow__capture_thought",
+  ], "plan-milestone");
+
+  assert.ok(
+    result.includes("mcp__gsd-workflow__gsd_plan_slice"),
+    "mcp__gsd-workflow__gsd_plan_slice must be included when only the MCP-scoped variant is available",
+  );
+});
+
 test("applyUnitSkillVisibility sets manifest or clears for wildcard", () => {
   const calls: Array<string[] | undefined> = [];
   applyUnitSkillVisibility({

package/src/resources/extensions/gsd/tests/tool-invocation-error-loop-break.test.ts

@@ -48,6 +48,7 @@ import {
   isDeterministicPolicyError,
   isPendingUserApprovalGateError,
   isToolInvocationError,
+  isToolUnavailableError,
   isQueuedUserMessageSkip,
 } from "../auto-tool-tracking.ts";
 import {
@@ -121,6 +122,13 @@ describe("#2883: isToolInvocationError classification", () => {
     assert.equal(isToolInvocationError("No such tool available: mcp__gsd-workflow__memory_query"), true);
   });
 
+  test("isToolUnavailableError singles out the startup-race error as transient", () => {
+    assert.equal(isToolUnavailableError("No such tool available: mcp__gsd-workflow__gsd_uat_exec"), true);
+    assert.equal(isToolUnavailableError("Validation failed for tool gsd_complete_slice"), false);
+    assert.equal(isToolUnavailableError("Unexpected end of JSON input"), false);
+    assert.equal(isToolUnavailableError(""), false);
+  });
+
   test("detects ESM export-link errors", () => {
     assert.equal(
       isToolInvocationError("The requested module '../paths.js' does not provide an export named 'gsdProjectionRoot'"),

package/src/resources/extensions/gsd/tests/tool-surface-readiness.test.ts

@@ -0,0 +1,329 @@
+// Project/App: gsd-pi
+// File Purpose: Contract coverage for the Tool Surface Readiness gate and its recovery classification.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import { getToolSurfaceReadinessError, awaitWorkflowMcpToolRegistration } from "../tool-surface-readiness.ts";
+import { clearWorkflowMcpProbeCache, recordWorkflowMcpProbe } from "../workflow-mcp-readiness-cache.ts";
+import { isToolUnavailableError } from "../auto-tool-tracking.ts";
+import { classifyError, isTransient } from "../error-classifier.ts";
+import { toMcpToolName } from "../mcp-tool-name.ts";
+import { classifyFailure } from "../recovery-classification.ts";
+
+const SERVER = "gsd-workflow";
+
+function prefixed(tool: string): string {
+  return toMcpToolName(SERVER, tool);
+}
+
+const RUN_UAT_TOOLS = [
+  "gsd_uat_exec",
+  "gsd_uat_result_save",
+  "gsd_resume",
+  "gsd_milestone_status",
+  "gsd_journal_query",
+];
+
+describe("getToolSurfaceReadinessError", () => {
+  test("returns null when no unit type or no workflow server is in play", () => {
+    const observation = { tools: [], mcpServers: [] };
+    assert.equal(
+      getToolSurfaceReadinessError({ unitType: undefined, workflowServerName: SERVER, observation }),
+      null,
+    );
+    assert.equal(
+      getToolSurfaceReadinessError({ unitType: "run-uat", workflowServerName: undefined, observation }),
+      null,
+    );
+  });
+
+  test("returns null for units with no required workflow tools", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "rewrite-docs",
+      workflowServerName: SERVER,
+      observation: { tools: [], mcpServers: [{ name: SERVER, status: "failed" }] },
+    });
+    assert.equal(error, null);
+  });
+
+  test("returns an error when the expected workflow server is absent from the init surface", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: { tools: ["read", "bash"], mcpServers: [{ name: "other-server", status: "connected" }] },
+    });
+    assert.ok(error, "expected a readiness error when the workflow server is absent");
+    assert.match(error, /workflow tool surface not ready for run-uat/);
+    assert.match(error, /absent from the init surface/);
+    assert.match(error, /gsd_uat_exec/);
+  });
+
+  test("still blocks pending init when required tools are absent from the live surface", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "pending" }] },
+    });
+    assert.ok(error);
+    assert.match(error!, /status is "pending"/);
+    assert.match(error!, /gsd_uat_exec/);
+  });
+
+  test("accepts pending server status when the live init surface already contains every required tool", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: [
+          prefixed("gsd_uat_exec"),
+          prefixed("gsd_uat_result_save"),
+          prefixed("gsd_resume"),
+          prefixed("gsd_milestone_status"),
+          prefixed("gsd_journal_query"),
+        ],
+        mcpServers: [{ name: SERVER, status: "pending" }],
+      },
+    });
+    assert.equal(error, null);
+  });
+
+  test("does not accept a pending live init surface just because a probe cache covers required tools", () => {
+    clearWorkflowMcpProbeCache();
+    const projectRoot = "/tmp/project-discuss-probe";
+    recordWorkflowMcpProbe(projectRoot, SERVER, [
+      "ask_user_questions",
+      "gsd_summary_save",
+      "gsd_requirement_save",
+      "gsd_requirement_update",
+      "gsd_plan_milestone",
+      "gsd_milestone_generate_id",
+    ]);
+
+    const error = getToolSurfaceReadinessError({
+      unitType: "discuss-milestone",
+      workflowServerName: SERVER,
+      projectRoot,
+      observation: {
+        tools: [],
+        mcpServers: [{ name: SERVER, status: "pending" }],
+      },
+    });
+
+    assert.ok(error, "expected live init tools to be authoritative over direct probe cache");
+    assert.match(error, /status is "pending"/);
+    assert.match(error, /ask_user_questions/);
+  });
+
+  test("pending server status reports only required tools missing from the live init surface", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: [
+          prefixed("gsd_uat_result_save"),
+          prefixed("gsd_resume"),
+          prefixed("gsd_milestone_status"),
+          prefixed("gsd_journal_query"),
+        ],
+        mcpServers: [{ name: SERVER, status: "pending" }],
+      },
+    });
+    assert.ok(error, "expected a readiness error while gsd_uat_exec is still absent");
+    assert.match(error, /status is "pending"/);
+    assert.match(error, /gsd_uat_exec/);
+    assert.doesNotMatch(error, /gsd_uat_result_save/);
+  });
+
+  test("returns null when all required tools are registered under the MCP prefix", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: ["read", ...RUN_UAT_TOOLS.map(prefixed)],
+        mcpServers: [{ name: SERVER, status: "connected" }],
+      },
+    });
+    assert.equal(error, null);
+  });
+
+  test("reports the failed server as terminal", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "failed" }] },
+    });
+    assert.ok(error, "expected a readiness error");
+    assert.match(error, /workflow tool surface not ready for run-uat/);
+    assert.match(error, /terminal/);
+  });
+
+  test("reports terminal status even when required tools are already on the init surface", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: RUN_UAT_TOOLS.map(prefixed),
+        mcpServers: [{ name: SERVER, status: "failed" }],
+      },
+    });
+    assert.ok(error, "expected a readiness error despite tools on the surface");
+    assert.match(error, /terminal/);
+    assert.match(error, /gsd_uat_exec/);
+  });
+
+  test("aborts on needs-auth (terminal — cannot self-heal)", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "needs-auth" }] },
+    });
+    assert.ok(error, "expected a readiness error for needs-auth");
+    assert.match(error, /terminal/);
+  });
+
+  test("aborts on disabled (terminal — cannot self-heal)", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "disabled" }] },
+    });
+    assert.ok(error, "expected a readiness error for disabled");
+    assert.match(error, /terminal/);
+  });
+
+  test("reports partially-registered surfaces even when the server says connected", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: [prefixed("gsd_uat_exec")],
+        mcpServers: [{ name: SERVER, status: "connected" }],
+      },
+    });
+    assert.ok(error, "expected a readiness error");
+    assert.match(error, /connected but has not registered/);
+    assert.match(error, /gsd_uat_result_save/);
+    assert.doesNotMatch(error, /gsd_uat_exec,/);
+  });
+
+  test("reports the screenshot case: result save registered but UAT exec missing", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: [
+          prefixed("gsd_uat_result_save"),
+          prefixed("gsd_resume"),
+          prefixed("gsd_milestone_status"),
+          prefixed("gsd_journal_query"),
+        ],
+        mcpServers: [{ name: SERVER, status: "connected" }],
+      },
+    });
+    assert.ok(error, "expected a readiness error when gsd_uat_exec is absent");
+    assert.match(error, /connected but has not registered/);
+    assert.match(error, /gsd_uat_exec/);
+    assert.doesNotMatch(error, /gsd_uat_result_save/);
+  });
+});
+
+describe("awaitWorkflowMcpToolRegistration", () => {
+  test("does not skip live probe when cache already covers required tools", async () => {
+    clearWorkflowMcpProbeCache();
+    const { recordWorkflowMcpProbe } = await import("../workflow-mcp-readiness-cache.ts");
+    recordWorkflowMcpProbe("/tmp/project-cache-hit", SERVER, RUN_UAT_TOOLS);
+
+    let probeCalls = 0;
+    const error = await awaitWorkflowMcpToolRegistration({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      projectRoot: "/tmp/project-cache-hit",
+      timeoutMs: 1,
+      pollMs: 1,
+      probe: async () => {
+        probeCalls += 1;
+        return { ok: true, tools: RUN_UAT_TOOLS };
+      },
+    });
+    assert.equal(error, null);
+    assert.ok(probeCalls > 0, "preflight must probe the live MCP server even when cache is warm");
+  });
+
+  test("resolves when probe reports required tools", async () => {
+    clearWorkflowMcpProbeCache();
+    const error = await awaitWorkflowMcpToolRegistration({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      projectRoot: "/tmp/project",
+      timeoutMs: 1_000,
+      pollMs: 1,
+      probe: async () => ({
+        ok: true,
+        tools: RUN_UAT_TOOLS,
+      }),
+    });
+    assert.equal(error, null);
+  });
+
+  test("times out when required tools never register", async () => {
+    clearWorkflowMcpProbeCache();
+    const error = await awaitWorkflowMcpToolRegistration({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      projectRoot: "/tmp/project",
+      timeoutMs: 5,
+      pollMs: 1,
+      probe: async () => ({ ok: true, tools: ["gsd_uat_result_save"] }),
+    });
+    assert.ok(error);
+    assert.match(error!, /did not register required tools before session start/);
+  });
+
+  test("aborts while waiting for workflow MCP tools", async () => {
+    clearWorkflowMcpProbeCache();
+    const controller = new AbortController();
+    let probeCount = 0;
+    const wait = awaitWorkflowMcpToolRegistration({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      projectRoot: "/tmp/project-abort",
+      timeoutMs: 10_000,
+      pollMs: 10_000,
+      signal: controller.signal,
+      probe: async () => {
+        probeCount += 1;
+        return { ok: true, tools: ["gsd_uat_result_save"] };
+      },
+    });
+
+    controller.abort();
+
+    await assert.rejects(wait, /AbortError/);
+    assert.equal(probeCount, 1);
+  });
+});
+
+describe("readiness error classification contract", () => {
+  const readinessError = getToolSurfaceReadinessError({
+    unitType: "run-uat",
+    workflowServerName: SERVER,
+    observation: { tools: [], mcpServers: [{ name: SERVER, status: "failed" }] },
+  })!;
+
+  test("auto-tool-tracking treats the readiness error as tool-unavailable", () => {
+    assert.equal(isToolUnavailableError(readinessError), true);
+  });
+
+  test("error-classifier treats the readiness error as transient", () => {
+    const cls = classifyError(`Claude Code error: ${readinessError}`);
+    assert.equal(isTransient(cls), true);
+  });
+
+  test("Recovery Classification maps the readiness error to tool-unavailable → retry", () => {
+    const recovery = classifyFailure({ error: new Error(readinessError), unitType: "run-uat", unitId: "M001" });
+    assert.equal(recovery.failureKind, "tool-unavailable");
+    assert.equal(recovery.action, "retry");
+    assert.equal(recovery.exitReason, "tool-unavailable");
+  });
+});