aegis-desktop 0.8.17 → 0.8.18

package/lib/local/engine.js

@@ -307,35 +307,32 @@ function normalizeCatalog(models) {
 /**
  * The Aegis Cloud (pooled) dropdown.
  *
- * It offers NO aegiscloud model. The catalog (`/api/v1/models`) lists
- * per-provider ids (`deepseek`, `anthropic`, `groq`, `openai`, ...) alongside
- * five pooled-brain tier spellings (`{aegis,nexus}-brain[-smart|-neo]`) that all
- * route the same worker pool, and this host must offer neither: "omit the
- * aegiscloud models" is the instruction, and a host that omitted the brain row
- * while leaving `deepseek` on screen would have kept exactly the per-provider
- * pin the Aegis Cloud policy is about. The class stays selectable and its
- * dropdown keeps the "server default (auto)" row, so the pooled lane still runs
- * — it just advertises nothing to pin.
+ * It offers the server's whole catalog (`/api/v1/models`): the pooled brain
+ * first, under its one name (Nexus), then every per-provider id the account can
+ * pin (`deepseek`, `anthropic`, `groq`, `openai`, ...).
+ *
+ * Two narrower shapes were shipped here and both are reverted, because both
+ * produced the same report — a user asking where the models went. First the
+ * class collapsed to a single "Nexus" row (`filterAegisCatalog`), which ended
+ * the two-host disagreement about the brain's five tier spellings by removing
+ * the choice: a funded account had `deepseek` advertised to it and no way to
+ * pin it. Then it offered nothing at all — `omitAegisCloudModels` composed with
+ * that collapse returns `[]`, because the omission removes the only entry the
+ * collapse looks for. The rule both hosts call now is `offerableCatalog`:
+ * everything the server advertises, the tier spellings folded into the one row
+ * they point at.
  *
  * What is NOT changed: the account key, and everything the key is *for* — the
  * pooled turn itself, cloud memory sync, and the BYOK handling fee that is
- * billed to this account (see the byok branch below, which still offers every
- * provider id the server's catalog names). Omitting a model list is not
- * disconnecting the lane.
- *
- * The omission itself is one shared rule (`omitAegisCloudModels`, and the
- * collapse it is composed with) in `client/brain-catalog.js`, shared with the
- * CLI: two copies is how this host and the terminal previously came to offer
- * the same account two different model lists. Resolved the two ways this repo
- * resolves every shared module — repo-relative in a checkout, and this app's
- * staged vendor/ tree.
+ * billed to this account (see the byok branch below).
  *
- * `filterAegisCatalog` is kept in the composition rather than dropped for the
- * shorter `models: []`: a payload with no brain tier at all (a self-hosted or
- * trimmed deployment) must still yield nothing here rather than leaking its
- * per-provider ids, and that is precisely the case the collapse already answers.
+ * The list itself is one shared rule in `client/brain-catalog.js`, shared with
+ * the CLI: two copies is how this host and the terminal previously came to
+ * offer the same account two different model lists. Resolved the two ways this
+ * repo resolves every shared module — repo-relative in a checkout, and this
+ * app's staged vendor/ tree.
  */
-const { filterAegisCatalog, omitAegisCloudModels } = requireSharedBrain();
+const { offerableCatalog } = requireSharedBrain();
 
 /**
  * The BYOK additions, applied to the server's provider catalog below. Same
@@ -855,20 +852,16 @@ function createLocalEngine({
       // entry so the class is usable the moment a key lands.
       if (!aegis.apiKey) return { class: cls, models: [], needsKey: true };
       const data = await aegis.listModels();
-      // No aegiscloud model is offered — see the rule above. The class, the
-      // auto row and the pooled turn are untouched; only the pinnable list is
-      // emptied, which is why `needsKey` keeps its meaning and the renderer's
-      // hint for this class is unchanged.
+      // The whole catalog, aliases folded — see the rule above. What the list
+      // contains does not touch `needsKey` or the renderer's per-class hint.
       return {
         class: cls,
-        // Omit FIRST, then collapse: the omission has to see the payload's own
-        // `alias_of` bookkeeping, which the collapse deliberately strips (a
-        // collapsed row IS the selection, so a renderer must not filter it back
-        // out as a hidden alias). Filtering a collapsed row instead would leave
-        // a renamed tier — `nexus-brain-v2`, an alias OF the brain under a
-        // spelling this release has never seen — on screen, which is the one
-        // case the rule exists to catch.
-        models: filterAegisCatalog(omitAegisCloudModels(normalizeCatalog(data && data.models))),
+        // One call, because the folding has to see the payload's own `alias_of`
+        // bookkeeping: a pre-collapsed row IS the selection, so a renderer must
+        // not filter it back out as a hidden alias, and folding what has already
+        // been folded would leave a renamed tier (`nexus-brain-v2`, an alias OF
+        // the brain under a spelling this release has never seen) on screen.
+        models: offerableCatalog(normalizeCatalog(data && data.models)),
       };
     }
     if (cls === 'byok') {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegis-desktop",
   "productName": "AEGIS Desktop",
-  "version": "0.8.17",
+  "version": "0.8.18",
   "description": "Thin Electron host for AEGIS — a local chat UI over the shared client/aegis.js transport. Ships transport + UI only; engine logic stays server-side.",
   "author": {
     "name": "AEGIS Code",

package/renderer/app.js

@@ -161,6 +161,19 @@ const ELEMENT_IDS = {
   queueAutoHint: 'queue-auto-hint',
   queueBoundary: 'queue-boundary',
   queueUpgrade: 'queue-upgrade',
+  // The two-key pop-up (index.html #keys-overlay, driven by applyKeysPopup()).
+  keysOverlay: 'keys-overlay',
+  keysBackdrop: 'keys-backdrop',
+  keysClose: 'keys-close',
+  keysCount: 'keys-count',
+  keysRowAegis: 'keys-row-aegis',
+  keysRowByok: 'keys-row-byok',
+  keysAegisState: 'keys-aegis-state',
+  keysByokState: 'keys-byok-state',
+  keysGotoAegis: 'keys-goto-aegis',
+  keysGotoByok: 'keys-goto-byok',
+  keysHint: 'keys-hint',
+  keysDismiss: 'keys-dismiss',
 };
 
 const els = {};
@@ -895,6 +908,10 @@ function renderStatus(s) {
   // from the CLI) retires the connect block; with no key it stays. No-ops when
   // the panel is not mounted.
   applyWelcomeConnect();
+  // And the two-key pop-up's gate: a status read is the only thing that knows
+  // either fact, so this is where the sheet is opened (a key still missing) or
+  // retired (both present). No-ops while the markup is absent.
+  applyKeysPopup();
 }
 
 // -------------------------------------------------------------- auto-update
@@ -1828,6 +1845,9 @@ const memoryView = {
  *  instead. Confusing the two is how a save would read a hidden textarea. */
 function overlayOpen() {
   if (memoryOverlayOpen()) return true;
+  // The two-key pop-up is a sheet on the same layer, so Escape belongs to it
+  // first while it is up — the same rule the memory inspector follows.
+  if (keysOverlayOpen()) return true;
   // Ask the PANEL, not the module.
   //
   // `window.aegisFingerprint` is desktop/renderer/fingerprint.js, whose exports
@@ -1858,6 +1878,12 @@ function memoryOverlayOpen() {
   return !!els.memoryOverlay && !els.memoryOverlay.hidden;
 }
 
+/** The two-key pop-up alone. Same shape as memoryOverlayOpen(): the element,
+ *  not a module variable, so a sheet closed by any path reads as closed. */
+function keysOverlayOpen() {
+  return !!els.keysOverlay && !els.keysOverlay.hidden;
+}
+
 /** The φ(α) panel handle, set by init() when desktop/renderer/fingerprint.js is
  *  loaded. Kept here rather than inside fingerprint.js so the Escape policy
  *  above can ask it whether it is open without reaching into its internals. */
@@ -2590,6 +2616,162 @@ function dismissWelcomeConnect() {
   if (box) box.hidden = true;
 }
 
+// ------------------------------------------- boot: the two-key pop-up
+//
+// The welcome block above pitches the ROUTES ("connect AEGIS Cloud", "bring
+// your own key") and retires the moment either one is taken. This sheet is the
+// other question, and the one nothing on screen used to answer: this app and
+// the `aegiscode` CLI on the command line are ONE engine over ONE store, so a
+// user who added only one of the two keys gets a surface that refuses turns
+// with no explanation of the other half.
+//
+//   AEGIS key   — `aegis:<...>` in ~/.aegiscode/.env (AEGIS_API_KEY), the
+//                 account key. The CLI writes it with `/key`, this app with
+//                 the Status card's field. Every turn on both surfaces needs
+//                 it: BYOK sends are relayed through AEGIS and bill a handling
+//                 fee to it, so a keyless BYOK send is refused outright.
+//   BYOK key    — a `byok:<provider>` row in the shared settings store. The
+//                 CLI writes it with `/byok-key <provider>`, this app with the
+//                 per-provider row in Provider settings. It is the free path:
+//                 your own provider account, on either surface.
+//
+// Both are reported by the main process in the status payload — keyConfigured
+// (also read here for the top-up guard) and providerConfigured (main.js
+// providerRouteConfigured(), documented at desktop/lib/provider-key-mirror.js)
+// — so the sheet is driven by one read, not by a second probe of its own.
+//
+// When it opens: on the status payload, while EITHER key is missing. That is
+// the ask the copy makes ("add both — both surfaces run"), so retiring it on
+// the first key would contradict the sentence the user just read. It is a
+// pop-up and therefore dismissible: `aegis.keysPopupDismissed` is persisted
+// and read on every repaint, exactly like the welcome block's flag, because a
+// sheet that reappears after "don't show this again" is a nag, not onboarding.
+// While the key state is still unknown (null, i.e. status has not been read)
+// it stays closed: a cold boot has no key far more often than not, but opening
+// a sheet on a guess is how the app would flash a pop-up at someone who is
+// fully configured. renderStatus() calls the gate again the moment the truth
+// arrives, which is what actually opens it.
+
+/** The dismiss flag. Read, not remembered — the sheet is re-gated on every
+ *  status repaint, so a module variable alone would bring it back. */
+const KEYS_POPUP_DISMISS_KEY = 'aegis.keysPopupDismissed';
+
+/** True while either key is still missing — the sheet's whole question. Both
+ *  facts default to "missing" for an unknown state, matching the fail-toward-
+ *  showing-it bias the welcome block and the CLI's connectNeeded() share; the
+ *  null check is in the gate below, not here, so this stays a plain predicate
+ *  about two booleans. */
+function keysPopupNeeded() {
+  return keyConfigured !== true || providerConfigured !== true;
+}
+
+/** Paint the two state lines and the count. Never the keys themselves — only
+ *  "set" / "not set", the same rule the φ(α) panel follows. */
+function renderKeysPopup() {
+  const aegisSet = keyConfigured === true;
+  const byokSet = providerConfigured === true;
+  if (els.keysAegisState) els.keysAegisState.textContent = aegisSet ? 'set' : 'not set';
+  if (els.keysByokState) els.keysByokState.textContent = byokSet ? 'set' : 'not set';
+  if (els.keysRowAegis) els.keysRowAegis.classList.toggle('set', aegisSet);
+  if (els.keysRowByok) els.keysRowByok.classList.toggle('set', byokSet);
+  if (els.keysCount) els.keysCount.textContent = `${(aegisSet ? 1 : 0) + (byokSet ? 1 : 0)} / 2`;
+  if (els.keysHint) {
+    els.keysHint.textContent =
+      aegisSet && byokSet
+        ? 'Both keys are on this machine — both surfaces run.'
+        : `Missing: ${[aegisSet ? null : 'the AEGIS key', byokSet ? null : 'your provider (BYOK) key']
+            .filter(Boolean)
+            .join(' and ')}. Add it above, then both AEGIS Desktop and the aegiscode CLI run.`;
+  }
+}
+
+/** Show the sheet. Idempotent, so the gate can call it on every repaint. */
+function openKeysPopup() {
+  if (!els.keysOverlay) return;
+  renderKeysPopup();
+  if (!els.keysOverlay.hidden) return;
+  els.keysOverlay.hidden = false;
+  document.body.classList.add('keys-open');
+}
+
+function closeKeysPopup() {
+  if (!els.keysOverlay) return;
+  els.keysOverlay.hidden = true;
+  document.body.classList.remove('keys-open');
+}
+
+/** True while a turn is in flight — the one fact that outranks this sheet.
+ *
+ *  Why this exists, and why it is a refusal rather than a lower z-index: the
+ *  sheet is composed into overlayOpen(), so while it is up Escape belongs to it
+ *  and is spent closing it — that is the contract every other sheet in this
+ *  file follows, and it is right for a sheet the USER opened. This one opens
+ *  ITSELF, on a status read, whenever a key is missing. So on a fresh or
+ *  half-configured install it is up before the first token, and Escape during a
+ *  streaming turn would close a pop-up instead of stopping the turn: the user's
+ *  only keyboard route to interrupting a runaway turn, silently spent on a
+ *  sheet they never asked for. It was found exactly that way — the headless
+ *  smoke run stopped failing to stop, with `overlayOpen: true` in the recorded
+ *  escape decision.
+ *
+ *  An advisory sheet must yield to the turn, so the gate never opens one while
+ *  a turn is running, and the send path closes any that is already up. Nothing
+ *  is lost: the sheet is re-gated on the next status read after the turn ends,
+ *  which is a repaint that happens anyway. */
+function turnInFlight() {
+  return Boolean(pendingSessionId);
+}
+
+/** The gate: called on every status read (and once after the key panel is
+ *  painted). Dismissed wins; an unknown key state defers to the next read. */
+function applyKeysPopup() {
+  const box = document.getElementById('keys-overlay');
+  if (!box) return;
+  let dismissed = false;
+  try {
+    dismissed = localStorage.getItem(KEYS_POPUP_DISMISS_KEY) === 'on';
+  } catch {
+    /* storage disabled — treat as not dismissed, same as the welcome block */
+  }
+  if (dismissed || keyConfigured === null) {
+    box.hidden = true;
+    return;
+  }
+  // Repaint before deciding: the two rows and the count describe the keys that
+  // exist right now, and a repaint is what retires the last missing one — so a
+  // sheet that has just become fully configured cannot close still reading
+  // "1 / 2" if it is opened again this session.
+  renderKeysPopup();
+  // A running turn outranks the ask. Close on the way past rather than merely
+  // declining to open, so a sheet already on screen when the turn began cannot
+  // keep the next Escape for itself (see turnInFlight()).
+  if (turnInFlight()) {
+    closeKeysPopup();
+    return;
+  }
+  if (keysPopupNeeded()) openKeysPopup();
+  else closeKeysPopup();
+}
+
+/** "Don't show this again": persisted, then dropped for this session. */
+function dismissKeysPopup() {
+  try {
+    localStorage.setItem(KEYS_POPUP_DISMISS_KEY, 'on');
+  } catch {
+    /* storage disabled — the sheet simply comes back next launch */
+  }
+  closeKeysPopup();
+}
+
+/** Which key is missing, in the sheet's own words — used as the hint under the
+ *  field the user is dropped on, so the two surfaces say the same thing. */
+function keysMissingLine() {
+  const missing = [];
+  if (keyConfigured !== true) missing.push('the AEGIS key');
+  if (providerConfigured !== true) missing.push('your provider (BYOK) key');
+  return missing.join(' and ');
+}
+
 // Assistant text is rendered as sanitized markdown (headings, lists, links,
 // highlighted fenced code with a copy button — see renderer/markdown.js);
 // user text always stays plain via textContent, and this is the only place
@@ -3956,6 +4138,12 @@ async function send() {
   if (!currentSessionId) currentSessionId = newSessionId();
   const sessionId = currentSessionId;
   pendingSessionId = sessionId;
+  // The two-key sheet yields to the turn it would otherwise sit in front of:
+  // Escape has to reach the interrupt, not a pop-up (see turnInFlight()). This
+  // is the moment a turn begins, so it is the moment to retire one already up —
+  // the gate alone would only stop it REopening, which leaves a sheet opened at
+  // boot covering the whole stream.
+  closeKeysPopup();
 
   // Snapshot prior turns for the model — the new prompt travels separately
   // as `prompt` and providers.js appends it after `messages` on the wire.
@@ -4491,6 +4679,37 @@ async function init() {
       renderMemoryOverlay();
     });
   }
+
+  // ── the two-key pop-up ───────────────────────────────────────────────────
+  // Same `?`-guards as the inspector above, for the same reason: the markup is
+  // optional and a missing node must degrade to "no sheet", not a boot crash.
+  // Both "go to" buttons land on the field the key is actually typed into, via
+  // the existing affordances (revealSidebarCard / welcomeByok), so this sheet
+  // adds no second way to store a key — it only says which two exist.
+  if (els.keysClose) els.keysClose.addEventListener('click', closeKeysPopup);
+  if (els.keysBackdrop) els.keysBackdrop.addEventListener('click', closeKeysPopup);
+  if (els.keysDismiss) els.keysDismiss.addEventListener('click', dismissKeysPopup);
+  if (els.keysGotoAegis) {
+    els.keysGotoAegis.addEventListener('click', () => {
+      closeKeysPopup();
+      revealSidebarCard(els.apiKeyInput);
+      if (els.apiKeyInput) els.apiKeyInput.focus();
+      if (els.apiKeyHint) {
+        els.apiKeyHint.textContent =
+          `Missing: ${keysMissingLine()}. This is the AEGIS account key — the same one ` +
+          'the CLI reads from ~/.aegiscode/.env, so pasting it here configures both.';
+      }
+    });
+  }
+  if (els.keysGotoByok) {
+    els.keysGotoByok.addEventListener('click', () => {
+      closeKeysPopup();
+      // Reuses the welcome block's BYOK route rather than repeating it: it
+      // switches the provider class, reveals the Provider settings card and
+      // focuses the first key row — the same landing spot, one implementation.
+      welcomeByok();
+    });
+  }
   // ── the autonomous queue card ────────────────────────────────────────────
   // The queue half of this file (window.queue -> main.js registerQueueIpc ->
   // desktop/lib/local/queue.js + autonomous.js) shipped with every handler
@@ -4592,6 +4811,14 @@ async function init() {
     // both are somehow up.
     isOverlayOpen: overlayOpen,
     onOverlayEscape: () => {
+      // The keys sheet is declared right here in this file, so it is closed
+      // first and needs no handle lookup: while it is up it is the outermost
+      // sheet, and falling through to the memory overlay would close a panel
+      // the user is not looking at.
+      if (keysOverlayOpen()) {
+        closeKeysPopup();
+        return;
+      }
       // Same handle, same reason as overlayOpen(): the module has no `close`,
       // the mounted panel does. Guessed at the module here too, which threw for
       // the same reason — and an overlay can only be closed by its own sheet's

package/renderer/index.html

@@ -745,6 +745,88 @@
     </div>
   </div>
 
+  <!-- The two-key pop-up. Same sheet as the memory inspector and the φ(α)
+       panel (the classes are shared on purpose: one translucent layer, one
+       Escape policy), and it exists because the app and the CLI are one engine
+       over one store: AEGIS Desktop reads the very `aegis:<...>` account key
+       and the very `byok:<provider>` rows `aegiscode` on the command line
+       writes, so BOTH keys are what make BOTH surfaces run.
+
+       Markup is static (no <template>) because it is opened by
+       openKeysPopup() from app.js on the status payload, not cloned into the
+       transcript. Every id below is declared in app.js's ELEMENT_IDS map and
+       toggled by applyKeysPopup(); the unit test slices those functions out of
+       app.js and drives them over a fake DOM, so a rename in either place
+       fails loudly. Nothing here ever displays a key — only "set" / "not set",
+       the same rule the φ(α) panel follows. -->
+  <div class="memory-overlay keys-overlay" id="keys-overlay" hidden>
+    <div class="memory-backdrop" id="keys-backdrop"></div>
+    <div
+      class="memory-panel keys-panel"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="keys-panel-title"
+    >
+      <header class="memory-panel-head">
+        <h2 id="keys-panel-title">Add both keys — both surfaces run</h2>
+        <span class="memory-count" id="keys-count">0 / 2</span>
+        <div class="spacer"></div>
+        <button type="button" id="keys-close" class="ghost-btn" title="Close (Esc)">
+          Close
+        </button>
+      </header>
+
+      <p class="hint" id="keys-lead">
+        AEGIS Desktop and the <code>aegiscode</code> CLI are the same engine over
+        the same store on this disk. Two keys turn on both: the AEGIS account key
+        (your bill, and the pooled models) and your own provider key (BYOK). Add
+        both and either surface runs — until then, a turn on the missing one is
+        refused with the same reason in both places.
+      </p>
+
+      <div class="keys-rows">
+        <div class="keys-row" id="keys-row-aegis">
+          <span class="keys-state" id="keys-aegis-state">not set</span>
+          <div class="keys-body">
+            <b>AEGIS key</b> — the account key, written to <code>~/.aegiscode/.env</code>
+            (<code>AEGIS_API_KEY</code>) by the CLI's <code>/key</code> and by the
+            field in the Status card. Without it both surfaces refuse a send.
+          </div>
+          <button type="button" id="keys-goto-aegis" class="ghost-btn">
+            Paste it here
+          </button>
+        </div>
+        <div class="keys-row" id="keys-row-byok">
+          <span class="keys-state" id="keys-byok-state">not set</span>
+          <div class="keys-body">
+            <b>Your own provider key (BYOK)</b> — a <code>byok:&lt;provider&gt;</code>
+            row in the shared settings store, written by the CLI's
+            <code>/byok-key &lt;provider&gt;</code> and by the Provider settings card
+            here. It runs the free path on your own account, on both surfaces.
+          </div>
+          <button type="button" id="keys-goto-byok" class="ghost-btn">Add it here</button>
+        </div>
+      </div>
+
+      <p class="hint" id="keys-hint"></p>
+
+      <div class="keys-actions">
+        <a
+          class="ghost-btn"
+          id="keys-get"
+          href="https://aegiscloud.org/key?s=desktop"
+          target="_blank"
+          rel="noreferrer noopener"
+        >
+          Get a free AEGIS key →
+        </a>
+        <button type="button" id="keys-dismiss" class="ghost-btn">
+          Don't show this again
+        </button>
+      </div>
+    </div>
+  </div>
+
   <script src="budget.js"></script>
   <script src="usage.js"></script>
   <script src="stream-policy.js"></script>

package/renderer/style.css

@@ -2443,3 +2443,77 @@ body.is-scrolled .composer {
 .diff-block .diff-code {
   white-space: pre;
 }
+
+/* ---------------------------------------------------------- the keys pop-up
+   The two-key sheet (#keys-overlay, markup in index.html, driven by
+   applyKeysPopup() in app.js). It reuses the memory inspector's translucent
+   layer and panel, so only the row layout is new here.
+
+   The `[hidden]` rule is not decoration: `hidden` is in the markup and the
+   gate turns it on and off, but a class selector on the overlay
+   (.memory-overlay sets a display) outranks the UA stylesheet's
+   `[hidden] { display:none }`, so without this the pop-up would be on screen
+   from the first paint no matter what the gate decided — the exact defect
+   fixed once already for .welcome-connect. */
+#keys-overlay[hidden] {
+  display: none;
+}
+
+body.keys-open {
+  overflow: hidden;
+}
+
+.keys-panel {
+  max-width: 720px;
+}
+
+.keys-rows {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  /* padding, not flex-grow: the panel already scrolls (memory-panel). */
+  padding: 4px 0;
+}
+
+.keys-row {
+  display: grid;
+  grid-template-columns: 78px 1fr auto;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 12px;
+  border: 1px solid var(--line, #2a2f3a);
+  border-radius: 10px;
+}
+
+/* A row whose key is already on the machine reads as done and drops back, so
+   the one still missing is the one the eye lands on. The state line under the
+   title counts the same two facts, so they cannot disagree. */
+.keys-row.set {
+  opacity: 0.7;
+}
+
+.keys-state {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  text-align: center;
+  padding: 2px 6px;
+  border-radius: 6px;
+  color: #9aa4b2;
+}
+
+.keys-row.set .keys-state {
+  color: #7ee0a0;
+}
+
+.keys-body {
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+.keys-actions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+  padding-top: 6px;
+}

package/vendor/credentials.js

@@ -18,10 +18,18 @@
  *
  * Resolution order, first hit wins:
  *
- *   1. `AEGIS_API_KEY` — the environment, so CI and an explicit export keep
- *      working and nothing written here can shadow them.
- *   2. `credentials.json` in the data dir, mode 0600. The writable store.
- *   3. `config.json`'s `aegiscloud.api_key` / `memory.token` — the shape an
+ *   1. `AEGIS_API_KEY` **exported by the launching shell** — so CI and an
+ *      explicit export keep working.
+ *   2. `credentials.json` in the data dir, mode 0600. The writable store, and
+ *      the record of a key the user deliberately saved (`aegiscode login`, the
+ *      CLI's `/key`, the desktop's Settings pane).
+ *   3. `AEGIS_API_KEY` from `~/.aegiscode/.env` — the documented place to put a
+ *      key, but a FALLBACK rather than a decision: no save stamp, shared by
+ *      every host, hand-edited. Both rungs read the same variable, which is why
+ *      `isFromEnvFile()` exists — without it a leftover line in that file
+ *      outranked rung 2 forever and a freshly saved key was silently ignored
+ *      while every host reported it as saved. See `resolveApiKey`.
+ *   4. `config.json`'s `aegiscloud.api_key` / `memory.token` — the shape an
  *      earlier AEGIS CLI left in the same data dir. Read, never written, and
  *      never deleted: it is another product's file and the user's key is in
  *      it. When one is found it is *also* copied into credentials.json so the
@@ -189,21 +197,79 @@ function adoptLegacy(dir) {
   return { adopted: Object.keys(patch) };
 }
 
+/**
+ * Was this environment value put there by `~/.aegiscode/.env`, rather than
+ * exported by the launching shell?
+ *
+ * The env object is passed through: provenance is a property of the object the
+ * value was loaded INTO, so a caller resolving from an injected `{ env }` (every
+ * test, and any host that scopes its environment) must be answered about that
+ * object rather than about `process.env`.
+ *
+ * Loaded lazily and defensively: this module is deliberately dependency-free
+ * (it is copied into hosts that bundle no other file), so an absent env-file
+ * module simply means "nothing is file-sourced" — which is the pre-existing
+ * behaviour, not a failure.
+ */
+function fromEnvFile(name, value, env) {
+  try {
+    const envFile = require('./env-file.js');
+    return (
+      typeof envFile.isFromEnvFile === 'function' &&
+      envFile.isFromEnvFile(name, value, env ? { env } : undefined)
+    );
+  } catch {
+    return false;
+  }
+}
+
 /**
  * The key to use, and where it came from.
  *
- * @returns {{key:string, source:'env'|'credentials'|'config'|'none', from:string}}
+ * Order, and the one asymmetry that matters:
+ *
+ *   1. `AEGIS_API_KEY` **exported by the launching shell** — unchanged, and
+ *      still first, so CI and an explicit `AEGIS_API_KEY=… aegiscode` keep
+ *      working.
+ *   2. `credentials.json` — a key the user explicitly saved with
+ *      `aegiscode login`, the CLI's `/key`, or the desktop's Settings pane.
+ *   3. `AEGIS_API_KEY` **from `~/.aegiscode/.env`** — the documented place to
+ *      put a key, but a fallback rather than a decision: it carries no save
+ *      stamp and the file is shared by every host and hand-edited by users.
+ *   4. `config.json`'s legacy `aegiscloud.api_key`.
+ *
+ * Rungs 1 and 3 are the same variable, which is exactly the bug this ordering
+ * fixes. `env-file.js` copies the file into `process.env` at host start-up, so a
+ * leftover line — a rotated key that was never cleaned up, a value from an
+ * older install, a provider row mirrored into the wrong name — became
+ * indistinguishable from a deliberate export and permanently outranked the file
+ * the user had just written. The symptom is the one that gets reported as
+ * "it says the key is saved but it is not using it": `aegiscode login` prints
+ * `key saved`, the desktop prints `saved (aegis_••••1234)`, `key status` reads
+ * back the new key — and every request authenticates with the stale one, so the
+ * account check 401s and nothing names the cause. `env-file.js`'s own contract
+ * is that the file is "a convenience for the common case, not a way for a stale
+ * file to shadow an explicit" setting; `isFromEnvFile()` is what makes that
+ * true for a save as well as for an export.
+ *
+ * @returns {{key:string, source:'env'|'credentials'|'envfile'|'config'|'none', from:string}}
  */
 function resolveApiKey(o = {}) {
   const env = o.env || process.env;
   const dir = o.dir;
   const fromEnv = normalizeApiKey(env && env[KEY_ENV]);
-  if (fromEnv) return { key: fromEnv, source: 'env', from: KEY_ENV };
+  // An explicit export wins outright. A value the env FILE supplied does not:
+  // it is held back to rung 3 so an explicit save outranks it.
+  if (fromEnv && !fromEnvFile(KEY_ENV, env && env[KEY_ENV], env)) {
+    return { key: fromEnv, source: 'env', from: KEY_ENV };
+  }
 
   const creds = readCredentials(dir);
   const stored = normalizeApiKey(creds.aegisApiKey);
   if (stored) return { key: stored, source: 'credentials', from: credentialsPath(dir) };
 
+  if (fromEnv) return { key: fromEnv, source: 'envfile', from: envFileLabel(env, dir) };
+
   const legacy = readLegacyConfig(dir).apiKey;
   if (legacy) return { key: legacy, source: 'config', from: configPath(dir) };
 
@@ -318,10 +384,30 @@ function clientOptions(o = {}) {
 const SOURCE_LABEL = {
   env: `${KEY_ENV}`,
   credentials: 'saved key file',
+  envfile: `~/.aegiscode/.env (${KEY_ENV})`,
   config: 'config.json (aegis CLI)',
   none: 'not set',
 };
 
+/**
+ * The env file a value came from, for the `envfile` status line. Resolved
+ * through env-file.js when it is present so the answer is the real path
+ * (`$AEGISCODE_HOME/.env` included) rather than a guess.
+ */
+function envFileLabel(env, dir) {
+  try {
+    const envFile = require('./env-file.js');
+    if (typeof envFile.envFileFor === 'function') return envFile.envFileFor(dir);
+  } catch {}
+  return envFileForFallback(dir);
+}
+
+/** `~/.aegiscode/.env`, built here so the label survives a host that ships no
+ *  env-file module (same rule aegisHome() exists for). */
+function envFileForFallback(dir) {
+  return path.join(dir || aegisHome(), '.env');
+}
+
 function sourceLabel(source) {
   return SOURCE_LABEL[source] || SOURCE_LABEL.none;
 }
@@ -377,6 +463,8 @@ module.exports = {
   adoptLegacy,
   resolveApiKey,
   hasApiKey,
+  fromEnvFile,
+  envFileForFallback,
   saveApiKey,
   clearApiKey,
   resolveMemoryToken,

package/vendor/env-file.js

@@ -262,9 +262,67 @@ function parseEnvText(text) {
  *   `loaded` — names taken from the file. `kept` — names the environment
  *   already had, left alone (a real export always wins).
  */
+/**
+ * Provenance of every value this process took from `~/.aegiscode/.env`.
+ *
+ * Keyed off the env object itself (a WeakMap, so an injected `{ env }` in a
+ * test is tracked without leaking and `process.env` needs no extra property).
+ * See `isFromEnvFile`.
+ */
+const ENV_SOURCED = new WeakMap();
+
+function sourcedFrom(env) {
+  let map = ENV_SOURCED.get(env);
+  if (!map) {
+    map = new Map();
+    ENV_SOURCED.set(env, map);
+  }
+  return map;
+}
+
+/**
+ * Was `name`'s CURRENT value in `env` one this process took from the shared env
+ * file, rather than something the launching shell exported?
+ *
+ * This is the distinction the file's own rule 1 depends on and could not
+ * previously express. The file is documented as a *convenience for the common
+ * case, not a way for a stale file to shadow an explicit export* — but once a
+ * value is copied into `process.env` the two are the same thing, so every
+ * env-first reader (`client/credentials.js`) treated a line in the file exactly
+ * like a deliberate export and let it win forever. Concretely: a user runs
+ * `aegiscode login`, the key is written to `credentials.json` (0600) and
+ * reported as saved, and every request since then authenticates with whatever
+ * `AEGIS_API_KEY=` line the file still carries — the "it says saved but the key
+ * is wrong" report. A real export still wins; a file value is a fallback.
+ *
+ * `value` is checked as well as the name: a shell export that replaced the
+ * loaded value is no longer file-sourced, and neither is a later `setEnvValue`
+ * (which applies the value it just wrote and marks it accordingly).
+ *
+ * @param {string} name
+ * @param {string} [value] the current value, to confirm it is still the one the
+ *                         file provided. Omit to ask about the name alone.
+ * @param {object} [o]     `env`, for tests and injected environments
+ */
+function isFromEnvFile(name, value, o = {}) {
+  const env = o.env || process.env;
+  const map = ENV_SOURCED.get(env);
+  if (!map || !map.has(name)) return false;
+  if (value === undefined) return true;
+  return map.get(name) === String(value);
+}
+
 function loadEnvFile(o = {}) {
   const env = o.env || process.env;
   const file = o.file || envFileFor(o.dir);
+  // Names this process took from the FILE, with the value it took. Kept so a
+  // consumer can tell the two sources apart: rule 1 above makes the file a
+  // fallback, but the moment its value lands in `process.env` it is otherwise
+  // indistinguishable from an explicit `AEGIS_API_KEY=… aegiscode` export, and
+  // `client/credentials.js`'s resolution order is env-first. Without this
+  // marker a leftover line in a file every host sources at start-up outranks
+  // the key the user explicitly saved — see `isFromEnvFile()` below.
+  const sourced = sourcedFrom(env);
   const result = {
     ok: false, file, loaded: [], kept: [], refused: [], reason: '', loose: false, mode: 0,
   };
@@ -296,8 +354,14 @@ function loadEnvFile(o = {}) {
     }
     if (env[name] === undefined || env[name] === '') {
       env[name] = value;
+      // Provenance: this value is the FILE's, not the launching shell's. An
+      // env-first reader must treat it as the fallback the file is documented
+      // to be, not as an explicit export that outranks a saved key.
+      sourced.set(name, value);
       result.loaded.push(name);
     } else {
+      // A real export wins (rule 1) and is deliberately NOT marked: it is the
+      // one source allowed to outrank `credentials.json`.
       result.kept.push(name);
     }
   }
@@ -615,7 +679,12 @@ function setEnvValue(name, value, o = {}) {
     out.changed = false;
     out.replaced = true;
     out.mode = previousMode || SECRET_FILE_MODE;
-    if (o.apply !== false) env[name] = secret;
+    if (o.apply !== false) {
+      env[name] = secret;
+      // Applied, and the file carries it: file-sourced, so an env-first reader
+      // treats it as the fallback it is (see isFromEnvFile).
+      sourcedFrom(env).set(name, secret);
+    }
     return out;
   }
 
@@ -640,7 +709,11 @@ function setEnvValue(name, value, o = {}) {
   out.replaced = replaced;
   out.mode = SECRET_FILE_MODE;
   out.tightened = !out.created && previousMode !== 0 && (previousMode & 0o077) !== 0;
-  if (o.apply !== false) env[name] = secret;
+  if (o.apply !== false) {
+    env[name] = secret;
+    // Just written to the file and applied here: file-sourced (see above).
+    sourcedFrom(env).set(name, secret);
+  }
   return out;
 }
 
@@ -810,16 +883,91 @@ function keyStatus(name, o = {}) {
  *
  * @param {string} modelId
  * @param {string} [cls] 'byok' | 'aegis' | anything else
- * @returns {{env:string, provider:string, pooled:boolean}}
+ * @returns {{env:string, provider:string, vendor:string, pooled:boolean}}
  */
 function keyForModelId(modelId, cls) {
   const id = String(modelId == null ? '' : modelId).trim();
   const byok = String(cls || '').toLowerCase() === 'byok' || id.includes(':');
   if (byok && id.includes(':')) {
     const provider = id.slice(0, id.indexOf(':')).trim();
-    return { env: envVarFor(provider), provider, pooled: false };
+    return { env: envVarFor(provider), provider, vendor: provider, pooled: false };
+  }
+  // A pooled id is served by the pool, so the credential the ROUTE needs is the
+  // account key — but the id may still NAME the vendor underneath it
+  // (`deepseek`, `anthropic-haiku`, `openai-gpt4o-mini`). That vendor is what
+  // `vendor` reports, and it is not the same question as `env`: it is the
+  // provider key a user may also want on this machine, which the picker asks
+  // for after the account key. `provider` stays '' for pooled on purpose — the
+  // byok call path reads it as "which provider's settings row to address", and
+  // a pooled row has none.
+  return { env: ACCOUNT_ENV_VAR, provider: '', vendor: providerForModelId(id, cls), pooled: true };
+}
+
+/**
+ * Vendors whose slug is a namespace a model id may be spelled under.
+ *
+ * Deliberately a *table* and not a pattern: the derivation below is a claim that
+ * a key for this vendor exists, so an id whose first segment is not on this list
+ * derives NO vendor (and the picker asks only for the account key) rather than
+ * inventing a variable name like `NEXUS_API_KEY` for the pool's own namespace.
+ * The list is the platform's providers as its own BYOK catalog spells them
+ * (aegis1 services/nexus_provider/catalog.py MODEL_CATALOG) plus the ids this
+ * module already re-spells in ALIASES above — keep it in step with that catalog,
+ * not with whatever vendor a user might mention.
+ */
+const VENDOR_SLUGS = Object.freeze([
+  'openai',
+  'anthropic',
+  'deepseek',
+  'google',
+  'gemini',
+  'groq',
+  'mistral',
+  'openrouter',
+  'together',
+  'together-ai',
+  'xai',
+  'x-ai',
+  'grok',
+  'huggingface',
+  'fireworks',
+  'voyage-ai',
+  'azure-openai',
+]);
+
+/** The multi-segment slugs, longest first, so `azure-openai-x` matches the full slug. */
+const VENDOR_COMPOUNDS = Object.freeze(
+  VENDOR_SLUGS.filter((s) => s.includes('-')).sort((a, b) => b.length - a.length)
+);
+
+/**
+ * The vendor a model id names, or '' — `deepseek-flash` → `deepseek`,
+ * `nexus-brain` → '', `deepseek:deepseek-v4-flash` → `deepseek`.
+ *
+ * The one question the picker needs to answer "is there a SECOND key worth
+ * asking for on this row?" A pooled row is billed to the AEGIS account, so its
+ * route needs the account key and nothing else — but when the row is named
+ * after a vendor whose key this machine could hold (`deepseek`), asking for that
+ * key too is what lets the account actually call the model instead of the pool
+ * failing a turn with "no provider key". That is the gap this closes:
+ * aegis-key present, models listed, and every turn still failing because the
+ * vendor key the models route through was never collected.
+ *
+ * @param {string} modelId
+ * @param {string} [cls] unused by the derivation; accepted so a caller can pass
+ *   the same (id, cls) pair it passes `keyForModelId` without branching.
+ * @returns {string} the vendor slug, or '' when the id names none this module
+ *   knows a variable for.
+ */
+function providerForModelId(modelId, cls) { // eslint-disable-line no-unused-vars
+  const id = String(modelId == null ? '' : modelId).trim().toLowerCase();
+  if (!id) return '';
+  if (id.includes(':')) return id.slice(0, id.indexOf(':')).trim();
+  for (const slug of VENDOR_COMPOUNDS) {
+    if (id === slug || id.startsWith(slug + '-')) return slug;
   }
-  return { env: ACCOUNT_ENV_VAR, provider: '', pooled: true };
+  const first = id.split('-')[0];
+  return VENDOR_SLUGS.includes(first) ? first : '';
 }
 
 module.exports = {
@@ -831,7 +979,15 @@ module.exports = {
   envVarFor,
   parseEnvText,
   loadEnvFile,
+  // Provenance of what loadEnvFile put in the environment: a value taken from
+  // the FILE is a fallback, not an explicit export, and the env-first readers
+  // (client/credentials.js) must be able to tell the two apart.
+  isFromEnvFile,
   providerKeyFromEnv,
+  // The vendor half of "what key does this model id need": the account key is
+  // the route's credential, this is the provider key underneath it.
+  providerForModelId,
+  VENDOR_SLUGS,
   isWritableName,
   quoteEnvValue,
   upsertEnvText,