aegiscode 6.3.2 → 6.4.0

package/src/commands.js

@@ -58,6 +58,9 @@ const { summarizeTranscript, recapLine } = require('./summarize.js');
 const { sessionAccounting, accountingFromUsage, estimateTokens } = require('./tokens.js');
 const { transcriptToMarkdown, transcriptToJSON, writeExportFile, lastAssistantText } = require('./export.js');
 const { detectDevCommand, runDevServer } = require('./devrun.js');
+const credentials = require('./credentials.js');
+const cloudsync = require('./cloudsync.js');
+const { maskKey } = require('./format.js');
 const { openUrl, URLS } = require('./system.js');
 const { sniffProject, buildAegisMd } = require('./init.js');
 const {
@@ -127,8 +130,117 @@ async function loadModels(c) {
  * The ÆGIS LLM routes are gated on the pooled brain being reachable — exactly
  * as the reference hides its ÆGIS routes when the backend is absent. `hidden`
  * is a function so visibility follows the environment at call time.
+ *
+ * It reads the *resolved* credential, not the environment: a key saved by
+ * `aegiscode login` lives in credentials.json, and checking only
+ * `process.env.AEGIS_API_KEY` here hid every AEGIS route from a user who had
+ * just successfully set one.
+ */
+const cloudReady = () => credentials.hasApiKey();
+
+// ── account key + cloud sync handlers ────────────────────────────────────────
+
+/** The account-key panel body, shared by /key, /login and /cloud. */
+function keyPanelLines(c, title = 'AEGIS account key') {
+  const st = c.keyStatus();
+  const lines = [
+    [span(C.gold + BOLD, title), span(BOLD_OFF, '')],
+    [span(C.gray, '─'.repeat(34))],
+    [
+      span(st.configured ? C.green : C.coral, `  ${st.configured ? '✔' : '⚠'}`),
+      span(C.white, '  key: '),
+      span(st.configured ? C.white : C.gray, st.configured ? maskKey(st.key) : 'not set'),
+      span(C.gray, `  (${credentials.sourceLabel(st.source)})`),
+    ],
+    [span(C.gray, `  stored in: ${st.path}${st.fileMode ? `  ${st.fileMode}` : ''}`)],
+  ];
+  if (st.verifiedAt) lines.push([span(C.gray, `  verified:  ${st.verifiedAt}`)]);
+  if (st.account && (st.account.plan || st.account.email)) {
+    lines.push([
+      span(C.gray, '  account:   '),
+      span(C.white, [st.account.plan, st.account.email].filter(Boolean).join(' · ')),
+    ]);
+  }
+  lines.push([
+    span(C.gray, '  memory:    '),
+    span(st.memoryToken ? C.green : C.gray, st.memoryToken ? 'token held (cloud sync ready)' : 'no token yet'),
+  ]);
+  if (!st.configured) {
+    lines.push([span(C.gray, '')]);
+    lines.push([span(C.white, '  Set one with /key <api_key>, or press Enter on /key to paste it.')]);
+    lines.push([span(C.gray, '  Free keys: https://aegiscloud.org')]);
+  }
+  if (st.legacyPlaintext) {
+    lines.push([span(C.gray, '')]);
+    lines.push([
+      span(C.coral, '  ⚠ a plaintext copy of the key is still in config.json (another AEGIS CLI wrote it).'),
+    ]);
+    lines.push([span(C.gray, '    Re-save with /key <api_key> and delete that block when convenient.')]);
+  }
+  return lines;
+}
+
+/**
+ * Take a key from the argument or an echo-off prompt, save it, and report what
+ * the account said. Shared by `/key`, `/login` and `/cloud key` so all three
+ * behave identically — the whole point is that there is one way to set a key.
  */
-const cloudReady = () => !!process.env.AEGIS_API_KEY;
+async function applyAccountKey(c, raw, { label = 'AEGIS API key' } = {}) {
+  let key = String(raw || '').trim();
+  if (!key) {
+    key = await c.readSecret(`${label} (kept off screen, Enter to cancel): `);
+  }
+  if (!key) {
+    note(c, 'no key given — /key <api_key> takes it inline, or press Enter on a bare /key to paste it');
+    return { ok: false };
+  }
+  const res = await c.setApiKey(key);
+  if (!res.ok) {
+    note(c, res.message || 'that key could not be saved');
+    return res;
+  }
+  if (res.error) {
+    note(c, `saved, but the account check failed: ${res.error.message}`);
+    note(c, 'the key is stored — /key status shows it; re-run /key <api_key> if it was mistyped');
+    return res;
+  }
+  const acct = (res.account && (res.account.email || res.account.plan)) || null;
+  done(c, `AEGIS key saved to ${res.path}${acct ? ` — signed in as ${acct}` : ' and verified'}`);
+  // The catalog is key-gated, so a freshly authenticated session should offer
+  // /model's picker without the user having to know to re-run it.
+  try {
+    await c.loadModels({ force: true });
+    const n = (c.state().models || []).length;
+    if (n) note(c, `${n} pinnable model${n === 1 ? '' : 's'} available — /model to pin one`);
+  } catch {}
+  return res;
+}
+
+/** Push + pull once, and report the counts (or the quota refusal). */
+async function runCloudSync(c, o = {}) {
+  if (!c.client.apiKey) {
+    note(c, `no key — ${credentials.HOW_TO_SET}`);
+    return null;
+  }
+  const res = await c.withWorking(() => cloudsync.syncNow(c.client, o));
+  const pushed = (res.push && res.push.pushed) || [];
+  const failed = [...((res.push && res.push.failed) || []), ...((res.pull && res.pull.failed) || [])];
+  const pulled = (res.pull && res.pull.imported) || 0;
+  if (pushed.length) {
+    done(c, `pushed ${pushed.length} session${pushed.length === 1 ? '' : 's'} (${pushed[0].messages} messages in the first)`);
+  } else if (res.push && res.push.skipped && res.push.skipped.length) {
+    note(c, `${res.push.skipped.length} session(s) had nothing to send`);
+  } else {
+    note(c, 'nothing to push — every local session is already in the cloud');
+  }
+  if (pulled) done(c, `pulled ${pulled} record${pulled === 1 ? '' : 's'} into the local store — /resume lists them`);
+  else if (res.pull && res.pull.ok) note(c, `cloud has ${res.pull.remote || 0} session(s); nothing newer locally`);
+  for (const f of failed) {
+    note(c, `${f.kind === 'quota' ? 'quota' : 'failed'}: ${f.message}`);
+    if (f.hint) note(c, f.hint);
+  }
+  return res;
+}
 
 /** Read + merge hook config from the standard settings files. */
 function readHooks() {
@@ -467,15 +579,32 @@ const COMMANDS = [
     },
   },
   {
-    name: 'login', hint: '', category: 'auth',
-    desc: 'Sign in to Claude Code',
-    unavailable: 'sign-in uses Claude Code auth, which this client does not have — it authenticates with your AEGIS key',
-    alt: '/byok-set',
+    name: 'login', aliases: ['signin'], args: ['value'], hint: '[<api_key>]', category: 'auth',
+    desc: 'Save your AEGIS API key',
+    handler: async (c, args) => {
+      // This used to be `unavailable` with `/byok-set` as its alternative —
+      // which was worse than useless: /byok-set stores a *provider* key
+      // server-side, so a user following that advice pasted their AEGIS key
+      // into a BYOK provider slot. Signing in to AEGIS Cloud *is* handing over
+      // an API key, and this is now where you give it one.
+      const arg = String(args.value || args._rest || '').trim();
+      await applyAccountKey(c, arg, { label: 'AEGIS API key' });
+      c.render();
+      return true;
+    },
   },
   {
-    name: 'logout', hint: '', category: 'auth',
-    desc: 'Sign out',
-    unavailable: 'there is no Claude Code sign-in here to end — aegiscode holds no session token of its own',
+    name: 'logout', args: [], hint: '', category: 'auth',
+    desc: 'Remove the saved AEGIS API key',
+    handler: async (c) => {
+      const res = c.forgetApiKey();
+      done(c, res.cleared ? `key removed from ${res.path}` : 'there was no saved key to remove');
+      if (credentials.legacyKeyOnDisk()) {
+        note(c, `a copy is still in ${configPath()} (another AEGIS CLI wrote it) — delete its "aegiscloud" block too`);
+      }
+      c.render();
+      return true;
+    },
   },
   {
     name: 'model', aliases: ['m'], args: ['sub'], hint: '[id|-]', category: 'model',
@@ -709,8 +838,19 @@ const COMMANDS = [
       let git = false;
       try { execSync('git rev-parse --git-dir', { cwd: process.cwd(), stdio: ['ignore', 'ignore', 'ignore'], timeout: 4000 }); git = true; } catch {}
       ok('git repo', git, git ? 'inside a work tree' : 'not a git repository');
-      const key = process.env.AEGIS_API_KEY || '';
-      ok('AEGIS_API_KEY', !!key, key ? 'set' : 'not set — export one (https://aegiscloud.org)');
+      const ks = credentials.keyStatus();
+      ok(
+        'AEGIS key',
+        ks.configured,
+        ks.configured
+          ? `${maskKey(ks.key)} via ${credentials.sourceLabel(ks.source)}`
+          : `not set — ${credentials.HOW_TO_SET} (free at https://aegiscloud.org)`
+      );
+      ok('credentials', true, `${ks.path}${ks.fileMode ? ` (${ks.fileMode})` : ''}`);
+      ok('cloud memory', ks.memoryToken, ks.memoryToken ? 'token held' : 'no memory token — /cloud activate');
+      if (ks.legacyPlaintext) {
+        ok('plaintext key', false, `a copy also sits in ${configPath()} (another AEGIS CLI) — /key re-saves it to ${ks.path}`);
+      }
       ok('config path', true, configPath());
       const lines = [[span(C.gold + BOLD, 'Doctor'), span(BOLD_OFF, '')], [span(C.gray, '─'.repeat(30))]];
       for (const [good, label, detail] of checks) {
@@ -1205,17 +1345,145 @@ const COMMANDS = [
     },
   },
   {
-    name: 'cloud', args: ['sub', 'value'], hint: '[status|key <api_key>|activate|deactivate]', category: 'support',
-    desc: 'Show ÆGIS cloud sync status',
+    name: 'cloud', args: ['sub', 'value'], hint: '[status|key <api_key>|activate|deactivate|sync [on|off|now]]', category: 'support',
+    desc: 'Show and control ÆGIS cloud sync',
     handler: async (c, args) => {
       const sub = (args.sub || '').toLowerCase();
-      if (['key', 'activate', 'deactivate'].includes(sub)) {
-        note(c, 'ÆGIS cloud key/sync is managed by the aegis CLI: run `aegis login` (free) — aegiscode does not store cloud keys.');
+      const rest = (args.value || args._rest || '').trim();
+
+      if (sub === 'key') {
+        await applyAccountKey(c, rest);
         c.render();
         return true;
       }
-      const st = c.state();
-      panel(c, panels.buildAegisStatus({ ...st, cloud: { key: st.online, sync: st.online } }, c.ctx));
+
+      if (sub === 'activate') {
+        if (!c.client.apiKey) {
+          note(c, `no key — ${credentials.HOW_TO_SET}`);
+          c.render();
+          return true;
+        }
+        try {
+          const res = await c.withWorking(() => c.client.memoryActivate());
+          const token = await c.client.getMemoryToken();
+          if (token) credentials.saveMemoryToken(token, { memorySubscribed: true });
+          done(c, res && res.ok === false ? 'the server refused activation' : 'cloud memory activated for this account');
+          if (res && res.token_limit) note(c, `quota: ${res.tokens_used || 0} / ${res.token_limit} synced tokens`);
+        } catch (e) {
+          note(c, `activation failed: ${e.message}`);
+        }
+        c.render();
+        return true;
+      }
+
+      if (sub === 'deactivate') {
+        // There is no /api/memory/deactivate on the server, so this clears the
+        // credential this host holds rather than pretending to unenrol the
+        // account. Saying which one it did is the difference between a control
+        // and a lie.
+        credentials.clearMemoryToken();
+        c.client.setApiKey(c.client.apiKey);
+        note(c, 'cloud memory token cleared locally — sync stops until /cloud activate re-issues one');
+        note(c, 'the account itself is still subscribed; manage the subscription at https://aegiscloud.org/subscribe');
+        c.render();
+        return true;
+      }
+
+      if (sub === 'sync' || sub === 'push' || sub === 'pull') {
+        const mode = sub === 'sync' ? (rest || 'status').toLowerCase() : sub;
+        if (mode === 'on' || mode === 'off') {
+          const on = mode === 'on';
+          c.setCloudSync(on);
+          note(c, on ? 'cloud sync on — /sync now pushes after each turn' : 'cloud sync off — nothing is sent until /sync now');
+          c.render();
+          return true;
+        }
+        if (mode === 'now') {
+          await runCloudSync(c);
+          c.render();
+          return true;
+        }
+        const st = cloudsync.status();
+        const rows = [
+          [span(C.gold + BOLD, 'Cloud sync'), span(BOLD_OFF, '')],
+          [span(C.gray, '─'.repeat(34))],
+          [span(C.white, `  ${c.cloudSyncEnabled() ? 'on' : 'off'}`), span(C.gray, c.cloudSyncEnabled() ? '  (auto-push each turn)' : '  (manual: /sync now)')],
+          [span(C.gray, `  local sessions: ${st.local}  ·  pending push: ${st.pending}  ·  in sync: ${st.synced}`)],
+          [span(C.gray, `  last push: ${st.lastPushAt ? new Date(st.lastPushAt).toLocaleString() : 'never'}  ·  last pull: ${st.lastPullAt ? new Date(st.lastPullAt).toLocaleString() : 'never'}`)],
+          [span(C.gray, `  state: ${st.path}`)],
+        ];
+        for (const e of st.errors.slice(0, 3)) {
+          rows.push([span(C.coral, `  ⚠ ${e.error}`)]);
+        }
+        panel(c, rows);
+        c.render();
+        return true;
+      }
+
+      // Default: the whole picture — key plus sync state.
+      const st = cloudsync.status();
+      panel(c, [
+        ...keyPanelLines(c, 'AEGIS cloud'),
+        [span(C.gray, '')],
+        [span(C.white + BOLD, '  Sync'), span(BOLD_OFF, '')],
+        [span(C.gray, `  ${c.cloudSyncEnabled() ? 'on' : 'off'}  ·  ${st.pending} pending  ·  ${st.synced} in sync  ·  ${st.importedRemote} pulled from cloud`)],
+        [span(C.gray, '  /cloud sync on | now | off')],
+      ]);
+      c.render();
+      return true;
+    },
+  },
+  {
+    name: 'key', aliases: ['apikey', 'api-key'], args: ['value'], hint: '[<api_key>|status|clear]', category: 'auth',
+    desc: 'Save or show the AEGIS account key',
+    handler: async (c, args) => {
+      const arg = String(args.value || args._rest || '').trim();
+      const lower = arg.toLowerCase();
+      if (lower === 'status') {
+        panel(c, keyPanelLines(c));
+        c.render();
+        return true;
+      }
+      if (lower === 'clear' || lower === 'remove' || lower === 'rm') {
+        const res = c.forgetApiKey();
+        done(c, res.cleared ? `key removed from ${res.path}` : 'there was no saved key to remove');
+        if (credentials.legacyKeyOnDisk()) {
+          note(c, `a copy is still in ${configPath()} (written by another AEGIS CLI) — delete the "aegiscloud" block to finish the job`);
+        }
+        c.render();
+        return true;
+      }
+      await applyAccountKey(c, arg);
+      c.render();
+      return true;
+    },
+  },
+  {
+    name: 'sync', aliases: ['cloudsync', 'cloud-sync'], args: ['mode'], hint: '[now|on|off|status]', category: 'data',
+    desc: 'Sync conversations with AEGIS Cloud',
+    hidden: (c) => !cloudReady(),
+    handler: async (c, args) => {
+      const mode = (args.mode || '').toLowerCase();
+      if (mode === 'on' || mode === 'off') {
+        c.setCloudSync(mode === 'on');
+        note(c, mode === 'on' ? 'cloud sync on' : 'cloud sync off — /sync now still runs a manual pass');
+        c.render();
+        return true;
+      }
+      if (mode === 'status') {
+        const st = cloudsync.status();
+        panel(c, [
+          [span(C.gold + BOLD, 'Cloud sync'), span(BOLD_OFF, '')],
+          [span(C.gray, '─'.repeat(34))],
+          [span(C.white, `  ${c.cloudSyncEnabled() ? 'on' : 'off'}`)],
+          [span(C.gray, `  local ${st.local}  ·  pending ${st.pending}  ·  in sync ${st.synced}`)],
+        ]);
+        c.render();
+        return true;
+      }
+      // Bare /sync and /sync now both do the thing: this is the command a user
+      // reaches for when they want their sessions in the cloud right now.
+      await runCloudSync(c);
       c.render();
       return true;
     },

package/src/credentials.js

@@ -0,0 +1,323 @@
+'use strict';
+
+/**
+ * The AEGIS account credential store for the terminal host.
+ *
+ * Before this module the CLI had exactly one way to be given a key: an
+ * `AEGIS_API_KEY` environment variable, checked as `process.env.AEGIS_API_KEY`
+ * at five separate call sites. A shell export does not survive a new terminal,
+ * a reboot, an SSH session or a desktop launcher, so every one of those turned
+ * the product back into "no key — export one" with no in-band way to fix it:
+ * `/byok-set` stores *provider* keys server-side and `/login` is one of the
+ * reference commands this host deliberately marks unavailable. The only
+ * credential the CLI could not accept was its own.
+ *
+ * Resolution order, first hit wins:
+ *
+ *   1. `AEGIS_API_KEY` — the environment, so CI and `--key` keep working and
+ *      nothing written here can shadow an explicit export.
+ *   2. `credentials.json` in the data dir, mode 0600. The writable store.
+ *   3. `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
+ *      next run reads the 0600 copy, and `/cloud status` says the plaintext
+ *      copy is still there rather than silently leaving it.
+ *
+ * The key is never printed in full by anything in this package; callers mask it
+ * with format.js's maskKey.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { aegisDir, configPath } = require('./config.js');
+
+const KEY_ENV = 'AEGIS_API_KEY';
+/** Optional override for the memory token (cloud sync's own credential). */
+const MEMORY_ENV = 'AEGIS_MEMORY_TOKEN';
+const CREDENTIALS_FILE = 'credentials.json';
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+
+function credentialsPath() {
+  return path.join(aegisDir(), CREDENTIALS_FILE);
+}
+
+/**
+ * Accept the key in the shapes a user actually pastes it.
+ *
+ * Copy-paste from a dashboard, a `.env` line, a shell profile or a chat message
+ * are all realistic — and pasting `AEGIS_API_KEY=aegis_…` or `"aegis_…"` into a
+ * prompt that stores the literal string produces an auth failure the user
+ * cannot see the cause of, because the key *looks* right in the status line.
+ */
+function normalizeApiKey(raw) {
+  let s = String(raw == null ? '' : raw).trim();
+  if (!s) return '';
+  s = s.replace(/^export\s+/i, '').trim();
+  const assignment = /^[A-Za-z_][A-Za-z0-9_]*\s*=\s*(.+)$/s.exec(s);
+  if (assignment) s = assignment[1].trim();
+  s = s.replace(/^["']|["']$/g, '').trim();
+  s = s.replace(/^Bearer\s+/i, '').trim();
+  return s;
+}
+
+/**
+ * Shape check only — no network. Catches the two mistakes that are structural
+ * (an empty paste, and a wrapped/truncated multi-line paste) so the caller can
+ * refuse before spending a verification round trip.
+ */
+function validateApiKey(raw) {
+  const key = normalizeApiKey(raw);
+  if (!key) return { ok: false, key, reason: 'empty', message: 'no key given' };
+  if (/\s/.test(key)) {
+    return {
+      ok: false,
+      key,
+      reason: 'whitespace',
+      message: 'that looks like more than one word — paste just the key',
+    };
+  }
+  if (key.length < 16) {
+    return {
+      ok: false,
+      key,
+      reason: 'too short',
+      message: `that key is ${key.length} characters — AEGIS keys are longer than that`,
+    };
+  }
+  return { ok: true, key, reason: null, message: null };
+}
+
+/** The stored credential object, or {} — never throws on a missing/corrupt file. */
+function readCredentials() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(credentialsPath(), 'utf8'));
+    if (parsed && typeof parsed === 'object') return parsed;
+  } catch {}
+  return {};
+}
+
+/**
+ * Merge a patch into the store, creating it 0600 (and tightening an existing
+ * file that is wider — a key file that a previous run left 0644 is exactly the
+ * leak this file exists to avoid).
+ */
+function writeCredentials(patch) {
+  const next = { ...readCredentials(), ...patch, version: 1 };
+  try {
+    fs.mkdirSync(aegisDir(), { recursive: true, mode: DIR_MODE });
+    const target = credentialsPath();
+    const tmp = target + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: FILE_MODE });
+    fs.renameSync(tmp, target);
+    try {
+      fs.chmodSync(target, FILE_MODE);
+    } catch {}
+  } catch (e) {
+    if (process.env.AEGIS_HIST_DEBUG) console.error('[credentials] write failed:', e);
+    return { ok: false, error: e, credentials: next };
+  }
+  return { ok: true, credentials: next };
+}
+
+/**
+ * The key an earlier AEGIS CLI wrote into config.json (the `aegiscloud` /
+ * `memory` blocks are not ours — config.js cannot produce them). Read-only.
+ */
+function readLegacyConfig() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return {};
+    const cloud = parsed.aegiscloud && typeof parsed.aegiscloud === 'object' ? parsed.aegiscloud : {};
+    const memory = parsed.memory && typeof parsed.memory === 'object' ? parsed.memory : {};
+    return {
+      apiKey: normalizeApiKey(cloud.api_key),
+      memoryToken: String(memory.token || '').trim(),
+      syncConversations: cloud.syncConversations === true ? true : undefined,
+      lastVerified: cloud.lastVerified || null,
+      memorySubscribed: memory.subscribed === true ? true : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** True when config.json still carries a plaintext copy of the account key. */
+function legacyKeyOnDisk() {
+  return !!readLegacyConfig().apiKey;
+}
+
+/**
+ * Copy a legacy key/token into the 0600 store, once, without touching the file
+ * it came from. Returns which fields were adopted so the caller can say so.
+ */
+function adoptLegacy() {
+  const legacy = readLegacyConfig();
+  const creds = readCredentials();
+  const patch = {};
+  if (legacy.apiKey && !creds.aegisApiKey) patch.aegisApiKey = legacy.apiKey;
+  if (legacy.memoryToken && !creds.memoryToken) patch.memoryToken = legacy.memoryToken;
+  if (!Object.keys(patch).length) return { adopted: [] };
+  const written = writeCredentials({ ...patch, adoptedFrom: configPath() });
+  if (!written.ok) return { adopted: [] };
+  return { adopted: Object.keys(patch) };
+}
+
+/**
+ * The key to use, and where it came from.
+ *
+ * @returns {{key:string, source:'env'|'credentials'|'config'|'none', from:string}}
+ */
+function resolveApiKey(o = {}) {
+  const env = o.env || process.env;
+  const fromEnv = normalizeApiKey(env && env[KEY_ENV]);
+  if (fromEnv) return { key: fromEnv, source: 'env', from: KEY_ENV };
+
+  const creds = readCredentials();
+  const stored = normalizeApiKey(creds.aegisApiKey);
+  if (stored) return { key: stored, source: 'credentials', from: credentialsPath() };
+
+  const legacy = readLegacyConfig().apiKey;
+  if (legacy) return { key: legacy, source: 'config', from: configPath() };
+
+  return { key: '', source: 'none', from: '' };
+}
+
+/** Whether any credential is available (env, store or legacy config). */
+function hasApiKey(o = {}) {
+  return !!resolveApiKey(o).key;
+}
+
+/**
+ * Persist a key.
+ *
+ * @returns {{ok:boolean, key:string, path:string, error?:Error, message?:string}}
+ */
+function saveApiKey(raw) {
+  const v = validateApiKey(raw);
+  if (!v.ok) return { ok: false, key: v.key, path: credentialsPath(), message: v.message };
+  const written = writeCredentials({ aegisApiKey: v.key, savedAt: new Date().toISOString() });
+  if (!written.ok) {
+    return {
+      ok: false,
+      key: v.key,
+      path: credentialsPath(),
+      error: written.error,
+      message: `could not write ${credentialsPath()}`,
+    };
+  }
+  return { ok: true, key: v.key, path: credentialsPath() };
+}
+
+/**
+ * Remove the stored key (and nothing else — the memory token stays, since a
+ * key rotation should not silently unsubscribe cloud memory). config.json is
+ * never touched: another product writes it.
+ */
+function clearApiKey() {
+  const had = !!normalizeApiKey(readCredentials().aegisApiKey);
+  const written = writeCredentials({ aegisApiKey: '', adoptedFrom: '' });
+  return { cleared: had, ok: written.ok, path: credentialsPath() };
+}
+
+/** The memory token cloud sync authenticates with, from store or legacy. */
+function resolveMemoryToken(o = {}) {
+  const env = o.env || process.env;
+  const fromEnv = String((env && env[MEMORY_ENV]) || '').trim();
+  if (fromEnv) return { token: fromEnv, source: 'env' };
+  const creds = readCredentials();
+  const stored = String(creds.memoryToken || '').trim();
+  if (stored) return { token: stored, source: 'credentials' };
+  const legacy = readLegacyConfig().memoryToken;
+  if (legacy) return { token: legacy, source: 'config' };
+  return { token: '', source: 'none' };
+}
+
+function saveMemoryToken(token, extra = {}) {
+  return writeCredentials({ memoryToken: String(token || '').trim(), ...extra });
+}
+
+function clearMemoryToken() {
+  return writeCredentials({ memoryToken: '', memorySubscribed: false });
+}
+
+/**
+ * Everything a status screen or a `doctor` line needs about the credential,
+ * without ever exposing the key itself.
+ */
+function keyStatus(o = {}) {
+  const { key, source, from } = resolveApiKey(o);
+  const creds = readCredentials();
+  let mode = null;
+  try {
+    mode = fs.statSync(credentialsPath()).mode & 0o777;
+  } catch {}
+  return {
+    configured: !!key,
+    key,
+    source,
+    from,
+    path: credentialsPath(),
+    fileMode: mode == null ? null : '0' + mode.toString(8),
+    stored: !!normalizeApiKey(creds.aegisApiKey),
+    legacyPlaintext: legacyKeyOnDisk(),
+    verifiedAt: creds.verifiedAt || null,
+    account: creds.account || null,
+    memoryToken: !!resolveMemoryToken(o).token,
+    memorySource: resolveMemoryToken(o).source,
+  };
+}
+
+/**
+ * Client options for `createClient`: the resolved key plus the stored memory
+ * token, so a restart does not re-exchange for a token it already has.
+ */
+function clientOptions(o = {}) {
+  const { key } = resolveApiKey(o);
+  const { token } = resolveMemoryToken(o);
+  const opts = {};
+  if (key) opts.apiKey = key;
+  if (token) opts.memoryToken = token;
+  return opts;
+}
+
+/** Human label for a resolution source, for status lines. */
+const SOURCE_LABEL = {
+  env: `$${KEY_ENV}`,
+  credentials: 'saved key file',
+  config: 'config.json (aegis CLI)',
+  none: 'not set',
+};
+
+function sourceLabel(source) {
+  return SOURCE_LABEL[source] || SOURCE_LABEL.none;
+}
+
+/** One line telling the user how to supply a key, used by every error path. */
+const HOW_TO_SET = 'run `aegiscode login` (or /key inside a session) to save one';
+
+module.exports = {
+  KEY_ENV,
+  MEMORY_ENV,
+  CREDENTIALS_FILE,
+  credentialsPath,
+  normalizeApiKey,
+  validateApiKey,
+  readCredentials,
+  writeCredentials,
+  readLegacyConfig,
+  legacyKeyOnDisk,
+  adoptLegacy,
+  resolveApiKey,
+  hasApiKey,
+  saveApiKey,
+  clearApiKey,
+  resolveMemoryToken,
+  saveMemoryToken,
+  clearMemoryToken,
+  keyStatus,
+  clientOptions,
+  sourceLabel,
+  HOW_TO_SET,
+};