gsd-pi 2.82.0-dev.dfbc5f58f → 2.82.0-dev.e7a7f1ed5

package/src/resources/extensions/gsd/tests/remediation-completion-guard.test.ts

@@ -110,6 +110,49 @@ test("completing-milestone blocks when VALIDATION verdict is needs-attention (#5
   }
 });
 
+test("completing-milestone blocks when VALIDATION verdict is fail (#5920)", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-fail-verdict-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+
+  try {
+    writeFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md"),
+      [
+        "---",
+        "verdict: fail",
+        "---",
+        "",
+        "# Validation Report",
+        "",
+        "Blocking failures remain unresolved.",
+      ].join("\n"),
+    );
+
+    const ctx = {
+      mid: "M001",
+      midTitle: "Test Milestone",
+      basePath: base,
+      state: { phase: "completing-milestone" } as any,
+      prefs: {} as any,
+      session: undefined,
+    };
+
+    const result = await completingRule!.match(ctx);
+
+    assert.ok(result !== null, "rule should match");
+    assert.equal(result!.action, "stop", "should return stop action");
+    if (result!.action === "stop") {
+      assert.equal(result!.level, "warning", "should be warning level (pausable)");
+      assert.ok(
+        result!.reason.includes('verdict is "fail"'),
+        "reason should mention fail verdict",
+      );
+    }
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test("completing-milestone proceeds normally when VALIDATION verdict is pass (#2675 guard)", async () => {
   const base = mkdtempSync(join(tmpdir(), "gsd-remediation-"));
   mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });

package/src/resources/extensions/gsd/tests/run-uat-replay-cap.test.ts

@@ -36,7 +36,7 @@ function makeUatProject(): string {
   return base;
 }
 
-test("run-uat dispatch stops after three attempts without a verdict", async () => {
+test("run-uat dispatch skips after three attempts without a verdict", async () => {
   const basePath = makeUatProject();
   const rule = DISPATCH_RULES.find((r) => r.name === "run-uat (post-completion)");
   assert.ok(rule, "run-uat dispatch rule is registered");
@@ -58,8 +58,7 @@ test("run-uat dispatch stops after three attempts without a verdict", async () =
     }
 
     const capped = await rule.match(ctx as any);
-    assert.equal(capped?.action, "stop");
-    assert.match(capped?.reason ?? "", /dispatched 3 times/);
+    assert.equal(capped?.action, "skip");
     assert.equal(getUatCount(basePath, "M001", "S01"), 4);
   } finally {
     rmSync(basePath, { recursive: true, force: true });

package/src/resources/extensions/gsd/tests/smart-entry-routing.test.ts

@@ -0,0 +1,113 @@
+// GSD-2 — Smart entry routing behavior tests.
+// Verifies guided wizard choices resolve to the correct execution path.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  resolveActiveTaskChoiceRoute,
+  resolveGuidedExecuteLaunchMode,
+  type ActiveTaskChoice,
+  type ActiveTaskRoute,
+  type SmartEntryIsolationMode,
+} from "../smart-entry-routing.ts";
+
+test("guided execute route enters auto step bootstrap only for worktree isolation", () => {
+  const cases: Array<{
+    isolationMode: SmartEntryIsolationMode;
+    expectedRoute: ActiveTaskRoute;
+  }> = [
+    {
+      isolationMode: "worktree",
+      expectedRoute: {
+        kind: "auto-bootstrap",
+        verboseMode: false,
+        options: {
+          step: true,
+          milestoneLock: "M001",
+        },
+      },
+    },
+    {
+      isolationMode: "none",
+      expectedRoute: {
+        kind: "guided-dispatch",
+        unitType: "execute-task",
+      },
+    },
+    {
+      isolationMode: "branch",
+      expectedRoute: {
+        kind: "guided-dispatch",
+        unitType: "execute-task",
+      },
+    },
+  ];
+
+  for (const testCase of cases) {
+    assert.deepEqual(
+      resolveActiveTaskChoiceRoute({
+        choice: "execute",
+        isolationMode: testCase.isolationMode,
+        milestoneId: "M001",
+      }),
+      testCase.expectedRoute,
+    );
+  }
+});
+
+test("active task smart entry choices resolve to explicit routes", () => {
+  const cases: Array<{
+    choice: ActiveTaskChoice;
+    expectedRoute: ActiveTaskRoute;
+  }> = [
+    {
+      choice: "auto",
+      expectedRoute: {
+        kind: "auto-bootstrap",
+        verboseMode: false,
+      },
+    },
+    {
+      choice: "status",
+      expectedRoute: {
+        kind: "status",
+      },
+    },
+    {
+      choice: "milestone_actions",
+      expectedRoute: {
+        kind: "milestone-actions",
+      },
+    },
+  ];
+
+  for (const testCase of cases) {
+    assert.deepEqual(
+      resolveActiveTaskChoiceRoute({
+        choice: testCase.choice,
+        isolationMode: "worktree",
+        milestoneId: "M001",
+      }),
+      testCase.expectedRoute,
+    );
+  }
+});
+
+test("active task route rejects invalid choices from untyped callers", () => {
+  assert.throws(
+    () =>
+      resolveActiveTaskChoiceRoute({
+        choice: "not_yet" as ActiveTaskChoice,
+        isolationMode: "worktree",
+        milestoneId: "M001",
+      }),
+    /Invalid ActiveTaskChoice: not_yet/,
+  );
+});
+
+test("guided execute launch mode remains a small compatibility helper", () => {
+  assert.equal(resolveGuidedExecuteLaunchMode("worktree"), "auto-step");
+  assert.equal(resolveGuidedExecuteLaunchMode("none"), "guided-dispatch");
+  assert.equal(resolveGuidedExecuteLaunchMode("branch"), "guided-dispatch");
+});

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

@@ -4,7 +4,10 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 import { _withDetachedAutoKeepaliveForTest } from "../auto.ts";
-import { _scheduleAutoStartAfterIdleForTest } from "../guided-flow.ts";
+import {
+  _scheduleAutoStartAfterIdleForTest,
+  resolveGuidedExecuteLaunchMode,
+} from "../guided-flow.ts";
 
 const gsdDir = resolve(import.meta.dirname, "..");
 
@@ -64,6 +67,24 @@ test("bare /gsd stays in the foreground smart-entry flow (#5125 regression)", ()
   );
 });
 
+test("guided execute uses auto step bootstrap when worktree isolation is enabled", () => {
+  assert.equal(
+    resolveGuidedExecuteLaunchMode("worktree"),
+    "auto-step",
+    "guided execute must enter auto bootstrap so the milestone worktree is created before execution",
+  );
+  assert.equal(
+    resolveGuidedExecuteLaunchMode("none"),
+    "guided-dispatch",
+    "non-isolated projects can keep the foreground guided dispatch path",
+  );
+  assert.equal(
+    resolveGuidedExecuteLaunchMode("branch"),
+    "guided-dispatch",
+    "this regression fix is scoped to worktree isolation",
+  );
+});
+
 test("auto bootstrap validates blocked directories before touching .gsd migration state", () => {
   const autoSrc = readGsdFile("auto.ts");
   const autoStartSrc = readGsdFile("auto-start.ts");

package/src/resources/extensions/gsd/tests/state-reconciliation-drift.test.ts

@@ -544,7 +544,7 @@ test("ADR-017 (#5703): live worker lock is not cleared", async (t) => {
 
 // ─── #5704: unregistered-milestone drift ────────────────────────────────────
 
-test("ADR-017 (#5704): unregistered-milestone drift detected and DB row inserted", async (t) => {
+test("ADR-017 (#5704): unregistered-milestone drift fails closed without importing markdown", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-adr017-projmd-"));
   const milestoneDir = join(base, ".gsd", "milestones", "M042");
   mkdirSync(milestoneDir, { recursive: true });
@@ -571,20 +571,22 @@ test("ADR-017 (#5704): unregistered-milestone drift detected and DB row inserted
   // Pre-condition: filesystem has the milestone, DB does NOT.
   assert.equal(getMilestone("M042"), null, "pre: DB has no row for M042");
 
-  const result = await reconcileBeforeDispatch(base, {
-    invalidateStateCache: () => {},
-    deriveState: async () => makeState(),
-  });
-
-  assert.equal(result.ok, true);
-  assert.ok(getMilestone("M042"), "post: DB row inserted for M042");
-  const milestoneRepaired = result.repaired.find(
-    (d) => d.kind === "unregistered-milestone",
+  await assert.rejects(
+    reconcileBeforeDispatch(base, {
+      invalidateStateCache: () => {},
+      deriveState: async () => makeState(),
+    }),
+    (err: unknown) => {
+      assert.ok(err instanceof ReconciliationFailedError);
+      assert.match(String(err.message), /unregistered-milestone/);
+      assert.equal(err.failures[0]?.drift.kind, "unregistered-milestone");
+      assert.match(String(err.failures[0]?.cause), /M042/);
+      assert.match(String(err.failures[0]?.cause), /markdown projection/);
+      assert.match(String(err.failures[0]?.cause), /recovery\/migration/);
+      return true;
+    },
   );
-  assert.ok(milestoneRepaired, "repaired list should include the unregistered-milestone drift");
-  if (milestoneRepaired?.kind === "unregistered-milestone") {
-    assert.equal(milestoneRepaired.milestoneId, "M042");
-  }
+  assert.equal(getMilestone("M042"), null, "post: DB still has no row for M042");
 });
 
 test("ADR-017 (#5704): registered milestone (DB row present) → no drift", async (t) => {
@@ -627,13 +629,14 @@ test("ADR-017 (#5704): registered milestone (DB row present) → no drift", asyn
 
 // ─── #5705: roadmap-divergence drift ─────────────────────────────────────────
 
-test("ADR-017 (#5705): roadmap-divergence drift detected and DB depends synced", async (t) => {
+test("ADR-017 (#5705): roadmap-divergence re-renders projection without syncing depends into DB", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-adr017-roadmap-"));
   const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  const roadmapPath = join(milestoneDir, "M001-ROADMAP.md");
   mkdirSync(milestoneDir, { recursive: true });
   // ROADMAP.md declares S02 depends on [S01]
   writeFileSync(
-    join(milestoneDir, "M001-ROADMAP.md"),
+    roadmapPath,
     [
       "# M001: Test",
       "",
@@ -665,7 +668,12 @@ test("ADR-017 (#5705): roadmap-divergence drift detected and DB depends synced",
   });
 
   assert.equal(result.ok, true);
-  assert.deepEqual(getSlice("M001", "S02")?.depends, ["S01"], "post: DB depends matches ROADMAP.md");
+  assert.deepEqual(getSlice("M001", "S02")?.depends, [], "post: DB depends remains authoritative");
+  assert.match(
+    readFileSync(roadmapPath, "utf-8"),
+    /- \[ \] \*\*S02: Feature\*\* `risk:medium` `depends:\[\]`/,
+    "post: ROADMAP projection is regenerated from DB depends",
+  );
   const roadmapRepaired = result.repaired.find((d) => d.kind === "roadmap-divergence");
   assert.ok(roadmapRepaired, "repaired list should include the roadmap-divergence drift");
   if (roadmapRepaired?.kind === "roadmap-divergence") {
@@ -673,13 +681,14 @@ test("ADR-017 (#5705): roadmap-divergence drift detected and DB depends synced",
   }
 });
 
-test("ADR-017 (#5705): ROADMAP declares slice missing from DB → slice inserted and drift reported", async (t) => {
+test("ADR-017 (#5705): ROADMAP-only slice is removed from projection and not inserted into DB", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-adr017-roadmap-newslice-"));
   const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  const roadmapPath = join(milestoneDir, "M001-ROADMAP.md");
   mkdirSync(milestoneDir, { recursive: true });
   // ROADMAP.md declares S01 and S02; DB will only have S01.
   writeFileSync(
-    join(milestoneDir, "M001-ROADMAP.md"),
+    roadmapPath,
     [
       "# M001: Test",
       "",
@@ -710,10 +719,10 @@ test("ADR-017 (#5705): ROADMAP declares slice missing from DB → slice inserted
   });
 
   assert.equal(result.ok, true);
-  const s02 = getSlice("M001", "S02");
-  assert.ok(s02, "post: S02 inserted into DB after repair");
-  assert.equal(s02?.sequence, 2, "post: S02 sequence matches ROADMAP order");
-  assert.deepEqual(s02?.depends, ["S01"], "post: S02 depends matches ROADMAP");
+  assert.equal(getSlice("M001", "S02"), null, "post: S02 still has no DB row");
+  const rendered = readFileSync(roadmapPath, "utf-8");
+  assert.match(rendered, /- \[ \] \*\*S01: Foundation\*\*/);
+  assert.doesNotMatch(rendered, /S02: Feature/, "post: ROADMAP-only S02 removed from projection");
   const roadmapRepaired = result.repaired.find((d) => d.kind === "roadmap-divergence");
   assert.ok(roadmapRepaired, "repaired list should include the roadmap-divergence drift");
   if (roadmapRepaired?.kind === "roadmap-divergence") {
@@ -721,6 +730,93 @@ test("ADR-017 (#5705): ROADMAP declares slice missing from DB → slice inserted
   }
 });
 
+test("ADR-017 (#5705): ROADMAP sequence drift re-renders from DB order without mutating DB", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-adr017-roadmap-sequence-"));
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  const roadmapPath = join(milestoneDir, "M001-ROADMAP.md");
+  mkdirSync(milestoneDir, { recursive: true });
+  writeFileSync(
+    roadmapPath,
+    [
+      "# M001: Test",
+      "",
+      "**Vision:** Verify sequence drift",
+      "",
+      "## Slices",
+      "",
+      "- [ ] **S02: Feature** `risk:medium` `depends:[]`",
+      "- [ ] **S01: Foundation** `risk:medium` `depends:[]`",
+      "",
+    ].join("\n"),
+  );
+  t.after(() => {
+    try { closeDatabase(); } catch { /* noop */ }
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Foundation", status: "pending", risk: "medium", depends: [], demo: "", sequence: 1 });
+  insertSlice({ id: "S02", milestoneId: "M001", title: "Feature", status: "pending", risk: "medium", depends: [], demo: "", sequence: 2 });
+
+  const result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => makeState(),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(getSlice("M001", "S01")?.sequence, 1, "post: S01 DB sequence remains authoritative");
+  assert.equal(getSlice("M001", "S02")?.sequence, 2, "post: S02 DB sequence remains authoritative");
+  const rendered = readFileSync(roadmapPath, "utf-8");
+  assert.ok(
+    rendered.indexOf("S01: Foundation") < rendered.indexOf("S02: Feature"),
+    "post: ROADMAP projection follows DB sequence",
+  );
+  assert.ok(result.repaired.some((d) => d.kind === "roadmap-divergence"));
+});
+
+test("ADR-017 (#5705): ROADMAP checkbox drift re-renders from DB status without mutating DB", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-adr017-roadmap-checkbox-"));
+  const milestoneDir = join(base, ".gsd", "milestones", "M001");
+  const roadmapPath = join(milestoneDir, "M001-ROADMAP.md");
+  mkdirSync(milestoneDir, { recursive: true });
+  writeFileSync(
+    roadmapPath,
+    [
+      "# M001: Test",
+      "",
+      "**Vision:** Verify checkbox drift",
+      "",
+      "## Slices",
+      "",
+      "- [x] **S01: Foundation** `risk:medium` `depends:[]`",
+      "",
+    ].join("\n"),
+  );
+  t.after(() => {
+    try { closeDatabase(); } catch { /* noop */ }
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Foundation", status: "pending", risk: "medium", depends: [], demo: "", sequence: 1 });
+
+  const result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => makeState(),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(getSlice("M001", "S01")?.status, "pending", "post: DB status remains authoritative");
+  assert.match(
+    readFileSync(roadmapPath, "utf-8"),
+    /- \[ \] \*\*S01: Foundation\*\*/,
+    "post: ROADMAP checkbox reflects DB status",
+  );
+  assert.ok(result.repaired.some((d) => d.kind === "roadmap-divergence"));
+});
+
 test("ADR-017 (#5705): in-sync ROADMAP and DB → no roadmap-divergence drift", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-adr017-roadmap-clean-"));
   const milestoneDir = join(base, ".gsd", "milestones", "M001");

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

@@ -3,7 +3,7 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 
-import { isClosedStatus } from '../status-guards.ts';
+import { isClosedStatus, isFutureMilestoneStatus } from '../status-guards.ts';
 
 test('isClosedStatus: "complete" returns true', () => {
   assert.equal(isClosedStatus('complete'), true);
@@ -32,3 +32,15 @@ test('isClosedStatus: "active" returns false', () => {
 test('isClosedStatus: "" (empty string) returns false', () => {
   assert.equal(isClosedStatus(''), false);
 });
+
+test('isFutureMilestoneStatus includes future milestone aliases', () => {
+  assert.equal(isFutureMilestoneStatus('pending'), true);
+  assert.equal(isFutureMilestoneStatus('queued'), true);
+  assert.equal(isFutureMilestoneStatus('planned'), true);
+});
+
+test('isFutureMilestoneStatus excludes active and closed milestones', () => {
+  assert.equal(isFutureMilestoneStatus('active'), false);
+  assert.equal(isFutureMilestoneStatus('complete'), false);
+  assert.equal(isFutureMilestoneStatus('parked'), false);
+});

package/src/resources/extensions/gsd/tests/validate-milestone-stuck-guard.test.ts

@@ -162,7 +162,7 @@ describe("validate-milestone stuck-loop guard (#4094)", () => {
     assert.equal(pauseAutoMock.mock.callCount(), 0);
   });
 
-  test("continues when no VALIDATION file exists yet", async () => {
+  test("retries when no VALIDATION file exists yet", async () => {
     insertMilestone({ id: "M001" });
     insertSlice({ id: "S01", milestoneId: "M001", title: "Slice 1", status: "complete" });
 
@@ -173,7 +173,34 @@ describe("validate-milestone stuck-loop guard (#4094)", () => {
 
     const result = await runPostUnitVerification({ s, ctx, pi } as VerificationContext, pauseAutoMock);
 
-    assert.equal(result, "continue");
+    assert.equal(result, "retry");
+    assert.equal(pauseAutoMock.mock.callCount(), 0);
+    assert.ok(s.pendingVerificationRetry);
+    assert.equal(s.pendingVerificationRetry!.unitId, "M001");
+    assert.match(s.pendingVerificationRetry!.failureContext, /gsd_validate_milestone/);
+    assert.equal(s.pendingVerificationRetry!.attempt, 1);
+  });
+
+  test("retries when VALIDATION file exists but is empty", async () => {
+    insertMilestone({ id: "M001" });
+    insertSlice({ id: "S01", milestoneId: "M001", title: "Slice 1", status: "complete" });
+
+    const path = join(tempDir, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
+    writeFileSync(path, "", "utf-8");
+    invalidateAllCaches();
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const pauseAutoMock = mock.fn(async () => {});
+    const s = makeMockSession(tempDir, "validate-milestone", "M001");
+
+    const result = await runPostUnitVerification({ s, ctx, pi } as VerificationContext, pauseAutoMock);
+
+    assert.equal(result, "retry");
     assert.equal(pauseAutoMock.mock.callCount(), 0);
+    assert.ok(s.pendingVerificationRetry);
+    assert.equal(s.pendingVerificationRetry!.unitId, "M001");
+    assert.match(s.pendingVerificationRetry!.failureContext, /exists but is empty/);
+    assert.equal(s.pendingVerificationRetry!.attempt, 1);
   });
 });

package/src/resources/extensions/gsd/tests/workflow-mcp.test.ts

@@ -746,3 +746,21 @@ test("transport compatibility still blocks units whose MCP tools are not exposed
   assert.match(error ?? "", /requires secure_env_collect/);
   assert.match(error ?? "", /currently exposes only/);
 });
+
+test("transport compatibility accepts MCP-namespaced runtime tools", () => {
+  const error = getWorkflowTransportSupportError(
+    "claude-code",
+    ["gsd_summary_save"],
+    {
+      projectRoot: "/tmp/project",
+      env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
+      surface: "auto-mode",
+      unitType: "research-slice",
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+      activeTools: ["mcp__gsd-workflow__gsd_summary_save"],
+    },
+  );
+
+  assert.equal(error, null);
+});

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -18,6 +18,7 @@ export interface WorkflowCapabilityOptions {
   unitType?: string;
   authMode?: "apiKey" | "oauth" | "externalCli" | "none";
   baseUrl?: string;
+  activeTools?: string[];
 }
 
 const MCP_WORKFLOW_TOOL_SURFACE = new Set([
@@ -383,6 +384,15 @@ function hasAskUserQuestionsTool(activeTools: string[]): boolean {
   });
 }
 
+function hasRequiredTool(requiredTool: string, activeTools: string[]): boolean {
+  return activeTools.some((toolName) => {
+    if (toolName === requiredTool) return true;
+    if (!toolName.startsWith("mcp__")) return false;
+    const toolSeparator = toolName.indexOf("__", "mcp__".length);
+    return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === requiredTool;
+  });
+}
+
 function workflowMcpStructuredQuestionsOptIn(env: NodeJS.ProcessEnv = process.env): boolean {
   const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
   return value === "1" || value === "true";
@@ -423,8 +433,15 @@ export function getWorkflowTransportSupportError(
     return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: the GSD workflow MCP server is not configured or discoverable. Detected Claude Code model but no workflow MCP. Please run /gsd mcp init . from your project root. You can also configure GSD_WORKFLOW_MCP_COMMAND, build packages/mcp-server/dist/cli.js, or install gsd-mcp-server on PATH.`;
   }
 
-  const missing = [...new Set(requiredTools)].filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
+  const uniqueRequired = [...new Set(requiredTools)];
+  const missing = (options.activeTools && options.activeTools.length > 0)
+    ? uniqueRequired.filter((tool) => !hasRequiredTool(tool, options.activeTools!))
+    : uniqueRequired.filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
   if (missing.length === 0) return null;
 
+  if (options.activeTools && options.activeTools.length > 0) {
+    return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the active runtime toolset currently exposes only ${options.activeTools.slice().sort().join(", ")}.`;
+  }
+
   return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the workflow MCP transport currently exposes only ${Array.from(MCP_WORKFLOW_TOOL_SURFACE).sort().join(", ")}.`;
 }