@nexrall/code-core 1.4.25 → 1.4.27

package/dist/agent/loop.js

@@ -33,7 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERIFY_CMD_RE = exports.WRITE_TOOL_NAMES = exports.ToolNotAllowedError = void 0;
+exports.VERIFY_CMD_RE = exports.WRITE_TOOL_NAMES = exports.ToolNotAllowedError = exports._stallLimits = void 0;
+exports.errorRoundSignature = errorRoundSignature;
 exports.resolveMaxIterations = resolveMaxIterations;
 exports.createLimiter = createLimiter;
 exports.extractSubTaskText = extractSubTaskText;
@@ -59,6 +60,8 @@ const executor_1 = require("../tools/executor");
 const agentTypes_1 = require("./agentTypes");
 const skills_1 = require("./skills");
 const rules_1 = require("../permissions/rules");
+const planMode_1 = require("./planMode");
+const agentRegistry_1 = require("./agentRegistry");
 const sandbox_1 = require("../tools/sandbox");
 const index_1 = require("../plugins/index");
 const testIntegrity_1 = require("./testIntegrity");
@@ -187,6 +190,30 @@ const DEFAULT_MAX_ITERATIONS = 500;
 const MAX_ITERATIONS_CEILING = 2000; // default auto-continue backstop (no explicit opt-in)
 const HARD_ITERATIONS_CAP = 100000; // absolute safety cap — even explicit opt-in can't exceed this
 const STALL_LIMIT = 8; // consecutive all-failed tool rounds → give up (runaway guard)
+// Consecutive rounds producing the IDENTICAL error(s) → give up, even if other calls in
+// those rounds succeeded. Higher than STALL_LIMIT because a repeat is weaker evidence of
+// being stuck than a total failure: legitimately retrying one failing command a few times
+// while making progress elsewhere is normal, twelve times is not.
+const REPEAT_STALL_LIMIT = 12;
+/**
+ * Fingerprint one round's tool failures, for the repeated-failure runaway guard.
+ *
+ * Exported (with the limits) purely as a test seam: the guard's whole value is in the
+ * edge cases — that a DIFFERENT error each round must NOT trip it, that call order
+ * within a round is irrelevant, that a long error body doesn't make every occurrence
+ * look unique — and none of that is reachable without driving a live model loop.
+ *
+ * Sorted so parallel tool calls completing in a different order still compare equal;
+ * truncated because errors often embed a varying path or timestamp late in the string.
+ */
+function errorRoundSignature(errored) {
+    return errored
+        .map(({ name, error }) => `${name}:${String(error).slice(0, 200)}`)
+        .sort()
+        .join('|');
+}
+/** Runaway-guard limits, exposed for tests. */
+exports._stallLimits = { STALL_LIMIT, REPEAT_STALL_LIMIT };
 // Resolve the soft iteration budget. Precedence:
 //   options.maxIterations  →  env NEXRALL_MAX_ITERATIONS  →  settings.maxIterations  →  default
 //
