gsd-pi 2.36.0-dev.f887f4e → 2.37.0-dev.3186675

package/src/resources/extensions/gsd/metrics.ts

@@ -20,8 +20,10 @@ import { getAndClearSkills } from "./skill-telemetry.js";
 import { loadJsonFile, loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 import { parseUnitId } from "./unit-id.js";
 
-// Re-export from shared — canonical implementation lives in format-utils.
-export { formatTokenCount } from "../shared/mod.js";
+// Re-export from shared — import directly from format-utils to avoid pulling
+// in the full barrel (mod.js → ui.js → @gsd/pi-tui) which breaks when loaded
+// outside jiti's alias resolution (e.g. dynamic import in auto-loop reports).
+export { formatTokenCount } from "../shared/format-utils.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 

package/src/resources/extensions/gsd/notifications.ts

@@ -4,6 +4,7 @@
 import { execFileSync } from "node:child_process";
 import type { NotificationPreferences } from "./types.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
 
 export type NotifyLevel = "info" | "success" | "warning" | "error";
 export type NotificationKind = "complete" | "error" | "budget" | "milestone" | "attention";
@@ -23,7 +24,15 @@ export function sendDesktopNotification(
   level: NotifyLevel = "info",
   kind: NotificationKind = "complete",
 ): void {
-  if (!shouldSendDesktopNotification(kind)) return;
+  const loaded = loadEffectiveGSDPreferences()?.preferences;
+  if (!shouldSendDesktopNotification(kind, loaded?.notifications)) return;
+
+  const cmux = resolveCmuxConfig(loaded);
+  if (cmux.notifications) {
+    const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+    if (delivered) return;
+    emitOsc777Notification(title, message);
+  }
 
   try {
     const command = buildDesktopNotificationCommand(process.platform, title, message, level);

package/src/resources/extensions/gsd/preferences-types.ts

@@ -68,6 +68,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "budget_enforcement",
   "context_pause_threshold",
   "notifications",
+  "cmux",
   "remote_questions",
   "git",
   "post_unit_hooks",
@@ -84,6 +85,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "search_provider",
   "compression_strategy",
   "context_selection",
+  "widget_mode",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -164,6 +166,14 @@ export interface RemoteQuestionsConfig {
   poll_interval_seconds?: number;  // clamped to 2-30
 }
 
+export interface CmuxPreferences {
+  enabled?: boolean;
+  notifications?: boolean;
+  sidebar?: boolean;
+  splits?: boolean;
+  browser?: boolean;
+}
+
 export interface GSDPreferences {
   version?: number;
   mode?: WorkflowMode;
@@ -182,6 +192,7 @@ export interface GSDPreferences {
   budget_enforcement?: BudgetEnforcementMode;
   context_pause_threshold?: number;
   notifications?: NotificationPreferences;
+  cmux?: CmuxPreferences;
   remote_questions?: RemoteQuestionsConfig;
   git?: GitPreferences;
   post_unit_hooks?: PostUnitHookConfig[];
@@ -202,6 +213,8 @@ export interface GSDPreferences {
   compression_strategy?: CompressionStrategy;
   /** Context selection mode for file inlining. "full" inlines entire files, "smart" uses semantic chunking. Default derived from token profile. */
   context_selection?: ContextSelectionMode;
+  /** Default widget display mode for auto-mode dashboard. "full" | "small" | "min" | "off". Default: "full". */
+  widget_mode?: "full" | "small" | "min" | "off";
 }
 
 export interface LoadedGSDPreferences {

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -242,6 +242,32 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Cmux ───────────────────────────────────────────────────────────────
+  if (preferences.cmux !== undefined) {
+    if (preferences.cmux && typeof preferences.cmux === "object") {
+      const cmux = preferences.cmux as Record<string, unknown>;
+      const validatedCmux: NonNullable<GSDPreferences["cmux"]> = {};
+      if (cmux.enabled !== undefined) validatedCmux.enabled = !!cmux.enabled;
+      if (cmux.notifications !== undefined) validatedCmux.notifications = !!cmux.notifications;
+      if (cmux.sidebar !== undefined) validatedCmux.sidebar = !!cmux.sidebar;
+      if (cmux.splits !== undefined) validatedCmux.splits = !!cmux.splits;
+      if (cmux.browser !== undefined) validatedCmux.browser = !!cmux.browser;
+
+      const knownCmuxKeys = new Set(["enabled", "notifications", "sidebar", "splits", "browser"]);
+      for (const key of Object.keys(cmux)) {
+        if (!knownCmuxKeys.has(key)) {
+          warnings.push(`unknown cmux key "${key}" — ignored`);
+        }
+      }
+
+      if (Object.keys(validatedCmux).length > 0) {
+        validated.cmux = validatedCmux;
+      }
+    } else {
+      errors.push("cmux must be an object");
+    }
+  }
+
   // ─── Remote Questions ───────────────────────────────────────────────
   if (preferences.remote_questions !== undefined) {
     if (preferences.remote_questions && typeof preferences.remote_questions === "object") {

package/src/resources/extensions/gsd/preferences.ts

@@ -45,6 +45,7 @@ export type {
   SkillDiscoveryMode,
   AutoSupervisorConfig,
   RemoteQuestionsConfig,
+  CmuxPreferences,
   GSDPreferences,
   LoadedGSDPreferences,
   SkillResolution,
@@ -241,6 +242,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     notifications: (base.notifications || override.notifications)
       ? { ...(base.notifications ?? {}), ...(override.notifications ?? {}) }
       : undefined,
+    cmux: (base.cmux || override.cmux)
+      ? { ...(base.cmux ?? {}), ...(override.cmux ?? {}) }
+      : undefined,
     remote_questions: override.remote_questions
       ? { ...(base.remote_questions ?? {}), ...override.remote_questions }
       : base.remote_questions,

package/src/resources/extensions/gsd/prompts/research-milestone.md

@@ -25,9 +25,10 @@ Then research the codebase and relevant technologies. Narrate key findings and s
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code. For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase
-5. Use the **Research** output template from the inlined context above — include only sections that have real content
-6. If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
-7. Write `{{outputPath}}`
+5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — prefer `resolve_library` / `get_library_docs` for library documentation. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit.
+6. Use the **Research** output template from the inlined context above — include only sections that have real content
+7. If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
+8. Write `{{outputPath}}`
 
 ## Strategic Questions to Answer
 

package/src/resources/extensions/gsd/prompts/research-slice.md

@@ -46,8 +46,9 @@ Research what this slice needs. Narrate key findings and surprises as you go —
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries — skip this for libraries already used in the codebase
-5. Use the **Research** output template from the inlined context above — include only sections that have real content. The template is already inlined above; do NOT attempt to read any template file from disk (there is no `templates/SLICE-RESEARCH.md` — the correct template is already present in this prompt).
-6. Write `{{outputPath}}`
+5. **Web search budget:** You have a limited budget of web searches (max ~15 per session). Use them strategically — prefer `resolve_library` / `get_library_docs` for library documentation. Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on. Target 3-5 total web searches for a typical research unit.
+6. Use the **Research** output template from the inlined context above — include only sections that have real content. The template is already inlined above; do NOT attempt to read any template file from disk (there is no `templates/SLICE-RESEARCH.md` — the correct template is already present in this prompt).
+7. Write `{{outputPath}}`
 
 The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir — just write the file.
 

package/src/resources/extensions/gsd/session-lock.ts

@@ -40,6 +40,19 @@ export type SessionLockResult =
   | { acquired: true }
   | { acquired: false; reason: string; existingPid?: number };
 
+export type SessionLockFailureReason =
+  | "compromised"
+  | "missing-metadata"
+  | "pid-mismatch";
+
+export interface SessionLockStatus {
+  valid: boolean;
+  failureReason?: SessionLockFailureReason;
+  existingPid?: number;
+  expectedPid?: number;
+  recovered?: boolean;
+}
+
 // ─── Module State ───────────────────────────────────────────────────────────
 
 /** Release function from proper-lockfile — calling it releases the OS lock. */
@@ -368,7 +381,7 @@ export function updateSessionLock(
  *
  * This is called periodically during the dispatch loop.
  */
-export function validateSessionLock(basePath: string): boolean {
+export function getSessionLockStatus(basePath: string): SessionLockStatus {
   // Lock was compromised by proper-lockfile (mtime drift from sleep, stall, etc.)
   if (_lockCompromised) {
     // Recovery gate (#1512): Before declaring the lock lost, check if the lock
@@ -385,18 +398,23 @@ export function validateSessionLock(basePath: string): boolean {
           process.stderr.write(
             `[gsd] Lock recovered after onCompromised — lock file PID matched, re-acquired.\n`,
           );
-          return true;
+          return { valid: true, recovered: true };
         }
       } catch {
         // Re-acquisition failed — fall through to return false
       }
     }
-    return false;
+    return {
+      valid: false,
+      failureReason: "compromised",
+      existingPid: existing?.pid,
+      expectedPid: process.pid,
+    };
   }
 
   // If we have an OS-level lock, we're still the owner
   if (_releaseFunction && _lockedPath === basePath) {
-    return true;
+    return { valid: true };
   }
 
   // Fallback: check the lock file PID
@@ -404,10 +422,27 @@ export function validateSessionLock(basePath: string): boolean {
   const existing = readExistingLockData(lp);
   if (!existing) {
     // Lock file was deleted — we lost ownership
-    return false;
+    return {
+      valid: false,
+      failureReason: "missing-metadata",
+      expectedPid: process.pid,
+    };
+  }
+
+  if (existing.pid !== process.pid) {
+    return {
+      valid: false,
+      failureReason: "pid-mismatch",
+      existingPid: existing.pid,
+      expectedPid: process.pid,
+    };
   }
 
-  return existing.pid === process.pid;
+  return { valid: true };
+}
+
+export function validateSessionLock(basePath: string): boolean {
+  return getSessionLockStatus(basePath).valid;
 }
 
 /**

package/src/resources/extensions/gsd/templates/preferences.md

@@ -57,6 +57,12 @@ notifications:
   on_budget:
   on_milestone:
   on_attention:
+cmux:
+  enabled:
+  notifications:
+  sidebar:
+  splits:
+  browser:
 remote_questions:
   channel:
   channel_id:

package/src/resources/extensions/gsd/tests/auto-loop.test.ts

@@ -14,6 +14,7 @@ import {
   type AgentEndEvent,
   type LoopDeps,
 } from "../auto-loop.js";
+import type { SessionLockStatus } from "../session-lock.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -317,6 +318,8 @@ function makeMockDeps(
     },
     clearUnitTimeout: () => {},
     updateProgressWidget: () => {},
+    syncCmuxSidebar: () => {},
+    logCmuxEvent: () => {},
     invalidateAllCaches: () => {
       callLog.push("invalidateAllCaches");
     },
@@ -339,7 +342,7 @@ function makeMockDeps(
     preDispatchHealthGate: async () => ({ proceed: true, fixesApplied: [] }),
     syncProjectRootToWorktree: () => {},
     checkResourcesStale: () => null,
-    validateSessionLock: () => true,
+    validateSessionLock: () => ({ valid: true } as SessionLockStatus),
     updateSessionLock: () => {
       callLog.push("updateSessionLock");
     },
@@ -530,6 +533,41 @@ test("autoLoop exits on terminal complete state", async (t) => {
   );
 });
 
+test("autoLoop passes structured session-lock failure details to the handler", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.ui.setStatus = () => {};
+  const pi = makeMockPi();
+  const s = makeLoopSession();
+  let observedLockStatus: SessionLockStatus | undefined;
+
+  const deps = makeMockDeps({
+    validateSessionLock: () =>
+      ({
+        valid: false,
+        failureReason: "compromised",
+        expectedPid: process.pid,
+      }) as SessionLockStatus,
+    handleLostSessionLock: (_ctx, lockStatus) => {
+      observedLockStatus = lockStatus;
+      deps.callLog.push("handleLostSessionLock");
+    },
+  });
+
+  await autoLoop(ctx, pi, s, deps);
+
+  assert.deepEqual(observedLockStatus, {
+    valid: false,
+    failureReason: "compromised",
+    expectedPid: process.pid,
+  });
+  assert.ok(
+    !deps.callLog.includes("resolveDispatch"),
+    "should stop before dispatch after lock validation fails",
+  );
+});
+
 test("autoLoop exits on terminal blocked state", async (t) => {
   _resetPendingResolve();
 

package/src/resources/extensions/gsd/tests/auto-worktree.test.ts

@@ -153,6 +153,25 @@ async function main(): Promise<void> {
     // After teardown, originalBase should be null
     assertEq(getAutoWorktreeOriginalBase(), null, "no split-brain: originalBase cleared");
 
+    // ─── #1526: getMainBranch returns milestone branch in auto-worktree ──
+    console.log("\n=== #1526: getMainBranch() returns milestone/<MID> in auto-worktree ===");
+    {
+      const { GitServiceImpl } = await import("../git-service.ts");
+
+      // Create worktree
+      const wtPath = createAutoWorktree(tempDir, "M005");
+      // Don't set main_branch pref so getMainBranch falls through to worktree detection
+      const gitService = new GitServiceImpl(wtPath);
+      gitService.setMilestoneId("M005");
+
+      // Verify getMainBranch returns the milestone branch
+      const mainBranch = gitService.getMainBranch();
+      assertEq(mainBranch, "milestone/M005", "getMainBranch returns milestone/<MID> in auto-worktree");
+
+      // Cleanup
+      teardownAutoWorktree(tempDir, "M005");
+    }
+
     // ─── #778: reconcile plan checkboxes on re-attach ─────────────────
     console.log("\n=== #778: reconcile plan checkboxes on re-attach ===");
     {

package/src/resources/extensions/gsd/tests/cmux.test.ts

@@ -0,0 +1,122 @@
+import test, { describe } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  buildCmuxProgress,
+  buildCmuxStatusLabel,
+  detectCmuxEnvironment,
+  markCmuxPromptShown,
+  resetCmuxPromptState,
+  resolveCmuxConfig,
+  shouldPromptToEnableCmux,
+} from "../../cmux/index.ts";
+import type { GSDState } from "../types.ts";
+
+test("detectCmuxEnvironment requires workspace, surface, and socket", () => {
+  const detected = detectCmuxEnvironment(
+    {
+      CMUX_WORKSPACE_ID: "workspace:1",
+      CMUX_SURFACE_ID: "surface:2",
+      CMUX_SOCKET_PATH: "/tmp/cmux.sock",
+    },
+    (path) => path === "/tmp/cmux.sock",
+    () => true,
+  );
+  assert.equal(detected.available, true);
+  assert.equal(detected.cliAvailable, true);
+});
+
+test("resolveCmuxConfig enables only when preference and environment are both active", () => {
+  const config = resolveCmuxConfig(
+    { cmux: { enabled: true, notifications: true, sidebar: true, splits: true } },
+    {
+      CMUX_WORKSPACE_ID: "workspace:1",
+      CMUX_SURFACE_ID: "surface:2",
+      CMUX_SOCKET_PATH: "/tmp/cmux.sock",
+    },
+    () => true,
+    () => true,
+  );
+  assert.equal(config.enabled, true);
+  assert.equal(config.notifications, true);
+  assert.equal(config.sidebar, true);
+  assert.equal(config.splits, true);
+});
+
+test("shouldPromptToEnableCmux only prompts once per session", () => {
+  resetCmuxPromptState();
+  assert.equal(shouldPromptToEnableCmux({}, {}, () => false, () => true), false);
+
+  assert.equal(
+    shouldPromptToEnableCmux(
+      {},
+      {
+        CMUX_WORKSPACE_ID: "workspace:1",
+        CMUX_SURFACE_ID: "surface:2",
+        CMUX_SOCKET_PATH: "/tmp/cmux.sock",
+      },
+      () => true,
+      () => true,
+    ),
+    true,
+  );
+  markCmuxPromptShown();
+  assert.equal(
+    shouldPromptToEnableCmux(
+      {},
+      {
+        CMUX_WORKSPACE_ID: "workspace:1",
+        CMUX_SURFACE_ID: "surface:2",
+        CMUX_SOCKET_PATH: "/tmp/cmux.sock",
+      },
+      () => true,
+      () => true,
+    ),
+    false,
+  );
+  resetCmuxPromptState();
+});
+
+test("buildCmuxStatusLabel and progress prefer deepest active unit", () => {
+  const state: GSDState = {
+    activeMilestone: { id: "M001", title: "Milestone" },
+    activeSlice: { id: "S02", title: "Slice" },
+    activeTask: { id: "T03", title: "Task" },
+    phase: "executing",
+    recentDecisions: [],
+    blockers: [],
+    nextAction: "Keep going",
+    registry: [],
+    progress: {
+      milestones: { done: 0, total: 1 },
+      slices: { done: 1, total: 3 },
+      tasks: { done: 2, total: 5 },
+    },
+  };
+
+  assert.equal(buildCmuxStatusLabel(state), "M001 S02/T03 · executing");
+  assert.deepEqual(buildCmuxProgress(state), { value: 0.4, label: "2/5 tasks" });
+});
+
+describe("cmux extension discovery opt-out", () => {
+  test("cmux directory has package.json with pi manifest to prevent auto-discovery as extension", () => {
+    const cmuxDir = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      "../../cmux",
+    );
+    const pkgPath = path.join(cmuxDir, "package.json");
+    assert.ok(fs.existsSync(pkgPath), `${pkgPath} must exist`);
+
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    assert.ok(
+      pkg.pi !== undefined && typeof pkg.pi === "object",
+      'package.json must have a "pi" field to opt out of extension auto-discovery',
+    );
+    assert.ok(
+      !pkg.pi.extensions?.length,
+      "pi.extensions must be empty or absent — cmux is a library, not an extension",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/preferences.test.ts

@@ -171,6 +171,29 @@ test("notification fields validate correctly", () => {
   assert.equal(preferences.notifications?.on_complete, false);
 });
 
+test("cmux fields validate correctly", () => {
+  const { preferences, errors } = validatePreferences({
+    cmux: {
+      enabled: true,
+      notifications: true,
+      sidebar: false,
+      splits: true,
+      browser: false,
+    },
+  });
+  assert.equal(errors.length, 0);
+  assert.equal(preferences.cmux?.enabled, true);
+  assert.equal(preferences.cmux?.sidebar, false);
+  assert.equal(preferences.cmux?.splits, true);
+});
+
+test("cmux unknown keys produce warnings", () => {
+  const { warnings } = validatePreferences({
+    cmux: { enabled: true, strange_mode: true } as any,
+  });
+  assert.ok(warnings.some((warning) => warning.includes('unknown cmux key "strange_mode"')));
+});
+
 test("git fields comprehensive validation", () => {
   const { preferences, errors } = validatePreferences({
     git: {

package/src/resources/extensions/gsd/tests/session-lock-regression.test.ts

@@ -17,6 +17,7 @@ import { tmpdir } from 'node:os';
 
 import {
   acquireSessionLock,
+  getSessionLockStatus,
   validateSessionLock,
   releaseSessionLock,
   readSessionLockData,
@@ -201,6 +202,50 @@ async function main(): Promise<void> {
     }
   }
 
+  // ─── 7b. getSessionLockStatus with missing metadata → reason surfaced ──
+  console.log('\n=== 7b. missing lock metadata → structured reason ===');
+  {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-session-lock-'));
+    mkdirSync(join(base, '.gsd'), { recursive: true });
+
+    try {
+      const status = getSessionLockStatus(base);
+      assertEq(status.valid, false, 'missing lock metadata is invalid');
+      assertEq(status.failureReason, 'missing-metadata', 'missing metadata reason is surfaced');
+      assertEq(status.expectedPid, process.pid, 'expected PID is included');
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
+  // ─── 7c. getSessionLockStatus with foreign PID → reason surfaced ───────
+  console.log('\n=== 7c. foreign PID in lock file → structured reason ===');
+  {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-session-lock-'));
+    mkdirSync(join(base, '.gsd'), { recursive: true });
+
+    try {
+      const foreignPid = process.pid + 1000;
+      const lockFile = join(gsdRoot(base), 'auto.lock');
+      writeFileSync(lockFile, JSON.stringify({
+        pid: foreignPid,
+        startedAt: new Date().toISOString(),
+        unitType: 'execute-task',
+        unitId: 'M001/S01/T01',
+        unitStartedAt: new Date().toISOString(),
+        completedUnits: 0,
+      }, null, 2));
+
+      const status = getSessionLockStatus(base);
+      assertEq(status.valid, false, 'foreign PID lock is invalid');
+      assertEq(status.failureReason, 'pid-mismatch', 'PID mismatch reason is surfaced');
+      assertEq(status.existingPid, foreignPid, 'existing PID is included');
+      assertEq(status.expectedPid, process.pid, 'expected PID is included');
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  }
+
   // ─── 8. Acquire after release is possible ─────────────────────────────
   console.log('\n=== 8. acquire after release → re-acquirable ===');
   {

package/src/resources/extensions/search-the-web/native-search.ts

@@ -16,6 +16,16 @@ export const CUSTOM_SEARCH_TOOL_NAMES = ["search-the-web", "search_and_read", "g
 /** Thinking block types that require signature validation by the API */
 const THINKING_TYPES = new Set(["thinking", "redacted_thinking"]);
 
+/**
+ * Maximum number of native web searches allowed per session (agent unit).
+ * The Anthropic API's `max_uses` is per-request — it resets on each API call.
+ * When `pause_turn` triggers a resubmit, the model gets a fresh budget.
+ * This session-level cap prevents unbounded search accumulation (#1309).
+ *
+ * 15 = 3 full turns of 5 searches each — generous for research, but bounded.
+ */
+export const MAX_NATIVE_SEARCHES_PER_SESSION = 15;
+
 /** When true, skip native web search injection and keep Brave/custom tools active on Anthropic. */
 export function preferBraveSearch(): boolean {
   // preferences.md takes priority over env var
@@ -74,6 +84,11 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
   let isAnthropicProvider = false;
   let modelSelectFired = false;
 
+  // Session-level native search counter (#1309).
+  // Tracks cumulative web_search_tool_result blocks across all turns in a session.
+  // Reset on session_start. Used to compute remaining budget for max_uses.
+  let sessionSearchCount = 0;
+
   // Track provider changes via model selection — also handles diagnostics
   // since model_select fires AFTER session_start and knows the provider.
   pi.on("model_select", async (event: any, ctx: any) => {
@@ -161,13 +176,41 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
     );
     payload.tools = tools;
 
+    // ── Session-level search budget (#1309) ──────────────────────────────
+    // Count web_search_tool_result blocks in the conversation history to
+    // determine how many native searches have already been used this session.
+    // The Anthropic API's max_uses resets per request, so without this guard,
+    // pause_turn → resubmit cycles allow unlimited total searches.
+    if (Array.isArray(messages)) {
+      let historySearchCount = 0;
+      for (const msg of messages) {
+        const content = msg.content;
+        if (!Array.isArray(content)) continue;
+        for (const block of content) {
+          if ((block as any)?.type === "web_search_tool_result") {
+            historySearchCount++;
+          }
+        }
+      }
+      // Sync counter from history (handles session restore / context replay)
+      sessionSearchCount = historySearchCount;
+    }
+
+    const remaining = Math.max(0, MAX_NATIVE_SEARCHES_PER_SESSION - sessionSearchCount);
+
+    if (remaining <= 0) {
+      // Budget exhausted — don't inject the search tool at all.
+      // The model will proceed without web search capability.
+      return payload;
+    }
+
     tools.push({
       type: "web_search_20250305",
       name: "web_search",
-      // Cap server-side searches per response to prevent the model from
-      // looping on web_search without synthesizing results (#817).
-      // 5 searches is generous — most queries need 1-2.
-      max_uses: 5,
+      // Cap per-request searches to the lesser of 5 (per-turn cap) or the
+      // remaining session budget (#1309). This prevents the model from
+      // consuming unlimited searches via pause_turn → resubmit cycles.
+      max_uses: Math.min(5, remaining),
     });
 
     return payload;
@@ -175,6 +218,9 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
 
   // Basic startup diagnostics — provider-specific info comes from model_select
   pi.on("session_start", async (_event: any, ctx: any) => {
+    // Reset session-level search budget (#1309)
+    sessionSearchCount = 0;
+
     const hasBrave = !!process.env.BRAVE_API_KEY;
     const hasJina = !!process.env.JINA_API_KEY;
     const hasAnswers = !!process.env.BRAVE_ANSWERS_KEY;