@opengsd/gsd-pi 1.5.0-dev.4fb2d460 → 1.5.0-dev.c4c8885f

package/src/resources/extensions/browser-tools/tests/gsd-browser-launch-config.test.mjs

@@ -55,6 +55,31 @@ describe("resolveGsdBrowserMcpLaunchConfig identity flags", () => {
     assert.equal(args[1], "mcp");
   });
 
+  it("appends GSD_BROWSER_MCP_EXTRA_ARGS after the identity flags (string form)", () => {
+    const { args } = resolveGsdBrowserMcpLaunchConfig("/tmp/example-project", {
+      GSD_BROWSER_MCP_EXTRA_ARGS: "--stealth --browser-path /usr/bin/chromium",
+    });
+
+    // Managed flags stay intact and the extra flags trail them.
+    assert.ok(args.indexOf("--identity-project") >= 0);
+    assert.deepEqual(args.slice(-3), ["--stealth", "--browser-path", "/usr/bin/chromium"]);
+    assert.ok(args.indexOf("--stealth") > args.indexOf("--identity-project"));
+  });
+
+  it("accepts GSD_BROWSER_MCP_EXTRA_ARGS as a JSON array", () => {
+    const { args } = resolveGsdBrowserMcpLaunchConfig("/tmp/example-project", {
+      GSD_BROWSER_MCP_EXTRA_ARGS: '["--stealth"]',
+    });
+    assert.equal(args[args.length - 1], "--stealth");
+  });
+
+  it("forwards GSD_BROWSER_MCP_EXTRA_ARGS to the daemon-start invocation", () => {
+    const env = { GSD_BROWSER_MCP_EXTRA_ARGS: "--stealth" };
+    const daemon = resolveGsdBrowserDaemonStartInvocation("/tmp/example-project", env);
+    assert.equal(daemon.args[daemon.args.length - 1], "--stealth");
+    assert.ok(daemon.args.indexOf("daemon") >= 0 && daemon.args.indexOf("start") >= 0);
+  });
+
   it("uses a path-safe identity-project identifier", () => {
     const { args } = resolveGsdBrowserMcpLaunchConfig("/tmp/example/project", {});
     const projectId = args[args.indexOf("--identity-project") + 1];

package/src/resources/extensions/browser-tools/tests/managed-gsd-browser-tools.test.mjs

@@ -4,6 +4,7 @@ import assert from "node:assert/strict";
 const {
   MANAGED_BROWSER_TOOL_SPECS,
   MANAGED_GSD_BROWSER_TOOL_NAMES,
+  ManagedGsdBrowserConnectionPool,
   findMissingContractCoverage,
   normalizeManagedArgs,
   registerManagedGsdBrowserTools,
@@ -29,6 +30,17 @@ const GSD_BROWSER_SERVED_TOOLS = [
   "browser_act",
 ];
 
+function makeLaunchConfig() {
+  return {
+    command: "gsd-browser",
+    args: ["mcp"],
+    cwd: "/tmp/example-project",
+    projectRoot: "/tmp/example-project",
+    serverName: "gsd-browser",
+    sessionName: "test-session",
+  };
+}
+
 describe("registerManagedGsdBrowserTools", () => {
   it("registers the curated Pi browser contract", () => {
     const tools = [];
@@ -72,6 +84,87 @@ describe("findMissingContractCoverage", () => {
   });
 });
 
+describe("ManagedGsdBrowserConnectionPool", () => {
+  it("closes a pending connection that resolves after the pool is closed", async () => {
+    const closed = [];
+    let resolveConnect;
+    const pool = new ManagedGsdBrowserConnectionPool(async () => {
+      return new Promise((resolve) => {
+        resolveConnect = resolve;
+      });
+    }, async (connection) => {
+      closed.push(connection.id);
+    });
+
+    const launch = makeLaunchConfig();
+
+    const pending = pool.getOrConnect(launch);
+    const closedPool = pool.closeAll();
+    resolveConnect({ id: "late-connection" });
+
+    await assert.rejects(
+      pending,
+      /closed during startup/,
+      "pending callers must not receive a reusable connection after close",
+    );
+    await closedPool;
+
+    assert.deepEqual(closed, ["late-connection"]);
+    assert.equal(pool.activeCount, 0);
+    assert.equal(pool.pendingCount, 0);
+  });
+
+  it("aborts pending connection attempts when the pool is closed", async () => {
+    let receivedSignal;
+    const pool = new ManagedGsdBrowserConnectionPool(async (_launch, signal) => {
+      receivedSignal = signal;
+      return new Promise((_resolve, reject) => {
+        signal.addEventListener("abort", () => reject(new Error("connect aborted")), { once: true });
+      });
+    }, async () => {});
+
+    const pending = pool.getOrConnect(makeLaunchConfig());
+    const closedPool = pool.closeAll();
+
+    await assert.rejects(pending, /connect aborted/);
+    await closedPool;
+
+    assert.equal(receivedSignal?.aborted, true);
+    assert.equal(pool.activeCount, 0);
+    assert.equal(pool.pendingCount, 0);
+  });
+
+  it("rejects new connection attempts started while the pool is closing", async () => {
+    let resolveConnect;
+    let connectCount = 0;
+    const pool = new ManagedGsdBrowserConnectionPool(async () => {
+      connectCount += 1;
+      return new Promise((resolve) => {
+        resolveConnect = resolve;
+      });
+    }, async () => {});
+
+    const pending = pool.getOrConnect(makeLaunchConfig());
+    const closedPool = pool.closeAll();
+
+    // A caller that arrives during the in-flight closeAll must not open a new
+    // connection that could survive shutdown.
+    await assert.rejects(
+      pool.getOrConnect(makeLaunchConfig()),
+      /closing/,
+      "getOrConnect must reject while the pool is closing",
+    );
+
+    resolveConnect({ id: "pending-connection" });
+    await assert.rejects(pending, /closed during startup/);
+    await closedPool;
+
+    assert.equal(connectCount, 1, "no second connection is started during shutdown");
+    assert.equal(pool.activeCount, 0);
+    assert.equal(pool.pendingCount, 0);
+  });
+});
+
 describe("contract tool translations", () => {
   it("translates browser_click into a single-step batch call", () => {
     const calls = MANAGED_BROWSER_TOOL_SPECS.browser_click.translate.build({ selector: "#save" });

package/src/resources/extensions/gsd/activity-log.ts

@@ -138,7 +138,7 @@ export function saveActivityLog(
     state.nextSeq += 1;
     state.lastSnapshotKeyByUnit.set(unitKey, key);
 
-    if (isUnifiedAuditEnabled()) {
+    if (isUnifiedAuditEnabled(basePath)) {
       emitUokAuditEvent(
         basePath,
         buildAuditEnvelope({

package/src/resources/extensions/gsd/auto/orchestrator.ts

@@ -1196,17 +1196,23 @@ export class AutoOrchestrator implements AutoOrchestrationModule {
         return skipped;
       }
 
-      // Stuck-loop detection: when the window is saturated with copies of
-      // `nextKey` (count >= STUCK_WINDOW_SIZE), consult the Dispatch History
-      // module's full detect-stuck rule set for the verdict instead of the old
-      // bare saturation count. This keeps the saturation threshold (the window
-      // deliberately records benign idempotent repeats, so earlier-firing
-      // rules would false-positive on pause/resume re-advances) while gaining
-      // retry-budget suppression and diagnosable rule reasons. A saturated
-      // window with no verdict means the dispatch ledger says we are inside
-      // the unit's retry-backoff budget — let the retry proceed.
-      const stuckVerdict =
-        matchingCount >= STUCK_WINDOW_SIZE ? this.dispatchHistory.detectStuck() : null;
+      // Stuck-loop detection: consult the Dispatch History module's full
+      // detect-stuck rule set once the window is *full* — not only when a
+      // single key saturates it. Gating on a single key's saturation count
+      // (matchingCount >= STUCK_WINDOW_SIZE) let two-unit oscillations slip
+      // through forever: an execute-task ↔ complete-slice loop (a slice gate
+      // that keeps reopening the same task, #1225) fills the window with two
+      // alternating keys, so neither key ever reaches the saturation count and
+      // detect-stuck's oscillation/repeat rules were never even invoked. Firing
+      // on window saturation instead covers both shapes. Consecutive same-key
+      // re-advances (the benign pause/resume churn the old count gate guarded
+      // against) are already short-circuited above by the idempotency skip, and
+      // legitimate retry backoff is still suppressed inside detect-stuck via the
+      // dispatch ledger — a saturated window with no verdict means we are inside
+      // the unit's retry-backoff budget, so let the retry proceed.
+      const windowSaturated =
+        this.dispatchHistory.getRecentWindow().length >= STUCK_WINDOW_SIZE;
+      const stuckVerdict = windowSaturated ? this.dispatchHistory.detectStuck() : null;
       if (stuckVerdict) {
         // #442: before declaring a stuck loop, verify the unit didn't actually
         // complete on disk (stale DB) and recover if so — legacy graduated

package/src/resources/extensions/gsd/auto-artifact-paths.ts

@@ -19,6 +19,7 @@ import {
   resolveSlicePath,
   resolveTasksDir,
   dirIsMetaOnlyLegacyMilestone,
+  normalizeRealPath,
 } from "./paths.js";
 import { milestoneIdToPhaseNum } from "./layout-policy.js";
 import { parseUnitId } from "./unit-id.js";
@@ -354,7 +355,7 @@ export function resolveSliceResearchLocation(
   if (canonicalPath && existsSync(canonicalPath)) {
     return {
       absolutePath: canonicalPath,
-      relativePath: relative(basePath, canonicalPath),
+      relativePath: relative(normalizeRealPath(basePath), canonicalPath),
     };
   }
 

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -79,9 +79,10 @@ import {
   buildGateEvaluatePrompt,
   buildParallelResearchSlicesPrompt,
   checkNeedsReassessment,
-  checkNeedsRunUat,
+  loadRoadmapCompletedSliceCandidates,
 } from "./auto-prompts.js";
-import { resolveModelWithFallbacksForUnit, resolveThinkingLevelForUnit } from "./preferences-models.js";
+import { checkNeedsRunUat } from "./uat-dispatch.js";
+import { normalizeModelFieldConfig, resolveModelWithFallbacksForUnit, resolveThinkingLevelForUnit } from "./preferences-models.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { selectReactiveDispatchBatch } from "./uok/execution-graph.js";
 import { getMilestonePipelineVariant } from "./milestone-scope-classifier.js";
@@ -308,12 +309,21 @@ export async function readUatGateVerdict(
       return null;
     }
 
-    const assessmentVerdict = extractVerdict(assessmentContent);
-    if (assessmentVerdict) {
-      return {
-        verdict: assessmentVerdict,
-        uatType: uatType ?? extractUatType(assessmentContent),
-      };
+    // Backfilled assessments (#1258) are placeholders created during milestone
+    // validation for completed slices that never produced a real UAT ASSESSMENT
+    // (e.g. artifact-driven UAT that was never dispatched). Their fabricated
+    // verdict must not be treated as a genuine UAT sign-off — otherwise "never
+    // checked" is silently read as "passed". Skip the placeholder and fall
+    // through to the authoritative run-uat DB row (which stays null unless a
+    // real UAT was actually recorded).
+    if (assessmentScope !== BACKFILL_ASSESSMENT_SCOPE) {
+      const assessmentVerdict = extractVerdict(assessmentContent);
+      if (assessmentVerdict) {
+        return {
+          verdict: assessmentVerdict,
+          uatType: uatType ?? extractUatType(assessmentContent),
+        };
+      }
     }
   }
 
@@ -489,17 +499,28 @@ function stripGsdPrefix(path: string): string {
   return path.startsWith(".gsd/") ? path.slice(".gsd/".length) : path;
 }
 
+// Scope marker for assessments fabricated by the milestone-validation backfill
+// (#1258). It keeps these placeholders distinguishable from genuine `run-uat`
+// sign-offs so `readUatGateVerdict` never mistakes "never checked" for "passed".
+const BACKFILL_ASSESSMENT_SCOPE = "backfill";
+
 function persistSliceAssessmentBackfill(
   assessmentRelPath: string,
   mid: string,
   sliceId: string,
   content: string,
+  fabricated: boolean,
 ): void {
   const artifactPath = stripGsdPrefix(assessmentRelPath);
   const existingAssessment =
     getAssessment(assessmentRelPath) ??
     getAssessment(artifactPath);
-  const scope = stringField(existingAssessment, "scope") ?? "run-uat";
+  // A newly fabricated placeholder is filed under a distinct scope; a pre-existing
+  // on-disk ASSESSMENT keeps its real scope (default `run-uat`) so genuine
+  // sign-offs are still honored.
+  const scope = fabricated
+    ? BACKFILL_ASSESSMENT_SCOPE
+    : stringField(existingAssessment, "scope") ?? "run-uat";
   const status = stringField(existingAssessment, "status") ??
     extractVerdict(content)?.toLowerCase() ??
     "unknown";
@@ -548,19 +569,25 @@ function backfillMissingAssessmentsFromSummaries(basePath: string, mid: string):
       "---",
       `sliceId: ${sliceId}`,
       "verdict: PASS",
+      // Distinguishing marker (#1258): this ASSESSMENT was fabricated to satisfy
+      // the per-slice artifact requirement, NOT produced by a real UAT run. It
+      // must not be read as a genuine UAT sign-off.
+      "backfilled: true",
+      "verified: false",
       `date: ${now}`,
       "---",
       "",
       `# Assessment — ${sliceId}`,
       "",
       "Auto-created during milestone validation because this completed slice had a SUMMARY but no ASSESSMENT artifact.",
+      "This is a placeholder: no UAT was executed for this slice, so its verdict is not an independent sign-off.",
       "No additional reassessment changes were detected in this backfill step.",
       "",
     ].join("\n") : readFileSync(assessmentPath, "utf-8");
 
     if (isDbAvailable()) {
       try {
-        persistSliceAssessmentBackfill(assessmentRelPath, mid, sliceId, content);
+        persistSliceAssessmentBackfill(assessmentRelPath, mid, sliceId, content, didCreateAssessment);
       } catch (err) {
         logWarning("dispatch", `failed to backfill assessment DB rows for ${mid}/${sliceId}: ${(err as Error).message}`);
       }
@@ -769,7 +796,12 @@ export const DISPATCH_RULES: DispatchRule[] = [
       registeredTools,
       sessionBaseUrl,
     }) => {
-      const needsRunUat = await checkNeedsRunUat(basePath, mid, state, prefs);
+      const needsRunUat = await checkNeedsRunUat(
+        basePath,
+        mid,
+        prefs,
+        await loadRoadmapCompletedSliceCandidates(basePath, mid),
+      );
       if (!needsRunUat) return null;
       const { sliceId, uatType } = needsRunUat;
 
@@ -1428,8 +1460,15 @@ export const DISPATCH_RULES: DispatchRule[] = [
       const sTitle = state.activeSlice.title;
       if (resolveSliceFile(basePath, mid, sid, "REACTIVE-BLOCKER")) return null;
       const maxParallel = reactiveConfig?.max_parallel ?? 2;
-      const subagentModel = reactiveConfig?.subagent_model ?? resolveModelWithFallbacksForUnit("subagent")?.primary;
-      const subagentThinking = resolveThinkingLevelForUnit("subagent");
+      // `subagent_model` accepts the phase-bucket object form (#1229); honor the
+      // full primary→fallbacks chain in the dispatch prompt (the reactive
+      // subagent model is embedded there rather than set as the session model).
+      const subagentModelConfig = normalizeModelFieldConfig(reactiveConfig?.subagent_model)
+        ?? resolveModelWithFallbacksForUnit("subagent");
+      const subagentModel = subagentModelConfig?.primary;
+      // Prefer the per-field `thinking` carried on `reactive_execution.subagent_model`'s
+      // object form over the phase-bucket `subagent` level (#1269).
+      const subagentThinking = subagentModelConfig?.thinking ?? resolveThinkingLevelForUnit("subagent");
       // Default-on safety threshold: only activate reactive dispatch when at
       // least N tasks are ready. Users who explicitly enabled reactive_execution
       // keep the legacy threshold of 2 (matches the prior "any parallelism is
@@ -1518,7 +1557,13 @@ export const DISPATCH_RULES: DispatchRule[] = [
             selected,
             basePath,
             subagentModel,
-            { sessionContextWindow, modelRegistry, sessionProvider, subagentThinking },
+            {
+              sessionContextWindow,
+              modelRegistry,
+              sessionProvider,
+              subagentThinking,
+              subagentModelFallbacks: subagentModelConfig?.fallbacks,
+            },
           ),
         };
       } catch (err) {

package/src/resources/extensions/gsd/auto-model-selection.ts

@@ -273,7 +273,7 @@ function buildModelPolicyBlockReasons(
   }];
 }
 
-function isModelUnavailable(
+export function isModelUnavailable(
   basePath: string,
   provider: string | undefined,
   id: string | undefined,
@@ -282,6 +282,38 @@ function isModelUnavailable(
     isModelTemporarilyUnavailable(basePath, provider, id);
 }
 
+/** Apply `auto_supervisor.model`, walking configured fallbacks on unavailability (#1229). */
+export async function applySupervisorModelIfConfigured(
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+  basePath: string,
+): Promise<void> {
+  const modelConfig = resolveModelWithFallbacksForUnit("supervisor", basePath);
+  if (!modelConfig) return;
+
+  const availableModels = ctx.modelRegistry.getAvailable();
+  for (const candidate of [modelConfig.primary, ...modelConfig.fallbacks]) {
+    const match = resolveModelId(candidate, availableModels, ctx.model?.provider);
+    if (!match) continue;
+    if (isModelUnavailable(basePath, match.provider, match.id)) continue;
+    try {
+      if (await pi.setModel(match, { persist: false })) {
+        // Prefer the per-field `thinking` from `auto_supervisor.model`'s object
+        // form over the session level so a configured supervisor level actually
+        // applies (#1269).
+        applyThinkingLevelForModel(pi, modelConfig.thinking ?? pi.getThinkingLevel(), match, ctx);
+        return;
+      }
+    } catch (err) {
+      // Non-fatal — try the next fallback.
+      logWarning(
+        "dispatch",
+        `supervisor model set failed for ${candidate}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+}
+
 function restoreToolBaseline(pi: ExtensionAPI): void {
   const key = pi as unknown as object;
   const baseline = TOOL_BASELINE.get(key);

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -30,6 +30,7 @@ import {
   relMilestoneFile,
   relSliceFile,
   relTaskFile,
+  normalizeRealPath,
 } from "./paths.js";
 import { invalidateAllCaches } from "./cache.js";
 import { rebuildState } from "./doctor.js";
@@ -960,7 +961,7 @@ function describeArtifactVerificationFailure(
   if (!artifactPath) {
     return `Artifact verification failed: ${unitType} "${unitId}" has no resolvable artifact path.`;
   }
-  const relPath = relative(basePath, artifactPath);
+  const relPath = relative(normalizeRealPath(basePath), artifactPath);
   if (!existsSync(artifactPath)) {
     const completionToolHint = unitType === "execute-task" && !hasTaskCompletionToolCall(agentEndMessages)
       ? " No completion tool call detected (`gsd_task_complete`/alias)."
@@ -2398,7 +2399,8 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
       const verdict = gateBlock.verdict ? ` verdict=${gateBlock.verdict};` : "";
       const artifact = gateBlock.artifact ? ` artifact=${gateBlock.artifact};` : "";
       const message =
-        `Post-unit gate "${gateBlock.hookName}" blocked ${gateBlock.triggerUnitType} ${gateBlock.triggerUnitId}:` +
+        `Post-unit gate "${gateBlock.hookName}" blocked ${gateBlock.triggerUnitType} ${gateBlock.triggerUnitId} ` +
+        `(detected on completion of ${s.currentUnit.type} ${s.currentUnit.id}):` +
         `${verdict}${artifact} ${gateBlock.reason}. Run /gsd status to inspect, then /gsd auto after recovery.`;
       ctx.ui.notify(message, "warning");
       await pauseAuto(ctx, pi);

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -11,7 +11,7 @@
 
 import { loadFile, parseContinue, parseSummary, loadActiveOverrides, formatOverridesSection, parseTaskPlanFile } from "./files.js";
 import type { Override } from "./files.js";
-import { hasVerdict, extractVerdict } from "./verdict-parser.js";
+import { extractVerdict } from "./verdict-parser.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import {
   resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
@@ -60,11 +60,8 @@ import { debugLog } from "./debug-logger.js";
 import { buildSkillActivationBlock, buildSkillDiscoveryVars } from "./skill-activation.js";
 import { findMilestoneIds } from "./milestone-ids.js";
 import { buildRunUatPresentationForType, RUN_UAT_TOOL_PRESENTATION_PLAN_ID } from "./tool-presentation-plan.js";
-import {
-  classifyUatContentForRun,
-  shouldDispatchUatForContent,
-  type UatType,
-} from "./uat-policy.js";
+import { classifyUatContentForRun } from "./uat-policy.js";
+import { checkNeedsRunUat as resolveNeedsRunUat, type UatDispatchCandidate } from "./uat-dispatch.js";
 import { buildWebAppUatGuidanceBlock } from "./web-app-uat.js";
 
 export { buildSkillActivationBlock, buildSkillDiscoveryVars };
@@ -1514,116 +1511,43 @@ export async function checkNeedsReassessment(
   return { sliceId: lastDone };
 }
 
-/**
- * Check if the most recently completed slice needs a UAT run.
- * Returns { sliceId, uatType } if UAT should be dispatched, null otherwise.
- *
- * Skips when:
- * - No roadmap or no completed slices
- * - uat_dispatch is not enabled and the UAT spec does not require runtime/browser evidence
- * - No UAT file exists for the slice
- * - UAT result file already exists (idempotent — already ran)
- */
-/**
- * Resolve the effective UAT mode for the dispatch gate the same way
- * `buildRunUatPrompt` does: classify the UAT body with the slice's SUMMARY as
- * supplemental context, so a `browser-executable` UAT whose slice references a
- * self-contained harness (`npm run test:uat`, `search-uat.mjs`, `npx
- * playwright test`) is promoted to `runtime-executable` for the gate too.
- *
- * Without this, `checkNeedsRunUat` returns `browser-executable` while the
- * prompt instructs runtime-only execution, causing the dispatch gate to
- * require browser tools / warm up the browser daemon (or stop dispatch when
- * browser MCP is unavailable) for UAT runs that never touch the browser. See
- * cursor[bot] review on PR #696 for the M007/S01 regression.
- */
-async function resolveRunUatEffectiveType(
+
+export function getRoadmapCompletedSliceCandidates(
+  roadmapContent: string,
+): UatDispatchCandidate[] {
+  return parseRoadmap(roadmapContent)
+    .slices.filter((slice) => slice.done)
+    .map((slice) => ({ sliceId: slice.id }))
+    .reverse();
+}
+
+
+export async function loadRoadmapCompletedSliceCandidates(
   base: string,
   mid: string,
-  sliceId: string,
-  uatContent: string,
-): Promise<UatType> {
-  let summaryContent = "";
-  try {
-    const summaryPath = resolveSliceFile(base, mid, sliceId, "SUMMARY");
-    if (summaryPath) {
-      summaryContent = (await loadFile(summaryPath)) ?? "";
-    }
-  } catch (err) {
-    logWarning(
-      "prompt",
-      `resolveRunUatEffectiveType SUMMARY load failed: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-  return classifyUatContentForRun(uatContent, summaryContent).effectiveType;
+): Promise<UatDispatchCandidate[]> {
+  const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
+  const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+  return roadmapContent ? getRoadmapCompletedSliceCandidates(roadmapContent) : [];
 }
 
+/**
+ * Back-compat wrapper for callers that import UAT dispatch checks from the
+ * prompt module. UAT dispatch architecture lives in `uat-dispatch.ts`; the
+ * `state` parameter is intentionally ignored because DB/roadmap artifacts are
+ * the source of truth for completed-slice discovery.
+ */
 export async function checkNeedsRunUat(
   base: string, mid: string, state: GSDState, prefs: GSDPreferences | undefined,
-): Promise<{ sliceId: string; uatType: UatType } | null> {
-  // DB primary path — fall through to file-based when DB has no data for this milestone
-  try {
-    const { isDbAvailable, getMilestoneSlices } = await import("./gsd-db.js");
-    if (isDbAvailable()) {
-      const slices = getMilestoneSlices(mid);
-      if (slices.length > 0) {
-        const completedSlices = slices.filter(s => s.status === "complete");
-        if (completedSlices.length === 0) return null;
-        for (const completed of [...completedSlices].reverse()) {
-          const sid = completed.id;
-          const uatFile = resolveSliceFile(base, mid, sid, "UAT");
-          if (!uatFile) continue;
-          const uatContent = await loadFile(uatFile);
-          if (!uatContent) continue;
-          // If the UAT file already contains a verdict, UAT has been run — skip
-          if (hasVerdict(uatContent)) continue;
-          // Also check the ASSESSMENT file — the run-uat prompt writes the verdict
-          // there (via gsd_uat_result_save), not into the
-          // UAT spec file. Without this check the unit re-dispatches indefinitely.
-          const assessmentFile = resolveSliceFile(base, mid, sid, "ASSESSMENT");
-          if (assessmentFile) {
-            const assessmentContent = await loadFile(assessmentFile);
-            if (assessmentContent && hasVerdict(assessmentContent)) continue;
-          }
-          if (!shouldDispatchUatForContent(uatContent, prefs)) continue;
-          const uatType = await resolveRunUatEffectiveType(base, mid, sid, uatContent);
-          return { sliceId: sid, uatType };
-        }
-        return null;
-      }
-    }
-  } catch (err) {
-    logWarning("prompt", `checkNeedsRunUat DB lookup failed: ${err instanceof Error ? err.message : String(err)}`);
-  }
+): Promise<Awaited<ReturnType<typeof resolveNeedsRunUat>>> {
+  void state;
 
-  // File-based fallback using roadmap checkboxes
-  const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
-  if (!roadmapPath) return null;
-  const roadmapContent = await loadFile(roadmapPath);
-  if (!roadmapContent) return null;
-  const parsed = parseRoadmap(roadmapContent);
-  const completedFileSlices = parsed.slices.filter(s => s.done);
-  if (completedFileSlices.length === 0) return null;
-  for (const completed of [...completedFileSlices].reverse()) {
-    const uatSid = completed.id;
-    const uatFileFb = resolveSliceFile(base, mid, uatSid, "UAT");
-    if (!uatFileFb) continue;
-    const uatContentFb = await loadFile(uatFileFb);
-    if (!uatContentFb) continue;
-    // If the UAT file already contains a verdict, UAT has been run — skip
-    if (hasVerdict(uatContentFb)) continue;
-    // Also check the ASSESSMENT file for the file-based fallback path (same
-    // reason as the DB path above — verdict lives in ASSESSMENT, not UAT).
-    const assessmentFileFb = resolveSliceFile(base, mid, uatSid, "ASSESSMENT");
-    if (assessmentFileFb) {
-      const assessmentContentFb = await loadFile(assessmentFileFb);
-      if (assessmentContentFb && hasVerdict(assessmentContentFb)) continue;
-    }
-    if (!shouldDispatchUatForContent(uatContentFb, prefs)) continue;
-    const uatType = await resolveRunUatEffectiveType(base, mid, uatSid, uatContentFb);
-    return { sliceId: uatSid, uatType };
-  }
-  return null;
+  return resolveNeedsRunUat(
+    base,
+    mid,
+    prefs,
+    await loadRoadmapCompletedSliceCandidates(base, mid),
+  );
 }
 
 // ─── Prompt Builders ──────────────────────────────────────────────────────
@@ -3909,9 +3833,15 @@ export async function buildReassessRoadmapPrompt(
  * that instructs the coordinator how to dispatch a `subagent` call. Either or
  * both may be absent (ADR-026 / #508).
  */
-function subagentCallSuffix(model?: string, thinking?: string): string {
+function subagentCallSuffix(model?: string, thinking?: string, fallbacks?: string[]): string {
   const parts: string[] = [];
-  if (model) parts.push(`model: "${model}"`);
+  if (model) {
+    let modelHint = `model: "${model}"`;
+    if (fallbacks && fallbacks.length > 0) {
+      modelHint += ` (fallbacks, in order: ${fallbacks.map((f) => `"${f}"`).join(", ")})`;
+    }
+    parts.push(modelHint);
+  }
   if (thinking) parts.push(`thinking: "${thinking}"`);
   return parts.length > 0 ? ` with ${parts.join(" and ")}` : "";
 }
@@ -3922,7 +3852,13 @@ export async function buildReactiveExecutePrompt(
   subagentModel?: string,
   // Reasoning effort travels inside opts here (not as a positional param) so
   // existing positional `opts` callers don't shift (#508).
-  opts?: { sessionContextWindow?: number; modelRegistry?: MinimalModelRegistry; sessionProvider?: string; subagentThinking?: string },
+  opts?: {
+    sessionContextWindow?: number;
+    modelRegistry?: MinimalModelRegistry;
+    sessionProvider?: string;
+    subagentThinking?: string;
+    subagentModelFallbacks?: string[];
+  },
 ): Promise<string> {
   const { loadSliceTaskIO, deriveTaskGraph, graphMetrics } = await import("./reactive-graph.js");
 
@@ -4019,7 +3955,11 @@ export async function buildReactiveExecutePrompt(
       `When done, say: "Task ${tid} complete."`,
     ].join("\n");
 
-    const modelSuffix = subagentCallSuffix(subagentModel, opts?.subagentThinking);
+    const modelSuffix = subagentCallSuffix(
+      subagentModel,
+      opts?.subagentThinking,
+      opts?.subagentModelFallbacks,
+    );
     subagentSections.push([
       `### ${tid}: ${tTitle}`,
       "",