aegis-desktop 1.0.12 → 1.0.13

package/vendor/aegis.js

@@ -466,6 +466,29 @@ const RATE_LIMIT_MAX_WAIT_MS = 30000;
 /** Base for the exponential fallback when the server sends no `Retry-After`. */
 const RATE_LIMIT_BASE_WAIT_MS = 1000;
 
+/**
+ * aegis1's chat-completions generator (`app.py` `nexus_chat_completions`'s
+ * `generate()`) wraps the whole upstream provider call in one `except
+ * Exception`, and on ANY failure forwards `str(e)` as a mid-stream SSE error
+ * frame: `{"error": {"message": str(e)[:200], "type": "server_error"}}`.
+ * Headers are already sent 200 OK by then, so there is no status code to
+ * tell a reset upstream socket apart from a real bug — both arrive as
+ * `postStream` throwing with `status: 200` and the CLI/desktop host showing
+ * `(backend error: [Errno 104] Connection reset by peer)` mid-turn.
+ *
+ * Narrowed to the Python exception messages a dropped TCP connection
+ * actually produces (ConnectionResetError/BrokenPipeError/ConnectionAbortedError
+ * and their usual Errno numbers), not every empty-turn error — a model that
+ * legitimately returned nothing must still fail on the first try, not retry
+ * forever. Only safe to retry when nothing streamed yet (`fullText` empty at
+ * the throw site below): no visible content can be duplicated by redoing the
+ * whole request from scratch.
+ */
+const TRANSIENT_STREAM_ERROR_PATTERN =
+  /connection reset by peer|broken pipe|connection aborted|errno 104|errno 32|errno 54|econnreset|epipe/i;
+const TRANSIENT_STREAM_RETRIES = 2;
+const TRANSIENT_STREAM_BASE_WAIT_MS = 500;
+
 /**
  * .mcp.json / Electron pass config as "${VAR}" template refs. When the var is
  * unset, hosts have been observed to leave the template literally unexpanded
@@ -505,6 +528,78 @@ function createClient(opts = {}) {
     return value.split(apiKey).join('[redacted]');
   }
 
+  /**
+   * Transport failure codes → what actually happened, in words that point at
+   * the culprit. Names, not errno numbers, because "ECONNRESET" tells a user
+   * nothing while "the connection was reset mid-request" tells them to retry.
+   */
+  const AEGIS_NETWORK_ERROR_HINTS = {
+    ECONNRESET: 'connection reset by the backend',
+    ECONNREFUSED: 'connection refused — is the backend running?',
+    EPIPE: 'connection closed while sending the request',
+    ETIMEDOUT: 'connection timed out',
+    ENOTFOUND: 'host not found — check the endpoint URL',
+    EAI_AGAIN: 'DNS lookup failed temporarily',
+    EHOSTUNREACH: 'host unreachable',
+    ENETUNREACH: 'network unreachable',
+    CERT_HAS_EXPIRED: 'TLS certificate has expired',
+    DEPTH_ZERO_SELF_SIGNED_CERT: 'TLS certificate is self-signed',
+    UND_ERR_SOCKET: 'the socket closed before the response finished',
+    UND_ERR_CLOSED: 'the connection was closed',
+    UND_ERR_CONNECT_TIMEOUT: 'timed out connecting to the backend',
+    UND_ERR_HEADERS_TIMEOUT: 'the backend accepted the connection but never sent a response',
+    UND_ERR_BODY_TIMEOUT: 'the backend stalled mid-response',
+    UND_ERR_ABORTED: 'the request was aborted',
+  };
+
+  /**
+   * Turn a raw transport failure into something a person can act on.
+   *
+   * Node's undici raises `TypeError: fetch failed` for every socket-level
+   * fault and puts the real reason on `err.cause` (`ECONNRESET`,
+   * `UND_ERR_SOCKET`, `HeadersTimeoutError`, `ENOTFOUND`, …). Rethrown
+   * untouched, the user sees the literal string `fetch failed`, which names
+   * no component, no cause and no next step — and, worse, hides the fact that
+   * the backend is the thing that dropped us rather than a bad request.
+   *
+   * The cause code, when there is one, is the single most useful fact here,
+   * so it is promoted into `message` and kept on `cause`/`networkCode` for
+   * callers that want to branch on it. Everything else about the error is
+   * left alone.
+   */
+  function networkFailureError(err, base) {
+    const reraised = err instanceof Error ? err : new Error(String(err));
+    // The caller's own cancellation is not a failure and must stay untouched.
+    const name = reraised && reraised.name;
+    if (name === 'AbortError' || name === 'TimeoutError') return err;
+    const detail = describeNetworkCause(reraised);
+    const target = base || 'the backend';
+    const e = new Error(
+      detail
+        ? `Could not reach ${target} (${detail}).`
+        : `Could not reach ${target}: ${reraised.message || 'network failure'}.`
+    );
+    e.status = 0;
+    e.code = 'network';
+    e.networkCode = detail || null;
+    e.data = null;
+    e.cause = reraised;
+    return e;
+  }
+
+  /** The innermost human-meaningful reason from an undici error chain. */
+  function describeNetworkCause(err, depth = 0) {
+    if (!err || depth > 4) return null;
+    const code = err.code || (err.cause && err.cause.code);
+    const inner = err.cause;
+    const innerDetail = inner ? describeNetworkCause(inner, depth + 1) : null;
+    if (AEGIS_NETWORK_ERROR_HINTS[code]) return AEGIS_NETWORK_ERROR_HINTS[code];
+    if (innerDetail) return innerDetail;
+    // An undici cause often carries only a message ("other side closed").
+    if (inner && inner.message && inner.message !== err.message) return inner.message;
+    return code || null;
+  }
+
   /**
    * A bounded `fetch`: caller signal where there is one, an aborting timeout
    * where there is not. Returns the caller's abort untouched (so a host that
@@ -549,7 +644,7 @@ function createClient(opts = {}) {
         e.data = null;
         throw e;
       }
-      throw err;
+      throw networkFailureError(err, apiBase);
     } finally {
       // The timeout is time-to-*headers* only, so it is cleared the moment the
       // response resolves: a long generation must never be cut off by it.
@@ -652,6 +747,30 @@ function createClient(opts = {}) {
       await sleep(wait, init && init.signal);
       res = await boundedFetch(url, init);
     }
+    // The NON-streaming twin of postStream's mid-stream transient retry below:
+    // aegis1's chat-completions route drains the same generate() generator
+    // itself when the caller sent `stream: false`, and on the SAME exception
+    // (a reset socket to the provider) returns it as a plain 503 —
+    // `{"error":{"message":"[Errno 104] Connection reset by peer","type":
+    // "server_error"}}` — not a 200 SSE frame, because no response has been
+    // sent yet on this branch. Peeked via a clone so a non-matching body (a
+    // real 503 — insufficient balance, "not configured" — is untouched for
+    // `parseResponse` to read and surface normally, unretried.
+    for (
+      let attempt = 0;
+      res && res.status >= 500 && res.status < 600 && attempt < TRANSIENT_STREAM_RETRIES;
+      attempt++
+    ) {
+      let text = '';
+      try {
+        text = await readCappedText(res.clone());
+      } catch {
+        break; // body already disturbed or unclonable — surface res as-is
+      }
+      if (!TRANSIENT_STREAM_ERROR_PATTERN.test(text)) break;
+      await sleep(TRANSIENT_STREAM_BASE_WAIT_MS * Math.pow(2, attempt), init && init.signal);
+      res = await boundedFetch(url, init);
+    }
     return res;
   }
 
@@ -1066,7 +1185,14 @@ function createClient(opts = {}) {
     else if (mode) body.mode = mode;
     const headers = authHeaders(agentKey ? { 'X-AEGIS-Agent-Key': agentKey } : undefined);
     if (!stream || typeof onStream !== 'function') {
-      return decodeDsmlInResult(await apiPost('/api/v1/chat/completions', { ...body, stream: false }, headers));
+      // `signal` must be forwarded here. It was not, and the consequence was
+      // silent: a caller that aborted a non-streaming turn saw the abort
+      // ignored, the request ran on to its timeout, and the eventual error was
+      // a timeout the user never asked for. postStream's own fallback at the
+      // bottom of this function always forwarded it — only this branch did not.
+      return decodeDsmlInResult(
+        await apiPost('/api/v1/chat/completions', { ...body, stream: false }, headers, { signal })
+      );
     }
     // An OpenAI-compatible SSE response carries no `usage` unless the caller
     // asks for it (`stream_options.include_usage`). Without this the streamed
@@ -1237,7 +1363,10 @@ function createClient(opts = {}) {
    * This keeps streaming purely additive for hosts that opt in.
    */
   async function postStream(path, body, headers, onStream, signal, streamOpts) {
-    const { onReasoning, idleTimeoutMs, retryWithoutStreamOptions } = streamOpts || {};
+    const {
+      onReasoning, idleTimeoutMs, retryWithoutStreamOptions,
+      _transientStreamAttempt: transientStreamAttempt = 0,
+    } = streamOpts || {};
     const request = (payload) =>
       // `boundedFetch` here bounds time-to-*headers* only: fetch resolves when
       // the status line lands, and the timer is cleared in its `finally`, so a
@@ -1545,6 +1674,16 @@ function createClient(opts = {}) {
     }
 
     if (!fullText && sseError) {
+      if (
+        transientStreamAttempt < TRANSIENT_STREAM_RETRIES
+        && TRANSIENT_STREAM_ERROR_PATTERN.test(sseError)
+      ) {
+        await sleep(TRANSIENT_STREAM_BASE_WAIT_MS * Math.pow(2, transientStreamAttempt), signal);
+        return postStream(path, body, headers, onStream, signal, {
+          ...streamOpts,
+          _transientStreamAttempt: transientStreamAttempt + 1,
+        });
+      }
       const err = new Error(sseError);
       err.status = res.status;
       throw err;
@@ -1763,6 +1902,32 @@ function createClient(opts = {}) {
     });
   }
 
