aegis-desktop 0.5.1 → 0.5.4

package/lib/local/engine.js

@@ -47,6 +47,28 @@ const toolsModule = require('./tools.js');
 const promptModule = require('./prompt.js');
 const { ShellSession } = require('./shell.js');
 const { agentSystemPrompt, agentRoleLabel } = require('./agents.js');
+// Cooperative working-tree sharing (see each module's header). The lock
+// serialises two hosts that start a turn on one checkout close together; the
+// guard is the load-bearing half — it refuses a tree-wide git operation while
+// another session's uncommitted work is present, which is the operation that
+// destroyed a peer's file for real. Both live beside the engine because the
+// CLI vendors this directory wholesale (cli/scripts/predist.mjs), so the GUI
+// and the terminal get one implementation rather than two that drift.
+const { beginTurnGuard, recordWrite, blocksDestructive } = require('./turn-guard.js');
+const { acquireWorktreeLock, releaseWorktreeLock } = require('./worktree-lock.js');
+
+/**
+ * How long a turn waits for the working-tree lock before running anyway.
+ *
+ * Short on purpose. This engine serves interactive hosts — a desktop window
+ * and a terminal — where stalling for the lock's own 11-minute default would
+ * be a worse failure than contending: the user is watching a spinner. So the
+ * lock is best-effort mutual exclusion for turns that start near-simultaneously
+ * (the common overlap), and the turn guard covers everything after that. A
+ * non-interactive caller that can afford to queue should pass
+ * `payload.worktreeWaitMs` with the long DEFAULT_WORKTREE_WAIT_MS instead.
+ */
+const WORKTREE_LOCK_WAIT_MS = 1500;
 
 /** Classes whose transport is a user-supplied endpoint + credential. */
 const CUSTOM_CLASSES = Object.freeze(['openai-compat', 'anthropic']);
