@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.822c9439

package/dist/resources/extensions/gsd/state.js

@@ -3,6 +3,11 @@
 // GSD Extension — State Derivation
 // DB-authoritative runtime derivation with explicit legacy filesystem fallback.
 // Pure TypeScript, zero Pi dependencies.
+// Pre-migration fallback ONLY (ADR-017): deriveState must work on projects
+// whose DB does not exist yet (before md-importer runs), so it parses markdown
+// projections when `isDbAvailable()` is false or the DB has no rows. Once the
+// DB is populated, decision reads go through gsd-db queries — these parsers
+// must never be consulted when DB data is present.
 import { parseRoadmap, parsePlan, } from './parsers-legacy.js';
 import { parseSummary, loadFile, parseRequirementCounts, parseContextDependsOn, } from './files.js';
 import { resolveMilestoneFile, resolveSlicePath, resolveSliceFile, resolveTaskFile, resolveTasksDir, resolveGsdRootFile, gsdRoot, } from './paths.js';

package/dist/resources/extensions/gsd/tool-contract.js

@@ -1,8 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: ADR-015 Tool Contract module for Unit prompt, policy, and tool parity.
 import { resolveManifest, } from "./unit-context-manifest.js";
-import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
-import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
+import { getWorkflowTransportSupportError, } from "./workflow-mcp.js";
+import { getRequiredWorkflowToolsForUnit, getUnitToolSurfaceContract, } from "./unit-tool-contracts.js";
 import { WHOLE_FILE_OBSERVATION_MAX_BYTES, WHOLE_FILE_OBSERVATION_MAX_LINES, } from "./source-observations.js";
 export function compileUnitContextContract(unitType) {
     const manifest = resolveManifest(unitType);
@@ -15,6 +15,17 @@ export function compileUnitContextContract(unitType) {
     }
     return { ok: true, contract: buildPromptContextContract(unitType, manifest) };
 }
+export function getUnitWorkflowDispatchReadinessError(input) {
+    return getWorkflowTransportSupportError(input.provider, getRequiredWorkflowToolsForUnit(input.unitType), {
+        projectRoot: input.projectRoot,
+        env: input.env,
+        surface: input.surface,
+        unitType: input.unitType,
+        authMode: input.authMode,
+        baseUrl: input.baseUrl,
+        activeTools: input.activeTools,
+    });
+}
 export function compileUnitToolContract(unitType) {
     const manifest = resolveManifest(unitType);
     const surfaceContract = getUnitToolSurfaceContract(unitType);
@@ -25,7 +36,7 @@ export function compileUnitToolContract(unitType) {
             detail: `No Unit manifest is registered for ${unitType}`,
         };
     }
-    const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+    const requiredWorkflowTools = getRequiredWorkflowToolsForUnit(unitType);
     const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
         .map(([name, reason]) => ({ name, reason }));
     const closeoutTools = requiredWorkflowTools.filter((tool) => /^gsd_(?:task|slice|milestone|complete|validate|save|summary|uat)/.test(tool));

package/dist/resources/extensions/gsd/tool-presentation-plan.js

