@opengsd/gsd-pi 1.5.0 → 1.6.0-dev.aa7f94e8

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

@@ -30,9 +30,10 @@ import { playNotificationBell, sendDesktopNotification } from "./notifications.j
 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";
+import { selectAndApplyModel, resolveModelId, clearToolBaseline, isModelUnavailable, applyThinkingLevelForModel } from "./auto-model-selection.js";
+import { resolveModelWithFallbacksForUnit } from "./preferences-models.js";
 import { resetRoutingHistory, recordOutcome } from "./routing-history.js";
-import { resetHookState, runPreDispatchHooks, restoreHookState, clearPersistedHookState, } from "./post-unit-hooks.js";
+import { resetHookState, runPreDispatchHooks, restoreHookState, reconcileRestoredHookDispatch, clearPersistedHookState, } from "./post-unit-hooks.js";
 import { runGSDDoctor, rebuildState } from "./doctor.js";
 import { preDispatchHealthGate, resetProactiveHealing, setLevelChangeCallback, } from "./doctor-proactive.js";
 import { clearSkillSnapshot } from "./skill-discovery.js";
@@ -51,10 +52,17 @@ import { atomicWriteSync } from "./atomic-write.js";
 import { captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
-import { createAutoWorktree, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
+import { autoWorktreeBranch } from "./auto-worktree-branch-lifecycle.js";
+import { createAutoWorktree } from "./auto-worktree-creation.js";
+import { isInAutoWorktree } from "./auto-worktree-entry.js";
+import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
+import { checkResourcesStale } from "./auto-worktree-resource-version.js";
+import { escapeStaleWorktree } from "./auto-worktree-runtime-cleanup.js";
+import { teardownWarmedBrowserDaemons } from "./browser-daemon-auto-prep.js";
+import { teardownAutoWorktree } from "./auto-worktree-teardown.js";
 import { pruneQueueOrder } from "./queue-order.js";
 import { startCommandPolling as _startCommandPolling, isRemoteConfigured } from "../remote-questions/manager.js";
-import { createMilestoneMergeTransaction } from "./milestone-merge-transaction.js";
+import { createDefaultMilestoneMergeTransaction } from "./milestone-merge-transaction.js";
 import { debugLog, isDebugEnabled, writeDebugSummary } from "./debug-logger.js";
 import { reconcileMergeState, verifyExpectedArtifact, } from "./auto-recovery.js";
 import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
@@ -326,11 +334,24 @@ function withDetachedAutoKeepalive(run) {
 }
 export const _withDetachedAutoKeepaliveForTest = withDetachedAutoKeepalive;
 export function startAutoDetached(ctx, pi, base, verboseMode, options) {
-    void withDetachedAutoKeepalive(startAuto(ctx, pi, base, verboseMode, options)).catch((err) => {
+    void withDetachedAutoKeepalive(startAuto(ctx, pi, base, verboseMode, options)).catch(async (err) => {
         const message = getErrorMessage(err);
         ctx.ui.notify(`Auto-start failed: ${message}`, "error");
         logWarning("engine", `auto start error: ${message}`, { file: "auto.ts" });
         debugLog("auto-start-failed", { error: message });
+        // Backstop cleanup (#1235): if startAuto threw after auto-mode was activated
+        // (e.g. an exception during bootstrap, before the loop's try/finally could
+        // run cleanupAfterLoopExit), s.active and the on-disk auto lock leak, so the
+        // re-entry guard silently no-ops every later /gsd auto until restart. Clear
+        // the leaked activation here so a failed start is always recoverable.
+        if (s.active) {
+            try {
+                await cleanupAfterLoopExit(ctx);
+            }
+            catch (cleanupErr) {
+                logWarning("engine", `auto start cleanup failed: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`, { file: "auto.ts" });
+            }
+        }
     });
 }
 /** Returns true if the project is configured for `isolation:worktree` mode. */
@@ -983,6 +1004,17 @@ export async function cleanupAfterLoopExit(ctx) {
         /* best-effort — mirror stopAuto cleanup */
         logWarning("session", `lock cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
+    // Symmetric teardown for the browser-UAT warm-up preflight (#1259): stop any
+    // gsd-browser daemon this session started so the Chrome process does not
+    // linger after the loop exits. Re-warms on the next browser-backed run-uat.
+    try {
+        for (const { projectRoot, error } of teardownWarmedBrowserDaemons()) {
+            logWarning("session", `gsd-browser daemon stop failed for ${projectRoot}: ${error}`, { file: "auto.ts" });
+        }
+    }
+    catch (err) {
+        logWarning("session", `browser daemon teardown failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+    }
     // A transient provider-error pause intentionally leaves the paused badge
     // visible so the user still has a resumable auto-mode signal on screen.
     if (!s.paused) {
@@ -1746,7 +1778,7 @@ export function buildWorktreeLifecycleDeps() {
             return new GitServiceImpl(basePath, gitConfig);
         },
         worktreeProjection: new WorktreeStateProjection(),
-        mergeMilestone: createMilestoneMergeTransaction(mergeMilestoneToMain),
+        mergeMilestone: createDefaultMilestoneMergeTransaction(),
     };
 }
 function buildLifecycle() {
@@ -2169,6 +2201,10 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         ctx.ui.setWidget("gsd-health", undefined);
         ctx.ui.notify(s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
         restoreHookState(s.basePath);
+        // A restored activeHook has no live dispatch (the sidecar queue is not
+        // persisted); re-enqueue it so the hook runs instead of blocking the next
+        // unrelated unit's close-out (#1246).
+        reconcileRestoredHookDispatch(s.basePath, s.sidecarQueue);
         // Re-sync managed resources on resume so long-lived auto sessions pick up
         // bundled extension updates before resume-time verification/state logic runs.
         // GSD_PKG_ROOT is set by loader.ts and points to the gsd-pi package root.
@@ -2222,15 +2258,19 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             debugLog("resume-orchestration-resume", { error: err instanceof Error ? err.message : String(err) });
         }
         startAutoCommandPolling(s.basePath);
-        await runAutoLoopWithUok({
-            ctx,
-            pi,
-            s,
-            deps: loopDeps,
-            runKernelLoop: runUokKernelLoop,
-            runLegacyLoop: runLegacyAutoLoop,
-        });
-        await cleanupAfterLoopExit(ctx);
+        try {
+            await runAutoLoopWithUok({
+                ctx,
+                pi,
+                s,
+                deps: loopDeps,
+                runKernelLoop: runUokKernelLoop,
+                runLegacyLoop: runLegacyAutoLoop,
+            });
+        }
+        finally {
+            await cleanupAfterLoopExit(ctx);
+        }
         return;
     }
     // ── Fresh start path — delegated to auto-start.ts ──
@@ -2246,8 +2286,16 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     // for crash-recovery fidelity (#5405).
     registerAutoWorkerForSession(s, base);
     const ready = await bootstrapAutoSession(s, ctx, pi, base, verboseMode, requestedStepMode, bootstrapDeps, freshStartAssessment);
-    if (!ready)
+    if (!ready) {
+        // bootstrapAutoSession sets s.active = true (auto-start.ts) before several
+        // post-activation bail-outs return false without a loop ever running (e.g.
+        // the SQLite-unavailable gate). Without this, s.active and the auto lock
+        // leak and every later /gsd auto silently no-ops via the re-entry guard
+        // (#1235). Run the canonical cleanup so a failed bootstrap stays recoverable.
+        if (s.active)
+            await cleanupAfterLoopExit(ctx);
         return;
+    }
     // Build scope after bootstrap has populated s.basePath / s.originalBasePath /
     // s.currentMilestoneId (including worktree setup inside bootstrapAutoSession).
     rebuildScope(s.basePath, s.currentMilestoneId);
@@ -2271,15 +2319,19 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     }
     startAutoCommandPolling(s.basePath);
     // Dispatch the first unit
-    await runAutoLoopWithUok({
-        ctx,
-        pi,
-        s,
-        deps: loopDeps,
-        runKernelLoop: runUokKernelLoop,
-        runLegacyLoop: runLegacyAutoLoop,
-    });
-    await cleanupAfterLoopExit(ctx);
+    try {
+        await runAutoLoopWithUok({
+            ctx,
+            pi,
+            s,
+            deps: loopDeps,
+            runKernelLoop: runUokKernelLoop,
+            runLegacyLoop: runLegacyAutoLoop,
+        });
+    }
+    finally {
+        await cleanupAfterLoopExit(ctx);
+    }
 }
 // describeNextUnit is imported from auto-dashboard.ts and re-exported
 export { describeNextUnit } from "./auto-dashboard.js";
@@ -2396,20 +2448,52 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         startedAt: hookStartedAt,
         workspaceRoot: s.basePath,
     });
