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

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

@@ -27,7 +27,7 @@ import { writeLock, clearLock, clearStaleWorkerLock, readCrashLock, isLockProces
 import { acquireSessionLock, getSessionLockStatus, releaseSessionLock, updateSessionLock, } from "./session-lock.js";
 import { resolveAutoSupervisorConfig, loadEffectiveGSDPreferences, loadEffectiveGSDPreferencesWithRegistry, resolveProfileAnchorProvider, getIsolationMode, resolveEffectiveUnitIsolationMode, } from "./preferences.js";
 import { playNotificationBell, sendDesktopNotification } from "./notifications.js";
-import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, } from "./auto-budget.js";
+import { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, HARD_CONTEXT_REROOT_THRESHOLD_PERCENT, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, shouldWarnStepSessionForContext, } from "./auto-budget.js";
 import { markToolStart as _markToolStart, markToolEnd as _markToolEnd, getOldestInFlightToolAgeMs as _getOldestInFlightToolAgeMs, clearInFlightTools, isToolInvocationError, isQueuedUserMessageSkip, isDeterministicPolicyError, } from "./auto-tool-tracking.js";
 import { closeoutUnit } from "./auto-unit-closeout.js";
 import { selectAndApplyModel, resolveModelId, clearToolBaseline } from "./auto-model-selection.js";
