@nexrall/code-core 1.4.66 → 1.4.68

package/dist/agent/iterationPolicy.d.ts

@@ -0,0 +1,121 @@
+import type { ToolResult } from '../types';
+import { type AgentMemoryScope } from './agentTypes';
+export declare const MAX_ITERATIONS_CEILING = 2000;
+export declare const STALL_LIMIT = 8;
+export declare const REPEAT_STALL_LIMIT = 12;
+export declare const EMPTY_TURN_RETRY_LIMIT = 3;
+/** Backoff for the Nth (0-based) empty-turn retry. Pure, so the schedule is testable. */
+export declare function emptyTurnBackoffMs(attempt: number): number;
+/**
+ * Should an empty assistant turn be retried automatically, rather than surfaced?
+ *
+ * Split out as a pure function because the two "empty" causes look IDENTICAL at the
+ * call site (both are `content.length === 0`) and telling them apart is the entire
+ * point — the previous bug in this area was treating a deterministic truncation as a
+ * transient hiccup and advising a retry that reproduced it verbatim.
+ *
+ *   • `max_tokens` → the model burned its whole output budget on reasoning and was CUT
+ *     OFF. Retrying re-runs the same prompt with the same budget and the same reasoning
+ *     behaviour, so it fails the same way while billing again. Never retried; the user
+ *     is told to lower effort or split the task (stopReasonNotice 'output-limit').
+ *   • anything else → a genuinely transient empty turn. Retried, up to the limit.
+ *
+ * The attempt cap matters as much as the classification: a model that has decided to
+ * return nothing (e.g. a prompt it refuses to continue) would otherwise loop forever
+ * on a paid endpoint. After the cap we fall back to the old visible notice.
+ */
+export declare function shouldRetryEmptyTurn(stopReason: string | null | undefined, attemptsSoFar: number): boolean;
+/** Empty-turn retry limits, exposed for tests. */
+export declare const _emptyTurnRetry: {
+    EMPTY_TURN_RETRY_LIMIT: number;
+    EMPTY_TURN_RETRY_BASE_MS: number;
+};
+/**
+ * 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.
+ */
+export declare function errorRoundSignature(errored: Array<{
+    name: string;
+    error: string;
+}>): string;
+/** Runaway-guard limits, exposed for tests. */
+export declare const _stallLimits: {
+    STALL_LIMIT: number;
+    REPEAT_STALL_LIMIT: number;
+};
+/**
+ * The single tool granted by a `memory:` frontmatter scope.
+ *
+ * Named distinctly from `memory_write` on purpose: they write to DIFFERENT stores, and
+ * a model that saw one name for both would reasonably assume its notes were visible to
+ * the main agent. They are not.
+ */
+export declare const AGENT_MEMORY_TOOL = "agent_memory_write";
+/**
+ * Schema advertised to the model, only for a sub-agent with a declared memory scope.
+ *
+ * The description does the load-bearing work of keeping the two stores apart in the
+ * model's head: it must not believe these notes reach the user or the main agent.
+ */
+export declare const AGENT_MEMORY_TOOL_SCHEMA: {
+    readonly name: "agent_memory_write";
+    readonly description: string;
+    readonly input_schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+                readonly description: "The single fact to remember, 1-2 sentences.";
+            };
+        };
+        readonly required: readonly ["content"];
+    };
+};
+/** Identifies whose notes an agent_memory_write call may touch. */
+export interface AgentMemoryBinding {
+    agentName: string;
+    scope: AgentMemoryScope;
+}
+/**
+ * Execute an `agent_memory_write` call.
+ *
+ * Pure-ish and exported so the refusal paths are testable without spawning a real
+ * sub-agent: the binding is data, so "no binding" and "unsafe agent name" can both be
+ * exercised directly.
+ */
+export declare function executeAgentMemoryWrite(input: Record<string, unknown>, binding: AgentMemoryBinding | undefined, workDir?: string): Promise<ToolResult>;
+/**
+ * Why an agent run stopped.
+ *
+ * `'clean'` and `'aborted'` are the two silent-by-design outcomes: the model gave a
+ * final answer, or the user pressed Ctrl+C and already knows why it stopped.
+ * EVERYTHING else owes the user an explanation, which is what stopReasonNotice covers.
+ */
+export type StopReason = 'clean' | 'aborted' | 'reported-elsewhere' | 'empty-response' | 'output-limit' | 'no-balance' | 'no-team-budget' | 'team-unavailable' | 'stalled' | 'stalled-repeat' | 'budget' | 'hook-blocked' | 'unknown';
+/**
+ * The message shown when a run ends for any reason other than a clean finish.
+ *
+ * Pure and exported so every branch is testable: reaching some of these for real needs
+ * an empty wallet, a dead upstream, or hundreds of iterations. Returns null only for
+ * the two outcomes that are deliberately silent.
+ *
+ * `'unknown'` deliberately produces a message rather than nothing. If a future `break`
+ * forgets to set a reason, the symptom should be a visible "ended unexpectedly" line —
+ * annoying and reportable — not the silent stop that made this refactor necessary.
+ */
+export declare function stopReasonNotice(reason: StopReason, ctx?: {
+    budget?: number;
+    repeatError?: string | null;
+    hookReason?: string | null;
+}): string | null;
+export declare const TEAM_SCOPE_ERROR_CODES: ReadonlySet<string>;
+export declare function resolveMaxIterations(optionValue: number | undefined, settingsRaw: Record<string, unknown>): number;
+export declare function resolveAutoContinue(optionValue: boolean | undefined, settingsRaw: Record<string, unknown>): boolean;
+//# sourceMappingURL=iterationPolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"iterationPolicy.d.ts","sourceRoot":"","sources":["../../src/agent/iterationPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAYrD,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAU5C,eAAO,MAAM,WAAW,IAAgB,CAAC;AAKzC,eAAO,MAAM,kBAAkB,KAAU,CAAC;AAuB1C,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAKxC,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACrC,aAAa,EAAE,MAAM,GACpB,OAAO,CAGT;AAED,kDAAkD;AAClD,eAAO,MAAM,eAAe;;;CAAuD,CAAC;AAEpF;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9C,MAAM,CAKR;AAED,+CAA+C;AAC/C,eAAO,MAAM,YAAY;;;CAAsC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;CAgB3B,CAAC;AAEX,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,kBAAkB,GAAG,SAAS,EACvC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CA8BrB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAClB,OAAO,GACP,SAAS,GACT,oBAAoB,GACpB,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,gBAAgB,GAChB,kBAAkB,GAClB,SAAS,GACT,gBAAgB,GAChB,QAAQ,GACR,cAAc,GACd,SAAS,CAAC;AAEd;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,UAAU,EAClB,GAAG,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GACrF,MAAM,GAAG,IAAI,CA4Df;AAMD,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAMrD,CAAC;AAaH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,CAYR;AAKD,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,OAAO,GAAG,SAAS,EAChC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,OAAO,CAQT"}

