aegis-desktop 0.8.35 → 1.0.0

package/README.md

@@ -101,6 +101,17 @@ the models that key unlocks appear as their own entries, one per provider.
    startup, and a provider with no key saved in Settings is resolved from it.
 3. Select the **Bring your own key** class and pick a model.
 
+**A model the catalogue does not name yet.** Vendors ship models faster than any
+client release, and the relay forwards whatever model string it is handed — so
+Settings ends with an **Add model** row (provider + model id + *Add model*). It
+writes the same `~/.aegiscode/models.json` the CLI's `/model-add` writes, so a
+model added here appears in the terminal's `/models` immediately and one added
+there appears in this picker on its next refresh; the row prints the file path,
+which is also the bulk-edit path. The provider id is offered from the live
+catalogue but you may type one, and a provider the relay takes no key for is
+refused rather than stored (a declaration nothing can attach a key to would show
+up in no picker at all). Each declared model gets a **Remove** row.
+
 **What it costs.** AEGIS pays your provider nothing on this lane, so there is no
 provider cost to take a margin on — instead your AEGIS account is charged a flat
 **handling fee** per 1k tokens, for the routing, prompt assembly, caching, tool

package/lib/deep-link.js

@@ -14,6 +14,36 @@
 const PROTOCOL = 'aegis';
 const SCHEME_PREFIX = `${PROTOCOL}://`;
 
+/**
+ * Ceilings on the two values a *remote* caller controls.
+ *
+ * Any web page or any other app on the machine can hand the OS an `aegis://`
+ * URL, so both fields are attacker-chosen input on a channel nobody authenticates
+ * (there is no "is this link from the user?" check, and there cannot be one for
+ * a custom scheme). Bounding them keeps a hostile link from parking megabytes of
+ * text in the composer, from filling the window with a wall of pre-filled prompt,
+ * or from using the deep link as a bulk data channel into a session that can run
+ * tools. The renderer pre-fills rather than auto-sends (renderer/app.js
+ * handleDeepLink), so the cost is bounded, but a pre-filled prompt is still the
+ * most direct route from "a page I visited" to "text the user is invited to send
+ * to a model with tools on".
+ *
+ * These are generous on purpose: a real hand-written link is a sentence or two.
+ */
+const MAX_PROMPT_LENGTH = 2000;
+/** Session ids are uuids (36 chars); the slack is for a future format, not a payload. */
+const MAX_SESSION_ID_LENGTH = 128;
+/**
+ * …and the charset is pinned too, because this id does not stay a string: the
+ * renderer's `open` handler hands it to openSession(), which loads the session
+ * by name. A hostile link could otherwise offer `../../…` or an absolute path
+ * and have the *renderer* ask main to open whatever that resolves to. Ids this
+ * app mints are `[0-9a-f-]`; anything outside a conservative id alphabet is not
+ * one of ours, so it is rejected rather than escaped or repaired.
+ */
+const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+
+
 /** True for any string that looks like our protocol, cheap enough to filter
  *  argv with before the full URL parse (which throws on most argv entries —
  *  flags, file paths — so callers should not run it against every arg). */
