aegiscode 6.3.2 → 6.5.0

package/README.md

@@ -38,12 +38,26 @@ npm install -g aegiscode
 node cli/bin/aegiscode.js
 ```
 
-Requires Node 18+. Set your key once:
+Requires Node 18+. Save your key once — it goes to `~/.aegiscode/credentials.json`
+(mode `0600`) and is then picked up by every later launch, script and shell:
 
 ```bash
-export AEGIS_API_KEY="aegis_..."
+aegiscode login                    # prompts, no echo
+aegiscode login "aegis_..."        # or inline
+aegiscode key status               # masked key + which source is in use
+aegiscode logout                   # remove it
 ```
 
+`AEGIS_API_KEY` still works and still wins (useful in CI, or for a one-off);
+`aegiscode --key <key>` applies to a single run and is never saved. A key an
+older AEGIS CLI left in `~/.aegiscode/config.json` is picked up and copied into
+the 0600 store automatically — `/cloud status` says so if the plaintext copy is
+still there.
+
+That one file is shared: the MCP plugin and AEGIS Desktop read the same store, so
+signing in here signs you in everywhere (see [One memory, shared with AEGIS
+Desktop](#one-memory-shared-with-aegis-desktop)).
+
 ## Use
 
 ```bash
@@ -101,8 +115,8 @@ command for command — 75 entries across nine categories:
 | Session & context | `/clear` `/compact` `/cost` `/exit` `/new` `/recap` `/resume` `/rewind` `/agents` `/status` `/teleport` `/version` `/clone` `/schedule` |
 | Workspace | `/run` `/build` `/cd` `/copy` `/init` `/review` `/prs` |
 | Model & behavior | `/model` `/effort` `/thinking` `/theme` `/vim` `/router` `/confirm` `/yolo` `/permissions` `/hooks` `/skills` `/mcp` |
-| Data | `/context` `/export` `/tokens` |
-| Auth | `/credentials` `/byok` `/byok-set` `/byok-rm` |
+| Data | `/context` `/export` `/tokens` `/sync` |
+| Auth | `/key` `/login` `/logout` `/credentials` `/byok` `/byok-set` `/byok-rm` |
 | Support | `/help` `/doctor` `/troubleshooting` `/feedback` `/bug` `/issue` `/onboarding` `/benchmark` `/release-notes` `/billing` `/cloud` |
 | Aegis plugin | `/aegis-ask` `/aegis-status` `/aegis-recall` `/aegis-remember` `/memory` `/aegis-council` `/aegis-multi` `/aegis-print` `/aegis-import` `/tool` |
 | Fun | `/radio` `/waifu` |
@@ -119,10 +133,60 @@ the project and writes `AEGIS.md`, `/export` writes the transcript out,
 `/resume` and `/rewind` read the session store, `/cd` moves the working
 directory, `/doctor` runs diagnostics.
 
