aegiscode 6.5.4 → 6.5.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegiscode",
   "productName": "AEGIS Code",
-  "version": "6.5.4",
+  "version": "6.5.6",
   "description": "aegiscode \u2014 the command-line version of AEGIS Desktop. The shared tool surface in your shell, over the same thin transport and tool registry as the MCP plugin and the desktop app. Ships transport + UI only; no brain.",
   "author": {
     "name": "AEGIS Code",

package/scripts/predist.mjs

@@ -37,6 +37,7 @@ const VENDOR = path.join(CLI_DIR, 'vendor');
 /** repo-relative -> staged location (same relative shape, under vendor/) */
 const FILES = [
   'client/aegis.js',
+  'client/update.js',
   'client/foreign-memory.js',
   // The account credential store and the unified session store. Shared with the
   // desktop app and the MCP plugin so all three see one key and one session

package/src/app.js

@@ -65,6 +65,26 @@ function defaultSystemPrompt() {
   return _defaultSystem || undefined;
 }
 
+// The engine accepts exactly 'once' | 'session' and coerces anything else to
+// 'deny' (vendor/desktop/lib/local/engine.js → respondApproval). Bridging the
+// vocabularies here, rather than trusting every prompter to speak the engine's
+// dialect, is what stops an approval from silently becoming a denial. The
+// failure mode is invisible from the outside: the tool is refused, the model
+// is told the user declined, and it retries against a gate that can only ever
+// say no — the turn burns its whole budget.
+//
+// Module scope on purpose: this must exist before createApp() runs, because it
+// is re-exported for the conformance tests. A nested copy here previously left
+// the export binding undefined and threw on require.
+function normalizeDecision(decision) {
+  const v = typeof decision === 'string' ? decision.trim().toLowerCase() : '';
+  if (v === 'session') return 'session';
+  if (v === 'once' || v === 'allow' || v === 'yes' || v === 'approve' || v === 'approved') {
+    return 'once';
+  }
+  return 'deny';
+}
+
 function createApp(options = {}) {
   const opts = {
     model: null,
@@ -125,6 +145,15 @@ function createApp(options = {}) {
     // pinning one would make every turn cost what that rung grants.
     effort: null,
     thinking: false,
+    // Deep recall (`aegis_recall_deep`) — the metered tier of the read: brain
+    // corrections plus the semantic answer cache, and the answer cache costs
+    // one provider embedding per turn (aegis1 app.py:8367 →
+    // services/brain_memory.py find_cached_answer). This host recalls on every
+    // turn already and pays per turn, so the deep tier is NEVER inferred: it is
+    // false here, `/memory-deep on` is the only thing that flips it, and that
+    // choice is deliberately NOT persisted — a flag that meters every turn must
+    // not survive into a session where nobody asked for it.
+    recallDeep: false,
     themeIndex: opts.light ? 2 : 1,
     vim: false,
     stream: opts.stream,
@@ -444,6 +473,8 @@ function createApp(options = {}) {
       return Promise.resolve('deny');
     };
 
+    // Vocabulary bridging lives at module scope (see normalizeDecision) so the
+    // same function the tests import is the one the live path calls.
     const onDelta = (chunk) => {
       if (!chunk) return;
       if (chunk.reasoning) {
@@ -472,7 +503,7 @@ function createApp(options = {}) {
         const decide = p.approval || approvalPrompter || denyNoPrompter;
         Promise.resolve(decide(info))
           .catch(() => 'deny')
-          .then((decision) => engine.respondApproval(info.id, decision));
+          .then((decision) => engine.respondApproval(info.id, normalizeDecision(decision)));
       }
     };
 
@@ -497,6 +528,11 @@ function createApp(options = {}) {
           // about what the turn cost. `null` (auto) is omitted so the server
           // infers the rung from the ask.
           effort: commandCtx.effort || undefined,
+          // The deep-recall opt-in travels only when this session turned it on
+          // (`/memory-deep on`). Sent as a literal `true` or not at all: the
+          // engine treats anything but `true` as off, and an omitted field is
+          // what keeps a stray value from ever buying a per-turn embedding.
+          recallDeep: commandCtx.recallDeep === true ? true : undefined,
           // false asks the engine for the buffered (non-stream) wire form, so
           // `--no-stream` and piped runs get a single body rather than SSE.
           stream: commandCtx.stream !== false,
@@ -1352,4 +1388,4 @@ function createApp(options = {}) {
   };
 }
 
-module.exports = { createApp, VERSION };
+module.exports = { createApp, VERSION, normalizeDecision };

package/src/art.js

@@ -89,6 +89,15 @@ const TAGLINE = 'Cloud brain in your shell.';
 // mangle █▓▒░ entirely; on macOS ✦ renders as a double-width emoji. Each pass
 // swaps offending code points 1:1 (same character count per row) so the width
 // maths stays exact and the mark keeps its shape.
+//
+// This table is the ONE stencil source of truth for the product. `theme.js`
+// resolves `GLYPH.star` through `stencilGlyph(STAR, platform)` rather than
+// carrying its own `'✦' → '*'` rule, and `render.js` builds the mark's tint map
+// by stencilling its runes — both had a private copy of the same decision, which
+// is how a stencil edit here could leave the star wide on macOS or the whale
+// untinted on Windows. `test/cli-art-platform.test.mjs` pins all of it.
+const STAR = '✦';
+
 const ASCII_STENCIL = new Map([
   ['█', '#'],
   ['▓', '@'],
@@ -100,7 +109,7 @@ const ASCII_STENCIL = new Map([
   ['▌', '#'],
   ['▝', '#'],
   ['▘', '#'],
-  ['✦', '*'],
+  [STAR, '*'],
   ['·', '.'],
 ]);
 
@@ -111,18 +120,45 @@ const DARWIN_STENCIL = new Map([
   ['▌', '#'],
   ['▝', '#'],
   ['▘', '#'],
-  ['✦', '*'],
+  [STAR, '*'],
 ]);
 
-/** One platform pass over an art block. */
+/** The platforms this mark has a pass for. Linux needs none (see `stencilFor`). */
+const PLATFORMS = ['linux', 'darwin', 'win32'];
+
+/** Every pass, keyed by `process.platform`; a platform with no entry is native. */
+const STENCILS = { darwin: DARWIN_STENCIL, win32: ASCII_STENCIL };
+
+/**
+ * The stencil for a platform, or `null` when its runes need no pass.
+ * @param {string} platform a `process.platform` string
+ */
+function stencilFor(platform) {
+  return STENCILS[platform] || null;
+}
+
+/**
+ * One rune as `platform` renders it — the identity when that platform is native.
+ * Exported so `theme.js`'s glyph table and `render.js`'s tint map are derived
+ * from the stencil instead of restating it.
+ * @param {string} ch
+ * @param {string} [platform]
+ */
+function stencilGlyph(ch, platform = process.platform) {
+  const s = stencilFor(platform);
+  return (s && s.get(ch)) || ch;
+}
+
+/** One platform pass over an art block, for an explicit platform. */
+function portabilityFor(rows, platform) {
+  const s = stencilFor(platform);
+  if (!s) return rows;
+  return rows.map((r) => [...r].map((ch) => s.get(ch) ?? ch).join(''));
+}
+
+/** The mark as the terminal running this process will render it. */
 function portability(rows) {
-  if (process.platform === 'win32') {
-    return rows.map((r) => [...r].map((ch) => ASCII_STENCIL.get(ch) ?? ch).join(''));
-  }
-  if (process.platform === 'darwin') {
-    return rows.map((r) => [...r].map((ch) => DARWIN_STENCIL.get(ch) ?? ch).join(''));
-  }
-  return rows;
+  return portabilityFor(rows, process.platform);
 }
 
 /** The mark that fits the current terminal: side-by-side when there's room. */
@@ -151,8 +187,9 @@ function welcomeArtParts(cols) {
     const n = Math.max(mascot.length, moonWhale.length);
     const rows = [];
     for (let i = 0; i < n; i++) {
-      const li = i + (n - mascot.length);
-      const ri = i + (n - moonWhale.length);
+      // Same bottom-align rule as joinSideBySide — subtract the offset.
+      const li = i - (n - mascot.length);
+      const ri = i - (n - moonWhale.length);
       rows.push([(mascot[li] ?? '').padEnd(L), (moonWhale[ri] ?? '').padEnd(R)]);
     }
     return { rows, width: L + gutter + R, gutter };
@@ -188,8 +225,14 @@ function joinSideBySide(left, right, gutter = 2, align = 'bottom') {
   const R = Math.max(...right.map((r) => [...r].length));
   const n = Math.max(left.length, right.length);
   return Array.from({ length: n }, (_, i) => {
-    const li = align === 'bottom' ? i + (n - left.length) : i;
-    const ri = align === 'bottom' ? i + (n - right.length) : i;
+    // Bottom-align puts each block's LAST row on the output's last row, so a
+    // shorter block starts lower and its index runs *behind* the output index.
+    // Adding the offset instead of subtracting it pushed the shorter block off
+    // the bottom edge and silently dropped its top rows: the moon+whale half,
+    // two rows shorter than the mascot, lost its spout and its top star and
+    // hung two rows below the baseline.
+    const li = align === 'bottom' ? i - (n - left.length) : i;
+    const ri = align === 'bottom' ? i - (n - right.length) : i;
     const l = (left[li] ?? '').padEnd(L);
     const r = (right[ri] ?? '').padEnd(R);
     return l + ' '.repeat(gutter) + r;
@@ -225,7 +268,13 @@ module.exports = {
   WELCOME_TITLE,
   WELCOME_BACK,
   TAGLINE,
+  STAR,
+  PLATFORMS,
+  STENCILS,
+  stencilFor,
+  stencilGlyph,
   portability,
+  portabilityFor,
   welcomeArtFor,
   welcomeArtParts,
   stackVertical,

package/src/chatflow.js

@@ -131,6 +131,50 @@ function resolveToolDone(transcript, t) {
   return m;
 }
 
+/**
+ * Fold one turn's tool events into the counts the end-of-turn summary prints.
+ *
+ * Deterministic and purely local, on purpose. The tail of every turn is the
+ * wrong place to spend a model call: it would bill the reader for a restatement
+ * of work they have already paid to have done, and it would arrive after a
+ * network round-trip instead of at the instant the turn ends. The data needed
+ * is already in the tool events — the engine hands us `ok` on every call and
+ * the args name every file and command — so the summary is arithmetic, not
+ * inference.
+ *
+ * @param {Array<{ok?:boolean,args?:object}>} tools This turn's tool events, in order.
+ * @returns {{tools:number,failed:number,files:string[],names:string[],more:number,commands:string[]}}
+ */
+function summarizeTurnTools(tools, { maxNames = 3 } = {}) {
+  const files = [];
+  const commands = [];
+  let failed = 0;
+  for (const tool of tools || []) {
+    if (!tool) continue;
+    if (tool.ok === false) failed += 1;
+    const args = tool.args;
+    if (!args || typeof args !== 'object') continue;
+    const file = args.file_path || args.path || args.notebook_path;
+    if (typeof file === 'string' && file && !files.includes(file)) files.push(file);
+    const cmd = args.command;
+    if (typeof cmd === 'string' && cmd.trim()) {
+      // First word only — the binary or builtin that ran, not its whole argv.
+      // "node /a/b/c.mjs --flag" reports as "node", which is what a one-line
+      // summary has room for.
+      const head = cmd.trim().split(/\s+/)[0].split('/').pop();
+      if (head && !commands.includes(head)) commands.push(head);
+    }
+  }
+  return {
+    tools: (tools || []).length,
+    failed,
+    files,
+    names: files.slice(0, maxNames).map((f) => f.split('/').pop()),
+    more: Math.max(0, files.length - maxNames),
+    commands,
+  };
+}
+
 /**
  * Finalize an assistant message's text: append a "(backend error: …)" marker
  * when the turn failed mid-stream, a single "(stopped)" marker on abort, and
@@ -254,6 +298,27 @@ function shortcutsGrid(cols, ctx) {
   ];
 }
 
+/**
+ * The engine's approval vocabulary — and the ONLY tokens that survive
+ * `respondApproval` (see cli/vendor/desktop/lib/local/engine.js). It accepts
+ * 'once' and 'session' and coerces EVERYTHING ELSE to 'deny'.
+ *
+ * This overlay used to answer 'allow': the desktop renderer's word for "yes",
+ * not the engine's. So a user who pressed "1. Yes" was denied anyway — silently,
+ * on every mutating tool, every time. The model then read "the user denied the
+ * request" and retried with a different command, which was denied too, and the
+ * turn burned several rounds of tokens to accomplish nothing. Emitting the
+ * engine's own words is the whole fix; `test/cli-approval.test.mjs` pins it so
+ * the two vocabularies cannot drift apart again.
+ */
+const APPROVE_ONCE = 'once';
+const APPROVE_SESSION = 'session';
+const DENY_TOKEN = 'deny';
+
+/** Choice labels, in overlay order. Index maps 1:1 onto DECISIONS. */
+const APPROVAL_CHOICES = ['Yes', 'Yes, allow for this session', 'No'];
+const APPROVAL_DECISIONS = [APPROVE_ONCE, APPROVE_SESSION, DENY_TOKEN];
+
 /** The tool-approval dialog body. */
 function confirmLines(overlay, cols, ctx) {
   const t = themeOf(ctx);
@@ -278,8 +343,13 @@ function confirmLines(overlay, cols, ctx) {
     const left = active ? span(t.lavender, GLYPH.cursor) : span('', ' ');
     return [left, span(t.gray, ` ${i + 1}. `), span(active ? t.lavender : t.white, label)];
   };
-  lines.push(opt(0, 'Yes'));
-  lines.push(opt(1, 'No'));
+  const toolName = overlay.name || 'this tool';
+  APPROVAL_CHOICES.forEach((label, i) => {
+    // The session option names the tool it will stop asking about, so the
+    // blanket allow is never something the user has to infer.
+    const text = i === 1 ? `Yes, and allow ${toolName} for this session` : label;
+    lines.push(opt(i, text));
+  });
   lines.push([span('', '')]);
   lines.push([span(t.gray, 'Esc to cancel')]);
   return lines;
@@ -358,6 +428,36 @@ function rowLines(msg, cols, ctx, now = Date.now()) {
     out.push(line);
     return out;
   }
+  if (msg.role === 'summary') {
+    // The end-of-turn delta line. Rendered as the LAST row of the turn so the
+    // bottom of the screen answers "what did that actually do?" without the
+    // reader scrolling back up through the tool rows that produced it.
+    const s = msg.counts || {};
+    if (!s.tools) return out;
+    const line = [span(t.dim, GLYPH.hook), span('', '  ')];
+    const bits = [
+      span(t.white, String(s.tools)),
+      span(t.gray, ` ${s.tools === 1 ? 'command' : 'commands'}`),
+    ];
+    if (s.files && s.files.length) {
+      bits.push(span(t.gray, ` ${GLYPH.bullet} `));
+      bits.push(
+        span(t.white, String(s.files.length)),
+        span(t.gray, ` ${s.files.length === 1 ? 'file changed' : 'files changed'}`)
+      );
+    }
+    if (s.failed) {
+      bits.push(span(t.gray, ` ${GLYPH.bullet} `));
+      bits.push(span(t.coral, `${s.failed} failed`));
+    }
+    if (s.names && s.names.length) {
+      const more = s.more ? ` +${s.more}` : '';
+      bits.push(span(t.dim, `  ${s.names.join(', ')}${more}`));
+    }
+    line.push(...bits);
+    out.push(line);
+    return out;
+  }
   if (msg.role === 'meta') {
     // Deliberate divergence from the reference: this client's reason to exist
     // is showing what a turn consumed, so the accounting line is a transcript
@@ -591,6 +691,10 @@ async function runSession(host) {
   let verb = VERBS[0];
   let turnCount = 0;
   let toolSeq = 0;
+  // This turn's raw tool events, kept so the end-of-turn summary can report the
+  // deltas (commands run, files touched, failures) without re-reading the
+  // transcript — the rows are display state, the events are the record.
+  let turnTools = [];
   let suggestionIdx = 0;
   let scroll = 0;
   let anchorEnd = null;
@@ -730,7 +834,6 @@ async function runSession(host) {
 
   let streamedChars = 0;
   const streamedCells = () => streamedChars;
-
   // ── the turn ──
 
   const confirmTool = (info) =>
@@ -738,34 +841,28 @@ async function runSession(host) {
       overlay = { type: 'confirm', name: info.tool || info.name || 'tool', args: info.args || {}, sel: 0, info };
       render();
       (async () => {
+        const choose = (decision) => {
+          overlay = null;
+          render();
+          resolve(decision);
+        };
         for (;;) {
           const key = await nextKey();
           if (key.name === KEY.UP || key.name === KEY.DOWN || key.name === KEY.TAB) {
-            overlay.sel = 1 - overlay.sel;
+            const step = key.name === KEY.UP ? -1 : 1;
+            overlay.sel = (overlay.sel + step + APPROVAL_CHOICES.length) % APPROVAL_CHOICES.length;
             render();
           } else if (key.name === KEY.ENTER) {
-            const yes = overlay.sel === 0;
-            overlay = null;
-            render();
-            resolve(yes ? 'allow' : 'deny');
+            choose(APPROVAL_DECISIONS[overlay.sel] || DENY_TOKEN);
             return;
           } else if (key.name === KEY.ESC || key.name === KEY.CTRL_C) {
-            overlay = null;
-            render();
-            resolve('deny');
+            choose(DENY_TOKEN);
             return;
           } else if (key.name === 'char') {
             const ch = String(key.ch).trim();
-            if (ch === '1') {
-              overlay = null;
-              render();
-              resolve('allow');
-              return;
-            }
-            if (ch === '2') {
-              overlay = null;
-              render();
-              resolve('deny');
+            const idx = Number(ch) - 1;
+            if (Number.isInteger(idx) && idx >= 0 && idx < APPROVAL_DECISIONS.length) {
+              choose(APPROVAL_DECISIONS[idx]);
               return;
             }
           }
@@ -779,6 +876,7 @@ async function runSession(host) {
     startedAt = Date.now();
     streamedChars = 0;
     toolSeq = 0;
+    turnTools = [];
     verb = VERBS[turnCount % VERBS.length];
     abort = new AbortController();
     spinnerTimer = setInterval(() => {
@@ -803,6 +901,7 @@ async function runSession(host) {
       // from one that produced nothing at all.
       reasoning: () => { sawReasoning = true; },
       tool: (tool) => {
+        turnTools.push(tool);
         if (tool.phase === 'run') {
           const n = ++toolSeq;
           const prefix = tool.agent ? `${tool.agent} ▸ ` : '';
@@ -819,8 +918,27 @@ async function runSession(host) {
             },
             { follow: false }
           );
-        } else {
-          resolveToolDone(transcript, tool);
+        } else if (!resolveToolDone(transcript, tool)) {
+          // A host that reports a tool once, after it ran, never opens a
+          // `phase: 'run'` row for resolveToolDone to close — the vendored
+          // local engine does exactly this (one `tool: {name,args,ok}` frame
+          // post-execution). Falling through left the row unwritten, so the
+          // turn silently showed no tool activity at all. Record the finished
+          // tool directly instead.
+          const n = ++toolSeq;
+          push(
+            {
+              role: 'tool',
+              phase: 'done',
+              name: tool.name,
+              args: tool.args,
+              agent: tool.agent,
+              id: tool.id,
+              ok: tool.ok,
+              label: `Ran ${n} ${tool.agent ? `${tool.agent} ▸ ` : ''}${toolLabel(tool.name, n)}`,
+            },
+            { follow: false }
+          );
         }
         scheduleRender();
       },
@@ -909,6 +1027,17 @@ async function runSession(host) {
         },
         { follow: false }
       );
+      // The turn's last row: a one-line delta of what the tools actually did.
+      // Without it the tail of a tool-heavy turn was the accounting row, and
+      // the answer to "what did that change?" was only reachable by scrolling
+      // back up through the tool rows. Follows the viewport EXCEPT when the
+      // reader has scrolled up themselves — scroll is non-zero exactly when
+      // they are mid-read, and yanking them to the bottom then would undo the
+      // scroll they asked for.
+      const counts = summarizeTurnTools(turnTools);
+      if (counts.tools > 0) {
+        push({ role: 'summary', counts }, { follow: scroll === 0 });
+      }
       render();
     }
   };
@@ -1645,6 +1774,7 @@ module.exports = {
   FRAME_MS,
   toolLabel,
   resolveToolDone,
+  summarizeTurnTools,
   finalizeTurnText,
   historyPairs,
   paletteQuery,
@@ -1655,6 +1785,10 @@ module.exports = {
   statusLine,
   shortcutsGrid,
   confirmLines,
+  // The approval vocabulary, exported so a test can assert the CLI only ever
+  // answers with tokens the engine actually honours (see APPROVAL_CHOICES).
+  APPROVAL_CHOICES,
+  APPROVAL_DECISIONS,
   rowLines,
   transcriptLines,
   inputPreviewText,

package/src/commands.js

@@ -1211,6 +1211,25 @@ const COMMANDS = [
     tool: 'aegis_memory_list',
     build: () => ({}),
   },
+  {
+    name: 'memory-deep', aliases: ['recall-deep'], args: ['mode'], hint: '[on|off]', category: 'model',
+    desc: 'Toggle DEEP recall for this session — brain corrections + cached answers (metered: one embedding per turn)',
+    handler: async (c, args) => {
+      const mode = (args.mode || '').toLowerCase();
+      if (mode && !['on', 'off'].includes(mode)) { note(c, 'Usage: /memory-deep [on|off]'); c.render(); return true; }
+      const want = mode === 'on' ? true : mode === 'off' ? false : !(c.ctx.recallDeep === true);
+      c.ctx.recallDeep = want;
+      // Deliberately session-scoped: nothing is written to config.json, because
+      // this flag meters every turn (aegis1 services/brain_memory.py embeds the
+      // query once per turn) and a silent restore on a later launch would bill
+      // for a decision made in a session that has ended. Contrast /thinking,
+      // which persists — it costs nothing. The cheap read half (`aegis_recall`)
+      // is always on and has no toggle.
+      note(c, `Deep recall: ${want ? 'on — brain corrections + cached answers, one embedding per turn' : 'off (only the cheap recall read)'}${want ? ' · this session only' : ''}`);
+      c.render();
+      return true;
+    },
+  },
   {
     name: 'confirm', aliases: ['confirmations'], args: ['mode'], hint: '[on|off]', category: 'model',
     desc: 'Toggle tool-call confirmation prompts',

package/src/deps.js

@@ -65,6 +65,9 @@ const agentsPath = resolveShared(path.join('desktop', 'lib', 'local', 'agents.js
 // running shell commands. Same file as the GUI, for the same reason engine.js
 // is: two personas would drift, and only one of them would get fixed.
 const promptPath = resolveShared(path.join('desktop', 'lib', 'local', 'prompt.js'));
+// The npm update checker, shared with the desktop host: two package names, one
+// implementation, so a fix to the check reaches both.
+const updatePath = resolveShared(path.join('client', 'update.js'));
 
 const { createClient } = require(clientPath);
 const { createTools } = require(toolsPath);
@@ -72,8 +75,10 @@ const { usageTokens } = require(usagePath);
 const { createLocalEngine } = require(enginePath);
 const { agentRoles, agentRoleLabel } = require(agentsPath);
 const { buildSystemPrompt } = require(promptPath);
+const updater = require(updatePath);
 
 module.exports = {
+  resolveShared,
   createClient,
   createTools,
   usageTokens,
@@ -81,6 +86,7 @@ module.exports = {
   agentRoles,
   agentRoleLabel,
   buildSystemPrompt,
-  paths: { client: clientPath, tools: toolsPath, usage: usagePath, engine: enginePath, agents: agentsPath, prompt: promptPath },
+  updater,
+  paths: { client: clientPath, tools: toolsPath, usage: usagePath, engine: enginePath, agents: agentsPath, prompt: promptPath, update: updatePath },
   roots,
 };

package/src/render.js

@@ -31,7 +31,7 @@ const {
   DONE_VERBS,
   themeOf,
 } = require('./theme.js');
-const { WELCOME_TITLE, WELCOME_BACK, TAGLINE, welcomeArtParts } = require('./art.js');
+const { WELCOME_TITLE, WELCOME_BACK, TAGLINE, STAR, stencilGlyph, welcomeArtParts } = require('./art.js');
 const { w, pad, padStart, wrapBlock, clip, span } = require('./screen.js');
 const { fmtTokens, fmtEur, fmtElapsed } = require('./format.js');
 
@@ -63,9 +63,17 @@ function centerStyled(text, width, style) {
 }
 
 /** The right (moon + whale) half of the mark: ▓ blue, ▒ lavender, ░ dim,
- *  eye white, stars gold. */
+ *  eye white, stars gold.
+ *
+ *  The keys are the runes as `art.js` drew them, then run through the stencil:
+ *  `artRow` is handed rows that have *already* been stencilled for this
+ *  platform, so a raw-rune table silently matched nothing on win32/darwin and
+ *  the whole moon/whale half rendered uncoloured there — the mark looked
+ *  different on two of the three platforms it ships to. */
 function tintWhale(str, t) {
-  const map = { '▓': t.blue, '▒': t.lavender, '░': t.dim, '█': t.white, '✦': t.gold, '·': t.dim };
+  const byRune = { '▓': t.blue, '▒': t.lavender, '░': t.dim, '█': t.white, [STAR]: t.gold, '·': t.dim };
+  const map = {};
+  for (const rune of Object.keys(byRune)) map[stencilGlyph(rune)] = byRune[rune];
   const spans = [];
   let cur = null;
   let style = '';

package/src/theme.js

@@ -16,6 +16,11 @@
  * Zero dependencies: SGR escapes are hand-built, like the rest of this repo.
  */
 
+// The stencil is the mark's single source of truth for its own runes — this
+// file resolves `star` through it rather than restating the platform rule.
+// `art.js` requires nothing, so this import cannot cycle.
+const { STAR, stencilGlyph } = require('./art.js');
+
 const RESET = '\x1b[0m';
 const BOLD = '\x1b[1m';
 const DIM = '\x1b[2m';
@@ -66,8 +71,16 @@ const LIGHT = {
  * or render as double-width emoji (✦ U+2726, ✻/✢/✽/✶), which breaks row
  * alignment exactly like the welcome art — those platforms get single-width
  * stand-ins instead.
+ *
+ * `star` is NOT restated here: it is resolved through `art.js`'s stencil, the
+ * single source of truth for the mark's runes. This file used to carry its own
+ * `'✦' → '*'` rule on win32/darwin, which is precisely how the star could stay
+ * wide on one platform while the art got stencilled on another — the mark and
+ * the glyph table would then disagree about the same character. Every other
+ * entry below is a *text* glyph (cursor, hook, spinner frames) that no art row
+ * contains, so it keeps its own definition.
  */
-const GLYPH = (() => {
+function glyphsFor(platform = process.platform) {
   const base = {
     cursor: '❯', // menu selection marker, prompt prefix
     check: '✔', // selected / completed
@@ -75,7 +88,7 @@ const GLYPH = (() => {
     bullet: '·', // inline separators
     hint: '❯', // "Try ..." suggestion marker
     pause: '⏸', // bottom status line (manual mode)
-    star: '✦', // own-session marker, decorations
+    star: stencilGlyph(STAR, platform), // own-session marker, decorations
     leftarrow: '←', // hints on the status line
     pointer: '▸', // tips list bullets
     hook: '⎿', // inline command / tip rows (tool commands, usage hints)
@@ -84,26 +97,26 @@ const GLYPH = (() => {
     spin: ['✢', '·', '✻', '*', '✽', '✶'], // working spinner
     ellipse: '…',
   };
-  if (process.platform === 'win32') {
+  if (platform === 'win32') {
     return {
       ...base,
       pause: '❚❚', // ⏸ U+23F8 missing from many Windows fonts
       hook: '_|', // ⎿ U+23BF almost never present in Windows fonts
-      star: '*', // ✦ U+2726 renders wide/emoji
       bloom: '*', // ✻ U+273B
       spin: ['|', '/', '-', '\\', '*', '-'],
     };
   }
-  if (process.platform === 'darwin') {
+  if (platform === 'darwin') {
     return {
       ...base,
       pause: '❚❚', // ⏸ has an emoji presentation on Apple fonts
-      star: '*', // ✦ renders as a double-width emoji in Terminal.app
       hook: '_|', // ⎿ U+23BF not in Apple monospace fonts
     };
   }
   return base;
-})();
+}
+
+const GLYPH = glyphsFor(process.platform);
 
 /** Working-line verbs, verbatim from the capture-backed table. */
 const VERBS = [
@@ -216,6 +229,7 @@ module.exports = {
   THEME_TABLE,
   themeForIndex,
   GLYPH,
+  glyphsFor,
   VERBS,
   DONE_VERBS,
   themeOf,

package/src/update.js

@@ -1,137 +1,13 @@
-/**
- * "There is a newer version" — the notice this CLI never had.
- *
- * Checked on 2026-09-15: there was no update check anywhere in the client, so
- * a user learned about a release only by guessing to run
- * `npm i -g aegiscode@latest`. Publishing therefore reached almost nobody, and
- * the installed base drifted months behind the registry.
- *
- * Three rules, because an update check is a background nicety that must never
- * become a liability:
- *   · it never blocks — the caller gets a cached answer immediately and the
- *     network call settles whenever it settles;
- *   · it never throws — offline, proxied, rate-limited or garbage JSON all
- *     mean "no notice", not a broken CLI;
- *   · it never nags — one check a day, cached, and nothing printed when the
- *     user is already current.
- */
-
-const https = require('node:https');
-
-const REGISTRY = 'https://registry.npmjs.org';
-const PKG = 'aegiscode';
-/** One check a day. A CLI that pings the registry every launch is spyware. */
-const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
-/** The registry is not on the critical path; give up quickly and silently. */
-const TIMEOUT_MS = 2500;
-
-/** Compare two semver-ish strings. Returns true when `latest` is newer. */
-function isNewer(latest, current) {
-  const parse = (v) =>
-    String(v || '')
-      .trim()
-      .replace(/^v/, '')
-      .split('-')[0] // a prerelease never counts as newer than its release
-      .split('.')
-      .map((n) => Number.parseInt(n, 10) || 0);
-  const a = parse(latest);
-  const b = parse(current);
-  for (let i = 0; i < Math.max(a.length, b.length); i++) {
-    const x = a[i] || 0;
-    const y = b[i] || 0;
-    if (x !== y) return x > y;
-  }
-  return false;
-}
-
-/** Fetch the registry's `latest` dist-tag. Resolves null on any failure. */
-function fetchLatest({ pkg = PKG, timeoutMs = TIMEOUT_MS } = {}) {
-  return new Promise((resolve) => {
-    let settled = false;
-    const done = (v) => {
-      if (!settled) {
-        settled = true;
-        resolve(v);
-      }
-    };
-    try {
-      // The abbreviated metadata document: a few KB instead of the full
-      // packument, which for a package with this many releases is megabytes.
-      const req = https.get(
-        `${REGISTRY}/${pkg}`,
-        { headers: { accept: 'application/vnd.npm.install-v1+json' }, timeout: timeoutMs },
-        (res) => {
-          if (res.statusCode !== 200) {
-            res.resume();
-            return done(null);
-          }
-          let body = '';
-          res.setEncoding('utf8');
-          res.on('data', (c) => {
-            body += c;
-            if (body.length > 2_000_000) {
-              req.destroy();
-              done(null);
-            }
-          });
-          res.on('end', () => {
-            try {
-              const tags = JSON.parse(body)['dist-tags'];
-              done((tags && tags.latest) || null);
-            } catch {
-              done(null);
-            }
-          });
-        }
-      );
-      req.on('timeout', () => {
-        req.destroy();
-        done(null);
-      });
-      req.on('error', () => done(null));
-    } catch {
-      done(null);
-    }
-  });
-}
+'use strict';
 
 /**
- * The notice to show, from cache. Never waits on the network.
+ * The CLI's view of the shared npm update checker (client/update.js).
  *
- * `cache` is the persisted `{ checkedAt, latest }` blob; `save` persists a new
- * one. Returns `{ latest, behind }`, and kicks off a refresh in the background
- * when the cache is stale.
+ * It lives at the repo root rather than here because the desktop host needs
+ * the same thing for `aegis-desktop`: two hosts, two package names, one
+ * checker. Resolved through deps.js so the in-repo and published-vendor
+ * layouts both work.
  */
-function updateNotice({
-  current,
-  cache,
-  save,
-  now = Date.now(),
-  fetchImpl = fetchLatest,
-  intervalMs = CHECK_INTERVAL_MS,
-} = {}) {
-  const c = cache || {};
-  const fresh = typeof c.checkedAt === 'number' && now - c.checkedAt < intervalMs;
-
-  if (!fresh) {
-    // Fire and forget: this run reports on what was already known, and the
-    // answer lands for the next one. A first run therefore never shows a
-    // notice, which is correct — it has nothing to compare against yet.
-    Promise.resolve(fetchImpl())
-      .then((latest) => {
-        if (latest && typeof save === 'function') save({ checkedAt: now, latest });
-      })
-      .catch(() => {});
-  }
-
-  const latest = c.latest || null;
-  return { latest, behind: !!(latest && isNewer(latest, current)) };
-}
-
-/** One line for the welcome box, or null when there is nothing to say. */
-function updateLine({ current, latest, behind }) {
-  if (!behind) return null;
-  return `Update available: ${current} → ${latest}   run: npm i -g ${PKG}@latest`;
-}
 
-module.exports = { isNewer, fetchLatest, updateNotice, updateLine, PKG, CHECK_INTERVAL_MS };
+const { resolveShared } = require('./deps.js');
+module.exports = require(resolveShared('client/update.js'));

package/vendor/client/aegis.js

@@ -664,11 +664,21 @@ function createClient(opts = {}) {
     return apiGet('/api/token-bank/balance');
   }
 
-  /** Start a token-bank top-up; resolves to { url } for the payment page. */
+  /** Start a token-bank top-up; resolves to { url } for the payment page.
+   *  aegis1 requires a signed-in account (403/401 without a key) and rejects
+   *  an amount outside 2..1000 EUR with 400. */
   async function tokenBankTopup(amountEur) {
     return apiPost('/api/token-bank/topup', { amount_eur: amountEur });
   }
 
+  /** Start a plan checkout; resolves to { url } for Stripe's hosted page.
+   *  aegis1 `/api/billing/checkout` is deliberately public (the Stripe page
+   *  collects the email), so this works with no key configured — but answers
+   *  503 `setup_required` while the price id is unset on the server. */
+  async function billingCheckout() {
+    return apiPost('/api/billing/checkout', {});
+  }
+
   async function byokStatus() {
     return apiGet('/api/user/api-keys');
   }
@@ -797,6 +807,7 @@ function createClient(opts = {}) {
     listModels,
     tokenBankBalance,
     tokenBankTopup,
+    billingCheckout,
     byokStatus,
     byokSet,
     getMemoryToken,

package/vendor/client/update.js

@@ -0,0 +1,140 @@
+/**
+ * "There is a newer version" — the notice this CLI never had.
+ *
+ * Checked on 2026-09-15: there was no update check anywhere in the client, so
+ * a user learned about a release only by guessing to run
+ * `npm i -g aegiscode@latest`. Publishing therefore reached almost nobody, and
+ * the installed base drifted months behind the registry.
+ *
+ * Three rules, because an update check is a background nicety that must never
+ * become a liability:
+ *   · it never blocks — the caller gets a cached answer immediately and the
+ *     network call settles whenever it settles;
+ *   · it never throws — offline, proxied, rate-limited or garbage JSON all
+ *     mean "no notice", not a broken CLI;
+ *   · it never nags — one check a day, cached, and nothing printed when the
+ *     user is already current.
+ */
+
+const https = require('node:https');
+
+const REGISTRY = 'https://registry.npmjs.org';
+//: Default package. Both hosts ship from npm — the CLI as `aegiscode`, the
+//: desktop as `aegis-desktop` — so one checker serves both; the caller names
+//: which one it is.
+const PKG = 'aegiscode';
+/** One check a day. A CLI that pings the registry every launch is spyware. */
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** The registry is not on the critical path; give up quickly and silently. */
+const TIMEOUT_MS = 2500;
+
+/** Compare two semver-ish strings. Returns true when `latest` is newer. */
+function isNewer(latest, current) {
+  const parse = (v) =>
+    String(v || '')
+      .trim()
+      .replace(/^v/, '')
+      .split('-')[0] // a prerelease never counts as newer than its release
+      .split('.')
+      .map((n) => Number.parseInt(n, 10) || 0);
+  const a = parse(latest);
+  const b = parse(current);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] || 0;
+    const y = b[i] || 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+
+/** Fetch the registry's `latest` dist-tag. Resolves null on any failure. */
+function fetchLatest({ pkg = PKG, timeoutMs = TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => {
+      if (!settled) {
+        settled = true;
+        resolve(v);
+      }
+    };
+    try {
+      // The abbreviated metadata document: a few KB instead of the full
+      // packument, which for a package with this many releases is megabytes.
+      const req = https.get(
+        `${REGISTRY}/${pkg}`,
+        { headers: { accept: 'application/vnd.npm.install-v1+json' }, timeout: timeoutMs },
+        (res) => {
+          if (res.statusCode !== 200) {
+            res.resume();
+            return done(null);
+          }
+          let body = '';
+          res.setEncoding('utf8');
+          res.on('data', (c) => {
+            body += c;
+            if (body.length > 2_000_000) {
+              req.destroy();
+              done(null);
+            }
+          });
+          res.on('end', () => {
+            try {
+              const tags = JSON.parse(body)['dist-tags'];
+              done((tags && tags.latest) || null);
+            } catch {
+              done(null);
+            }
+          });
+        }
+      );
+      req.on('timeout', () => {
+        req.destroy();
+        done(null);
+      });
+      req.on('error', () => done(null));
+    } catch {
+      done(null);
+    }
+  });
+}
+
+/**
+ * The notice to show, from cache. Never waits on the network.
+ *
+ * `cache` is the persisted `{ checkedAt, latest }` blob; `save` persists a new
+ * one. Returns `{ latest, behind }`, and kicks off a refresh in the background
+ * when the cache is stale.
+ */
+function updateNotice({
+  current,
+  cache,
+  save,
+  now = Date.now(),
+  fetchImpl = fetchLatest,
+  intervalMs = CHECK_INTERVAL_MS,
+} = {}) {
+  const c = cache || {};
+  const fresh = typeof c.checkedAt === 'number' && now - c.checkedAt < intervalMs;
+
+  if (!fresh) {
+    // Fire and forget: this run reports on what was already known, and the
+    // answer lands for the next one. A first run therefore never shows a
+    // notice, which is correct — it has nothing to compare against yet.
+    Promise.resolve(fetchImpl())
+      .then((latest) => {
+        if (latest && typeof save === 'function') save({ checkedAt: now, latest });
+      })
+      .catch(() => {});
+  }
+
+  const latest = c.latest || null;
+  return { latest, behind: !!(latest && isNewer(latest, current)) };
+}
+
+/** One line for the welcome box, or null when there is nothing to say. */
+function updateLine({ current, latest, behind, pkg = PKG }) {
+  if (!behind) return null;
+  return `Update available: ${current} → ${latest}   run: npm i -g ${pkg}@latest`;
+}
+
+module.exports = { isNewer, fetchLatest, updateNotice, updateLine, PKG, CHECK_INTERVAL_MS };

package/vendor/desktop/lib/local/engine.js

@@ -346,6 +346,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) {
@@ -358,10 +367,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 };
   }
 
@@ -379,22 +422,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;
@@ -405,7 +454,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({
@@ -440,6 +489,13 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
     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);
+    // 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') {
@@ -453,8 +509,15 @@ 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);
 
@@ -598,12 +661,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
@@ -759,6 +863,14 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
         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
@@ -873,7 +985,12 @@ function createLocalEngine({ aegis, settings, ollama, providers, tools, promptBu
           });
         }
         round += 1;
-        const opts = { ...base, system, messages: history, prompt, tools: toolSchemas };
+        // `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);
@@ -917,6 +1034,10 @@ 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
@@ -948,6 +1069,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: [],