@@ -369,7 +369,7 @@ function getEffectiveUnitIsolationMode(basePath) {
  * running suspiciously long (e.g., a Bash command hung because `&` kept stdout open).
  */
 // Re-export budget utilities for external consumers
-export { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, getContextPauseAction, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, } from "./auto-budget.js";
+export { getBudgetAlertLevel, getNewBudgetAlertLevel, getBudgetEnforcementAction, getContextPauseAction, resolveCompactionThresholdPercent, shouldRerootStepSessionForContext, shouldWarnStepSessionForContext, } from "./auto-budget.js";
 function closeOutSignalInterruptedUnit(currentBasePath) {
     const currentUnit = s.currentUnit;
     if (!currentUnit)
@@ -904,9 +904,10 @@ export async function rerootCommandSession(cmdCtx, workspaceRoot) {
     }
 }
 /**
- * After a completed step-mode unit, reclaim context headroom when usage is at
- * or above the compaction threshold. Writes a context-mode snapshot first, then
- * re-roots the visible command session while leaving the NEXT progress surface.
+ * After a completed step-mode unit, warn when usage reaches the configurable
+ * soft context threshold. At the fixed hard boundary, write a context-mode
+ * snapshot and re-root the visible command session while leaving the NEXT
+ * progress surface.
  */
 export async function maybeRerootStepSessionForHighContext(ctx, workspaceRoot, cmdCtx, originalBasePath) {
     if (!cmdCtx)
@@ -915,18 +916,24 @@ export async function maybeRerootStepSessionForHighContext(ctx, workspaceRoot, c
     const { loadEffectiveGSDPreferences } = await import("./preferences.js");
     const prefs = loadEffectiveGSDPreferences(workspaceRoot);
     const compactionThreshold = prefs?.preferences.context_management?.compaction_threshold_percent;
-    if (!shouldRerootStepSessionForContext(contextPercent, compactionThreshold)) {
+    const shouldWarn = shouldWarnStepSessionForContext(contextPercent, compactionThreshold);
+    const shouldReroot = shouldRerootStepSessionForContext(contextPercent);
+    if (!shouldWarn && !shouldReroot) {
+        return { rerooted: false };
+    }
+    const displayPercent = contextPercent.toFixed(1);
+    const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
+    if (!shouldReroot) {
+        ctx.ui.notify(`Step complete — context at ${displayPercent}% (soft threshold: ${thresholdDisplay}%). Use /compact when convenient; continuing in this session is still safe.`, "info");
         return { rerooted: false };
     }
     const { resolveWorktreeProjectRoot } = await import("./worktree-root.js");
     const snapshotBase = resolveWorktreeProjectRoot(workspaceRoot, originalBasePath);
     const { writeContextModeCompactionSnapshot } = await import("./context-mode-snapshot.js");
     await writeContextModeCompactionSnapshot(snapshotBase);
-    const displayPercent = contextPercent.toFixed(1);
-    const thresholdDisplay = resolveCompactionThresholdPercent(compactionThreshold).toFixed(0);
     const result = await rerootCommandSession(cmdCtx, workspaceRoot);
     if (result.status === "ok") {
-        ctx.ui.notify(`Step complete — context at ${displayPercent}% (threshold: ${thresholdDisplay}%). Fresh session ready for /gsd next.`, "info");
+        ctx.ui.notify(`Step complete — context at ${displayPercent}% (hard threshold: ${HARD_CONTEXT_REROOT_THRESHOLD_PERCENT}%). Fresh session ready for /gsd next.`, "info");
         return { rerooted: true };
     }
     if (result.status === "cancelled") {
@@ -1545,7 +1552,7 @@ export function _selectStopAutoWorktreeExit(args) {
 /**
  * Pause auto-mode without destroying state. Context is preserved.
  * The user can interact with the agent, then `/gsd auto` resumes
- * from disk state. Called when the user presses Escape during auto-mode.
+ * from disk state. Called when the user presses Escape or runs `/gsd pause`.
  */
 export async function pauseAuto(ctx, _pi, _errorContext, options = {}) {
     if (!s.active)
@@ -1564,6 +1571,8 @@ export async function pauseAuto(ctx, _pi, _errorContext, options = {}) {
     ].filter((path) => Boolean(path)));
     s.active = false;
     s.paused = true;
+    if (options.abortActiveTurn && ctx && !ctx.isIdle())
+        ctx.abort();
     clearUnitTimeout();
     stopAutoCommandPolling();
     // Flush queued follow-up messages (#3512).

package/dist/resources/extensions/gsd/bootstrap/core-session-tools.js

@@ -0,0 +1,39 @@
+// Project/App: gsd-pi
+// File Purpose: Canonical core session tool surface shared by auto-mode scoping and loop guards.
+/** Base tools available during auto-mode execution before unit-specific GSD tools are added. */
+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",
+];
+/** Tools excluded from the high per-turn loop-guard cap (strict or orchestration). */
+const NON_REPEATABLE_FROM_MINIMAL_BASE = new Set([
+    "ask_user_questions",
+    "subagent",
+    "ToolSearch",
+]);
+/** Additional core tools not in MINIMAL_AUTO_BASE but routinely multi-called per turn. */
+const EXTRA_INHERENTLY_REPEATABLE = [
+    "gsd_exec",
+    "multi_edit",
+    "todo_write",
+    "notebook_edit",
+    "search_and_read",
+];
+/** Core session tools that may be invoked many times per agent turn. */
+export const INHERENTLY_REPEATABLE_TOOL_NAMES = [
+    ...MINIMAL_AUTO_BASE_TOOL_NAMES.filter((name) => !NON_REPEATABLE_FROM_MINIMAL_BASE.has(name)),
+    ...EXTRA_INHERENTLY_REPEATABLE,
+];
+export const INHERENTLY_REPEATABLE_TOOL_SET = new Set(INHERENTLY_REPEATABLE_TOOL_NAMES);

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -654,8 +654,9 @@ export function registerDbTools(pi) {
         promptSnippet: "Plan a slice via DB write + PLAN render + cache invalidation",
         promptGuidelines: [
             "Use gsd_plan_slice for slice planning instead of writing S##-PLAN.md or task PLAN files directly.",
-            "Keep parameters flat and provide the full slice planning payload, including tasks.",
-            "The tool validates input, requires an existing parent slice, writes slice/task planning data, renders PLAN.md and task plan files from DB, and clears both state and parse caches after success.",
+            "For incremental planning, call gsd_plan_slice with slice metadata only, then call gsd_plan_task once per task.",
+            "When tasks is omitted or empty, the tool writes only slice planning metadata and preserves existing tasks.",
+            "When tasks is non-empty, the tool validates input, requires an existing parent slice, writes slice/task planning data, renders PLAN.md and task plan files from DB, and clears both state and parse caches after success.",
             "Use the canonical name gsd_plan_slice; gsd_slice_plan is only an alias.",
         ],
         parameters: Type.Object({
@@ -663,7 +664,7 @@ export function registerDbTools(pi) {
             milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
             sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
             goal: Type.String({ description: "Slice goal" }),
-            tasks: Type.Array(Type.Object({
+            tasks: Type.Optional(Type.Array(Type.Object({
                 taskId: Type.String({ description: "Task ID (e.g. T01)" }),
                 title: Type.String({ description: "Task title" }),
                 description: Type.String({ description: "Task description / steps block" }),
@@ -673,7 +674,7 @@ export function registerDbTools(pi) {
                 inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
                 expectedOutput: Type.Array(Type.String(), { description: "Array<string> of files this task creates or overwrites; pass [\"path\"] or [], never prose or a single string" }),
                 observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
-            }), { description: "Planned tasks for the slice" }),
+            }), { description: "Optional full task replacement for the slice. Omit for incremental planning, then call gsd_plan_task once per task." })),
             // ── Enrichment metadata (optional — defaults to empty) ────────────
             successCriteria: Type.Optional(Type.String({ description: "Slice success criteria block" })),
             proofLevel: Type.Optional(Type.String({ description: "Slice proof level" })),

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

@@ -14,6 +14,7 @@ import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
 import { logWarning, isGsdExtensionStderrEnabled } from "../workflow-logger.js";
 import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.js";
+import { installManifestFlushOnProcessTeardown } from "../workflow-manifest.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
@@ -177,6 +178,7 @@ export function registerGsdExtension(pi) {
         process.stderr.write(`[gsd] Failed to bootstrap hook-emitter bridge: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
     });
     installEpipeGuard();
+    installManifestFlushOnProcessTeardown();
     // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
     // GSD-owned `before_agent_start` dispatch step (#3338).
     const ecosystemHandlers = [];

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

@@ -14,7 +14,8 @@ import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from
 import { loadFile, saveFile, formatContinue } from "../files.js";
 import { clearAutoCompletionStopInProgress, clearToolInvocationError, getAutoRuntimeSnapshot, getSourceObservationStore, isAutoActive, isAutoCompletionStopInProgress, isAutoPaused, isInteractiveElicitationInFlight, markToolEnd, markToolStart, recordAutoToolSurfaceSnapshot, recordToolInvocationError, } from "../auto-runtime-state.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";
@@ -42,6 +43,7 @@ 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";
 let approvalQuestionAbortInFlight = false;
 async function loadWelcomeScreenModule() {
     const candidates = [];
@@ -138,22 +140,7 @@ export const MINIMAL_GSD_TOOL_NAMES = [
     "capture_thought",
     "gsd_capture_thought",
 ];
-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",
-];
+export { MINIMAL_AUTO_BASE_TOOL_NAMES } from "./core-session-tools.js";
 function withPreservedShimTools(toolNames) {
     return [...new Set([...toolNames, ...ALWAYS_PRESERVED_SHIM_TOOL_NAMES])];
 }
@@ -449,6 +436,16 @@ function deferApprovalGateFromSnapshot(gateId, basePath, snapshot) {
 function contextBasePath(ctx) {
     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) {
+    if (!reason || !getAutoRuntimeSnapshot().active)
+        return reason;
+    return LOOP_GUARD_INTERACTIVE_INSTRUCTIONS.reduce((formatted, instruction) => formatted.replace(instruction, LOOP_GUARD_AUTO_INSTRUCTION), reason);
+}
 function beginSourceObservationStoreForCurrentUnit(ctx) {
     if (!isAutoActive())
         return null;
@@ -717,6 +714,12 @@ export function registerHooks(pi, ecosystemHandlers) {
                     }
                 }
             }
+            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 migration: ${err instanceof Error ? err.message : String(err)}`);
@@ -874,6 +877,17 @@ export function registerHooks(pi, ecosystemHandlers) {
         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 {
@@ -1063,7 +1077,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         // ── Loop guard: block repeated identical tool calls ──
         const loopCheck = checkToolCallLoop(toolName, event.input);
         if (loopCheck.block) {
-            return { block: true, reason: loopCheck.reason };
+            return { block: true, reason: formatLoopGuardBlockReason(loopCheck.reason) };
         }
         const deferredGateGuard = shouldBlockDeferredApprovalTool(toolName, event.input, discussionBasePath);
         if (deferredGateGuard.block) {
@@ -1269,6 +1283,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
         if (!event.isError) {
+            recordToolCallLoopMutation(toolName);
             refreshSourceObservationAfterMutation(toolName, event.input, ctx);
             clearSourceObservationsAfterShell(toolName);
         }

package/dist/resources/extensions/gsd/bootstrap/tool-call-loop-guard.js

@@ -1,24 +1,29 @@
 /**
  * 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";
 const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 /** Interactive/user-facing tools where even 1 duplicate is confusing. */
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
@@ -35,32 +40,16 @@ 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 = "";
 let lastToolName = "";
 let enabled = true;
 /** Per-tool-name call counts within the current turn (#783 Brief C). */
 const perToolCounts = new Map();
+let mutationEpoch = 0;
+const perToolLastMutationEpoch = new Map();
 /** Hash tool name + args into a compact signature for comparison. */
 function hashToolCall(toolName, args) {
     const h = createHash("sha256");
@@ -84,7 +73,8 @@ function hashToolCall(toolName, args) {
  *  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, args) {
     if (!enabled)
@@ -107,16 +97,25 @@ export function checkToolCallLoop(toolName, args) {
             block: true,
             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,
         };
     }
     // ── 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.
+    if (PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName)) {
+        return { block: false, count: consecutiveCount };
+    }
+    const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
         ? PER_TOOL_REPEATABLE_CAP
         : PER_TOOL_DEFAULT_CAP;
     if (perToolCount > perToolCap) {
@@ -124,12 +123,21 @@ export function checkToolCallLoop(toolName, args) {
             block: true,
             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,
         };
     }
     return { block: false, count: consecutiveCount };
 }
+/** Record successful mutation progress so Guard 2 can decay on the next count. */
+export function recordToolCallLoopMutation(toolName) {
+    if (!enabled)
+        return;
+    if (!STATE_MUTATING_TOOL_SET.has(toolName))
+        return;
+    mutationEpoch++;
+}
 /** Reset the guard state. Call at agent turn boundaries. */
 export function resetToolCallLoopGuard() {
     consecutiveCount = 0;
@@ -137,6 +145,8 @@ export function resetToolCallLoopGuard() {
     lastToolName = "";
     enabled = true;
     perToolCounts.clear();
+    mutationEpoch = 0;
+    perToolLastMutationEpoch.clear();
 }
 /** Disable the guard (e.g. during shutdown). */
 export function disableToolCallLoopGuard() {
@@ -145,6 +155,8 @@ export function disableToolCallLoopGuard() {
     lastSignature = "";
     lastToolName = "";
     perToolCounts.clear();
+    mutationEpoch = 0;
+    perToolLastMutationEpoch.clear();
 }
 /** Get current consecutive count for diagnostics. */
 export function getToolCallLoopCount() {

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

@@ -81,8 +81,18 @@ function createEmptyWriteGateState() {
     };
 }
 const writeGateStatesByBasePath = new Map();
+/**
+ * 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) {
+    return resolve(resolveWorktreeProjectRoot(basePath));
+}
 function writeGateStateKey(basePath) {
-    return resolve(basePath);
+    return resolveWriteGateSnapshotRoot(basePath);
 }
 function getWriteGateState(basePath = process.cwd()) {
     const key = writeGateStateKey(basePath);
@@ -123,16 +133,17 @@ function shouldPersistWriteGateSnapshot(env = process.env) {
     return v !== "0" && v !== "false";
 }
 function writeGateSnapshotPath(basePath) {
-    return join(basePath, ".gsd", "runtime", "write-gate-state.json");
+    return join(resolveWriteGateSnapshotRoot(basePath), ".gsd", "runtime", "write-gate-state.json");
 }
 function ensureWriteGateSnapshotDirectory(basePath) {
-    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 {

package/dist/resources/extensions/gsd/closeout-consistency-gate.js

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getLatestAssessmentByScope, getMilestone, getMilestoneSlices, getPendingGates, getSliceTasks, insertAssessment, isDbAvailable, transaction, } from "./gsd-db.js";
 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";
@@ -144,6 +144,8 @@ export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
         });
     }
     for (const slice of slices) {
+        if (isDeferredStatus(slice.status))
+            continue;
         if (!isClosedStatus(slice.status)) {
             return blocked("slice-open", `Closeout consistency blocked for ${milestoneId}: slice ${slice.id} status is "${slice.status}".`);
         }

package/dist/resources/extensions/gsd/commands/handlers/auto.js

@@ -190,7 +190,7 @@ export async function handleAutoCommand(trimmed, ctx, pi) {
             }
             return true;
         }
-        await pauseAuto(ctx, pi);
+        await pauseAuto(ctx, pi, undefined, { abortActiveTurn: true });
         return true;
     }
     if (trimmed === "rate" || trimmed.startsWith("rate ")) {

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -1164,7 +1164,7 @@ async function configureContextCodebase(ctx, prefs) {
         cm.observation_mask_turns = maskTurns;
     else if (maskTurns === "clear")
         delete cm.observation_mask_turns;
-    const thresh = await promptNumber(ctx, "Compaction threshold percent (0.5–0.95)", cm.compaction_threshold_percent, "0.60");
+    const thresh = await promptNumber(ctx, "Soft context warning threshold percent (0.5–0.95)", cm.compaction_threshold_percent, "0.60");
     if (thresh !== undefined && thresh !== "clear")
         cm.compaction_threshold_percent = thresh;
     else if (thresh === "clear")

package/dist/resources/extensions/gsd/commands-usage.js

@@ -83,7 +83,7 @@ function formatThresholdLines() {
     }
     const compactionThreshold = prefs?.context_management?.compaction_threshold_percent;
     if (typeof compactionThreshold === "number") {
-        lines.push(`Compaction: ${Math.round(compactionThreshold * 100)}%`);
+        lines.push(`Soft context warning: ${Math.round(compactionThreshold * 100)}%`);
     }
     return lines;
 }

package/dist/resources/extensions/gsd/db/engine.js

@@ -19,7 +19,7 @@ import { createCoordinationTablesV24 } from "../db-coordination-schema.js";
 import { createDbConnectionCache } from "../db-connection-cache.js";
 import { backupDatabaseBeforeMigration, isMigrationBackupError } from "../db-migration-backup.js";
 import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, applyMigrationV28MemoryLastHitAt, applyMigrationV29RepositoryTargets, } from "../db-migration-steps.js";
-import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "../db-memory-fts-schema.js";
+import { isMemoriesFtsAvailableSchema, rebuildMemoriesFtsSchemaOnce, tryCreateMemoriesFtsSchema, } from "../db-memory-fts-schema.js";
 import { createDbOpenState } from "../db-open-state.js";
 import { createRuntimeKvTableV25 } from "../db-runtime-kv-schema.js";
 import { getCurrentSchemaVersion, recordSchemaVersion } from "../db-schema-metadata.js";
@@ -101,6 +101,9 @@ function initSchema(db, fileBacked, dbPath) {
         throw err;
     }
     migrateSchema(db, dbPath);
+    rebuildMemoriesFtsSchemaOnce(db, {
+        onRebuildFailed: (message) => logWarning("db", message),
+    });
 }
 export function _isLikelyWslDrvFsPathForTest(dbPath) {
     if (!dbPath || process.platform !== "linux")

package/dist/resources/extensions/gsd/db-memory-fts-schema.js

@@ -1,5 +1,7 @@
 // Project/App: gsd-pi
 // File Purpose: Memory FTS5 SQLite schema helpers for the GSD database facade.
+import { createRuntimeKvTableV25 } from "./db-runtime-kv-schema.js";
+export const MEMORIES_FTS_REBUILT_KEY = "memories_fts_rebuilt_at";
 function formatFtsUnavailableError(err) {
     const message = err instanceof Error ? err.message : String(err);
     return message.replace(/\bmoduel\s*:\s*/gi, "module: ");
@@ -54,3 +56,35 @@ export function isMemoriesFtsAvailableSchema(db) {
         return false;
     }
 }
+export function rebuildMemoriesFtsSchemaOnce(db, options = {}) {
+    if (!isMemoriesFtsAvailableSchema(db))
+        return;
+    createRuntimeKvTableV25(db);
+    const marker = db.prepare("SELECT 1 as present FROM runtime_kv WHERE scope = 'global' AND scope_id = '' AND key = :key").get({ ":key": MEMORIES_FTS_REBUILT_KEY });
+    if (marker)
+        return;
+    const now = new Date().toISOString();
+    try {
+        db.exec("BEGIN");
+        db.exec("INSERT INTO memories_fts(memories_fts) VALUES('rebuild')");
+        db.prepare(`INSERT INTO runtime_kv (scope, scope_id, key, value_json, updated_at)
+       VALUES ('global', '', :key, :value_json, :updated_at)
+       ON CONFLICT (scope, scope_id, key) DO UPDATE SET
+         value_json = excluded.value_json,
+         updated_at = excluded.updated_at`).run({
+            ":key": MEMORIES_FTS_REBUILT_KEY,
+            ":value_json": JSON.stringify(now),
+            ":updated_at": now,
+        });
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // Best effort: leave startup alive and retry the rebuild on next open.
+        }
+        options.onRebuildFailed?.(`FTS5 rebuild failed: ${err.message}`);
+    }
+}