aegis-desktop 0.8.1 → 0.8.3

package/README.md

@@ -1,5 +1,7 @@
 # AEGIS Desktop
 
+![AEGIS Desktop running: the three-class model picker, an agent turn, a gated tool-approval diff, and the unattended work queue](https://raw.githubusercontent.com/aegisinfo/aegiscode-plugin/main/desktop/docs/demo.gif)
+
 A standalone Electron chat app over the [AEGIS](https://aegiscloud.org) API,
 with an **agentic tool loop**: the model can read, write, and edit files,
 list directories, glob, grep, run shell commands in a persistent session, and
@@ -25,8 +27,10 @@ Either way, on first launch:
 3. Pick a model class from the picker at the bottom of the composer.
 
 The published package is [`aegis-desktop`](https://www.npmjs.com/package/aegis-desktop)
-on npm; this repo is its source. Both classes bill your AEGIS account — either
-the pooled margin, or the BYOK handling fee on top of your own provider key.
+on npm; this repo is its source. Two of the three classes bill your AEGIS
+account — either the pooled margin, or the BYOK handling fee on top of your own
+provider key; the free **Local** class runs on your own hardware and bills
+nobody.
 
 ## Using it
 
@@ -49,18 +53,25 @@ with **Settings → "Confirm before running tools"** — on by default.
 
 ## Model classes
 
-Pick either of two routes from the model-class picker, switchable
-mid-conversation with context intact:
+Pick from three routes on the model-class picker, switchable mid-conversation
+with context intact:
 
 | Class | Transport | Key held in | Billed? |
 |---|---|---|---|
 | **Aegis Cloud** | `aegiscloud.org` — one entry, **Nexus**; the pool auto-routes across whichever providers are live | main process | yes — pooled margin |
 | **Bring your own key** | your provider key, relayed by AEGIS — see below | main process | yes — flat AEGIS handling fee |
-
-Get a free AEGIS key at **https://aegiscloud.org**. The local-endpoint classes
-that used to live here — Ollama, and the OpenAI-/Anthropic-compatible direct
-lanes — have been removed; the hosted providers they could reach are on the
-**Bring your own key** class, which bills the handling fee.
+| **Local** | a model on your own machine or network — your Ollama daemon at `localhost:11434` by default | n/a — no key | no — free, no AEGIS account needed |
+
+Get a free AEGIS key at **https://aegiscloud.org** for the Cloud and BYOK
+classes. The generic OpenAI-/Anthropic-compatible direct-dial lanes that used
+to live here were removed for good — those providers are reachable only
+through **Bring your own key**, which bills the handling fee. **Local** is
+narrower: it points at a model on your own machine or your own network, and the
+endpoint check (`desktop/lib/local/local.js`) refuses anything public —
+fail-closed, run when the base URL is saved and again before a request is
+dialled. Your Ollama daemon at `localhost:11434` is the default, and any
+OpenAI-compatible server on that box — llama.cpp, LM Studio, vLLM — works by
+pointing the base URL at it. So there's no vendor to bill and no key to hold.
 
 ### Bring your own key (BYOK)
 
@@ -94,6 +105,26 @@ Note that a **BYOK turn is single-shot** — the relay takes no `tools` paramete
 so the agentic tool loop below is off for these models. Use the **Aegis Cloud**
 class when you want file and shell access.
 
+## Screenshots
+
+Captured from the real app, not mocked up: the stills come from
+`scripts/capture-marketing-shots.mjs` and the demo at the top of this page from
+`scripts/record-demo-gif.mjs`. Both drive the actual renderer against a local
+stub and refuse to publish an asset that fails their assertions.
+
+**The model-class picker** — all three routes, switchable mid-conversation:
+
+![The model-class picker listing Aegis Cloud, Bring your own key, and Local](https://raw.githubusercontent.com/aegisinfo/aegiscode-plugin/main/docs/marketing-assets/01-model-class-picker.png)
+
+**A completed answer** in the transcript:
+
+![A completed answer in the transcript](https://raw.githubusercontent.com/aegisinfo/aegiscode-plugin/main/docs/marketing-assets/02-answer-complete.png)
+
+**The tool-call approval card** with a proposed edit — what blocks `exec`,
+`writeFile` and `editFile` until you allow, allow for the session, or deny:
+
+![The tool-call approval card with a proposed edit](https://raw.githubusercontent.com/aegisinfo/aegiscode-plugin/main/docs/marketing-assets/03-tool-approval-diff.png)
+
 ## Tools available to the model
 
 | Tool | What it does |

package/main.js

@@ -480,6 +480,22 @@ async function importForeignMemory(aegis, dir, payload) {
   };
 }
 
+/** Where the packaged/dev build keeps its icon files. Packaged: shipped via
+ *  electron-builder.yml's `extraResources` into resourcesPath/icons/ (icons
+ *  live outside asar, since app.icns/.ico aren't otherwise reachable at
+ *  runtime). Dev: read straight from build/, the same source those resources
+ *  are copied from. Same split as ae-guix's lib/windows.js. */
+function resolveIconsDir(isPackaged, resourcesPath, dirname) {
+  return isPackaged ? path.join(resourcesPath, 'icons') : path.join(dirname, 'build');
+}
+
+/** icon.icns on mac, icon.ico on Windows, icon.png everywhere else (Linux). */
+function iconForPlatform(iconsDir, platform) {
+  if (platform === 'darwin') return path.join(iconsDir, 'icon.icns');
+  if (platform === 'win32') return path.join(iconsDir, 'icon.ico');
+  return path.join(iconsDir, 'icon.png');
+}
+
 /** Only http/https may be opened externally — file://, javascript:, etc.
  *  would hand the OS shell an arbitrary URI straight from model output. */
 function isSafeExternalUrl(url) {
@@ -492,6 +508,50 @@ function isSafeExternalUrl(url) {
   }
 }
 
+/**
+ * Whether this machine holds a provider route of the user's OWN — the "bring
+ * your own key" half of the welcome block's two pitches.
+ *
+ * The AEGIS Cloud key is `aegis.apiKey` and is reported separately as
+ * `keyConfigured`; a BYOK provider row never appears there (it is written by
+ * the Provider settings card through settings.set(provider, {baseURL, key})),
+ * so it needs its own reader. A row counts once it carries either a key (the
+ * pasted-provider case) or a baseURL (the point-it-at-a-local-model case) —
+ * both are the user having answered the question the block was asking.
+ *
+ * `settings.list()` goes through `get()`, which is the same reader the IPC
+ * bridge uses to answer the renderer — it never puts the plaintext key on a
+ * row (that would put it one `list()` call away from crossing IPC), only the
+ * `configured` boolean it already derived from the key. Reading `row.key`
+ * here was always reading a field `get()` doesn't emit, so a pasted-key-only
+ * provider row (no baseURL — the common case: OpenAI, Anthropic, DeepSeek)
+ * never counted and the block kept nagging a user who had already connected
+ * one. Verified live: `store.set('openai', { key })` then `list()` — the row
+ * carries `configured: true` and no `key` property at all.
+ *
+ * Reserved namespaces are excluded for the same reason createModelDispatch
+ * filters them: they are the store's own bookkeeping (the AEGIS key, the
+ * memory-persist preference), not a provider the user configured.
+ *
+ * Failure reads as "no", which keeps the block visible — the same
+ * fail-toward-showing-it bias the CLI's connectNeeded() documents. Showing a
+ * block the user has outgrown is a nag; hiding one a new install needed is a
+ * dead end, and only the latter loses the user.
+ */
+function providerRouteConfigured(engine) {
+  try {
+    const list = engine && engine.settings && engine.settings.list;
+    if (typeof list !== 'function') return false;
+    return (list.call(engine.settings) || []).some((row) => {
+      if (!row || !row.provider || isReservedNamespace(row.provider)) return false;
+      const baseURL = typeof row.baseURL === 'string' ? row.baseURL.trim() : '';
+      return Boolean(row.configured || baseURL);
+    });
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Pure mapping: IPC payload -> shared-client call. No Electron types here, so
  * tests can drive it with a stub client and a fake ipcMain. `openExternal` is
@@ -499,7 +559,17 @@ function isSafeExternalUrl(url) {
  * reject), injected by bootstrap() so this module still needs no `electron`
  * import to stay unit-testable.
  */
-function createIpcDispatch(aegis, dir, persistApiKey, openExternal) {
+function createIpcDispatch(aegis, dir, persistApiKey, openExternal, providerConfigured) {
+  // `providerConfigured` is an injected thunk (bootstrap() passes one that reads
+  // the settings store) so this module keeps its no-Electron, unit-testable
+  // shape; absent in tests and older call sites, where it reads as "no".
+  const hasOwnProviderKey = () => {
+    try {
+      return Boolean(typeof providerConfigured === 'function' && providerConfigured());
+    } catch {
+      return false;
+    }
+  };
   const openExternalFn = openExternal || (() => Promise.reject(new Error('no opener configured')));
   const dispatch = {
     status: () => ({
@@ -508,6 +578,12 @@ function createIpcDispatch(aegis, dir, persistApiKey, openExternal) {
       apiBase: aegis.apiBase,
       keyConfigured: Boolean(aegis.apiKey),
       keyMask: maskKey(aegis.apiKey),
+      // The welcome block pitches TWO routes (bring your own key, or AEGIS
+      // Cloud) and must retire once the user has taken either one. A BYOK
+      // provider key never touches aegis.apiKey, so without this the block
+      // kept re-pitching "bring your own key" at someone who just did — see
+      // applyWelcomeConnect() in renderer/app.js.
+      providerConfigured: hasOwnProviderKey(),
     }),
 
     // In-app API key entry (plan rebuild): replace the live client key and
@@ -612,8 +688,8 @@ function withReplyNotify(promise, event, onReplyFinished) {
  *  tests, where the safe no-op default in createIpcDispatch takes over.
  *  `onReplyFinished` is likewise bootstrap()-only: it fires the native
  *  "reply ready" notification when the window is unfocused/hidden. */
-function registerIpc(ipcMain, aegis, dir, persistApiKey, openExternal, onReplyFinished) {
-  const dispatch = createIpcDispatch(aegis, dir, persistApiKey, openExternal);
+function registerIpc(ipcMain, aegis, dir, persistApiKey, openExternal, onReplyFinished, providerConfigured) {
+  const dispatch = createIpcDispatch(aegis, dir, persistApiKey, openExternal, providerConfigured);
   for (const [name, handler] of Object.entries(dispatch)) {
     if (name === 'chatCompletion') {
       // Streaming render (D2.1): when the renderer asks for stream, SSE deltas
@@ -2362,7 +2438,8 @@ function bootstrap() {
     dataDir,
     persistApiKey,
     (url) => shell.openExternal(url),
-    notifyReplyIfUnfocused
+    notifyReplyIfUnfocused,
+    () => providerRouteConfigured(engine)
   );
   registerModelIpc(
     ipcMain,
@@ -2421,6 +2498,7 @@ function bootstrap() {
       minimizable: false,
       maximizable: false,
       backgroundColor: '#0d1117',
+      icon: iconForPlatform(resolveIconsDir(app.isPackaged, process.resourcesPath, __dirname), process.platform),
       webPreferences: {
         preload: path.join(__dirname, 'preload.js'),
         contextIsolation: true,
@@ -2595,6 +2673,7 @@ function bootstrap() {
     // connected display — that's a window that "opens" but nobody can see
     // or reach.
     const bounds = windowState.clampToDisplay(saved, screen.getAllDisplays(), defaultBounds);
+    const iconsDir = resolveIconsDir(app.isPackaged, process.resourcesPath, __dirname);
 
     const win = new BrowserWindow({
       ...bounds,
@@ -2602,6 +2681,7 @@ function bootstrap() {
       minHeight: 480,
       backgroundColor: '#0d1117',
       title: 'AEGIS Desktop',
+      icon: iconForPlatform(iconsDir, process.platform),
       webPreferences: {
         preload: path.join(__dirname, 'preload.js'),
         contextIsolation: true,
@@ -2736,6 +2816,7 @@ if (electron && electron.app) {
 module.exports = {
   createIpcDispatch,
   registerIpc,
+  providerRouteConfigured,
   IPC_PREFIX,
   MODEL_PREFIX,
   SYNC_PREFIX,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegis-desktop",
   "productName": "AEGIS Desktop",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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",
@@ -33,6 +33,7 @@
     "prepublishOnly": "npm run predist",
     "icon": "node scripts/generate-icon.mjs",
     "shots": "node scripts/capture-marketing-shots.mjs",
+    "demo": "node scripts/record-demo-gif.mjs",
     "dist": "npm run predist && electron-builder",
     "dist:dir": "npm run predist && electron-builder --dir",
     "check": "node --check main.js && node --check preload.js && node --check renderer/app.js && node --check renderer/quick.js && node --check renderer/budget.js && node --check renderer/usage.js && node --check renderer/stream-policy.js && node --check renderer/transcript-view.js && node --check renderer/diff.js && node --check renderer/diffview.js && node --check renderer/markdown.js && node --check renderer/vendor/aegis-highlight.js && node --check scripts/predist.mjs && node --check scripts/generate-icon.mjs && node --check lib/local/local.js && node --check lib/local/context.js && node --check lib/local/engine.js && node --check lib/local/session-rounds.js && node --check lib/local/tools.js && node --check lib/local/prompt.js && node --check lib/local/shell.js && node --check lib/local/agents.js && node --check lib/local/queue.js && node --check lib/local/autonomous.js && node --check lib/settings.js && node --check lib/sync/sessions.js && node --check lib/sync/memory-queue.js && node --check lib/window-state.js && node --check lib/deep-link.js && node --check lib/quick-launcher.js && node --check bin/aegis.js",
@@ -52,10 +53,13 @@
     "test:renderer-wiring": "node ../test/renderer-wiring.test.mjs"
   },
   "dependencies": {
-    "electron": "^33.0.0",
     "electron-updater": "^6.8.9"
   },
   "devDependencies": {
-    "electron-builder": "^25.1.8"
+    "electron-builder": "^25.1.8",
+    "electron": "^33.0.0"
+  },
+  "optionalDependencies": {
+    "electron": "^33.0.0"
   }
 }

package/renderer/app.js

@@ -160,6 +160,11 @@ const EFFORT_KEY = 'aegis.effort';
 const LEGACY_EFFORT_KEY = 'aegis.autonomousEffort';
 const AUTONOMOUS_WORKERS_KEY = 'aegis.autonomousWorkers';
 const EXPLORE_KEY = 'aegis.explore';
+// "Don't show this again" on the welcome panel's connect block. Stored here
+// rather than in the settings store because it is a per-machine UI preference,
+// not a credential, and the settings store is what the main process filters and
+// syncs.
+const WELCOME_DISMISS_KEY = 'aegis.welcomeConnectDismissed';
 // "Work autonomously" (pool_brain worker fan-out, aegis1 services/pool_brain.py)
 // is only billable/routable through the pooled AEGIS Cloud class.
 const AUTONOMOUS_CLASS = 'aegis';
@@ -595,6 +600,10 @@ function renderStatus(s) {
   els.base.textContent = s.apiBase || '–';
   els.key.textContent = s.keyConfigured ? s.keyMask : 'not set';
   setConn(s.keyConfigured, s.keyConfigured ? 'key configured' : 'no API key');
+  // A key that arrives while the welcome panel is on screen (pasted, or synced
+  // from the CLI) retires the connect block; with no key it stays. No-ops when
+  // the panel is not mounted.
+  applyWelcomeConnect();
 }
 
 // -------------------------------------------------------------- auto-update
@@ -1858,6 +1867,16 @@ function renderWelcome() {
   for (const btn of els.messages.querySelectorAll('.chat-quick-pill')) {
     btn.addEventListener('click', () => quickAction(btn.dataset.quick || ''));
   }
+  // The connect block's three controls. Bound here (not inline, not at boot)
+  // because they only exist in the cloned panel; CSP `script-src 'self'` would
+  // drop an inline handler anyway.
+  const byok = document.getElementById('welcome-byok');
+  if (byok) byok.addEventListener('click', welcomeByok);
+  const cloud = document.getElementById('welcome-cloud');
+  if (cloud) cloud.addEventListener('click', welcomeCloud);
+  const skip = document.getElementById('welcome-dismiss');
+  if (skip) skip.addEventListener('click', dismissWelcomeConnect);
+  applyWelcomeConnect();
 }
 
 /** Drop the welcome panel once real transcript content exists. */
@@ -1866,6 +1885,134 @@ function hideWelcome() {
   if (w) w.remove();
 }
 
+// --------------------------------------------- welcome: the connect block
+//
+// The welcome panel is the only surface a new install sees before it has a
+// key, and it is where the app has to say what it is and how it gets paid for.
+// The block is shown ONLY while nothing is connected (no AEGIS key) and the
+// user has not dismissed it: the panel is re-rendered on every New chat, so an
+// always-on version would be an advert in the composition window.
+//
+// Both routes are real paths into the existing UI, not links out:
+//
+//   byok  — switches the provider class and lands on Provider settings, which
+//           is where the per-provider key rows are built (loadSettings()).
+//           BYOK still needs an AEGIS key for the handling fee (the engine
+//           refuses a keyless BYOK send outright), so when there is none the
+//           same click also focuses the AEGIS key field and says so, rather
+//           than leaving the user at a row whose Save would fail.
+//   cloud — focuses the AEGIS key field in the Status card, where Save/Verify
+//           and the Upgrade/Top up buttons already live. Getting a key is the
+//           one step that happens off-machine, so the hint carries the link
+//           and openExternal is reached through the anchor, never a bare
+//           window.open (CSP `script-src 'self'` drops nothing here, but the
+//           main process is what validates the URL).
+
+/** Show the connect block only on an unconnected, un-dismissed install. */
+function applyWelcomeConnect() {
+  const box = document.getElementById('welcome-connect');
+  if (!box) return;
+  let dismissed = false;
+  try {
+    dismissed = localStorage.getItem(WELCOME_DISMISS_KEY) === 'on';
+  } catch {
+    /* storage disabled — treat as not dismissed */
+  }
+  // keyConfigured is null until status is read, so an unknown state keeps the
+  // block visible: on a cold boot the user has no key far more often than not,
+  // and renderStatus() calls this again the moment the truth arrives.
+  box.hidden = dismissed || keyConfigured === true;
+}
+
+/** Scroll a sidebar card into view and mark it, so a welcome click has a
+ *  visible landing spot. The sidebar is a plain scroll container, so this is
+ *  the whole of the "open settings" affordance. */
+function revealSidebarCard(node) {
+  if (!node) return;
+  const card = node.closest('section.card') || node;
+  try {
+    card.scrollIntoView({ block: 'center', behavior: 'smooth' });
+  } catch {
+    card.scrollIntoView();
+  }
+  card.classList.add('flash');
+  setTimeout(() => card.classList.remove('flash'), 1200);
+}
+
+/** "Bring your own key": land the user where a provider key can be typed. */
+async function welcomeByok() {
+  renderWelcomeHint('byok');
+  const hasByok = Array.from(els.classSelect.options).some((o) => o.value === 'byok');
+  if (hasByok && els.classSelect.value !== 'byok') {
+    els.classSelect.value = 'byok';
+    // The change listener persists the class and reloads the catalog, so the
+    // provider rows appear without duplicating any of that here.
+    els.classSelect.dispatchEvent(new Event('change'));
+  }
+  revealSidebarCard(els.settingsList);
+  // A BYOK turn is refused without an AEGIS key (the handling fee is billed
+  // there), so a keyless user is sent to the key field first — the provider row
+  // cannot succeed on its own.
+  if (keyConfigured === false && els.apiKeyHint) {
+    els.apiKeyHint.textContent =
+      'BYOK needs an AEGIS key too — the handling fee is billed to it. ' +
+      'Paste one above, then add your provider key below.';
+  }
+  if (keyConfigured === false && els.apiKeyInput) {
+    els.apiKeyInput.focus();
+    revealSidebarCard(els.apiKeyInput);
+    return;
+  }
+  const row = els.settingsList
+    ? els.settingsList.querySelector('.setting-row input[type="password"]')
+    : null;
+  if (row) row.focus();
+}
+
+/** "Connect AEGIS Cloud": land the user on the key field that unlocks it. */
+function welcomeCloud() {
+  renderWelcomeHint('cloud');
+  revealSidebarCard(els.apiKeyInput);
+  if (els.apiKeyInput) els.apiKeyInput.focus();
+}
+
+/** The hint under the key field, rewritten to match the route just clicked.
+ *  Uses child nodes rather than textContent so the aegiscloud.org link inside
+ *  it survives (same shape as the Model card's needsKey hint). */
+function renderWelcomeHint(kind) {
+  const el = els.apiKeyHint;
+  if (!el) return;
+  el.textContent = '';
+  if (kind === 'byok') {
+    el.appendChild(document.createTextNode(
+      'Bring your own key: paste your AEGIS key here (it bills the handling fee), ' +
+      'then add the provider key in Provider settings. No key yet? ',
+    ));
+  } else {
+    el.appendChild(document.createTextNode(
+      'Connect AEGIS Cloud: paste your AEGIS key, then Save. Free key at ',
+    ));
+  }
+  const a = document.createElement('a');
+  a.href = GET_AEGIS_KEY_URL;
+  a.target = '_blank';
+  a.rel = 'noreferrer noopener';
+  a.textContent = 'aegiscloud.org';
+  el.appendChild(a);
+  el.appendChild(document.createTextNode('.'));
+}
+
+/** Persist "don't show this again" and drop the block for this session. */
+function dismissWelcomeConnect() {
+  try {
+    localStorage.setItem(WELCOME_DISMISS_KEY, 'on');
+  } catch {
+    /* storage disabled — the block simply comes back next launch */
+  }
+  const box = document.getElementById('welcome-connect');
+  if (box) box.hidden = true;
+}
+
 // 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

package/renderer/index.html

@@ -315,6 +315,7 @@
             <div class="glyph">✦</div>
             <div class="title" id="chat-greeting">Hello</div>
           </div>
+          <div class="sub" id="welcome-tagline">Your intent, AI automated.</div>
           <div class="sub">
             Ask anything — or start with one of these.
           </div>
@@ -347,6 +348,79 @@
               <span class="qp-ic">⊞</span>Plan a project
             </button>
           </div>
+          <!-- Why AEGIS Desktop, and the two ways to power it.
+               The app itself is MIT and free; what pays for it is a connected
+               account — either an AEGIS Cloud key (pooled models, billed to
+               the balance in the Status card) or a provider key of your own
+               relayed under BYOK, whose handling fee is the other revenue
+               line. A new install therefore has to be told, in the app, both
+               why it should stay and how to connect; until this panel existed
+               the only route to either was a paragraph in the README.
+
+               Both buttons are real: #welcome-byok switches the provider
+               class to byok and drops the user on the Provider settings card,
+               #welcome-cloud focuses the AEGIS key field in the Status card.
+               The whole block is hidden once a key is configured or the user
+               dismisses it (applyWelcomeConnect() in app.js) — a welcome
+               panel that reappears on every New chat is an ad, not a welcome. -->
+          <div class="welcome-connect" id="welcome-connect" hidden>
+            <div class="wc-why">
+              <div class="wc-why-title">Why AEGIS Desktop</div>
+              <ul class="wc-why-list">
+                <li>
+                  <b>It runs on your machine.</b> Your repos, sessions and keys
+                  live on this disk — an agent turn only leaves it for the
+                  model call you configured, and nothing else is uploaded.
+                </li>
+                <li>
+                  <b>Your key, your bill.</b> Paste an OpenAI, Anthropic or
+                  DeepSeek key and pay your provider directly, point it at a
+                  local model server for free, or use AEGIS Cloud with no
+                  provider key at all.
+                </li>
+                <li>
+                  <b>It does the work, not just the talking.</b> Exec, write and
+                  edit run against your actual working tree — with the
+                  autonomous queue draining multi-step jobs while you are away.
+                </li>
+                <li>
+                  <b>Open client, paid service.</b> The desktop app is
+                  MIT-licensed and needs no account to run a local model; AEGIS
+                  Cloud is what funds it.
+                </li>
+              </ul>
+            </div>
+            <div class="wc-paths">
+              <button type="button" class="wc-path" id="welcome-byok">
+                <span class="wc-ic" aria-hidden="true">🔑</span>
+                <span class="wc-body">
+                  <span class="wc-name">Bring your own key</span>
+                  <span class="wc-desc">
+                    Keep the provider plan you already pay for. The key is
+                    stored on this machine and authenticates to the provider;
+                    the relay that carries your turn is what bills the AEGIS
+                    handling fee.
+                  </span>
+                </span>
+                <span class="wc-go">Set up →</span>
+              </button>
+              <button type="button" class="wc-path" id="welcome-cloud">
+                <span class="wc-ic" aria-hidden="true">✦</span>
+                <span class="wc-body">
+                  <span class="wc-name">Connect AEGIS Cloud</span>
+                  <span class="wc-desc">
+                    One key, no provider account needed. Pooled models, memory
+                    sync and the autonomous worker fan-out; free tier to start,
+                    then upgrade or top up from the Status card.
+                  </span>
+                </span>
+                <span class="wc-go">Connect →</span>
+              </button>
+              <button type="button" class="wc-skip" id="welcome-dismiss">
+                Don't show this again
+              </button>
+            </div>
+          </div>
           <div class="hints">
             Enter to send · Shift+Enter for a newline · the discovery lane adds
             two extra paths to every answer

package/renderer/style.css

@@ -1669,6 +1669,12 @@ label {
   flex-direction: column;
   align-items: center;
   justify-content: center;
+  /* The connect block made this panel tall enough to overflow a short window.
+     Without a scroll container the overflow is unreachable, and `center` alone
+     clips the *top* of an overflowing box, so the greeting disappears. `safe`
+     degrades to plain `center` (the previous behaviour) where unsupported. */
+  justify-content: safe center;
+  overflow-y: auto;
   flex: 1;
   gap: 18px;
   text-align: center;
@@ -1759,6 +1765,216 @@ label {
   line-height: 1.6;
 }
 
+/* ------------------------------------------- welcome: the connect block
+   The "why AEGIS Desktop / bring your own key / connect AEGIS Cloud" panel
+   cloned into #messages by renderWelcome(). It is the only surface a new
+   install sees before it has a key, so it carries the two revenue routes:
+   BYOK (provider key relayed, AEGIS handling fee billed) and AEGIS Cloud.
+
+   Deliberately wider and left-aligned against the centred greeting above it:
+   the greeting is a title, this is body copy plus two calls to action, and
+   centred paragraphs at this length are unreadable. */
+.welcome-connect {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  width: 100%;
+  max-width: 620px;
+  margin-top: 8px;
+  padding: 16px 18px;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: var(--surface);
+  text-align: left;
+  animation: wc-in 0.25s ease-out;
+}
+
+/* Required, not cosmetic: `display: flex` above outranks the UA sheet's
+   `[hidden] { display: none }`, so without this the `hidden` attribute the
+   dismiss button and applyWelcomeConnect() rely on would be a silent no-op
+   (same trap already documented for .update-banner and .autonomous-controls). */
+.welcome-connect[hidden] {
+  display: none;
+}
+
+@keyframes wc-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+
+.wc-why-title {
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--teal);
+  margin-bottom: 8px;
+  font-family: var(--font-display);
+}
+
+.wc-why-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 7px;
+}
+
+.wc-why-list li {
+  position: relative;
+  padding-left: 17px;
+  font-size: 12px;
+  line-height: 1.55;
+  color: var(--text2);
+}
+
+.wc-why-list li::before {
+  content: '✦';
+  position: absolute;
+  left: 0;
+  top: 1px;
+  font-size: 10px;
+  color: var(--text3);
+}
+
+.wc-why-list b {
+  color: var(--text);
+  font-weight: 600;
+}
+
+.wc-paths {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 10px;
+  align-items: stretch;
+}
+
+.wc-path {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  text-align: left;
+  padding: 13px 14px;
+  border: 1px solid var(--border2);
+  border-radius: 9px;
+  background: var(--surface2);
+  color: var(--text2);
+  font-family: var(--font-chat);
+  cursor: pointer;
+  transition: all 0.15s;
+}
+
+.wc-path:hover,
+.wc-path:focus-visible {
+  border-color: var(--teal);
+  background: rgba(0, 229, 192, 0.06);
+  outline: none;
+}
+
+.wc-ic {
+  font-size: 16px;
+  line-height: 1;
+}
+
+.wc-body {
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+  flex: 1;
+}
+
+.wc-name {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--text);
+}
+
+.wc-path:hover .wc-name,
+.wc-path:focus-visible .wc-name {
+  color: var(--teal);
+}
+
+.wc-desc {
+  font-size: 11px;
+  line-height: 1.5;
+  color: var(--text2);
+}
+
+.wc-go {
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  color: var(--teal);
+}
+
+.wc-skip {
+  grid-column: 1 / -1;
+  justify-self: center;
+  border: 0;
+  background: none;
+  padding: 2px 8px;
+  font-family: var(--font-chat);
+  font-size: 11px;
+  color: var(--text3);
+  cursor: pointer;
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  text-decoration-color: var(--border2);
+}
+
+.wc-skip:hover {
+  color: var(--text2);
+}
+
+/* Sidebar cards are ~280px, so side-by-side path cards stop being readable
+   long before the window is narrow. */
+@media (max-width: 720px) {
+  .wc-paths {
+    grid-template-columns: 1fr;
+  }
+}
+
+/* ------------------------------------------------ sidebar "landing" flash
+   revealSidebarCard() adds .flash for 1.2s after a welcome click scrolls a
+   settings card into view. The class was being added with no rule behind it,
+   so the click had no visible landing spot at all — this is that rule. Kept
+   element-agnostic: revealSidebarCard falls back to the node itself when it
+   is not inside a .card. */
+.flash {
+  animation: card-flash 1.2s ease-out;
+}
+
+@keyframes card-flash {
+  0% {
+    border-color: var(--teal);
+    box-shadow: 0 0 0 3px rgba(0, 229, 192, 0.18);
+  }
+  70% {
+    border-color: var(--teal);
+    box-shadow: 0 0 0 3px rgba(0, 229, 192, 0.1);
+  }
+  100% {
+    box-shadow: none;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .welcome-connect {
+    animation: none;
+  }
+  .flash {
+    animation: none;
+    border-color: var(--teal);
+  }
+}
+
 /* ------------------------------------------------- rendered markdown (D?)
    renderer/markdown.js parses assistant text with marked, sanitizes with
    DOMPurify, then hands the sanitized HTML to .body/.flow-body via

package/vendor/aegis.js

@@ -46,6 +46,25 @@ function envVar(name) {
   return v && !/^\$\{[A-Z_]+\}$/.test(v) ? v : '';
 }
 
+/**
+ * Read a positive millisecond count from the environment, or 0 for "unset".
+ *
+ * Used only for the two stream watchdogs below. Non-positive and unparseable
+ * values are IGNORED rather than honoured — deliberately not the rule the
+ * engine's host cooldown uses, where `AEGIS_HOST_COOLDOWN_MS=0` meaning "no
+ * cooldown" is a coherent thing to ask for. Here `0` would mean "the stream is
+ * dead before its first byte", which is a typo rather than a preference, and
+ * silently killing every turn is a far worse failure than ignoring a bad
+ * number. A test that genuinely wants a sub-second watchdog passes
+ * `idleTimeoutMs` per call (test/autonomous-mode.test.mjs does exactly that).
+ */
+function envIdleMs(name) {
+  const raw = envVar(name);
+  if (!raw) return 0;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
 /**
  * UUID v4 that works everywhere: Web Crypto first (browsers, Node ≥ 19),
  * then Node's CJS crypto module (Node < 19), then a Math.random fallback for
@@ -895,9 +914,27 @@ const BRAIN_IDLE_TIMEOUT_MS = 15 * 60_000;
  * that runs the fan-out, so a renamed brain id or a caller that forgot its
  * flag cannot desynchronise the two. A response with no header (an older
  * server, or a single-pass call) keeps the caller's budget or the 60s default.
+ *
+ * ── the two env knobs ───────────────────────────────────────────────────────
+ *
+ * `AEGIS_SSE_IDLE_TIMEOUT_MS` and `AEGIS_BRAIN_IDLE_TIMEOUT_MS` move those two
+ * *defaults* without a code edit: the CLI is a host, not a fork, so before this
+ * the only way to give a slow link more room — or to reproduce a stall against
+ * a fixed wedged server — was to patch the transport. Same escape hatch the
+ * engine gives its host cooldown (`AEGIS_HOST_COOLDOWN_MS`).
+ *
+ * Both are read at CALL time, not at module load, so a host that sets one after
+ * `require()` still gets it, and one that unsets it is back on the shipped
+ * default. A per-call `idleTimeoutMs` still outranks both: an explicit number
+ * from the caller is a decision about *this* request, while the env var is only
+ * a house default. See envIdleMs() for why a bad value is ignored rather than
+ * obeyed.
  */
 function idleBudgetFor(res, requestedMs) {
-  const base = Number(requestedMs) > 0 ? Number(requestedMs) : SSE_IDLE_TIMEOUT_MS;
+  // Caller override -> env knob -> shipped default.
+  const stated = Number(requestedMs);
+  const envDefault = envIdleMs('AEGIS_SSE_IDLE_TIMEOUT_MS');
+  const base = stated > 0 ? stated : envDefault > 0 ? envDefault : SSE_IDLE_TIMEOUT_MS;
   let header = '';
   try {
     const get = res && res.headers && typeof res.headers.get === 'function' ? res.headers.get.bind(res.headers) : null;
@@ -905,7 +942,13 @@ function idleBudgetFor(res, requestedMs) {
   } catch {
     header = ''; // an exotic fetch shim without headers: keep the caller's budget
   }
-  return header && String(header).trim() ? Math.max(base, BRAIN_IDLE_TIMEOUT_MS) : base;
+  // The fan-out floor is tunable for the same reason the base is — and it has
+  // to stay a FLOOR: a server that announced workers=3 is still working, so a
+  // smaller base must not cut it off. Raise both if the server's own
+  // NEXUS_BRAIN_WORKER_TIMEOUT moves (test/autonomous-mode.test.mjs pins the
+  // 600s relationship between them).
+  const brainFloor = envIdleMs('AEGIS_BRAIN_IDLE_TIMEOUT_MS') || BRAIN_IDLE_TIMEOUT_MS;
+  return header && String(header).trim() ? Math.max(base, brainFloor) : base;
 }
 
 const api = { createClient, envVar, randomUUID, DEFAULT_API_BASE, CLIENT_VERSION, idleBudgetFor, SSE_IDLE_TIMEOUT_MS, BRAIN_IDLE_TIMEOUT_MS };