@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/server/lib/omp/session/sidebar-activity.server.test.ts

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `sidebar:activity` resolver, against a real sessions directory.
+ *
+ * The rules under test are the ones that keep this payload small enough to be
+ * republished per tool call:
+ *
+ *   - it carries ONLY sessions with a run in flight — every other row keeps the
+ *     stamp the structure gave it, which is why the structure does not have to
+ *     be re-scanned;
+ *   - a live run with no transcript yet contributes nothing (a fresh spawn:
+ *     omp writes the file only when the first assistant message settles);
+ *   - the stamp it reports is the newest ENTRY's timestamp, the same quantity
+ *     the structure ships as `updated_at`, so the client can compare them;
+ *   - the subagent flag is reported alongside, because a subagent's transcript
+ *     appears mid-run and lights the parent row's roster chevron.
+ *
+ * Driven through `localRuns()` rather than a stubbed registry: that set is the
+ * real "a run is in flight" source (the mock SSE stream uses it too), so the
+ * test exercises the same read `loadSidebarStatus` does.
+ */
+
+import { afterAll, afterEach, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import * as path from 'path';
+
+import { loadSidebarActivity } from '@/server/lib/omp/session/sidebar-activity.server';
+import { localRuns } from '@/server/lib/omp/session/local-runs.server';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { SESSION_TITLE_SLOT_BYTES } from '@/server/lib/omp/session/files';
+
+const tempDirs: string[] = [];
+const previousAgentDir = process.env.PI_CODING_AGENT_DIR;
+
+/**
+ * Point the agent dir at a scratch tree, because `findSessionFileById` resolves
+ * through the real sessions root. `PI_CODING_AGENT_DIR` is read per call, so no
+ * module reload is needed — but the file caches are process-wide and keyed by
+ * path, so they are cleared before and after.
+ */
+function useAgentDir(): string {
+  const dir = fs.mkdtempSync(path.join(fs.realpathSync('/tmp'), 'kabmo-activity-'));
+  tempDirs.push(dir);
+  process.env.PI_CODING_AGENT_DIR = dir;
+  clearSessionFileCaches();
+  return dir;
+}
+
+/** A title slot line, exactly as omp writes it, so the scan reads a real file. */
+function titleSlot(title: string): string {
+  const raw = JSON.stringify({ type: 'title', title });
+  return raw + ' '.repeat(Math.max(0, SESSION_TITLE_SLOT_BYTES - 1 - raw.length));
+}
+
+interface SessionFixture {
+  id: string;
+  entries?: Array<{ type: string; timestamp?: string }>;
+  subagents?: string[];
+}
+
+/**
+ * Write one session file under `<agentDir>/sessions/<project>/`.
+ *
+ * The entries are minimal but carry the field the scan dates the file by (the
+ * newest entry's own `timestamp`), which is the whole quantity under test.
+ */
+function writeSession(agentDir: string, fixture: SessionFixture): string {
+  const projectDir = path.join(agentDir, 'sessions', '-tmp-project');
+  fs.mkdirSync(projectDir, { recursive: true });
+  const file = path.join(projectDir, `2026-10-24T00-00-00-000Z_${fixture.id}.jsonl`);
+  const lines = [
+    titleSlot(`Session ${fixture.id}`),
+    JSON.stringify({ type: 'session', id: fixture.id, cwd: '/tmp/project', timestamp: '2026-10-24T00:00:00.000Z' }),
+    ...(fixture.entries ?? []).map((entry) => JSON.stringify(entry)),
+  ];
+  fs.writeFileSync(file, `${lines.join('\n')}\n`);
+
+  if (fixture.subagents?.length) {
+    // A sibling directory named after the session file, holding one .jsonl per
+    // subagent — the shape `sessionHasSubagents` reads.
+    const sibling = file.replace(/\.jsonl$/, '');
+    fs.mkdirSync(sibling, { recursive: true });
+    for (const id of fixture.subagents) {
+      fs.writeFileSync(path.join(sibling, `${id}.jsonl`), `${JSON.stringify({ type: 'message' })}\n`);
+    }
+  }
+  clearSessionFileCaches();
+  return file;
+}
+
+afterEach(() => {
+  localRuns().clear();
+  clearSessionFileCaches();
+});
+
+afterAll(() => {
+  if (previousAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+  else process.env.PI_CODING_AGENT_DIR = previousAgentDir;
+  for (const dir of tempDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe('loadSidebarActivity', () => {
+  test('carries nothing when no run is in flight', async () => {
+    const agentDir = useAgentDir();
+    writeSession(agentDir, { id: 'idle', entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }] });
+    expect(await loadSidebarActivity()).toEqual({});
+  });
+
+  test('reports the newest entry timestamp of a session with a live run', async () => {
+    const agentDir = useAgentDir();
+    writeSession(agentDir, {
+      id: 'live',
+      entries: [
+        { type: 'message', timestamp: '2026-10-24T01:00:00.000Z' },
+        { type: 'message', timestamp: '2026-10-24T01:05:00.000Z' },
+      ],
+    });
+    localRuns().add('live');
+
+    const activity = await loadSidebarActivity();
+    expect(Object.keys(activity)).toEqual(['live']);
+    expect(activity.live?.updatedAt).toBe('2026-10-24T01:05:00.000Z');
+  });
+
+  test('never reports a session without a run, however recent its transcript', async () => {
+    const agentDir = useAgentDir();
+    writeSession(agentDir, { id: 'other', entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }] });
+    writeSession(agentDir, { id: 'live', entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }] });
+    localRuns().add('live');
+
+    expect(Object.keys(await loadSidebarActivity())).toEqual(['live']);
+  });
+
+  test('omits a live run whose transcript does not exist yet', async () => {
+    // A fresh spawn: omp writes the session file only when the first assistant
+    // message settles, so there is no stamp to report. Its row is the client's
+    // pending row until the scan finds the file.
+    useAgentDir();
+    localRuns().add('not-written-yet');
+    expect(await loadSidebarActivity()).toEqual({});
+  });
+
+  test('reports the subagent flag, which moves mid-run', async () => {
+    const agentDir = useAgentDir();
+    writeSession(agentDir, {
+      id: 'with-sub',
+      entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }],
+      subagents: ['Sleeper'],
+    });
+    writeSession(agentDir, { id: 'plain', entries: [{ type: 'message', timestamp: '2026-10-24T01:00:00.000Z' }] });
+    localRuns().add('with-sub');
+    localRuns().add('plain');
+
+    const activity = await loadSidebarActivity();
+    expect(activity['with-sub']?.hasSubagents).toBe(true);
+    expect(activity.plain?.hasSubagents).toBe(false);
+  });
+});