-The only two commands that answer "not available" are `/login` and `/logout`:
-their whole premise is Claude Code's own auth loop, which this client does not
-participate in — it authenticates with an AEGIS key (or your own provider key
-via `/byok-set`). They say so, and point at the working alternative.
+## Account key and cloud sync
+
+Three ways in, one store: `aegiscode login <key>`, `/key <api_key>` (or a bare
+`/key` to paste it echo-off), and `$AEGIS_API_KEY`. The first two persist;
+the env var outranks the store and needs no persistence. `/login` used to be an
+unavailable Claude Code auth-loop command pointing at `/byok-set` — which stores
+a *provider* key, so that advice sent the AEGIS key into the wrong slot. It is
+now the in-band way to set the account key, and `/logout` removes it.
+
+Conversation sync is the same `conversationSyncPush/Pull` surface the desktop
+uses, over the sessions this host keeps in `~/.aegiscode/history.jsonl`:
+
+```bash
+/sync                 # push what is pending, then pull — the one you want
+/sync status          # local / pending / in-sync counts, last push and pull
+/sync on | off         # auto-push after each turn (off by default)
+/cloud                 # key + sync state in one panel
+/cloud activate        # turn on cloud memory for the account
+```
+
+Sync is **off by default** on purpose: the server charges a push for the growth
+of a session against the plan's synced-token ceiling, so nothing is uploaded
+until you ask. A refusal (HTTP 402) is reported as a quota refusal with the way
+out, not as "sync failed". Imported remote sessions land in the same store
+`/resume` reads, and are marked `imported` with estimated token counts — never
+passed off as measured here.
+
+## One memory, shared with AEGIS Desktop
+
+`~/.aegiscode/` is the data dir for **every** AEGIS host — this CLI, AEGIS
+Desktop and the MCP plugin built on the same account:
+
+| File | What it holds | Written by |
+|---|---|---|
+| `credentials.json` | the account key, mode 0600 | `aegiscode login`, `/key`, the desktop's Settings pane |
+| `sessions.json` | every conversation, one record per session | both hosts, live |
+| `history.jsonl` | this host's per-exchange ledger (feeds `/cost`) | the CLI |
+| `config.json` | preferences, permissions | the CLI |
+
+Sign in once and all three hosts are signed in: they resolve the key with the
+same precedence (`$AEGIS_API_KEY` → `credentials.json` → an older `config.json`),
+and when two hosts hold a key the **most recently saved one wins** — so rotating
+it from the terminal does not leave the app 401-ing on a stale string.
+
+Sessions are shared too, and not only through the cloud. `/resume` lists a
+thread typed in the desktop, and the desktop's session list shows a thread typed
+here — same file, no sync and no network. An upgrade adopts a desktop install's
+private `sessions.json` into the shared store once, so no existing conversation
+is lost. Records carry `origin`, and terminal sessions are **not** enrolled in
+the desktop's push queue (that would spend the account's synced-token quota as a
+side effect of typing in a shell); this host's own `/sync` covers them.
+
+There are currently **no** `unavailable` commands: every entry in the registry
+either runs or is a real handler that says honestly what it cannot do.
 
 ## The chatflow
 
@@ -181,9 +245,11 @@ What the loop does, in the order a turn happens:
   `/resume` the session list, `?` the shortcut grid, `ctrl+o` permissions, and a
   centred Yes/No dialog when a mutating tool needs approval. `Esc` closes an
   overlay, and clears the input line when nothing is open.
-- **Every turn is persisted** to `~/.aegiscode/history.jsonl`, with a transcript
-  checkpoint alongside it, so `/resume`, `/cost`, `/clear` and `/rewind` all have
-  something real to read. On exit the session prints how to come back to it.
+- **Every turn is persisted** to `~/.aegiscode/history.jsonl` and mirrored into
+  the shared `~/.aegiscode/sessions.json`, with a transcript checkpoint alongside
+  them, so `/resume`, `/cost`, `/clear` and `/rewind` all have something real to
+  read — and the desktop app sees the same conversations. On exit the session
+  prints how to come back to it.
 
 Anything that is not a real terminal — a pipe, `-p`, a CI run — stays a linear
 transcript written once to scrollback, so output remains pipeable and

package/bin/aegiscode.js

@@ -24,10 +24,16 @@ Usage:
   aegiscode -p "question"       same, explicit
   echo "q" | aegiscode -p -     read the prompt from stdin
 
+Account:
+  aegiscode login [<key>]       save your AEGIS API key (prompts, no echo, if omitted)
+  aegiscode logout              remove the saved key
+  aegiscode key status          show which key is in use and where it came from
+
 Options:
   -m, --model <id>        pin a model id (see /models; default: server choice)
       --base <url>        API base (default $AEGIS_API_BASE or aegiscloud.org)
-      --key <key>         API key for this run (prefer $AEGIS_API_KEY)
+      --key <key>         API key for THIS RUN only — it is not saved. Use
+                           "aegiscode login" to store one for good.
       --json              with -p: emit JSON instead of text
       --no-stream         buffer the answer instead of streaming it
       --max-tokens <n>    output ceiling hint
@@ -59,9 +65,22 @@ function parseArgs(argv) {
     prompt: null,
     help: false,
     version: false,
+    command: null,
+    commandArg: null,
   };
   const rest = [];
 
