@opengsd/gsd-pi 1.2.0-dev.b1abb545 → 1.2.0-dev.fb12b103

package/dist/resources/extensions/gsd/bootstrap/register-extension.js

@@ -13,6 +13,7 @@ import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
 import { logWarning } from "../workflow-logger.js";
+import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.js";
 // Static import so cmux event listeners are registered synchronously during
 // extension bootstrap. Prior implementation used `void import().then()` which
 // queued listener registration as a microtask — any CMUX_CHANNELS emit fired
@@ -30,6 +31,9 @@ const EPIPE_STORM_THRESHOLD = 100;
 const EPIPE_STORM_WINDOW_MS = 10_000;
 let epipeCount = 0;
 let epipeWindowStart = 0;
+export const CRITICAL_GSD_WORKFLOW_TOOL_NAMES = [...new Set(Object.values(UNIT_TOOL_CONTRACTS)
+        .flatMap((contract) => contract.requiredWorkflowTools)
+        .filter((toolName) => toolName.startsWith("gsd_")))].sort();
 /** Write to stderr without ever re-throwing — stderr can EPIPE too, which would
  *  re-enter this handler and re-loop. */
 function safeStderr(msg) {
@@ -121,6 +125,20 @@ export function installEpipeGuard() {
         process.on("unhandledRejection", _gsdRejectionGuard);
     }
 }
