@opengsd/gsd-pi 1.2.0-dev.9ad8ae33 → 1.2.0-dev.a6376d75

package/src/resources/extensions/gsd/tests/phases-terminal-complete-idempotent.test.ts

@@ -30,7 +30,7 @@
  */
 
 import { createTestContext } from "./test-helpers.ts";
-import { runPreDispatch } from "../auto/phases.ts";
+import { runPreDispatch } from "../auto/pre-dispatch.ts";
 import {
   openDatabase,
   closeDatabase,

package/src/resources/extensions/gsd/tests/plan-gate-failed-doctor-heal-hint.test.ts

@@ -18,12 +18,12 @@ function readSrc(file: string): string {
   return readFileSync(join(gsdDir, file), "utf-8");
 }
 
-test("#4620: auto/phases plan gate failed message includes doctor heal hint", () => {
-  const src = readSrc("auto/phases.ts");
+test("#4620: auto/pre-dispatch plan gate failed message includes doctor heal hint", () => {
+  const src = readSrc("auto/pre-dispatch.ts");
   assert.match(
     src,
     /Plan gate failed-closed:[\s\S]*\/gsd doctor heal/,
-    "auto/phases.ts should include /gsd doctor heal in plan gate failed notification",
+    "auto/pre-dispatch.ts should include /gsd doctor heal in plan gate failed notification",
   );
 });
 

package/src/resources/extensions/gsd/tests/prompt-contracts.test.ts

@@ -55,14 +55,20 @@ const PHASE_PROMPT_TOOL_CALLS: Record<string, readonly string[]> = {
   "plan-slice": ["gsd_reassess_roadmap", "gsd_plan_slice", "gsd_decision_save"],
   "refine-slice": ["gsd_plan_slice", "gsd_decision_save"],
   "replan-slice": ["gsd_replan_slice"],
-  "execute-task": ["gsd_task_complete"],
+  "execute-task": [
+    "gsd_task_complete",
+    "gsd_exec",
+    "gsd_exec_search",
+    "gsd_resume",
+    "gsd_capture_thought",
+  ],
   "reactive-execute": ["gsd_summary_save"],
   "complete-slice": [
     "gsd_exec",
     "gsd_task_reopen",
     "gsd_replan_slice",
     "gsd_requirement_update",
-    "capture_thought",
+    "gsd_capture_thought",
     "gsd_slice_complete",
     "gsd_summary_save",
   ],
@@ -240,6 +246,8 @@ test("workflow-start prompt defaults to autonomy instead of per-phase confirmati
   const prompt = readPrompt("workflow-start");
   assert.match(prompt, /Keep moving by default/i);
   assert.match(prompt, /Decision gates, not ceremony/i);
+  assert.match(prompt, /Persist workflow state/i);
+  assert.match(prompt, /completedAt/i);
   assert.doesNotMatch(prompt, /confirm with the user before proceeding/i);
   assert.doesNotMatch(prompt, /Gate between phases/i);
 });

package/src/resources/extensions/gsd/tests/provider-errors.test.ts

@@ -17,10 +17,8 @@ import {
   shouldDeferTransientErrorToCoreRetry,
   suppressTerminalDeletedWorktreeMessageEnd,
 } from "../bootstrap/agent-end-recovery.ts";
-import {
-  _buildCancelledUnitStopReason,
-  _classifyZeroToolProviderMessageForTest,
-} from "../auto/phases.ts";
+import { _buildCancelledUnitStopReason } from "../auto/phase-helpers.ts";
+import { _classifyZeroToolProviderMessageForTest } from "../auto/unit-phase.ts";
 import { autoSession } from "../auto-runtime-state.ts";
 import { getNextFallbackModel } from "../preferences.ts";
 // Zero-import module — imported by path rather than through the package

package/src/resources/extensions/gsd/tests/remote-notification-from-desktop.test.ts

@@ -5,103 +5,53 @@
  * as a fire-and-forget side-effect so that Telegram/Slack/Discord channels
  * receive the same events as native desktop notifications.
  *
- * Testing strategy (structural analysis):
- *   node:test does not support mock.module without --experimental-test-module-mocks,
- *   so we use the same source-code structural approach established in this codebase
- *   (see session-start-footer.test.ts). We read notifications.ts and assert that:
- *     1. It imports sendRemoteNotification from the remote-questions/notify module.
- *     2. The sendDesktopNotification function body calls sendRemoteNotification
- *        with title and message as arguments.
- *     3. The call uses the void fire-and-forget pattern with a .catch(() => {})
- *        suppressor so that async failures never break the synchronous caller.
+ * Testing strategy (behavioral):
+ *   Import sendDesktopNotification and the swappable remoteNotificationDispatcher.
+ *   Mock the dispatcher's send method, call sendDesktopNotification, and assert
+ *   that the dispatcher received the same title/message and that the call is
+ *   fire-and-forget (the function returns without awaiting).
  *
  * Relates to #4341.
  */
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const SOURCE = readFileSync(join(__dirname, "..", "notifications.ts"), "utf-8");
+import {
+  sendDesktopNotification,
+  remoteNotificationDispatcher,
+} from "../notifications.js";
 
-test("notifications.ts imports sendRemoteNotification from remote-questions/notify", () => {
-  const hasImport =
-    SOURCE.includes('from "../remote-questions/notify.js"') ||
-    SOURCE.includes("from '../remote-questions/notify.js'");
-  assert.ok(
-    hasImport,
-    "notifications.ts must import from '../remote-questions/notify.js'",
-  );
-
-  const importLine = SOURCE.split("\n").find(
-    (line) =>
-      line.includes("sendRemoteNotification") &&
-      (line.includes("remote-questions/notify") || line.includes("remote-questions/notify.js")),
-  );
-  assert.ok(
-    importLine,
-    "The import statement must include sendRemoteNotification from the remote-questions/notify module",
-  );
-});
-
-test("sendDesktopNotification calls sendRemoteNotification(title, message)", () => {
-  // Extract the body of sendDesktopNotification — from its opening brace to the
-  // closing brace at the same indentation level.
-  const fnStart = SOURCE.indexOf("export function sendDesktopNotification(");
-  assert.ok(fnStart > -1, "sendDesktopNotification must be present in notifications.ts");
+test("sendDesktopNotification calls sendRemoteNotification with title and message", async (t) => {
+  const sendMock = t.mock.method(remoteNotificationDispatcher, "send", async () => {});
 
-  // Find the next exported function/const after sendDesktopNotification to bound the search.
-  const nextExportIdx = SOURCE.indexOf("\nexport ", fnStart + 1);
-  const fnBody = nextExportIdx > -1 ? SOURCE.slice(fnStart, nextExportIdx) : SOURCE.slice(fnStart);
-
-  assert.ok(
-    fnBody.includes("sendRemoteNotification"),
-    "sendDesktopNotification must call sendRemoteNotification",
-  );
+  sendDesktopNotification("Test Title", "Test Message");
 
-  assert.ok(
-    fnBody.includes("sendRemoteNotification(title") || fnBody.includes("sendRemoteNotification(title,"),
-    "sendRemoteNotification must be called with title as first argument",
-  );
+  assert.equal(sendMock.mock.callCount(), 1);
+  assert.deepEqual(sendMock.mock.calls[0].arguments, ["Test Title", "Test Message"]);
 });
 
-test("sendRemoteNotification is invoked as void fire-and-forget with .catch(() => {})", () => {
-  const fnStart = SOURCE.indexOf("export function sendDesktopNotification(");
-  const nextExportIdx = SOURCE.indexOf("\nexport ", fnStart + 1);
-  const fnBody = nextExportIdx > -1 ? SOURCE.slice(fnStart, nextExportIdx) : SOURCE.slice(fnStart);
+test("sendDesktopNotification does not await the remote notification", async (t) => {
+  const sendMock = t.mock.method(remoteNotificationDispatcher, "send", async () => {});
 
-  assert.ok(
-    fnBody.includes("void sendRemoteNotification("),
-    "sendRemoteNotification must be called with void (fire-and-forget)",
-  );
+  const result = sendDesktopNotification("Async Title", "Async Message");
 
-  assert.ok(
-    fnBody.includes(".catch("),
-    "sendRemoteNotification call must be followed by .catch() to suppress unhandled-rejection warnings",
-  );
+  assert.equal(result, undefined, "sendDesktopNotification must return void");
+  assert.equal(sendMock.mock.callCount(), 1);
 });
 
-test("sendRemoteNotification call appears before shouldSendDesktopNotification guard", () => {
-  // Regression guard for the HIGH-severity bug where remote notifications were
-  // gated behind the desktop-notification preference check. Users who disable
-  // desktop notifications must still receive Telegram/Slack/Discord messages.
-  const fnStart = SOURCE.indexOf("export function sendDesktopNotification(");
-  assert.ok(fnStart > -1, "sendDesktopNotification must be present in notifications.ts");
-
-  const nextExportIdx = SOURCE.indexOf("\nexport ", fnStart + 1);
-  const fnBody = nextExportIdx > -1 ? SOURCE.slice(fnStart, nextExportIdx) : SOURCE.slice(fnStart);
+test("sendDesktopNotification fires remote notification even when desktop notifications are disabled", async (t) => {
+  const sendMock = t.mock.method(remoteNotificationDispatcher, "send", async () => {});
 
-  const remoteCallIdx = fnBody.indexOf("sendRemoteNotification(");
-  const guardIdx = fnBody.indexOf("shouldSendDesktopNotification(");
-
-  assert.ok(remoteCallIdx > -1, "sendRemoteNotification must be called inside sendDesktopNotification");
-  assert.ok(guardIdx > -1, "shouldSendDesktopNotification guard must be present inside sendDesktopNotification");
-
-  assert.ok(
-    remoteCallIdx < guardIdx,
-    `sendRemoteNotification (pos ${remoteCallIdx}) must appear BEFORE the shouldSendDesktopNotification guard (pos ${guardIdx}) so that remote channels fire even when desktop notifications are disabled`,
+  sendDesktopNotification(
+    "Remote Title",
+    "Remote Message",
+    "info",
+    "complete",
+    undefined,
+    { notifications: { enabled: false } },
   );
+
+  assert.equal(sendMock.mock.callCount(), 1);
+  assert.deepEqual(sendMock.mock.calls[0].arguments, ["Remote Title", "Remote Message"]);
 });

package/src/resources/extensions/gsd/tests/runtime-invariant-modules.test.ts

@@ -67,7 +67,13 @@ test("Tool Contract compiles known Unit prompt and tool policy", () => {
 
   assert.equal(result.ok, true);
   assert.equal(result.ok && result.contract.unitType, "execute-task");
-  assert.deepEqual(result.ok && result.contract.requiredWorkflowTools, ["gsd_task_complete"]);
+  assert.deepEqual(result.ok && result.contract.requiredWorkflowTools, [
+    "gsd_task_complete",
+    "gsd_exec",
+    "gsd_exec_search",
+    "gsd_resume",
+    "gsd_capture_thought",
+  ]);
   assert.deepEqual(result.ok && result.contract.forbiddenWorkflowTools, []);
   assert.equal(result.ok && result.contract.toolsPolicy.mode, "all");
   assert.ok(result.ok && result.contract.validationRules.includes("closeout-tool-present"));

package/src/resources/extensions/gsd/tests/skill-activation.test.ts

@@ -92,14 +92,14 @@ test("buildSkillActivationBlock activates skills via prefer_skills when context
       prefer_skills: ["react"],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'react' \}\)/);
+    assert.match(result, /Read the installed 'react' skill file from <available_skills>/);
     assert.doesNotMatch(result, /swiftui/);
   } finally {
     cleanup(base);
   }
 });
 
-test("buildSkillActivationBlock includes always_use_skills from preferences using exact Skill tool format", () => {
+test("buildSkillActivationBlock includes always_use_skills using read-based skill loading", () => {
   const base = makeTempBase();
   try {
     writeSkill(base, "swift-testing", "Use for Swift Testing assertions and verification patterns.");
@@ -109,7 +109,10 @@ test("buildSkillActivationBlock includes always_use_skills from preferences usin
       always_use_skills: ["swift-testing"],
     });
 
-    assert.equal(result, "<skill_activation>Call Skill({ skill: 'swift-testing' }).</skill_activation>");
+    assert.equal(
+      result,
+      "<skill_activation>Read the installed 'swift-testing' skill file from <available_skills>.</skill_activation>",
+    );
   } finally {
     cleanup(base);
   }
@@ -137,8 +140,8 @@ test("buildSkillActivationBlock includes skill_rules matches and task-plan skill
       skill_rules: [{ when: "prisma database schema", use: ["prisma"] }],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'accessibility' \}\)/);
-    assert.match(result, /Call Skill\(\{ skill: 'prisma' \}\)/);
+    assert.match(result, /Read the installed 'accessibility' skill file from <available_skills>/);
+    assert.match(result, /Read the installed 'prisma' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -160,7 +163,7 @@ test("buildSkillActivationBlock matches skill_rules against exact unit type cont
       ],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'complete-slice-policies' \}\)/);
+    assert.match(result, /Read the installed 'complete-slice-policies' skill file from <available_skills>/);
     assert.doesNotMatch(result, /slice-broad/);
   } finally {
     cleanup(base);
@@ -264,8 +267,8 @@ test("buildSkillActivationBlock allows valid skill names and rejects invalid one
     });
 
     assert.match(result, /skill_activation/);
-    assert.match(result, /Call Skill\(\{ skill: 'react' \}\)/);
-    assert.match(result, /Call Skill\(\{ skill: 'good-skill-2' \}\)/);
+    assert.match(result, /Read the installed 'react' skill file from <available_skills>/);
+    assert.match(result, /Read the installed 'good-skill-2' skill file from <available_skills>/);
     assert.doesNotMatch(result, /bad'name/);
   } finally {
     cleanup(base);
@@ -289,8 +292,8 @@ test("buildSkillActivationBlock: explicit always_use_skills bypass the unit-type
       always_use_skills: ["write-docs", "swiftui"],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'write-docs' \}\)/);
-    assert.match(result, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(result, /Read the installed 'write-docs' skill file from <available_skills>/);
+    assert.match(result, /Read the installed 'swiftui' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -307,7 +310,7 @@ test("buildSkillActivationBlock falls through to all skills for unknown unit typ
     });
 
     // Unknown unit type = wildcard fallback (pre-manifest behavior).
-    assert.match(result, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(result, /Read the installed 'swiftui' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -324,7 +327,7 @@ test("buildSkillActivationBlock without unitType preserves pre-manifest behavior
       always_use_skills: ["swiftui"],
     });
 
-    assert.match(result, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(result, /Read the installed 'swiftui' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -341,12 +344,12 @@ test("milestone prompt builders propagate always_use_skills through buildSkillAc
     loadOnlyTestSkills(base);
 
     const researchPrompt = await buildResearchMilestonePrompt("M001", "Test", base);
-    assert.match(researchPrompt, /Call Skill\(\{ skill: 'write-docs' \}\)/);
-    assert.match(researchPrompt, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(researchPrompt, /Read the installed 'write-docs' skill file from <available_skills>/);
+    assert.match(researchPrompt, /Read the installed 'swiftui' skill file from <available_skills>/);
 
     const planPrompt = await buildPlanMilestonePrompt("M001", "Test", base);
-    assert.match(planPrompt, /Call Skill\(\{ skill: 'write-docs' \}\)/);
-    assert.match(planPrompt, /Call Skill\(\{ skill: 'swiftui' \}\)/);
+    assert.match(planPrompt, /Read the installed 'write-docs' skill file from <available_skills>/);
+    assert.match(planPrompt, /Read the installed 'swiftui' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }
@@ -377,7 +380,7 @@ test("complete-slice prompt propagates always_use_skills through buildSkillActiv
 
     const prompt = await buildCompleteSlicePrompt("M001", "Test", "S01", "Slice", base);
 
-    assert.match(prompt, /Call Skill\(\{ skill: 'write-docs' \}\)/);
+    assert.match(prompt, /Read the installed 'write-docs' skill file from <available_skills>/);
   } finally {
     cleanup(base);
   }

package/src/resources/extensions/gsd/tests/start-auto-detached.test.ts

@@ -339,7 +339,7 @@ test("resume path only hard-exits on blocked stop, not blocked pause (#6154)", (
   );
 });
 
-test("prepareForUnit skips worktree safety when isolation is not worktree (#6154)", () => {
+test("prepareForUnit enforces worktree safety for all isolation modes (#6154)", () => {
   const orchSrc = readGsdFile("auto/orchestrator.ts");
   const prepareForUnitIdx = orchSrc.indexOf("private async prepareWorktreeForUnit(");
   const prepareForUnitBody = orchSrc.slice(prepareForUnitIdx, orchSrc.indexOf("private classifyAndRecover(", prepareForUnitIdx));
@@ -350,8 +350,12 @@ test("prepareForUnit skips worktree safety when isolation is not worktree (#6154
     "prepareForUnit should resolve the effective isolation mode once",
   );
   assert.ok(
-    prepareForUnitBody.includes('if (isolationMode !== "worktree")'),
-    "prepareForUnit should bypass worktree safety validation outside worktree isolation mode",
+    prepareForUnitBody.includes('const writeScope ='),
+    "prepareForUnit should classify the unit's write scope before validating",
+  );
+  assert.ok(
+    !prepareForUnitBody.includes('if (isolationMode !== "worktree")'),
+    "prepareForUnit must not bypass worktree safety outside worktree isolation mode",
   );
 });
 

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/token-tool-gating.test.ts

@@ -365,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"));
 });
@@ -387,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"));
@@ -395,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", () => {

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

@@ -4,7 +4,8 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 
-import { getToolSurfaceReadinessError } from "../tool-surface-readiness.ts";
+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";
@@ -58,18 +59,82 @@ describe("getToolSurfaceReadinessError", () => {
     assert.match(error, /gsd_uat_exec/);
   });
 
-  test("passes a still-connecting (pending) server through instead of aborting", () => {
-    // The SDK reports still-connecting servers as "pending" at init — the
-    // common healthy session. A genuine miss after pass-through is caught
-    // in-session ("No such tool available" → tool-unavailable → retry).
+  test("still blocks pending init when required tools are absent from the live surface", () => {
     const error = getToolSurfaceReadinessError({
-      unitType: "plan-slice",
+      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",
@@ -82,7 +147,7 @@ describe("getToolSurfaceReadinessError", () => {
     assert.equal(error, null);
   });
 
-  test("reports the failed server and the missing tools when the surface never registered", () => {
+  test("reports the failed server as terminal", () => {
     const error = getToolSurfaceReadinessError({
       unitType: "run-uat",
       workflowServerName: SERVER,
@@ -90,7 +155,20 @@ describe("getToolSurfaceReadinessError", () => {
     });
     assert.ok(error, "expected a readiness error");
     assert.match(error, /workflow tool surface not ready for run-uat/);
-    assert.match(error, /status is "failed"/);
+    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/);
   });
 
@@ -101,7 +179,7 @@ describe("getToolSurfaceReadinessError", () => {
       observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "needs-auth" }] },
     });
     assert.ok(error, "expected a readiness error for needs-auth");
-    assert.match(error, /status is "needs-auth"/);
+    assert.match(error, /terminal/);
   });
 
   test("aborts on disabled (terminal — cannot self-heal)", () => {
@@ -111,7 +189,7 @@ describe("getToolSurfaceReadinessError", () => {
       observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "disabled" }] },
     });
     assert.ok(error, "expected a readiness error for disabled");
-    assert.match(error, /status is "disabled"/);
+    assert.match(error, /terminal/);
   });
 
   test("reports partially-registered surfaces even when the server says connected", () => {
@@ -128,6 +206,102 @@ describe("getToolSurfaceReadinessError", () => {
     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", () => {