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

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -26,12 +26,11 @@ import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../path
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
-import { getDeclaredUatType, shouldEscalateArtifactUatToBrowser } from "../uat-policy.js";
+import { classifyUatContent, escalatesArtifactUatToBrowser } from "../uat-policy.js";
 import { invalidateStateCache } from "../state.js";
-import { renderRoadmapFromDb } from "../markdown-renderer.js";
-import { parseRoadmap } from "../parsers-legacy.js";
+import { renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "../markdown-renderer.js";
 import { isStaleWrite } from "../auto/turn-epoch.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -91,9 +90,11 @@ function hasCompleteSliceArtifactContract(basePath: string, milestoneId: string,
     join(gsdProjectionRoot(basePath), "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
   if (!existsSync(roadmapPath)) return false;
 
+  // Projection-completeness check (ADR-017): the DB has already recorded the
+  // duplicate completion; this only verifies the rendered markdown artifacts
+  // exist and reflect it, deciding whether re-rendering is needed.
   try {
-    const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
-    return roadmap.slices.some((slice) => slice.id === sliceId && slice.done);
+    return roadmapRenderMarksSliceDone(readFileSync(roadmapPath, "utf-8"), sliceId);
   } catch {
     return false;
   }
@@ -355,10 +356,18 @@ export async function handleCompleteSlice(
   // `npx playwright test` via gsd_uat_exec, and live-runtime/mixed/
   // browser-executable receive browser tools (UAT_MODE_POLICIES).
   const uatContent = params.uatContent || "";
-  const declaredUatMode = getDeclaredUatType(uatContent);
-  if (shouldEscalateArtifactUatToBrowser(uatContent)) {
+  const uatPolicy = classifyUatContent(uatContent);
+  if (escalatesArtifactUatToBrowser(uatPolicy)) {
+    // Distinguish an explicit artifact-driven declaration from a missing or
+    // unparseable one that merely *defaulted* to artifact-driven — telling an
+    // agent it "declared artifact-driven" when its declaration simply failed
+    // to parse sends it into a rewrite loop with the same unparseable format.
+    const staticOnlyClause = `which only runs static/file checks and would defer the browser work to a human`;
+    const modeClause = uatPolicy.modeDeclared
+      ? `declares "UAT mode: artifact-driven", ${staticOnlyClause}`
+      : `has no parseable UAT mode declaration in its "## UAT Type" section (the declaration must be a bullet exactly like "- UAT mode: browser-executable"), so it defaults to "artifact-driven", ${staticOnlyClause}`;
     return {
-      error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but declares "UAT mode: artifact-driven", which only runs static/file checks and would defer the browser work to a human. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
+      error: `UAT requires browser verification (opening a page in a browser, navigating to a page or localhost, screenshots) but ${modeClause}. Use a mode that actually verifies the UI: "browser-executable" (interactive browser tools), "runtime-executable" (a browser test command such as playwright), or a browser-inclusive "mixed"/"live-runtime". Re-author the UAT Type section and complete the slice again.`,
     };
   }
 
@@ -470,8 +479,9 @@ export async function handleCompleteSlice(
 
     const roadmap = await renderRoadmapFromDb(artifactBasePath, params.milestoneId);
     clearParseCache();
-    const roadmapSlice = parseRoadmap(roadmap.content).slices.find((slice) => slice.id === params.sliceId);
-    if (!roadmapSlice?.done) {
+    // Render verification (ADR-017): confirms the just-written projection
+    // reflects the DB completion; the DB row is already committed.
+    if (!roadmapRenderMarksSliceDone(roadmap.content, params.sliceId)) {
       throw new Error(`roadmap render did not mark ${params.milestoneId}/${params.sliceId} complete`);
     }
   } catch (renderErr) {
@@ -527,7 +537,7 @@ export async function handleCompleteSlice(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await renderAllProjections(artifactBasePath, params.milestoneId);
+    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
   } catch (projErr) {
     logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${(projErr as Error).message}`);
   }

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -35,7 +35,8 @@ import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanCheckboxes } from "../markdown-renderer.js";
-import { renderAllProjections, renderSummaryContent } from "../workflow-projections.js";
+import { renderSummaryContent } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -467,7 +468,7 @@ export async function handleCompleteTask(
   // Separate try/catch per step so a projection failure doesn't prevent
   // the event log entry (critical for worktree reconciliation).
   try {
-    await renderAllProjections(artifactBasePath, params.milestoneId);
+    await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
   } catch (projErr) {
     logWarning("tool", `complete-task projection warning: ${(projErr as Error).message}`);
   }

package/src/resources/extensions/gsd/tools/exec-tool.ts

@@ -11,7 +11,7 @@ import {
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { isContextModeEnabled, type ContextModeConfig } from "../preferences-types.js";
-import { findWorktreeSegment } from "../worktree-root.js";
+import { projectRootFromWorktreePath } from "../worktree-root.js";
 import { contextModeDisabledResult, type ToolExecutionResult } from "./context-mode-tool-result.js";
 
 export interface ExecToolParams {
@@ -202,12 +202,9 @@ function normalizeScanPath(value: string): string {
 
 function parseWorktreeBase(baseDir: string): { originalRoot: string; worktreeRoot: string } | null {
   const normalizedBase = normalizeScanPath(baseDir);
-  const segment = findWorktreeSegment(normalizedBase);
-  if (!segment || segment.gsdIdx <= 0) return null;
-  return {
-    originalRoot: normalizedBase.slice(0, segment.gsdIdx),
-    worktreeRoot: normalizedBase,
-  };
+  const originalRoot = projectRootFromWorktreePath(normalizedBase);
+  if (!originalRoot) return null;
+  return { originalRoot, worktreeRoot: normalizedBase };
 }
 
 function pathInside(parent: string, target: string): boolean {
@@ -427,6 +424,7 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
       exit_code: result.exit_code,
       signal: result.signal,
       timed_out: result.timed_out,
+      force_resolved: result.force_resolved,
       duration_ms: result.duration_ms,
       stdout_bytes: result.stdout_bytes,
       stderr_bytes: result.stderr_bytes,
@@ -441,6 +439,9 @@ function formatResult(result: ExecSandboxResult): ToolExecutionResult {
 }
 
 function formatExit(result: ExecSandboxResult): string {
+  // force_resolved means a non-closing (D-state) child was force-resolved past its
+  // hard deadline rather than observed exiting; distinguish it from a clean timeout.
+  if (result.force_resolved) return "timeout(force-killed)";
   if (result.timed_out) return "timeout";
   if (result.signal) return `signal:${result.signal}`;
   if (result.exit_code === null) return "null";

package/src/resources/extensions/gsd/tools/plan-slice.ts

@@ -21,13 +21,14 @@ import {
 import type { GateEvaluationConfig, GateId } from "../types.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
 import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
-import { checkFilePathConsistency, checkTaskOrdering } from "../pre-execution-checks.js";
+import { runTaskPathChecks } from "../pre-execution-checks.js";
 import type { TaskRow } from "../db-task-slice-rows.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { buildTaskFileName, gsdProjectionRoot } from "../paths.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { createRepositoryRegistryFromPreferences, defaultRepositoryTargets, type RepositoryRegistry } from "../repository-registry.js";
@@ -268,11 +269,16 @@ function validateTaskPathsBeforePersist(
   const additionalRoots = allowedRoots
     .map((root) => resolve(root))
     .filter((root) => root !== baseRoot);
-  const context = additionalRoots.length > 0 ? { additionalRoots } : undefined;
-  const checks = [
-    ...checkFilePathConsistency(taskRows, basePath, context),
-    ...checkTaskOrdering(taskRows, basePath, context),
-  ];
+  const resolvedCanonicalRoot = resolve(resolveWorktreeProjectRoot(basePath));
+  const canonicalProjectRoot = resolvedCanonicalRoot !== baseRoot ? resolvedCanonicalRoot : undefined;
+  const hasContext = additionalRoots.length > 0 || canonicalProjectRoot !== undefined;
+  const context = hasContext
+    ? {
+        ...(additionalRoots.length > 0 ? { additionalRoots } : {}),
+        ...(canonicalProjectRoot !== undefined ? { canonicalProjectRoot } : {}),
+      }
+    : undefined;
+  const checks = runTaskPathChecks(taskRows, basePath, context);
   const blocking = checks.filter((check) => !check.passed && check.blocking);
 
   if (blocking.length === 0) return null;
@@ -462,7 +468,7 @@ export async function handlePlanSlice(
 
     // ── Post-mutation hook: projections, manifest, event log ─────────────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "plan-slice",

package/src/resources/extensions/gsd/tools/plan-task.ts

@@ -4,7 +4,7 @@ import { isNonEmptyString, validateStringArray } from "../validation.js";
 import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderTaskPlanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -142,7 +142,7 @@ export async function handlePlanTask(
 
     // ── Post-mutation hook: projections, manifest, event log ─────────────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "plan-task",

package/src/resources/extensions/gsd/tools/reassess-roadmap.ts

@@ -16,7 +16,7 @@ import {
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, renderAssessmentFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -306,7 +306,7 @@ export async function handleReassessRoadmap(
 
     // ── Post-mutation hook: projections, manifest, event log ─────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "reassess-roadmap",

package/src/resources/extensions/gsd/tools/reopen-milestone.ts

@@ -15,7 +15,7 @@ import {
   reopenMilestoneCascade,
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -98,7 +98,7 @@ export async function handleReopenMilestone(
 
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "reopen-milestone",

package/src/resources/extensions/gsd/tools/reopen-slice.ts

@@ -16,7 +16,7 @@ import {
   reopenSliceCascade,
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -97,7 +97,7 @@ export async function handleReopenSlice(
 
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "reopen-slice",

package/src/resources/extensions/gsd/tools/reopen-task.ts

@@ -19,7 +19,7 @@ import {
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -119,7 +119,7 @@ export async function handleReopenTask(
 
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "reopen-task",

package/src/resources/extensions/gsd/tools/replan-slice.ts

@@ -13,7 +13,7 @@ import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
 import { renderPlanFromDb, renderReplanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -216,7 +216,7 @@ export async function handleReplanSlice(
 
     // ── Post-mutation hook: projections, manifest, event log ─────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "replan-slice",

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -19,9 +19,10 @@ import {
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
+import { hostname } from "node:os";
 import { join } from "node:path";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
 import { handleCompleteMilestone } from "./complete-milestone.js";
@@ -48,13 +49,21 @@ import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
-import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
+import { autoSession, getAutoRuntimeSnapshot, isAutoActive } from "../auto-runtime-state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
 import {
   prepareUatRun,
   saveUatAttemptArtifact,
   type UatResultSaveParams,
 } from "../uat-run.js";
+import { registerAutoWorker, markWorkerStopping, getAutoWorker } from "../db/auto-workers.js";
+import {
+  claimMilestoneLease,
+  releaseMilestoneLease,
+  getMilestoneLease,
+  refreshMilestoneLease,
+  milestoneLeaseTtlSeconds,
+} from "../db/milestone-leases.js";
 export type {
   UatCheckResultInput,
   UatEvidenceRef,
@@ -105,6 +114,24 @@ function blockIfWrongAutoUnit(requiredUnitType: string, operation: string): Tool
   };
 }
 
+function milestoneLeaseConflictResult(
+  milestoneId: string,
+  byWorker: string,
+  expiresAt: string,
+): ToolExecutionResult {
+  return {
+    content: [{ type: "text", text: `Milestone ${milestoneId} is currently leased by ${byWorker}. Retry after ${expiresAt}.` }],
+    details: {
+      operation: "plan_milestone",
+      error: "milestone_lease_conflict",
+      milestoneId,
+      byWorker,
+      expiresAt,
+    },
+    isError: true,
+  };
+}
+
 export interface SummarySaveParams {
   milestone_id?: string;
   slice_id?: string;
@@ -1244,7 +1271,48 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  let workerId: string | null = null;
+  let acquiredToken: number | null = null;
+  let leaseRefreshTimer: ReturnType<typeof setInterval> | undefined;
   try {
+    // Re-read at the gate so a peer-created milestone is not treated as fresh.
+    const milestoneExists = getMilestone(params.milestoneId) !== null;
+    if (milestoneExists) {
+      const heldLease = getMilestoneLease(params.milestoneId);
+      if (heldLease?.status === "held" && Date.parse(heldLease.expires_at) > Date.now()) {
+        const holder = getAutoWorker(heldLease.worker_id);
+        // Let the one-shot claim path recover stale same-process worker rows.
+        const projectRoot = normalizeRealPath(basePath);
+        const isOurAutoLease = isAutoActive() && heldLease.worker_id === autoSession.workerId;
+        const holderIsOneShotReentrantPeer = !isAutoActive()
+          && !!holder
+          && holder.host === hostname()
+          && holder.pid === process.pid
+          && holder.project_root_realpath === projectRoot;
+        if (holder?.status === "active" && !isOurAutoLease && !holderIsOneShotReentrantPeer) {
+          return milestoneLeaseConflictResult(params.milestoneId, heldLease.worker_id, heldLease.expires_at);
+        }
+      }
+    }
+
+    // Fresh creation cannot claim a lease because the FK row does not exist.
+    // In-process auto already owns its lease; re-claiming would bump its token.
+    if (!isAutoActive() && milestoneExists) {
+      workerId = registerAutoWorker({ projectRootRealpath: normalizeRealPath(basePath) });
+      const lease = claimMilestoneLease(workerId, params.milestoneId);
+      if (!lease.ok) {
+        return milestoneLeaseConflictResult(params.milestoneId, lease.byWorker, lease.expiresAt);
+      }
+      acquiredToken = lease.token;
+
+      const leaseRefreshMs = (milestoneLeaseTtlSeconds() / 2) * 1000;
+      leaseRefreshTimer = setInterval(() => {
+        if (acquiredToken !== null && workerId !== null) {
+          refreshMilestoneLease(workerId, params.milestoneId, acquiredToken);
+        }
+      }, leaseRefreshMs);
+    }
+
     const result = await handlePlanMilestone(params, basePath);
     if ("error" in result) {
       return {
@@ -1270,6 +1338,17 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  finally {
+    if (leaseRefreshTimer !== undefined) {
+      clearInterval(leaseRefreshTimer);
+    }
+    if (workerId !== null && acquiredToken !== null) {
+      releaseMilestoneLease(workerId, params.milestoneId, acquiredToken);
+    }
+    if (workerId !== null) {
+      markWorkerStopping(workerId);
+    }
+  }
 }
 
 export async function executePlanSlice(

package/src/resources/extensions/gsd/uat-policy.ts

@@ -1,7 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Central UAT mode policy for dispatch, tool presentation, and result validation.
 
-import { extractUatType } from "./files.js";
+import { hasBrowserContractPrefix } from "../shared/browser-contract.js";
+import { extractUatType, UAT_TYPE_KEYWORDS } from "./files.js";
 import type { UatType } from "./files.js";
 import { hasBrowserRequiredText } from "./browser-evidence.js";
 import { parseMcpToolName } from "./mcp-tool-name.js";
@@ -27,19 +28,14 @@ export interface UatModePolicy {
 
 export interface UatContentPolicy {
   declaredType: UatType;
+  /** False when no parseable `UAT mode:` declaration exists and declaredType defaulted to artifact-driven. */
+  modeDeclared: boolean;
   effectiveType: UatType;
   browserRequired: boolean;
   shouldDispatchByDefault: boolean;
 }
 
-export const UAT_TYPES: readonly UatType[] = [
-  "artifact-driven",
-  "browser-executable",
-  "runtime-executable",
-  "live-runtime",
-  "mixed",
-  "human-experience",
-] as const;
+export const UAT_TYPES: readonly UatType[] = UAT_TYPE_KEYWORDS;
 
 export const UAT_MODE_POLICIES: Readonly<Record<UatType, UatModePolicy>> = {
   "artifact-driven": {
@@ -88,26 +84,76 @@ export function getDeclaredUatType(content: string): UatType {
   return extractUatType(content) ?? "artifact-driven";
 }
 
-export function classifyUatContent(content: string): UatContentPolicy {
-  const declaredType = getDeclaredUatType(content);
-  const browserRequired = hasBrowserRequiredText(content);
-  const effectiveType = declaredType === "artifact-driven" && browserRequired
+/** Self-contained browser UAT harnesses that manage server lifecycle internally. */
+const SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE =
+  /\b(?:npm run test:uat|node\s+(?:--check\s+\S+\s+&&\s+)*tests\/browser\/search-uat\.mjs|npx playwright test(?:\s+\S+)?)\b/i;
+
+export function hasSelfContainedRuntimeUatCommand(content: string): boolean {
+  return SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE.test(content);
+}
+
+function resolveEffectiveUatTypeFromPolicy(
+  declaredType: UatType,
+  browserRequired: boolean,
+  content: string,
+): UatType {
+  let effectiveType = declaredType === "artifact-driven" && browserRequired
     ? "browser-executable"
     : declaredType;
 
+  // M006/S01 regression: specs often declare browser-executable with localhost
+  // preconditions while the Evidence section names a runtime harness such as
+  // `npm run test:uat`. Interactive browser_* checks then race a fixed port
+  // against the script's own ephemeral server — run the harness instead.
+  if (
+    effectiveType === "browser-executable" &&
+    hasSelfContainedRuntimeUatCommand(content)
+  ) {
+    effectiveType = "runtime-executable";
+  }
+
+  return effectiveType;
+}
+
+export function classifyUatContent(content: string): UatContentPolicy {
+  return classifyUatContentForRun(content);
+}
+
+/**
+ * Classify UAT mode for run-uat dispatch. Supplemental context (slice summary,
+ * verification excerpts) can name a self-contained harness even when the UAT
+ * file only documents a separate server command such as `npm run test:server`.
+ */
+export function classifyUatContentForRun(content: string, supplementalContext = ""): UatContentPolicy {
+  const parsedType = extractUatType(content);
+  const declaredType = parsedType ?? "artifact-driven";
+  const browserRequired = hasBrowserRequiredText(content);
+  const combinedForHarness = supplementalContext.trim()
+    ? `${content}\n\n${supplementalContext}`
+    : content;
+  const effectiveType = resolveEffectiveUatTypeFromPolicy(
+    declaredType,
+    browserRequired,
+    combinedForHarness,
+  );
+
   return {
     declaredType,
+    modeDeclared: parsedType !== undefined,
     effectiveType,
     browserRequired,
     shouldDispatchByDefault: effectiveType !== "artifact-driven" || browserRequired,
   };
 }
 
-export function shouldEscalateArtifactUatToBrowser(content: string): boolean {
-  const policy = classifyUatContent(content);
+export function escalatesArtifactUatToBrowser(policy: UatContentPolicy): boolean {
   return policy.declaredType === "artifact-driven" && policy.browserRequired;
 }
 
+export function shouldEscalateArtifactUatToBrowser(content: string): boolean {
+  return escalatesArtifactUatToBrowser(classifyUatContent(content));
+}
+
 export function resolveEffectiveUatType(content: string): UatType {
   return classifyUatContent(content).effectiveType;
 }
@@ -126,7 +172,7 @@ export function uatTypeIncludesBrowser(uatType: string | undefined): boolean {
 export function isUatBrowserToolName(toolName: string): boolean {
   const parsed = parseMcpToolName(toolName);
   const canonicalName = parsed?.toolName ?? toolName;
-  if (canonicalName.startsWith("browser_")) return true;
+  if (hasBrowserContractPrefix(canonicalName)) return true;
   return parsed?.toolName === "*" && parsed.serverName.toLowerCase().includes("browser");
 }