+function assertCriticalGsdWorkflowToolsRegistered(pi) {
+    if (typeof pi.getAllTools !== "function")
+        return;
+    const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+    const missing = CRITICAL_GSD_WORKFLOW_TOOL_NAMES.filter((toolName) => !registered.has(toolName));
+    if (missing.length === 0)
+        return;
+    const message = [
+        `Critical GSD workflow tool registration failed; missing required tool(s): ${missing.join(", ")}.`,
+        "Check earlier bootstrap warnings for the registration slot that failed.",
+    ].join(" ");
+    logWarning("bootstrap", message);
+    throw new Error(message);
+}
 export function registerGsdExtension(pi) {
     // Note: registerGSDCommand is called by index.ts before this function,
     // so we intentionally skip it here to avoid double-registration.
@@ -186,4 +204,5 @@ export function registerGsdExtension(pi) {
             logWarning("bootstrap", `Failed to register ${name}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    assertCriticalGsdWorkflowToolsRegistered(pi);
 }

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -7,7 +7,7 @@ import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { ALWAYS_PRESERVED_SHIM_TOOL_NAMES } from "@gsd/pi-ai";
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 import { buildMilestoneFileName, clearPathCache, milestonesDir, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { applyAskUserQuestionsGateResult, canonicalToolName, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, isMilestoneDepthVerified, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { applyAskUserQuestionsGateResult, canonicalToolName, clearDiscussionFlowState, formatPendingAskUserQuestionsGateMessage, isApprovalGateVerifiedInSnapshot, isDepthConfirmationAnswer, isMilestoneDepthVerified, isMilestoneDepthVerifiedInSnapshot, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, refreshWriteGateStateFromDisk, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -19,7 +19,9 @@ import { saveActivityLog } from "../activity-log.js";
 import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult, saveEvidenceToDisk } from "../safety/evidence-collector.js";
 import { parseUnitId } from "../unit-id.js";
 import { classifyCommand } from "../safety/destructive-guard.js";
+import { confirmDestructiveCommand, consumeDestructiveConfirmation, isDestructiveConfirmGateId, requestDestructiveConfirmation, } from "../safety/destructive-confirmation.js";
 import { logWarning as safetyLogWarning } from "../workflow-logger.js";
+import { isUnitCloseoutTool, runInteractiveUnitCloseout } from "../unit-closeout.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
@@ -31,10 +33,14 @@ import { applyUnitSkillVisibility, unitHasSkillManifest } from "../skill-scope.j
 import { getGuidedUnitContext } from "../guided-unit-context.js";
 import { registerPlanMilestoneSchemaRecovery } from "./plan-milestone-schema-recovery.js";
 import { AUTO_UNIT_SCOPED_TOOLS, RUN_UAT_BROWSER_TOOL_NAMES, canonicalWorkflowToolName, isWorkflowAliasTool } from "../auto-unit-tool-scope.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
 import { filterToolsForProvider } from "../model-router.js";
 import { mcpToolMatchesBaseName } from "../mcp-tool-name.js";
 import { RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
 import { supportsSourceObservationsForUnit } from "../source-observations.js";
+import { clearPendingAutoStart } from "../pending-auto-start.js";
+import { resolveWorkflowToolBasePath } from "./dynamic-tools.js";
+import { getRequiredWorkflowToolsForUnit } from "../unit-tool-contracts.js";
 let approvalQuestionAbortInFlight = false;
 async function loadWelcomeScreenModule() {
     const candidates = [];
@@ -137,7 +143,7 @@ function withPreservedShimTools(toolNames) {
 }
 /** True for the browser automation tools (browser_navigate, browser_click, ...). */
 function isBrowserTool(toolName) {
-    return canonicalToolName(toolName).startsWith("browser_");
+    return hasBrowserContractPrefix(canonicalToolName(toolName));
 }
 /**
  * True when any message in the request is driven by a GSD workflow command
@@ -199,7 +205,7 @@ export function buildMinimalGsdToolSet(activeToolNames) {
     const minimal = resolveScopedToolNames(activeToolNames, MINIMAL_GSD_TOOL_NAMES);
     return withPreservedShimTools([...new Set([...preserved, ...minimal])]);
 }
-export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registeredToolNames = activeToolNames) {
+export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registeredToolNames = activeToolNames, warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames) {
     if (unitType === "run-uat") {
         return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
     }
@@ -211,7 +217,20 @@ export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registered
             ...availableBaseTools,
         ])];
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [...MINIMAL_GSD_TOOL_NAMES, ...unitTools]);
-    return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
+    const result = withPreservedShimTools([...new Set([...preserved, ...scoped])]);
+    warnIfRequiredWorkflowToolsUnresolved(unitType, result, warnOnUnresolvedRequiredTools);
+    return result;
+}
+function hasResolvedWorkflowTool(resolvedToolNames, requiredToolName) {
+    return resolvedToolNames.some((name) => name === requiredToolName || mcpToolMatchesBaseName(name, requiredToolName));
+}
+function warnIfRequiredWorkflowToolsUnresolved(unitType, scopedToolNames, shouldWarn) {
+    if (!unitType || !shouldWarn)
+        return;
+    const unresolved = getRequiredWorkflowToolsForUnit(unitType).filter((toolName) => !hasResolvedWorkflowTool(scopedToolNames, toolName));
+    if (unresolved.length === 0)
+        return;
+    safetyLogWarning("bootstrap", `buildMinimalAutoGsdToolSet(${unitType}): required workflow tool(s) not in active/registered surface after scoping: ${unresolved.join(", ")}. Tool registration may have partially failed, provider filtering may have removed a required tool, or workflow MCP may be disconnected.`);
 }
 export function buildRunUatGsdToolSet(activeToolNames, registeredToolNames = activeToolNames) {
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [
@@ -237,7 +256,7 @@ export function buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNa
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], WORKFLOW_GSD_TOOL_NAMES);
     return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
 }
-export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessages, registeredToolNames = activeToolNames, guidedUnitType) {
+export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessages, registeredToolNames = activeToolNames, guidedUnitType, warnOnUnresolvedRequiredTools = registeredToolNames !== activeToolNames) {
     for (let index = (requestCustomMessages?.length ?? 0) - 1; index >= 0; index--) {
         const currentCustomType = requestCustomMessages?.[index]?.customType;
         if (currentCustomType === "gsd-run" ||
@@ -245,7 +264,7 @@ export function buildRequestScopedGsdToolSet(activeToolNames, requestCustomMessa
             currentCustomType === "gsd-doctor-heal" ||
             currentCustomType === "gsd-triage") {
             if (guidedUnitType) {
-                return buildMinimalAutoGsdToolSet(activeToolNames, guidedUnitType, registeredToolNames);
+                return buildMinimalAutoGsdToolSet(activeToolNames, guidedUnitType, registeredToolNames, warnOnUnresolvedRequiredTools);
             }
             return buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNames);
         }
@@ -279,8 +298,9 @@ function applyMinimalGsdToolSurface(pi) {
     const dash = getAutoRuntimeSnapshot();
     if (dash.active && dash.currentUnit) {
         const currentToolNames = pi.getActiveTools();
+        const hasRegisteredSurface = typeof pi.getAllTools === "function";
         const registeredToolNames = resolveRegisteredToolNames(pi, currentToolNames);
-        const scopedToolNames = buildMinimalAutoGsdToolSet(currentToolNames, dash.currentUnit.type, registeredToolNames);
+        const scopedToolNames = buildMinimalAutoGsdToolSet(currentToolNames, dash.currentUnit.type, registeredToolNames, hasRegisteredSurface);
         recordAutoToolSurfaceSnapshot({
             source: "runtime-scope",
             unitType: dash.currentUnit.type,
@@ -299,9 +319,10 @@ export function scopeGsdWorkflowToolsForDispatch(pi, unitType) {
     if (isFullGsdToolSurfaceRequested())
         return null;
     const current = pi.getActiveTools();
+    const hasRegisteredSurface = typeof pi.getAllTools === "function";
     const registeredToolNames = resolveRegisteredToolNames(pi, current);
     const scoped = unitType
-        ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames)
+        ? buildMinimalAutoGsdToolSet(current, unitType, registeredToolNames, hasRegisteredSurface)
         : buildMinimalGsdWorkflowToolSet(current, registeredToolNames);
     recordAutoToolSurfaceSnapshot({
         source: "dispatch-scope",
@@ -444,8 +465,15 @@ function isShellExecutionTool(canonicalName) {
 function activateDeferredApprovalGate(basePath) {
     if (deferredApprovalGate?.basePath !== basePath)
         return;
-    setPendingGate(deferredApprovalGate.gateId, basePath);
+    const gateId = deferredApprovalGate.gateId;
     deferredApprovalGate = null;
+    const snapshot = refreshWriteGateStateFromDisk(basePath);
+    const milestoneId = extractDepthVerificationMilestoneId(gateId);
+    if (isApprovalGateVerifiedInSnapshot(snapshot, gateId))
+        return;
+    if (milestoneId && isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId))
+        return;
+    setPendingGate(gateId, basePath);
 }
 function extractGateQuestionId(input) {
     const questions = input?.questions ?? [];
@@ -463,6 +491,25 @@ function isContextDraftSummarySave(toolName, input) {
         return false;
     return input.artifact_type === "CONTEXT-DRAFT";
 }
+/**
+ * External engines (claude-code-cli) deliver ask_user_questions results as
+ * relayed MCP tool results: the structured round payload arrives in
+ * `result.structuredContent`, not in pi-native `event.details`. Without this
+ * fallback, applyAskUserQuestionsGateResult sees no response for an answered
+ * gate question and lands in the "waiting" branch — leaving a re-armed gate
+ * permanently pending and the discuss→auto handoff blocked.
+ */
+function resolveAskUserQuestionsGateDetails(event) {
+    const hasRoundShape = (value) => !!value && typeof value === "object" &&
+        (value.cancelled !== undefined || value.response !== undefined);
+    const details = event.details;
+    if (hasRoundShape(details))
+        return details;
+    const structured = event.result?.structuredContent;
+    if (hasRoundShape(structured))
+        return structured;
+    return details ?? {};
+}
 function selectedAnswerLabel(selected) {
     if (Array.isArray(selected))
         return selected.map(String).join(", ");
@@ -626,7 +673,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             catch { /* non-fatal */ }
         }
     });
-    pi.on("session_switch", async (_event, ctx) => {
+    pi.on("session_switch", async (event, ctx) => {
         const basePath = contextBasePath(ctx);
         const preserveCloseoutSurface = isAutoCompletionStopInProgress();
         initSessionNotifications(ctx);
@@ -635,6 +682,13 @@ export function registerHooks(pi, ecosystemHandlers) {
         clearDeferredApprovalGate();
         await resetAskUserQuestionsTurnCache();
         clearDiscussionFlowState(basePath);
+        // /clear or /new destroys the conversation holding a discuss interview, so
+        // its pending discuss→auto handoff can never be answered — clear it. Resume
+        // restores the interview transcript, so the entry survives. Auto-mode's own
+        // newSession() calls are safe: the handoff consumes the entry on agent_end.
+        if (event.reason === "new") {
+            clearPendingAutoStart(basePath);
+        }
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
         await applyCompactionThresholdOverride(ctx);
@@ -1056,19 +1110,35 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         // Destructive command classification + hard gate in all modes.
         if (isToolCallEventType("bash", event)) {
-            const classification = classifyCommand(event.input.command);
+            const command = event.input.command;
+            const classification = classifyCommand(command);
             if (classification.destructive) {
+                const guardBasePath = contextBasePath(ctx);
+                // Escape hatch: if the user already confirmed this exact command via a
+                // destructive_confirm gate, consume the one-shot token and let it run.
+                // Without this, the block below loops forever — the model cannot satisfy
+                // "confirm in the current turn" because nothing ever clears the gate.
+                if (consumeDestructiveConfirmation(command, guardBasePath)) {
+                    safetyLogWarning("safety", `destructive command confirmed: ${classification.labels.join(", ")}`, {
+                        command: String(command).slice(0, 200),
+                    });
+                    return;
+                }
+                // Record the command as pending so an affirmative answer to a
+                // destructive_confirm gate (handled in tool_result) can confirm it.
+                requestDestructiveConfirmation(command, guardBasePath);
                 const reason = [
                     "HARD BLOCK: destructive Bash command requires explicit human confirmation.",
                     `Detected: ${classification.labels.join(", ")}`,
-                    "Run this via ask_user_questions, wait for the user's response,",
-                    "then issue the command only when confirmed in the current turn.",
+                    "Call ask_user_questions with a question id containing \"destructive_confirm\"",
+                    "and a first option that affirms the action; wait for the user's response,",
+                    "then re-issue this exact command in the same turn to run it once.",
                 ].join(" ");
                 safetyLogWarning("safety", `destructive command: ${classification.labels.join(", ")}`, {
-                    command: String(event.input.command).slice(0, 200),
+                    command: String(command).slice(0, 200),
                 });
                 if (ctx) {
-                    await maybePauseAutoForApprovalGate(ctx, pi, isAutoActive(), "Depth confirmation is waiting for your answer — pausing auto-mode.");
+                    await maybePauseAutoForApprovalGate(ctx, pi, isAutoActive(), "Destructive-command confirmation is waiting for your answer — pausing auto-mode.");
                 }
                 return { block: true, reason };
             }
@@ -1105,12 +1175,27 @@ export function registerHooks(pi, ecosystemHandlers) {
         else if (isAutoActive()) {
             clearToolInvocationError();
         }
+        // Interactive Closeout adapter (ADR-032): auto-mode owns closeout for its
+        // own units; interactive completions get the durable git subset (commit +
+        // Closeout Git Verdict) instead of silently bypassing git.isolation.
+        if (!event.isError && !isAutoActive() && isUnitCloseoutTool(toolName)) {
+            try {
+                runInteractiveUnitCloseout({
+                    basePath: resolveWorkflowToolBasePath(ctx, event.input),
+                    canonicalToolName: toolName,
+                    input: event.input,
+                });
+            }
+            catch (err) {
+                safetyLogWarning("engine", `interactive unit closeout failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         if (toolName !== "ask_user_questions")
             return;
         const basePath = contextBasePath(ctx);
         const milestoneId = await getDiscussionMilestoneIdFor(basePath);
-        const details = event.details;
-        const questions = event.input?.questions ?? [];
+        const details = resolveAskUserQuestionsGateDetails(event);
+        const questions = event.input?.questions ?? details?.questions ?? [];
         const gateResult = applyAskUserQuestionsGateResult({
             basePath,
             questions,
@@ -1136,6 +1221,22 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         if (details?.cancelled || !details?.response)
             return;
+        // Destructive-command confirmation: an affirmative answer to a
+        // destructive_confirm gate promotes the pending blocked command to a
+        // one-shot confirmed token, which the bash tool_call guard consumes on the
+        // next attempt. Rejecting/declining leaves the command blocked.
+        // (Depth-verification gate handling now lives in
+        // applyAskUserQuestionsGateResult above; only the destructive-confirm gate
+        // is handled inline here.)
+        for (const question of questions) {
+            if (isDestructiveConfirmGateId(question?.id)) {
+                const answer = details.response?.answers?.[question.id];
+                if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
+                    confirmDestructiveCommand(basePath);
+                }
+                break;
+            }
+        }
         if (!milestoneId)
             return;
         await saveDiscussionQuestionRound(basePath, milestoneId, questions, details);
@@ -1146,10 +1247,39 @@ export function registerHooks(pi, ecosystemHandlers) {
         if (toolName === "ask_user_questions") {
             const questionId = extractGateQuestionId(event.args);
             if (typeof questionId === "string") {
-                setPendingGate(questionId, basePath);
+                // External engines (claude-code-cli) ingest the SDK turn's tool blocks
+                // post-hoc, so this event can fire AFTER the workflow MCP child already
+                // verified this gate and allowed the CONTEXT save. setPendingGate also
+                // revokes verifiedDepthMilestones/verifiedApprovalGates, so an
+                // unconditional re-arm here wipes the child's verification and leaves
+                // the discuss→auto handoff permanently blocked. Skip the re-arm when
+                // the snapshot already records this exact gate as verified — mirrors
+                // activateDeferredApprovalGate's guard. Stale verified state cannot
+                // leak into a later re-discussion: a successful handoff deletes the
+                // snapshot via clearDiscussionFlowState.
+                const snapshot = refreshWriteGateStateFromDisk(basePath);
+                const gateMilestoneId = extractDepthVerificationMilestoneId(questionId);
+                const alreadyVerified = isApprovalGateVerifiedInSnapshot(snapshot, questionId) ||
+                    isMilestoneDepthVerifiedInSnapshot(snapshot, gateMilestoneId);
+                if (!alreadyVerified) {
+                    setPendingGate(questionId, basePath);
+                }
                 clearDeferredApprovalGate(basePath);
             }
         }
+        // Safety harness: record evidence here, not only in tool_call. External
+        // engines (claude-code-cli) pre-execute tools, so the agent loop skips
+        // beforeToolCall/tool_call for them — tool_execution_start is the only
+        // event that fires for every tool call. recordToolCall dedupes by
+        // toolCallId, so native tools (which hit both events) record once.
+        safetyRecordToolCall(event.toolCallId, event.toolName, (event.args ?? {}));
+        const execDash = getAutoRuntimeSnapshot();
+        if (execDash.basePath && execDash.currentUnit?.type === "execute-task") {
+            const { milestone: xMid, slice: xSid, task: xTid } = parseUnitId(execDash.currentUnit.id);
+            if (xMid && xSid && xTid) {
+                saveEvidenceToDisk(execDash.basePath, xMid, xSid, xTid);
+            }
+        }
         if (!isAutoActive())
             return;
         markToolStart(event.toolCallId, event.toolName);
@@ -1223,12 +1353,13 @@ export function registerHooks(pi, ecosystemHandlers) {
             return surfaceReduced ? { toolNames: providerCompatible } : undefined;
         }
         const registeredToolNames = resolveRegisteredToolNames(pi, event.activeToolNames);
+        const hasRegisteredSurface = typeof pi.getAllTools === "function";
         const compatibleRegisteredToolNames = filterToolsForProvider(registeredToolNames, event.selectedModelApi, event.selectedModelProvider).compatible.filter((name) => !(dropAliases && isWorkflowAliasTool(name)));
         const guidedUnit = getGuidedUnitContext();
         const requestRegisteredToolNames = guidedUnit?.unitType === "run-uat"
             ? compatibleRegisteredToolNames
             : registeredToolNames;
-        const requestScoped = buildRequestScopedGsdToolSet(guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible, event.requestCustomMessages, requestRegisteredToolNames, guidedUnit?.unitType);
+        const requestScoped = buildRequestScopedGsdToolSet(guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible, event.requestCustomMessages, requestRegisteredToolNames, guidedUnit?.unitType, hasRegisteredSurface);
         if (requestScoped) {
             recordAutoToolSurfaceSnapshot({
                 source: "provider-adjustment",
@@ -1244,7 +1375,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             const registeredForUnit = dash.currentUnit.type === "run-uat"
                 ? compatibleRegisteredToolNames
                 : resolveRegisteredToolNames(pi, event.activeToolNames);
-            const scopedToolNames = buildMinimalAutoGsdToolSet(dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible, dash.currentUnit.type, registeredForUnit);
+            const scopedToolNames = buildMinimalAutoGsdToolSet(dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible, dash.currentUnit.type, registeredForUnit, hasRegisteredSurface);
             recordAutoToolSurfaceSnapshot({
                 source: "provider-adjustment",
                 unitType: dash.currentUnit.type,

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

@@ -8,6 +8,7 @@ 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";
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
  * and unique M001-abc123 formats. Exported so regex-hardening tests
@@ -214,6 +215,27 @@ export function loadWriteGateSnapshot(basePath) {
         return currentWriteGateSnapshot(basePath);
     }
 }
+/**
+ * Merge 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.
+ *
+ * Returns the snapshot used for the refresh so callers that need to inspect
+ * it (e.g. re-arm guards) avoid a second disk read.
+ */
+export function refreshWriteGateStateFromDisk(basePath) {
+    const snapshot = loadWriteGateSnapshot(basePath);
+    if (!shouldPersistWriteGateSnapshot())
+        return snapshot;
+    const state = getWriteGateState(basePath);
+    state.pendingGateId = snapshot.pendingGateId;
+    state.activeQueuePhase = snapshot.activeQueuePhase;
+    state.verifiedDepthMilestones = new Set(snapshot.verifiedDepthMilestones);
+    state.verifiedApprovalGates = new Set(snapshot.verifiedApprovalGates ?? []);
+    return snapshot;
+}
 export function isDepthVerified(basePath = process.cwd()) {
     return getWriteGateState(basePath).verifiedDepthMilestones.size > 0;
 }
@@ -223,6 +245,7 @@ export function isDepthVerified(basePath = process.cwd()) {
 export function isMilestoneDepthVerified(milestoneId, basePath = process.cwd()) {
     if (!milestoneId)
         return false;
+    refreshWriteGateStateFromDisk(basePath);
     return getWriteGateState(basePath).verifiedDepthMilestones.has(milestoneId);
 }
 export function isMilestoneDepthVerifiedInSnapshot(snapshot, milestoneId) {
@@ -309,6 +332,7 @@ export function clearPendingGate(basePath) {
  * Get the currently pending gate, if any.
  */
 export function getPendingGate(basePath = process.cwd()) {
+    refreshWriteGateStateFromDisk(basePath);
     return getWriteGateState(basePath).pendingGateId;
 }
 /**
@@ -919,10 +943,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)) {

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

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

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

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

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

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

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

@@ -8,9 +8,10 @@
  * `.gsd/CAPTURES.md`, not the worktree's local `.gsd/`.
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { join, resolve, sep } from "node:path";
+import { join, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { gsdRoot } from "./paths.js";
+import { projectRootFromWorktreePath } from "./worktree-root.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CAPTURES_FILENAME = "CAPTURES.md";
 const VALID_CLASSIFICATIONS = [
@@ -29,20 +30,9 @@ const VALID_CLASSIFICATIONS = [
  * directory that contains `.gsd/worktrees/` — that's the project root.
  */
 export function resolveCapturesPath(basePath) {
-    const resolved = resolve(basePath);
-    // Direct layout: /.gsd/worktrees/
-    const worktreeMarker = `${sep}.gsd${sep}worktrees${sep}`;
-    let idx = resolved.indexOf(worktreeMarker);
-    if (idx === -1) {
-        // Symlink-resolved layout: /.gsd/projects/<hash>/worktrees/
-        const symlinkRe = new RegExp(`\\${sep}\\.gsd\\${sep}projects\\${sep}[a-f0-9]+\\${sep}worktrees\\${sep}`);
-        const match = resolved.match(symlinkRe);
-        if (match && match.index !== undefined)
-            idx = match.index;
-    }
-    if (idx !== -1) {
-        // basePath is inside a worktree — resolve to project root
-        const projectRoot = resolved.slice(0, idx);
+    // If basePath is inside a worktree, resolve to the project root.
+    const projectRoot = projectRootFromWorktreePath(resolve(basePath));
+    if (projectRoot) {
         return join(projectRoot, ".gsd", CAPTURES_FILENAME);
     }
     return join(gsdRoot(basePath), CAPTURES_FILENAME);

package/dist/resources/extensions/gsd/closeout-recovery.js

@@ -2,12 +2,13 @@
 // File Purpose: Closeout git failure discovery, retry, and manual resolution helpers.
 import { execFileSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, resolve } from "node:path";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { runTurnGitAction } from "./git-service.js";
 import { _getAdapter, upsertTurnGitTransaction } from "./gsd-db.js";
 import { probeGitConflictState } from "./git-conflict-state.js";
 import { parseUnitId } from "./unit-id.js";
+import { worktreePathFor } from "./worktree-placement.js";
 function parseMetadata(value) {
     if (typeof value !== "string" || !value.trim())
         return {};
@@ -121,7 +122,7 @@ export function resolveCloseoutRecoveryBasePath(projectRoot, record) {
     const parsed = parseUnitId(record.unitId);
     const milestoneId = parsed.milestone ?? (/^M\d+(?:-[a-z0-9]{6})?/.exec(record.unitId)?.[0] ?? "");
     if (milestoneId) {
-        const worktreePath = existingRealPath(join(projectRoot, ".gsd", "worktrees", milestoneId));
+        const worktreePath = existingRealPath(worktreePathFor(projectRoot, milestoneId));
         if (worktreePath)
             return worktreePath;
     }