reasonix 0.41.0 → 0.43.0

package/dist/index.js

@@ -966,6 +966,7 @@ var EN = {
     applied: "applied",
     rejected: "rejected",
     noDashboard: "Suppress the auto-launched embedded web dashboard.",
+    openDashboardHint: "Open the dashboard URL in your default browser as soon as the server is ready. No-op when --no-dashboard is set.",
     dashboardPortHint: "Pin the dashboard to a fixed port (1\u201365535). Stable across restarts \u2014 required for SSH tunnels. Default: ephemeral.",
     dashboardPortInvalid: "\u25B2 ignoring --dashboard-port={value} (must be an integer 1\u201365535) \u2014 falling back to ephemeral",
     dashboardAutoStartFailed: "\u25B2 dashboard auto-start failed ({reason}) \u2014 try /dashboard, or pass --no-dashboard to silence",
@@ -1130,7 +1131,13 @@ var EN = {
     jsonHintCatalog: "output as JSON",
     jsonHintReport: "output the inspection report as JSON",
     modelOverrideFlash: "override the model (default: deepseek-v4-flash)",
-    skipConfirmHint: "skip the confirmation prompt"
+    skipConfirmHint: "skip the confirmation prompt",
+    yoloHint: "auto-approve plan checkpoints for this invocation (equivalent to editMode=yolo without mutating config)"
+  },
+  code: {
+    workspaceConflict: "\u26A0 workspace contains another agent platform's files ({platforms}). Reasonix Code may read them as project content; relaunch with --dir <your-project> if that's not what you want.\n",
+    systemAppendEmpty: "--system-append is empty \u2014 no prompt text will be appended\n",
+    systemAppendFileReadError: 'Error: cannot read --system-append-file "{filePath}": {errorDetails}\n'
   },
   slash: {
     help: { description: "show the full command reference" },
@@ -1276,6 +1283,14 @@ var EN = {
     logs: {
       description: "tail a background job's output (default last 80 lines)",
       argsHint: "<id> [lines]"
+    },
+    btw: {
+      description: "ask a quick side question \u2014 answered from a blank slate, never added to the conversation context",
+      argsHint: "<question>"
+    },
+    "search-engine": {
+      description: "switch web search backend \u2014 mojeek (default, no deps) or searxng (self-hosted)",
+      argsHint: "<mojeek|searxng> [<endpoint>]"
     }
   },
   wizard: {
@@ -1478,7 +1493,6 @@ var EN = {
     flashEscalation: "\u21E7 flash requested escalation \u2014 retrying this turn on {model}{reasonSuffix}",
     harvestStatus: "extracting plan state from reasoning\u2026",
     autoEscalation: "\u21E7 auto-escalating to {model} for the rest of this turn \u2014 flash hit {breakdown}. Next turn falls back to {fallback} unless /pro is armed.",
-    readOnlyLoopEscalation: "\u21E7 auto-escalating to {model} \u2014 flash made {n} consecutive read-only calls without producing an edit or final answer. Next turn falls back to {fallback} unless /pro is armed.",
     repeatToolCallWarning: "Caught a repeated tool call \u2014 let the model see the issue and retry with a different approach.",
     stormStuck: "Stopped a stuck retry loop \u2014 the model kept calling the same tool with identical args after a self-correction nudge. Try /retry, rephrase, or rule out the underlying blocker.",
     stormSuppressed: "Suppressed {count} repeated tool call(s) \u2014 same name + args fired 3+ times.",
@@ -1859,7 +1873,8 @@ var EN = {
     mb: " MB",
     evt: " evt",
     editsLabel: "edits:",
-    mcpLoading: "MCP"
+    mcpLoading: "MCP",
+    ctx: "ctx"
   },
   editMode: {
     plan: "PLAN MODE",
@@ -2232,7 +2247,9 @@ var EN = {
     reconnect: "reconnect\u2026",
     initDetail: "initialise \u2192 tools/list \u2192 resources/list",
     reconnectDetail: "tearing down \xB7 re-handshake \xB7 listing tools",
-    disabledDetail: "via /mcp disable {name}"
+    disabledDetail: "via /mcp disable {name}",
+    failedSetupHint: "\u2192 run `reasonix setup` to remove this entry, or fix the underlying issue (missing npm package, network, etc.).",
+    failedSetupConfigHint: "\u2192 run `reasonix setup` to remove broken entries from your saved config."
   },
   checkpointPicker: {
     title: "restore a checkpoint \u2014 {workspace}",
@@ -2330,6 +2347,7 @@ var zhCN = {
     applied: "\u5DF2\u5E94\u7528",
     rejected: "\u5DF2\u62D2\u7EDD",
     noDashboard: "\u7981\u6B62\u81EA\u52A8\u542F\u52A8\u5D4C\u5165\u5F0F Web \u4EEA\u8868\u677F\u3002",
+    openDashboardHint: "\u670D\u52A1\u5C31\u7EEA\u540E\u7ACB\u5373\u5728\u9ED8\u8BA4\u6D4F\u89C8\u5668\u4E2D\u6253\u5F00\u4EEA\u8868\u677F\u5730\u5740\u3002\u8BBE\u7F6E\u4E86 --no-dashboard \u65F6\u4E0D\u751F\u6548\u3002",
     dashboardPortHint: "\u5C06\u4EEA\u8868\u677F\u7ED1\u5B9A\u5230\u56FA\u5B9A\u7AEF\u53E3 (1\u201365535)\u3002\u91CD\u542F\u540E\u4FDD\u6301\u7A33\u5B9A \u2014 SSH \u96A7\u9053\u8BBF\u95EE\u5FC5\u9700\u3002\u9ED8\u8BA4\u4E3A\u4E34\u65F6\u7AEF\u53E3\u3002",
     dashboardPortInvalid: "\u25B2 \u5FFD\u7565 --dashboard-port={value} (\u5FC5\u987B\u4E3A 1\u201365535 \u4E4B\u95F4\u7684\u6574\u6570) \u2014 \u56DE\u9000\u5230\u4E34\u65F6\u7AEF\u53E3",
     dashboardAutoStartFailed: "\u25B2 \u4EEA\u8868\u677F\u81EA\u52A8\u542F\u52A8\u5931\u8D25 ({reason}) \u2014 \u5C1D\u8BD5 /dashboard\uFF0C\u6216\u4F20\u9012 --no-dashboard \u4EE5\u9759\u9ED8",
@@ -2491,7 +2509,13 @@ var zhCN = {
     jsonHintCatalog: "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA",
     jsonHintReport: "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA\u68C0\u67E5\u62A5\u544A",
     modelOverrideFlash: "\u8986\u76D6\u6A21\u578B\uFF08\u9ED8\u8BA4\uFF1Adeepseek-v4-flash\uFF09",
-    skipConfirmHint: "\u8DF3\u8FC7\u786E\u8BA4\u63D0\u793A"
+    skipConfirmHint: "\u8DF3\u8FC7\u786E\u8BA4\u63D0\u793A",
+    yoloHint: "\u81EA\u52A8\u6279\u51C6\u672C\u6B21\u8C03\u7528\u7684\u8BA1\u5212\u68C0\u67E5\u70B9\uFF08\u7B49\u540C\u4E8E editMode=yolo\uFF0C\u4F46\u4E0D\u4FEE\u6539\u914D\u7F6E\u6587\u4EF6\uFF09"
+  },
+  code: {
+    workspaceConflict: "\u26A0 \u5DE5\u4F5C\u533A\u5305\u542B\u53E6\u4E00\u4E2A\u667A\u80FD\u4F53\u5E73\u53F0\u7684\u6587\u4EF6 ({platforms})\u3002Reasonix Code \u53EF\u80FD\u4F1A\u5C06\u5176\u4F5C\u4E3A\u9879\u76EE\u5185\u5BB9\u8BFB\u53D6\uFF1B\u5982\u679C\u4E0D\u662F\u60A8\u60F3\u8981\u7684\uFF0C\u8BF7\u4F7F\u7528 --dir <your-project> \u91CD\u65B0\u542F\u52A8\u3002\n",
+    systemAppendEmpty: "--system-append \u4E3A\u7A7A \u2014 \u4E0D\u4F1A\u8FFD\u52A0\u4EFB\u4F55\u63D0\u793A\u6587\u672C\n",
+    systemAppendFileReadError: '\u9519\u8BEF\uFF1A\u65E0\u6CD5\u8BFB\u53D6 --system-append-file "{filePath}"\uFF1A{errorDetails}\n'
   },
   slash: {
     help: { description: "\u663E\u793A\u5B8C\u6574\u547D\u4EE4\u53C2\u8003" },
@@ -2641,6 +2665,14 @@ var zhCN = {
     logs: {
       description: "\u8DDF\u8E2A\u540E\u53F0\u4F5C\u4E1A\u7684\u8F93\u51FA\uFF08\u9ED8\u8BA4\u6700\u540E 80 \u884C\uFF09",
       argsHint: "<id> [lines]"
+    },
+    btw: {
+      description: "\u987A\u4FBF\u95EE\u4E00\u4E0B \u2014 \u4ECE\u7A7A\u767D\u4E0A\u4E0B\u6587\u56DE\u7B54\uFF0C\u4E0D\u5199\u5165\u4F1A\u8BDD\u5386\u53F2",
+      argsHint: "<question>"
+    },
+    "search-engine": {
+      description: "\u5207\u6362\u7F51\u7EDC\u641C\u7D22\u540E\u7AEF \u2014 mojeek\uFF08\u9ED8\u8BA4\uFF0C\u65E0\u4F9D\u8D56\uFF09\u6216 searxng\uFF08\u81EA\u6258\u7BA1\uFF09",
+      argsHint: "<mojeek|searxng> [<endpoint>]"
     }
   },
   wizard: {
@@ -2843,7 +2875,6 @@ var zhCN = {
     flashEscalation: "\u21E7 flash \u8BF7\u6C42\u5347\u7EA7 \u2014 \u672C\u8F6E\u6539\u7528 {model}{reasonSuffix}",
     harvestStatus: "\u6B63\u5728\u4ECE\u63A8\u7406\u8FC7\u7A0B\u63D0\u53D6\u8BA1\u5212\u72B6\u6001\u2026",
     autoEscalation: "\u21E7 \u672C\u8F6E\u5269\u4F59\u8C03\u7528\u81EA\u52A8\u5347\u7EA7\u5230 {model} \u2014 flash \u547D\u4E2D {breakdown}\u3002\u4E0B\u4E00\u8F6E\u56DE\u9000\u5230 {fallback}\uFF0C\u9664\u975E\u5DF2\u88C5\u5907 /pro\u3002",
-    readOnlyLoopEscalation: "\u21E7 \u81EA\u52A8\u5347\u7EA7\u5230 {model} \u2014 flash \u8FDE\u7EED {n} \u6B21\u53EA\u8BFB\u8C03\u7528\uFF0C\u672A\u4EA7\u51FA\u4FEE\u6539\u6216\u6700\u7EC8\u7B54\u6848\u3002\u4E0B\u4E00\u8F6E\u56DE\u9000\u5230 {fallback}\uFF0C\u9664\u975E\u5DF2\u88C5\u5907 /pro\u3002",
     repeatToolCallWarning: "\u62E6\u622A\u5230\u91CD\u590D\u5DE5\u5177\u8C03\u7528 \u2014 \u8BA9\u6A21\u578B\u5BDF\u89C9\u95EE\u9898\u5E76\u6362\u79CD\u65B9\u5F0F\u91CD\u8BD5\u3002",
     stormStuck: "\u5DF2\u505C\u6B62\u5361\u6B7B\u7684\u91CD\u8BD5\u5FAA\u73AF \u2014 \u6A21\u578B\u5728\u81EA\u7EA0\u63D0\u793A\u540E\u4ECD\u4EE5\u76F8\u540C\u53C2\u6570\u91CD\u590D\u8C03\u7528\u540C\u4E00\u5DE5\u5177\u3002\u8BF7\u5C1D\u8BD5 /retry\u3001\u6362\u79CD\u8BF4\u6CD5\uFF0C\u6216\u6392\u67E5\u5E95\u5C42\u963B\u585E\u3002",
     stormSuppressed: "\u5DF2\u6291\u5236 {count} \u6B21\u91CD\u590D\u5DE5\u5177\u8C03\u7528 \u2014 \u540C\u4E00\u540D\u79F0 + \u53C2\u6570\u89E6\u53D1 3 \u6B21\u4EE5\u4E0A\u3002",
@@ -3224,7 +3255,8 @@ var zhCN = {
     mb: " MB",
     evt: " \u4E8B\u4EF6",
     editsLabel: "\u7F16\u8F91:",
-    mcpLoading: "MCP"
+    mcpLoading: "MCP",
+    ctx: "\u4E0A\u4E0B\u6587"
   },
   editMode: {
     plan: "\u8BA1\u5212",
@@ -3597,7 +3629,9 @@ var zhCN = {
     reconnect: "\u91CD\u8FDE\u4E2D\u2026",
     initDetail: "\u521D\u59CB\u5316 \u2192 tools/list \u2192 resources/list",
     reconnectDetail: "\u65AD\u5F00\u65E7\u8FDE\u63A5 \xB7 \u91CD\u65B0\u63E1\u624B \xB7 \u5217\u51FA\u5DE5\u5177",
-    disabledDetail: "\u901A\u8FC7 /mcp disable {name}"
+    disabledDetail: "\u901A\u8FC7 /mcp disable {name}",
+    failedSetupHint: "\u2192 \u8FD0\u884C `reasonix setup` \u79FB\u9664\u6B64\u6761\u76EE\uFF0C\u6216\u4FEE\u590D\u5E95\u5C42\u95EE\u9898\uFF08\u7F3A\u5C11 npm \u5305\u3001\u7F51\u7EDC\u7B49\uFF09\u3002",
+    failedSetupConfigHint: "\u2192 \u8FD0\u884C `reasonix setup` \u4ECE\u5DF2\u4FDD\u5B58\u914D\u7F6E\u4E2D\u79FB\u9664\u635F\u574F\u7684\u6761\u76EE\u3002"
   },
   checkpointPicker: {
     title: "\u6062\u590D\u68C0\u67E5\u70B9 \u2014 {workspace}",
@@ -4581,7 +4615,7 @@ import {
   writeFileSync as writeFileSync2
 } from "fs";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname3, join as join4 } from "path";
+import { dirname as dirname3, join as join4, posix as posixPath, win32 as win32Path } from "path";
 function sessionsDir() {
   return join4(homedir3(), ".reasonix", "sessions");
 }
@@ -4868,6 +4902,23 @@ var HISTORY_FOLD_MIN_SAVINGS_FRACTION = 0.3;
 var FORCE_SUMMARY_THRESHOLD = 0.8;
 var PREFLIGHT_EMERGENCY_THRESHOLD = 0.95;
 var HISTORY_FOLD_MARKER = "[CONVERSATION HISTORY SUMMARY \u2014 earlier turns folded for context efficiency]\n\n";
+var SKILL_PIN_MEMO_HEADER = "[Active skill memos \u2014 preserved verbatim across the fold:]";
+var SKILL_PIN_REGEX = /<skill-pin name="([^"]+)">\n[\s\S]*?\n<\/skill-pin>/g;
+function extractPinnedSkills(head) {
+  const pinned = /* @__PURE__ */ new Map();
+  const stubbedHead = head.map((msg) => {
+    if (typeof msg.content !== "string") return msg;
+    let hit = false;
+    const next = msg.content.replace(SKILL_PIN_REGEX, (full, name) => {
+      pinned.delete(name);
+      pinned.set(name, full);
+      hit = true;
+      return `[skill ${JSON.stringify(name)} memo \u2014 preserved separately, do not summarize.]`;
+    });
+    return hit ? { ...msg, content: next } : msg;
+  });
+  return { stubbedHead, pinnedBodies: [...pinned.values()] };
+}
 var ContextManager = class {
   constructor(deps) {
     this.deps = deps;
@@ -4937,11 +4988,17 @@ var ContextManager = class {
     const tail = all.slice(boundary);
     const headTokens = totalTokens - cumTokens;
     if (headTokens < totalTokens * HISTORY_FOLD_MIN_SAVINGS_FRACTION) return noop;
-    const summary = await this.summarizeForFold(head);
+    const { stubbedHead, pinnedBodies } = extractPinnedSkills(head);
+    const summary = await this.summarizeForFold(stubbedHead);
     if (!summary) return noop;
+    const memoTail = pinnedBodies.length > 0 ? `
+
+${SKILL_PIN_MEMO_HEADER}
+
+${pinnedBodies.join("\n\n")}` : "";
     const summaryMsg = {
       role: "assistant",
-      content: HISTORY_FOLD_MARKER + summary
+      content: HISTORY_FOLD_MARKER + summary + memoTail
     };
     const replacement = [summaryMsg, ...tail];
     this.deps.log.compactInPlace(replacement);
@@ -5166,6 +5223,8 @@ function buildSyntheticAssistantMessage(content, fallbackModel) {
 }
 
 // src/loop/force-summary.ts
+var PAUSE_SUMMARY_MODEL = "deepseek-v4-flash";
+var PAUSE_SUMMARY_EFFORT = "high";
 async function* forceSummaryAfterIterLimit(ctx, opts = { reason: "budget" }) {
   try {
     yield { turn: ctx.turn, role: "status", content: t("summary.status") };
@@ -5211,6 +5270,28 @@ ${summary}`;
     yield { turn: ctx.turn, role: "done", content: "" };
   }
 }
+async function summarizePartialProgress(ctx) {
+  try {
+    const messages = ctx.buildMessages();
+    messages.push({
+      role: "user",
+      content: "You're being paused at a checkpoint, not stopped. In 3-6 sentences of plain prose, tell the parent agent: (1) what you accomplished so far, (2) what's still left, (3) any blockers or open questions. Be concrete \u2014 mention specific files / functions / tool results \u2014 so the parent can decide whether to resume you or take over. Do NOT emit any tool calls, function-call markup, DSML invocations, or SEARCH/REPLACE edit blocks \u2014 they will be silently discarded. Just plain text."
+    });
+    const resp = await ctx.client.chat({
+      model: PAUSE_SUMMARY_MODEL,
+      messages,
+      signal: ctx.signal,
+      thinking: thinkingModeForModel(PAUSE_SUMMARY_MODEL),
+      reasoningEffort: PAUSE_SUMMARY_EFFORT
+    });
+    const cleaned = stripHallucinatedToolMarkup(resp.content?.trim() ?? "");
+    if (!cleaned) return null;
+    const stats = ctx.recordStats(PAUSE_SUMMARY_MODEL, resp.usage ?? new Usage());
+    return { summary: cleaned, stats };
+  } catch {
+    return null;
+  }
+}
 
 // src/loop/shrink.ts
 function looksLikeCompleteJson(s) {
@@ -5348,32 +5429,6 @@ function* hookWarnings(outcomes, turn) {
   }
 }
 
-// src/loop/read-only-loop-tracker.ts
-var READONLY_LOOP_ESCALATION_THRESHOLD = 8;
-var ReadOnlyLoopTracker = class {
-  streak = 0;
-  threshold;
-  constructor(threshold = READONLY_LOOP_ESCALATION_THRESHOLD) {
-    this.threshold = Math.max(1, threshold);
-  }
-  reset() {
-    this.streak = 0;
-  }
-  /** True ONLY on the call where the streak crosses the configured threshold. */
-  noteAndCrossedThreshold(isReadOnly) {
-    if (!isReadOnly) {
-      this.streak = 0;
-      return false;
-    }
-    const before = this.streak;
-    this.streak += 1;
-    return before < this.threshold && this.streak >= this.threshold;
-  }
-  get currentStreak() {
-    return this.streak;
-  }
-};
-
 // src/loop/turn-failure-tracker.ts
 var FAILURE_ESCALATION_THRESHOLD = 3;
 var TurnFailureTracker = class {
@@ -5856,6 +5911,7 @@ var CacheFirstLoop = class {
   /** One-shot 80% warning latch — cleared by setBudget so a bump re-arms at the new boundary. */
   _budgetWarned = false;
   sessionName;
+  onIterBudgetExhausted;
   hooks;
   hookCwd;
   /** PauseGate bridge — defaults to singleton, injectable for tests. */
@@ -5872,7 +5928,6 @@ var CacheFirstLoop = class {
   _proArmedForNextTurn = false;
   _escalateThisTurn = false;
   _turnFailures;
-  _readOnlyLoop;
   _turnSelfCorrected = false;
   _foldedThisTurn = false;
   _toolDispatchesThisStep = 0;
@@ -5895,10 +5950,8 @@ var CacheFirstLoop = class {
     this._turnFailures = new TurnFailureTracker(
       resolveFailureThreshold(opts.failureThreshold, FAILURE_ESCALATION_THRESHOLD)
     );
-    this._readOnlyLoop = new ReadOnlyLoopTracker(
-      parsePositiveIntEnv(process.env.REASONIX_READONLY_LOOP_THRESHOLD) ?? READONLY_LOOP_ESCALATION_THRESHOLD
-    );
     this.maxToolIters = opts.maxToolIters ?? 64;
+    this.onIterBudgetExhausted = opts.onIterBudgetExhausted ?? "summarize";
     this.hooks = opts.hooks ?? [];
     this.hookCwd = opts.hookCwd ?? process.cwd();
     this.confirmationGate = opts.confirmationGate ?? pauseGate;
@@ -6074,14 +6127,6 @@ var CacheFirstLoop = class {
     this._escalateThisTurn = true;
     return true;
   }
-  /** Returns true ONLY on the call where the read-only streak crosses the threshold (#681). */
-  noteReadOnlyToolCall(call) {
-    const isReadOnly = !this.isMutating(call);
-    if (!this._readOnlyLoop.noteAndCrossedThreshold(isReadOnly)) return false;
-    if (this._escalateThisTurn || !this.autoEscalate) return false;
-    this._escalateThisTurn = true;
-    return true;
-  }
   /** A call counts as mutating when its definition reports `readOnly !== true` and any dynamic `readOnlyCheck` doesn't override that for these args. */
   isMutating(call) {
     const name = call.function?.name;
@@ -6223,7 +6268,6 @@ ${reason}`
     this.scratch.reset();
     this.repair.resetStorm();
     this._turnFailures.reset();
-    this._readOnlyLoop.reset();
     this._turnSelfCorrected = false;
     this._escalateThisTurn = false;
     this._foldedThisTurn = false;
@@ -6341,6 +6385,15 @@ ${reason}`
             thinking: thinkingModeForModel(callModel),
             reasoningEffort: this.reasoningEffort
           })) {
+            if (chunk.reasoningDelta) {
+              reasoningContent += chunk.reasoningDelta;
+              yield {
+                turn: this._turn,
+                role: "assistant_delta",
+                content: "",
+                reasoningDelta: chunk.reasoningDelta
+              };
+            }
             if (chunk.contentDelta) {
               assistantContent += chunk.contentDelta;
               if (bufferForEscalation && !escalationBufFlushed) {
@@ -6365,15 +6418,6 @@ ${reason}`
                 };
               }
             }
-            if (chunk.reasoningDelta) {
-              reasoningContent += chunk.reasoningDelta;
-              yield {
-                turn: this._turn,
-                role: "assistant_delta",
-                content: "",
-                reasoningDelta: chunk.reasoningDelta
-              };
-            }
             if (chunk.toolCallDelta) {
               const d = chunk.toolCallDelta;
               const cur = callBuf.get(d.index) ?? {
@@ -6650,17 +6694,6 @@ ${reason}`
               })
             };
           }
-          if (this.noteReadOnlyToolCall(call)) {
-            yield {
-              turn: this._turn,
-              role: "warning",
-              content: t("loop.readOnlyLoopEscalation", {
-                model: ESCALATION_MODEL,
-                n: this._readOnlyLoop.currentStreak,
-                fallback: this.model
-              })
-            };
-          }
           yield {
             turn: this._turn,
             role: "tool",
@@ -6672,6 +6705,19 @@ ${reason}`
         }
       }
     }
+    if (this.onIterBudgetExhausted === "pause") {
+      const partial = await summarizePartialProgress(this.summaryContext());
+      yield {
+        turn: this._turn,
+        role: "paused",
+        content: "",
+        sessionName: this.sessionName ?? void 0,
+        pausedAtIter: this.maxToolIters,
+        partialSummary: partial?.summary
+      };
+      yield { turn: this._turn, role: "done", content: "" };
+      return;
+    }
     yield* forceSummaryAfterIterLimit(this.summaryContext(), { reason: "budget" });
   }
   summaryContext() {
@@ -7364,6 +7410,12 @@ function parseAllowedTools(raw) {
   const names = raw.split(",").map((s) => s.trim()).filter(Boolean);
   return names.length > 0 ? Object.freeze(names) : void 0;
 }
+function parseMaxToolIters(raw) {
+  if (raw === void 0) return void 0;
+  const n = Number.parseInt(raw.trim(), 10);
+  if (!Number.isFinite(n) || n < 1) return void 0;
+  return n;
+}
 var SkillStore = class {
   homeDir;
   projectRoot;
@@ -7494,7 +7546,8 @@ var SkillStore = class {
       path: path2,
       allowedTools: parseAllowedTools(data["allowed-tools"]),
       runAs: parseRunAs(data.runAs),
-      model: data.model?.startsWith("deepseek-") ? data.model : void 0
+      model: data.model?.startsWith("deepseek-") ? data.model : void 0,
+      maxToolIters: parseMaxToolIters(data["max-iters"])
     };
   }
 };
@@ -7515,6 +7568,7 @@ Tips:
 - Reference tools by name (run_command, edit_file, search_content, ...)
 - Add \`runAs: subagent\` to frontmatter to spawn an isolated subagent loop
 - Add \`allowed-tools: read_file, search_content\` to scope a subagent's tools
+- Add \`max-iters: N\` to change the subagent's pause cadence (default 16). This isn't a budget \u2014 the parent resumes on pause, so N is how often the parent gets a checkpoint, not how much total work the subagent gets.
 `;
 }
 function skillIndexLine(s) {
@@ -9886,9 +9940,7 @@ ${NEGATIVE_CLAIM_RULE}
 
 ${TUI_FORMATTING_RULES}`;
 var DEFAULT_MAX_RESULT_CHARS2 = 8e3;
-var DEFAULT_MAX_ITERS = 16;
-var MIN_MAX_ITERS = 1;
-var MAX_MAX_ITERS = 32;
+var DEFAULT_PAUSE_EVERY = 16;
 var BUDGET_WARN_THRESHOLD = 3;
 function budgetParagraph(maxToolIters) {
   return `Tool budget: you have ${maxToolIters} tool call${maxToolIters === 1 ? "" : "s"} for this task. The cap is enforced from outside \u2014 the call after #${maxToolIters} is refused. Pace yourself: if you can't fully resolve the task within the budget, stop early and return what you have plus what's missing, rather than burning the budget on one branch.`;
@@ -9911,12 +9963,13 @@ function subagentBudgetHint(spawnCount, totalTokens) {
 }
 async function spawnSubagent(opts) {
   const model = opts.model ?? DEFAULT_SUBAGENT_MODEL;
-  const maxToolIters = opts.maxToolIters ?? DEFAULT_MAX_ITERS;
+  const maxToolIters = opts.maxToolIters ?? DEFAULT_PAUSE_EVERY;
   const maxResultChars = opts.maxResultChars ?? DEFAULT_MAX_RESULT_CHARS2;
   const sink = opts.sink;
   const skillName = opts.skillName;
-  const startedAt = Date.now();
   const runId = nextRunId();
+  const sessionName = opts.resumeSession ?? `subagent-${runId}-${timestampSuffix()}`;
+  const startedAt = Date.now();
   const taskPreview = opts.task.length > 30 ? `${opts.task.slice(0, 30)}\u2026` : opts.task;
   sink?.current?.({
     kind: "start",
@@ -9996,10 +10049,9 @@ ${budgetParagraph(maxToolIters)}`,
     reasoningEffort: DEFAULT_SUBAGENT_EFFORT,
     maxToolIters,
     hooks: [],
-    // Streaming on so the parent UI can flip the "summarising" phase the
-    // moment the model starts emitting the final answer (first assistant_delta
-    // after the last tool result, before assistant_final lands).
-    stream: true
+    stream: true,
+    session: sessionName,
+    onIterBudgetExhausted: "pause"
   });
   const onParentAbort = () => childLoop.abort();
   if (opts.parentSignal?.aborted) {
@@ -10011,8 +10063,13 @@ ${budgetParagraph(maxToolIters)}`,
   let errorMessage;
   let toolIter = 0;
   let summarisingEmitted = false;
+  let paused = false;
+  let partialSummary;
+  const taskForLoop = opts.resumeSession ? `[Resume: your tool-call budget has been refreshed with ${maxToolIters} new calls. Earlier "wrap up" / "finalize NOW" budget hints in this conversation referred to the previous window \u2014 they no longer apply. Continue the work you were given.]
+
+${opts.task}` : opts.task;
   try {
-    for await (const ev of childLoop.step(opts.task)) {
+    for await (const ev of childLoop.step(taskForLoop)) {
       sink?.current?.({ kind: "inner", runId, task: taskPreview, skillName, model, inner: ev });
       if (ev.role === "tool") {
         toolIter++;
@@ -10050,13 +10107,17 @@ ${budgetParagraph(maxToolIters)}`,
       if (ev.role === "error") {
         errorMessage = ev.error ?? "subagent error";
       }
+      if (ev.role === "paused") {
+        paused = true;
+        if (ev.partialSummary) partialSummary = ev.partialSummary;
+      }
     }
   } catch (err) {
     errorMessage = err.message;
   } finally {
     opts.parentSignal?.removeEventListener("abort", onParentAbort);
   }
-  if (!errorMessage && !final) {
+  if (!errorMessage && !final && !paused) {
     errorMessage = opts.parentSignal?.aborted ? "subagent aborted before producing an answer" : "subagent ended without producing an answer";
   }
   const elapsedMs = Date.now() - startedAt;
@@ -10090,7 +10151,10 @@ ${budgetParagraph(maxToolIters)}`,
     costUsd: costUsd2,
     model,
     skillName,
-    usage
+    usage,
+    paused: paused || void 0,
+    pausedSession: paused ? sessionName : void 0,
+    partialSummary: paused ? partialSummary : void 0
   };
 }
 function aggregateChildUsage(loop) {
@@ -10105,6 +10169,18 @@ function aggregateChildUsage(loop) {
   return agg;
 }
 function formatSubagentResult(r) {
+  if (r.paused) {
+    return JSON.stringify({
+      success: false,
+      paused: true,
+      resume_session: r.pausedSession,
+      tool_iters: r.toolIters,
+      elapsed_ms: r.elapsedMs,
+      cost_usd: r.costUsd,
+      partial_summary: r.partialSummary,
+      note: `Subagent reached its pause-every interval (${r.toolIters} tool calls) without producing a final answer. Read partial_summary above to see what was done / left / blocked, then decide: resume by calling spawn_subagent again with resume_session="${r.pausedSession}" (the task arg becomes a continuation nudge \u2014 e.g. "finish what you started"), or accept the partial work and proceed with what you already know.`
+    });
+  }
   if (!r.success) {
     return JSON.stringify({
       success: false,
@@ -10127,7 +10203,7 @@ function registerSubagentTool(parentRegistry, opts) {
   const baseSystem = opts.defaultSystem ?? SUBAGENT_BASE_SYSTEM;
   const defaultSystemBase = opts.projectRoot ? applyProjectMemory(baseSystem, opts.projectRoot) : baseSystem;
   const defaultModel = opts.defaultModel ?? DEFAULT_SUBAGENT_MODEL;
-  const maxToolIters = opts.maxToolIters ?? DEFAULT_MAX_ITERS;
+  const maxToolIters = opts.maxToolIters ?? DEFAULT_PAUSE_EVERY;
   const maxResultChars = opts.maxResultChars ?? DEFAULT_MAX_RESULT_CHARS2;
   const sink = opts.sink;
   let sessionSpawnCount = 0;
@@ -10135,17 +10211,17 @@ function registerSubagentTool(parentRegistry, opts) {
   parentRegistry.register({
     name: SUBAGENT_TOOL_NAME,
     parallelSafe: true,
-    description: "Spawn an isolated subagent to handle a self-contained subtask in a fresh context, returning only its final answer. **Prefer direct tools.** Spawn primarily for parallel fan-out (2+ independent investigations issued in one tool batch) or when the work would otherwise need >10 file reads/searches whose trail you don't need to keep. Single greps, 1-3 file cross-references, and 'keep my context clean for one question' are NOT good reasons to spawn \u2014 direct tools are cheaper and let you reference the evidence later. Each spawn pays a fresh prefix-cache miss plus a full child loop. The subagent inherits your tools but runs in its own isolated message log; only the final assistant message comes back. Keep tasks focused; the subagent has a stricter iter budget than you do.",
+    description: "Spawn an isolated subagent to handle a self-contained subtask in a fresh context, returning only its final answer. **Prefer direct tools.** Spawn primarily for parallel fan-out (2+ independent investigations issued in one tool batch) or when the work would otherwise need >10 file reads/searches whose trail you don't need to keep. Single greps, 1-3 file cross-references, and 'keep my context clean for one question' are NOT good reasons to spawn \u2014 direct tools are cheaper and let you reference the evidence later. Each fresh spawn pays a prefix-cache miss plus a full child loop. The subagent inherits your tools but runs in its own isolated message log; only the final assistant message comes back. **Pause/resume**: subagents yield back to you every `max_iters` tool calls. A paused result returns `{ paused: true, resume_session: \"...\" }` \u2014 you can either accept the partial state, or call spawn_subagent again with `resume_session` set to continue where it left off (cheap: the prior prefix is cached). Tasks expected to run much longer than 16 tool calls don't need a huge `max_iters` \u2014 just resume.",
     parameters: {
       type: "object",
       properties: {
         task: {
           type: "string",
-          description: "The subtask the subagent should perform. Be specific and self-contained \u2014 the subagent has none of your conversation context, only what you write here."
+          description: 'The subtask the subagent should perform. Be specific and self-contained \u2014 the subagent has none of your conversation context, only what you write here. When resuming via `resume_session`, this becomes a continuation nudge (e.g. "finish what you started" or a delta instruction).'
         },
         system: {
           type: "string",
-          description: "Optional override for the subagent's system prompt. The default tells it to stay focused and return a concise answer; override only when the subtask needs a specialized persona."
+          description: "Optional override for the subagent's system prompt. The default tells it to stay focused and return a concise answer; override only when the subtask needs a specialized persona. Ignored on resume \u2014 the prior session keeps its original system prompt for cache stability."
         },
         model: {
           type: "string",
@@ -10154,9 +10230,11 @@ function registerSubagentTool(parentRegistry, opts) {
         },
         max_iters: {
           type: "integer",
-          minimum: MIN_MAX_ITERS,
-          maximum: MAX_MAX_ITERS,
-          description: `Cap on the subagent's tool-call iterations. Default 16 (or the type's default when 'type' is set). Hard range: ${MIN_MAX_ITERS}-${MAX_MAX_ITERS}; out-of-range values are clamped to the nearest end.`
+          description: "How many tool calls the subagent runs before pausing back to you for a checkpoint. Default 16. This is checkpoint cadence, not a budget \u2014 work continues across pauses via `resume_session`. Pick what feels natural for the granularity of decisions you want to make: small (4-8) when you want frequent control, larger (32-64) when the subagent should mostly run autonomously."
+        },
+        resume_session: {
+          type: "string",
+          description: "Provide the `resume_session` value returned by a previous paused spawn to continue that subagent. When set, prior messages are loaded from disk and the original system prompt is reused (cache-friendly). `task` becomes a continuation nudge."
         },
         type: {
           type: "string",
@@ -10178,7 +10256,8 @@ function registerSubagentTool(parentRegistry, opts) {
       const system = typeof args.system === "string" && args.system.trim().length > 0 ? args.system.trim() : typeSpec?.system ?? `${defaultSystemBase}
 
 ${escalationContract(model)}`;
-      const callerIters = clampMaxIters(args.max_iters);
+      const callerIters = parseMaxIters(args.max_iters);
+      const resumeSession = typeof args.resume_session === "string" && args.resume_session.trim().length > 0 ? args.resume_session.trim() : void 0;
       const result = await spawnSubagent({
         client: opts.client,
         parentRegistry,
@@ -10188,7 +10267,8 @@ ${escalationContract(model)}`;
         maxToolIters: callerIters ?? typeSpec?.maxToolIters ?? maxToolIters,
         maxResultChars,
         sink,
-        parentSignal: ctx?.signal
+        parentSignal: ctx?.signal,
+        resumeSession
       });
       sessionSpawnCount++;
       sessionSpawnTokens += result.usage.totalTokens;
@@ -10200,12 +10280,10 @@ ${hint}` : formatted;
   });
   return parentRegistry;
 }
-function clampMaxIters(raw) {
+function parseMaxIters(raw) {
   if (typeof raw !== "number" || !Number.isFinite(raw)) return void 0;
   const n = Math.floor(raw);
-  if (n < MIN_MAX_ITERS) return MIN_MAX_ITERS;
-  if (n > MAX_MAX_ITERS) return MAX_MAX_ITERS;
-  return n;
+  return n >= 1 ? n : void 0;
 }
 function forkRegistryExcluding(parent, exclude) {
   const child = new ToolRegistry();
@@ -10607,6 +10685,7 @@ import * as pathMod8 from "path";
 // src/tools/shell-chain.ts
 import { spawn as spawn3 } from "child_process";
 import { closeSync, openSync } from "fs";
+import { devNull } from "os";
 import * as pathMod7 from "path";
 var UnsupportedSyntaxError = class extends Error {
   constructor(detail) {
@@ -10866,6 +10945,12 @@ async function runChain(chain, opts) {
 [\u2026 truncated ${output.length - opts.maxOutputChars} chars \u2026]` : output;
   return { exitCode: lastExit, output: truncated, timedOut };
 }
+function isNullDeviceAlias(target) {
+  const lower = target.toLowerCase();
+  if (lower === "/dev/null") return true;
+  if (process.platform === "win32" && lower === "nul") return true;
+  return false;
+}
 function openRedirects(redirects, cwd) {
   let stdinFd = null;
   let stdoutFd = null;
@@ -10874,7 +10959,7 @@ function openRedirects(redirects, cwd) {
   let bothFd = null;
   const toClose = [];
   const open = (target, flags) => {
-    const resolved = pathMod7.resolve(cwd, target);
+    const resolved = isNullDeviceAlias(target) ? devNull : pathMod7.resolve(cwd, target);
     const fd = openSync(resolved, flags);
     toClose.push(fd);
     return fd;