@@ -70,22 +92,30 @@ const CLASSES = [
 /**
  * Mirrors aegiscodex-dev's src/backend.js DEEPSEEK_REASONING_MODEL_RE +
  * EFFORT_TOKEN_BUDGET verbatim. DeepSeek's reasoning models (deepseek-flash,
- * deepseek-v4-pro, the deprecated deepseek-reasoner, and the legacy
- * v4-flash/v4.1-flash aliases some configs still carry) spend part of
- * max_tokens on hidden chain-of-thought before ever emitting visible
- * content — DeepSeek counts reasoning tokens against the same budget as
- * content. At the renderer's 4k default (index.html's max-tokens select),
- * any non-trivial question can burn the whole budget reasoning and finish
- * with empty content: no error, no tool calls, just a turn that "completes"
- * with nothing to show for it (the empty-response bug). A user pointing the
- * Custom OpenAI-compatible class straight at DeepSeek's API hits exactly
- * this, so the request floors to the same effort budget aegiscodex-dev uses
- * for its own direct DeepSeek calls instead of shipping whatever the
- * dropdown happens to have selected.
+ * i.e. "Flash 4.1", deepseek-v4-pro, the deprecated deepseek-reasoner, and the
+ * legacy v4-flash/v4.1-flash aliases some configs still carry) spend part of
+ * the budget on hidden chain-of-thought before ever emitting visible content —
+ * DeepSeek counts reasoning tokens against the same budget as content. Under
+ * the renderer's removed 4k dropdown default, any non-trivial question could
+ * burn the whole budget reasoning and finish with empty content: no error, no
+ * tool calls, just a turn that "completes" with nothing to show for it (the
+ * empty-response bug). A user pointing the Custom OpenAI-compatible class
+ * straight at DeepSeek's API hits exactly this, so the request is sized by the
+ * same effort budget aegiscodex-dev uses for its own direct DeepSeek calls.
+ *
+ * desktop/renderer/budget.js carries the renderer's copy of these two
+ * constants plus budgetFor() below; test/budget.test.mjs requires both and
+ * asserts they agree, so the mirror cannot drift silently.
  */
 const DEEPSEEK_REASONING_MODEL_RE = /^deepseek-(v4(\.\d+)?-(flash|pro)|flash|pro|reasoner)$/;
 const EFFORT_TOKEN_BUDGET = { low: 8192, medium: 16384, high: 32768 };
 
+/** The one class whose wire format REQUIRES a stated `max_tokens`: Anthropic's
+ *  Messages API 400s without it, so that field is derived from the effort rung
+ *  rather than invented by the transport (which is what a blanket
+ *  `max_tokens: maxTokens || 4096` did — see providers.anthropicMessages). */
+const REQUIRES_STATED_BUDGET = new Set(['anthropic']);
+
 /**
  * Idle-stream budget for a pooled brain call ("work autonomously"). The
  * generic watchdog in vendor/aegis.js kills a stream that goes 60s without a
@@ -109,18 +139,38 @@ const EFFORT_TOKEN_BUDGET = { low: 8192, medium: 16384, high: 32768 };
 const AUTONOMOUS_IDLE_TIMEOUT_MS = 15 * 60_000;
 
 /**
- * Only ever raises a too-low budget for a DeepSeek reasoning model — never
- * lowers whatever the caller (renderer dropdown, or "adaptive" ceiling)
- * already asked for. Everything else (non-DeepSeek models, non-reasoning
- * DeepSeek ids like deepseek-chat) passes through untouched. Effort defaults
- * to 'high' since custom endpoints have no effort selector of their own
- * (that UI is aegis-class/autonomous-only) — matching aegiscodex-dev's own
- * default effort.
+ * The budget a request travels with, resolved from EXACTLY ONE authority per
+ * call — the engine-side half of the rule desktop/renderer/budget.js mirrors
+ * and test/budget.test.mjs compares the two halves of, so neither can drift.
+ *
+ *   1. a caller-stated number IS the budget and is returned verbatim. It is a
+ *      deliberate liability ceiling (aegis1 pass_budgets honours it downward:
+ *      total = min(ladder, max_tokens x passes)) and no rung may raise it — the
+ *      old `Math.max(stated, EFFORT_TOKEN_BUDGET[eff])` form did exactly that,
+ *      so a caller asking for 1024 silently ran on 32768.
+ *   2. with nothing stated, a model that reasons against its own output budget
+ *      (DeepSeek bills hidden chain-of-thought against the SAME budget as the
+ *      answer) or a class whose wire format REQUIRES the field (Anthropic's
+ *      Messages API) gets the Effort rung. This is why the renderer's
+ *      max-tokens dropdown was removed rather than fixed: at its 4k default a
+ *      reasoning model spent the entire budget thinking and finished empty —
+ *      no error, no tool call, just a "completed" turn with nothing in it.
+ *   3. otherwise `undefined` — no `max_tokens` goes on the wire and the
+ *      provider's own output limit governs. The transport used to fill this
+ *      gap with an invented 4096 default, which is the defect in (2).
+ *
+ * Truncated and empty turns are still handled where they belong — the
+ * doubled-budget retry plus emptyTurnError — rather than by inflating the
+ * caller's ceiling up front.
  */
-function deepseekReasoningFloor(model, maxTokens, effort) {
-  if (!DEEPSEEK_REASONING_MODEL_RE.test(String(model || ''))) return maxTokens;
-  const eff = effort === 'low' || effort === 'medium' ? effort : 'high';
-  return Math.max(Number(maxTokens) || 0, EFFORT_TOKEN_BUDGET[eff]);
+function reasoningBudget(cls, model, maxTokens, effort) {
+  const stated = Number(maxTokens);
+  if (Number.isFinite(stated) && stated > 0) return stated;
+  if (DEEPSEEK_REASONING_MODEL_RE.test(String(model || '')) || REQUIRES_STATED_BUDGET.has(cls)) {
+    const eff = effort === 'low' || effort === 'medium' ? effort : 'high';
+    return EFFORT_TOKEN_BUDGET[eff];
+  }
+  return undefined;
 }
 
 /** Relay model entries arrive as ids or objects; keep only real model ids. */
@@ -259,6 +309,33 @@ function doubledBudget(maxTokens) {
   return n > 0 ? n * 2 : 8192;
 }
 
+/**
+ * The cap the CALLER stated, or `undefined` meaning "none was stated".
+ *
+ * The two branches resolve one question — whose number is this? — and the
+ * first is the fix. An internal re-entry (runSubagent's nested chat()) passes
+ * `statedMaxTokens` explicitly, because the `maxTokens` it holds is the rung
+ * reasoningBudget() derived from `effort`: a number the server is about to
+ * derive for itself. Re-reading that value as the caller's own is what put a
+ * guessed 32768 on the wire as a *ceiling over* aegis1's ladder
+ * (pass_budgets: total = min(ladder, max_tokens x passes)) — so a
+ * high-effort subagent silently ran at 8192 and the ladder the UI advertised
+ * was not the budget the call used.
+ *
+ * A non-numeric or non-positive value means "nothing stated" — never a 0- or
+ * NaN-token ceiling.
+ */
+function statedCapOf(payload) {
+  const asCap = (v) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+  };
+  if (payload && Object.prototype.hasOwnProperty.call(payload, 'statedMaxTokens')) {
+    return asCap(payload.statedMaxTokens);
+  }
+  return asCap(payload && payload.maxTokens);
+}
+
 /**
  * The follow-up shown to a model that ended its turn with neither text nor a
  * tool call. Sent as a plain user message (never as a tool result — there is
@@ -285,9 +362,9 @@ const EMPTY_TURN_NUDGE =
 function emptyTurnError({ cls, model, maxTokens, finishReason }) {
   const err = new Error(
     `The model returned no answer after ${cls}/${model} was asked to summarise its results ` +
-      `(stop reason: ${finishReason || 'none'}, max_tokens: ${maxTokens}). The token budget ` +
-      'was most likely consumed before any visible text — raise the max-tokens setting, ' +
-      'or lower effort.'
+      `(stop reason: ${finishReason || 'none'}, max_tokens: ${maxTokens || 'unstated'}). The token budget ` +
+      'was most likely consumed before any visible text — raise the Effort rung, which is ' +
+      'what sizes this call, or ask for a smaller piece of work.'
   );
   err.status = 502;
   return err;
@@ -326,6 +403,15 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
   // In-memory only, on purpose — never persisted, so a restart (or
   // newChat()'s clearSessionApprovals) always starts from a clean gate.
   const sessionAllowlists = new Map(); // rootSessionId -> Set<toolName>
+  // Denials are remembered for the same reason allows are, mirroring it for
+  // the other answer. Without this, a "Deny" was forgotten the instant it was
+  // given: the model read `… the user denied the request`, re-planned, called
+  // the SAME tool again, and the gate raised a SECOND card — so one "no" cost
+  // the user a prompt per round for up to maxRounds (24 chat / 40 autonomous)
+  // rounds, each round re-sending the whole conversation to the provider. A
+  // gate that only remembers "yes" turns a single click into a retry storm;
+  // remembering "no" makes the first answer stick.
+  const sessionDenials = new Map(); // rootSessionId -> Set<toolName>
   const pendingApprovals = new Map(); // approvalId -> { resolve }
 
   function sessionAllows(rootId, name) {
@@ -338,10 +424,44 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     sessionAllowlists.get(rootId).add(name);
   }
 
+  /** Has this conversation already refused this tool? Checked before the card
+   *  is raised, so a repeat call is refused outright instead of re-prompting. */
+  function sessionDenies(rootId, name) {
+    const set = sessionDenials.get(rootId);
+    return Boolean(set && set.has(name));
+  }
+
+  function denyForSession(rootId, name) {
+    if (!sessionDenials.has(rootId)) sessionDenials.set(rootId, new Set());
+    sessionDenials.get(rootId).add(name);
+  }
+
+  /**
+   * The text a refused tool hands back to the model. The old one-line
+   * `"<tool> was not executed — the user denied the request."` read to a
+   * capable agent as a transient failure to route around: it would apologise,
+   * pick a different command that does the same thing, and call the gate
+   * again. This says the durable part out loud (the refusal covers the rest of
+   * the conversation, not just that call) and asks for the one response that
+   * actually helps — say what you need and stop, so the user can re-enable it.
+   */
+  function denialText(name) {
+    return (
+      `${name} was not executed — the user denied this tool for this conversation. ` +
+      `Do NOT retry it and do NOT attempt the same effect by another route ` +
+      `(another command, a writeFile instead of an edit, a subagent). ` +
+      `Stop calling tools and reply in plain text: say what you were trying to do, ` +
+      `what you need, and that the user can re-enable ${name} to let it proceed.`
+    );
+  }
+
   /** newChat() in the renderer calls this so a fresh conversation never
-   *  inherits a prior thread's blanket allows. */
+   *  inherits a prior thread's blanket allows — or its refusals. A new chat is
+   *  a new gate in both directions: leaving denials behind would silently
+   *  refuse a tool in a thread where the user never said no. */
   function clearSessionApprovals(rootSessionId) {
     sessionAllowlists.delete(rootSessionId);
+    sessionDenials.delete(rootSessionId);
     return { ok: true };
   }
 
@@ -359,22 +479,28 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
 
   /**
    * Ask the renderer to approve one mutating tool call. Resolves 'once',
-   * 'session' or 'deny'. Sent over `rootOnDelta` (see chat()) as an
-   * `{ approval }` chunk so it rides the exact same streaming channel as
-   * tool-activity chunks — no new IPC surface needed on the push side, only
-   * on the reply side (respondApproval). Fails safe: no listener able to
-   * ever answer (no onDelta, or the turn was aborted) resolves 'deny'
-   * instead of hanging the tool round forever.
+   * 'session' or 'deny' (an explicit choice by the user) — or 'cancel' when
+   * nobody ever answered: no listener able to reply, or the turn was aborted.
+   * 'cancel' is kept apart from 'deny' on purpose. Both refuse the call, but
+   * only 'deny' is a decision the user made, so only 'deny' may be remembered
+   * as "this conversation said no" (see sessionDenials). Folding the two
+   * together — which is what the old fail-safe did, resolving 'deny' for an
+   * abort — would let a cancelled turn permanently refuse a tool the user
+   * never ruled on. Sent over `rootOnDelta` (see chat()) as an `{ approval }`
+   * chunk so it rides the exact same streaming channel as tool-activity
+   * chunks — no new IPC surface needed on the push side, only on the reply
+   * side (respondApproval). Fails safe: an unanswered request refuses the
+   * call instead of hanging the tool round forever.
    */
   function requestApproval(rootSessionId, rootOnDelta, signal, info) {
     return new Promise((resolve) => {
       if (signal && signal.aborted) {
-        resolve('deny');
+        resolve('cancel');
         return;
       }
       const id = randomUUID();
       let settled = false;
-      const onAbort = () => finish('deny');
+      const onAbort = () => finish('cancel');
       const finish = (decision) => {
         if (settled) return;
         settled = true;
@@ -385,7 +511,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       if (signal) signal.addEventListener('abort', onAbort, { once: true });
       pendingApprovals.set(id, { resolve: finish });
       if (typeof rootOnDelta !== 'function') {
-        finish('deny');
+        finish('cancel');
         return;
       }
       rootOnDelta({
@@ -415,11 +541,51 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
    * runs straight through exactly like a session-allowed one, so "don't ask"
    * is one switch rather than a per-tool blanket allow in every conversation.
    */
+  /**
+   * The single place a tool executor is called from the chat loop, so the
+   * turn guard cannot be bypassed by reaching a different branch (there are
+   * four `return`s in gatedExecuteTool below; all of them come through here).
+   *
+   * exec is *checked* before running and writeFile/editFile are *recorded*
+   * after, and the asymmetry is the point: a refusal has to happen before the
+   * command runs, while "this path is mine" is only true once the write
+   * actually happened — recording a denied or preview-failed write would hide
+   * a genuinely foreign file behind a claim of ownership.
+   *
+   * A refusal is returned as an ordinary tool error, so the model reads it and
+   * adapts (name the paths, or don't do it) with no new IPC or renderer
+   * channel — the same reason it works identically in the GUI and the CLI.
+   */
+  async function guardedExecute(name, args, toolCtx) {
+    const guard = toolCtx && toolCtx.guard;
+    if (guard && name === 'exec') {
+      const verdict = blocksDestructive(guard, args && args.command);
+      if (!verdict.ok) return { ok: false, error: verdict.reason };
+    }
+    // Awaited, not merely returned: "this path is mine" is only true once the
+    // write actually landed, and `executeTool` is async — inspecting `.ok` on
+    // an un-awaited promise would read undefined and record every write,
+    // including the ones that failed. Ownership is load-bearing in the other
+    // direction too: a path wrongly claimed stops being reported as foreign.
+    const result = await T.executeTool(name, args, toolCtx);
+    if (guard && (name === 'writeFile' || name === 'editFile') && result && result.ok !== false) {
+      recordWrite(guard, args && args.path);
+    }
+    return result;
+  }
+
   async function gatedExecuteTool(call, { toolCtx, rootSessionId, rootOnDelta, signal }) {
     const { name, args } = call;
-    if (!T.MUTATING_TOOLS.has(name)) return T.executeTool(name, args, toolCtx);
-    if (!confirmModeEnabled()) return T.executeTool(name, args, toolCtx);
-    if (sessionAllows(rootSessionId, name)) return T.executeTool(name, args, toolCtx);
+    if (!T.MUTATING_TOOLS.has(name)) return guardedExecute(name, args, toolCtx);
+    if (!confirmModeEnabled()) return guardedExecute(name, args, toolCtx);
+    if (sessionAllows(rootSessionId, name)) return guardedExecute(name, args, toolCtx);
+    // Already refused in this conversation: refuse again WITHOUT raising a
+    // second card. Before this, the model's retry after a denial re-prompted
+    // the user for the same tool — one "no" produced a card per round for up
+    // to maxRounds rounds, each one a billed provider call re-sending the
+    // whole conversation. Checked after the confirm-mode short-circuit so
+    // turning the gate off still overrides an earlier refusal.
+    if (sessionDenies(rootSessionId, name)) return { ok: false, error: denialText(name) };
 
     let preview = null;
     if (name === 'writeFile' || name === 'editFile') {
@@ -433,13 +599,30 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       diff: preview && preview.diff,
     });
 
+    // Only a click is remembered. 'cancel' (aborted turn / nobody able to
+    // answer) refuses this call but must not write a durable "no" the user
+    // never gave.
     if (decision === 'deny') {
-      return { ok: false, error: `${name} was not executed — the user denied the request.` };
+      denyForSession(rootSessionId, name);
+      return { ok: false, error: denialText(name) };
+    }
+    if (decision !== 'session' && decision !== 'once') {
+      return { ok: false, error: `${name} was not executed — the request was cancelled.` };
     }
     if (decision === 'session') allowForSession(rootSessionId, name);
 
-    if (preview) return T.applyChecked(name, args, preview);
-    return T.executeTool(name, args, toolCtx);
+    if (preview) {
+      const res = T.applyChecked(name, args, preview);
+      // Recorded on the same condition as guardedExecute's path: only a write
+      // that landed is this session's. (The previous form returned here
+      // unconditionally, making every line below it unreachable — the
+      // approved-write path recorded nothing at all.)
+      if (res && res.ok !== false && toolCtx && toolCtx.guard) {
+        recordWrite(toolCtx.guard, args && args.path);
+      }
+      return res;
+    }
+    return guardedExecute(name, args, toolCtx);
   }
 
   /**
@@ -545,7 +728,25 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         messages: opts.messages,
         model: opts.model,
         mode: opts.mode,
-        maxTokens: opts.maxTokens,
+        // Only a cap the caller STATED travels; an effort-derived one does not.
+        // The server derives its own budget from `effort` (aegis1 pass_budgets
+        // splits its ladder across workers + synthesis), so forwarding the
+        // derived number states one decision twice — and the copies had already
+        // drifted: 974adc5 doubled aegis1's ladder while this side stood still,
+        // leaving the client capping below the budget it displayed. The cap was
+        // never the one the renderer showed either (the Max tokens dropdown
+        // that used to claim a figure for the pooled class is gone — see
+        // desktop/renderer/budget.js). Omitting the field is
+        // what tells aegis1 "no cap stated — let effort decide", the same
+        // contract aegiscodex-dev sends.
+        //
+        // A cap the caller DID state is a different thing, and dropping it was
+        // a bug: aegis1 reads a body max_tokens as a ceiling over its ladder,
+        // so omitting it does not bound the call — it grants the full top rung
+        // instead. A deliberate 4096 would have run at 32768, which is the same
+        // "only ever raise the caller's ceiling" failure the old
+        // Math.max(Number(maxTokens) || 0, EFFORT_TOKEN_BUDGET[eff]) had.
+        maxTokens: opts.statedMaxTokens,
         stream: opts.stream !== false,
         // The pooled (Nexus) brain is streamed, and an OpenAI-compatible SSE
         // stream reports no token usage unless asked. Without this the Aegis
@@ -561,12 +762,53 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         // AUTONOMOUS_IDLE_TIMEOUT_MS). Undefined elsewhere -> 60s default.
         idleTimeoutMs: opts.idleTimeoutMs,
         signal: opts.signal,
-        // aegis_memory: automatic, no button — the server both reads prior
-        // synced memory into context AND writes this turn back to it, the
-        // same flag aegis-online sets. Matches aegiscodex-dev's own
-        // cross-session memory (auto-indexed, no manual tagging).
+        // aegis_recall — the read half of aegis_memory, and the only half a
+        // client on this engine should send.
+        //
+        // aegis_memory is both halves: it injects the account's synced memory
+        // into context AND persists this turn back into it, charging sync
+        // quota for the write. That pairing is right for aegis-online, whose
+        // chat has nowhere else to live. It is wrong here, because this engine
+        // is shared by the GUI and the CLI (cli/src/deps.js loads this file):
+        // either would be billed for every "hey" and would fill the user's
+        // memory with greetings. Verified against aegis1 app.py: every
+        // write-back site (the note/upsert calls) is gated on aegis_memory,
+        // and aegis_memory implies aegis_recall there — so dropping the write
+        // half leaves /online unchanged and costs nothing on the read side.
+        //
+        // Writing is still available, explicitly: the aegis_memory_save tool
+        // (mcp/tools.js; the CLI exposes it as /memory). Recall on every turn,
+        // store only what the user asks for — which is what aegiscodex-dev's
+        // own cross-session memory does, and what this comment claimed to
+        // match while sending both halves.
+        //
+        // Recall was previously unreachable for a client that would not pay
+        // for it: services/tiered_recall.py only ran behind a flag that also
+        // bought a write, so the tiered path existed with no caller able to
+        // afford it. The split is what makes it reachable. The DEEP tier of the
+        // same read is a third flag with its own price — see `opts.recallDeep`
+        // below, which is off unless the session opted in.
         extra: {
-          aegis_memory: true,
+          aegis_recall: true,
+          // The DEEP tier of that read — brain corrections plus the semantic
+          // answer cache — is not the same price, so it does not ride along.
+          // aegis1 app.py:8367 reads `aegis_recall_deep` (or the
+          // X-AEGIS-Recall-Deep header) and services/brain_memory.py
+          // find_cached_answer embeds the query: one provider embedding per
+          // turn, metered. The server deliberately implies it from
+          // `aegis_memory` and NOT from `aegis_recall`, so that a terminal
+          // client can buy the cheap read without the embedding.
+          //
+          // This client is that terminal client (the CLI loads this file via
+          // cli/src/deps.js), so it must not opt itself in: the flag is sent
+          // only when the SESSION asked for it — CLI `/memory-deep on`, a
+          // desktop payload with `recallDeep: true` — and it defaults false
+          // everywhere. It also travels only on the user's own turn
+          // (`opts.recallDeep` is cleared for every other dispatch below): a
+          // tool round, the doubled-budget retry and the write-up re-dispatch
+          // all re-send a context whose embedding the first round already
+          // bought, which would turn one embedding per turn into one per round.
+          ...(opts.recallDeep ? { aegis_recall_deep: true } : {}),
           session: opts.sessionId,
           // The fan-out is opt-in per dispatch. `brain` is sent EXPLICITLY
           // whenever this dispatch is not the autonomous one, because the
@@ -638,7 +880,19 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
   async function chat(payload, onDelta) {
     const cls = payload && payload.class;
     const model = payload && payload.model;
-    const maxTokens = deepseekReasoningFloor(model, payload && payload.maxTokens, payload && payload.effort);
+    const maxTokens = reasoningBudget(cls, model, payload && payload.maxTokens, payload && payload.effort);
+    // The caller's OWN number, kept apart from `maxTokens` above. That one
+    // collapses two different facts into a single value — "the caller stated
+    // 4096" and "effort implies 32768" — and the pooled path must treat them
+    // differently. A stated cap is a liability ceiling the server honours
+    // downward (aegis1 pass_budgets: total = min(ladder, max_tokens x passes));
+    // an effort-derived one is the server's own arithmetic stated twice, and
+    // sending it is how the two copies came to disagree. So the pooled call
+    // forwards only what the caller actually asked for.
+    // ...and it is read through statedCapOf(), so a nested chat() that states
+    // the key overrides its own derived `maxTokens` instead of being mistaken
+    // for a caller who asked for that number (see statedCapOf).
+    const statedMaxTokens = statedCapOf(payload);
     // "Work autonomously" — routes this call through aegis1's pool_brain
     // worker fan-out (services/pool_brain.py: N reasoning workers + a
     // synthesis pass) instead of a single provider call. UI-gated to the
@@ -710,9 +964,17 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       }
 
       const base = {
-        cls, model, mode: payload && payload.mode, maxTokens, autonomous, sessionId, signal, onDelta, cfg, apiKey, toolChoice,
+        cls, model, mode: payload && payload.mode, maxTokens, statedMaxTokens, autonomous, sessionId, signal, onDelta, cfg, apiKey, toolChoice,
         effort: payload && payload.effort,
         workers: payload && payload.workers,
+        // Deep recall (`aegis_recall_deep`) is an explicit per-session opt-in
+        // and never a default: it costs one provider embedding per turn
+        // server-side (aegis1 services/brain_memory.py find_cached_answer), so
+        // a client that pays per turn must not turn it on for itself. Only a
+        // literal `true` from the caller counts — an absent or `undefined`
+        // field is off, which is what keeps every existing caller (the
+        // renderer's IPC payloads included) on the cheap read.
+        recallDeep: payload && payload.recallDeep === true,
         onReasoning,
         idleTimeoutMs: autonomous ? AUTONOMOUS_IDLE_TIMEOUT_MS : undefined,
         // A caller with no live streaming surface (a `--no-stream` CLI flag, a
@@ -741,6 +1003,26 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       let truncationRetried = false;
       let synthesisDone = false;
 
+      // Round cap — the bound aegiscodex-dev has had all along and this engine
+      // did not. Removing the old fixed cap (12) was right in spirit and wrong
+      // in effect: it left the turn with NO horizon, and on 2026-09-15 the
+      // question "can you check the plan" ran ~70 rounds, grew the context
+      // from 2,260 to 116,011 tokens, cost about EUR 2, and spent those rounds
+      // writing 400 lines of unrequested code into the source tree. Each round
+      // re-sends the whole conversation, so an unbounded loop gets more
+      // expensive the longer it runs.
+      //
+      // The numbers match aegiscodex-dev's (src/autonomous.js) so both clients
+      // behave the same: 24 rounds for a chat turn, 40 for an autonomous one.
+      // Env-overridable for a deliberately long job.
+      const maxRounds = (() => {
+        const name = autonomous ? 'AEGIS_AUTONOMOUS_MAX_ROUNDS' : 'AEGIS_CHAT_MAX_ROUNDS';
+        const raw = Number.parseInt(process.env[name] || '', 10);
+        if (Number.isFinite(raw) && raw > 0) return raw;
+        return autonomous ? 40 : 24;
+      })();
+      let round = 0;
+
       // Token accounting for the whole TURN, not just its last round. An
       // agentic turn makes one provider call per tool round, and returning only
       // the final round's `usage` (what this did) reported a fraction of what
@@ -789,7 +1071,30 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       };
 
       for (;;) {
-        const opts = { ...base, system, messages: history, prompt, tools: toolSchemas };
+        // Stop and SAY so. A turn that reaches its horizon has usually done
+        // real work; ending silently would paint an empty answer over it,
+        // which is the same "(empty response)" failure the guards below exist
+        // to prevent.
+        if (round >= maxRounds) {
+          const note =
+            `[stopped at ${maxRounds} tool rounds` +
+            `${turnUsage.total_tokens ? `, ${turnUsage.total_tokens.toLocaleString()} tokens` : ''}` +
+            `. Ask again to continue, or raise ` +
+            `${autonomous ? 'AEGIS_AUTONOMOUS_MAX_ROUNDS' : 'AEGIS_CHAT_MAX_ROUNDS'}.]`;
+          if (rootOnDelta) rootOnDelta({ delta: `\n\n${note}` });
+          return withTurnUsage({
+            model: base.model,
+            choices: [{ message: { content: note }, finish_reason: 'length' }],
+            stoppedOnRounds: true,
+          });
+        }
+        round += 1;
+        // `round === 1` is the user's own ask, and the ONLY dispatch allowed to
+        // carry the deep-recall opt-in: the deep tier embeds the query once per
+        // dispatch, so leaving it on for an agentic turn would charge one
+        // embedding per tool round instead of one per turn (the retries below
+        // clear it explicitly, being re-dispatches inside round 1).
+        const opts = { ...base, system, messages: history, prompt, tools: toolSchemas, recallDeep: base.recallDeep && round === 1 };
         let res;
         try {
           res = await dispatch(cls, opts);
@@ -833,7 +1138,17 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
           res = await dispatch(cls, {
             ...opts,
             singlePass: true,
+            // A re-dispatch, not a new ask: the deep tier's embedding was
+            // bought by round 1, and buying it again here would charge a
+            // second one for the same context.
+            recallDeep: false,
             maxTokens: doubledBudget(opts.maxTokens),
+            // Doubling applies to the pooled path only when the caller stated a
+            // number. With none stated, the server's effort ladder IS the
+            // budget, and sending doubledBudget's 8192 floor would *lower* it
+            // (aegis1 reads max_tokens as a ceiling over the ladder) — a
+            // "double the budget" retry that halves it at high effort.
+            statedMaxTokens: opts.statedMaxTokens ? doubledBudget(opts.statedMaxTokens) : undefined,
           });
           addUsage(res);
         }
@@ -858,6 +1173,9 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
           res = await dispatch(cls, {
             ...opts,
             singlePass: true,
+            // Same as the truncation retry above: this pass writes up findings
+            // already in `history`, and a fresh embedding buys it nothing.
+            recallDeep: false,
             messages: history,
             prompt: '',
             tools: [],
@@ -891,7 +1209,8 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         for (const call of calls) {
           const result = call.name === T.SUBAGENT_TOOL
             ? await runSubagent(call.args, {
-                cls, model, maxTokens, mode: payload && payload.mode, parentSignal: signal, depth, rootSessionId, rootOnDelta,
+                cls, model, statedMaxTokens, effort: payload && payload.effort,
+                mode: payload && payload.mode, parentSignal: signal, depth, rootSessionId, rootOnDelta,
               })
             : await gatedExecuteTool(call, { toolCtx, rootSessionId, rootOnDelta, signal });
           // A subagent's spend rides back on its tool result (see runSubagent).
@@ -921,7 +1240,7 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
    */
   async function runSubagent(
     { description, subagent_type, prompt: subPrompt } = {},
-    { cls, model, maxTokens, mode, parentSignal, depth, rootSessionId, rootOnDelta } = {}
+    { cls, model, statedMaxTokens, effort, mode, parentSignal, depth, rootSessionId, rootOnDelta } = {}
   ) {
     const task = String(subPrompt || description || '').trim();
     if (!task) return { ok: false, error: 'task requires a prompt' };
@@ -945,8 +1264,17 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
       // silently hanging behind this call's no-op onDelta below.
       const res = await chat(
         {
-          class: cls, model, maxTokens, mode, system, prompt: task, sessionId: subSessionId, depth: (depth || 0) + 1,
+          class: cls, model, mode, system, prompt: task, sessionId: subSessionId, depth: (depth || 0) + 1,
           rootSessionId, rootOnDelta,
+          // The parent's budget AUTHORITY is forwarded, not the number it
+          // implies. `maxTokens` is deliberately absent: it is the rung this
+          // turn derived from `effort`, and a re-entry that hands it back gets
+          // read as the caller's own cap (statedCapOf). The rung itself rides
+          // along as `effort`, which is what aegis1 sizes the fan-out and its
+          // ladder from — so a subagent now runs at the effort the user chose
+          // instead of at a number that only meant anything for this model id.
+          statedMaxTokens,
+          effort,
         },
         () => {}
       );
@@ -985,4 +1313,4 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
   };
 }
 
-module.exports = { CLASSES, createLocalEngine, extractToolCalls, parseArgs };
+module.exports = { CLASSES, createLocalEngine, extractToolCalls, parseArgs, reasoningBudget };