@opengsd/gsd-pi 1.3.0-dev.eed73bea → 1.4.0-dev.5fc22c6f

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -32,9 +32,16 @@ import {
   recordAutoToolSurfaceSnapshot,
   recordToolInvocationError,
 } from "../auto-runtime-state.js";
+import {
+  isDeterministicPolicyError,
+  isQueuedUserMessageSkip,
+  isToolInvocationError,
+  isToolUnavailableError,
+} from "../auto-tool-tracking.js";
 import { applyProviderPayloadPolicy } from "../provider-payload-policy.js";
 
-import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
+import { checkToolCallLoop, recordToolCallLoopMutation, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
+import { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 import { maybePauseAutoForApprovalGate, resetPendingGatePauseGuard } from "./pending-gate-pause.js";
 import { saveActivityLog } from "../activity-log.js";
 import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult, saveEvidenceToDisk } from "../safety/evidence-collector.js";
@@ -75,9 +82,25 @@ 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";
+import { flushAllManifests } from "../workflow-manifest.js";
+import { recordUnitHarnessAbort, type UnitHarnessAbortRecord } from "../unit-runtime.js";
 
 let approvalQuestionAbortInFlight = false;
 
+function recordCurrentUnitHarnessAbort(
+  abort: Omit<UnitHarnessAbortRecord, "recordedAt"> & { recordedAt?: number },
+): void {
+  const dash = getAutoRuntimeSnapshot();
+  if (!dash.active || !dash.basePath || !dash.currentUnit) return;
+  recordUnitHarnessAbort(
+    dash.basePath,
+    dash.currentUnit.type,
+    dash.currentUnit.id,
+    dash.currentUnit.startedAt,
+    abort,
+  );
+}
+
 type WelcomeScreenModule = {
   buildWelcomeScreenLines(opts: { version: string; remoteChannel?: string; width?: number }): string[];
 };
@@ -178,22 +201,7 @@ export const MINIMAL_GSD_TOOL_NAMES = [
   "gsd_capture_thought",
 ] as const;
 
-export const MINIMAL_AUTO_BASE_TOOL_NAMES = [
-  "ask_user_questions",
-  "bash",
-  "bg_shell",
-  "edit",
-  "find",
-  "glob",
-  "grep",
-  "fetch_page",
-  "search-the-web",
-  "ls",
-  "read",
-  "subagent",
-  "write",
-  "ToolSearch",
-] as const;
+export { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 
 function withPreservedShimTools(toolNames: readonly string[]): string[] {
   return [...new Set([...toolNames, ...ALWAYS_PRESERVED_SHIM_TOOL_NAMES])];
@@ -222,10 +230,26 @@ const WORKFLOW_GSD_TOOL_NAMES = [
   ...Object.values(AUTO_UNIT_SCOPED_TOOLS).flat(),
 ].filter(isGsdManagedTool);
 
+const WORKFLOW_ONLY_AUTO_BASE_TOOL_NAMES = [
+  "find",
+  "glob",
+  "grep",
+  "ls",
+  "read",
+  "subagent",
+] as const;
+
 function isGsdManagedTool(name: string): boolean {
   return name.startsWith("gsd_") || name === "memory_query" || name === "capture_thought" || name === "gsd_graph";
 }
 
+function autoBaseToolNamesForUnit(unitType: string | undefined): readonly string[] {
+  const manifest = unitType ? resolveManifest(unitType) : null;
+  return manifest?.tools.mode === "workflow-only"
+    ? WORKFLOW_ONLY_AUTO_BASE_TOOL_NAMES
+    : MINIMAL_AUTO_BASE_TOOL_NAMES;
+}
+
 /**
  * Resolves requested tool names against active tools using exact and MCP-scoped matches.
  *
@@ -288,7 +312,7 @@ export function buildMinimalAutoGsdToolSet(
     return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
   }
   const unitTools = unitType ? AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [] : [];
-  const autoBaseTools = new Set<string>(MINIMAL_AUTO_BASE_TOOL_NAMES);
+  const autoBaseTools = new Set<string>(autoBaseToolNamesForUnit(unitType));
   const availableBaseTools = registeredToolNames.filter((name) => autoBaseTools.has(name));
   const preserved = [...new Set([
     ...activeToolNames.filter((name) => autoBaseTools.has(name)),
@@ -597,6 +621,87 @@ function contextBasePath(ctx?: { cwd?: string }): string {
   return typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd();
 }
 
+const LOOP_GUARD_INTERACTIVE_INSTRUCTIONS = [
+  "Do not retry this tool or call other tools this turn — stop and respond to the user in text.",
+  "Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.",
+];
+const LOOP_GUARD_AUTO_INSTRUCTION =
+  "Do not re-issue this blocked tool. In /gsd auto, stop tool calls for this turn and return control to the auto-mode recovery/replan path.";
+
+function formatLoopGuardBlockReason(reason: string | undefined): string | undefined {
+  if (!reason || !getAutoRuntimeSnapshot().active) return reason;
+  return LOOP_GUARD_INTERACTIVE_INSTRUCTIONS.reduce(
+    (formatted, instruction) => formatted.replace(instruction, LOOP_GUARD_AUTO_INSTRUCTION),
+    reason,
+  );
+}
+
+function isGateResultPersistenceTool(toolName: string): boolean {
+  return toolName === "gsd_save_gate_result" || toolName === "gsd_uat_result_save";
+}
+
+function resultDetails(result: unknown): Record<string, unknown> {
+  if (!result || typeof result !== "object") return {};
+  const details = (result as { details?: unknown }).details;
+  return details && typeof details === "object" ? details as Record<string, unknown> : {};
+}
+
+function isAbortedExecutionToolResult(toolName: string, result: unknown): boolean {
+  if (toolName !== "gsd_exec" && toolName !== "gsd_uat_exec") return false;
+  const details = resultDetails(result);
+  return details.aborted === true || details.force_resolved === true || details.timed_out === true;
+}
+
+function isRetryableHarnessToolError(toolName: string, result: unknown, errorText: string): boolean {
+  if (isGateResultPersistenceTool(toolName)) return false;
+  if (isDeterministicPolicyError(errorText)) return false;
+  if (toolName === "gsd_exec" || toolName === "gsd_uat_exec") {
+    if (isAbortedExecutionToolResult(toolName, result)) return true;
+    if (isToolUnavailableError(errorText)) return true;
+    if (isQueuedUserMessageSkip(errorText)) return true;
+    return isToolInvocationError(errorText);
+  }
+  if (isToolUnavailableError(errorText)) return true;
+  if (isQueuedUserMessageSkip(errorText)) return true;
+  return false;
+}
+
+function recordRetryableHarnessToolError(toolName: string, result: unknown, errorText: string): void {
+  if (!isRetryableHarnessToolError(toolName, result, errorText)) return;
+  recordCurrentUnitHarnessAbort({
+    kind: "tool-error",
+    reason: errorText || "Tool execution failed before the unit could complete its gate evaluation.",
+    toolName,
+  });
+}
+
+function recordRetryableTurnAbort(event: { abortOrigin?: unknown; messages?: unknown[] }): void {
+  const origin = typeof event.abortOrigin === "string" ? event.abortOrigin : undefined;
+  if (origin === "session-transition") return;
+
+  const messages = Array.isArray(event.messages) ? event.messages : [];
+  const lastMsg = messages[messages.length - 1];
+  const stopReason = lastMsg && typeof lastMsg === "object"
+    ? (lastMsg as { stopReason?: unknown }).stopReason
+    : undefined;
+  if (stopReason !== "aborted" && stopReason !== "error") return;
+
+  const errorMessage = lastMsg && typeof lastMsg === "object"
+    ? (lastMsg as { errorMessage?: unknown }).errorMessage
+    : undefined;
+  const reason = [
+    "Agent turn aborted before the unit could complete its gate evaluation.",
+    origin ? `origin=${origin}` : undefined,
+    typeof stopReason === "string" ? `stopReason=${stopReason}` : undefined,
+    typeof errorMessage === "string" && errorMessage.trim() ? `error=${errorMessage.trim()}` : undefined,
+  ].filter(Boolean).join(" ");
+
+  recordCurrentUnitHarnessAbort({
+    kind: "turn-abort",
+    reason,
+  });
+}
+
 function beginSourceObservationStoreForCurrentUnit(
   ctx?: { cwd?: string },
 ): ReturnType<typeof getSourceObservationStore> | null {
@@ -900,8 +1005,8 @@ export function registerHooks(
     await prepareWorkflowMcpForHookContext(ctx, basePath);
 
     // Migrate legacy .gsd/milestones/ to flat-phase .gsd/phases/ when detected.
-    // Best-effort — never blocks session startup. Skipped inside auto-worktrees
-    // (migration already ran on the project root before the worktree was created).
+    // Fail closed on migration errors: resolvers assume flat-phase paths after
+    // startup, so continuing with nested disk state corrupts later checks.
     try {
       const { isInAutoWorktree } = await import("../auto-worktree.js");
       if (!isInAutoWorktree(basePath)) {
@@ -915,13 +1020,32 @@ export function registerHooks(
           } else {
             safetyLogWarning(
               "bootstrap",
-              "flat-phase migration deferred: legacy .gsd/milestones/ layout detected but the workflow database could not be opened — will retry on next session",
+              "flat-phase migration required: legacy .gsd/milestones/ layout detected but the workflow database could not be opened — fix database access before starting GSD",
+            );
+            throw new Error(
+              "flat-phase migration required but the workflow database could not be opened; fix database access before starting GSD",
             );
           }
         }
       }
     } catch (err) {
-      safetyLogWarning("bootstrap", `flat-phase migration: ${err instanceof Error ? err.message : String(err)}`);
+      const message = err instanceof Error ? err.message : String(err);
+      safetyLogWarning("bootstrap", `flat-phase migration failed: ${message}`);
+      throw new Error(`flat-phase migration failed: ${message}`);
+    }
+
+    try {
+      const projectRoot = resolveWorktreeProjectRoot(basePath);
+      const { pruneStaleFlatPhaseBackups } = await import("../flat-phase-migration.js");
+      const pruned = pruneStaleFlatPhaseBackups(projectRoot);
+      if (pruned > 0) {
+        safetyLogWarning(
+          "bootstrap",
+          `pruned ${pruned} stale flat-phase migration backup(s) from .gsd-backups/ (retention exceeded)`,
+        );
+      }
+    } catch (err) {
+      safetyLogWarning("bootstrap", `flat-phase backup pruning: ${err instanceof Error ? err.message : String(err)}`);
     }
 
     // Apply show_token_cost preference (#1515)
@@ -1079,12 +1203,26 @@ export function registerHooks(
 
   pi.on("agent_end", async (event, ctx: ExtensionContext) => {
     approvalQuestionAbortInFlight = false;
+    recordRetryableTurnAbort(event);
     resetToolCallLoopGuard();
     resetPendingGatePauseGuard();
     await resetAskUserQuestionsTurnCache();
     const { handleAgentEnd } = await import("./agent-end-recovery.js");
     const agentEndBasePath = contextBasePath(ctx);
     try {
+      // The manifest is a non-critical projection (the append-only event log is
+      // the authoritative recovery source), so a flush failure must not skip
+      // agent_end recovery. drainManifestWrites still propagates write failures
+      // to explicit flush callers; here we deliberately log and continue so
+      // handleAgentEnd (and the finally below) always run.
+      try {
+        await flushAllManifests();
+      } catch (err) {
+        safetyLogWarning(
+          "manifest",
+          `flushAllManifests on agent_end failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
       await handleAgentEnd(pi, event, ctx);
     } finally {
       activateDeferredApprovalGate(agentEndBasePath);
@@ -1291,7 +1429,13 @@ export function registerHooks(
     // ── Loop guard: block repeated identical tool calls ──
     const loopCheck = checkToolCallLoop(toolName, event.input as Record<string, unknown>);
     if (loopCheck.block) {
-      return { block: true, reason: loopCheck.reason };
+      recordCurrentUnitHarnessAbort({
+        kind: "tool-loop-guard",
+        reason: loopCheck.reason ?? "Tool-call loop guard blocked a repeated tool call.",
+        toolName,
+        count: loopCheck.count,
+      });
+      return { block: true, reason: formatLoopGuardBlockReason(loopCheck.reason) };
     }
 
     const deferredGateGuard = shouldBlockDeferredApprovalTool(
@@ -1563,6 +1707,7 @@ export function registerHooks(
       }
     }
     if (!event.isError) {
+      recordToolCallLoopMutation(toolName);
       refreshSourceObservationAfterMutation(toolName, event.input, ctx);
       clearSourceObservationsAfterShell(toolName);
     }
@@ -1578,6 +1723,7 @@ export function registerHooks(
       // Let recordToolInvocationError classify the failure so non-gsd_ harness
       // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
+      recordRetryableHarnessToolError(toolName, resultPayload, errorText);
     } else if (isAutoActive()) {
       clearToolInvocationError();
     }
@@ -1774,6 +1920,7 @@ export function registerHooks(
   // for every finalized tool call on every engine, so error classification
   // and evidence persistence here cover external engines that skip tool_result.
   pi.on("tool_execution_end", async (event) => {
+    const toolName = canonicalToolName(event.toolName);
     markToolEnd(event.toolCallId);
     // #2883/#4974: Capture deterministic invocation/policy errors
     // so postUnitPreVerification can break the retry loop instead of re-dispatching.
@@ -1784,6 +1931,7 @@ export function registerHooks(
       // Let recordToolInvocationError classify the failure so non-gsd_ harness
       // errors and deterministic policy rejections are handled consistently.
       recordToolInvocationError(event.toolName, errorText);
+      recordRetryableHarnessToolError(toolName, event.result, errorText);
     } else if (isAutoActive()) {
       clearToolInvocationError();
     }

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

@@ -9,13 +9,14 @@
 
 import { test, describe, before, after } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { mkdtempSync, rmSync, existsSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import {
   markDepthVerified,
   loadWriteGateSnapshot,
+  shouldBlockContextArtifactSaveInSnapshot,
   clearDiscussionFlowState,
 } from "../write-gate.js";
 
@@ -100,4 +101,51 @@ describe("write-gate basePath regression", () => {
       "loadWriteGateSnapshot(baseDirB) must not bleed state from baseDirA",
     );
   });
+
+  test("worktree basePath reads depth verification from project-root snapshot", (t) => {
+    const prev = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    t.after(() => {
+      if (prev === undefined) {
+        delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+      } else {
+        process.env.GSD_PERSIST_WRITE_GATE_STATE = prev;
+      }
+    });
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
+
+    const projectRoot = makeTempDir();
+    const worktreePath = join(projectRoot, ".gsd-worktrees", "M020");
+    t.after(() => {
+      rmSync(projectRoot, { recursive: true, force: true });
+    });
+
+    clearDiscussionFlowState(projectRoot);
+    clearDiscussionFlowState(worktreePath);
+
+    // Simulate MCP routing: verification recorded at project root.
+    markDepthVerified("M020", projectRoot);
+
+    // Worktree has a local .gsd projection but no write-gate snapshot file.
+    mkdirSync(join(worktreePath, ".gsd", "runtime"), { recursive: true });
+    mkdirSync(join(projectRoot, ".gsd", "milestones"), { recursive: true });
+
+    const projectSnapshotPath = join(projectRoot, ".gsd", "runtime", "write-gate-state.json");
+    const worktreeSnapshotPath = join(worktreePath, ".gsd", "runtime", "write-gate-state.json");
+    assert.ok(existsSync(projectSnapshotPath), "verification snapshot lives at project root");
+    assert.ok(!existsSync(worktreeSnapshotPath), "worktree must not have its own snapshot file");
+
+    const snapshotFromWorktree = loadWriteGateSnapshot(worktreePath);
+    assert.ok(
+      snapshotFromWorktree.verifiedDepthMilestones.includes("M020"),
+      "loadWriteGateSnapshot(worktree) must inherit project-root verification",
+    );
+
+    const guard = shouldBlockContextArtifactSaveInSnapshot(
+      snapshotFromWorktree,
+      "CONTEXT",
+      "M020",
+      null,
+    );
+    assert.equal(guard.block, false, "CONTEXT save must unblock once project-root gate is verified");
+  });
 });

package/src/resources/extensions/gsd/bootstrap/tool-call-loop-guard.ts

@@ -1,25 +1,32 @@
 /**
  * Tool-call loop guard.
  *
- * Detects when a model calls the same tool with identical arguments
- * repeatedly within a single agent turn. Works in both auto-mode and
- * interactive sessions by hooking into the `tool_call` event, which
- * fires before execution and can block the call.
+ * Detects when a model repeats tool calls within a single Agent Turn.
+ * Works in both auto-mode and interactive sessions by hooking into the
+ * native engine's `tool_call` event, which fires before execution and can
+ * block the call.
  *
- * The guard uses a sliding window: it tracks the last N tool signatures
- * and blocks when the same signature appears more than MAX_CONSECUTIVE
- * times in a row. Resets on each agent turn (session_start, agent_end)
- * and when a different tool call breaks the streak.
+ * The guard has two independent checks: a sliding window for identical
+ * tool signatures, and a per-tool-name cap for repeated calls with varied
+ * arguments. State resets at Agent Turn boundaries (session_start,
+ * agent_end) and the identical-signature streak also resets when a
+ * different tool call breaks the streak. Block messages instruct the model
+ * to stop tooling for the rest of that turn and answer in text.
  *
- * A second, independent check (#783 Brief C) tracks per-tool-name call
- * counts within a turn regardless of args. This catches improvisation
+ * The per-tool-name check (#783 Brief C) tracks call counts within a
+ * turn regardless of args, decaying after successful state-mutating tools.
+ * This catches improvisation
  * loops where the model attempts the same missing workflow tool through
  * varied surfaces (bash → `node -e` → CLI), each with a different
- * signature, so the identical-args streak never trips. Whichever guard
+ * signature, so the identical-args streak never trips, while allowing
+ * tool-heavy turns that are making file-mutation progress. Whichever guard
  * trips first blocks.
  */
 
 import { createHash } from "node:crypto";
+import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
 
 const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 
@@ -39,27 +46,8 @@ const MAX_CONSECUTIVE_STRICT = 1;
  */
 const PER_TOOL_DEFAULT_CAP = 6;
 const PER_TOOL_REPEATABLE_CAP = 15;
-
-/**
- * Inherently-repeatable tools: called many times per turn in normal work
- * (reading/writing several files, running several commands, searching). These
- * get PER_TOOL_REPEATABLE_CAP rather than the default. Keep this list
- * conservative — a tool here can be invoked up to PER_TOOL_REPEATABLE_CAP times
- * per turn before the guard blocks.
- */
-const REPEATABLE_TOOLS = new Set([
-  "read",
-  "write",
-  "edit",
-  "multi_edit",
-  "bash",
-  "grep",
-  "glob",
-  "search-the-web",
-  "fetch_page",
-  "todo_write",
-  "notebook_edit",
-]);
+const PER_TOOL_CAP_EXEMPT_TOOLS = new Set(["find", "glob", "grep", "ls", "read", "search_and_read"]);
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
 
 let consecutiveCount = 0;
 let lastSignature = "";
@@ -68,6 +56,8 @@ let enabled = true;
 
 /** Per-tool-name call counts within the current turn (#783 Brief C). */
 const perToolCounts = new Map<string, number>();
+let mutationEpoch = 0;
+const perToolLastMutationEpoch = new Map<string, number>();
 
 /** Hash tool name + args into a compact signature for comparison. */
 function hashToolCall(toolName: string, args: Record<string, unknown>): string {
@@ -95,7 +85,8 @@ function hashToolCall(toolName: string, args: Record<string, unknown>): string {
  *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
  *     ask_user_questions).
  *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
- *     independent of args — catches improvisation loops (#783).
+ *     independent of args, reset after file-mutation progress — catches
+ *     improvisation loops (#783).
  */
 export function checkToolCallLoop(
   toolName: string,
@@ -124,7 +115,7 @@ export function checkToolCallLoop(
       reason:
         `Tool loop detected (identical args): ${toolName} called ${consecutiveCount} times ` +
         `with identical arguments. Blocking to prevent infinite loop. ` +
-        `Try a different approach or modify your arguments.`,
+        `Do not retry this tool or call other tools this turn — stop and respond to the user in text.`,
       count: consecutiveCount,
     };
   }
@@ -132,9 +123,29 @@ export function checkToolCallLoop(
   // ── Guard 2: per-tool-name cap, independent of args (#783 Brief C) ──
   // Catches improvisation loops where the same tool is invoked many times with
   // varied args (e.g. retrying a missing workflow tool via bash/node -e/CLI).
-  const perToolCount = (perToolCounts.get(toolName) ?? 0) + 1;
+  const priorPerToolCount =
+    (perToolLastMutationEpoch.get(toolName) ?? mutationEpoch) < mutationEpoch
+      ? 0
+      : (perToolCounts.get(toolName) ?? 0);
+  const perToolCount = priorPerToolCount + 1;
   perToolCounts.set(toolName, perToolCount);
-  const perToolCap = REPEATABLE_TOOLS.has(toolName)
+  perToolLastMutationEpoch.set(toolName, mutationEpoch);
+
+  // Read-only navigation tools are normal context gathering; Guard 1 still
+  // catches true reread loops with identical arguments. Browser Automation
+  // Contract tools (browser_*) are the same shape: a browser-backed UAT makes
+  // many distinct-arg calls (read a message, count edits, inspect a card, …),
+  // so the arg-independent per-tool cap misfires on legitimate verification;
+  // Guard 1's identical-signature streak still catches a genuinely stuck
+  // browser loop.
+  if (
+    PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName) ||
+    hasBrowserContractPrefix(canonicalToolName(toolName))
+  ) {
+    return { block: false, count: consecutiveCount };
+  }
+
+  const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
     ? PER_TOOL_REPEATABLE_CAP
     : PER_TOOL_DEFAULT_CAP;
 
@@ -144,7 +155,8 @@ export function checkToolCallLoop(
       reason:
         `Tool loop detected (repeated tool): ${toolName} called ${perToolCount} times ` +
         `this turn (cap ${perToolCap}). Blocking to prevent infinite loop. ` +
-        `The tool may be unavailable or failing repeatedly — try a different approach.`,
+        `The tool may be unavailable or failing repeatedly. ` +
+        `Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.`,
       count: perToolCount,
     };
   }
@@ -152,6 +164,13 @@ export function checkToolCallLoop(
   return { block: false, count: consecutiveCount };
 }
 
+/** Record successful mutation progress so Guard 2 can decay on the next count. */
+export function recordToolCallLoopMutation(toolName: string): void {
+  if (!enabled) return;
+  if (!STATE_MUTATING_TOOL_SET.has(toolName)) return;
+  mutationEpoch++;
+}
+
 /** Reset the guard state. Call at agent turn boundaries. */
 export function resetToolCallLoopGuard(): void {
   consecutiveCount = 0;
@@ -159,6 +178,8 @@ export function resetToolCallLoopGuard(): void {
   lastToolName = "";
   enabled = true;
   perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Disable the guard (e.g. during shutdown). */
@@ -168,6 +189,8 @@ export function disableToolCallLoopGuard(): void {
   lastSignature = "";
   lastToolName = "";
   perToolCounts.clear();
+  mutationEpoch = 0;
+  perToolLastMutationEpoch.clear();
 }
 
 /** Get current consecutive count for diagnostics. */

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

@@ -97,8 +97,19 @@ function createEmptyWriteGateState(): InMemoryWriteGateState {
 
 const writeGateStatesByBasePath = new Map<string, InMemoryWriteGateState>();
 
+/**
+ * Write-gate snapshots are project-scoped, not worktree-scoped. When auto-mode
+ * routes MCP tool writes to `.gsd-worktrees/<MID>/`, depth verification still
+ * lands in the authoritative project `.gsd/runtime/` tree (or external-state
+ * symlink target). Without this canonicalization, `loadWriteGateSnapshot(worktree)`
+ * sees an empty snapshot and CONTEXT saves loop forever (#M020 gate loop).
+ */
+function resolveWriteGateSnapshotRoot(basePath: string): string {
+  return resolve(resolveWorktreeProjectRoot(basePath));
+}
+
 function writeGateStateKey(basePath: string): string {
-  return resolve(basePath);
+  return resolveWriteGateSnapshotRoot(basePath);
 }
 
 function getWriteGateState(basePath: string = process.cwd()): InMemoryWriteGateState {
@@ -161,17 +172,18 @@ function shouldPersistWriteGateSnapshot(env: NodeJS.ProcessEnv = process.env): b
 }
 
 function writeGateSnapshotPath(basePath: string): string {
-  return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+  return join(resolveWriteGateSnapshotRoot(basePath), ".gsd", "runtime", "write-gate-state.json");
 }
 
 function ensureWriteGateSnapshotDirectory(basePath: string): void {
-  const gsdPath = join(basePath, ".gsd");
+  const snapshotRoot = resolveWriteGateSnapshotRoot(basePath);
+  const gsdPath = join(snapshotRoot, ".gsd");
   if (!existsSync(gsdPath)) {
     try {
       const stat = lstatSync(gsdPath);
       if (stat.isSymbolicLink()) {
         const target = readlinkSync(gsdPath);
-        mkdirSync(isAbsolute(target) ? target : resolve(basePath, target), { recursive: true });
+        mkdirSync(isAbsolute(target) ? target : resolve(snapshotRoot, target), { recursive: true });
       }
     } catch {
       // If .gsd truly does not exist, the runtime mkdir below will create it.
@@ -1157,7 +1169,7 @@ function allowsControlledSubagentDispatch(
   policy: ToolsPolicy,
 ): policy is ToolsPolicy & { readonly allowedSubagents: readonly string[] } {
   return (
-    (policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    (policy.mode === "planning-dispatch" || policy.mode === "verification" || policy.mode === "workflow-only") &&
     Array.isArray((policy as { readonly allowedSubagents?: unknown }).allowedSubagents)
   );
 }
@@ -1187,6 +1199,7 @@ function warnMissingControlledDispatchAgentClasses(unitType: string, mode: strin
 const PLANNING_SAFE_TOOLS = new Set([
   "read", "grep", "find", "ls", "glob",
   "ask_user_questions",
+  "memory_query",
   "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
   "search_and_read",
 ]);
@@ -1253,6 +1266,9 @@ type PlanningUnitBlockResult = {
  *                  → allows Bash for project verification commands, keeps
  *                    writes restricted to .gsd/, and permits subagent dispatch
  *                    only when the manifest declares allowedSubagents.
+ *   - "workflow-only"
+ *                  → allows reads, GSD workflow tools, and declared read-only
+ *                    subagents; blocks generic Bash and direct file writes.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -1342,6 +1358,24 @@ export function shouldBlockPlanningUnit(
     return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
   }
 
+  if (policy.mode === "workflow-only") {
+    if (tool === "bash") {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `bash is not permitted; use the unit's dedicated GSD workflow tools for durable validation output`,
+      );
+    }
+    if (PLANNING_WRITE_TOOLS.has(tool)) {
+      return planningBlock(
+        unitType,
+        policy.mode,
+        `cannot ${tool} "${pathOrCommand}" — direct artifact writes are disabled; call the required GSD workflow tool instead`,
+      );
+    }
+    return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the workflow-only allowlist`);
+  }
+
   if (tool === "bash") {
     if (policy.mode === "verification") {
       if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };

package/src/resources/extensions/gsd/closeout-consistency-gate.ts

@@ -18,7 +18,7 @@ import {
   getWorkflowDatabasePath,
   refreshWorkflowDatabaseFromDisk,
 } from "./db-workspace.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "./status-guards.js";
 import { closeQualityGatesFromEvidence } from "./quality-gate-closure.js";
 import { insertMilestoneValidationGates } from "./milestone-validation-gates.js";
 import { relMilestoneFile, resolveSliceFile } from "./paths.js";
@@ -229,6 +229,7 @@ export function checkCloseoutConsistencyGate(
   }
 
   for (const slice of slices) {
+    if (isDeferredStatus(slice.status)) continue;
     if (!isClosedStatus(slice.status)) {
       return blocked(
         "slice-open",