@@ -4,7 +4,7 @@ import { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_
 import { toMcpToolName } from "./mcp-tool-name.js";
 import { createToolSurfaceSnapshot } from "./tool-surface-snapshot.js";
 import { uatTypeIncludesBrowser } from "./uat-policy.js";
-import { canonicalWorkflowSurfaceToolName } from "./workflow-tool-surface.js";
+import { canonicalWorkflowToolName } from "./engine-hook-contract.js";
 export { RUN_UAT_BROWSER_TOOL_NAMES, RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_TOOL_PRESENTATION_PLAN_ID, RUN_UAT_WORKFLOW_TOOL_NAMES, } from "./unit-tool-contracts.js";
 export const RUN_UAT_FORBIDDEN_TOOL_NAMES = [
     "edit",
@@ -24,9 +24,9 @@ export const RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES = [
     "Glob",
     "Grep",
 ];
-export function canonicalWorkflowToolName(toolName) {
-    return canonicalWorkflowSurfaceToolName(toolName);
-}
+// Normalizer seam lives in engine-hook-contract.ts; re-exported here for
+// existing presentation importers (uat-run.ts).
+export { canonicalWorkflowToolName };
 export { parseMcpToolName } from "./mcp-tool-name.js";
 export function toWorkflowMcpToolName(serverName, toolName) {
     return toMcpToolName(serverName, canonicalWorkflowToolName(toolName));

package/dist/resources/extensions/gsd/tools/complete-milestone.js

@@ -16,7 +16,8 @@ import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { isClosedStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
-import { renderAllProjections, stripIdPrefix } from "../workflow-projections.js";
+import { stripIdPrefix } 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";
@@ -166,7 +167,7 @@ export async function handleCompleteMilestone(params, basePath) {
     // 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-milestone projection warning: ${projErr.message}`);

package/dist/resources/extensions/gsd/tools/complete-slice.js

@@ -17,12 +17,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";
@@ -55,9 +54,11 @@ function hasCompleteSliceArtifactContract(basePath, milestoneId, sliceId) {
         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;
@@ -288,10 +289,18 @@ export async function handleCompleteSlice(params, basePath) {
     // `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.`,
         };
     }
     // ── Atomic completion cascade (guards + writes in one transaction) ───────
@@ -388,8 +397,9 @@ export async function handleCompleteSlice(params, basePath) {
         await saveFile(uatPath, uatMd);
         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`);
         }
     }
@@ -438,7 +448,7 @@ export async function handleCompleteSlice(params, basePath) {
     // 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.message}`);

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -18,7 +18,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";
@@ -358,7 +359,7 @@ export async function handleCompleteTask(params, basePath) {
     // 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.message}`);

package/dist/resources/extensions/gsd/tools/exec-tool.js

@@ -342,6 +342,7 @@ function formatResult(result) {
             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,
@@ -355,6 +356,10 @@ function formatResult(result) {
     };
 }
 function formatExit(result) {
+    // 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)

package/dist/resources/extensions/gsd/tools/plan-slice.js

@@ -7,7 +7,7 @@ import { getGateIdsForTurn } from "../gate-registry.js";
 import { transaction, getMilestone, getSlice, getSliceTasks, insertTask, upsertSlicePlanning, upsertTaskPlanning, insertGateRow, updateSliceStatus, setSliceSketchFlag, deleteTask, deleteArtifactByPath, } from "../gsd-db.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";
@@ -367,7 +367,7 @@ export async function handlePlanSlice(rawParams, basePath) {
         clearParseCache();
         // ── 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/dist/resources/extensions/gsd/tools/plan-task.js

@@ -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";
@@ -110,7 +110,7 @@ export async function handlePlanTask(rawParams, basePath) {
         clearParseCache();
         // ── 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/dist/resources/extensions/gsd/tools/reassess-roadmap.js

@@ -6,7 +6,7 @@ import { isNonEmptyString } from "../validation.js";
 import { transaction, getMilestone, getMilestoneSlices, getSlice, insertSlice, updateSliceFields, insertAssessment, deleteAssessmentByScope, deleteSlice, } 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";
@@ -234,7 +234,7 @@ export async function handleReassessRoadmap(rawParams, basePath) {
         clearParseCache();
         // ── 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/dist/resources/extensions/gsd/tools/reopen-milestone.js

@@ -9,7 +9,7 @@
  */
 import { getMilestoneSlices, getSliceTasks, 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";
@@ -74,7 +74,7 @@ export async function handleReopenMilestone(params, basePath) {
     clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "reopen-milestone",

package/dist/resources/extensions/gsd/tools/reopen-slice.js

@@ -11,7 +11,7 @@
 // Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 import { getSliceTasks, 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";
@@ -72,7 +72,7 @@ export async function handleReopenSlice(params, basePath) {
     clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "reopen-slice",

package/dist/resources/extensions/gsd/tools/reopen-task.js

@@ -11,7 +11,7 @@
 import { getMilestone, getSlice, getTask, updateTaskStatus, transaction, } 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";
@@ -83,7 +83,7 @@ export async function handleReopenTask(params, basePath) {
     clearPathCache();
     // ── Post-mutation hook ───────────────────────────────────────────────────
     try {
-        await renderAllProjections(basePath, params.milestoneId);
+        await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
         writeManifest(basePath);
         appendEvent(basePath, {
             cmd: "reopen-task",

package/dist/resources/extensions/gsd/tools/replan-slice.js

@@ -4,7 +4,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";
@@ -162,7 +162,7 @@ export async function handleReplanSlice(rawParams, basePath) {
         clearParseCache();
         // ── 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/dist/resources/extensions/gsd/tools/workflow-tool-executors.js

@@ -6,9 +6,10 @@ import { loadWriteGateSnapshot, shouldBlockContextArtifactSaveInSnapshot, should
 import { getActiveRequirements, getAllMilestones, getMilestone, getSliceStatusSummary, getSliceTaskCounts, insertMilestone, insertAssessment, insertGateRun, readTransaction, saveGateResult, upsertQualityGate, } 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 { handleCompleteMilestone } from "./complete-milestone.js";
 import { handleCompleteTask } from "./complete-task.js";
@@ -25,9 +26,11 @@ 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, } 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 const SUPPORTED_SUMMARY_ARTIFACT_TYPES = [
     "SUMMARY",
     "RESEARCH",
@@ -61,6 +64,19 @@ function blockIfWrongAutoUnit(requiredUnitType, operation) {
         isError: true,
     };
 }
+function milestoneLeaseConflictResult(milestoneId, byWorker, expiresAt) {
+    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,
+    };
+}
 function registerProjectMilestoneSequence(content) {
     const parsed = parseProject(content);
     const registered = [];
@@ -1066,7 +1082,45 @@ export async function executePlanMilestone(params, basePath = process.cwd()) {
             isError: true,
         };
     }
+    let workerId = null;
+    let acquiredToken = null;
+    let leaseRefreshTimer;
     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 {
@@ -1093,6 +1147,17 @@ export async function executePlanMilestone(params, basePath = process.cwd()) {
             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(params, basePath = process.cwd()) {
     const dbAvailable = await ensureDbOpen(basePath);

package/dist/resources/extensions/gsd/uat-policy.js

@@ -1,16 +1,10 @@
 // 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 { hasBrowserRequiredText } from "./browser-evidence.js";
 import { parseMcpToolName } from "./mcp-tool-name.js";
-export const UAT_TYPES = [
-    "artifact-driven",
-    "browser-executable",
-    "runtime-executable",
-    "live-runtime",
-    "mixed",
-    "human-experience",
-];
+export const UAT_TYPES = UAT_TYPE_KEYWORDS;
 export const UAT_MODE_POLICIES = {
     "artifact-driven": {
         browserTools: false,
@@ -55,23 +49,55 @@ export function isUatType(value) {
 export function getDeclaredUatType(content) {
     return extractUatType(content) ?? "artifact-driven";
 }
-export function classifyUatContent(content) {
-    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) {
+    return SELF_CONTAINED_RUNTIME_UAT_COMMAND_RE.test(content);
+}
+function resolveEffectiveUatTypeFromPolicy(declaredType, browserRequired, content) {
+    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) {
+    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, supplementalContext = "") {
+    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) {
-    const policy = classifyUatContent(content);
+export function escalatesArtifactUatToBrowser(policy) {
     return policy.declaredType === "artifact-driven" && policy.browserRequired;
 }
+export function shouldEscalateArtifactUatToBrowser(content) {
+    return escalatesArtifactUatToBrowser(classifyUatContent(content));
+}
 export function resolveEffectiveUatType(content) {
     return classifyUatContent(content).effectiveType;
 }
@@ -84,7 +110,7 @@ export function uatTypeIncludesBrowser(uatType) {
 export function isUatBrowserToolName(toolName) {
     const parsed = parseMcpToolName(toolName);
     const canonicalName = parsed?.toolName ?? toolName;
-    if (canonicalName.startsWith("browser_"))
+    if (hasBrowserContractPrefix(canonicalName))
         return true;
     return parsed?.toolName === "*" && parsed.serverName.toLowerCase().includes("browser");
 }

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -36,6 +36,7 @@
 // owned by the unit, not in the composer. Reviews must enforce this — it
 // is the difference between an orchestrator and a runaway DSL.
 import { resolveManifest, } from "./unit-context-manifest.js";
+import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 /**
  * Produce the inlined-context portion of a unit's system prompt by
  * walking the manifest's `artifacts.inline` list in order and calling
@@ -122,6 +123,70 @@ export function composeContextModeInstructions(unitType, opts) {
         guidance,
     ].join("\n");
 }
+const TOOL_SURFACE_GUIDANCE_BY_UNIT = {
+    "run-uat": "Do not call `gsd_exec`, `Bash`, `Write`, or `Edit` — they are unavailable in this unit. Run every automated check through `gsd_uat_exec` with the appropriate `intent`. For browser UAT modes, use `browser_*` tools when presented; if browser automation fails, record the failure honestly and use `gsd_uat_exec` for the best objective substitute.",
+    "complete-slice": "Run slice-level verification through `gsd_exec` (or MCP-scoped `mcp__…__gsd_exec`), not direct `bash`. Do not call `gsd_uat_result_save` — run-uat owns persisted UAT assessment. On verification failure, do not edit user source files in this unit.",
+    "gate-evaluate": "Dispatch only **tester** subagents via `subagent`. Persist each gate with `gsd_save_gate_result`. Do not use `ToolSearch` — it is not available.",
+    "reactive-execute": "Dispatch only **worker** subagents via `subagent`. Do not call `gsd_task_complete` from this parent batch — each worker owns its task completion. If a failed task left no summary, call `gsd_summary_save` with `blocker_discovered: true`.",
+    "execute-task": "Complete only this task via `gsd_task_complete`. Do not call `gsd_slice_complete`, `gsd_validate_milestone`, or `gsd_complete_milestone` — the orchestrator owns phase transitions.",
+    "validate-milestone": "Dispatch reviewer subagents in parallel, then persist the verdict via `gsd_validate_milestone`. Do not query `.gsd/gsd.db` directly — use `gsd_milestone_status` and inlined context.",
+    "complete-milestone": "Persist completion only through `gsd_complete_milestone` after verification passes. Do not query `.gsd/gsd.db` directly. Do not write `.gsd/PROJECT.md` or `.gsd/REQUIREMENTS.md` by hand — use `gsd_summary_save` and `gsd_requirement_update`.",
+    "replan-slice": "Persist replans through `gsd_replan_slice` only. Do not edit `PLAN.md` or task plans directly.",
+    "plan-slice": "Persist planning through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner** for reconnaissance — not implementation agents. Do not edit user source files outside `.gsd/**`.",
+    "refine-slice": "Persist refinements through `gsd_plan_slice` only. Dispatch subagents only to **scout** or **planner**. Do not edit user source files outside `.gsd/**`.",
+    "plan-milestone": "Persist milestone planning through `gsd_plan_milestone` / `gsd_plan_slice`. Do not edit user source files outside `.gsd/**`.",
+    "research-slice": "Dispatch subagents only to **scout** or **planner** for reconnaissance. Do not edit user source files outside `.gsd/**`.",
+};
+function guidanceForToolsPolicy(policy) {
+    switch (policy.mode) {
+        case "planning":
+            return "Writes are restricted to `.gsd/**` under the working directory — do not edit user source files. `bash` is limited to read-only investigation commands. Do not dispatch subagents. For human elicitation, use workflow MCP `ask_user_questions` when available — not native `AskUserQuestion`.";
+        case "planning-dispatch": {
+            const agents = policy.allowedSubagents.map((agent) => `**${agent}**`).join(", ");
+            return `Writes are restricted to \`.gsd/**\`. Dispatch subagents only to: ${agents}. Do not edit user source files.`;
+        }
+        case "docs":
+            return "Writes are restricted to `.gsd/**` and project documentation paths (`docs/`, `README*`, `CHANGELOG.md`, root `*.md`). Do not edit application source.";
+        case "verification": {
+            const subagentLine = policy.allowedSubagents?.length
+                ? ` Dispatch subagents only to: ${policy.allowedSubagents.map((agent) => `**${agent}**`).join(", ")}.`
+                : " Do not dispatch subagents.";
+            return `\`bash\` is limited to build/test verification commands. Writes restricted to \`.gsd/**\`.${subagentLine}`;
+        }
+        default:
+            return null;
+    }
+}
+function formatForbiddenWorkflowToolsLine(unitType, unitGuidance) {
+    const forbidden = getUnitToolSurfaceContract(unitType)?.forbiddenGsdTools;
+    if (!forbidden)
+        return null;
+    const names = Object.keys(forbidden).filter((name) => !unitGuidance?.includes(`\`${name}\``));
+    if (names.length === 0)
+        return null;
+    return `Do not call ${names.map((name) => `\`${name}\``).join(", ")} in this unit.`;
+}
+/**
+ * Render upfront tool-surface guidance for a unit type. Unknown units and
+ * unrestricted (`tools.mode: "all"`) units omit the block unless they have
+ * unit-specific closeout guidance registered above.
+ */
+export function composeToolSurfaceInstructions(unitType, opts) {
+    const manifest = resolveManifest(unitType);
+    if (!manifest)
+        return "";
+    const unitGuidance = TOOL_SURFACE_GUIDANCE_BY_UNIT[unitType];
+    const policyGuidance = unitGuidance ? null : guidanceForToolsPolicy(manifest.tools);
+    const forbiddenLine = formatForbiddenWorkflowToolsLine(unitType, unitGuidance);
+    const parts = [unitGuidance, policyGuidance, forbiddenLine].filter((part) => typeof part === "string" && part.length > 0);
+    if (parts.length === 0)
+        return "";
+    const body = parts.join(" ");
+    if (opts.renderMode === "nested") {
+        return `Tool surface: ${body}`;
+    }
+    return ["## Tool Surface", "", body].join("\n");
+}
 const SECTION_SEPARATOR = "\n\n---\n\n";
 /**
  * Compose all manifest-declared context for a unit type using the v2