package/src/server/lib/omp/session/sidebar-activity.server.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `sidebar:activity` resolver: the two row fields a RUNNING session can
+ * still move between turn boundaries.
+ *
+ * Split out of `sidebar-data.server.ts` (which owns the structure and the
+ * status) because it answers a different question at a different cadence: the
+ * structure is re-scanned at turn boundaries, while this is resolved on every
+ * tool call — and its whole reason to exist is that the structure must NOT be.
+ *
+ * A run appends to its transcript on every tool call, so its row's age and its
+ * `LATEST_SESSION` position move mid-run. Republishing the structure for that
+ * cost 216 KB over 731 sessions per tool call (measured on the author's
+ * install, against 87 bytes for one live entry here), which is what made a
+ * phone's stream feel slow. Only a RUNNING session can move between boundaries,
+ * so only those are carried.
+ *
+ * A live run with no session FILE yet (a fresh spawn: omp writes it only when
+ * the first assistant message settles) contributes nothing — there is no stamp
+ * to report, and its sidebar row is the client's pending row until the scan
+ * finds the file.
+ */
+
+import { isMockMode } from '@/server/mock.server';
+import { getLiveRunSessionIds } from '@/server/lib/omp/rpc/session-registry';
+import { findSessionFileById } from '@/server/lib/omp/session/locator';
+import { scanSessionInfoCached } from '@/server/lib/omp/session/files';
+import { sessionHasSubagents } from '@/server/lib/omp/session/subagent-presence';
+import type { SidebarActivityPayload } from '@/shared/types/realtime';
+
+export async function loadSidebarActivity(): Promise<SidebarActivityPayload> {
+  const activity: SidebarActivityPayload = {};
+  // MOCK answers nothing, and that is not a shortcut: the simulated stream is
+  // an SSE route, not an omp child, so no `tool_execution_end` frame ever fires
+  // there and there is no between-boundary movement to report. Its rows also
+  // read `created_at` (the mock `sessions` table has no `updated_at`), so a
+  // `chat_sessions` stamp would be a different quantity under the same name —
+  // the one thing this payload must never be.
+  if (isMockMode()) return activity;
+
+  const live = getLiveRunSessionIds();
+  if (live.size === 0) return activity;
+  const entries = await Promise.all(
+    [...live].map(async (sessionId) => {
+      const filePath = await findSessionFileById(sessionId);
+      if (!filePath) return null;
+      const info = await scanSessionInfoCached(filePath);
+      if (!info) return null;
+      // `modified` is the newest entry's own timestamp, which is what the
+      // structure ships as `updated_at` — the same quantity, so the client can
+      // compare the two as ISO strings.
+      const updatedAt = info.modified.toISOString();
+      // The chevron's flag moves mid-run too: a subagent writes its own
+      // transcript beside the parent, and the row it lights is the parent's.
+      // Cost is a stat plus (on a change) one readdir, and the presence module
+      // memoizes on `(last entry, sibling mtime)` — measured 4-8 ms on a cache
+      // miss, 0 on a hit.
+      const hasSubagents = await sessionHasSubagents(filePath, updatedAt);
+      return [sessionId, { updatedAt, hasSubagents }] as const;
+    }),
+  );
+  for (const entry of entries) {
+    if (entry) activity[entry[0]] = entry[1];
+  }
+  return activity;
+}

