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

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -23,6 +23,9 @@ const DEFAULT_KNOWLEDGE_MAX_CHARS = 12_000;
 const DEFAULT_CODEBASE_MAX_CHARS = 8_000;
 const MIN_CONTEXT_MESSAGE_MAX_CHARS = 1_000;
 const MIN_KNOWLEDGE_MAX_CHARS = 1_000;
+const contextMaintenanceCompletedForBasePath = new Set();
+const contextMaintenanceInFlightByBasePath = new Map();
+const deferredContextMaintenanceByBasePath = new Map();
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
  * hardcoding absolute paths in the system prompt template. Only skills
@@ -65,6 +68,24 @@ export const BUNDLED_SKILL_TRIGGERS = [
     { trigger: "Author a YAML workflow definition — steps, triggers, and templates", skill: "create-workflow" },
     { trigger: "Deep code optimization audit — perf anti-patterns, memory leaks, algorithmic complexity, bundle size, I/O, caching, dead code (parallel pattern-based hunt)", skill: "code-optimizer" },
 ];
+/**
+ * Remove the volatile lines from a CODEBASE.md map before it is injected into
+ * the cached system-prompt prefix: the human-readable `Generated: <timestamp>`
+ * header and the `<!-- gsd:codebase-meta {...} -->` comment. Both carry a
+ * per-regeneration timestamp (and fingerprint) that change whenever the map is
+ * refreshed, which would otherwise invalidate the provider KV cache prefix on
+ * every turn even when the underlying file structure is identical. (#847)
+ */
+export function stripVolatileCodebaseMetadata(content) {
+    return content
+        .split("\n")
+        .filter((line) => {
+        const trimmed = line.trimStart();
+        return !trimmed.startsWith("Generated:") && !trimmed.startsWith("<!-- gsd:codebase-meta");
+    })
+        .join("\n")
+        .trim();
+}
 function warnDeprecatedAgentInstructions() {
     const paths = [
         join(gsdHome(), "agent-instructions.md"),
@@ -78,45 +99,69 @@ function warnDeprecatedAgentInstructions() {
         }
     }
 }