@@ -541,7 +568,49 @@ async function runSubTask(input, options, agentTypes) {
     // ENOENT stats — against a sub-agent that is about to run for seconds to
     // minutes. Note runAgentLoop re-reads for the sub-agent anyway, so the old
     // behaviour was already inconsistent: fresh for the child, stale for the lookup.
-    const requestedType = typeof input.subagent_type === 'string' ? input.subagent_type : '';
+    // ── Resolve a resume target ─────────────────────────────────────────────────
+    //
+    // `resume_agent_id` continues a previous sub-agent. The stored transcript
+    // carries the agent's NAME, and that name — not the one the model passed — is
+    // what gets authorised below.
+    //
+    // This matters because an id would otherwise be a permanent capability: deny
+    // `task(explorer)` today and a model holding yesterday's explorer id could
+    // still resume it, with the deny rule looking like it was applied. Re-deriving
+    // the name from storage also stops a mismatched `subagent_type` from being
+    // used to launder a denied agent under an allowed name.
+    const resumeId = typeof input.resume_agent_id === 'string' ? input.resume_agent_id.trim() : '';
+    const resumed = resumeId ? (0, agentRegistry_1.getAgent)(resumeId) : undefined;
+    if (resumeId && !resumed) {
+        return {
+            error: `No resumable sub-agent with id "${resumeId}". Ids live only for the current session and the ` +
+                'oldest are dropped when too many accumulate, so this one has expired or never existed. ' +
+                'Start a fresh sub-task with a self-contained prompt instead.',
+        };
+    }
+    const requestedType = resumed
+        ? (resumed.agentName ?? '')
+        : (typeof input.subagent_type === 'string' ? input.subagent_type : '');
+    // ── Enforce `deny: ["task(<name>)"]` ─────────────────────────────────────────
+    //
+    // This is the load-bearing check; filtering the catalogue in runAgentLoop only
+    // stops the agent being SUGGESTED. It must run BEFORE resolution, because the
+    // reload-on-miss path below deliberately re-reads from disk UNFILTERED — a
+    // denied agent is absent from the snapshot, would therefore "miss", and would
+    // then be found by that reload and run. Denying by omission is not denying.
+    //
+    // Phrased as a policy refusal, not "unknown type": the model must not respond
+    // by trying to create the agent file it thinks is missing.
+    if (requestedType) {
+        const decision = (0, rules_1.evaluatePermission)((0, rules_1.loadSettings)(options.workDir).permissions, 'task', { subagent_type: requestedType }, options.workDir);
+        if (decision === 'deny') {
+            return {
+                error: `The sub-agent "${requestedType}" is disabled by a permission rule in this project ` +
+                    `(permissions.deny in settings.json). This is a deliberate policy choice, not a missing file — ` +
+                    'do not create it and do not retry. Do the work yourself, or use a different sub-agent.',
+            };
+        }
+    }
     let agent = (0, agentTypes_1.findAgentType)(agentTypes, requestedType);
     let knownTypes = agentTypes;
     if (requestedType && !agent) {
@@ -584,9 +653,16 @@ async function runSubTask(input, options, agentTypes) {
         }
         return options.requestPermission(req);
     };
-    const subMessages = [
-        { role: 'user', content: [{ type: 'text', text: prompt }] },
-    ];
+    // ── Resume: continue a previous sub-agent instead of starting cold ──────────
+    //
+    // The new prompt is appended as another user turn to the stored transcript, so
+    // the agent keeps every file it read and every conclusion it reached. Without
+    // this, "now also check the auth path" means re-describing the entire job and
+    // re-reading everything — the most common and most expensive kind of waste in
+    // a delegated workflow.
+    const subMessages = resumed
+        ? [...resumed.messages, { role: 'user', content: [{ type: 'text', text: prompt }] }]
+        : [{ role: 'user', content: [{ type: 'text', text: prompt }] }];
     // A dedicated abort signal for this sub-agent, distinct from the parent's own
     // options.abortSignal (user hit Ctrl+C). Set to true either when the parent
     // aborts OR when the stall timeout below fires, whichever happens first —
@@ -609,6 +685,9 @@ async function runSubTask(input, options, agentTypes) {
             _agentScope: `sub_${++_subTaskCounter}`, // isolated todo store per sub-agent
             editorContext: null, // fresh isolated context for sub-agent
             model: agent?.model ?? options.model,
+            // Plan mode is inherited, never relaxed. If the main agent could spawn a
+            // sub-agent that writes, the lock would be one `task` call from useless.
+            planMode: options.planMode,
             nexrallMd: subNexrallMd,
             abortSignal: subAbort,
             requestPermission: gatedPermission,
@@ -671,7 +750,23 @@ async function runSubTask(input, options, agentTypes) {
         }
         // Normal completion: the final assistant message is the sub-agent's answer.
         const text = capSubTaskText(extractSubTaskText(result, true));
-        return { output: text || '(sub-task completed with no text output)' };
+        // Store the transcript so a follow-up can continue this agent rather than
+        // re-running it from scratch, and tell the parent the id.
+        //
+        // Only on NORMAL completion. A timed-out or failed run is deliberately not
+        // resumable: its transcript ends mid-thought, often mid-tool-call, and
+        // resuming from that state invites the model to build on work whose status
+        // it cannot determine. Those paths already salvage their partial output as
+        // TEXT, which is the safe way to carry that information forward.
+        const agentId = resumed
+            ? ((0, agentRegistry_1.updateAgent)(resumed.id, result), resumed.id)
+            : (0, agentRegistry_1.rememberAgent)(agent?.name ?? null, (typeof input.description === 'string' && input.description.trim()) || prompt.slice(0, 80), result);
+        const body = text || '(sub-task completed with no text output)';
+        return {
+            output: `${body}\n\n[resumable: this sub-agent is "${agentId}". To ask IT a follow-up — keeping ` +
+                'everything it already read and concluded — call task again with resume_agent_id="' + agentId +
+                '" instead of writing a new prompt from scratch.]',
+        };
     }
     catch (err) {
         // Same salvage rule as the timeout path above, for the other way a sub-agent
@@ -760,6 +855,26 @@ function compactionThresholds() {
 // so we require at least this many bytes reclaimed before accepting a prune.
 const PRUNE_MIN_RECLAIM_BYTES = 256 * 1024; // 256 KB
 const COMPACT_KEEP_MIN = 6; // always keep at least the last N messages verbatim
+/**
+ * Bytes a compaction must reclaim to count as productive.
+ *
+ * Deliberately much smaller than PRUNE_MIN_RECLAIM_BYTES: a prune declines when the
+ * gain isn't worth busting the prompt cache, whereas by the time we are summarising
+ * we are already committed to rewriting the prefix — the only question is whether the
+ * summariser is making ANY headway. 32 KB is small enough that a genuinely useful
+ * compaction always clears it, large enough that shuffling a few bytes doesn't.
+ */
+const COMPACT_MIN_RECLAIM_BYTES = 32 * 1024; // 32 KB
+/**
+ * Consecutive non-productive compaction attempts before auto-compaction is switched
+ * off for the rest of the run.
+ *
+ * 3 rather than 1 because the failure is often transient — a summariser stream that
+ * blipped will usually succeed on the next turn, and giving up instantly would lose
+ * the safety net for a whole long session over one network hiccup. 3 also bounds the
+ * wasted spend: at most three summariser calls, not hundreds.
+ */
+const COMPACT_MAX_FAILURES = 3;
 // Byte-level safety net, independent of the token estimate.
 //
 // Tool-heavy sessions on large codebases accumulate many tool_result blocks
@@ -943,7 +1058,7 @@ function transcriptOf(messages) {
 const LEDGER_MAX_FILES = 60; // cap the file list so the preamble can't balloon
 const LEDGER_MAX_NOTES = 20; // cap verification/among notes
 function createLedger() {
-    return { filesTouched: new Map(), verifications: [], testIntegrity: [], epoch: 0 };
+    return { filesTouched: new Map(), filesTouchedTotal: 0, verifications: [], testIntegrity: [], testIntegrityTotal: 0, epoch: 0 };
 }
 /** Record one tool call's effect on the ledger (deterministic, no model call). */
 function ledgerRecord(ledger, toolName, input, ok, output, exitCode) {
@@ -956,7 +1071,32 @@ function ledgerRecord(ledger, toolName, input, ok, output, exitCode) {
         const p = typeof input?.path === 'string' ? input.path : undefined;
         if (p) {
             const prev = ledger.filesTouched.get(p);
+            if (!prev)
+                ledger.filesTouchedTotal++;
+            // DELETE before SET, so a re-touched path moves to the BACK of the insertion
+            // order. `Map.set` on an existing key keeps its ORIGINAL slot, which quietly
+            // broke the eviction policy below: a file edited hundreds of times over a long
+            // session kept the position of its FIRST edit, so it aged out like a file nobody
+            // had looked at since — and on the next edit it was re-inserted as "new", double-
+            // counting filesTouchedTotal (which is documented as DISTINCT paths). Making the
+            // Map a true LRU-by-touch is what lets the `key !== p` guard below mean anything.
+            ledger.filesTouched.delete(p);
             ledger.filesTouched.set(p, { tool: toolName, edits: (prev?.edits ?? 0) + 1 });
+            // Bound the Map itself, not just its rendering. LEDGER_MAX_FILES caps how many
+            // paths the preamble PRINTS (see ledgerSummary's slice), but the Map was only ever
+            // written to — so a multi-hour run touching thousands of files grew it without
+            // limit, and it is deliberately retained across every compaction. Evict the
+            // least-recently-touched entries once we hold well beyond what can ever be
+            // displayed. Hysteresis (evict down to 2× only once we exceed 4×) keeps this an
+            // occasional bulk sweep instead of a delete on every single write.
+            if (ledger.filesTouched.size > LEDGER_MAX_FILES * 4) {
+                for (const key of ledger.filesTouched.keys()) {
+                    if (ledger.filesTouched.size <= LEDGER_MAX_FILES * 2)
+                        break;
+                    if (key !== p)
+                        ledger.filesTouched.delete(key);
+                }
+            }
         }
         // Reward-hacking guard: if this write WEAKENED a test file, record it so the
         // signal survives compaction and can be surfaced before the agent finishes.
@@ -976,6 +1116,7 @@ function ledgerRecord(ledger, toolName, input, ok, output, exitCode) {
         if (reasons.length && p) {
             for (const reason of reasons) {
                 ledger.testIntegrity.push({ path: p, reason });
+                ledger.testIntegrityTotal++;
             }
             if (ledger.testIntegrity.length > LEDGER_MAX_NOTES * 2) {
                 ledger.testIntegrity.splice(0, ledger.testIntegrity.length - LEDGER_MAX_NOTES);
@@ -1008,8 +1149,11 @@ function ledgerSummary(ledger) {
     const lines = [];
     if (ledger.filesTouched.size) {
         const files = [...ledger.filesTouched.entries()];
-        const shown = files.slice(0, LEDGER_MAX_FILES);
-        lines.push(`FILES CHANGED THIS SESSION (${ledger.filesTouched.size}):`);
+        // The TAIL, not the head: the Map is ordered least-recently-touched first, so
+        // slicing from the front showed the OLDEST files and reliably omitted the ones the
+        // agent was working on right now — the opposite of what this preamble is for.
+        const shown = files.slice(-LEDGER_MAX_FILES);
+        lines.push(`FILES CHANGED THIS SESSION (${ledger.filesTouchedTotal || ledger.filesTouched.size}):`);
         for (const [p, meta] of shown) {
             lines.push(`  • ${p}  (${meta.tool}${meta.edits > 1 ? ` ×${meta.edits}` : ''})`);
         }
@@ -1342,17 +1486,36 @@ async function runAgentLoop(initialMessages, options) {
     const hooks = loadHooks(options.workDir);
     const depth = options._depth ?? 0;
     const agentScope = options._agentScope ?? 'root';
+    // Settings are read before the agent catalogue because a `deny` rule can
+    // switch a sub-agent off, and an agent that may not run must not be
+    // advertised (see below).
+    const settings = (0, rules_1.loadSettings)(options.workDir);
     // Discover custom sub-agent types. Only the top-level agent is told the
     // catalogue (sub-agents can't spawn further), but every level resolves types.
-    const agentTypes = (0, agentTypes_1.loadAgentTypes)(options.workDir);
+    //
+    // Denied agents are filtered OUT of the catalogue rather than left in it to be
+    // refused on dispatch. Listing an agent you have forbidden trains the model to
+    // spend a tool call discovering the refusal, and "available types: …" on the
+    // error path would name it again. Enforcement still happens at dispatch
+    // (runSubTask) — this is the cosmetic half; that is the load-bearing half.
+    const agentTypes = (0, agentTypes_1.loadAgentTypes)(options.workDir).filter((t) => (0, rules_1.evaluatePermission)(settings.permissions, 'task', { subagent_type: t.name }, options.workDir) !== 'deny');
     const agentsCatalogue = depth === 0 ? (0, agentTypes_1.summariseAgents)(agentTypes) : '';
     // Skills catalogue — unlike agentsCatalogue, available at every depth: a skill is
     // just a reusable prompt template (via use_skill), not another spawn point, so
     // sub-agents benefit from the same playbooks without the recursion concerns that
     // gate agentsCatalogue to the top level.
     const skillsCatalogue = (0, skills_1.summariseSkills)((0, skills_1.loadSkills)(options.workDir));
+    // Plan mode instructions ride the project-instructions channel, which is
+    // authoritative in the system prompt. Prepended rather than appended: the
+    // lock has to be read before the project conventions it overrides.
+    //
+    // Telling the model is not the enforcement (checkPlanMode at the call site is)
+    // — it exists so the model spends the turn planning instead of discovering the
+    // lock one refused tool call at a time.
+    const planAwareNexrallMd = options.planMode
+        ? planMode_1.PLAN_MODE_INSTRUCTIONS + (options.nexrallMd ? `\n\n---\n\n${options.nexrallMd}` : '')
+        : options.nexrallMd;
     // Optional OS-level bash sandbox (opt-in via settings.json "sandbox").
-    const settings = (0, rules_1.loadSettings)(options.workDir);
     const sandboxCfg = (0, sandbox_1.parseSandboxConfig)(settings.raw.sandbox) ?? undefined;
     // Soft iteration budget + optional auto-continue past it (see resolvers above).
     const maxIterations = resolveMaxIterations(options.maxIterations, settings.raw);
@@ -1383,6 +1546,12 @@ async function runAgentLoop(initialMessages, options) {
     let completedRounds = 0;
     let stalledOut = false; // tripped the runaway guard (all-failed rounds)
     let consecutiveErrorRounds = 0; // rounds where every tool call errored
+    // Repeated-identical-failure guard: see the runaway guards below. Tracked
+    // separately from consecutiveErrorRounds because a round can contain a succeeding
+    // call and still be part of a livelock.
+    let repeatedErrorRounds = 0;
+    let lastErrorSignature = '';
+    let stalledRepeatError = null;
     let budget = maxIterations; // extended by auto-continue, capped at hardCap
     let iteration = 0;
     // ─── Verification nudge (GAP D) ───────────────────────────────────────────────
@@ -1409,6 +1578,31 @@ async function runAgentLoop(initialMessages, options) {
     let claimEvidenceNudged = false;
     // GAP E — deterministic progress ledger, preserved verbatim across compactions.
     const ledger = createLedger();
+    // ─── Auto-compact circuit breaker ─────────────────────────────────────────────
+    //
+    // The in-loop compaction trigger below re-derives its pressure from the CURRENT
+    // body on every iteration. That is correct, but it means a compaction which does
+    // not shrink anything leaves the trigger condition still true — so the next
+    // iteration pays for another summariser call over the same (up to ~600KB)
+    // transcript, and so on for the rest of the run. Two ways that happens:
+    //
+    //   • autoCompactMessages returns false (summariser stream threw, or came back
+    //     empty). Nothing was replaced, so the pressure is unchanged.
+    //   • It returns true but cannot get under MAX_BODY_BYTES, because the messages
+    //     it must retain (COMPACT_KEEP_MIN) are themselves huge. `lastPromptTokens = 0`
+    //     suppresses only the TOKEN trigger; the BYTE trigger fires again immediately.
+    //
+    // Both are invisible to the user (the success notice only prints when `did`), so
+    // the symptom is a long run that silently gets slower and more expensive. Count
+    // consecutive non-productive attempts and stop trying after a few — losing
+    // compaction degrades gracefully (the turn may still fit, and the prune pass
+    // still runs), whereas an unbounded retry loop does not.
+    //
+    // The resume-time compactor already had exactly these guards
+    // (compactMessagesForResume: a bounded loop plus `if (!did) break`); this brings
+    // the in-loop path in line with it.
+    let compactFailures = 0;
+    let compactDisabled = false;
     try {
         for (; iteration < budget; iteration++) {
             if (options.abortSignal?.aborted)
@@ -1457,10 +1651,17 @@ async function runAgentLoop(initialMessages, options) {
                     (options.onNotice ?? options.onText)(`\u267b\ufe0f Trimmed ~${(reclaimed / (1024 * 1024)).toFixed(1)}MB of already-processed tool output to keep this chat cheap to continue.`);
                 }
             }
-            if (autoCompact && !compacting && (tokenPressure || bytePressure) && messages.length > COMPACT_KEEP_MIN + 2) {
+            if (autoCompact && !compactDisabled && !compacting && (tokenPressure || bytePressure) && messages.length > COMPACT_KEEP_MIN + 2) {
                 compacting = true;
                 try {
+                    // Measured BEFORE, so "did it actually help?" is a fact about bytes rather
+                    // than a claim from the compactor. A compaction that returns true but
+                    // reclaims nothing is a failure for our purposes — it leaves the trigger
+                    // armed for the next iteration, which is precisely the runaway.
+                    const bytesBefore = estimateBodyBytes(messages);
                     const did = await autoCompactMessages(messages, options, ledger);
+                    const bytesAfter = did ? estimateBodyBytes(messages) : bytesBefore;
+                    const reclaimed = bytesBefore - bytesAfter;
                     if (did) {
                         lastPromptTokens = 0; // stale — next usage event refreshes it
                         const reason = bytePressure
@@ -1469,6 +1670,24 @@ async function runAgentLoop(initialMessages, options) {
                         // Same reasoning as above: this is a system notice about housekeeping,
                         // not part of the model's answer — keep it out of the text bubble.
                         (options.onNotice ?? options.onText)(`\u267b\ufe0f Auto-compacted earlier conversation to stay within the ${reason}.`);
+                        // Refresh local pressure so the rest of THIS iteration sees the new size.
+                        bodyBytes = bytesAfter;
+                        bytePressure = bodyBytes > MAX_BODY_BYTES;
+                    }
+                    // Productive == it shrank the body meaningfully. A successful-but-useless
+                    // compaction counts as a failure, otherwise the "cannot get under the byte
+                    // cap" case would never trip the breaker.
+                    if (did && reclaimed >= COMPACT_MIN_RECLAIM_BYTES) {
+                        compactFailures = 0;
+                    }
+                    else if (++compactFailures >= COMPACT_MAX_FAILURES) {
+                        compactDisabled = true;
+                        // Surfaced ONCE. The user needs to know the automatic safety net is off
+                        // (so a context-window error later isn't a total surprise) and what to do
+                        // about it, but repeating this every iteration would be its own spam.
+                        (options.onNotice ?? options.onText)(`\u26a0\ufe0f Auto-compaction isn't reducing this conversation any further, so it's been switched off ` +
+                            `for the rest of this run to avoid repeated summarising. If the context fills up, start a fresh ` +
+                            `chat or run /compact manually.`);
                     }
                 }
                 finally {
@@ -1569,7 +1788,7 @@ async function runAgentLoop(initialMessages, options) {
                     effort: options.effort,
                     env: options.env,
                     editorContext: options.editorContext,
-                    nexrallMd: options.nexrallMd,
+                    nexrallMd: planAwareNexrallMd,
                     clientType: options.clientType,
                     abortSignal: options.abortSignal,
                     extraTools: options.mcpManager?.getAnthropicTools(),
@@ -1683,9 +1902,19 @@ async function runAgentLoop(initialMessages, options) {
                 // and require the agent to either justify each change (legit refactor) or
                 // revert it and fix the real code. Deterministic — the signal comes from
                 // diff structure, not model self-report, so it can't be gamed away.
-                if (ledger.testIntegrity.length > testIntegrityNudgedCount) {
-                    const fresh = ledger.testIntegrity.slice(testIntegrityNudgedCount);
-                    testIntegrityNudgedCount = ledger.testIntegrity.length;
+                //
+                // Compared against testIntegrityTotal, NOT testIntegrity.length: the array is a
+                // bounded window that gets trimmed, so once a long session passed ~40 findings
+                // its length stopped growing and could even fall BELOW the already-nudged count,
+                // permanently wedging this condition false and disabling the guard for the rest
+                // of the run. The total only ever increases.
+                if (ledger.testIntegrityTotal > testIntegrityNudgedCount) {
+                    // How many are genuinely new, clamped to what the window still holds — the
+                    // trimmed-away ones are unrecoverable, and reporting the tail we DO have is
+                    // strictly better than reporting nothing.
+                    const newCount = Math.min(ledger.testIntegrityTotal - testIntegrityNudgedCount, ledger.testIntegrity.length);
+                    const fresh = ledger.testIntegrity.slice(ledger.testIntegrity.length - newCount);
+                    testIntegrityNudgedCount = ledger.testIntegrityTotal;
                     const bullet = fresh.map((t) => `  • ${t.path}: ${t.reason}`).join('\n');
                     messages.push({
                         role: 'user',
@@ -1794,6 +2023,21 @@ async function runAgentLoop(initialMessages, options) {
                     options.onToolResult(name, result);
                     return { block: { ...block, id }, result };
                 }
+                // ── Plan mode: a session-wide read-only lock ────────────────────────
+                //
+                // Checked BEFORE requestPermission on purpose. Routing it through the
+                // permission prompt would ask the user to approve something that is
+                // not theirs to approve in that moment, and a model told "denied by
+                // user" reliably re-asks. This refusal instead says plainly that no
+                // answer here can unlock it.
+                if (options.planMode) {
+                    const refusal = (0, planMode_1.checkPlanMode)(name, input);
+                    if (refusal) {
+                        result = { error: refusal.message };
+                        options.onToolResult(name, result);
+                        return { block: { ...block, id }, result };
+                    }
+                }
                 // Request permission
                 const description = humanDescription(name, input);
                 let permitted;
@@ -1969,16 +2213,46 @@ async function runAgentLoop(initialMessages, options) {
             // tool_result user turn). Let the caller checkpoint progress so a crash
             // mid-run loses only the in-flight step, not the whole session.
             options.onProgress?.(messages);
-            // Runaway guard: if every tool call in this round failed, count it. Enough
-            // consecutive all-failed rounds (e.g. a command that always errors, or the
-            // user denying every permission) means we're stuck — stop instead of
-            // burning the whole budget spinning.
-            const allErrored = toolResults.length > 0 && toolResults.every(({ result }) => result.error !== undefined);
+            // ── Runaway guards ────────────────────────────────────────────────────────
+            //
+            // TWO independent counters, because "stuck" has two shapes and the original
+            // all-failed test only caught the first.
+            //
+            //   1. TOTAL failure: every call in the round errored (a command that always
+            //      errors, the user denying every permission). Unambiguous.
+            //
+            //   2. REPEATED failure: the SAME error keeps coming back, round after round,
+            //      even though other calls in those rounds succeed. This is the livelock the
+            //      `.every()` test missed entirely — one trivially-succeeding sibling (say a
+            //      `read_file` alongside an `edit_file` that fails identically every time)
+            //      reset the counter to 0 forever, so a genuine loop burned the full
+            //      2000-iteration ceiling instead of stopping at 8. That is the expensive,
+            //      user-visible "it just spun for an hour" failure.
+            //
+            // Keyed on tool + error text so a DIFFERENT error each round (real progress
+            // through a chain of distinct problems) does not trip it.
+            const errored = toolResults.filter(({ result }) => result.error !== undefined);
+            const allErrored = toolResults.length > 0 && errored.length === toolResults.length;
             consecutiveErrorRounds = allErrored ? consecutiveErrorRounds + 1 : 0;
             if (consecutiveErrorRounds >= STALL_LIMIT) {
                 stalledOut = true;
                 break;
             }
+            // Signature of this round's failures, order-independent and truncated so a long
+            // error body (or a path echoed inside it) doesn't make every occurrence unique.
+            const errSignature = errorRoundSignature(errored.map(({ block, result }) => ({ name: block.name, error: String(result.error) })));
+            if (errSignature && errSignature === lastErrorSignature) {
+                repeatedErrorRounds++;
+            }
+            else {
+                repeatedErrorRounds = 0;
+                lastErrorSignature = errSignature;
+            }
+            if (repeatedErrorRounds >= REPEAT_STALL_LIMIT) {
+                stalledOut = true;
+                stalledRepeatError = errored[0] ? String(errored[0].result.error).slice(0, 300) : null;
+                break;
+            }
             // Auto-continue: about to exhaust the current budget but the model is still
             // calling tools (task unfinished) and we're under the ceiling → extend the
             // budget by another segment and keep going, so the agent finishes on its own
@@ -1994,12 +2268,19 @@ async function runAgentLoop(initialMessages, options) {
         // long run never just goes silent. History ends on a tool_result turn, so
         // "continue" resumes exactly where it left off.
         if (!options.abortSignal?.aborted && !completedCleanly) {
+            // Routed through onNotice (falling back to onText) like every other housekeeping
+            // message in this file — these are statements from the harness, not from the model,
+            // and splicing them into the assistant's own bubble reads as if it said them.
             if (stalledOut) {
-                options.onText(`\n🛑 Stopped: the last ${STALL_LIMIT} tool rounds all failed, so the agent looked stuck. ` +
-                    `Fix the underlying error (or grant the needed permission) and send "continue".\n`);
+                (options.onNotice ?? options.onText)(stalledRepeatError
+                    ? `\n🛑 Stopped: the same tool error repeated ${REPEAT_STALL_LIMIT} rounds in a row, so the agent ` +
+                        `was looping without making progress. The recurring error was:\n${stalledRepeatError}\n` +
+                        `Fix that underlying cause (or grant the needed permission) and send "continue".\n`
+                    : `\n🛑 Stopped: the last ${STALL_LIMIT} tool rounds all failed, so the agent looked stuck. ` +
+                        `Fix the underlying error (or grant the needed permission) and send "continue".\n`);
             }
             else if (iteration >= budget) {
-                options.onText(`\n⏸️ Stopped at the ${budget}-step safety limit — the task may be incomplete. ` +
+                (options.onNotice ?? options.onText)(`\n⏸️ Stopped at the ${budget}-step safety limit — the task may be incomplete. ` +
                     `Send "continue" to resume, or raise the limit via "maxIterations" in .nexrall/settings.json ` +
                     `(or the NEXRALL_MAX_ITERATIONS env var). Auto-continue can be disabled with "autoContinue": false.\n`);
             }

package/dist/agent/planMode.d.ts

@@ -0,0 +1,20 @@
+export interface PlanModeRefusal {
+    /** Machine-readable reason, for tests and telemetry. */
+    reason: 'mutating-tool' | 'bash-not-read-only';
+    /** Message shown to the MODEL. Must stop it retrying or asking for approval. */
+    message: string;
+}
+/**
+ * Is this bash command provably read-only?
+ *
+ * "Provably" is doing real work: unknown verbs are refused, not guessed at.
+ */
+export declare function isReadOnlyCommand(command: string): boolean;
+/**
+ * Should this tool call be refused because the session is in plan mode?
+ * Returns null when the call is allowed.
+ */
+export declare function checkPlanMode(tool: string, input: Record<string, unknown>): PlanModeRefusal | null;
+/** Text appended to the system prompt while plan mode is active. */
+export declare const PLAN_MODE_INSTRUCTIONS: string;
+//# sourceMappingURL=planMode.d.ts.map

package/dist/agent/planMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planMode.d.ts","sourceRoot":"","sources":["../../src/agent/planMode.ts"],"names":[],"mappings":"AAwHA,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,MAAM,EAAE,eAAe,GAAG,oBAAoB,CAAC;IAC/C,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAgE1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,eAAe,GAAG,IAAI,CAoCxB;AAED,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,QAqBvB,CAAC"}