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

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,14 +1,16 @@
 // gsd-pi - Write gate runtime persistence and policy guards.
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
 import { GSD_PHASE_SCOPE_DISPLAY_REASON, shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
-import { stripMcpToolPrefix } from "../mcp-tool-name.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
+import { loadJsonFileOrNull } from "../json-persistence.js";
 import { getIsolationMode } from "../preferences.js";
 import { compileSubagentPermissionContract } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { worktreesDirs } from "../worktree-placement.js";
+import { evaluateGateAnswer } from "../consent-verdict.js";
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
  * and unique M001-abc123 formats. Exported so regex-hardening tests
@@ -103,9 +105,6 @@ const GATE_QUESTION_PATTERNS = [
 const GATE_SAFE_TOOLS = new Set([
     "ask_user_questions",
 ]);
-export function canonicalToolName(toolName) {
-    return stripMcpToolPrefix(toolName);
-}
 /**
  * Persistence is ON by default (opt-out).
  * Set GSD_PERSIST_WRITE_GATE_STATE="0" or GSD_PERSIST_WRITE_GATE_STATE="false"
@@ -144,13 +143,11 @@ function currentWriteGateSnapshot(basePath = process.cwd()) {
         pendingGateId: state.pendingGateId,
     };
 }
-function persistWriteGateSnapshot(basePath) {
-    if (!shouldPersistWriteGateSnapshot())
-        return;
+function writeSnapshotFileAtomic(basePath, snapshot) {
     const path = writeGateSnapshotPath(basePath);
     ensureWriteGateSnapshotDirectory(basePath);
     const tempPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
-    writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(basePath), null, 2), "utf-8");
+    writeFileSync(tempPath, JSON.stringify(snapshot, null, 2), "utf-8");
     try {
         renameSync(tempPath, path);
     }
@@ -166,6 +163,18 @@ function persistWriteGateSnapshot(basePath) {
         }
     }
 }
+/**
+ * Persist the current in-memory state for `basePath`, stamped with the
+ * writer provenance tag. Callers (mutateWriteGateState / childMutate) are
+ * responsible for first reconciling in-memory content against the disk
+ * snapshot — the read-merge-write sequence is synchronous, so a concurrent
+ * writer's update is folded in by that unconditional pre-persist read.
+ */
+function persistWriteGateSnapshot(basePath, writer) {
+    if (!shouldPersistWriteGateSnapshot())
+        return;
+    writeSnapshotFileAtomic(basePath, { ...currentWriteGateSnapshot(basePath), writer });
+}
 function clearPersistedWriteGateSnapshot(basePath) {
     if (!shouldPersistWriteGateSnapshot())
         return;
@@ -190,6 +199,7 @@ function normalizeWriteGateSnapshot(value) {
         verifiedApprovalGates: [...new Set(verifiedGates)].sort(),
         activeQueuePhase: record.activeQueuePhase === true,
         pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null,
+        ...(record.writer === "host" || record.writer === "child" ? { writer: record.writer } : {}),
     };
 }
 const EMPTY_SNAPSHOT = {
@@ -198,6 +208,14 @@ const EMPTY_SNAPSHOT = {
     activeQueuePhase: false,
     pendingGateId: null,
 };
+/**
+ * Read the snapshot file as it exists on disk. Returns null when the file
+ * is missing or unparseable (no in-memory fallback — callers decide).
+ */
+function readDiskSnapshot(basePath) {
+    const raw = loadJsonFileOrNull(writeGateSnapshotPath(basePath), (data) => typeof data === "object" && data !== null);
+    return raw === null ? null : normalizeWriteGateSnapshot(raw);
+}
 export function loadWriteGateSnapshot(basePath) {
     const path = writeGateSnapshotPath(basePath);
     if (!existsSync(path)) {
@@ -208,29 +226,112 @@ export function loadWriteGateSnapshot(basePath) {
             return EMPTY_SNAPSHOT;
         return currentWriteGateSnapshot(basePath);
     }
-    try {
-        return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
-    }
-    catch {
-        return currentWriteGateSnapshot(basePath);
+    const disk = readDiskSnapshot(basePath);
+    return disk ?? currentWriteGateSnapshot(basePath);
+}
+/**
+ * Reconcile a disk snapshot into the in-memory state. This is THE merge
+ * rule for the two-process seam:
+ *
+ *   - verifications are a grow-only union: a milestone/gate verified by
+ *     either process is never lost to a stale write from the other;
+ *   - activeQueuePhase and pendingGateId take the disk value (last writer
+ *     wins — matches the long-standing refresh semantics, and keeps
+ *     "delete the snapshot file to clear the HARD BLOCK" working);
+ *   - verified wins over pending: if the merged verified sets already cover
+ *     the pending gate (gate id verified, or its depth milestone verified),
+ *     the pending re-arm is dropped. This generalizes the ad-hoc re-arm
+ *     guard that previously protected only the tool_execution_start window.
+ */
+function mergeSnapshotIntoState(state, disk) {
+    for (const milestone of disk.verifiedDepthMilestones)
+        state.verifiedDepthMilestones.add(milestone);
+    for (const gate of disk.verifiedApprovalGates ?? [])
+        state.verifiedApprovalGates.add(gate);
+    state.activeQueuePhase = disk.activeQueuePhase;
+    state.pendingGateId = disk.pendingGateId;
+    dropVerifiedPendingGate(state);
+}
+/** Verified-on-disk wins over a pending re-arm (see mergeSnapshotIntoState). */
+function dropVerifiedPendingGate(state) {
+    const pending = state.pendingGateId;
+    if (!pending)
+        return;
+    const milestoneId = extractDepthVerificationMilestoneId(pending);
+    if (state.verifiedApprovalGates.has(pending) ||
+        (milestoneId !== null && state.verifiedDepthMilestones.has(milestoneId))) {
+        state.pendingGateId = null;
     }
 }
+function replaceStateFromSnapshot(state, snapshot) {
+    state.pendingGateId = snapshot.pendingGateId;
+    state.activeQueuePhase = snapshot.activeQueuePhase;
+    state.verifiedDepthMilestones = new Set(snapshot.verifiedDepthMilestones);
+    state.verifiedApprovalGates = new Set(snapshot.verifiedApprovalGates ?? []);
+}
 /**
- * Merge the persisted write-gate snapshot into the in-process Map entry.
+ * Reconcile the persisted write-gate snapshot into the in-process Map entry.
  * The workflow MCP server runs in a child process and records depth
  * verification there; without this refresh the extension host keeps stale
  * pending-gate memory and `activateDeferredApprovalGate` can re-arm a gate
  * that the subprocess already cleared on disk.
+ *
+ * Uses the union merge rule (mergeSnapshotIntoState) when a readable
+ * snapshot file exists; a missing or unparseable file is a full reset
+ * (replace with empty) so deleting the file still clears all gate state,
+ * and a corrupt file does not leave stale `pendingGateId` in memory for
+ * the next mutation to persist back.
+ *
+ * Returns the reconciled snapshot so callers that need to inspect it
+ * (e.g. re-arm guards) avoid a second disk read.
  */
 export function refreshWriteGateStateFromDisk(basePath) {
     if (!shouldPersistWriteGateSnapshot())
-        return;
-    const snapshot = loadWriteGateSnapshot(basePath);
+        return currentWriteGateSnapshot(basePath);
     const state = getWriteGateState(basePath);
-    state.pendingGateId = snapshot.pendingGateId;
-    state.activeQueuePhase = snapshot.activeQueuePhase;
-    state.verifiedDepthMilestones = new Set(snapshot.verifiedDepthMilestones);
-    state.verifiedApprovalGates = new Set(snapshot.verifiedApprovalGates ?? []);
+    const disk = readDiskSnapshot(basePath);
+    if (disk) {
+        mergeSnapshotIntoState(state, disk);
+    }
+    else {
+        replaceStateFromSnapshot(state, EMPTY_SNAPSHOT);
+    }
+    return currentWriteGateSnapshot(basePath);
+}
+/**
+ * Read-modify-write primitive for gate mutations. Reconciles the disk
+ * snapshot into memory (union merge), applies the mutation on top, then
+ * persists. The whole sequence is synchronous, so the reconcile read
+ * doubles as the pre-persist merge of concurrent writes — there is no
+ * version field; the read-merge-write is simply unconditional.
+ *
+ * The mutate callback sees the already-reconciled state, so policy checks
+ * (e.g. host setPending's verified-on-disk-wins guard) can live inside it
+ * without a second disk read. Returning `false` from the callback aborts:
+ * nothing is persisted and this function returns false.
+ *
+ * `reconcile: false` skips the disk merge — used for intentional full
+ * resets where re-unioning disk verifications would defeat the reset.
+ */
+function mutateWriteGateState(basePath, mutate, opts) {
+    const state = getWriteGateState(basePath);
+    if (shouldPersistWriteGateSnapshot() && (opts?.reconcile ?? true)) {
+        const disk = readDiskSnapshot(basePath);
+        if (disk) {
+            mergeSnapshotIntoState(state, disk);
+        }
+        else {
+            // Missing OR unparseable on disk: treat as a full reset. Keeping
+            // stale in-memory state across a corrupt snapshot would persist it
+            // back on this very mutation and defeat the documented
+            // "delete the file to clear the HARD BLOCK gate" escape hatch.
+            replaceStateFromSnapshot(state, EMPTY_SNAPSHOT);
+        }
+    }
+    if (mutate(state) === false)
+        return false;
+    persistWriteGateSnapshot(basePath, opts?.writer ?? defaultWriteGateWriter());
+    return true;
 }
 export function isDepthVerified(basePath = process.cwd()) {
     return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;
@@ -253,31 +354,34 @@ export function isQueuePhaseActive(basePath = process.cwd()) {
     return getWriteGateState(basePath).activeQueuePhase;
 }
 export function setQueuePhaseActive(active, basePath) {
-    getWriteGateState(basePath).activeQueuePhase = active;
-    persistWriteGateSnapshot(basePath);
+    mutateWriteGateState(basePath, (state) => {
+        state.activeQueuePhase = active;
+    });
 }
 export function resetWriteGateState(basePath) {
-    const state = getWriteGateState(basePath);
-    state.verifiedDepthMilestones.clear();
-    state.verifiedApprovalGates.clear();
-    state.pendingGateId = null;
-    persistWriteGateSnapshot(basePath);
+    mutateWriteGateState(basePath, (state) => {
+        state.verifiedDepthMilestones.clear();
+        state.verifiedApprovalGates.clear();
+        state.pendingGateId = null;
+    }, { reconcile: false });
 }
 export function clearDiscussionFlowState(basePath) {
     writeGateStatesByBasePath.delete(writeGateStateKey(basePath));
     clearPersistedWriteGateSnapshot(basePath);
 }
+/**
+ * Ambient (env-sniffed) export, reserved for the child's dynamic-import
+ * surface (packages/mcp-server) and module-internal use. Host-owned modules
+ * (register-hooks, auto-dispatch, …) must call
+ * hostWriteGateAdapter.markDepthVerified explicitly so a leaked
+ * GSD_WORKFLOW_* env variable cannot silently flip them to child semantics.
+ */
 export function markDepthVerified(milestoneId, basePath = process.cwd()) {
-    if (!milestoneId)
-        return;
-    getWriteGateState(basePath).verifiedDepthMilestones.add(milestoneId);
-    persistWriteGateSnapshot(basePath);
+    defaultWriteGateAdapter().markDepthVerified(milestoneId, basePath);
 }
+/** Ambient export for the child's dynamic-import surface — see markDepthVerified. */
 export function markApprovalGateVerified(gateId, basePath = process.cwd()) {
-    if (!gateId)
-        return;
-    getWriteGateState(basePath).verifiedApprovalGates.add(gateId);
-    persistWriteGateSnapshot(basePath);
+    defaultWriteGateAdapter().markApprovalGateVerified(gateId, basePath);
 }
 export function isApprovalGateVerifiedInSnapshot(snapshot, gateId) {
     if (!gateId)
@@ -306,30 +410,147 @@ function extractContextMilestoneId(inputPath) {
     return match?.[1] ?? null;
 }
 /**
- * Mark a gate as pending (called when ask_user_questions is invoked with a gate ID).
+ * Mark a gate as pending (called when ask_user_questions is invoked with a
+ * gate ID). Delegates to the process's default adapter: in the workflow MCP
+ * child the arm is unconditional (a fresh question intentionally revokes
+ * prior verification); in the host the adapter's verified-on-disk-wins
+ * guard applies and a suppressed arm returns false.
+ *
+ * Ambient (env-sniffed) export, reserved for the child's dynamic-import
+ * surface (packages/mcp-server). Host-owned modules must call
+ * hostWriteGateAdapter.setPending explicitly.
  */
 export function setPendingGate(gateId, basePath) {
-    const state = getWriteGateState(basePath);
+    return defaultWriteGateAdapter().setPending(gateId, basePath);
+}
+/** Arm `gateId` on a reconciled state, revoking its prior verification. */
+function armPendingGate(state, gateId) {
     state.pendingGateId = gateId;
     state.verifiedApprovalGates.delete(gateId);
     const milestoneId = extractDepthVerificationMilestoneId(gateId);
     if (milestoneId)
         state.verifiedDepthMilestones.delete(milestoneId);
-    persistWriteGateSnapshot(basePath);
 }
 /**
  * Clear the pending gate (called when the user confirms).
+ * Ambient export for the child's dynamic-import surface — host-owned
+ * modules must call hostWriteGateAdapter.clearPending explicitly.
  */
 export function clearPendingGate(basePath) {
-    getWriteGateState(basePath).pendingGateId = null;
-    persistWriteGateSnapshot(basePath);
+    defaultWriteGateAdapter().clearPending(basePath);
 }
 /**
  * Get the currently pending gate, if any.
+ * Ambient export for the child's dynamic-import surface — host-owned
+ * modules should prefer hostWriteGateAdapter.readState.
  */
 export function getPendingGate(basePath = process.cwd()) {
-    refreshWriteGateStateFromDisk(basePath);
-    return getWriteGateState(basePath).pendingGateId;
+    return defaultWriteGateAdapter().readState(basePath).pendingGateId;
+}
+/**
+ * HOST adapter: in-memory state + reconcile-on-read. Disk verifications are
+ * never lost (union merge), and a gate verified on disk wins over an
+ * in-memory pending re-arm — setPending refuses to clobber a verification
+ * the child already recorded. This generalizes the ad-hoc re-arm guard that
+ * previously protected only the tool_execution_start window in
+ * register-hooks.ts.
+ */
+export const hostWriteGateAdapter = {
+    writer: "host",
+    readState(basePath) {
+        return refreshWriteGateStateFromDisk(basePath);
+    },
+    markDepthVerified(milestoneId, basePath) {
+        if (!milestoneId)
+            return;
+        mutateWriteGateState(basePath, (state) => {
+            state.verifiedDepthMilestones.add(milestoneId);
+        }, { writer: "host" });
+    },
+    markApprovalGateVerified(gateId, basePath) {
+        if (!gateId)
+            return;
+        mutateWriteGateState(basePath, (state) => {
+            state.verifiedApprovalGates.add(gateId);
+        }, { writer: "host" });
+    },
+    setPending(gateId, basePath) {
+        // The verified-check runs inside the mutate callback so the single
+        // reconcile read in mutateWriteGateState serves both the guard and the
+        // pre-persist merge. A suppressed arm aborts without persisting.
+        return mutateWriteGateState(basePath, (state) => {
+            if (state.verifiedApprovalGates.has(gateId))
+                return false;
+            const milestoneId = extractDepthVerificationMilestoneId(gateId);
+            if (milestoneId && state.verifiedDepthMilestones.has(milestoneId))
+                return false;
+            armPendingGate(state, gateId);
+        }, { writer: "host" });
+    },
+    clearPending(basePath) {
+        mutateWriteGateState(basePath, (state) => {
+            state.pendingGateId = null;
+        }, { writer: "host" });
+    },
+};
+/**
+ * CHILD adapter: write-through with always-fresh reads — load the disk
+ * snapshot, mutate, persist. No cross-turn in-memory state is trusted: the
+ * in-process Map entry is replaced from disk before every mutation so a
+ * long-lived MCP child never resurrects state the host has since changed.
+ */
+export const childWriteGateAdapter = {
+    writer: "child",
+    readState(basePath) {
+        return loadWriteGateSnapshot(basePath);
+    },
+    markDepthVerified(milestoneId, basePath) {
+        if (!milestoneId)
+            return;
+        childMutate(basePath, (state) => {
+            state.verifiedDepthMilestones.add(milestoneId);
+        });
+    },
+    markApprovalGateVerified(gateId, basePath) {
+        if (!gateId)
+            return;
+        childMutate(basePath, (state) => {
+            state.verifiedApprovalGates.add(gateId);
+        });
+    },
+    setPending(gateId, basePath) {
+        childMutate(basePath, (state) => armPendingGate(state, gateId));
+        return true;
+    },
+    clearPending(basePath) {
+        childMutate(basePath, (state) => {
+            state.pendingGateId = null;
+        });
+    },
+};
+function childMutate(basePath, mutate) {
+    const state = getWriteGateState(basePath);
+    if (shouldPersistWriteGateSnapshot()) {
+        // Always-fresh: disk is the only truth for the child; discard any
+        // cross-turn in-memory residue before mutating.
+        replaceStateFromSnapshot(state, readDiskSnapshot(basePath) ?? EMPTY_SNAPSHOT);
+    }
+    mutate(state);
+    persistWriteGateSnapshot(basePath, "child");
+}
+/**
+ * Which adapter the module-level convenience exports (markDepthVerified,
+ * setPendingGate, …) delegate to. The workflow MCP child is spawned with
+ * GSD_WORKFLOW_WRITE_GATE_MODULE / GSD_WORKFLOW_PROJECT_ROOT in its
+ * environment (workflow-mcp.ts), so when this module is dynamically imported
+ * inside that process the child adapter is selected automatically; the
+ * extension host process has neither variable and stays on the host adapter.
+ */
+export function defaultWriteGateWriter(env = process.env) {
+    return env.GSD_WORKFLOW_WRITE_GATE_MODULE || env.GSD_WORKFLOW_PROJECT_ROOT ? "child" : "host";
+}
+function defaultWriteGateAdapter() {
+    return defaultWriteGateWriter() === "child" ? childWriteGateAdapter : hostWriteGateAdapter;
 }
 /**
  * Check whether a tool call should be blocked because a discussion gate
@@ -379,36 +600,15 @@ export function shouldBlockPendingGateBashInSnapshot(snapshot, command, _milesto
         ].join(" "),
     };
 }
-/**
- * Check whether a depth_verification answer confirms the discussion is complete.
- * Uses structural validation: the selected answer must exactly match the first
- * option label from the question definition (the confirmation option by convention).
- * This rejects free-form "Other" text, decline options, and garbage input without
- * coupling to any specific label substring.
- *
- * @param selected  The answer's selected value from details.response.answers[id].selected
- * @param options   The question's options array from event.input.questions[n].options
- */
-export function isDepthConfirmationAnswer(selected, options) {
-    const value = Array.isArray(selected) ? selected[0] : selected;
-    if (typeof value !== "string" || !value)
-        return false;
-    // If options are available, structurally validate: selected must exactly match
-    // the first option (confirmation) label. Rejects free-form "Other" and decline options.
-    if (Array.isArray(options) && options.length > 0) {
-        const confirmLabel = options[0]?.label;
-        return typeof confirmLabel === "string" && value === confirmLabel;
-    }
-    // Fail-closed: no options means we cannot structurally validate the answer.
-    // Returning false prevents any free-form string from unlocking the gate.
-    return false;
-}
+// The structural depth-confirmation validator lives in the consent-verdict
+// leaf (../consent-verdict.ts) so the write gate and the Consent Question
+// module share one verdict engine without an import cycle. Re-exported here
+// because the workflow MCP child loads this module by dist path and validates
+// the function is present (packages/mcp-server/src/server.ts).
+export { isDepthConfirmationAnswer } from "../consent-verdict.js";
 function findGateQuestion(questions, gateId) {
     return questions.find((question) => question?.id === gateId);
 }
-function readSelectedGateAnswer(details, questionId) {
-    return details.response?.answers?.[questionId]?.selected;
-}
 function verifyAnsweredGate(basePath, question, fallbackMilestoneId) {
     const gateId = typeof question.id === "string" ? question.id : "";
     const milestoneId = extractDepthVerificationMilestoneId(gateId) ?? fallbackMilestoneId ?? null;
@@ -417,6 +617,30 @@ function verifyAnsweredGate(basePath, question, fallbackMilestoneId) {
     clearPendingGate(basePath);
     return { status: "verified", gateId, milestoneId };
 }
+/** Map an unresolved (non-verified) gate verdict to the caller-facing result. */
+function unresolvedGateResult(verdict, gateId, details) {
+    if (verdict === "declined")
+        return { status: "declined", gateId };
+    // "waiting" (and the unreachable post-cancel case): an empty selection is
+    // not an answer — keep the gate pending and make the caller pause.
+    return {
+        status: "waiting",
+        pendingGateId: gateId,
+        interrupted: details.interrupted === true,
+    };
+}
+/**
+ * Apply an ask_user_questions round to durable gate state. The per-question
+ * VERDICT comes from the consent-verdict leaf (evaluateGateAnswer) — the same
+ * engine the Consent Question module uses — so write-gate only owns the
+ * persistence/arming side effects:
+ *
+ * - "verified" verdict → markApprovalGateVerified/markDepthVerified/clearPendingGate.
+ * - "declined" verdict → no state change; the gate (if armed) stays pending.
+ * - "waiting" verdict (empty/missing selection) → no state change; reported as
+ *   "waiting" so callers pause instead of proceeding (fail-closed; an empty
+ *   answer is never an answer).
+ */
 export function applyAskUserQuestionsGateResult(options) {
     const { basePath, questions, details, fallbackMilestoneId } = options;
     const currentPendingGate = getPendingGate(basePath);
@@ -430,11 +654,11 @@ export function applyAskUserQuestionsGateResult(options) {
         }
         const pendingQuestion = findGateQuestion(questions, currentPendingGate);
         if (pendingQuestion) {
-            const selected = readSelectedGateAnswer(details, currentPendingGate);
-            if (isDepthConfirmationAnswer(selected, pendingQuestion.options)) {
+            const verdict = evaluateGateAnswer(pendingQuestion, details);
+            if (verdict === "verified") {
                 return verifyAnsweredGate(basePath, pendingQuestion, fallbackMilestoneId);
             }
-            return { status: "answered", gateId: currentPendingGate };
+            return unresolvedGateResult(verdict, currentPendingGate, details);
         }
     }
     if (details.cancelled || !details.response)
@@ -442,12 +666,14 @@ export function applyAskUserQuestionsGateResult(options) {
     for (const question of questions) {
         if (typeof question.id !== "string" || !isGateQuestionId(question.id))
             continue;
-        const selected = readSelectedGateAnswer(details, question.id);
-        if (!isDepthConfirmationAnswer(selected, question.options)) {
-            return { status: "answered", gateId: question.id };
+        const verdict = evaluateGateAnswer(question, details);
+        if (verdict !== "verified") {
+            return unresolvedGateResult(verdict, question.id, details);
         }
         if (currentPendingGate && question.id !== currentPendingGate) {
-            return { status: "answered", gateId: currentPendingGate };
+            // A different gate than the armed one was confirmed — the armed gate is
+            // still unresolved, so do not verify and let discussion continue.
+            return { status: "declined", gateId: currentPendingGate };
         }
         return verifyAnsweredGate(basePath, question, fallbackMilestoneId);
     }

package/dist/resources/extensions/gsd/branch-patterns.js

@@ -11,3 +11,5 @@ export const SLICE_BRANCH_RE = /^gsd\/(?:([a-zA-Z0-9_-]+)\/)?(M\d+(?:-[a-z0-9]{6
 export const QUICK_BRANCH_RE = /^gsd\/quick\//;
 /** Matches GSD-generated workflow template branches, not arbitrary user gsd/* branches. */
 export const WORKFLOW_BRANCH_RE = /^gsd\/(?:hotfix|bugfix|small-feature|refactor|spike|security-audit|dep-upgrade|full-project)\//;
+/** Auto-mode milestone branch prefix: milestone/<MID>. */
+export const MILESTONE_BRANCH_PREFIX = "milestone/";

package/dist/resources/extensions/gsd/browser-daemon-auto-prep.js

@@ -0,0 +1,83 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { resolveAmbientBrowserEngineResolution, resolveBrowserEngineResolution, } from "../browser-tools/engine/selection.js";
+import { resolveGsdBrowserCliAvailability, resolveGsdBrowserDaemonStartInvocation, } from "../shared/gsd-browser-cli.js";
+import { uatTypeIncludesBrowser } from "./uat-policy.js";
+const DEFAULT_DAEMON_START_TIMEOUT_MS = 30_000;
+function isEnvDisabled(value) {
+    if (!value)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "0" || normalized === "false" || normalized === "off";
+}
+function isWarmUpDisabled(env = process.env) {
+    const value = env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
+    return value === "0" || value === "false" || value === "off";
+}
+/** Active engine for warm-up: explicit env override, else session-committed ambient resolution. */
+function resolveActiveBrowserEngine(projectRoot, env) {
+    if (env.GSD_BROWSER_ENGINE?.trim()) {
+        return resolveBrowserEngineResolution(env, projectRoot).engine;
+    }
+    return resolveAmbientBrowserEngineResolution(projectRoot).engine;
+}
+export function shouldWarmBrowserDaemonForUat(ctx) {
+    if (!uatTypeIncludesBrowser(ctx.uatType))
+        return false;
+    const env = ctx.env ?? process.env;
+    if (isWarmUpDisabled(env))
+        return false;
+    if (isEnvDisabled(env.GSD_BROWSER_MCP_ENABLED))
+        return false;
+    const availability = resolveGsdBrowserCliAvailability(env);
+    if (!availability.available)
+        return false;
+    const projectRoot = resolve(ctx.projectRoot);
+    return resolveActiveBrowserEngine(projectRoot, env) === "gsd-browser";
+}
+export function ensureBrowserDaemonStarted(projectRoot, options = {}) {
+    const env = options.env ?? process.env;
+    const availability = resolveGsdBrowserCliAvailability(env);
+    if (!availability.available) {
+        return { ok: false, error: availability.detail };
+    }
+    let invocation;
+    try {
+        invocation = resolveGsdBrowserDaemonStartInvocation(projectRoot, env);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        execFileSync(invocation.command, invocation.args, {
+            cwd: invocation.cwd,
+            env: { ...process.env, ...env, ...(invocation.env ?? {}) },
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: options.timeoutMs ?? DEFAULT_DAEMON_START_TIMEOUT_MS,
+            encoding: "utf-8",
+        });
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Best-effort pre-warm of the gsd-browser session daemon before browser-backed
+ * run-uat dispatch. Returns an actionable stop reason when warm-up is required
+ * but fails; returns null when warm-up is skipped or succeeds.
+ */
+export function prepareBrowserDaemonForUat(ctx) {
+    if (!shouldWarmBrowserDaemonForUat(ctx))
+        return null;
+    const result = ensureBrowserDaemonStarted(ctx.projectRoot, { env: ctx.env });
+    if (result.ok)
+        return null;
+    return `Cannot dispatch browser-backed run-uat: gsd-browser daemon failed to start (${result.error}). Ensure Chrome/Chromium is installed, run \`gsd-browser daemon health\` with the project session flags from .mcp.json, or set GSD_BROWSER_PATH to a Chromium binary.`;
+}

package/dist/resources/extensions/gsd/browser-evidence.js

@@ -1,8 +1,14 @@
 // Project/App: gsd-pi
 // File Purpose: Shared browser-observable UAT requirement and evidence detection.
-export const BROWSER_REQUIREMENT_RE = /\b(?:file:\/\/|localhost|playwright|chrome|screenshot|snapshot|browser_(?:assert|batch|find|verify|snapshot_refs))\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file:\/\/)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b/i;
+import { BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES } from "../shared/browser-contract.js";
+// Alternation fragment over the contract's evidence-signal names, e.g.
+// `browser_(?:assert|batch|...)`. The names are `browser_`-prefixed
+// identifiers (pinned by tests/browser-contract.test.ts), so no escaping is
+// needed.
+const BROWSER_TOOL_SIGNAL = `browser_(?:${BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES.map((name) => name.slice("browser_".length)).join("|")})`;
+export const BROWSER_REQUIREMENT_RE = new RegExp(String.raw `\b(?:file://|localhost|playwright|chrome|screenshot|snapshot|${BROWSER_TOOL_SIGNAL})\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file://)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b`, "i");
 export const NO_BROWSER_EVIDENCE_RE = /\b(?:no|without|not|wasn'?t|isn'?t)\s+(?:automated\s+)?(?:live\s+)?browser(?:\s+(?:session|test|uat))?|\bno\s+automated\s+browser\b|\bnot\s+conducted\b/i;
-export const BROWSER_RUNTIME_RE = /\b(?:browser|playwright|chrome|camoufox|browser_(?:assert|batch|find|verify|snapshot_refs)|screenshot|snapshot|file:\/\/|localhost)\b/i;
+export const BROWSER_RUNTIME_RE = new RegExp(String.raw `\b(?:browser|playwright|chrome|camoufox|${BROWSER_TOOL_SIGNAL}|screenshot|snapshot|file://|localhost)\b`, "i");
 export const BROWSER_ACTION_RE = /\b(?:open(?:ed)?|navigate(?:d)?|click(?:ed)?|type(?:d)?|reload(?:ed)?|capture(?:d)?|screenshot|snapshot)\b/i;
 export const BROWSER_ASSERTION_RE = /\b(?:assert(?:ed|ion)?|observed|confirmed|verified|expected|visible|text|count|label|strikethrough|localstorage|screenshot|snapshot|passed)\b/i;
 const NON_REQUIREMENT_BROWSER_HEADING_RE = /^(?:not\s+proven|not\s+covered|out\s+of\s+scope|deferred|follow-?ups?|known\s+limitations|notes\s+for\s+tester)\b/i;

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

@@ -11,7 +11,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { gsdRoot } from "./paths.js";
-import { findWorktreeSegment } from "./worktree-root.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CAPTURES_FILENAME = "CAPTURES.md";
 const VALID_CLASSIFICATIONS = [
@@ -30,11 +30,9 @@ const VALID_CLASSIFICATIONS = [
  * directory that contains `.gsd/worktrees/` — that's the project root.
  */
 export function resolveCapturesPath(basePath) {
-    const resolved = resolve(basePath);
-    const segment = findWorktreeSegment(resolved.replaceAll("\\", "/"));
-    if (segment) {
-        // basePath is inside a worktree — resolve to project root
-        const projectRoot = resolved.slice(0, segment.gsdIdx);
+    // If basePath is inside a worktree, resolve to the project root.
+    const projectRoot = projectRootFromWorktreePath(resolve(basePath));
+    if (projectRoot) {
         return join(projectRoot, ".gsd", CAPTURES_FILENAME);
     }
     return join(gsdRoot(basePath), CAPTURES_FILENAME);