+  // An account subcommand is `argv[0]` and nothing else — position 0 only, so
+  // `aegiscode -p "key"` (a one-shot prompt whose text happens to be one of
+  // these words) is never hijacked into an account operation.
+  const head = argv[0];
+  if (head && !head.startsWith('-') && ACCOUNT_COMMANDS.has(head)) {
+    const arg = argv[1];
+    opts.command = head;
+    opts.commandArg = arg && !arg.startsWith('-') ? arg : null;
+    argv = argv.slice(opts.commandArg ? 2 : 1);
+  }
+
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     const next = () => {
@@ -127,6 +146,134 @@ function parseArgs(argv) {
   return opts;
 }
 
+/**
+ * Account subcommands: the in-band way to give this host a key.
+ *
+ * They exist because an `AEGIS_API_KEY` export was previously the *only* way
+ * in, and an export does not survive a new terminal. `--key` remains purely
+ * per-run (CI, a rotation test) so there is exactly one thing a user has to
+ * remember: `aegiscode login` saves it, `aegiscode logout` removes it.
+ */
+const ACCOUNT_COMMANDS = new Set(['login', 'logout', 'key']);
+
+/**
+ * Run `login` / `logout` / `key` and return a process exit code.
+ *
+ * Exit codes are meaningful because these are the commands a script calls:
+ * 0 = done, 1 = the server refused the credential, 2 = no credential and no
+ * way to ask for one (no TTY).
+ */
+async function runAccountCommand(command, arg, io = {}) {
+  const stdout = io.stdout || process.stdout;
+  const stderr = io.stderr || process.stderr;
+  const stdin = io.stdin || process.stdin;
+  const { credentials, readSecret, maskKey } = loadAccountDeps();
+
+  const where = () => credentials.credentialsPath();
+
+  if (command === 'logout' || (command === 'key' && ['clear', 'remove', 'rm'].includes(String(arg || '').toLowerCase()))) {
+    const res = credentials.clearApiKey();
+    stdout.write(
+      res.cleared
+        ? `aegiscode: key removed from ${res.path}\n`
+        : 'aegiscode: no saved key to remove\n'
+    );
+    if (credentials.legacyKeyOnDisk()) {
+      stdout.write(
+        'aegiscode: note — a plaintext copy is also in config.json, written by an older ' +
+          'AEGIS CLI; delete its "aegiscloud" block as well to finish removing it\n'
+      );
+    }
+    return 0;
+  }
+
+  if (command === 'key' && ['status', 'show', ''].includes(String(arg || '').toLowerCase())) {
+    const st = credentials.keyStatus();
+    if (io.json) {
+      stdout.write(
+        JSON.stringify(
+          {
+            configured: st.configured,
+            source: st.source,
+            source_label: credentials.sourceLabel(st.source),
+            path: st.path,
+            file_mode: st.fileMode,
+            masked: st.configured ? maskKey(st.key) : null,
+            memory_token: st.memoryToken,
+            verified_at: st.verifiedAt,
+            plaintext_copy_in_config: st.legacyPlaintext,
+          },
+          null,
+          2
+        ) + '\n'
+      );
+      return st.configured ? 0 : 1;
+    }
+    stdout.write(
+      [
+        `key:      ${st.configured ? maskKey(st.key) : 'not set'}`,
+        `source:   ${credentials.sourceLabel(st.source)}`,
+        `file:     ${st.path}${st.fileMode ? ` (${st.fileMode})` : ''}`,
+        `memory:   ${st.memoryToken ? 'token held (cloud sync ready)' : 'no token'}`,
+        st.verifiedAt ? `verified: ${st.verifiedAt}` : null,
+        st.legacyPlaintext
+          ? `note:     a plaintext copy also sits in config.json — re-save with \`aegiscode login\` to move it`
+          : null,
+      ]
+        .filter(Boolean)
+        .join('\n') + '\n'
+    );
+    return st.configured ? 0 : 1;
+  }
+
+  // `login [<key>]` and `key <api_key>`: take the key inline or ask for it.
+  let key = arg && arg !== 'status' ? String(arg).trim() : '';
+  if (!key) {
+    if (!stdin.isTTY) {
+      stderr.write(
+        'aegiscode: no terminal to prompt on — pass the key: `aegiscode login <api_key>`\n' +
+          '           (or set AEGIS_API_KEY for a single run)\n'
+      );
+      return 2;
+    }
+    key = await readSecret('AEGIS API key (kept off screen, Enter to cancel): ', { stdin, stdout });
+  }
+  if (!key) {
+    stderr.write('aegiscode: no key given — nothing saved\n');
+    return 2;
+  }
+
+  const { createApp } = require('../src/app.js');
+  const app = createApp({ interactive: false });
+  const res = await app.setApiKey(key);
+  if (!res.ok) {
+    stderr.write(`aegiscode: ${res.message || 'that key could not be saved'}\n`);
+    return 2;
+  }
+  const who = res.account && (res.account.email || res.account.plan);
+  stdout.write(`aegiscode: key saved to ${res.path}${who ? ` — ${who}` : ''}\n`);
+  if (res.error) {
+    const status = res.error.status;
+    stderr.write(`aegiscode: the account check failed: ${res.error.message}\n`);
+    if (status === 401 || status === 403) {
+      stderr.write('aegiscode: the key is stored but the server refused it — re-run with a fresh key\n');
+      return 1;
+    }
+    stderr.write('aegiscode: (stored anyway — the server could not be reached to confirm it)\n');
+    return 0;
+  }
+  stdout.write('aegiscode: verified — run `aegiscode` to start a session\n');
+  return 0;
+}
+
+/** Lazily required so `--version`/`--help` stay dependency-free and instant. */
+function loadAccountDeps() {
+  const credentials = require('../src/credentials.js');
+  const { readSecret } = require('../src/secret.js');
+  const { maskKey } = require('../src/format.js');
+  return { credentials, readSecret, maskKey };
+}
+
 function readStdin() {
   return new Promise((resolve) => {
     let buf = '';
@@ -163,6 +310,18 @@ async function main(argv = process.argv.slice(2)) {
   if (opts.base) process.env.AEGIS_API_BASE = opts.base;
   if (opts.key) process.env.AEGIS_API_KEY = opts.key;
 
+  // Account subcommands run before a session is built: they are one-shot,
+  // non-interactive, and must work in a script (`aegiscode login "$KEY"`) as
+  // well as at a prompt.
+  if (ACCOUNT_COMMANDS.has(opts.command)) {
+    return runAccountCommand(opts.command, opts.commandArg, {
+      json: opts.json,
+      stdin: process.stdin,
+      stdout: process.stdout,
+      stderr: process.stderr,
+    });
+  }
+
   const { createApp } = require('../src/app.js');
 
   let prompt = opts.prompt;
@@ -214,4 +373,4 @@ if (require.main === module) {
     });
 }
 
-module.exports = { main, parseArgs, HELP };
+module.exports = { main, parseArgs, HELP, ACCOUNT_COMMANDS, runAccountCommand };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "aegiscode",
   "productName": "AEGIS Code",
-  "version": "6.3.2",
-  "description": "aegiscode — 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.",
+  "version": "6.5.0",
+  "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",
     "email": "nborneklint@gmail.com"

package/scripts/predist.mjs

@@ -38,6 +38,11 @@ const VENDOR = path.join(CLI_DIR, 'vendor');
 const FILES = [
   'client/aegis.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
+  // list; `src/shared.js` resolves them from here in an installed package.
+  'client/credentials.js',
+  'client/session-store.js',
   'mcp/tools.js',
   'desktop/renderer/usage.js',
   // The agent-loop engine (persistent shell, editFile/grep/exec, Task

package/src/app.js

@@ -27,6 +27,9 @@ const { GLYPH, VERBS, themeOf, RESET, THEME_TABLE } = require('./theme.js');
 const { LiveRegion, termWidth, w } = require('./screen.js');
 const { parseLine, COMMANDS, visibleCommands } = require('./commands.js');
 const { updateConfig, loadPermissions, loadConfig, configExists } = require('./config.js');
+const credentials = require('./credentials.js');
+const cloudsync = require('./cloudsync.js');
+const { readSecret } = require('./secret.js');
 const { normalizeModelCatalog, pickerEntries, catalogIds } = require('./models.js');
 const { appendHistory, readSessionTranscript, readOwnSessions } = require('./history.js');
 const { snapshotCheckpoint } = require('./checkpoint.js');
@@ -50,7 +53,12 @@ function createApp(options = {}) {
   };
   const out = options.out || process.stdout;
   const err = options.err || process.stderr;
-  const client = options.client || createClient();
+  // The key comes from the credential store (env → credentials.json →
+  // config.json) rather than from the environment alone: an export does not
+  // survive a new shell, and until it is *stored* every one of those launches
+  // is "no key" with no in-band way to set one. An injected client keeps
+  // whatever key it was built with.
+  const client = options.client || createClient(credentials.clientOptions());
   const { TOOLS, toolList } = options.tools || createTools(client);
 
   // Tool-approval gate (exec/writeFile/editFile confirm before running).
@@ -151,6 +159,83 @@ function createApp(options = {}) {
     }
   }
 
+  // ── the AEGIS account key ─────────────────────────────────────────────────
+  //
+  // Set/forget at runtime, for `/key` and `aegiscode login`. Both paths are the
+  // same three steps — persist, apply to the live client, invalidate the model
+  // catalog — because a key that is stored but not applied leaves the current
+  // session failing, and one that is applied but not stored is gone next launch.
+
+  /**
+   * Persist an account key and start using it immediately.
+   *
+   * `verify` spends one `/api/verify-api-key` round trip to catch a bad key at
+   * the moment it is entered rather than at the first prompt, and is also how
+   * the memory token (cloud sync's credential) is obtained — so a successful
+   * login leaves both credentials in the store.
+   */
+  async function setApiKey(raw, { verify = true } = {}) {
+    const saved = credentials.saveApiKey(raw);
+    if (!saved.ok) return saved;
+    client.setApiKey(saved.key);
+    modelCache.models = [];
+    modelCache.at = 0;
+    let account = null;
+    let error = null;
+    if (verify) {
+      try {
+        const info = (await client.verifyApiKey()) || {};
+        account = info;
+        const patch = { verifiedAt: new Date().toISOString() };
+        if (info.memory_token) patch.memoryToken = info.memory_token;
+        if (info.plan) patch.plan = info.plan;
+        patch.account = { plan: info.plan || null, email: info.email || null, valid: info.valid !== false };
+        credentials.writeCredentials(patch);
+        if (info.plan) session.plan = info.plan;
+        if (info.email) session.account = { ...(session.account || {}), email: info.email };
+      } catch (e) {
+        error = e;
+      }
+    }
+    return { ...saved, account, error };
+  }
+
+  /** Drop the stored key and stop authenticating this session. */
+  function forgetApiKey() {
+    const res = credentials.clearApiKey();
+    client.setApiKey('');
+    modelCache.models = [];
+    modelCache.at = 0;
+    return res;
+  }
+
+  function cloudSyncEnabled() {
+    try {
+      return loadConfig().cloudSync === true;
+    } catch {
+      return false;
+    }
+  }
+
+  function setCloudSync(on) {
+    return updateConfig({ cloudSync: on === true });
+  }
+
+  /**
+   * Copy a key found in config.json into the 0600 store, once, so the next run
+   * reads the tight copy. Never deletes the original — that file belongs to
+   * another product and holds the user's key.
+   */
+  function adoptLegacyKeyOnce() {
+    try {
+      const resolved = credentials.resolveApiKey();
+      if (resolved.source !== 'config') return [];
+      return credentials.adoptLegacy().adopted;
+    } catch {
+      return [];
+    }
+  }
+
   // ── the AEGIS Cloud model catalog ──────────────────────────────────────────
   //
   // `/model` (and the alt+p chord that dispatches it) reads the pinnable ids
@@ -448,7 +533,7 @@ function createApp(options = {}) {
         render.renderNotice(
           ctx(),
           'error',
-          'no AEGIS_API_KEY set — export one (https://aegiscloud.org) or run /byok-set'
+          `no AEGIS account key — ${credentials.HOW_TO_SET} (or set $${credentials.KEY_ENV})`
         )
       );
       return;
@@ -506,7 +591,7 @@ function createApp(options = {}) {
     const tool = TOOLS[name];
     if (!tool) throw new Error(`unknown tool: ${name}`);
     if (!client.apiKey) {
-      throw new Error('no AEGIS_API_KEY set — export one (https://aegiscloud.org)');
+      throw new Error(`no AEGIS account key — ${credentials.HOW_TO_SET}`);
     }
     const text = await tool.run(args || {});
     emit(render.renderToolResult(ctx(), name, text, width()));
@@ -725,6 +810,17 @@ function createApp(options = {}) {
       TOOLS,
       saveConfig: (patch) => updateConfig(patch),
       showThemePicker: () => showThemePicker(),
+      // Credential + cloud-sync surface for the /key, /cloud and /sync commands.
+      // Defined here on the app's context so the chatflow's Object.assign-based
+      // context inherits them too — one definition, both hosts.
+      keyStatus: () => credentials.keyStatus(),
+      setApiKey: (raw, o) => setApiKey(raw, o),
+      forgetApiKey: () => forgetApiKey(),
+      readSecret: (text) => readSecret(text, { stdin: process.stdin, stdout: out }),
+      cloudsync,
+      cloudSyncEnabled: () => cloudSyncEnabled(),
+      setCloudSync: (on) => setCloudSync(on),
+      adoptLegacyKey: () => adoptLegacyKeyOnce(),
     };
     Object.defineProperty(c, 'sessionId', {
       enumerable: true,
@@ -813,7 +909,7 @@ function createApp(options = {}) {
     try {
       let args = cmd.build(arg);
       if (cmd.secret) {
-        const key = await readSecret(`provider key for ${args.provider}: `);
+        const key = await askSecret(`provider key for ${args.provider}: `);
         if (!key) {
           emit(render.renderNotice(ctx(), 'warn', 'empty key — nothing sent'));
           return true;
@@ -828,52 +924,26 @@ function createApp(options = {}) {
     return true;
   }
 
-  /** Read a secret without echoing it (raw mode; falls back to plain input). */
-  function readSecret(promptText) {
-    if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function') {
-      return Promise.resolve('');
-    }
-    return new Promise((resolve) => {
-      const t = themeOf(ctx());
-      out.write(t.gray + promptText + RESET);
-      const stdin = process.stdin;
-      let buf = '';
-      stdin.setRawMode(true);
-      stdin.resume();
-      const onData = (chunk) => {
-        for (const ch of chunk.toString('utf8')) {
-          if (ch === '\r' || ch === '\n') {
-            stdin.setRawMode(false);
-            stdin.removeListener('data', onData);
-            out.write('\n');
-            return resolve(buf);
-          }
-          if (ch === '\x03') {
-            // ctrl+c
-            stdin.setRawMode(false);
-            stdin.removeListener('data', onData);
-            out.write('\n');
-            return resolve('');
-          }
-          if (ch === '\u007f') {
-            buf = buf.slice(0, -1);
-            out.write('\b \b');
-            continue;
-          }
-          buf += ch;
-          out.write('•');
-        }
-      };
-      stdin.on('data', onData);
-    });
+  /**
+   * Ask for a secret on this session's streams.
+   *
+   * The prompt loop itself lives in secret.js, shared with `aegiscode login` in
+   * the bin — one implementation, so the terminal host and the non-interactive
+   * entry point cannot differ in whether a key is echoed or masked. Only the
+   * prompt's colouring is the session's business.
+   */
+  function askSecret(promptText) {
+    const t = themeOf(ctx());
+    return readSecret(t.gray + promptText + RESET, { stdin: process.stdin, stdout: out });
   }
 
   // --- entry points ---------------------------------------------------------
 
   /** Non-interactive: one prompt, plain output, exit code. */
   async function runOnce(prompt, { json = false } = {}) {
+    adoptLegacyKeyOnce();
     if (!client.apiKey) {
-      err.write('aegiscode: no AEGIS_API_KEY set. Export your key first (https://aegiscloud.org).\n');
+      err.write(`aegiscode: no AEGIS account key. ${credentials.HOW_TO_SET}, or set $${credentials.KEY_ENV}.\n`);
       return 2;
     }
     const res = await ask(prompt);
@@ -958,6 +1028,39 @@ function createApp(options = {}) {
     } catch {
       /* persistence is best-effort */
     }
+    // Auto-sync hook: one place, reached by both the linear REPL and the
+    // chatflow's session loop, and only when the user turned it on. Off by
+    // default because a push is billed against the plan's synced-token ceiling
+    // (aegis1 charges the *growth* of a session), so uploading is a choice.
+    if (cloudSyncEnabled()) autoSync();
+  }
+
+  /**
+   * Push after a turn, in the background.
+   *
+   * Deliberately not awaited and deliberately quiet on success: this runs after
+   * every turn, and a line per turn would be noise. Failures are reported once
+   * per session per session-cycle — a quota refusal that repeats forever is a
+   * wall of text, not information — and never thrown, because the user's turn
+   * already succeeded by the time this runs.
+   */
+  let autoSyncNotes = new Set();
+  function autoSync() {
+    if (!client.apiKey) return;
+    Promise.resolve()
+      .then(() => cloudsync.push(client))
+      .then((res) => {
+        if (res && res.failed && res.failed.length) {
+          const f = res.failed[0];
+          if (autoSyncNotes.has(f.kind)) return;
+          autoSyncNotes.add(f.kind);
+          const hint = f.hint ? ` — ${f.hint}` : '';
+          emit(render.renderNotice(ctx(), f.kind === 'quota' ? 'warn' : 'error', `cloud sync: ${f.message}${hint}`));
+        }
+      })
+      .catch(() => {
+        /* offline is not worth interrupting a session over */
+      });
   }
 
   /** One line of session accounting, for ctrl+t and the meta row. */  function tokenSummary() {
@@ -1115,6 +1218,7 @@ function createApp(options = {}) {
       process.stdout.isTTY;
     if (tty) {
       restorePrefs();
+      adoptLegacyKeyOnce();
       // Onboarding runs in the normal buffer, before the session takes the
       // alternate screen — the reference's order. A declined trust check must
       // abort: the reference returns without ever reaching `session(ctx)`.
@@ -1122,8 +1226,31 @@ function createApp(options = {}) {
         continue: !!options.continue,
         seen: options.seen || configExists,
         save: (patch) => updateConfig(patch),
+        // With no key the session can do nothing, so ask for it here where the
+        // user is already answering questions — verified on submit, and saved
+        // 0600 so the next launch (and every script) has it.
+        needsKey: () => !client.apiKey,
+        submitKey: (key) => setApiKey(key),
       });
       if (!onboard.ok) return 0;
+      if (onboard.key && onboard.key.set) {
+        emit(
+          render.renderNotice(
+            ctx(),
+            'info',
+            `key saved to ${credentials.credentialsPath()} — no export needed from now on`
+          )
+        );
+      }
+      if (onboard.key && onboard.key.skipped && !client.apiKey) {
+        emit(
+          render.renderNotice(
+            ctx(),
+            'warn',
+            `no key saved — /key <api_key> or \`aegiscode login\` whenever you are ready`
+          )
+        );
+      }
       // A stored pin the platform does not advertise routes elsewhere in
       // silence (see validatePinnedModel) — checked once, here, where the user
       // can act on it. Not on `-p`: a network round-trip ahead of the first
@@ -1143,6 +1270,7 @@ function createApp(options = {}) {
       return 0;
     }
     restorePrefs();
+    adoptLegacyKeyOnce();
     return runLinearRepl();
   }
 
@@ -1168,6 +1296,13 @@ function createApp(options = {}) {
     recordTurn,
     persistTurn,
     restorePrefs,
+    setApiKey,
+    forgetApiKey,
+    adoptLegacyKeyOnce,
+    cloudSyncEnabled,
+    setCloudSync,
+    cloudsync,
+    keyStatus: () => credentials.keyStatus(),
     sessionId: () => commandCtx.sessionId,
     tokenSummary,
     resumeSession,