@@ -44,11 +74,15 @@ function parseDeepLinkUrl(url) {
   if (action === 'open') {
     const sessionId = parsed.searchParams.get('session');
     if (!sessionId) return null;
+    if (sessionId.length > MAX_SESSION_ID_LENGTH) return null;
+    if (!SESSION_ID_PATTERN.test(sessionId)) return null;
     return { action: 'open', sessionId };
   }
 
   if (action === 'new') {
-    return { action: 'new', prompt: parsed.searchParams.get('prompt') || '' };
+    const prompt = parsed.searchParams.get('prompt') || '';
+    if (prompt.length > MAX_PROMPT_LENGTH) return null;
+    return { action: 'new', prompt };
   }
 
   return null;

package/lib/local/autonomous.js

@@ -73,6 +73,83 @@ const MAX_ROUND_STOPS = 3;
  */
 const WRITE_TOOLS = new Set(['writeFile', 'editFile']);
 
+// ── Auto mode and the round horizon ─────────────────────────────────────────
+//
+// The two halves of "auto mode" the upstream engine (aegiscodex-dev) defines
+// are independent, and a host that wires only one of them is *not* running auto
+// mode — it is running "no approval cards", which is half the feature and all
+// the friction:
+//
+//   1. no approval keystroke per mutating tool call;
+//   2. a turn that hits its round horizon is EXTENDED silently a few times
+//      before a human is asked.
+//
+// (1) is the posture (the desktop's Tool-approvals switch, the CLI's
+// /automode); (2) needs the arithmetic below, and the plugin's Electron host
+// had none of it — with auto mode ON, every horizon hit still raised the
+// blocking round card, which is precisely the question auto mode exists to stop
+// asking ("12 rounds — keep going?" answered the same way every time).
+//
+// Ported verbatim from the engine's src/autonomous.js (DEFAULT_AUTO_CONTINUES,
+// autoContinueLimit, autoRoundsDefault, autoContinuePlan) rather than vendored,
+// because this repo hosts no build of that ESM module — but with the SAME
+// numbers and the SAME env knobs, so a turn behaves identically in either
+// client. cli/src/chatflow.js carries the third copy, which is what the CLI
+// presenter uses to answer the ask.
+
+/** Automatic continuations an attended turn may take while auto mode is on. */
+const DEFAULT_AUTO_CONTINUES = 3;
+
+/**
+ * The auto-continue allowance, honouring AEGIS_AUTO_CONTINUE_MAX.
+ *
+ * Bounded and pure, and a garbage value falls back to the default rather than
+ * to 0: an unparseable env var must not silently switch auto mode off, because
+ * the visible symptom of that ("why is it asking me again?") points nowhere
+ * near the environment.
+ */
+function autoContinueLimit(env = process.env) {
+  const n = Number.parseInt(env && env.AEGIS_AUTO_CONTINUE_MAX, 10);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_AUTO_CONTINUES;
+}
+
+/**
+ * Values of AEGIS_AUTO_ROUNDS that mean "start in manual mode". Anything else —
+ * unset, empty, a typo like `flase` — leaves auto mode's default in place, so a
+ * misspelt opt-out cannot silently disable the mode the operator asked for.
+ * Same set, same reasoning, as the engine's AUTO_ROUNDS_OFF.
+ */
+const AUTO_ROUNDS_OFF = new Set(['0', 'false', 'off', 'no']);
+
+/** False only when AEGIS_AUTO_ROUNDS explicitly says so. */
+function autoRoundsDefault(env = process.env) {
+  const raw = env && env.AEGIS_AUTO_ROUNDS;
+  if (raw === undefined || raw === null) return true;
+  const val = String(raw).trim().toLowerCase();
+  if (!val) return true;
+  return !AUTO_ROUNDS_OFF.has(val);
+}
+
+/**
+ * Decide what one round-horizon ask becomes while auto mode is on.
+ *
+ * Pure, because this is budget arithmetic on a keystroke-less path: the caller
+ * only renders the answer and must not be trusted to keep the count. `used` is
+ * the running tally the caller holds and echoes back, so an ask that IS shown
+ * to the human resets it — the human was asked, so the next block of automatic
+ * continuations starts clean.
+ *
+ *   { auto: true,  used: n }  → answer the ask "yes" without a dialog
+ *   { auto: false, used: n }  → show the real ask (allowance spent, or off)
+ */
+function autoContinuePlan({ on = false, used = 0, limit = DEFAULT_AUTO_CONTINUES } = {}) {
+  const cap = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : DEFAULT_AUTO_CONTINUES;
+  const spent = Number.isFinite(used) && used > 0 ? Math.floor(used) : 0;
+  if (!on) return { auto: false, used: spent, cap };
+  if (spent >= cap) return { auto: false, used: 0, cap };
+  return { auto: true, used: spent + 1, cap };
+}
+
 /** The path a file-writing tool call names, in either spelling the engine uses. */
 function writtenPath(tool) {
   const args = (tool && tool.args) || {};
@@ -906,6 +983,10 @@ module.exports = {
   isAutonomousRequest,
   maxRounds,
   withRoundHorizon,
+  DEFAULT_AUTO_CONTINUES,
+  autoContinueLimit,
+  autoRoundsDefault,
+  autoContinuePlan,
   resolveModel,
   ignoredEnvModel,
   resolveEffort,

package/lib/local/engine.js

@@ -305,6 +305,36 @@ function requireSharedByokCatalog() {
   throw last;
 }
 
+/**
+ * The models the USER declares (`client/user-models.js`) — resolved exactly as
+ * the two modules above, and required here for the same reason: it is the ONE
+ * store the CLI's `/model-add` and this window's Settings row both write, so a
+ * model added in the terminal is a row in this picker and vice versa. A second
+ * implementation would be a second file, and "the two hosts show one account
+ * two different model lists" is the defect class this resolution rule exists
+ * to end.
+ *
+ * Unlike the two catalog modules this one touches the disk (it reads
+ * `$AEGISCODE_HOME/models.json`), which is why it is required through the
+ * staged-tree fallback like any other shared module — the packaged app has no
+ * `client/` beside it.
+ */
+function requireSharedUserModels() {
+  const candidates = [
+    () => require('../../../client/user-models.js'),
+    () => require('../../vendor/user-models.js'),
+  ];
+  let last = null;
+  for (const load of candidates) {
+    try {
+      return load();
+    } catch (err) {
+      last = err;
+    }
+  }
+  throw last;
+}
+
 /**
  * How long a turn waits for the working-tree lock before running anyway.
  *
@@ -578,6 +608,12 @@ const { offerableCatalog } = requireSharedBrain();
  * provider row the other does not.
  */
 const { withByokAdditions } = requireSharedByokCatalog();
+const {
+  withUserModels,
+  load: loadUserModels,
+  addUserModel,
+  removeUserModel,
+} = requireSharedUserModels();
 
 // ── Agent-loop helpers ──────────────────────────────────────────────────────
 
@@ -652,6 +688,91 @@ function isTruncated(res) {
   return reason === 'length' || reason === 'max_tokens';
 }
 
+/**
+ * The hidden chain-of-thought a completion carried, read from every wire shape
+ * that reports one. DeepSeek returns `message.reasoning_content`, OpenAI's
+ * o-series/gpt-5 shape returns `message.reasoning`, and the Anthropic parser
+ * folds thinking into content blocks. All three are the same thing here: tokens
+ * the model spent out of the same budget as its answer.
+ */
+function reasoningTextOf(res) {
+  if (!res) return '';
+  const choice = res.choices && res.choices[0];
+  const msg = (choice && choice.message) || {};
+  if (Array.isArray(msg.content)) {
+    const blocks = msg.content
+      .filter((b) => b && (b.type === 'thinking' || b.type === 'reasoning'))
+      .map((b) => b.thinking || b.text || '')
+      .join('');
+    if (blocks) return blocks;
+  }
+  const fromContent = msg.content && typeof msg.content === 'object' ? msg.content.reasoning_content : '';
+  const candidates = [
+    msg.reasoning_content,
+    msg.reasoning,
+    choice && choice.reasoning_content,
+    res.reasoning_content,
+    res.reasoning,
+    fromContent,
+  ];
+  for (const c of candidates) if (typeof c === 'string' && c) return c;
+  return '';
+}
+
+/**
+ * The empty turn `isTruncated()` cannot see, and the reason this error survived
+ * a truncation retry that was already in place: a reasoning model that spends
+ * the budget on hidden chain-of-thought and then finishes with NO visible text
+ * still reports `finish_reason: 'stop'` — the provider considers the call
+ * complete, because to it the model did stop, it just stopped while thinking.
+ * Measured live on byok/deepseek-v4-flash: `stop` + empty content + non-empty
+ * `reasoning_content`, which fell straight through both retry gates to
+ * emptyTurnError. Reasoning tokens and answer tokens share one budget, so the
+ * recovery is identical to a 'length' cut: buy room and ask once more.
+ */
+function reasonedButSilent(res) {
+  return !assistantText(res) && reasoningTextOf(res) !== '';
+}
+
+/**
+ * The rung a reasoning-only retry is raised to. Every reasoning retry is paid
+ * for out of the same budget twice — the chain-of-thought is paid for again
+ * before a single visible word can be written — so a rung that merely doubled
+ * (the 8k floor -> 16k) still finished silent: the floor is what an unstated
+ * budget yields, and it is the rung the live failure had already exhausted.
+ */
+const REASONING_RETRY_FLOOR = 32768;
+
+/**
+ * The one budget decision every empty-turn retry makes, in one place: is the
+ * number we hold ours (a rung we derived, which a retry may raise) or the
+ * caller's (a deliberate cap the retry may only double)?
+ *
+ * It matters exactly here. The floor above is a floor on OUR rung; applying it
+ * to a stated cap would turn the flow lane's deliberate 1024-token ceiling into
+ * 32768 because the model happened to think out loud — the same "a guessed
+ * number goes on the wire as a ceiling" bug statedCapOf() exists to prevent.
+ */
+function retryBudgetFor(opts, reasoningOnly) {
+  const doubled = doubledBudget(opts.maxTokens);
+  if (!reasoningOnly) return doubled;
+  // Which number is this? A budget that is one of EFFORT_TOKEN_BUDGET's own
+  // rungs (8192/16384/32768) is the rung this call was sized at, so a reasoning
+  // retry may raise it to the top of the ladder — that is the live failure this
+  // exists for: 16384 burned on hidden chain-of-thought, finish_reason 'stop',
+  // empty content. Any OTHER number belongs to someone who chose it (the flow
+  // lane's deliberate 1024, a caller's own 4096), and doubling is as far as a
+  // retry may go: promoting it by an order of magnitude would put a ceiling the
+  // user never asked for on the wire.
+  return ladderRung(opts.maxTokens) ? Math.max(doubled, REASONING_RETRY_FLOOR) : doubled;
+}
+
+/** Is this budget one of the effort ladder's own rungs (a size WE derived)? */
+function ladderRung(maxTokens) {
+  const n = Number(maxTokens);
+  return Number.isFinite(n) && Object.values(EFFORT_TOKEN_BUDGET).includes(n);
+}
+
 /**
  * Double a budget for the one-shot truncation retry. A budget the caller set
  * on purpose (the flow lane's deliberate 1024-token cap, say) is merely
@@ -701,6 +822,62 @@ const EMPTY_TURN_NUDGE =
   'No tools are available in this reply, so do not call any: respond in plain ' +
   'prose or markdown.';
 
+/**
+ * The nudge for an empty round that was NOT really empty: the model spent it
+ * thinking. A reasoning model that burns its budget on hidden chain-of-thought
+ * and stops without writing a visible word (`finish_reason: 'stop'`, empty
+ * content, non-empty `reasoning_content`) is the normal shape of this failure on
+ * DeepSeek, and the generic nudge above does not describe it — "write your answer
+ * now" invites the same reasoning pass a second time, because nothing told the
+ * model that the thinking was the problem.
+ *
+ * Naming the failure IS the fix, and it is the upstream engine's own last resort
+ * (`src/backend.js`, the `thoughtOnly` recovery round). Buying budget is the
+ * other lever, already tried below; when that has failed the budget is not what
+ * is wrong, so the ask changes instead: answer WITHOUT thinking first.
+ */
+const THOUGHT_ONLY_NUDGE =
+  'Your previous round was spent entirely on hidden reasoning and produced no visible reply. ' +
+  'Answer the user directly and briefly now. Do not reason, explain, or think first — write only ' +
+  'the answer, no tools.';
+
+/**
+ * The last ask of the recovery ladder, for a turn that stayed silent even after
+ * being told not to think first.
+ *
+ * A model that is going to reason anyway will reason whatever the nudge says, so
+ * the final round stops asking it not to: the ask becomes "say anything usable
+ * about what you already have", which a model that has demonstrably read the
+ * context can always satisfy. Producing a slightly thin write-up is strictly
+ * better than the alternative — the transcript keeps the answer, and the user
+ * can ask for detail on the one point that was skimped, in a turn where the
+ * material is already in context.
+ */
+const FINAL_ANSWER_NUDGE =
+  'Write your answer now, in plain prose, using only what is already in this conversation. ' +
+  'If your information is incomplete, say what you have and what is missing — an incomplete ' +
+  'answer is the expected outcome here and is better than none. No tools, no preface.';
+
+/**
+ * How many EXTRA calls an empty write-up round is worth before the turn is
+ * declared failed.
+ *
+ * The upstream engine spends additional calls on a silent round rather than
+ * telling the reader to go and change a setting (`src/backend.js`'s thoughtOnly
+ * recovery), and this is the same trade, made explicit because the trade is the
+ * whole point of the number: an extra dispatch costs tokens, a failed turn costs
+ * the entire investigation the tool log on screen paid for. Two calls — one
+ * after the budget-retry above, one after the ask changes — is where the curve
+ * flattens: measured on byok/deepseek-v4-flash, a round that reasons and stays
+ * silent either answers on the first changed ask or is not going to answer at
+ * all, because the failure is the model's habit and not the wording.
+ *
+ * Crucially, every one of these rounds runs with `tools: []` on `synthesisOpts`:
+ * they re-ask for the write-up out of a context that already holds the findings,
+ * so "more calls" can never mean "do the investigation again".
+ */
+const RECOVERY_ROUNDS = 2;
+
 /**
  * Last resort for a turn that is still empty after the synthesis pass.
  *
@@ -713,12 +890,29 @@ const EMPTY_TURN_NUDGE =
  * real tool log on screen, keeps the transcript honest, and names the cause
  * (renderer prints `Error: <message>`).
  */
-function emptyTurnError({ cls, model, maxTokens, finishReason }) {
+function emptyTurnError({ cls, model, finishReason, reasoningChars, effort, recoveryRounds }) {
+  const calls = Number(recoveryRounds) || 0;
   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 || '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.'
+    `The model returned no answer after ${cls}/${model} was asked to summarise its results` +
+      (calls
+        ? `, and ${calls} extra recovery call${calls === 1 ? '' : 's'} with a larger budget ` +
+          'and a changed ask came back empty too'
+        : '') +
+      ` (stop reason: ${finishReason || 'none'}` +
+      `${effort ? `, effort: ${effort}` : ''}` +
+      `${reasoningChars ? `, hidden reasoning: ${reasoningChars} chars and no visible text` : ''}). ` +
+      (reasoningChars
+        ? // Deliberately NOT "raise the Effort rung". The budget was already taken
+          // out of the equation before this error could be reached: the recovery
+          // calls above ran at the top of the ladder, so pointing at the ceiling
+          // would send the reader to change the one setting that is already
+          // maxed out. The unchanged thing is the model's habit of answering
+          // inside its head, and that is what gets named.
+          'Every one of those calls spent its output on hidden reasoning instead of writing a ' +
+          'word, so this is the model rather than the budget: pick a model that answers without ' +
+          'a thinking pass, or ask for a smaller piece of work.'
+        : 'No visible text came back from any of those calls. Send the request again, in smaller ' +
+          'pieces, or from a different model.')
   );
   err.status = 502;
   return err;
@@ -1207,7 +1401,7 @@ function createLocalEngine({
         // of `providers` — the model list built just below, the renderer's
         // per-provider Settings rows, and the CLI's own `/byok` listing when it
         // runs on this engine — sees one list instead of three opinions.
-        providers = withByokAdditions((data && data.providers) || []);
+        providers = withUserModels(withByokAdditions((data && data.providers) || []));
         // The handling fee AEGIS adds on top of the caller's vendor bill. It is
         // the server's own published rate (services/pricing.price_byok_call) and
         // is passed through untouched — never re-derived here, because a client
@@ -2032,8 +2226,9 @@ function createLocalEngine({
         // double up in the renderer's live view. When text *has* arrived the
         // turn is not empty — the answer is merely truncated — and a retry
         // would stream it a second time onto the same bubble.
-        if (!truncationRetried && !assistantText(res) && isTruncated(res)) {
+        if (!truncationRetried && !assistantText(res) && (isTruncated(res) || reasonedButSilent(res))) {
           truncationRetried = true;
+          const reasoningOnly = reasonedButSilent(res);
           // singlePass: this retry buys *budget*, not a second investigation.
           // The fan-out's workers would re-run the whole task from scratch for
           // it — 3 extra reasoning passes + a synthesis — which is the opposite
@@ -2046,7 +2241,11 @@ function createLocalEngine({
             // bought by round 1, and buying it again here would charge a
             // second one for the same context.
             recallDeep: false,
-            maxTokens: doubledBudget(opts.maxTokens),
+            // A reasoning-only completion gets the high rung AND high effort:
+            // the model is about to re-pay for the same chain-of-thought, and
+            // on DeepSeek that pair is what actually moves the ceiling.
+            effort: reasoningOnly ? 'high' : opts.effort,
+            maxTokens: retryBudgetFor(opts, reasoningOnly),
             // 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
@@ -2073,14 +2272,20 @@ function createLocalEngine({
           // no gathered context to rescue, so a bare completion is just that.
           synthesisDone = true;
           foldPromptIntoHistory();
-          history.push({ role: 'user', content: EMPTY_TURN_NUDGE });
+          // The nudge is chosen by what the empty round actually WAS, not by the
+          // fact that it was empty. A round that spent its budget on hidden
+          // reasoning and stopped without writing a word needs to be told not to
+          // think; the generic wording invites the same silent pass a second
+          // time, which is precisely how a recoverable turn became
+          // `emptyTurnError` on byok/deepseek-v4-flash (2026-10-11).
+          history.push({ role: 'user', content: reasonedButSilent(res) ? THOUGHT_ONLY_NUDGE : EMPTY_TURN_NUDGE });
           // singlePass: same reasoning as the truncation retry above, and it is
           // the same comment's literal promise ("force the summary out of the
           // context it already holds"). Escalating a write-up back into the
           // worker fan-out asked three fresh workers to redo an investigation
           // whose findings are already in `history`, at 4x the cost, to produce
           // a paragraph the model had all the material for.
-          res = await dispatch(cls, {
+          const synthesisOpts = {
             ...opts,
             singlePass: true,
             // Same as the truncation retry above: this pass writes up findings
@@ -2089,7 +2294,13 @@ function createLocalEngine({
             messages: history,
             prompt: '',
             tools: [],
-          });
+          };
+          res = await dispatch(cls, synthesisOpts);
+          // The ceiling and the rung of the last dispatch that came back empty,
+          // so the failure below reports the call that actually failed instead of
+          // the original one it was retried away from.
+          let lastBudget = synthesisOpts.maxTokens;
+          let lastEffort = synthesisOpts.effort;
           addUsage(res);
           // Same guard again: a cancel landing during the synthesis pass
           // resolves empty too, and without this check it fell through to
@@ -2097,12 +2308,108 @@ function createLocalEngine({
           // "no answer" failure over what was actually just the user hitting
           // Cancel.
           if (signal.aborted) return withTurnUsage(res);
+          // The SAME truncation retry the main round gets, one level down: the
+          // write-up pass is itself a fresh dispatch billed against `opts.maxTokens`,
+          // and a reasoning model can burn that whole budget on hidden
+          // chain-of-thought a SECOND time while composing the summary — history
+          // is bigger than round 1's, so if anything this pass is more likely to
+          // need the room. Without this, "the synthesis pass also got
+          // truncated" and "the model is simply done" were indistinguishable —
+          // both threw the same emptyTurnError — even though the first is
+          // recoverable with the exact one-line fix already proven above.
+          if (!assistantText(res) && (isTruncated(res) || reasonedButSilent(res))) {
+            const reasoningOnly = reasonedButSilent(res);
+            lastBudget = retryBudgetFor(synthesisOpts, reasoningOnly);
+            lastEffort = reasoningOnly ? 'high' : synthesisOpts.effort;
+            res = await dispatch(cls, {
+              ...synthesisOpts,
+              effort: lastEffort,
+              maxTokens: lastBudget,
+              statedMaxTokens: synthesisOpts.statedMaxTokens
+                ? doubledBudget(synthesisOpts.statedMaxTokens)
+                : undefined,
+            });
+            addUsage(res);
+            if (signal.aborted) return withTurnUsage(res);
+          }
+          // ── The recovery ladder: extra calls, not a verdict ────────────────
+          // Everything above bought a bigger ceiling; this changes the ASK —
+          // and repeats it — because a round that reasoned and then stayed
+          // silent has already been handed more room and still did not write a
+          // word.
+          //
+          // This is the upstream engine's own trade (`src/backend.js`, the
+          // `thoughtOnly` recovery round): spend another call rather than hand
+          // the reader a red "backend error: … raise the Effort rung" over work
+          // that is finished and already sitting in `history`. Telling someone
+          // to go and raise a setting is not a recovery, and the ceiling it
+          // points at was raised by the retry above — so the ladder spends
+          // calls, with a variant of the ask each time, and only reports
+          // failure when every one of them comes back empty as well.
+          //
+          // Bounded by construction: `RECOVERY_ROUNDS` caps the calls,
+          // `synthesisDone` is already true, and each nudge JOINS `history`
+          // rather than replacing it — every round here runs with `tools: []`,
+          // so a round is a re-ask out of context the model already holds and
+          // can never become a fresh investigation.
+          //
+          // The ceiling lift below is computed ONCE, not per round. A ladder
+          // that doubled the budget each time would turn "two more calls" into
+          // "two more calls at double the price" for a model whose problem is
+          // demonstrably not the price, and Math.max keeps it monotone: for a
+          // rung this is the top of the ladder, and a number a previous retry
+          // already raised past it (a caller's doubled cap) is never lowered.
+          const ladderBudget = (() => {
+            const owned = Number(lastBudget) || 0;
+            // No number in hand — the caller stated none and the model is not a
+            // reasoning model, so `reasoningBudget()` sends no `max_tokens` at
+            // all and the provider's own limit governs. Inventing one here
+            // (retryBudgetFor's 8192 floor) would put a ceiling on the wire that
+            // nobody asked for, which is the very defect this file's budget
+            // comments were written about. The ladder's extra call is then the
+            // same price as the call it repeats, and only the ask changes.
+            if (!owned) return lastBudget;
+            const ask = { maxTokens: lastBudget };
+            if (synthesisOpts.statedMaxTokens) ask.statedMaxTokens = synthesisOpts.statedMaxTokens;
+            return Math.max(owned, retryBudgetFor(ask, true));
+          })();
+          let recoveryRounds = 0;
+          while (!assistantText(res) && recoveryRounds < RECOVERY_ROUNDS && !signal.aborted) {
+            const reasoningOnly = reasonedButSilent(res);
+            recoveryRounds += 1;
+            history.push({
+              role: 'user',
+              content: reasoningOnly
+                ? recoveryRounds === 1
+                  ? THOUGHT_ONLY_NUDGE
+                  : FINAL_ANSWER_NUDGE
+                : EMPTY_TURN_NUDGE,
+            });
+            if (reasoningOnly) lastEffort = 'high';
+            lastBudget = ladderBudget;
+            res = await dispatch(cls, {
+              ...synthesisOpts,
+              messages: history,
+              effort: lastEffort,
+              maxTokens: lastBudget,
+              statedMaxTokens: synthesisOpts.statedMaxTokens
+                ? doubledBudget(synthesisOpts.statedMaxTokens)
+                : undefined,
+            });
+            addUsage(res);
+            if (signal.aborted) return withTurnUsage(res);
+          }
           if (!assistantText(res)) {
             throw emptyTurnError({
               cls,
               model,
-              maxTokens: opts.maxTokens,
+              // What the LAST call looked like, and how many extra calls the
+              // ladder already spent: the report describes the call that failed
+              // rather than the first one it was retried away from.
+              effort: lastEffort,
+              recoveryRounds,
               finishReason: finishReasonOf(res),
+              reasoningChars: reasoningTextOf(res).length,
             });
           }
           return withTurnUsage(res);
@@ -2260,6 +2567,21 @@ function createLocalEngine({
     clearSessionApprovals,
     settings,
     unloadLocalModels,
+    // The user's own model declarations (`$AEGISCODE_HOME/models.json`), read,
+    // added and removed through ONE implementation because THREE faces write
+    // them: the desktop's Settings row (via main.js's model dispatch), the
+    // CLI's `/model-add`, and the user's own editor. `userModels()` returns
+    // `{ dir, file, map, invalid }` so a host can SHOW where the file is and
+    // name the rows it refused (`invalid`), instead of a declaration vanishing
+    // into a picker that looks like the feature did nothing.
+    //
+    // Add/remove THROW on a malformed provider or model id (that is the point —
+    // an id the relay would forward to a vendor 404s on the user's first turn,
+    // where a rejected input 404s never), so every caller surfaces the message
+    // rather than storing it.
+    userModels: () => loadUserModels(),
+    addUserModel: (provider, model) => addUserModel(provider, model),
+    removeUserModel: (provider, model) => removeUserModel(provider, model),
   };
 }