package/dist/agent/iterationPolicy.js

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEAM_SCOPE_ERROR_CODES = exports.AGENT_MEMORY_TOOL_SCHEMA = exports.AGENT_MEMORY_TOOL = exports._stallLimits = exports._emptyTurnRetry = exports.EMPTY_TURN_RETRY_LIMIT = exports.REPEAT_STALL_LIMIT = exports.STALL_LIMIT = exports.MAX_ITERATIONS_CEILING = void 0;
+exports.emptyTurnBackoffMs = emptyTurnBackoffMs;
+exports.shouldRetryEmptyTurn = shouldRetryEmptyTurn;
+exports.errorRoundSignature = errorRoundSignature;
+exports.executeAgentMemoryWrite = executeAgentMemoryWrite;
+exports.stopReasonNotice = stopReasonNotice;
+exports.resolveMaxIterations = resolveMaxIterations;
+exports.resolveAutoContinue = resolveAutoContinue;
+const memory_1 = require("./memory");
+// ─── Iteration cap ──────────────────────────────────────────────────────────
+// Each iteration is one model response + one round of tool execution. The cap is
+// a runaway-loop backstop, NOT a task-size limit — on a large project a single
+// task can legitimately need well over 50 rounds (read → search → edit → test →
+// fix → …). A too-low cap makes the agent appear to "freeze" mid-task. Keep the
+// default high and let projects raise it further via settings / env.
+const DEFAULT_MAX_ITERATIONS = 500;
+exports.MAX_ITERATIONS_CEILING = 2000; // default auto-continue backstop (no explicit opt-in)
+// There is deliberately NO hard ceiling on an explicit opt-in anymore: a task meant to run
+// for days/weeks/months (an unattended agent loop) must not die at an arbitrary iteration
+// count just because someone picked a big-but-finite safety number in the past. The actual
+// protection against a runaway session burning cost forever is STALL_LIMIT /
+// REPEAT_STALL_LIMIT below — those catch "stuck", not "long", and fire in a handful of
+// rounds regardless of how high maxIterations is set. `Infinity` here is a real, intentional
+// value (not a bug) — resolveMaxIterations() below returns it whenever the caller does not
+// explicitly opt in to a finite number, matching the wording "unbounded unless you cap it".
+const HARD_ITERATIONS_CAP = Infinity; // no absolute cap — bounded only by the stall guards
+exports.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.
+exports.REPEAT_STALL_LIMIT = 12;
+// ─── Empty-turn auto-retry ────────────────────────────────────────────────────
+//
+// A model turn can come back STRUCTURALLY FINE (the stream completed, `message_complete`
+// arrived) and still contain nothing usable once thinking blocks are stripped for
+// history. Anthropic models hit this materially more often than the OpenAI-compatible
+// ones, because only they emit `thinking`/`redacted_thinking` blocks — a turn that
+// reasons and then ends without committing text or a tool call strips down to `[]`.
+//
+// The transport layer cannot fix this. client.ts only retries when the stream produced
+// NOTHING; here the stream produced a valid message that happens to be empty, so it
+// resolves normally and the loop used to break immediately and tell the user to type
+// "continue" — asking a human to press a button the loop can press itself.
+//
+// Retrying here is safe for a specific, checkable reason, not a hopeful one:
+//   • tools are dispatched from `assistantMessage.content` AFTER this check, and this
+//     content is empty, so no tool ran and no file changed;
+//   • nothing was pushed to `messages` (the push happens below this branch), so the
+//     history is byte-identical to the previous attempt — a retry is a clean re-ask,
+//     not a resend of a corrupted turn;
+//   • no round was counted, no hook fired, no checkpoint was taken.
+// Contrast the output-limit case, which is NOT retried: see shouldRetryEmptyTurn.
+exports.EMPTY_TURN_RETRY_LIMIT = 3;
+// Short, escalating pause (1s, 2s, 4s). Long enough to ride out the upstream blip that
+// causes this; short enough that three failures cost ~7s rather than a visible stall.
+const EMPTY_TURN_RETRY_BASE_MS = 1000;
+/** Backoff for the Nth (0-based) empty-turn retry. Pure, so the schedule is testable. */
+function emptyTurnBackoffMs(attempt) {
+    return EMPTY_TURN_RETRY_BASE_MS * Math.pow(2, Math.max(0, attempt));
+}
+/**
+ * Should an empty assistant turn be retried automatically, rather than surfaced?
+ *
+ * Split out as a pure function because the two "empty" causes look IDENTICAL at the
+ * call site (both are `content.length === 0`) and telling them apart is the entire
+ * point — the previous bug in this area was treating a deterministic truncation as a
+ * transient hiccup and advising a retry that reproduced it verbatim.
+ *
+ *   • `max_tokens` → the model burned its whole output budget on reasoning and was CUT
+ *     OFF. Retrying re-runs the same prompt with the same budget and the same reasoning
+ *     behaviour, so it fails the same way while billing again. Never retried; the user
+ *     is told to lower effort or split the task (stopReasonNotice 'output-limit').
+ *   • anything else → a genuinely transient empty turn. Retried, up to the limit.
+ *
+ * The attempt cap matters as much as the classification: a model that has decided to
+ * return nothing (e.g. a prompt it refuses to continue) would otherwise loop forever
+ * on a paid endpoint. After the cap we fall back to the old visible notice.
+ */
+function shouldRetryEmptyTurn(stopReason, attemptsSoFar) {
+    if (stopReason === 'max_tokens')
+        return false;
+    return attemptsSoFar < exports.EMPTY_TURN_RETRY_LIMIT;
+}
+/** Empty-turn retry limits, exposed for tests. */
+exports._emptyTurnRetry = { EMPTY_TURN_RETRY_LIMIT: exports.EMPTY_TURN_RETRY_LIMIT, EMPTY_TURN_RETRY_BASE_MS };
+/**
+ * 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: exports.STALL_LIMIT, REPEAT_STALL_LIMIT: exports.REPEAT_STALL_LIMIT };
+/**
+ * The single tool granted by a `memory:` frontmatter scope.
+ *
+ * Named distinctly from `memory_write` on purpose: they write to DIFFERENT stores, and
+ * a model that saw one name for both would reasonably assume its notes were visible to
+ * the main agent. They are not.
+ */
+exports.AGENT_MEMORY_TOOL = 'agent_memory_write';
+/**
+ * Schema advertised to the model, only for a sub-agent with a declared memory scope.
+ *
+ * The description does the load-bearing work of keeping the two stores apart in the
+ * model's head: it must not believe these notes reach the user or the main agent.
+ */
+exports.AGENT_MEMORY_TOOL_SCHEMA = {
+    name: exports.AGENT_MEMORY_TOOL,
+    description: 'Save a durable note to YOUR OWN persistent notes, which are injected into your prompt on ' +
+        'future runs. Use this for lessons that will still be true next time — a convention this repo ' +
+        'follows, a recurring bug pattern, a command that works, a dead end not worth retrying. ' +
+        'These notes are PRIVATE to you: they are NOT shown to the user and NOT read by the main agent, ' +
+        'so anything the user or the main agent needs to know must still go in your final message. ' +
+        'One self-contained fact per call, a sentence or two. Do not save transient task details.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            content: { type: 'string', description: 'The single fact to remember, 1-2 sentences.' },
+        },
+        required: ['content'],
+    },
+};
+/**
+ * Execute an `agent_memory_write` call.
+ *
+ * Pure-ish and exported so the refusal paths are testable without spawning a real
+ * sub-agent: the binding is data, so "no binding" and "unsafe agent name" can both be
+ * exercised directly.
+ */
+async function executeAgentMemoryWrite(input, binding, workDir) {
+    // Belt-and-braces: the permission gate already refuses this tool without a binding.
+    // Re-checked because this is the function that actually touches the filesystem, and
+    // it must not depend on a caller elsewhere having got the check right.
+    if (!binding) {
+        return {
+            error: `${exports.AGENT_MEMORY_TOOL} is only available to a sub-agent whose definition declares a \`memory:\` ` +
+                'scope. Put anything worth remembering in your final message instead.',
+        };
+    }
+    const content = typeof input.content === 'string' ? input.content.trim() : '';
+    if (!content)
+        return { error: `${exports.AGENT_MEMORY_TOOL} requires a non-empty \`content\` string.` };
+    const res = await (0, memory_1.writeAgentMemory)(binding.agentName, binding.scope, content, workDir);
+    if (!res.ok) {
+        // The realistic cause is a repo-scoped store with no workDir, or an agent name that
+        // is not a safe single path segment. Say which, rather than a bare failure.
+        return {
+            error: `Could not save to the "${binding.agentName}" agent's ${binding.scope} notes. ` +
+                'Either this scope needs a project directory (use `memory: user` for a store that ' +
+                'works anywhere) or the agent name is not usable as a filename.',
+        };
+    }
+    return {
+        output: res.already
+            ? 'Already saved (a near-identical note exists) — nothing added.'
+            : `Saved to your ${binding.scope} notes. It will be in your prompt on your next run.`,
+    };
+}
+/**
+ * The message shown when a run ends for any reason other than a clean finish.
+ *
+ * Pure and exported so every branch is testable: reaching some of these for real needs
+ * an empty wallet, a dead upstream, or hundreds of iterations. Returns null only for
+ * the two outcomes that are deliberately silent.
+ *
+ * `'unknown'` deliberately produces a message rather than nothing. If a future `break`
+ * forgets to set a reason, the symptom should be a visible "ended unexpectedly" line —
+ * annoying and reportable — not the silent stop that made this refactor necessary.
+ */
+function stopReasonNotice(reason, ctx = {}) {
+    switch (reason) {
+        case 'clean':
+        case 'aborted':
+        // A dedicated channel (e.g. the zero-balance bubble via onBalanceStatus) has already
+        // told the user why this stopped. Naming this case explicitly — rather than reusing
+        // 'aborted' — keeps "the user cancelled" from silently coming to mean two things.
+        case 'reported-elsewhere':
+            return null;
+        // Reaching this notice now means the loop ALREADY retried automatically and the
+        // model came back empty every time (see shouldRetryEmptyTurn). Saying "send
+        // continue to retry" without that context reads as if nothing was tried, and the
+        // user's manual retry is then the fourth identical attempt — so name the attempts.
+        case 'empty-response':
+            return `\n\u26a0\ufe0f The model returned an empty response ${exports.EMPTY_TURN_RETRY_LIMIT} times in a row, so nothing was done. ` +
+                `This is usually a transient upstream hiccup that the agent retries by itself; it did not clear this time. ` +
+                `Send "continue" to try again, or switch model with /model if it persists.\n`;
+        // Deliberately NOT folded into 'empty-response'. Both arrive as an assistant
+        // message with no content once thinking blocks are stripped, so they used to
+        // be indistinguishable — and the user was told the truncation case was "a
+        // transient upstream hiccup" they should retry with "continue". Both halves
+        // were wrong: nothing was transient, and continuing re-runs the same prompt
+        // with the same budget and the same reasoning behaviour, reproducing it
+        // exactly. Naming the cause is the fix; the advice has to change with it.
+        case 'output-limit':
+            return `\n\u26a0\ufe0f The model used its entire output budget on internal reasoning and was cut off ` +
+                `before it could reply, so nothing was done. This will repeat identically if you just retry \u2014 ` +
+                `lower the reasoning effort (/effort) or split the task into smaller steps.\n`;
+        case 'no-balance':
+            return `\n\ud83d\udcb3 Stopped: your balance is empty, so the request was rejected before it started. ` +
+                `Top up and send "continue" \u2014 no tokens were used for this turn.\n`;
+        case 'no-team-budget':
+            return `\n\ud83d\udcb3 Stopped: the team budget you are billing to is empty, so the request was rejected ` +
+                `before it started. Ask your team admin to add funds \u2014 or switch "Bill to" back to Personal \u2014 ` +
+                `and send "continue". No tokens were used for this turn.\n`;
+        case 'team-unavailable':
+            return `\n\u26a0\ufe0f Stopped: that team is no longer available for billing (you may have been removed, or the ` +
+                `team was suspended). "Bill to" has been reset to your Personal account, so sending "continue" will ` +
+                `run on your own wallet.\n`;
+        case 'stalled':
+            return `\n\ud83d\uded1 Stopped: the last ${exports.STALL_LIMIT} tool rounds all failed, so the agent looked stuck. ` +
+                `Fix the underlying error (or grant the needed permission) and send "continue".\n`;
+        case 'stalled-repeat':
+            return `\n\ud83d\uded1 Stopped: the same tool error repeated ${exports.REPEAT_STALL_LIMIT} rounds in a row, so the agent ` +
+                `was looping without making progress.` +
+                (ctx.repeatError ? ` The recurring error was:\n${ctx.repeatError}\n` : '\n') +
+                `Fix that underlying cause (or grant the needed permission) and send "continue".\n`;
+        case 'hook-blocked':
+            return `\n\u26d4 A PostToolBatch hook stopped the turn before the next model call` +
+                (ctx.hookReason ? `: ${ctx.hookReason}` : '.') +
+                `\nThe reason is in the conversation, so send "continue" once the cause is handled.\n`;
+        case 'budget':
+            return `\n\u23f8\ufe0f Stopped at the ${ctx.budget}-step safety limit \u2014 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`;
+        case 'unknown':
+        default:
+            return `\n\u26a0\ufe0f The run ended unexpectedly without completing. Your work so far is preserved \u2014 ` +
+                `send "continue" to resume.\n`;
+    }
+}
+// Error codes that mean "this team cannot pay for anything right now" — the
+// pre-flight refusals routes/code.js returns when a request names a team
+// (migration 139). Kept as one list so the loop's auto-fallback and the server's
+// vocabulary cannot drift apart silently.
+exports.TEAM_SCOPE_ERROR_CODES = new Set([
+    'team_unavailable',
+    'team_not_found',
+    'not_a_member',
+    'member_suspended',
+    'team_suspended',
+]);
+// Resolve the soft iteration budget. Precedence:
+//   options.maxIterations  →  env NEXRALL_MAX_ITERATIONS  →  settings.maxIterations  →  default
+//
+// The DEFAULT (nothing set) is clamped to MAX_ITERATIONS_CEILING so an ordinary
+// run can never spin past 2000 rounds by accident. But an EXPLICIT value from
+// any of the three opt-in channels is honoured with NO upper bound (HARD_ITERATIONS_CAP
+// is Infinity) — this is what lets a genuinely unattended, long-lived task (an agent meant
+// to keep working for days or longer) run for as many rounds as it needs once the user has
+// deliberately asked for that, instead of dying at a hidden ceiling while the error message
+// misleadingly tells them to "raise the limit". A stuck/looping run is still caught by the
+// STALL_LIMIT / REPEAT_STALL_LIMIT guards below, independent of this budget.
+function resolveMaxIterations(optionValue, settingsRaw) {
+    const fromEnv = Number(process.env.NEXRALL_MAX_ITERATIONS);
+    const fromSettings = Number(settingsRaw.maxIterations);
+    const explicit = (typeof optionValue === 'number' && optionValue > 0) ? optionValue
+        : Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv
+            : Number.isFinite(fromSettings) && fromSettings > 0 ? fromSettings
+                : undefined;
+    if (explicit === undefined)
+        return DEFAULT_MAX_ITERATIONS;
+    // Explicit opt-in: honour it verbatim (floor for a fractional value from JSON/env), no
+    // longer bounded by an absolute safety cap — see HARD_ITERATIONS_CAP's comment above.
+    return Math.min(Math.floor(explicit), HARD_ITERATIONS_CAP);
+}
+// When the soft budget is exhausted with work still pending, keep going instead
+// of stopping. Precedence: options.autoContinue → env NEXRALL_AUTO_CONTINUE →
+// settings.autoContinue → default (on). Bounded by STALL_LIMIT and the ceiling.
+function resolveAutoContinue(optionValue, settingsRaw) {
+    if (typeof optionValue === 'boolean')
+        return optionValue;
+    const env = process.env.NEXRALL_AUTO_CONTINUE;
+    if (env === '0' || env === 'false')
+        return false;
+    if (env === '1' || env === 'true')
+        return true;
+    const s = settingsRaw.autoContinue;
+    if (typeof s === 'boolean')
+        return s;
+    return true;
+}
+//# sourceMappingURL=iterationPolicy.js.map