+  /**
+   * aegis1's stored Google Drive connection for this account (`GET
+   * /api/drive/token` — app.py's `get_drive_token`), authenticated with the
+   * ordinary API key (the same header `authHeaders()` already sends, which
+   * that route accepts alongside its session-cookie path). Resolves
+   * `{connected, access_token, email}` — `connected: false` with no error
+   * when this account has never run the browser's `/connect/drive` consent
+   * screen (the route's 404: a real account, just nothing saved yet), since
+   * "not yet connected" is the expected answer on every account until it
+   * does. A 401 is a DIFFERENT fact — this key is not valid at all — so it is
+   * left to throw rather than folded into the same "not connected" reading,
+   * which would hide a real credential problem behind the normal first-run
+   * state. The access token is refreshed server-side from the stored refresh
+   * token on every call, so a caller never has to reason about expiry.
+   */
+  async function driveToken() {
+    try {
+      return await apiGet('/api/drive/token');
+    } catch (e) {
+      if (e && e.status === 404) {
+        return { connected: false, access_token: null, email: null };
+      }
+      throw e;
+    }
+  }
+
   return {
     apiBase,
     get apiKey() {
@@ -1798,6 +1963,7 @@ function createClient(opts = {}) {
     conversationSyncPush,
     conversationSyncPull,
     importConversation,
+    driveToken,
     randomUUID,
   };
 }

package/vendor/drive-connect.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
+// AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
+// Conveying a modified copy, or running one as a network service, owes the
+// corresponding source under this licence (§5/§13) — see LICENSING.md.
+'use strict';
+
+/**
+ * drive-connect.js — the desktop half of aegis1's Google Drive OAuth.
+ *
+ * aegis1 already runs the full web side of this: `/connect/drive` sends the
+ * browser through Google's consent screen with the `drive.file` scope, saves
+ * the resulting tokens on whichever account that Google identity resolves
+ * to, and lands on a static "connected" page. `/api/drive/token` then hands
+ * back a fresh (server-refreshed) access token for that account, authenticated
+ * with the ordinary AEGIS API key — see `client/aegis.js`'s `driveToken()`.
+ *
+ * Unlike `/auth/google` (see `client/google-signin.js`), `/connect/drive` has
+ * no desktop round-trip: it never redirects back to a local callback, so
+ * there is nothing here to listen for. This module does the other honest
+ * thing instead — open the browser to it, and POLL the status endpoint
+ * (this machine's own API key) until the account shows connected, or give up
+ * after a timeout. The caller provides the actual browser-opening (Electron's
+ * `shell.openExternal`); this module is Electron-free so it can be driven by
+ * a test with a stub `aegis` client and no network.
+ *
+ * ONE PRECONDITION THIS MODULE DOES NOT ENFORCE, BECAUSE IT CANNOT:
+ * `/connect/drive` resolves the account by Google identity (google_id, then
+ * email), not by whatever account this machine's API key already belongs to.
+ * So polling only ever reports connected when THIS machine is already signed
+ * in with that same Google identity — otherwise the browser attaches the
+ * Drive tokens to a different account than the one being polled, and the
+ * poll simply times out. `desktop/lib/google-connect.js` is what sequences
+ * "sign in with Google first" ahead of this.
+ */
+
+/** `${apiBase}/connect/drive` — the one URL this flow opens. */
+function driveConnectUrl(apiBase) {
+  return `${String(apiBase || '').replace(/\/+$/, '')}/connect/drive`;
+}
+
+/**
+ * One status check: is a Drive token on file for this account?
+ *
+ * @param {{driveToken: () => Promise<{connected:boolean, email?:string}>}} aegis
+ */
+async function driveStatus(aegis) {
+  const data = await aegis.driveToken();
+  return {
+    connected: Boolean(data && data.connected),
+    email: (data && data.email) || null,
+  };
+}
+
+/**
+ * Poll `driveStatus` until it reports connected, or time out.
+ *
+ * The browser round-trip has no signal of its own to wait on (unlike
+ * `startGoogleSignIn`'s local callback server), so this is the only way the
+ * caller learns the user actually finished the consent screen — or gave up
+ * on it, which is why this is bounded rather than polled forever.
+ *
+ * @param {object} aegis a client exposing `driveToken()`
+ * @param {{timeoutMs?:number, pollMs?:number, signal?:AbortSignal}} [opts]
+ */
+async function waitForDriveConnected(aegis, opts = {}) {
+  const timeoutMs = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : 3 * 60 * 1000;
+  const pollMs = Number(opts.pollMs) > 0 ? Number(opts.pollMs) : 2000;
+  const signal = opts.signal || null;
+  const deadline = Date.now() + timeoutMs;
+
+  for (;;) {
+    const status = await driveStatus(aegis);
+    if (status.connected) return status;
+    if (signal && signal.aborted) {
+      const e = new Error('cancelled');
+      e.name = 'AbortError';
+      throw e;
+    }
+    if (Date.now() >= deadline) {
+      throw new Error(`timed out after ${Math.round(timeoutMs / 1000)}s waiting for Google Drive to connect`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+}
+
+module.exports = { driveConnectUrl, driveStatus, waitForDriveConnected };

package/vendor/drive-upload.js

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 Niklas Borneklint — AEGIS Code (aegiscode) / Aegiscloud.
+// AEGIS Code (aegiscode) — source: https://github.com/aegisinfo/aegiscode-plugin
+// Conveying a modified copy, or running one as a network service, owes the
+// corresponding source under this licence (§5/§13) — see LICENSING.md.
+'use strict';
+
+/**
+ * drive-upload.js — a Drive v3 REST client, scoped to exactly one job:
+ * keep a single memory-backup file, in a single app folder, up to date.
+ *
+ * This talks to Google's API directly with the access token
+ * `client/drive-connect.js` obtains (via `/api/drive/token`) — it never goes
+ * through aegis1, and aegis1 never sees the memory content this uploads.
+ *
+ * Scoped to `drive.file` (the scope `/connect/drive` requests): that grant
+ * only ever sees files this app itself creates, which is why every write
+ * here goes through `findOrCreateFolder`/`findFileInFolder` rather than
+ * assuming some well-known id — there is no well-known id this scope could
+ * resolve, and a file this app did not create is invisible to it even by
+ * name. One stable file is overwritten in place on every sync rather than
+ * creating a new one each time, so a daily backup habit does not pile up a
+ * thousand same-named files with no way to tell them apart.
+ */
+
+const DRIVE_FILES_URL = 'https://www.googleapis.com/drive/v3/files';
+const DRIVE_UPLOAD_URL = 'https://www.googleapis.com/upload/drive/v3/files';
+const FOLDER_MIME = 'application/vnd.google-apps.folder';
+const BOUNDARY = 'aegiscode-drive-upload-boundary';
+
+const DEFAULT_FOLDER = 'AEGIS Memory';
+const DEFAULT_FILE = 'aegis-memory-backup.json';
+
+function resolveFetch(fetchImpl) {
+  const f = fetchImpl || (typeof fetch === 'function' ? fetch : null);
+  if (!f) throw new Error('drive: this Node has no global fetch — upgrade to Node 22+');
+  return f;
+}
+
+/** Escape a value for Drive's `q=` string-literal quoting rules. */
+function escapeQ(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+async function driveRequest(fetchImpl, url, { method = 'GET', accessToken, body, headers } = {}) {
+  const f = resolveFetch(fetchImpl);
+  const res = await f(url, {
+    method,
+    headers: { Authorization: `Bearer ${accessToken}`, ...(headers || {}) },
+    body,
+  });
+  const text = await res.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = null;
+  }
+  if (!res.ok) {
+    const rawMsg = (data && data.error && (data.error.message || data.error)) || text.slice(0, 200) || `HTTP ${res.status}`;
+    const err = new Error(`drive: ${method} ${url.split('?')[0]} failed — ${typeof rawMsg === 'string' ? rawMsg : JSON.stringify(rawMsg)}`);
+    err.status = res.status;
+    err.data = data;
+    throw err;
+  }
+  return data || {};
+}
+
+/** The first file matching an exact query, or null. */
+async function findOne(fetchImpl, accessToken, query) {
+  const url = `${DRIVE_FILES_URL}?q=${encodeURIComponent(query)}&fields=${encodeURIComponent('files(id,name)')}&pageSize=1`;
+  const data = await driveRequest(fetchImpl, url, { accessToken });
+  const files = Array.isArray(data.files) ? data.files : [];
+  return files[0] || null;
+}
+
+/** This app's folder by name, creating it the first time. Returns its id. */
+async function findOrCreateFolder(accessToken, name, { fetchImpl } = {}) {
+  const query = `mimeType='${FOLDER_MIME}' and name='${escapeQ(name)}' and trashed=false`;
+  const existing = await findOne(fetchImpl, accessToken, query);
+  if (existing) return existing.id;
+  const created = await driveRequest(fetchImpl, DRIVE_FILES_URL, {
+    method: 'POST',
+    accessToken,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name, mimeType: FOLDER_MIME }),
+  });
+  return created.id;
+}
+
+/** One file by name inside a given folder, or null. */
+async function findFileInFolder(accessToken, name, folderId, { fetchImpl } = {}) {
+  const query = `'${escapeQ(folderId)}' in parents and name='${escapeQ(name)}' and trashed=false`;
+  return findOne(fetchImpl, accessToken, query);
+}
+
+/**
+ * Create a new file: a multipart/related body (metadata part naming the
+ * parent folder, content part carrying the bytes) — the shape Drive's
+ * `uploadType=multipart` requires for a create, since a plain media upload
+ * has nowhere to say which folder the file belongs in.
+ */
+async function createFile(accessToken, { name, folderId, content, mimeType }, { fetchImpl } = {}) {
+  const metadata = JSON.stringify({ name, parents: [folderId] });
+  const body =
+    `--${BOUNDARY}\r\n` +
+    `Content-Type: application/json; charset=UTF-8\r\n\r\n${metadata}\r\n` +
+    `--${BOUNDARY}\r\n` +
+    `Content-Type: ${mimeType}\r\n\r\n${content}\r\n` +
+    `--${BOUNDARY}--`;
+  return driveRequest(
+    fetchImpl,
+    `${DRIVE_UPLOAD_URL}?uploadType=multipart&fields=${encodeURIComponent('id,webViewLink')}`,
+    {
+      method: 'POST',
+      accessToken,
+      headers: { 'Content-Type': `multipart/related; boundary=${BOUNDARY}` },
+      body,
+    }
+  );
+}
+
+/**
+ * Overwrite an existing file's content in place. A plain media upload is
+ * enough here — the name and parent folder never change on a resync, so
+ * there is nothing a metadata part would need to say.
+ */
+async function updateFileContent(accessToken, fileId, content, mimeType, { fetchImpl } = {}) {
+  return driveRequest(
+    fetchImpl,
+    `${DRIVE_UPLOAD_URL}/${encodeURIComponent(fileId)}?uploadType=media&fields=${encodeURIComponent('id,webViewLink')}`,
+    {
+      method: 'PATCH',
+      accessToken,
+      headers: { 'Content-Type': mimeType },
+      body: content,
+    }
+  );
+}
+
+/**
+ * Upload (create or overwrite) one memory backup file in the user's Drive.
+ *
+ * @param {string} accessToken a live Drive access token (client/drive-connect.js / aegis.driveToken())
+ * @param {string} content the file's bytes — the caller serialises; this module never shapes the memory export itself
+ * @param {{folderName?:string, fileName?:string, mimeType?:string, fetchImpl?:Function}} [opts]
+ * @returns {Promise<{fileId:string, webViewLink:string|null, updated:boolean}>}
+ */
+async function uploadMemoryBackup(accessToken, content, opts = {}) {
+  const folderName = opts.folderName || DEFAULT_FOLDER;
+  const fileName = opts.fileName || DEFAULT_FILE;
+  const mimeType = opts.mimeType || 'application/json';
+  const fetchImpl = opts.fetchImpl;
+
+  const folderId = await findOrCreateFolder(accessToken, folderName, { fetchImpl });
+  const existing = await findFileInFolder(accessToken, fileName, folderId, { fetchImpl });
+  const result = existing
+    ? await updateFileContent(accessToken, existing.id, content, mimeType, { fetchImpl })
+    : await createFile(accessToken, { name: fileName, folderId, content, mimeType }, { fetchImpl });
+
+  return {
+    fileId: result.id || (existing && existing.id) || null,
+    webViewLink: result.webViewLink || null,
+    updated: Boolean(existing),
+  };
+}
+
+module.exports = {
+  DEFAULT_FOLDER,
+  DEFAULT_FILE,
+  findOrCreateFolder,
+  findFileInFolder,
+  createFile,
+  updateFileContent,
+  uploadMemoryBackup,
+};

package/vendor/update.js

@@ -399,19 +399,21 @@ function updateNotice({
  *
  * @param {{current: string, latest: ?string, behind: boolean, channel?: 'npm'|'desktop', pkg?: string}} input
  */
-function updatePlan({ current, latest, behind, channel = 'npm', pkg = PKG } = {}) {
+function updatePlan({ current, latest, behind, channel = 'npm', pkg = PKG, method = 'npm' } = {}) {
   const currentText = String(current == null ? '' : current);
   const latestText = latest ? String(latest) : null;
   const pending = Boolean(behind) && Boolean(latestText);
   if (!pending) {
     return {
       channel,
+      method,
       current: currentText,
       latest: latestText,
       behind: false,
       action: 'none',
       applier: 'none',
       instruction: null,
+      apply: null,
     };
   }
   if (channel === 'desktop') {
@@ -420,25 +422,101 @@ function updatePlan({ current, latest, behind, channel = 'npm', pkg = PKG } = {}
     // beside the running app. The applier is the app's own updater.
     return {
       channel,
+      method,
       current: currentText,
       latest: latestText,
       behind: true,
       action: 'desktop-update',
       applier: 'electron-updater',
       instruction: 'Aegis Desktop → Check for Updates…',
+      apply: null,
     };
   }
+
+  // Which installer owns this copy. The command is not cosmetic: `npm i -g`
+  // against a pip-installed `aegiscode` writes a second copy beside the one the
+  // user actually runs, and the "upgrade" appears to do nothing. Same for an
+  // `npx` run, which has nothing installed to upgrade at all.
+  const applier = APPLIERS[method] || APPLIERS.npm;
   return {
     channel,
+    method,
     current: currentText,
     latest: latestText,
     behind: true,
-    action: 'npm-update',
-    applier: 'npm',
-    instruction: `npm i -g ${pkg}@latest`,
+    action: applier.action,
+    applier: applier.name,
+    instruction: applier.instruction(pkg),
+    apply: applier.apply ? applier.apply(pkg) : null,
   };
 }
 
+/**
+ * The ways this product reaches a machine, and what "update it" means for each.
+ *
+ * `apply` names argv to run — it is what the window's Update button and the
+ * CLI's `/upgrade apply` execute. `null` means there is nothing to install:
+ * `npx` fetches `latest` on every launch by definition, and a source checkout
+ * belongs to its owner's git remote.
+ */
+const APPLIERS = Object.freeze({
+  npm: Object.freeze({
+    name: 'npm',
+    action: 'npm-update',
+    instruction: (pkg) => `npm i -g ${pkg}@latest`,
+    apply: (pkg) => ({ command: 'npm', args: ['i', '-g', `${pkg}@latest`] }),
+  }),
+  pip: Object.freeze({
+    name: 'pip',
+    action: 'pip-update',
+    // The published pip package is a launcher for the npm one, so this is
+    // genuinely a different command — not an npm call with a different word.
+    instruction: (pkg) => `pip install -U ${pkg}`,
+    apply: (pkg) => ({ command: process.platform === 'win32' ? 'python' : 'python3',
+      args: ['-m', 'pip', 'install', '-U', pkg] }),
+  }),
+  npx: Object.freeze({
+    name: 'none',
+    action: 'npx-update',
+    instruction: () => 'already fetched fresh on every run — restart to pick up the new version',
+    apply: null,
+  }),
+  source: Object.freeze({
+    name: 'git',
+    action: 'source-update',
+    instruction: () => 'git pull && npm ci   (this copy is a source checkout)',
+    apply: null,
+  }),
+});
+
+/**
+ * Which installer owns the copy that is running — so the sentence names a
+ * command that actually changes THIS binary.
+ *
+ * Order matters. An explicit declaration wins (the pip launcher sets
+ * `AEGIS_INSTALL_METHOD=pip` before exec'ing the real CLI, which is the only
+ * way the npm package can know a Python install is driving it). Then npx, which
+ * is detectable from the argv it builds. Then a source checkout, then npm.
+ *
+ * Pure and injectable: `env`, `argv` and a file probe, no `process` reads, so a
+ * test can assert every branch without npm or pip being installed.
+ */
+function detectInstallMethod({
+  env = {}, argv = [], pkg = PKG, fileExists = () => false, entry = '',
+} = {}) {
+  const declared = String((env && env.AEGIS_INSTALL_METHOD) || '').trim().toLowerCase();
+  if (declared && Object.prototype.hasOwnProperty.call(APPLIERS, declared)) return declared;
+
+  const joined = argv.map((a) => String(a)).join(' ');
+  if (/\bnpx\b/.test(joined) || /_npx[\\/]/.test(joined) || /_npx[\\/]/.test(entry)) return 'npx';
+  if (/[\\/]pipx[\\/]venvs[\\/]/.test(entry) || /[\\/]site-packages[\\/]/.test(entry)) return 'pip';
+  if (/[\\/]node_modules[\\/]/.test(entry)) return 'npm';
+  // A git checkout has the repo's own marker files; a global npm install does
+  // not (they are not in the package's `files` list).
+  if (fileExists('.git') && fileExists('client/update.js')) return 'source';
+  return 'npm';
+}
+
 /**
  * The same once-a-day check as `updateNotice`, but *awaited* and detailed.
  *
@@ -518,11 +596,23 @@ async function checkPublished({
  * Rendered from `updatePlan`, not from a second copy of the sentence: the
  * command the terminal tells the user to run and the command the window's
  * banner offers are the same string produced by the same verdict.
+ *
+ * `method` is the install channel the caller detected (see
+ * `detectInstallMethod`). It is threaded through rather than assumed to be npm
+ * because the previous version returned `null` — silence — for every channel
+ * that was not npm, so a pip install and an npx run were never told a release
+ * existed. A host that knows how it was installed should say so.
  */
-function updateLine({ current, latest, behind, pkg = PKG }) {
-  const plan = updatePlan({ current, latest, behind, channel: 'npm', pkg });
-  if (plan.action !== 'npm-update') return null;
-  return `Update available: ${plan.current} → ${plan.latest}   run: ${plan.instruction}`;
+function updateLine({ current, latest, behind, pkg = PKG, method = 'npm' }) {
+  const plan = updatePlan({ current, latest, behind, channel: 'npm', pkg, method });
+  if (!plan.behind) return null;
+  const head = `Update available: ${plan.current} → ${plan.latest}`;
+  // `apply` is null for the two channels with nothing to install, whose
+  // instruction is already a sentence — prefixing those with "run:" would read
+  // as a command that does not exist.
+  return plan.apply
+    ? `${head}   run: ${plan.instruction}`
+    : `${head}   ${plan.instruction}`;
 }
 
 /**
@@ -607,6 +697,8 @@ module.exports = {
   checkPublished,
   updatePlan,
   updateLine,
+  detectInstallMethod,
+  APPLIERS,
   PKG,
   CHECK_INTERVAL_MS,
   REASONS,