-export async function buildBeforeAgentStartResult(event, ctx) {
-    if (!existsSync(join(process.cwd(), ".gsd")))
-        return undefined;
-    const stopContextTimer = debugTime("context-inject");
-    const systemContent = loadPrompt("system", {
-        templatesDir: getTemplatesDir(),
-        shortcutDashboard: formatShortcut("Ctrl+Alt+G"),
-        shortcutShell: formatShortcut("Ctrl+Alt+B"),
-    });
-    let loadedPreferences = loadEffectiveGSDPreferences();
-    try {
-        const { markCmuxPromptShown, shouldPromptToEnableCmux } = await import("../../cmux/index.js");
-        if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
-            markCmuxPromptShown();
-            if (autoEnableCmuxPreferences()) {
-                loadedPreferences = loadEffectiveGSDPreferences();
-                ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
-            }
+async function runSessionStartupMaintenanceOnce(basePath, ctx) {
+    if (contextMaintenanceCompletedForBasePath.has(basePath)) {
+        // Backfills are session-once, but memory queries and other DB-backed
+        // prompt assembly still need an active adapter on every turn.
+        try {
+            const { ensureDbOpen } = await import("./dynamic-tools.js");
+            await ensureDbOpen(basePath);
         }
+        catch (e) {
+            logWarning("bootstrap", `project DB open failed: ${e.message}`);
+        }
+        return false;
+    }
+    const existing = contextMaintenanceInFlightByBasePath.get(basePath);
+    const isInitiator = !existing;
+    // Use a definite Promise<boolean> so `await inFlight` has a known return type.
+    let inFlight;
+    if (isInitiator) {
+        inFlight = performSessionStartupMaintenance(basePath, ctx);
+        contextMaintenanceInFlightByBasePath.set(basePath, inFlight);
+        void inFlight.finally(() => {
+            if (contextMaintenanceInFlightByBasePath.get(basePath) === inFlight) {
+                contextMaintenanceInFlightByBasePath.delete(basePath);
+            }
+        });
     }
-    catch (e) {
-        logWarning("bootstrap", `cmux prompt setup skipped: ${e.message}`);
+    else {
+        inFlight = existing;
     }
-    const ctxProjectRoot = ctx.projectRoot;
-    const basePath = typeof ctxProjectRoot === "string" && ctxProjectRoot.length > 0
-        ? ctxProjectRoot
-        : process.cwd();
-    let preferenceBlock = "";
-    if (loadedPreferences) {
-        const cwd = basePath;
-        const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
-        preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions, { includeResolvedPaths: false })}`;
-        if (report.warnings.length > 0) {
-            ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
-        }
+    const result = await inFlight;
+    return isInitiator ? result : false;
+}
+async function performSessionStartupMaintenance(basePath, ctx) {
+    // DB-backed memory backfills run below. On a cold session the database file
+    // may exist without an active in-process adapter, so open the canonical
+    // project DB before those best-effort operations inspect it.
+    let dbOpen = false;
+    try {
+        const { ensureDbOpen } = await import("./dynamic-tools.js");
+        dbOpen = await ensureDbOpen(basePath);
     }
+    catch (e) {
+        logWarning("bootstrap", `project DB open failed before memory projection: ${e.message}`);
+    }
+    if (!dbOpen)
+        return false;
+    // These backfills are independent idempotent migrations. Keep them on the
+    // startup path because their rows can affect the MEMORY block for this turn,
+    // but do not make their import/IO latencies add serially.
+    await Promise.allSettled([
+        runDecisionsMemoryBackfill(ctx),
+        runKnowledgeMemoryBackfill(basePath, ctx),
+    ]);
+    // Mark session complete before scheduling deferred work so any concurrent
+    // caller that observes the completed state does not re-enter maintenance.
+    contextMaintenanceCompletedForBasePath.add(basePath);
+    scheduleDeferredContextMaintenance(basePath);
+    return true;
+}
+async function runDecisionsMemoryBackfill(ctx) {
     // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
     // and best-effort — first run absorbs the existing decisions table into
-    // the memory store; subsequent runs are a single sentinel SELECT.
+    // the memory store; repeated turns skip this session-once maintenance.
     try {
         const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
         const written = backfillDecisionsToMemories();
@@ -127,10 +172,11 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
-    // ADR-013 Stage 2b: KNOWLEDGE.md Patterns + Lessons backfill, then
-    // re-render the hybrid projection (manual Rules + projected Patterns +
-    // projected Lessons). Both are idempotent and best-effort — failures here
-    // can't block agent startup.
+}
+async function runKnowledgeMemoryBackfill(basePath, ctx) {
+    // ADR-013 Stage 2b: KNOWLEDGE.md Patterns + Lessons backfill. Idempotent
+    // and best-effort — first run migrates rows into memories; repeated turns
+    // skip this session-once maintenance.
     try {
         const { backfillKnowledgeToMemories } = await import("../knowledge-backfill.js");
         const writtenK = backfillKnowledgeToMemories(basePath);
@@ -141,6 +187,32 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `KNOWLEDGE.md backfill failed: ${e.message}`);
     }
+}
+function scheduleDeferredContextMaintenance(basePath) {
+    if (deferredContextMaintenanceByBasePath.has(basePath))
+        return;
+    const task = new Promise((resolve) => {
+        setTimeout(() => {
+            void runDeferredContextMaintenance(basePath).finally(resolve);
+        }, 0);
+    });
+    deferredContextMaintenanceByBasePath.set(basePath, task);
+    void task.finally(() => {
+        if (deferredContextMaintenanceByBasePath.get(basePath) === task) {
+            deferredContextMaintenanceByBasePath.delete(basePath);
+        }
+    });
+}
+async function runDeferredContextMaintenance(basePath) {
+    // Projection rendering and consolidation-gap reporting do not contribute to
+    // the returned system prompt. Run them after startup context is assembled so
+    // their DB/file scans do not block the first response.
+    await Promise.allSettled([
+        renderKnowledgeProjectionDeferred(basePath),
+        reportConsolidationGapsDeferred(basePath),
+    ]);
+}
+async function renderKnowledgeProjectionDeferred(basePath) {
     try {
         const { renderKnowledgeProjection } = await import("../knowledge-projection.js");
         renderKnowledgeProjection(basePath);
@@ -148,9 +220,8 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `KNOWLEDGE.md projection render failed: ${e.message}`);
     }
-    // ADR-013 step 6 preflight: warn when decisions / KNOWLEDGE.md rows are not
-    // yet in the memories table. Read-only; never throws. Runs after the two
-    // backfills above so the gap report reflects post-backfill state.
+}
+async function reportConsolidationGapsDeferred(basePath) {
     try {
         const { reportConsolidationGaps } = await import("../memory-consolidation-scanner.js");
         reportConsolidationGaps(basePath);
@@ -158,6 +229,50 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `memory consolidation scan failed: ${e.message}`);
     }
+}
+export async function _flushDeferredContextMaintenanceForTest(basePath) {
+    const tasks = basePath
+        ? [deferredContextMaintenanceByBasePath.get(basePath)].filter((task) => Boolean(task))
+        : [...deferredContextMaintenanceByBasePath.values()];
+    await Promise.allSettled(tasks);
+}
+export async function buildBeforeAgentStartResult(event, ctx) {
+    if (!existsSync(join(process.cwd(), ".gsd")))
+        return undefined;
+    const stopContextTimer = debugTime("context-inject");
+    const systemContent = loadPrompt("system", {
+        templatesDir: getTemplatesDir(),
+        shortcutDashboard: formatShortcut("Ctrl+Alt+G"),
+        shortcutShell: formatShortcut("Ctrl+Alt+B"),
+    });
+    let loadedPreferences = loadEffectiveGSDPreferences();
+    try {
+        const { markCmuxPromptShown, shouldPromptToEnableCmux } = await import("../../cmux/index.js");
+        if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+            markCmuxPromptShown();
+            if (autoEnableCmuxPreferences()) {
+                loadedPreferences = loadEffectiveGSDPreferences();
+                ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
+            }
+        }
+    }
+    catch (e) {
+        logWarning("bootstrap", `cmux prompt setup skipped: ${e.message}`);
+    }
+    const ctxProjectRoot = ctx.projectRoot;
+    const basePath = typeof ctxProjectRoot === "string" && ctxProjectRoot.length > 0
+        ? ctxProjectRoot
+        : process.cwd();
+    let preferenceBlock = "";
+    if (loadedPreferences) {
+        const cwd = basePath;
+        const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
+        preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions, { includeResolvedPaths: false })}`;
+        if (report.warnings.length > 0) {
+            ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
+        }
+    }
+    await runSessionStartupMaintenanceOnce(basePath, ctx);
     const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), basePath);
     if (globalSizeKb > 4) {
         ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
@@ -180,16 +295,21 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     const rawCodebase = readCodebaseMap(process.cwd());
     if (existsSync(codebasePath) && rawCodebase) {
         try {
-            const rawContent = rawCodebase.trim();
+            // Strip the volatile `Generated: <timestamp>` header line and the
+            // machine-readable `gsd:codebase-meta` comment before injecting. Both
+            // embed a per-regeneration timestamp/fingerprint; because this block
+            // rides the cached system-prompt prefix, leaving the timestamp in would
+            // invalidate the provider KV cache on every map refresh even when the
+            // file structure is unchanged. The full map (with timestamp) remains at
+            // .gsd/CODEBASE.md. (#847)
+            const rawContent = stripVolatileCodebaseMetadata(rawCodebase.trim());
             if (rawContent) {
                 // Cap injection size to ~2 000 tokens to avoid bloating every request.
                 // Full map is always available at .gsd/CODEBASE.md.
-                const generatedMatch = rawContent.match(/Generated: (\S+)/);
-                const generatedAt = generatedMatch?.[1] ?? "unknown";
                 const content = rawContent.length > DEFAULT_CODEBASE_MAX_CHARS
                     ? rawContent.slice(0, DEFAULT_CODEBASE_MAX_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
                     : rawContent;
-                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
+                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
             }
         }
         catch (e) {

package/dist/resources/extensions/gsd/bootstrap/tool-search-shim.js

@@ -26,8 +26,27 @@ export function registerToolSearchShim(pi) {
             return new Text(theme.fg("warning", text), 0, 0);
         },
     });
-    const active = pi.getActiveTools();
-    if (!active.includes("ToolSearch")) {
-        pi.setActiveTools([...active, "ToolSearch"]);
+    // Ensure the shim is part of the active tool set. registerTool() is valid
+    // during extension loading, but getActiveTools()/setActiveTools() are stubs
+    // that throw "Extension runtime not initialized" until runner.bindCore() runs
+    // (after all registerExtension() calls return). When the throw was hit, the
+    // catch in register-extension.ts swallowed it — leaving the whole bootstrap
+    // partially failed and, under Claude Code CLI, the workflow tools could end
+    // up missing from the model's surface, which traps plan-milestone in a
+    // finalize-retry loop with no gsd_plan_milestone available.
+    //
+    // The activation here is also redundant post-bind: ToolSearch is in
+    // MINIMAL_AUTO_BASE_TOOL_NAMES, so buildMinimalAutoGsdToolSet adds it during
+    // adjust_tool_set (before_agent_start). Tolerate the loading-stub throw so
+    // the shim always registers; activation is completed by post-bind scoping.
+    try {
+        const active = pi.getActiveTools();
+        if (!active.includes("ToolSearch")) {
+            pi.setActiveTools([...active, "ToolSearch"]);
+        }
+    }
+    catch {
+        // Pre-bind runtime: getActiveTools/setActiveTools are not yet wired.
+        // The tool is registered; activation happens at adjust_tool_set.
     }
 }

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

@@ -10,6 +10,7 @@ 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
@@ -20,6 +21,12 @@ import { evaluateGateAnswer } from "../consent-verdict.js";
 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.
@@ -189,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")
@@ -245,7 +254,7 @@ export function loadWriteGateSnapshot(basePath) {
  */
 function mergeSnapshotIntoState(state, disk) {
     for (const milestone of disk.verifiedDepthMilestones)
-        state.verifiedDepthMilestones.add(milestone);
+        state.verifiedDepthMilestones.add(normalizeMilestoneId(milestone));
     for (const gate of disk.verifiedApprovalGates ?? [])
         state.verifiedApprovalGates.add(gate);
     state.activeQueuePhase = disk.activeQueuePhase;
@@ -343,12 +352,12 @@ export function isMilestoneDepthVerified(milestoneId, basePath = process.cwd())
     if (!milestoneId)
         return false;
     refreshWriteGateStateFromDisk(basePath);
-    return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
+    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;
@@ -400,14 +409,14 @@ 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
@@ -464,7 +473,7 @@ export const hostWriteGateAdapter = {
         if (!milestoneId)
             return;
         mutateWriteGateState(basePath, (state) => {
-            state.verifiedDepthMilestones.add(milestoneId);
+            state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
         }, { writer: "host" });
     },
     markApprovalGateVerified(gateId, basePath) {
@@ -508,7 +517,7 @@ export const childWriteGateAdapter = {
         if (!milestoneId)
             return;
         childMutate(basePath, (state) => {
-            state.verifiedDepthMilestones.add(milestoneId);
+            state.verifiedDepthMilestones.add(normalizeMilestoneId(milestoneId));
         });
     },
     markApprovalGateVerified(gateId, basePath) {
@@ -621,6 +630,17 @@ function verifyAnsweredGate(basePath, question, fallbackMilestoneId) {
 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 {
@@ -645,6 +665,16 @@ 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",
@@ -661,6 +691,8 @@ export function applyAskUserQuestionsGateResult(options) {
             return unresolvedGateResult(verdict, currentPendingGate, details);
         }
     }
+    if (details.timed_out)
+        return { status: "not-gate" };
     if (details.cancelled || !details.response)
         return { status: "not-gate" };
     for (const question of questions) {
@@ -690,12 +722,27 @@ export function formatPendingAskUserQuestionsGateMessage(pendingGateId, interrup
         `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,
@@ -713,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(" "),
     };
@@ -1116,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
@@ -1133,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);
@@ -1180,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),
     };
 }