package/dist/agent/lifecycleHost.d.ts

@@ -0,0 +1,55 @@
+/** One instruction file that was loaded, told to the InstructionsLoaded hooks. */
+export interface LoadedInstruction {
+    file_path: string;
+    /** Claude Code's memory_type vocabulary, mapped onto nex's files (see the CLI caller). */
+    memory_type: 'User' | 'Project' | 'Local' | 'Managed';
+    /** Claude Code's load_reason vocabulary: session_start | compact | include | nested_traversal | path_glob_match. */
+    load_reason: string;
+    globs?: string[];
+}
+/**
+ * Tell the InstructionsLoaded hooks which instruction files this session loaded.
+ * Observer: output and exit code are ignored (Claude Code says the same for this event).
+ *
+ * Called by the host at the moment the files are actually read — a `--bare` run reads
+ * none and therefore fires nothing, which is the honest behaviour.
+ */
+export declare function fireInstructionsLoadedHooks(workDir: string, sessionId: string, files: LoadedInstruction[]): Promise<void>;
+export interface FileChangedWatcher {
+    /** Stop watching and drop any pending debounce timer. Safe to call twice. */
+    stop(): void;
+    /** Replace the DYNAMIC watch list (a hook's watchPaths answer). Static matcher names stay. */
+    updateWatchPaths(paths: string[]): void;
+    /** What the watcher is currently listening for — exposed for tests and `nex doctor`. */
+    watchedFiles(): string[];
+}
+/**
+ * Start watching the files named by the FileChanged hooks' matchers ("a.txt|b.txt").
+ *
+ * - Returns null when no FileChanged hook is configured, so callers can wire it
+ *   unconditionally.
+ * - `fs.watch` on the WORKING DIRECTORY (not the files themselves: editors replace
+ *   files, which kills a per-file watch on rename) filtered to the watched basenames,
+ *   with a short per-file debounce — one save is several fs events.
+ * - A hook's `{"watchPaths": […]}` answer replaces the dynamic list; `{"systemMessage": "…"}`
+ *   is handed to `onSystemMessage` for the host to display.
+ * - Never throws into the host: watching is best-effort (an OS without inotify, a
+ *   directory that vanishes) and a broken watch must not break the session.
+ */
+export declare function startFileChangedWatcher(workDir: string, sessionId: string, opts?: {
+    onSystemMessage?: (message: string) => void;
+    /**
+     * How long to wait before the arming reconcile pass looks for a write the OS stream
+     * may have missed because it was not armed yet (see `stamp` below). 0 disables it;
+     * tests set it low, the default is tuned for a real save landing right at session start.
+     */
+    armGraceMs?: number;
+}): FileChangedWatcher | null;
+/**
+ * Which watched files differ from the snapshot taken when the watcher armed. This is the
+ * whole substance of the arming reconcile: fs.watch arms asynchronously, so a write that
+ * lands before the stream is listening is not queued — it is gone. Exported so the
+ * comparison can be tested without racing an OS event.
+ */
+export declare function filesChangedSinceSnapshot(names: Iterable<string>, seen: Map<string, string>, stamp: (name: string) => string): string[];
+//# sourceMappingURL=lifecycleHost.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycleHost.d.ts","sourceRoot":"","sources":["../../src/agent/lifecycleHost.ts"],"names":[],"mappings":"AAeA,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACtD,oHAAoH;IACpH,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,iBAAiB,EAAE,GACzB,OAAO,CAAC,IAAI,CAAC,CAef;AAED,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,IAAI,IAAI,IAAI,CAAC;IACb,8FAA8F;IAC9F,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxC,wFAAwF;IACxF,YAAY,IAAI,MAAM,EAAE,CAAC;CAC1B;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;IACL,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,kBAAkB,GAAG,IAAI,CA+H3B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACzB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAC9B,MAAM,EAAE,CAIV"}