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

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -1,14 +1,19 @@
 // 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, type ToolsPolicy } 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
@@ -20,6 +25,12 @@ 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: string): string {
+  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.
@@ -122,17 +133,20 @@ const GATE_SAFE_TOOLS = new Set([
   "ask_user_questions",
 ]);
 
-export function canonicalToolName(toolName: string): string {
-  if (!toolName.startsWith("mcp__")) return toolName;
-  const toolSeparator = toolName.indexOf("__", "mcp__".length);
-  return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
-}
+/**
+ * Which process wrote a snapshot. Two processes share the snapshot file:
+ * the extension host ("host") and the workflow MCP child ("child"), which
+ * dynamically imports this same compiled module in its own process.
+ */
+export type WriteGateWriter = "host" | "child";
 
 export interface WriteGateSnapshot {
   verifiedDepthMilestones: string[];
   verifiedApprovalGates?: string[];
   activeQueuePhase: boolean;
   pendingGateId: string | null;
+  /** Tag of the process that produced this snapshot (diagnostic only). */
+  writer?: WriteGateWriter;
 }
 
 /**
@@ -166,7 +180,7 @@ function ensureWriteGateSnapshotDirectory(basePath: string): void {
   mkdirSync(join(gsdPath, "runtime"), { recursive: true });
 }
 
-function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
+export function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSnapshot {
   const state = getWriteGateState(basePath);
   return {
     verifiedDepthMilestones: [...state.verifiedDepthMilestones].sort(),
@@ -176,12 +190,11 @@ function currentWriteGateSnapshot(basePath: string = process.cwd()): WriteGateSn
   };
 }
 
-function persistWriteGateSnapshot(basePath: string): void {
-  if (!shouldPersistWriteGateSnapshot()) return;
+function writeSnapshotFileAtomic(basePath: string, snapshot: WriteGateSnapshot): void {
   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);
   } catch (err: unknown) {
@@ -196,6 +209,18 @@ function persistWriteGateSnapshot(basePath: string): void {
   }
 }
 
+/**
+ * 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: string, writer: WriteGateWriter): void {
+  if (!shouldPersistWriteGateSnapshot()) return;
+  writeSnapshotFileAtomic(basePath, { ...currentWriteGateSnapshot(basePath), writer });
+}
+
 function clearPersistedWriteGateSnapshot(basePath: string): void {
   if (!shouldPersistWriteGateSnapshot()) return;
   const path = writeGateSnapshotPath(basePath);
@@ -209,7 +234,9 @@ function clearPersistedWriteGateSnapshot(basePath: string): void {
 function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
   const record = value && typeof value === "object" ? value as Record<string, unknown> : {};
   const verified = Array.isArray(record.verifiedDepthMilestones)
-    ? record.verifiedDepthMilestones.filter((item): item is string => typeof item === "string")
+    ? record.verifiedDepthMilestones
+        .filter((item): item is string => typeof item === "string")
+        .map(normalizeMilestoneId)
     : [];
   const verifiedGates = Array.isArray(record.verifiedApprovalGates)
     ? record.verifiedApprovalGates.filter((item): item is string => typeof item === "string")
@@ -219,6 +246,7 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
     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 } : {}),
   };
 }
 
@@ -229,6 +257,18 @@ const EMPTY_SNAPSHOT: WriteGateSnapshot = {
   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: string): WriteGateSnapshot | null {
+  const raw = loadJsonFileOrNull(
+    writeGateSnapshotPath(basePath),
+    (data): data is Record<string, unknown> => typeof data === "object" && data !== null,
+  );
+  return raw === null ? null : normalizeWriteGateSnapshot(raw);
+}
+
 export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
   const path = writeGateSnapshotPath(basePath);
   if (!existsSync(path)) {
@@ -238,13 +278,118 @@ export function loadWriteGateSnapshot(basePath: string): WriteGateSnapshot {
     if (shouldPersistWriteGateSnapshot()) 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: InMemoryWriteGateState, disk: WriteGateSnapshot): void {
+  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: InMemoryWriteGateState): void {
+  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: InMemoryWriteGateState, snapshot: WriteGateSnapshot): void {
+  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: string): WriteGateSnapshot {
+  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: string,
+  mutate: (state: InMemoryWriteGateState) => void | false,
+  opts?: { writer?: WriteGateWriter; reconcile?: boolean },
+): boolean {
+  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: string = process.cwd()): boolean {
   return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;
 }
@@ -257,7 +402,8 @@ export function isMilestoneDepthVerified(
   basePath: string = process.cwd(),
 ): boolean {
   if (!milestoneId) return false;
-  return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
+  refreshWriteGateStateFromDisk(basePath);
+  return getWriteGateState(basePath).verifiedDepthMilestones.has(normalizeMilestoneId(milestoneId));
 }
 
 export function isMilestoneDepthVerifiedInSnapshot(
@@ -265,7 +411,7 @@ export function isMilestoneDepthVerifiedInSnapshot(
   milestoneId: string | null | undefined,
 ): boolean {
   if (!milestoneId) return false;
-  return snapshot.verifiedDepthMilestones.includes(milestoneId);
+  return snapshot.verifiedDepthMilestones.includes(normalizeMilestoneId(milestoneId));
 }
 
 export function isQueuePhaseActive(basePath: string = process.cwd()): boolean {
@@ -273,16 +419,17 @@ export function isQueuePhaseActive(basePath: string = process.cwd()): boolean {
 }
 
 export function setQueuePhaseActive(active: boolean, basePath: string): void {
-  getWriteGateState(basePath).activeQueuePhase = active;
-  persistWriteGateSnapshot(basePath);
+  mutateWriteGateState(basePath, (state) => {
+    state.activeQueuePhase = active;
+  });
 }
 
 export function resetWriteGateState(basePath: string): void {
-  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: string): void {
@@ -290,16 +437,20 @@ export function clearDiscussionFlowState(basePath: string): void {
   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?: string | null, basePath: string = process.cwd()): void {
-  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?: string | null, basePath: string = process.cwd()): void {
-  if (!gateId) return;
-  getWriteGateState(basePath).verifiedApprovalGates.add(gateId);
-  persistWriteGateSnapshot(basePath);
+  defaultWriteGateAdapter().markApprovalGateVerified(gateId, basePath);
 }
 
 export function isApprovalGateVerifiedInSnapshot(
@@ -323,7 +474,7 @@ export function isGateQuestionId(questionId: string): boolean {
  */
 export function extractDepthVerificationMilestoneId(questionId: string): string | null {
   const match = questionId.match(DEPTH_VERIFICATION_MILESTONE_RE);
-  return match?.[1] ?? null;
+  return match?.[1] ? normalizeMilestoneId(match[1]) : null;
 }
 
 /**
@@ -331,34 +482,178 @@ export function extractDepthVerificationMilestoneId(questionId: string): string
  */
 function extractContextMilestoneId(inputPath: string): string | null {
   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: string, basePath: string): void {
-  const state = getWriteGateState(basePath);
+export function setPendingGate(gateId: string, basePath: string): boolean {
+  return defaultWriteGateAdapter().setPending(gateId, basePath);
+}
+
+/** Arm `gateId` on a reconciled state, revoking its prior verification. */
+function armPendingGate(state: InMemoryWriteGateState, gateId: string): void {
   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: string): void {
-  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: string = process.cwd()): string | null {
-  return getWriteGateState(basePath).pendingGateId;
+  return defaultWriteGateAdapter().readState(basePath).pendingGateId;
+}
+
+// ─── Write-gate two-process seam ─────────────────────────────────────────────
+//
+// Two processes write .gsd/runtime/write-gate-state.json: the extension host
+// and the workflow MCP child (which dynamically imports this same compiled
+// module — see GSD_WORKFLOW_WRITE_GATE_MODULE in workflow-mcp.ts and
+// packages/mcp-server/src/server.ts). The adapters below name that seam:
+// every cross-process interleaving reduces to "host adapter op vs child
+// adapter op", which is deterministic given the merge rule documented on
+// mergeSnapshotIntoState plus the unconditional read-merge-write persist.
+
+export interface WriteGateStateAdapter {
+  readonly writer: WriteGateWriter;
+  /** Fresh (child) or disk-reconciled (host) view of gate state. */
+  readState(basePath: string): WriteGateSnapshot;
+  markDepthVerified(milestoneId: string | null | undefined, basePath: string): void;
+  markApprovalGateVerified(gateId: string | null | undefined, basePath: string): void;
+  /**
+   * Arm a pending gate. Returns false when the adapter's policy suppressed
+   * the arm (host: gate already verified on disk — verified wins over a
+   * stale re-arm). Child adapter always arms (a fresh question intentionally
+   * revokes prior verification).
+   */
+  setPending(gateId: string, basePath: string): boolean;
+  clearPending(basePath: string): void;
+}
+
+/**
+ * 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: WriteGateStateAdapter = {
+  writer: "host",
+  readState(basePath: string): WriteGateSnapshot {
+    return refreshWriteGateStateFromDisk(basePath);
+  },
+  markDepthVerified(milestoneId, basePath): void {
+    if (!milestoneId) return;
+    mutateWriteGateState(basePath, (state) => {
+      state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
+    }, { writer: "host" });
+  },
+  markApprovalGateVerified(gateId, basePath): void {
+    if (!gateId) return;
+    mutateWriteGateState(basePath, (state) => {
+      state.verifiedApprovalGates.add(gateId);
+    }, { writer: "host" });
+  },
+  setPending(gateId: string, basePath: string): boolean {
+    // 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: string): void {
+    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: WriteGateStateAdapter = {
+  writer: "child",
+  readState(basePath: string): WriteGateSnapshot {
+    return loadWriteGateSnapshot(basePath);
+  },
+  markDepthVerified(milestoneId, basePath): void {
+    if (!milestoneId) return;
+    childMutate(basePath, (state) => {
+      state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
+    });
+  },
+  markApprovalGateVerified(gateId, basePath): void {
+    if (!gateId) return;
+    childMutate(basePath, (state) => {
+      state.verifiedApprovalGates.add(gateId);
+    });
+  },
+  setPending(gateId: string, basePath: string): boolean {
+    childMutate(basePath, (state) => armPendingGate(state, gateId));
+    return true;
+  },
+  clearPending(basePath: string): void {
+    childMutate(basePath, (state) => {
+      state.pendingGateId = null;
+    });
+  },
+};
+
+function childMutate(basePath: string, mutate: (state: InMemoryWriteGateState) => void): void {
+  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: NodeJS.ProcessEnv = process.env): WriteGateWriter {
+  return env.GSD_WORKFLOW_WRITE_GATE_MODULE || env.GSD_WORKFLOW_PROJECT_ROOT ? "child" : "host";
+}
+
+function defaultWriteGateAdapter(): WriteGateStateAdapter {
+  return defaultWriteGateWriter() === "child" ? childWriteGateAdapter : hostWriteGateAdapter;
 }
 
 /**
@@ -433,33 +728,187 @@ export function shouldBlockPendingGateBashInSnapshot(
   };
 }
 
+// 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";
+
+export interface AskUserQuestionsGateQuestion {
+  id?: unknown;
+  options?: Array<{ label?: string }>;
+}
+
+export interface AskUserQuestionsGateDetails {
+  cancelled?: boolean;
+  interrupted?: boolean;
+  /**
+   * True when the host elicitation channel timed out before the user answered.
+   * Distinct from `cancelled` (deliberate dismissal): the gate verdict maps
+   * this to "timeout" so callers pause-and-wait instead of letting the model
+   * re-ask into the same timeout loop (#852).
+   */
+  timed_out?: boolean;
+  response?: {
+    answers?: Record<string, { selected?: unknown } | undefined>;
+  } | null;
+}
+
+export type AskUserQuestionsGateResult =
+  | { status: "not-gate" }
+  | { status: "waiting"; pendingGateId: string; interrupted: boolean }
+  | { status: "verified"; gateId: string; milestoneId: string | null }
+  | { status: "declined"; gateId: string }
+  | { status: "timeout"; pendingGateId: string; interrupted: boolean };
+
+function findGateQuestion(
+  questions: AskUserQuestionsGateQuestion[],
+  gateId: string,
+): AskUserQuestionsGateQuestion | undefined {
+  return questions.find((question) => question?.id === gateId);
+}
+
+function verifyAnsweredGate(
+  basePath: string,
+  question: AskUserQuestionsGateQuestion,
+  fallbackMilestoneId?: string | null,
+): AskUserQuestionsGateResult {
+  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: "declined" | "waiting" | "cancelled" | "timeout",
+  gateId: string,
+  details: AskUserQuestionsGateDetails,
+): AskUserQuestionsGateResult {
+  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: unknown,
-  options?: Array<{ label?: string }>,
-): boolean {
-  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: {
+  basePath: string;
+  questions: AskUserQuestionsGateQuestion[];
+  details: AskUserQuestionsGateDetails;
+  fallbackMilestoneId?: string | null;
+}): AskUserQuestionsGateResult {
+  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: string,
+  interrupted: boolean,
+): string {
+  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: string,
+): string {
+  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(
@@ -472,7 +921,7 @@ export function shouldBlockContextWrite(
   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,
@@ -491,8 +940,8 @@ export function shouldBlockContextWrite(
     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(" "),
   };
@@ -981,6 +1430,37 @@ function isPathContained(target: string, container: string): boolean {
   return target.startsWith(container.endsWith(sep) ? container : container + sep);
 }
 
+function formatWorktreeIsolationBlockReason(
+  tool: string,
+  displayTarget: string,
+  isAutoLive: boolean,
+  effectiveBasePath: string,
+): string {
+  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
@@ -998,10 +1478,9 @@ function isPathContained(target: string, container: string): boolean {
  *   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: string,
@@ -1034,10 +1513,12 @@ export function shouldBlockWorktreeWrite(
   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).
@@ -1048,24 +1529,46 @@ export function shouldBlockWorktreeWrite(
     // 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: string,
+  effectiveBasePath: string,
+  isAutoLive: boolean,
+  currentUnitType?: string | null,
+): { block: boolean; reason?: string } {
+  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,
+    ),
   };
 }