@opengsd/gsd-pi 1.5.0 → 1.6.0

package/src/resources/extensions/gsd/tests/supervisor-model-swap-inflight-guard.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Supervisor model swap honors the in-flight-tool guard (#1229 follow-up).
+ *
+ * The wrap-up soft-timeout timer gates `triggerTurn` on there being no tools
+ * in flight — sending a turn mid-tool-call skips tool results and trips
+ * provider errors (#3512). The supervisor model swap
+ * (`applySupervisorModelIfConfigured`) must honor the identical guard: swapping
+ * the session model while tool calls are still open risks the same provider
+ * errors, so it must only run when the timer will actually trigger a turn.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mock } from "node:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { startUnitSupervision, type SupervisionContext } from "../auto-timers.ts";
+import { clearGSDPreferencesCache } from "../preferences.ts";
+import {
+  markToolStart,
+  markToolEnd,
+  clearInFlightTools,
+} from "../auto-tool-tracking.ts";
+
+const SUPERVISOR_PREFS = [
+  "auto_supervisor:",
+  "  soft_timeout_minutes: 1",
+  "  idle_timeout_minutes: 100",
+  "  hard_timeout_minutes: 100",
+  "  model:",
+  "    model: supervisor-primary",
+  "    fallbacks: [supervisor-fb]",
+];
+
+interface Harness {
+  home: string;
+  base: string;
+  ctx: any;
+  pi: any;
+  s: any;
+  sctx: SupervisionContext;
+  setModelCalls: unknown[][];
+  sendMessageCalls: unknown[][];
+}
+
+function makeHarness(): Harness {
+  const home = mkdtempSync(join(tmpdir(), "gsd-supervisor-guard-home-"));
+  const base = mkdtempSync(join(tmpdir(), "gsd-supervisor-guard-base-"));
+  process.env.GSD_HOME = home;
+  writeFileSync(join(home, "preferences.md"), ["---", ...SUPERVISOR_PREFS, "---", ""].join("\n"));
+  clearGSDPreferencesCache();
+
+  const setModelCalls: unknown[][] = [];
+  const sendMessageCalls: unknown[][] = [];
+
+  const ctx = {
+    ui: { notify: () => {} },
+    model: { provider: "anthropic" },
+    modelRegistry: {
+      getAvailable: () => [
+        { id: "supervisor-primary", provider: "anthropic" },
+        { id: "supervisor-fb", provider: "anthropic" },
+      ],
+    },
+  } as any;
+
+  const pi = {
+    sendMessage: (...args: unknown[]) => {
+      sendMessageCalls.push(args);
+    },
+    setModel: async (...args: unknown[]) => {
+      setModelCalls.push(args);
+      return true;
+    },
+    getThinkingLevel: () => "off",
+    setThinkingLevel: () => {},
+  } as any;
+
+  const s = {
+    active: true,
+    verbose: false,
+    basePath: base,
+    currentUnit: { type: "task", id: "T01", startedAt: 1234 },
+    cmdCtx: undefined,
+    wrapupWarningHandle: null,
+    idleWatchdogHandle: null,
+    unitTimeoutHandle: null,
+    continueHereHandle: null,
+  } as any;
+
+  const sctx: SupervisionContext = {
+    s,
+    ctx,
+    pi,
+    unitType: "task",
+    unitId: "T01",
+    prefs: undefined,
+    buildSnapshotOpts: () => ({}) as any,
+    buildRecoveryContext: () => ({}) as any,
+    pauseAuto: async () => {},
+  };
+
+  return { home, base, ctx, pi, s, sctx, setModelCalls, sendMessageCalls };
+}
+
+function cleanup(h: Harness): void {
+  clearInFlightTools();
+  clearGSDPreferencesCache();
+  delete process.env.GSD_HOME;
+  rmSync(h.home, { recursive: true, force: true });
+  rmSync(h.base, { recursive: true, force: true });
+}
+
+/** Neutralize every timer except the soft-timeout wrap-up so only it fires. */
+function isolateSoftTimeout(s: any): void {
+  if (s.idleWatchdogHandle) clearInterval(s.idleWatchdogHandle);
+  if (s.unitTimeoutHandle) clearTimeout(s.unitTimeoutHandle);
+  if (s.continueHereHandle) clearInterval(s.continueHereHandle);
+}
+
+/** Flush the soft-timeout callback's chained awaits. */
+async function flush(): Promise<void> {
+  for (let i = 0; i < 10; i++) await Promise.resolve();
+}
+
+test("soft-timeout skips the supervisor model swap while a tool is in flight", async () => {
+  const h = makeHarness();
+  mock.timers.enable({ apis: ["setTimeout", "setInterval", "Date"], now: 0 });
+  try {
+    startUnitSupervision(h.sctx);
+    isolateSoftTimeout(h.s);
+
+    // A tool is still executing when the soft timeout fires.
+    markToolStart("call-1", true, "some_tool");
+
+    mock.timers.tick(60_000);
+    await flush();
+
+    assert.equal(
+      h.setModelCalls.length,
+      0,
+      "model must NOT swap while a tool is in flight",
+    );
+    assert.equal(h.sendMessageCalls.length, 1, "wrap-up message still sent (queued)");
+    const opts = h.sendMessageCalls[0][1] as { triggerTurn?: boolean };
+    assert.equal(opts.triggerTurn, false, "turn is not triggered mid-tool-call");
+
+    markToolEnd("call-1");
+  } finally {
+    mock.timers.reset();
+    cleanup(h);
+  }
+});
+
+test("soft-timeout applies the supervisor model swap when no tools are in flight", async () => {
+  const h = makeHarness();
+  mock.timers.enable({ apis: ["setTimeout", "setInterval", "Date"], now: 0 });
+  try {
+    startUnitSupervision(h.sctx);
+    isolateSoftTimeout(h.s);
+
+    // No tools in flight — the timer will trigger a turn, so the model swaps.
+    mock.timers.tick(60_000);
+    await flush();
+
+    assert.equal(h.setModelCalls.length, 1, "model swaps to the supervisor model");
+    assert.deepEqual(
+      h.setModelCalls[0][0],
+      { id: "supervisor-primary", provider: "anthropic" },
+      "swaps to the configured supervisor primary",
+    );
+    assert.equal(h.sendMessageCalls.length, 1);
+    const opts = h.sendMessageCalls[0][1] as { triggerTurn?: boolean };
+    assert.equal(opts.triggerTurn, true, "turn is triggered when no tools are open");
+  } finally {
+    mock.timers.reset();
+    cleanup(h);
+  }
+});

package/src/resources/extensions/gsd/tests/supervisor-model-swap-thinking-clamp.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Supervisor model swap reclamps the reasoning level (#1229 follow-up).
+ *
+ * Hook overrides in `unit-phase.ts` reapply `applyThinkingLevelForModel` after a
+ * model swap so the session's reasoning effort is re-clamped to what the newly
+ * selected model supports (ADR-026). `applySupervisorModelIfConfigured` swaps
+ * the session model for supervisor interventions (wrap-up, context-budget,
+ * timeout recovery) and must do the same — otherwise a level that was valid for
+ * the prior model can reach the provider on the steered turn.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { applySupervisorModelIfConfigured } from "../auto-model-selection.ts";
+import { clearGSDPreferencesCache } from "../preferences.ts";
+
+const SUPERVISOR_PREFS = [
+  "auto_supervisor:",
+  "  model:",
+  "    model: supervisor-primary",
+  "    fallbacks: [supervisor-fb]",
+];
+
+interface Harness {
+  home: string;
+  base: string;
+  ctx: any;
+  pi: any;
+  setModelCalls: unknown[][];
+  setThinkingCalls: unknown[];
+  order: string[];
+}
+
+function makeHarness(): Harness {
+  const home = mkdtempSync(join(tmpdir(), "gsd-supervisor-clamp-home-"));
+  const base = mkdtempSync(join(tmpdir(), "gsd-supervisor-clamp-base-"));
+  process.env.GSD_HOME = home;
+  writeFileSync(join(home, "preferences.md"), ["---", ...SUPERVISOR_PREFS, "---", ""].join("\n"));
+  clearGSDPreferencesCache();
+
+  const setModelCalls: unknown[][] = [];
+  const setThinkingCalls: unknown[] = [];
+  const order: string[] = [];
+
+  const ctx = {
+    ui: { notify: () => {} },
+    model: { provider: "anthropic" },
+    modelRegistry: {
+      getAvailable: () => [
+        { id: "supervisor-primary", provider: "anthropic" },
+        { id: "supervisor-fb", provider: "anthropic" },
+      ],
+    },
+  } as any;
+
+  const pi = {
+    setModel: async (...args: unknown[]) => {
+      setModelCalls.push(args);
+      order.push("setModel");
+      return true;
+    },
+    getThinkingLevel: () => "high",
+    setThinkingLevel: (level: unknown) => {
+      setThinkingCalls.push(level);
+      order.push("setThinkingLevel");
+    },
+  } as any;
+
+  return { home, base, ctx, pi, setModelCalls, setThinkingCalls, order };
+}
+
+function cleanup(h: Harness): void {
+  clearGSDPreferencesCache();
+  delete process.env.GSD_HOME;
+  rmSync(h.home, { recursive: true, force: true });
+  rmSync(h.base, { recursive: true, force: true });
+}
+
+test("supervisor swap reapplies the thinking level after selecting the model", async () => {
+  const h = makeHarness();
+  try {
+    await applySupervisorModelIfConfigured(h.ctx, h.pi, h.base);
+
+    assert.equal(h.setModelCalls.length, 1, "model swaps to the supervisor model");
+    assert.deepEqual(
+      h.setModelCalls[0][0],
+      { id: "supervisor-primary", provider: "anthropic" },
+      "swaps to the configured supervisor primary",
+    );
+    assert.equal(
+      h.setThinkingCalls.length,
+      1,
+      "thinking level is reclamped exactly once after the swap",
+    );
+    assert.deepEqual(
+      h.order,
+      ["setModel", "setThinkingLevel"],
+      "reclamp happens after setModel, matching the hook-override pattern",
+    );
+  } finally {
+    cleanup(h);
+  }
+});
+
+test("supervisor swap does not touch the thinking level when no model is configured", async () => {
+  const h = makeHarness();
+  // Overwrite prefs with no auto_supervisor.model.
+  writeFileSync(join(h.home, "preferences.md"), ["---", "auto_supervisor:", "  soft_timeout_minutes: 1", "---", ""].join("\n"));
+  clearGSDPreferencesCache();
+  try {
+    await applySupervisorModelIfConfigured(h.ctx, h.pi, h.base);
+
+    assert.equal(h.setModelCalls.length, 0, "no swap without a configured supervisor model");
+    assert.equal(h.setThinkingCalls.length, 0, "thinking level untouched when nothing swaps");
+  } finally {
+    cleanup(h);
+  }
+});

package/src/resources/extensions/gsd/tests/sync-worktree-skip-current.test.ts

@@ -8,7 +8,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { syncWorktreeStateBack } from "../auto-worktree.ts";
+import { syncWorktreeStateBack } from "../auto-worktree-sync.ts";
 
 describe("syncWorktreeStateBack does not copy worktree milestone projections", () => {
   it("copies root diagnostics but leaves milestone markdown directories behind", () => {

package/src/resources/extensions/gsd/tests/system-flat-phase-layout.test.ts

@@ -0,0 +1,33 @@
+// gsd-pi — Regression tests: system.md documents the flat-phase layout, not legacy milestone/slice/task paths
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const promptsDir = join(process.cwd(), "src/resources/extensions/gsd/prompts");
+
+function readPrompt(name: string): string {
+  return readFileSync(join(promptsDir, `${name}.md`), "utf-8");
+}
+
+test("system.md does not advertise legacy milestone/slice/task artifact paths", () => {
+  const prompt = readPrompt("system");
+  for (const legacy of [".gsd/milestones", "milestones/M001", "slices/S01", "tasks/T01-PLAN.md"]) {
+    assert.ok(
+      !prompt.includes(legacy),
+      `system.md must not reference the legacy path fragment "${legacy}" after flat-phase migration`,
+    );
+  }
+});
+
+test("system.md documents the flat-phase directory structure", () => {
+  const prompt = readPrompt("system");
+  assert.match(prompt, /phases\/\{MM\}-\{slug\}/, "system.md must document phases/{MM}-{slug}/ directories");
+  assert.match(prompt, /\{MM\}-\{SS\}-PLAN\.md/, "system.md must document {MM}-{SS}-PLAN.md slice plans");
+  assert.match(
+    prompt,
+    /do not expect `tasks\/T##-PLAN\.md`/,
+    "system.md must state task plan content lives inside the slice plan, not tasks/T##-PLAN.md",
+  );
+});

package/src/resources/extensions/gsd/tests/teardown-chdir-failure-clears-registry.test.ts

@@ -36,13 +36,13 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 
+import { createAutoWorktree } from "../auto-worktree-creation.ts";
 import {
-  createAutoWorktree,
-  teardownAutoWorktree,
-  getAutoWorktreeOriginalBase,
   getActiveAutoWorktreeContext,
+  getAutoWorktreeOriginalBase,
   _resetAutoWorktreeOriginalBaseForTests,
-} from "../auto-worktree.ts";
+} from "../auto-worktree-session-registry.ts";
+import { teardownAutoWorktree } from "../auto-worktree-teardown.ts";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 

package/src/resources/extensions/gsd/tests/teardown-cleanup-parity.test.ts

@@ -22,7 +22,8 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 
-import { teardownAutoWorktree, _resetAutoWorktreeOriginalBaseForTests } from "../auto-worktree.ts";
+import { _resetAutoWorktreeOriginalBaseForTests } from "../auto-worktree-session-registry.ts";
+import { teardownAutoWorktree } from "../auto-worktree-teardown.ts";
 
 function git(args: string[], cwd: string): void {
   execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] });

package/src/resources/extensions/gsd/tests/teardown-failure-clears-registry.test.ts

@@ -38,13 +38,13 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 
+import { createAutoWorktree } from "../auto-worktree-creation.ts";
 import {
-  createAutoWorktree,
-  teardownAutoWorktree,
-  getAutoWorktreeOriginalBase,
   getActiveAutoWorktreeContext,
+  getAutoWorktreeOriginalBase,
   _resetAutoWorktreeOriginalBaseForTests,
-} from "../auto-worktree.ts";
+} from "../auto-worktree-session-registry.ts";
+import { teardownAutoWorktree } from "../auto-worktree-teardown.ts";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 

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

@@ -7,6 +7,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   checkToolCallLoop,
+  configureToolCallLoopGuard,
   recordToolCallLoopMutation,
   resetToolCallLoopGuard,
   disableToolCallLoopGuard,
@@ -251,6 +252,99 @@ console.log('\n── Loop guard: mutation progress decays per-tool counts (#109
   }
 }
 
+// ═══════════════════════════════════════════════════════════════════════════
+// Successful shell/exec progress decays per-tool counts (#1206)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: successful shell/exec progress decays per-tool counts (#1206) ──');
+
+{
+  // A local model debugging a UAT scenario runs many varied bg_shell /
+  // gsd_uat_exec calls (restart server, npm install, curl an endpoint). Each
+  // successful call is state progression, so Guard 2 must decay and never
+  // block the productive turn — even past the repeatable cap.
+  for (const execTool of ['bg_shell', 'gsd_uat_exec', 'bash', 'gsd_exec']) {
+    resetToolCallLoopGuard();
+
+    for (let i = 1; i <= 20; i++) {
+      const result = checkToolCallLoop(execTool, { command: `step ${i}` });
+      assert.ok(result.block === false, `${execTool} call ${i} after exec progress should be allowed`);
+      assert.deepStrictEqual(getToolCallCountForTool(execTool), 1, `${execTool} count should decay before call ${i}`);
+
+      // A successful (non-error) exec call records progress, like a file mutation.
+      recordToolCallLoopMutation(execTool);
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Failing exec loops still trip the per-tool cap (#783 vs #1206)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: failing exec loop (no progress recorded) still trips the cap (#783) ──');
+
+{
+  resetToolCallLoopGuard();
+
+  // The improvisation loop from #783: the model retries a missing tool through
+  // varied bash commands. Those fail (non-zero exit → isError), so the caller
+  // never records progress and the per-tool cap must still trip.
+  for (let i = 1; i <= 15; i++) {
+    const result = checkToolCallLoop('bash', { command: `try-missing-tool ${i}` });
+    assert.ok(result.block === false, `failing bash call ${i} should be allowed up to the cap`);
+    // No recordToolCallLoopMutation — the command errored.
+  }
+  const blocked = checkToolCallLoop('bash', { command: 'try-missing-tool 16' });
+  assert.ok(blocked.block === true, '16th failing bash call should be blocked by the per-tool cap');
+  assert.ok(blocked.reason?.includes('repeated tool'), 'reason should identify the per-tool guard');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// bg_shell/async_bash false-success must not decay the per-tool cap (#783)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: bg_shell failed run/start does not decay the cap (#783) ──');
+
+{
+  resetToolCallLoopGuard();
+
+  for (let i = 1; i <= 15; i++) {
+    const result = checkToolCallLoop('bg_shell', { action: 'run', command: `try-missing-tool ${i}` });
+    assert.ok(result.block === false, `failing bg_shell run ${i} should be allowed up to the cap`);
+    recordToolCallLoopMutation('bg_shell', { action: 'run', exitCode: 1, timedOut: false });
+  }
+  const blocked = checkToolCallLoop('bg_shell', { action: 'run', command: 'try-missing-tool 16' });
+  assert.ok(blocked.block === true, '16th failing bg_shell run should be blocked by the per-tool cap');
+}
+
+{
+  resetToolCallLoopGuard();
+
+  for (let i = 1; i <= 15; i++) {
+    checkToolCallLoop('bg_shell', { action: 'start', command: `bad-server ${i}` });
+    recordToolCallLoopMutation('bg_shell', {
+      action: 'start',
+      process: { alive: false, exitCode: 1 },
+    });
+  }
+  const blocked = checkToolCallLoop('bg_shell', { action: 'start', command: 'bad-server 16' });
+  assert.ok(blocked.block === true, '16th dead bg_shell start should be blocked by the per-tool cap');
+}
+
+console.log('\n── Loop guard: async_bash job registration does not decay the cap (#783) ──');
+
+{
+  resetToolCallLoopGuard();
+
+  for (let i = 1; i <= 6; i++) {
+    const result = checkToolCallLoop('async_bash', { command: `try-missing-tool ${i}` });
+    assert.ok(result.block === false, `async_bash call ${i} should be allowed up to the cap`);
+    recordToolCallLoopMutation('async_bash');
+  }
+  const blocked = checkToolCallLoop('async_bash', { command: 'try-missing-tool 7' });
+  assert.ok(blocked.block === true, '7th async_bash call should be blocked by the per-tool cap');
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Distinct read-only navigation calls are context gathering, not repeated-tool loops.
 // ═══════════════════════════════════════════════════════════════════════════
@@ -448,3 +542,105 @@ console.log('\n── Loop guard: browser exemption does not widen to other tool
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
+// Configurable thresholds (#1198)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Loop guard: master switch disables both guards (#1198) ──');
+
+{
+  configureToolCallLoopGuard({ enabled: false });
+  resetToolCallLoopGuard();
+  // Neither identical-args nor per-tool cap should ever trip while disabled.
+  for (let i = 1; i <= 30; i++) {
+    const result = checkToolCallLoop('gsd_complete_milestone', { same: 'args' });
+    assert.ok(result.block === false, `disabled guard should allow call ${i}`);
+  }
+  // Restore defaults for subsequent tests.
+  configureToolCallLoopGuard(null);
+}
+
+console.log('\n── Loop guard: repeated_tool disabled keeps identical-args protection (#1198) ──');
+
+{
+  configureToolCallLoopGuard({ repeated_tool: { enabled: false } });
+  resetToolCallLoopGuard();
+  // Per-tool cap is off: many varied-arg calls are allowed.
+  for (let i = 1; i <= 20; i++) {
+    const result = checkToolCallLoop('gsd_exec', { cmd: `run-${i}` });
+    assert.ok(result.block === false, `repeated_tool disabled should allow varied call ${i}`);
+  }
+  // Identical-args guard is still active.
+  resetToolCallLoopGuard();
+  for (let i = 1; i <= 4; i++) {
+    assert.ok(checkToolCallLoop('gsd_exec', { cmd: 'same' }).block === false);
+  }
+  const blocked = checkToolCallLoop('gsd_exec', { cmd: 'same' });
+  assert.ok(blocked.block === true, 'identical-args guard should still trip when repeated_tool is off');
+  assert.ok(blocked.reason?.includes('identical args'));
+  configureToolCallLoopGuard(null);
+}
+
+console.log('\n── Loop guard: raised caps allow more repeated calls (#1198) ──');
+
+{
+  configureToolCallLoopGuard({ repeated_tool: { default_cap: 10 } });
+  resetToolCallLoopGuard();
+  for (let i = 1; i <= 10; i++) {
+    const result = checkToolCallLoop('gsd_complete_milestone', { arg: `v${i}` });
+    assert.ok(result.block === false, `raised-cap call ${i} should be allowed`);
+  }
+  const blocked = checkToolCallLoop('gsd_complete_milestone', { arg: 'v11' });
+  assert.ok(blocked.block === true, '11th call should trip the raised cap of 10');
+  assert.ok(blocked.reason?.includes('cap 10'), 'block message should mention the active cap');
+  assert.ok(blocked.reason?.includes('tool_call_loop_guard'), 'block message should mention the config key');
+  configureToolCallLoopGuard(null);
+}
+
+console.log('\n── Loop guard: user-added exempt tools bypass the per-tool cap (#1198) ──');
+
+{
+  configureToolCallLoopGuard({ repeated_tool: { exempt_tools: ['ctx_execute'] } });
+  resetToolCallLoopGuard();
+  for (let i = 1; i <= 30; i++) {
+    const result = checkToolCallLoop('ctx_execute', { arg: `v${i}` });
+    assert.ok(result.block === false, `exempt tool call ${i} should be allowed`);
+  }
+  // Built-in exempt defaults are preserved alongside the user-added tool.
+  resetToolCallLoopGuard();
+  for (let i = 1; i <= 30; i++) {
+    assert.ok(checkToolCallLoop('read', { path: `f${i}` }).block === false, 'built-in exempt read should remain exempt');
+  }
+  configureToolCallLoopGuard(null);
+}
+
+console.log('\n── Loop guard: identical-args max is configurable (#1198) ──');
+
+{
+  configureToolCallLoopGuard({ identical_args: { max_consecutive_calls: 2 } });
+  resetToolCallLoopGuard();
+  assert.ok(checkToolCallLoop('web_search', { q: 'x' }).block === false, 'call 1 allowed');
+  assert.ok(checkToolCallLoop('web_search', { q: 'x' }).block === false, 'call 2 allowed');
+  const blocked = checkToolCallLoop('web_search', { q: 'x' });
+  assert.ok(blocked.block === true, '3rd identical call should trip lowered max of 2');
+  assert.ok(blocked.reason?.includes('max 2'), 'block message should mention active max');
+  configureToolCallLoopGuard(null);
+}
+
+console.log('\n── Loop guard: env overrides win over preferences (#1198) ──');
+
+{
+  process.env.GSD_TOOL_LOOP_REPEATED_DEFAULT_CAP = '2';
+  configureToolCallLoopGuard({ repeated_tool: { default_cap: 6 } });
+  resetToolCallLoopGuard();
+  assert.ok(checkToolCallLoop('gsd_complete_milestone', { a: '1' }).block === false, 'call 1 allowed');
+  assert.ok(checkToolCallLoop('gsd_complete_milestone', { a: '2' }).block === false, 'call 2 allowed');
+  const blocked = checkToolCallLoop('gsd_complete_milestone', { a: '3' });
+  assert.ok(blocked.block === true, 'env override cap of 2 should win over preference cap of 6');
+  delete process.env.GSD_TOOL_LOOP_REPEATED_DEFAULT_CAP;
+  configureToolCallLoopGuard(null);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Reset restores default guard state after configuration tests
+// ═══════════════════════════════════════════════════════════════════════════
+resetToolCallLoopGuard();