@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.65546769

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

@@ -1,12 +1,17 @@
 // 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 { 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 { bashReferencesProjectRootOutsideWorktree } from "../worktree-shell-guard.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
@@ -16,6 +21,12 @@ import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.
 export const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
+function normalizeMilestoneId(milestoneId) {
+    const match = milestoneId.match(/^(M)(\d+)(?:-([a-z0-9]{6}))?$/i);
+    if (!match)
+        return milestoneId;
+    return `M${match[2]}${match[3] ? `-${match[3].toLowerCase()}` : ""}`;
+}
 /**
  * Path segment that identifies .gsd/ planning artifacts.
  * Writes to these paths are allowed during queue mode.
@@ -101,12 +112,6 @@ const GATE_QUESTION_PATTERNS = [
 const GATE_SAFE_TOOLS = new Set([
     "ask_user_questions",
 ]);
-export function canonicalToolName(toolName) {
-    if (!toolName.startsWith("mcp__"))
-        return toolName;
-    const toolSeparator = toolName.indexOf("__", "mcp__".length);
-    return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
-}
 /**
  * Persistence is ON by default (opt-out).
  * Set GSD_PERSIST_WRITE_GATE_STATE="0" or GSD_PERSIST_WRITE_GATE_STATE="false"
@@ -145,13 +150,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);
     }
@@ -167,6 +170,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;
@@ -181,7 +196,9 @@ function clearPersistedWriteGateSnapshot(basePath) {
 function normalizeWriteGateSnapshot(value) {
     const record = value && typeof value === "object" ? value : {};
     const verified = Array.isArray(record.verifiedDepthMilestones)
-        ? record.verifiedDepthMilestones.filter((item) => typeof item === "string")
+        ? record.verifiedDepthMilestones
+            .filter((item) => typeof item === "string")
+            .map(normalizeMilestoneId)
         : [];
     const verifiedGates = Array.isArray(record.verifiedApprovalGates)
         ? record.verifiedApprovalGates.filter((item) => typeof item === "string")
@@ -191,6 +208,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 = {
@@ -199,6 +217,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)) {
@@ -209,12 +235,112 @@ export function loadWriteGateSnapshot(basePath) {
             return EMPTY_SNAPSHOT;
         return currentWriteGateSnapshot(basePath);
     }
-    try {
-        return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
+    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(normalizeMilestoneId(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;
     }
-    catch {
+}
+function replaceStateFromSnapshot(state, snapshot) {
+    state.pendingGateId = snapshot.pendingGateId;
+    state.activeQueuePhase = snapshot.activeQueuePhase;
+    state.verifiedDepthMilestones = new Set(snapshot.verifiedDepthMilestones);
+    state.verifiedApprovalGates = new Set(snapshot.verifiedApprovalGates ?? []);
+}
+/**
+ * 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 currentWriteGateSnapshot(basePath);
+    const state = getWriteGateState(basePath);
+    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;
@@ -225,42 +351,46 @@ export function isDepthVerified(basePath = process.cwd()) {
 export function isMilestoneDepthVerified(milestoneId, basePath = process.cwd()) {
     if (!milestoneId)
         return false;
-    return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
+    refreshWriteGateStateFromDisk(basePath);
+    return getWriteGateState(basePath).verifiedDepthMilestones.has(normalizeMilestoneId(milestoneId));
 }
 export function isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId) {
     if (!milestoneId)
         return false;
-    return snapshot.verifiedDepthMilestones.includes(milestoneId);
+    return snapshot.verifiedDepthMilestones.includes(normalizeMilestoneId(milestoneId));
 }
 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)
@@ -279,39 +409,157 @@ export function isGateQuestionId(questionId) {
  */
 export function extractDepthVerificationMilestoneId(questionId) {
     const match = questionId.match(DEPTH_VERIFICATION_MILESTONE_RE);
-    return match?.[1] ?? null;
+    return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 /**
  * Extract the milestone ID from a milestone CONTEXT file path.
  */
 function extractContextMilestoneId(inputPath) {
     const match = inputPath.match(CONTEXT_MILESTONE_RE);
-    return match?.[1] ?? null;
+    return match?.[1] ? normalizeMilestoneId(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()) {
-    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(normalizeMilestoneId(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(normalizeMilestoneId(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
@@ -361,36 +609,140 @@ export function shouldBlockPendingGateBashInSnapshot(snapshot, command, _milesto
         ].join(" "),
     };
 }
+// 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 verifyAnsweredGate(basePath, question, fallbackMilestoneId) {
+    const gateId = typeof question.id === "string" ? question.id : "";
+    const milestoneId = extractDepthVerificationMilestoneId(gateId) ?? fallbackMilestoneId ?? null;
+    markApprovalGateVerified(gateId, basePath);
+    markDepthVerified(milestoneId, basePath);
+    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 };
+    if (verdict === "timeout") {
+        // Host elicitation expired before the user answered. The gate stays
+        // pending (fail-closed — a timeout is never approval), but the status is
+        // "timeout" so the caller pauses-and-waits instead of re-asking into the
+        // same timeout loop (#852).
+        return {
+            status: "timeout",
+            pendingGateId: gateId,
+            interrupted: details.interrupted === true,
+        };
+    }
+    // "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,
+    };
+}
 /**
- * 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.
+ * 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:
  *
- * @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
+ * - "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 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;
+export function applyAskUserQuestionsGateResult(options) {
+    const { basePath, questions, details, fallbackMilestoneId } = options;
+    const currentPendingGate = getPendingGate(basePath);
+    if (currentPendingGate) {
+        if (details.timed_out) {
+            // Host elicitation timed out before the user answered. Keep the gate
+            // pending (fail-closed) but report "timeout" so the caller pauses-and-
+            // waits instead of re-asking into the same timeout loop (#852).
+            return {
+                status: "timeout",
+                pendingGateId: currentPendingGate,
+                interrupted: details.interrupted === true,
+            };
+        }
+        if (details.cancelled || !details.response) {
+            return {
+                status: "waiting",
+                pendingGateId: currentPendingGate,
+                interrupted: details.interrupted === true,
+            };
+        }
+        const pendingQuestion = findGateQuestion(questions, currentPendingGate);
+        if (pendingQuestion) {
+            const verdict = evaluateGateAnswer(pendingQuestion, details);
+            if (verdict === "verified") {
+                return verifyAnsweredGate(basePath, pendingQuestion, fallbackMilestoneId);
+            }
+            return unresolvedGateResult(verdict, currentPendingGate, details);
+        }
     }
-    // Fail-closed: no options means we cannot structurally validate the answer.
-    // Returning false prevents any free-form string from unlocking the gate.
-    return false;
+    if (details.timed_out)
+        return { status: "not-gate" };
+    if (details.cancelled || !details.response)
+        return { status: "not-gate" };
+    for (const question of questions) {
+        if (typeof question.id !== "string" || !isGateQuestionId(question.id))
+            continue;
+        const verdict = evaluateGateAnswer(question, details);
+        if (verdict !== "verified") {
+            return unresolvedGateResult(verdict, question.id, details);
+        }
+        if (currentPendingGate && question.id !== 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);
+    }
+    return { status: "not-gate" };
+}
+export function formatPendingAskUserQuestionsGateMessage(pendingGateId, interrupted) {
+    return [
+        `Waiting for depth confirmation on gate "${pendingGateId}".`,
+        interrupted
+            ? "The confirmation question was interrupted before a response was recorded."
+            : "No user response was received for the confirmation question.",
+        "Do not infer approval from earlier or prior messages.",
+        "Do not proceed, write files, save artifacts, or call other tools.",
+        `Re-call ask_user_questions with the same gate question id ("${pendingGateId}") and wait for the user's response.`,
+    ].join(" ");
+}
+/**
+ * Format the LLM-facing message returned when a depth-confirmation gate
+ * elicitation times out. Distinct from {@link formatPendingAskUserQuestionsGateMessage}:
+ * a timeout must NOT tell the model to immediately re-ask (that re-triggers
+ * the same timeout loop). Instead it tells the model to stop, that auto-mode
+ * is paused, and that the user will respond on their own (#852).
+ */
+export function formatTimedOutAskUserQuestionsGateMessage(pendingGateId) {
+    return [
+        `Depth confirmation on gate "${pendingGateId}" timed out waiting for a response.`,
+        "The user did not answer within the host elicitation window — do not re-ask in this turn, it will time out again.",
+        "Auto-mode is paused. Stop calling tools and wait for the user to respond on a new turn.",
+        "When the user replies with confirmation, the gate will be satisfied and work will resume.",
+    ].join(" ");
 }
 export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queuePhaseActive, basePath = process.cwd()) {
     if (toolName !== "write")
         return { block: false };
     if (!MILESTONE_CONTEXT_RE.test(inputPath))
         return { block: false };
-    const targetMilestoneId = extractContextMilestoneId(inputPath) ?? milestoneId;
+    const targetMilestoneId = extractContextMilestoneId(inputPath) ?? (milestoneId ? normalizeMilestoneId(milestoneId) : null);
     if (!targetMilestoneId) {
         return {
             block: true,
@@ -408,8 +760,8 @@ export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queue
         reason: [
             `HARD BLOCK: Cannot write to milestone CONTEXT.md without depth verification.`,
             `This is a mechanical gate — you MUST NOT proceed, retry, or rationalize past this block.`,
-            `Required action: call ask_user_questions with question id containing "depth_verification".`,
-            `The user MUST select the "(Recommended)" confirmation option to unlock this gate.`,
+            `Required action: call ask_user_questions with question id "depth_verification_${targetMilestoneId}_confirm".`,
+            `The user MUST select the first "(Recommended)" confirmation option to unlock this gate.`,
             `If the user declines, cancels, or the tool fails, you must re-ask — not bypass.`,
         ].join(" "),
     };
@@ -811,6 +1163,30 @@ function isPathContained(target, container) {
         return true;
     return target.startsWith(container.endsWith(sep) ? container : container + sep);
 }
+function formatWorktreeIsolationBlockReason(tool, displayTarget, isAutoLive, effectiveBasePath) {
+    if (isGsdWorktreePath(effectiveBasePath)) {
+        return [
+            `HARD BLOCK: ${tool} target "${displayTarget}" is outside the active milestone worktree`,
+            `while \`git.isolation: worktree\` is configured. Source edits must stay inside`,
+            `\`.gsd-worktrees/<MID>/\` (or \`.gsd/\` planning artifacts) so the auto-mode commit`,
+            `pipeline captures them. Writing to the project root leaks changes that block milestone merge.`,
+            `Use a relative path under the worktree cwd or an absolute path inside the worktree directory.`,
+            ...(isAutoLive ? [] : [
+                "This guard also applies to subagent children spawned from the worktree — do not",
+                "`cd` to the project root or reference its paths in shell commands.",
+            ]),
+        ].join(" ");
+    }
+    return [
+        `HARD BLOCK: Worktree isolation is configured (\`git.isolation: worktree\`) but auto-mode is`,
+        `not running and the target "${displayTarget}" is not inside \`.gsd/worktrees/<MID>/\`.`,
+        `Code edits at the project root would be lost — only the auto-mode commit pipeline`,
+        `(auto-post-unit) commits work, and it never runs outside the loop.`,
+        `Required action: start auto-mode with \`/gsd\` so the milestone worktree is created,`,
+        `then write inside it. To disable this guard for self-hosting development, set`,
+        `GSD_DISABLE_WORKTREE_WRITE_GUARD=1.`,
+    ].join(" ");
+}
 /**
  * Block planning-write tool calls that would land code at the project root
  * while `git.isolation: worktree` is in effect and auto-mode hasn't created
@@ -828,10 +1204,9 @@ function isPathContained(target, container) {
  *   5. Target is inside `<projectRoot>/.gsd/worktrees/` (a real worktree).
  *   6. Target is inside `<projectRoot>/.gsd/` and isn't masquerading as a
  *      worktrees sibling (rejects the `.gsd/worktrees-extra/…` prefix trick).
- *   7. Auto is live AND `effectiveBasePath` is itself a `.gsd/worktrees/…` path.
  *
- * Otherwise: block with a message that points the agent at `/gsd` to start
- * auto-mode.
+ * Otherwise: block with a message that points the agent at the active worktree
+ * or `/gsd` to start auto-mode.
  */
 export function shouldBlockWorktreeWrite(toolName, targetPath, effectiveBasePath, isAutoLive, currentUnitType) {
     const tool = canonicalToolName(toolName);
@@ -860,10 +1235,12 @@ export function shouldBlockWorktreeWrite(toolName, targetPath, effectiveBasePath
     const realTarget = realpathOrResolve(absTarget);
     const realRoot = realpathOrResolve(projectRoot);
     const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));
-    const realWorktreesDir = realpathOrResolve(join(projectRoot, ".gsd", "worktrees"));
-    // Allow writes inside the legitimate worktrees subtree.
-    if (isPathContained(realTarget, realWorktreesDir))
-        return { block: false };
+    // Allow writes inside a legitimate worktrees subtree (canonical
+    // .gsd-worktrees/ or legacy .gsd/worktrees/).
+    for (const container of worktreesDirs(projectRoot)) {
+        if (isPathContained(realTarget, realpathOrResolve(container)))
+            return { block: false };
+    }
     // Allow writes to .gsd/ planning artifacts, but reject siblings whose name
     // starts with "worktrees" (the worktrees-extra prefix trick — case 4).
     if (isPathContained(realTarget, realGsd)) {
@@ -873,24 +1250,40 @@ export function shouldBlockWorktreeWrite(toolName, targetPath, effectiveBasePath
             return { block: false };
         // fall through: looks like worktrees<something> sibling — block
     }
-    // Auto is live and the caller is operating inside a worktree path —
-    // host tool's write happens in worktree context; let it through.
-    if (isAutoLive && isGsdWorktreePath(effectiveBasePath))
-        return { block: false };
     // Block. Provide enough context that the agent can self-correct.
     const displayTarget = isPathContained(realTarget, realRoot)
         ? relative(realRoot, realTarget) || "."
         : realTarget;
     return {
         block: true,
-        reason: [
-            `HARD BLOCK: Worktree isolation is configured (\`git.isolation: worktree\`) but auto-mode is`,
-            `not running and the target "${displayTarget}" is not inside \`.gsd/worktrees/<MID>/\`.`,
-            `Code edits at the project root would be lost — only the auto-mode commit pipeline`,
-            `(auto-post-unit) commits work, and it never runs outside the loop.`,
-            `Required action: start auto-mode with \`/gsd\` so the milestone worktree is created,`,
-            `then write inside it. To disable this guard for self-hosting development, set`,
-            `GSD_DISABLE_WORKTREE_WRITE_GUARD=1.`,
-        ].join(" "),
+        reason: formatWorktreeIsolationBlockReason(tool, displayTarget, isAutoLive, effectiveBasePath),
+    };
+}
+/**
+ * Block bash commands that reference the project root while executing inside an
+ * active milestone worktree under `git.isolation: worktree`.
+ *
+ * Mirrors the gsd_exec sandbox rule so native bash cannot bypass write/edit gates.
+ */
+export function shouldBlockWorktreeBash(command, effectiveBasePath, isAutoLive, currentUnitType) {
+    if (process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD === "1")
+        return { block: false };
+    if (getIsolationMode(effectiveBasePath) !== "worktree")
+        return { block: false };
+    if (currentUnitType && WORKTREE_GATE_BOOTSTRAP_UNITS.has(currentUnitType))
+        return { block: false };
+    // Block whenever the effective cwd is inside a milestone worktree — not only
+    // during live auto-mode. Reactive-execute subagents run as fresh pi children
+    // without an auto session, but still inherit the worktree cwd and must not
+    // shell out to the project root (the native bash bypass that caused root-write leaks).
+    if (!isGsdWorktreePath(effectiveBasePath))
+        return { block: false };
+    if (!command.trim())
+        return { block: false };
+    if (!bashReferencesProjectRootOutsideWorktree(command, effectiveBasePath))
+        return { block: false };
+    return {
+        block: true,
+        reason: formatWorktreeIsolationBlockReason("bash", "project root path reference in shell command", isAutoLive, effectiveBasePath),
     };
 }