package/src/server/lib/omp/session/telemetry/compute.ts

@@ -10,6 +10,15 @@ import { scanSessionEntries } from '@/server/lib/omp/session/telemetry/scan';
  * Compute real `SessionContextTelemetry` for a session file (all-zero on
  * unreadable/empty). `rawLimit` caps materialized raw items (0 = none): the
  * panel reads full pages from `computeRawMessagesPage` in ./telemetry-raw.ts.
+ *
+ * The default is 0 — no raw items — and that is load-bearing rather than
+ * tidy: this value is published as the `session:<id>:telemetry` topic, which
+ * the navbar ring subscribes to for EVERY open session and the server
+ * republishes on every tool call. Measured on a 111-message transcript, the
+ * full `rawMessages` list (each item carrying its whole entry as
+ * `rawPayload`) was **690 KB of a 691 KB snapshot** — 99.9% of every push,
+ * per tool call, per tab. Nothing reads it: the panel pages raw items from
+ * `/api/telemetry/raw-messages`, and `/api/telemetry/context` strips them.
  */
 export async function computeRealSessionTelemetry(
   filePath: string,
@@ -106,7 +115,10 @@ export async function computeRealSessionTelemetry(
 
     if (role === 'user' || role === 'assistant') {
       messagesCount++;
-      if (rawLimit === 0 || rawMessages.length < rawLimit) {
+      // `rawLimit` is a CAP, so 0 means "none" — the guard must not read 0 as
+      // "unlimited", which is what it did and what put the whole transcript on
+      // the telemetry topic (see the doc above).
+      if (rawLimit > 0 && rawMessages.length < rawLimit) {
         const isAssistant = role === 'assistant';
         const snippet = text.slice(0, 70);
         rawMessages.push({

package/src/server/lib/omp/session/telemetry.test.ts

@@ -152,3 +152,36 @@ describe('computeRealSessionTelemetry context anchor', () => {
     expect(telemetry.contextUsed).toBe(2200);
   });
 });
+
+describe('computeRealSessionTelemetry raw items', () => {
+  // The default is the TELEMETRY TOPIC's payload, which the navbar ring keeps
+  // subscribed for every open session and the server republishes on every tool
+  // call. A raw item carries its whole entry as `rawPayload`, so reading 0 as
+  // "unlimited" put the entire transcript on that topic — measured 690 KB of a
+  // 691 KB snapshot on a 111-message session.
+  test('materializes no raw items by default', async () => {
+    const file = await writeSession([
+      header,
+      userMessage('u1', 'first turn'),
+      assistantMessage('a1', { usage: { input: 10, output: 5 } }),
+      userMessage('u2', 'second turn'),
+      assistantMessage('a2', { usage: { input: 20, output: 5 } }),
+    ]);
+    const telemetry = await computeRealSessionTelemetry(file, 'ses_telemetry');
+    expect(telemetry.messagesCount).toBe(4);
+    expect(telemetry.rawMessages).toEqual([]);
+  });
+
+  test('caps raw items at a positive limit', async () => {
+    const file = await writeSession([
+      header,
+      userMessage('u1', 'first turn'),
+      assistantMessage('a1', { usage: { input: 10, output: 5 } }),
+      userMessage('u2', 'second turn'),
+      assistantMessage('a2', { usage: { input: 20, output: 5 } }),
+    ]);
+    const telemetry = await computeRealSessionTelemetry(file, 'ses_telemetry', undefined, 2);
+    expect(telemetry.rawMessages).toHaveLength(2);
+    expect(telemetry.rawMessages[0]?.id).toBe('u1');
+  });
+});

package/src/server/lib/realtime/signals.server.ts

@@ -22,6 +22,16 @@ export type RealtimeSignal =
   | 'stream-status'
   /** The sidebar's structure changed (a session or folder was added/removed). */
   | 'sidebar-structure'
+  /**
+   * A RUNNING session's transcript grew, so its last-activity stamp moved.
+   *
+   * Raised per tool call, which is the whole reason it is not
+   * `sidebar-structure`: that payload is every folder and session (216 KB over
+   * 731 sessions, measured), while only a running session's stamp can move
+   * between turn boundaries. Republishing the structure here is what made a
+   * phone's stream feel slow — one full list per tool call.
+   */
+  | 'sidebar-activity'
   /** An omp child for `sessionId` became reachable, or was torn down. */
   | 'session-attached'
   /** A scheduled task was created, edited, paused, deleted or fired. */

package/src/server/lib/realtime/topics/catalog.server.ts

@@ -20,6 +20,7 @@ import {
   TOPIC_PANELS,
   TOPIC_SCHEDULE,
   TOPIC_SIDEBAR,
+  TOPIC_SIDEBAR_ACTIVITY,
   TOPIC_SIDEBAR_STATUS,
   TOPIC_USAGE,
   TOPIC_WAITING,
@@ -28,10 +29,11 @@ import {
   sessionTelemetryTopic,
   sessionTodosTopic,
 } from '@/shared/lib/realtime/protocol';
-import type { SidebarPayload, SidebarStatusPayload } from '@/shared/types/realtime';
+import type { SidebarActivityPayload, SidebarPayload, SidebarStatusPayload } from '@/shared/types/realtime';
 import { isValidPluginId } from '@/shared/lib/plugins/protocol';
 import type { TopicDescriptor } from '@/server/lib/realtime/hub.types';
 import { loadSidebarStatus, loadSidebarStructure } from '@/server/lib/omp/session/sidebar-data.server';
+import { loadSidebarActivity } from '@/server/lib/omp/session/sidebar-activity.server';
 import { sessionDescriptor } from '@/server/lib/realtime/topics/session.server';
 import { btwDescriptor } from '@/server/lib/realtime/topics/btw.server';
 import { SESSION_DATA_TOPICS } from '@/server/lib/realtime/topics/session-data.server';
@@ -64,6 +66,7 @@ export const SCOPED_FAMILIES: Record<string, (scope: string) => TopicDescriptor>
 export const EXACT_TOPICS = new Map<string, TopicDescriptor>([
   [TOPIC_SIDEBAR, { resolve: async (): Promise<SidebarPayload> => loadSidebarStructure() }],
   [TOPIC_SIDEBAR_STATUS, { resolve: async (): Promise<SidebarStatusPayload> => loadSidebarStatus() }],
+  [TOPIC_SIDEBAR_ACTIVITY, { resolve: async (): Promise<SidebarActivityPayload> => loadSidebarActivity() }],
   [TOPIC_SCHEDULE, { resolve: () => globalDescriptor(TOPIC_SCHEDULE).resolve(TOPIC_SCHEDULE) }],
   [TOPIC_USAGE, { resolve: () => globalDescriptor(TOPIC_USAGE).resolve(TOPIC_USAGE) }],
   [TOPIC_PANELS, { resolve: () => globalDescriptor(TOPIC_PANELS).resolve(TOPIC_PANELS) }],

package/src/server/lib/realtime/topics.server.ts

@@ -18,6 +18,7 @@ import {
   TOPIC_PANELS,
   TOPIC_SCHEDULE,
   TOPIC_SIDEBAR,
+  TOPIC_SIDEBAR_ACTIVITY,
   TOPIC_SIDEBAR_STATUS,
   TOPIC_USAGE,
   TOPIC_WAITING,
@@ -29,6 +30,7 @@ import { getRealtimeHub, registerTopics, type TopicDescriptor } from '@/server/l
 import { onRealtimeSignal } from '@/server/lib/realtime/signals.server';
 import { invalidateOmpSidebarData } from '@/server/lib/omp/session/reader';
 import { loadSidebarStatus, loadSidebarStructure } from '@/server/lib/omp/session/sidebar-data.server';
+import { loadSidebarActivity } from '@/server/lib/omp/session/sidebar-activity.server';
 import { EXACT_TOPICS, descriptorFor, isKnownTopicName } from '@/server/lib/realtime/topics/catalog.server';
 
 declare global {
@@ -78,6 +80,7 @@ export function initRealtimeTopics(): void {
   onRealtimeSignal(({ signal, sessionId, root }) => {
     if (signal === 'stream-status') publishSidebarStatus();
     else if (signal === 'sidebar-structure') publishSidebarStructure();
+    else if (signal === 'sidebar-activity') publishSidebarActivity();
     else if (signal === 'session-attached' && sessionId) publishSessionState(sessionId);
     else if (signal === 'schedule-changed') publishTopic(TOPIC_SCHEDULE);
     else if (signal === 'panels-changed') publishTopic(TOPIC_PANELS);
@@ -244,6 +247,19 @@ export function publishSidebarStatus(): void {
   schedulePublish(TOPIC_SIDEBAR_STATUS, loadSidebarStatus);
 }
 
+/**
+ * A RUNNING session's transcript grew: republish its activity stamps.
+ *
+ * Called per tool call (see `handleToolExecutionEnd`), so it must never be the
+ * structure publish: that one invalidates the discovery scan and re-serializes
+ * every folder and session. This payload carries one ISO string per live run
+ * and re-reads nothing but those files' own summaries (each memoized on
+ * `(size, mtimeMs)`, measured 0.1 ms on a cache miss).
+ */
+export function publishSidebarActivity(): void {
+  schedulePublish(TOPIC_SIDEBAR_ACTIVITY, loadSidebarActivity);
+}
+
 /**
  * The sidebar's STRUCTURE changed: a session was created, deleted, renamed, a
  * folder was added or removed, or a JSONL grew a new session.

package/src/server/lib/updates/shell-assets.ts

@@ -12,6 +12,7 @@
  * version against a shell version.
  */
 
+import type { ShellArch } from '@/shared/lib/updates/shell-arch';
 import type { ShellKind } from '@/shared/lib/updates/shell-ua';
 
 /**
@@ -28,7 +29,13 @@ import type { ShellKind } from '@/shared/lib/updates/shell-ua';
  * The desktop entries match on the segment AFTER the version rather than on the
  * whole name, because one release carries several files per platform
  * (`-mac-arm64.zip` and `-mac-arm64.dmg`, four Linux formats, two arches). Any
- * one of them answers the same version, and the download is the release page.
+ * one of them answers the same version, which is all `pattern` is for.
+ *
+ * WHICH file the console hands back is a second question, and `selfUpdate` is
+ * the answer: a desktop shell that knows its architecture installs one exact
+ * artifact, and a probe that does not know it still gets the release page. Both
+ * live in this table so the route, the pages fallback and the tests read one
+ * spelling.
  *
  * **`legacy` is not dead code.** These names are PARSED to answer "is a newer
  * shell published", and every release already on GitHub carries the old mobile
@@ -45,47 +52,131 @@ export interface AssetScheme {
   /** The old mobile spelling, or null for a shell that never had one. */
   legacy: { prefix: string; extension: string } | null;
   /**
-   * Whether the payload's `url` should be the artifact itself. False for a
-   * per-arch desktop build, where the release page is the only honest link.
+   * Whether the payload's `url` should be the artifact itself. True for the
+   * mobile pair, whose artifact is the same file on every device.
    */
   directDownload: boolean;
+  /**
+   * The ONE file a desktop shell installs ITSELF from, per architecture.
+   *
+   * `null` for the mobile pair: an APK is installed by `PackageInstaller` and an
+   * IPA cannot be installed at all, so neither is this shell's own business.
+   *
+   * The desktop entry is deliberately narrower than `pattern`: one release
+   * carries several files per platform (`.zip` and `.dmg`, `.tar.gz`/`.deb`/
+   * `.rpm`/`.AppImage`), and only ONE of each is something the shell can install
+   * without a human opening it. The choice is stated here rather than at the
+   * call site so the route, the pages fallback and the tests cannot disagree
+   * about which file "the update" means.
+   */
+  selfUpdate: SelfUpdateScheme | null;
+}
+
+/**
+ * How one desktop shell's self-update artifact is named.
+ *
+ * `pattern` captures the version AND the architecture, because the two answers
+ * come from the same string: the version is what the console compares against
+ * the installed build, and the architecture is what makes this file the right
+ * one for the machine asking.
+ */
+export interface SelfUpdateScheme {
+  /** `Kabmo-<version>-<platform>-<arch><suffix>` → `[name, version, arch]`. */
+  pattern: RegExp;
+  /** How each canonical arch is spelled in the ASSET name. */
+  assetArch: Record<ShellArch, string>;
 }
 
 const VERSION = String.raw`(\d+\.\d+\.\d+)`;
 
+/** `arm64`/`x64` as macOS and Windows spell them. */
+const SAME_ARCH: Record<ShellArch, string> = { arm64: 'arm64', x64: 'x64' };
+
+/** Linux says `x86_64` where the other two say `x64`. */
+const LINUX_ARCH: Record<ShellArch, string> = { arm64: 'arm64', x64: 'x86_64' };
+
 export const SHELL_ASSETS: Record<ShellKind, AssetScheme> = {
   android: {
     pattern: new RegExp(`^Kabmo-${VERSION}-android\\.apk$`),
     current: /^Kabmo-\d/,
     legacy: { prefix: 'kabmo-android-v', extension: '.apk' },
     directDownload: true,
+    selfUpdate: null,
   },
   ios: {
     pattern: new RegExp(`^Kabmo-${VERSION}-ios\\.ipa$`),
     current: /^Kabmo-\d/,
     legacy: { prefix: 'kabmo-ios-v', extension: '.ipa' },
     directDownload: true,
+    selfUpdate: null,
   },
   macos: {
     pattern: new RegExp(`^Kabmo-${VERSION}-mac-`),
     current: /^Kabmo-\d/,
     legacy: null,
     directDownload: false,
+    // The `.zip`, not the `.dmg`: `ditto -x -k` extracts it without mounting a
+    // volume, and the shell has to be able to do that with no human present.
+    // Both shapes are published; only one is installable by the app itself.
+    selfUpdate: {
+      pattern: new RegExp(`^Kabmo-${VERSION}-mac-(arm64|x64)\\.zip$`),
+      assetArch: SAME_ARCH,
+    },
   },
   windows: {
     pattern: new RegExp(`^Kabmo-${VERSION}-win-`),
     current: /^Kabmo-\d/,
     legacy: null,
     directDownload: false,
+    // The INSTALLER, not the `.zip`-shaped publish output: Inno already owns the
+    // upgrade semantics (a stable `AppId` is what makes an install an upgrade
+    // rather than a second copy), and `/CLOSEAPPLICATIONS` is how it replaces a
+    // running exe.
+    selfUpdate: {
+      pattern: new RegExp(`^Kabmo-${VERSION}-win-(arm64|x64)-setup\\.exe$`),
+      assetArch: SAME_ARCH,
+    },
   },
   linux: {
     pattern: new RegExp(`^Kabmo-${VERSION}-linux-`),
     current: /^Kabmo-\d/,
     legacy: null,
     directDownload: false,
+    // The AppImage, and only it: `.deb`/`.rpm` need root and a package manager,
+    // so a shell cannot install them — it says so instead. An AppImage is ONE
+    // file the shell can replace atomically and re-exec.
+    selfUpdate: {
+      pattern: new RegExp(`^Kabmo-${VERSION}-linux-(arm64|x86_64)\\.AppImage$`),
+      assetArch: LINUX_ARCH,
+    },
   },
 };
 
+/**
+ * The self-update artifact for one architecture, if this name is it.
+ *
+ * Null for a shell that has no self-update, for an arch it does not publish, and
+ * for every other file in the release (a `.dmg`, a `.deb`, the OTHER
+ * architecture's build). Callers treat null as "not the file this machine
+ * installs", which is why the route falls back to the release page rather than
+ * guessing.
+ */
+export function selfUpdateArtifact(
+  kind: ShellKind,
+  arch: ShellArch,
+  name: string,
+): { version: string } | null {
+  const scheme = SHELL_ASSETS[kind].selfUpdate;
+  if (!scheme) return null;
+
+  const match = scheme.pattern.exec(name);
+  if (!match) return null;
+  // The captured arch is compared against the ASSET spelling, so a Linux build
+  // reporting `x64` matches `…-linux-x86_64.AppImage` and nothing else.
+  if (match[2] !== scheme.assetArch[arch]) return null;
+  return { version: match[1] ?? '' };
+}
+
 /**
  * `Kabmo-0.5.0-android.apk` → `0.5.0`, the `.ipa` twin, every desktop spelling,
  * plus the legacy `kabmo-android-v0.5.0.apk` the older releases still carry.

package/src/server/lib/updates/shell-cache.ts

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The shell-release answer cache, and where the GitHub reads go.
+ *
+ * Split from `shell-release.ts` for two reasons that are not cosmetic.
+ *
+ * 1. **The key is per SHELL AND per ARCHITECTURE.** A desktop shell asks for the
+ *    artifact of its own machine, so a single per-kind slot would answer an
+ *    arm64 window with the x64 installer the moment both hit one console — and
+ *    the console is routinely shared by a whole team.
+ * 2. **The cache outlives a test file.** It lives on `globalThis` so `bun --hot`
+ *    cannot orphan it, which is also why `resetShellReleaseCache` exists: without
+ *    that seam the second case in a suite reads the first case's answer and
+ *    passes for the wrong reason (measured — the "malformed body" case returned
+ *    the previous test's release).
+ */
+
+import type { ShellArch } from '@/shared/lib/updates/shell-arch';
+import type { ShellKind } from '@/shared/lib/updates/shell-ua';
+
+/** How long an answer is reused. */
+export const CACHE_MS = 5 * 60_000;
+
+/** One shell's (and, for a desktop, one architecture's) cached answer. */
+export interface CacheSlot<T> {
+  entry: T | null;
+  at: number;
+}
+
+type ShellCacheHost = typeof globalThis & {
+  __kabmoShellRelease?: Record<string, CacheSlot<unknown>>;
+};
+
+/**
+ * The cache key for one question.
+ *
+ * The arch is part of the KEY rather than a field on the value, so a stale entry
+ * can never be read by the wrong machine: a miss is a miss, and there is no
+ * comparison left to get wrong.
+ */
+export function shellCacheKey(kind: ShellKind, arch: ShellArch | null): string {
+  return arch ? `${kind}:${arch}` : kind;
+}
+
+/** The cache slot for one key, created on first use. */
+export function cacheSlot<T>(key: string): CacheSlot<T> {
+  const host = globalThis as ShellCacheHost;
+  host.__kabmoShellRelease ??= {};
+  host.__kabmoShellRelease[key] ??= { entry: null, at: 0 };
+  return host.__kabmoShellRelease[key] as CacheSlot<T>;
+}
+
+/**
+ * Drop the cached answer for one shell (or every shell, with no argument).
+ *
+ * Production has no caller; it is the test seam described above.
+ */
+export function resetShellReleaseCache(kind?: ShellKind): void {
+  const host = globalThis as ShellCacheHost;
+  if (!kind) {
+    host.__kabmoShellRelease = {};
+    return;
+  }
+  const prefix = `${kind}:`;
+  const slots = host.__kabmoShellRelease ?? {};
+  for (const key of Object.keys(slots)) {
+    if (key === kind || key.startsWith(prefix)) delete slots[key];
+  }
+}
+
+/**
+ * Where the release read goes.
+ *
+ * Overridable for the same reason the npm probe honours `NPM_CONFIG_REGISTRY`: a
+ * test and a rehearsal need to exercise the real parsing against a stub instead
+ * of a live GitHub call, and hardcoding the host makes that impossible without
+ * intercepting `fetch` globally.
+ */
+export function githubApiBase(): string {
+  const configured = Bun.env.KABMO_GITHUB_API ?? '';
+  return configured.trim().replace(/\/+$/, '') || 'https://api.github.com';
+}
+
+/**
+ * A token, when the operator has one, which lifts the API quota from 60 an hour
+ * to 5000 — the difference between the precise read working on a shared address
+ * and falling through to the pages every time.
+ *
+ * Read from the environment rather than a setting: it is a deployment fact, it
+ * must never reach the browser, and `kabmo serve` already passes its own
+ * environment through.
+ */
+export function gitHubHeaders(): Record<string, string> {
+  const token = (Bun.env.KABMO_GITHUB_TOKEN ?? Bun.env.GITHUB_TOKEN ?? '').trim();
+  const headers: Record<string, string> = {
+    // GitHub rejects a request with no User-Agent.
+    'user-agent': 'kabmo-console',
+  };
+  if (token) headers.authorization = `Bearer ${token}`;
+  return headers;
+}