-    if (hookModel) {
-        const availableModels = ctx.modelRegistry.getAvailable();
-        const match = resolveModelId(hookModel, availableModels, ctx.model?.provider);
-        if (match) {
+    // Resolve the hook's model honoring the configured `fallbacks[]` chain
+    // (#1229). The manual trigger path bypasses selectAndApplyModel, so resolve
+    // the primary→fallbacks order here and apply the first candidate available in
+    // the registry — a blocked or unconfigured primary then transparently drops
+    // to a fallback instead of silently reverting to the session model.
+    const availableModels = ctx.modelRegistry.getAvailable();
+    const availableModelIds = availableModels.map((m) => `${m.provider}/${m.id}`);
+    const hookModelConfig = resolveModelWithFallbacksForUnit(hookUnitType, targetBasePath, availableModelIds);
+    const modelCandidates = hookModelConfig
+        ? [hookModelConfig.primary, ...hookModelConfig.fallbacks]
+        : hookModel
+            ? [hookModel]
+            : [];
+    if (modelCandidates.length > 0) {
+        let applied = false;
+        for (const candidate of modelCandidates) {
+            const match = resolveModelId(candidate, availableModels, ctx.model?.provider);
+            if (!match)
+                continue;
+            // Skip models the runtime has marked blocked or temporarily unavailable
+            // (e.g. a primary that just tripped a provider limit) so the configured
+            // fallbacks[] chain actually engages — parity with auto-mode's
+            // selectAndApplyModel, which consults the same blocked-models store (#1229).
+            if (isModelUnavailable(targetBasePath, match.provider, match.id))
+                continue;
             try {
-                await pi.setModel(match);
+                if (await pi.setModel(match)) {
+                    // The manual trigger path bypasses selectAndApplyModel, so apply the
+                    // hook's per-field `thinking` (from `post_unit_hooks[].model`'s object
+                    // form) here against the just-set model rather than leaving the hook at
+                    // the session level (#1269). Absent → session level, unchanged.
+                    if (hookModelConfig?.thinking) {
+                        applyThinkingLevelForModel(pi, hookModelConfig.thinking, match, ctx);
+                    }
+                    applied = true;
+                    break;
+                }
             }
             catch (err) {
-                /* non-fatal */
-                logWarning("dispatch", `hook model set failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+                /* non-fatal — try the next fallback */
+                logWarning("dispatch", `hook model set failed for ${candidate}: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
             }
         }
-        else {
-            ctx.ui.notify(`Hook model "${hookModel}" not found in available models. Falling back to current session model. ` +
+        if (!applied) {
+            ctx.ui.notify(`Hook model${modelCandidates.length > 1 ? "s" : ""} "${modelCandidates.join(", ")}" not available. ` +
+                `Falling back to current session model. ` +
                 `Ensure the model is defined in models.json and has auth configured.`, "warning");
         }
     }

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

@@ -6,7 +6,7 @@ import { join } from "node:path";
 import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@gsd/pi-coding-agent";
 import { logWarning } from "../workflow-logger.js";
 import { getWorkflowDatabaseStatus, openWorkflowDatabase, } from "../db-workspace.js";
-import { getAutoWorktreePath } from "../auto-worktree.js";
+import { getAutoWorktreePath } from "../auto-worktree-path-resolution.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { worktreesDirs } from "../worktree-placement.js";
 export function safeWorkspaceCwd() {

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

@@ -15,7 +15,7 @@ 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 { isDeterministicPolicyError, isQueuedUserMessageSkip, isToolInvocationError, isToolUnavailableError, } from "../auto-tool-tracking.js";
 import { applyProviderPayloadPolicy } from "../provider-payload-policy.js";
-import { checkToolCallLoop, recordToolCallLoopMutation, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
+import { checkToolCallLoop, configureToolCallLoopGuard, 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";
@@ -432,6 +432,22 @@ async function applyCompactionThresholdOverride(ctx) {
         ctx.setCompactionThresholdOverride?.(0.6);
     }
 }
+/**
+ * Apply user-tunable tool-call loop guard thresholds (#1198) from GSD
+ * preferences plus GSD_TOOL_LOOP_* env overrides. Runs at session boundaries
+ * so both interactive sessions and `/gsd auto` pick up the configuration.
+ * Non-fatal: falls back to built-in defaults when preferences cannot be loaded.
+ */
+async function applyToolCallLoopGuardConfig(basePath) {
+    try {
+        const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+        const prefs = loadEffectiveGSDPreferences(basePath);
+        configureToolCallLoopGuard(prefs?.preferences.tool_call_loop_guard);
+    }
+    catch {
+        configureToolCallLoopGuard(null);
+    }
+}
 function clearDeferredApprovalGate(basePath) {
     if (!basePath) {
         deferredApprovalGates.clear();
@@ -779,6 +795,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         resetWriteGateState(basePath);
         resetToolCallLoopGuard();
+        await applyToolCallLoopGuardConfig(basePath);
         approvalQuestionAbortInFlight = false;
         clearDeferredApprovalGate();
         await resetAskUserQuestionsTurnCache();
@@ -864,6 +881,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         initSessionNotifications(ctx);
         resetWriteGateState(basePath);
         resetToolCallLoopGuard();
+        await applyToolCallLoopGuardConfig(basePath);
         clearDeferredApprovalGate();
         await resetAskUserQuestionsTurnCache();
         clearDiscussionFlowState(basePath);
@@ -1389,7 +1407,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
         if (!event.isError) {
-            recordToolCallLoopMutation(toolName);
+            recordToolCallLoopMutation(toolName, event.details);
             refreshSourceObservationAfterMutation(toolName, event.input, ctx);
             clearSourceObservationsAfterShell(toolName);
         }

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

@@ -11,7 +11,7 @@ import { resolveModelWithFallbacksForUnit } from "../preferences-models.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
 import { extractIntroAndRules } from "../knowledge-parser.js";
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
-import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
+import { getActiveAutoWorktreeContext } from "../auto-worktree-session-registry.js";
 import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-session-state.js";
 import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";

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

@@ -14,36 +14,173 @@
  * to stop tooling for the rest of that turn and answer in text.
  *
  * The per-tool-name check (#783 Brief C) tracks call counts within a
- * turn regardless of args, decaying after successful state-mutating tools.
+ * turn regardless of args, decaying after successful state-progressing 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, while allowing
- * tool-heavy turns that are making file-mutation progress. Whichever guard
- * trips first blocks.
+ * tool-heavy turns that are making progress. Progress means a successful file
+ * mutation (edit/write) or a successful shell/exec call (bg_shell,
+ * gsd_uat_exec, …) — so a local model running a legitimate iterative
+ * debugging loop (restart server, npm install, curl an endpoint) is not
+ * blocked as a false loop (#1206). Whichever guard trips first blocks.
+ *
+ * Thresholds, exempt tools, and enable flags are user-tunable (#1198) via the
+ * `tool_call_loop_guard` key in `.gsd/PREFERENCES.md` and `GSD_TOOL_LOOP_*`
+ * environment variables, applied through {@link configureToolCallLoopGuard}.
+ * Defaults preserve the original hardcoded behavior.
  */
 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;
+/** Built-in defaults. Preserved when preferences/env do not override them. */
+const DEFAULT_MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
+const DEFAULT_PER_TOOL_DEFAULT_CAP = 6;
+const DEFAULT_PER_TOOL_REPEATABLE_CAP = 15;
+const DEFAULT_PER_TOOL_CAP_EXEMPT_TOOLS = ["find", "glob", "grep", "ls", "read", "search_and_read"];
 /** Interactive/user-facing tools where even 1 duplicate is confusing. */
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
 const MAX_CONSECUTIVE_STRICT = 1;
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
 /**
- * Per-turn cap on calls to the SAME tool name, regardless of args (#783).
+ * Successful shell/exec calls are state progression too (#1206), not just file
+ * mutations. A local model debugging a UAT scenario legitimately restarts
+ * servers, runs `npm install`, and curls endpoints via bg_shell / gsd_uat_exec
+ * with varied args — productive work that never touches a file, so Guard 2's
+ * per-tool cap would otherwise misfire as a false loop. Decaying on these
+ * successful calls keeps the guard from aborting a progressing turn.
  *
- * General-purpose execution tools are routinely called many times per turn
- * (touching multiple files, running several commands), so they get a higher
- * ceiling. Everything else — workflow one-shot tools (e.g. gsd_complete_milestone)
- * and any non-allowlisted tool — gets the default cap. The default is generous
- * enough to absorb legitimate retries but catches the reported improvisation
- * loop (~51 calls) well before a cost spike.
+ * Only successful calls reach {@link recordToolCallLoopMutation}: the
+ * tool_result hook skips `isError` results, and the bash tool throws on
+ * non-zero exit, so a genuinely stuck improvisation loop of failing commands
+ * (#783) never decays and still trips the cap. `async_bash` is excluded
+ * because it only registers a background job; command success is reported
+ * later via `await_job`. `bg_shell` may return `isError: false` for failed
+ * `run`/`start` outcomes, so the hook passes `details` for validation.
  */
-const PER_TOOL_DEFAULT_CAP = 6;
-const PER_TOOL_REPEATABLE_CAP = 15;
-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"]);
+const STATE_PROGRESSING_EXEC_TOOL_SET = new Set([
+    "bash",
+    "bg_shell",
+    "shell",
+    "powershell",
+    "gsd_exec",
+    "gsd_uat_exec",
+]);
+function isSuccessfulBgShellLoopProgress(details) {
+    if (!details || typeof details !== "object")
+        return false;
+    const record = details;
+    switch (record.action) {
+        case "run":
+            return record.exitCode === 0 && record.timedOut !== true;
+        case "start":
+        case "restart": {
+            const process = record.process;
+            if (!process || typeof process !== "object")
+                return false;
+            return process.alive === true;
+        }
+        case "wait_for_ready":
+            return record.ready === true;
+        case "send_and_wait":
+            return record.matched === true;
+        default:
+            return true;
+    }
+}
+function defaultGuardConfig() {
+    return {
+        guardEnabled: true,
+        identicalEnabled: true,
+        maxConsecutiveIdentical: DEFAULT_MAX_CONSECUTIVE_IDENTICAL_CALLS,
+        repeatedEnabled: true,
+        perToolDefaultCap: DEFAULT_PER_TOOL_DEFAULT_CAP,
+        perToolRepeatableCap: DEFAULT_PER_TOOL_REPEATABLE_CAP,
+        perToolExempt: new Set(DEFAULT_PER_TOOL_CAP_EXEMPT_TOOLS),
+    };
+}
+let config = defaultGuardConfig();
+/** Parse a positive-integer env var, returning undefined when unset/invalid. */
+function envPositiveInt(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : undefined;
+}
+/** Parse a boolean env var (`true`/`1` vs `false`/`0`), undefined when unset. */
+function envBool(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    const v = raw.trim().toLowerCase();
+    if (v === "true" || v === "1" || v === "yes" || v === "on")
+        return true;
+    if (v === "false" || v === "0" || v === "no" || v === "off")
+        return false;
+    return undefined;
+}
+/** Parse a comma-separated tool-name list env var. */
+function envToolList(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return [];
+    return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+/**
+ * Resolve preferences + environment overrides into the active configuration.
+ * Environment variables win over preferences; preferences win over built-in
+ * defaults. User-supplied exempt tools are additive to the built-in exempt
+ * set so defaults are always preserved.
+ *
+ * Applied to both interactive sessions and `/gsd auto` (called from the
+ * session_start / session_switch hooks).
+ */
+export function configureToolCallLoopGuard(prefs) {
+    const next = defaultGuardConfig();
+    if (prefs) {
+        if (typeof prefs.enabled === "boolean")
+            next.guardEnabled = prefs.enabled;
+        if (prefs.identical_args) {
+            if (typeof prefs.identical_args.enabled === "boolean")
+                next.identicalEnabled = prefs.identical_args.enabled;
+            if (typeof prefs.identical_args.max_consecutive_calls === "number" && prefs.identical_args.max_consecutive_calls >= 1) {
+                next.maxConsecutiveIdentical = Math.floor(prefs.identical_args.max_consecutive_calls);
+            }
+        }
+        if (prefs.repeated_tool) {
+            if (typeof prefs.repeated_tool.enabled === "boolean")
+                next.repeatedEnabled = prefs.repeated_tool.enabled;
+            if (typeof prefs.repeated_tool.default_cap === "number" && prefs.repeated_tool.default_cap >= 1) {
+                next.perToolDefaultCap = Math.floor(prefs.repeated_tool.default_cap);
+            }
+            if (typeof prefs.repeated_tool.repeatable_cap === "number" && prefs.repeated_tool.repeatable_cap >= 1) {
+                next.perToolRepeatableCap = Math.floor(prefs.repeated_tool.repeatable_cap);
+            }
+            for (const tool of prefs.repeated_tool.exempt_tools ?? []) {
+                if (typeof tool === "string" && tool.trim())
+                    next.perToolExempt.add(tool.trim());
+            }
+        }
+    }
+    // Environment overrides (win over preferences).
+    const envEnabled = envBool("GSD_TOOL_LOOP_GUARD_ENABLED");
+    if (envEnabled !== undefined)
+        next.guardEnabled = envEnabled;
+    const envIdenticalMax = envPositiveInt("GSD_TOOL_LOOP_IDENTICAL_MAX");
+    if (envIdenticalMax !== undefined)
+        next.maxConsecutiveIdentical = envIdenticalMax;
+    const envDefaultCap = envPositiveInt("GSD_TOOL_LOOP_REPEATED_DEFAULT_CAP");
+    if (envDefaultCap !== undefined)
+        next.perToolDefaultCap = envDefaultCap;
+    const envRepeatableCap = envPositiveInt("GSD_TOOL_LOOP_REPEATED_REPEATABLE_CAP");
+    if (envRepeatableCap !== undefined)
+        next.perToolRepeatableCap = envRepeatableCap;
+    for (const tool of envToolList("GSD_TOOL_LOOP_EXEMPT_TOOLS"))
+        next.perToolExempt.add(tool);
+    config = next;
+}
 let consecutiveCount = 0;
 let lastSignature = "";
 let lastToolName = "";
@@ -72,14 +209,17 @@ function hashToolCall(toolName, args) {
  * Returns `{ block: true, reason }` when the loop threshold is exceeded.
  *
  * Two independent guards run; whichever trips first blocks:
- *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
+ *  1. Identical-signature streak (config.maxConsecutiveIdentical, strict for
  *     ask_user_questions).
- *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
+ *  2. Per-tool-name cap (config.perToolDefaultCap / config.perToolRepeatableCap),
  *     independent of args, reset after file-mutation progress — catches
  *     improvisation loops (#783).
+ *
+ * Both guards, their thresholds, and the per-tool exempt set are user-tunable
+ * via {@link configureToolCallLoopGuard} (#1198).
  */
 export function checkToolCallLoop(toolName, args) {
-    if (!enabled)
+    if (!enabled || !config.guardEnabled)
         return { block: false, count: 0 };
     const sig = hashToolCall(toolName, args);
     if (sig === lastSignature) {
@@ -93,12 +233,14 @@ export function checkToolCallLoop(toolName, args) {
     // ── Guard 1: identical-signature streak ──
     const threshold = STRICT_LOOP_TOOLS.has(toolName)
         ? MAX_CONSECUTIVE_STRICT
-        : MAX_CONSECUTIVE_IDENTICAL_CALLS;
-    if (consecutiveCount > threshold) {
+        : config.maxConsecutiveIdentical;
+    if (config.identicalEnabled && consecutiveCount > threshold) {
         return {
             block: true,
             reason: `Tool loop detected (identical args): ${toolName} called ${consecutiveCount} times ` +
-                `with identical arguments. Blocking to prevent infinite loop. ` +
+                `with identical arguments (max ${threshold}). Blocking to prevent infinite loop. ` +
+                `Raise tool_call_loop_guard.identical_args.max_consecutive_calls in .gsd/PREFERENCES.md ` +
+                `(or GSD_TOOL_LOOP_IDENTICAL_MAX) if this is expected. ` +
                 `Do not retry this tool or call other tools this turn — stop and respond to the user in text.`,
             count: consecutiveCount,
         };
@@ -119,30 +261,46 @@ export function checkToolCallLoop(toolName, args) {
     // 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) ||
+    if (!config.repeatedEnabled ||
+        config.perToolExempt.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;
+        ? config.perToolRepeatableCap
+        : config.perToolDefaultCap;
     if (perToolCount > perToolCap) {
         return {
             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. ` +
+                `Raise tool_call_loop_guard.repeated_tool.default_cap/repeatable_cap or add "${toolName}" ` +
+                `to tool_call_loop_guard.repeated_tool.exempt_tools in .gsd/PREFERENCES.md ` +
+                `(or GSD_TOOL_LOOP_REPEATED_* / GSD_TOOL_LOOP_EXEMPT_TOOLS) if this is expected. ` +
                 `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) {
+/**
+ * Record successful state progress so Guard 2 can decay on the next count.
+ * File mutations (edit/write/…) and successful shell/exec calls (bash,
+ * bg_shell, gsd_uat_exec, …) both count as progress (#1092, #1206). The caller
+ * only invokes this for non-error results, so failing improvisation loops
+ * (#783) never decay and still trip the per-tool cap.
+ */
+export function recordToolCallLoopMutation(toolName, details) {
     if (!enabled)
         return;
-    if (!STATE_MUTATING_TOOL_SET.has(toolName))
+    if (STATE_MUTATING_TOOL_SET.has(toolName)) {
+        mutationEpoch++;
+        return;
+    }
+    if (!STATE_PROGRESSING_EXEC_TOOL_SET.has(toolName))
+        return;
+    if (toolName === "bg_shell" && details !== undefined && !isSuccessfulBgShellLoopProgress(details))
         return;
     mutationEpoch++;
 }