@kabmo-labs/kabmo 0.1.0 → 0.3.0

package/src/server/lib/updates/android-release.ts

@@ -0,0 +1,183 @@
+/**
+ * Which Android APK a browser should download, and whether this one is behind.
+ *
+ * The APK is NOT an npm package (see `.github/workflows/publish-android.yml`), so
+ * the npm probe that answers for the app and for `omp` cannot answer here. The
+ * only record of a published APK is a GitHub release asset, which means one
+ * unauthenticated REST read of the release LIST — not `/releases/latest`, which
+ * answers the newest release of ANY kind (see `fetchAndroidRelease`).
+ *
+ * Two facts travel back, and they answer different questions:
+ *
+ * - `url` is the asset to download. It is resolved from the release's OWN asset
+ *   list rather than built as `releases/latest/download/<name>`, because that
+ *   path needs the asset name to match exactly and the name carries the tag
+ *   (`kabmo-android-v1.2.3.apk`) — a name built here would be a second copy of
+ *   the workflow's naming rule, and the first release that renames it 404s.
+ * - `latest` is the version that asset ships, read from the asset name. The
+ *   release TAG cannot be used: the APK is attached to the app's release, whose
+ *   tag names the SERVER version, and the two move independently.
+ *
+ * Failure is a normal answer here (`null`), never a throw: an offline box or a
+ * rate-limited GitHub must not take the sidebar down, and a button that appears
+ * because a probe failed would offer a download that does not exist.
+ */
+
+import { REPO } from '@/server/lib/updates/release-url';
+
+/** One published APK, as the console needs it. */
+export interface AndroidRelease {
+  /** Asset download URL, or null when the release carries no APK. */
+  url: string | null;
+  /** Version the asset name declares (`v1.2.3` → `1.2.3`), or null. */
+  latest: string | null;
+  /** The release page, for a "what changed" link. */
+  releaseUrl: string | null;
+}
+
+/** The asset-name prefix the release workflow writes. */
+const ASSET_PREFIX = 'kabmo-android-';
+
+/**
+ * `kabmo-android-v1.2.3.apk` → `1.2.3`.
+ *
+ * The `v` is optional because a hand-uploaded asset may omit it, and a version
+ * that cannot be read is not evidence of an update — the caller treats null as
+ * "no new version".
+ */
+export function versionFromAssetName(name: string): string | null {
+  if (!name.startsWith(ASSET_PREFIX) || !name.endsWith('.apk')) return null;
+  const middle = name.slice(ASSET_PREFIX.length, -'.apk'.length);
+  const version = middle.startsWith('v') ? middle.slice(1) : middle;
+  return /^\d+\.\d+\.\d+/.test(version) ? version : null;
+}
+
+/**
+ * The newest release that actually carries an APK.
+ *
+ * NOT `/releases/latest`, which answers the newest release of ANY kind. This
+ * repository publishes three artifacts from one push, and the packages are
+ * released FIRST (`packages → marketplace → android → app` in `release.yml`),
+ * so their `kabmo-sdk/v*` / `kabmo-ui/v*` releases are newer than the app
+ * release that carries the APK. `@semantic-release/github` runs in both
+ * pipelines, so those are real releases — measured against a stub that answered
+ * a package release: `/releases/latest` produced `{url: null, latest: null}` and
+ * the sidebar's button disappeared even though the APK sat on the release
+ * directly below.
+ *
+ * One request, cached for five minutes on `globalThis` for the same reason the
+ * database handle is anchored there: `bun --hot` re-evaluates this module while
+ * the cache it would otherwise hold lives on. GitHub allows 60 unauthenticated
+ * reads an hour per address, and the sidebar asks on every mount.
+ */
+export async function fetchAndroidRelease(fetchImpl: typeof fetch = fetch): Promise<AndroidRelease | null> {
+  const cache = cacheSlot();
+  const now = Date.now();
+  if (cache.entry && now - cache.at < CACHE_MS) return cache.entry;
+
+  try {
+    const response = await fetchImpl(`${githubApiBase()}/repos/${REPO}/releases?per_page=${RELEASE_SCAN}`, {
+      headers: {
+        accept: 'application/vnd.github+json',
+        // GitHub rejects a request with no User-Agent.
+        'user-agent': 'kabmo-console',
+      },
+    });
+    if (!response.ok) return cache.entry ?? null;
+
+    const body = (await response.json()) as unknown;
+    // A body that is not the release list is a failed probe, not an empty
+    // repository: answering `{url: null, latest: null}` here would be
+    // indistinguishable from "no release carries an APK", and the caller would
+    // cache that mistake for five minutes.
+    if (!Array.isArray(body)) return cache.entry ?? null;
+
+    // Drafts are not published and prereleases are not what a console offers an
+    // installed app — the same two the `latest` endpoint excluded.
+    const published = body.filter(
+      (entry): entry is Record<string, unknown> =>
+        entry !== null && typeof entry === 'object' && entry.draft !== true && entry.prerelease !== true,
+    );
+
+    const release = published
+      .map((entry) => ({ entry, asset: apkAsset(entry.assets) }))
+      .find((candidate) => candidate.asset !== null);
+
+    if (!release?.asset) {
+      const fallback: AndroidRelease = { url: null, latest: null, releaseUrl: null };
+      cache.entry = fallback;
+      cache.at = now;
+      return fallback;
+    }
+
+    const resolved: AndroidRelease = {
+      url: typeof release.asset.browser_download_url === 'string' ? release.asset.browser_download_url : null,
+      latest: versionFromAssetName(String(release.asset.name)),
+      releaseUrl: typeof release.entry.html_url === 'string' ? release.entry.html_url : null,
+    };
+
+    cache.entry = resolved;
+    cache.at = now;
+    return resolved;
+  } catch {
+    // Keep the last good answer rather than replacing it with a failure: a
+    // momentary outage must not remove a download button that was valid.
+    return cache.entry ?? null;
+  }
+}
+
+/** How many releases to look back through for the APK. */
+const RELEASE_SCAN = 20;
+
+/** The first asset of a release that names an APK, or null. */
+function apkAsset(assets: unknown): Record<string, unknown> | null {
+  if (!Array.isArray(assets)) return null;
+
+  for (const entry of assets) {
+    if (entry === null || typeof entry !== 'object') continue;
+    const asset = entry as Record<string, unknown>;
+    if (typeof asset.name === 'string' && versionFromAssetName(asset.name) !== null) return asset;
+  }
+
+  return null;
+}
+
+const CACHE_MS = 5 * 60_000;
+
+/**
+ * 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.
+ */
+function githubApiBase(): string {
+  const configured = Bun.env.KABMO_GITHUB_API ?? '';
+  return configured.trim().replace(/\/+$/, '') || 'https://api.github.com';
+}
+
+interface CacheSlot {
+  entry: AndroidRelease | null;
+  at: number;
+}
+
+function cacheSlot(): CacheSlot {
+  const host = globalThis as typeof globalThis & { __kabmoAndroidRelease?: CacheSlot };
+  host.__kabmoAndroidRelease ??= { entry: null, at: 0 };
+  return host.__kabmoAndroidRelease;
+}
+
+/**
+ * Drop the cached answer.
+ *
+ * The cache lives on `globalThis` so `bun --hot` cannot orphan it, which also
+ * means it outlives a test file: without this 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). Production has no
+ * caller; it exists because the cache is process-wide by design.
+ */
+export function resetAndroidReleaseCache(): void {
+  cacheSlot().entry = null;
+  cacheSlot().at = 0;
+}

package/src/server/plugins/ssr.ts

@@ -15,6 +15,7 @@ import { readSettingsBlob } from '@/shared/lib/settings/keys';
 import { resolveTheme } from '@/shared/lib/theme/catalog';
 import { windowChromeColor } from '@/shared/lib/theme/chrome';
 import { THEME_STYLE_ELEMENT_ID, themeStyleSheet } from '@/shared/lib/theme/css';
+import { androidShellVersion, isAndroidDevice } from '@/shared/lib/updates/shell-ua';
 
 /** HTML-escape a string for interpolation into the failure page's `<pre>`. */
 function escapeHtmlText(value: string): string {
@@ -153,7 +154,18 @@ export const ssrRoutes = new Elysia({ name: 'ssr' }).get('*', async ({ request }
   // downgrade, the retired `noir` alias) renders the default palette instead of
   // an unstyled page.
   const theme = resolveTheme(settingsBlob.theme);
-  const initialIsMobile = MOBILE_UA.test(request.headers.get('user-agent') ?? '');
+  const userAgent = request.headers.get('user-agent') ?? '';
+  const initialIsMobile = MOBILE_UA.test(userAgent);
+  // Which APK is asking, when the request came from the Android shell. Read
+  // HERE because the shell is rendered per request and the client's download
+  // button needs the answer before its first paint: a fetch after hydration
+  // would draw the button late, or draw it and then remove it.
+  //
+  // `isAndroid` is the wider fact and it exists for the INSTALL offer: a reader
+  // on Chrome or Brave for Android carries no shell token, and "not the app"
+  // alone cannot tell them from a desktop where an APK is useless.
+  const shellVersion = androidShellVersion(userAgent);
+  const isAndroid = isAndroidDevice(userAgent);
 
   const rendered = await renderShell();
   if (!rendered.ok) return shellUnavailableResponse(rendered.reason);
@@ -165,7 +177,7 @@ export const ssrRoutes = new Elysia({ name: 'ssr' }).get('*', async ({ request }
   // questions: "this browser has a session" versus "there is a session to have".
   // A Kabmo running open answers `authenticated: true` for every visitor, so
   // the navbar cannot use it to decide whether a sign-out control applies.
-  const bootstrap = JSON.stringify({ initialIsMobile, authenticated, authEnabled: isAuthEnabled(), production: !DEV_ASSETS_ENABLED, appSettings: settings }).replace(/</g, '\\u003c');
+  const bootstrap = JSON.stringify({ initialIsMobile, shellVersion, isAndroid, authenticated, authEnabled: isAuthEnabled(), production: !DEV_ASSETS_ENABLED, appSettings: settings }).replace(/</g, '\\u003c');
   // The template's own `<meta name="theme-color">` is REWRITTEN, not joined by
   // a second tag: with both present Chrome reads the first one, so an appended
   // tag would leave a dark theme painting light browser chrome.

package/src/server/routes/fs/read.ts

@@ -95,12 +95,9 @@ export async function browseDirectories({ request }: LoaderFunctionArgs) {
   });
 }
 
-/**
- * Names never listed in the Files panel: dependency/build output and the git
- * object database. Skipped for being noise, not for being hidden — every other
- * entry is listed, dot-prefixed files and folders included.
- */
-
+// No name is filtered: `lib/fs/listing.ts` (shared with the realtime topic)
+// lists every entry, and git-ignored ones are dimmed rather than dropped.
+//
 // Lazy listing: return only the immediate children of a directory. Folders are
 // emitted with `children: null` meaning "not loaded yet" so the client can
 // fetch them on demand — directories are NOT recursed here (keeps the initial
@@ -143,8 +140,26 @@ export async function listDirectory({ request }: LoaderFunctionArgs) {
 /** Hard cap on emitted files so a huge tree cannot stall the request. */
 const MAX_FILES = 3000;
 
-/** Directory names that are never recursed into. */
-const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.cache', 'coverage']);
+/**
+ * Directory names the RECURSIVE walk does not descend into.
+ *
+ * This is a budget guard, not the Files panel's noise table (there is none any
+ * more — `lib/fs/listing.ts` lists every entry). `/api/fs/list` returns a flat
+ * file index capped at `MAX_FILES` for the composer's `@` picker, and
+ * descending into a dependency tree spends that whole budget inside
+ * `node_modules` — leaving the picker with no project file in it. The tree
+ * panel is unaffected: it lists lazily, one directory per request, so a folder
+ * is only walked when someone expands it.
+ */
+const SKIP_DIRS: Record<string, true> = {
+  node_modules: true,
+  '.git': true,
+  dist: true,
+  build: true,
+  '.next': true,
+  '.cache': true,
+  coverage: true,
+};
 
 interface ListFileEntry {
   name: string;
@@ -172,7 +187,7 @@ async function walk(dir: string, baseDir: string, out: ListFileEntry[]): Promise
     if (entry.name.startsWith('.')) continue;
 
     if (entry.isDirectory()) {
-      if (SKIP_DIRS.has(entry.name)) continue;
+      if (SKIP_DIRS[entry.name]) continue;
       await walk(path.join(dir, entry.name), baseDir, out);
       continue;
     }

package/src/server/routes/sessions/batch-delete.test.ts

@@ -29,6 +29,13 @@ const AGENT_DIR = path.join(os.tmpdir(), `omc-batch-delete-${process.pid}`, 'age
 let priorAgentDir: string | undefined;
 
 beforeAll(() => {
+  // This suite reaches the database: `removeSession` → `purgeSessionData`
+  // resolves `getDb()`. Without isolating, it inherits whatever handle an
+  // earlier file left on the process-wide slot — and when that handle points at
+  // a temp directory its owner already deleted, SQLite answers `disk I/O error`
+  // and the verdict loses its code (measured on CI: `not_found` came back
+  // `undefined` while the same file passed alone).
+  isolateDb();
   fs.rmSync(AGENT_DIR, { recursive: true, force: true });
   fs.mkdirSync(path.join(AGENT_DIR, 'sessions'), { recursive: true });
   priorAgentDir = Bun.env.PI_CODING_AGENT_DIR;
@@ -41,6 +48,7 @@ afterAll(() => {
   if (priorAgentDir === undefined) delete Bun.env.PI_CODING_AGENT_DIR;
   else Bun.env.PI_CODING_AGENT_DIR = priorAgentDir;
   fs.rmSync(path.dirname(AGENT_DIR), { recursive: true, force: true });
+  releaseDb();
 });
 
 function post(body: unknown, url: string): Promise<Response> {
@@ -124,16 +132,11 @@ describe('batchDeleteFolders request shape', () => {
   });
 
   test('an unknown workspace is refused per id', async () => {
-    isolateDb();
-    try {
-      const res = await postFolder({ ids: ['424242'] });
-      expect(res.status).toBe(200);
-      const body = await res.json() as { success: boolean; removed: string[]; refused: { code?: string }[] };
-      expect(body.success).toBe(false);
-      expect(body.removed).toEqual([]);
-      expect(body.refused[0].code).toBe('not_found');
-    } finally {
-      releaseDb();
-    }
+    const res = await postFolder({ ids: ['424242'] });
+    expect(res.status).toBe(200);
+    const body = await res.json() as { success: boolean; removed: string[]; refused: { code?: string }[] };
+    expect(body.success).toBe(false);
+    expect(body.removed).toEqual([]);
+    expect(body.refused[0].code).toBe('not_found');
   });
 });

package/src/server/routes/updates/android.ts

@@ -0,0 +1,22 @@
+import { json, NO_STORE_HEADERS } from '@/server/lib/remix-compat';
+import { fetchAndroidRelease, type AndroidRelease } from '@/server/lib/updates/android-release';
+
+/**
+ * GET /api/updates/android — the newest APK a visitor can download.
+ *
+ * Its own route rather than a field on `/api/updates/check`: that one answers for
+ * the INSTALLED server (npm), this one answers for a different product (the
+ * Android shell), and folding them would make one probe's failure look like the
+ * other's. The client asks for it only when the sidebar renders, so a console
+ * that never shows the button never pays for the read.
+ *
+ * A failed probe is a valid answer (`url: null`), never a 500: the sidebar's job
+ * is to omit a button it cannot back with a link.
+ */
+export async function loader() {
+  const release: AndroidRelease | null = await fetchAndroidRelease();
+  return json(
+    release ?? { url: null, latest: null, releaseUrl: null },
+    { headers: NO_STORE_HEADERS },
+  );
+}

package/src/server/routes/updates/index.ts

@@ -1,9 +1,11 @@
 import { bindingsFor, type HandlerBinding } from '@/server/lib/route-adapter';
+import * as updatesAndroid from '@/server/routes/updates/android';
 import * as updatesApply from '@/server/routes/updates/apply';
 import * as updatesChangelog from '@/server/routes/updates/changelog';
 import * as updatesCheck from '@/server/routes/updates/check';
 
 export const updatesBindings: HandlerBinding[] = [
+  ...bindingsFor(updatesAndroid, '/api/updates/android'),
   ...bindingsFor(updatesApply, '/api/updates/apply'),
   ...bindingsFor(updatesChangelog, '/api/updates/changelog'),
   ...bindingsFor(updatesCheck, '/api/updates/check'),

package/src/shared/lib/updates/shell-ua.test.ts

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { androidShellVersion, isAndroidDevice, SHELL_UA_PREFIX } from '@/shared/lib/updates/shell-ua';
+
+/**
+ * The token is the only signal that a page is running inside the Android app,
+ * and it decides whether a download button appears. Two failure modes matter:
+ * a browser mistaken for the app (a button in a place it does not belong) and a
+ * malformed token read as a version (a comparison against `''`).
+ */
+describe('androidShellVersion', () => {
+  test('reads the version from a real WebView UA', () => {
+    const ua =
+      'Mozilla/5.0 (Linux; Android 15; Pixel 6 Build/AP4A; wv) AppleWebKit/537.36 (KHTML, like Gecko) '
+      + `Version/4.0 Chrome/124.0.6367.219 Mobile Safari/537.36 ${SHELL_UA_PREFIX}0.1.0`;
+    expect(androidShellVersion(ua)).toBe('0.1.0');
+  });
+
+  test('is null for a plain browser', () => {
+    expect(androidShellVersion('Mozilla/5.0 (Macintosh) AppleWebKit/537.36 Chrome/124.0 Safari/537.36')).toBeNull();
+    expect(androidShellVersion('')).toBeNull();
+    expect(androidShellVersion(null)).toBeNull();
+    expect(androidShellVersion(undefined)).toBeNull();
+  });
+
+  test('is null when the token carries no usable version', () => {
+    // A forged or truncated token must not read as version '' — that would make
+    // `isNewer(latest, '')` true for every release and show a button always.
+    expect(androidShellVersion('Mozilla/5.0 KabmoAndroid/')).toBeNull();
+    expect(androidShellVersion('Mozilla/5.0 KabmoAndroid/abc')).toBeNull();
+    expect(androidShellVersion('Mozilla/5.0 KabmoAndroid/1.x.3')).toBeNull();
+  });
+
+  test('accepts one-, two- and three-part versions and a prerelease', () => {
+    expect(androidShellVersion('KabmoAndroid/1')).toBe('1');
+    expect(androidShellVersion('KabmoAndroid/1.2')).toBe('1.2');
+    expect(androidShellVersion('KabmoAndroid/1.2.3')).toBe('1.2.3');
+    expect(androidShellVersion('KabmoAndroid/1.2.3-beta.1')).toBe('1.2.3-beta.1');
+  });
+
+  test('takes the first token when the UA was crafted twice', () => {
+    expect(androidShellVersion('KabmoAndroid/1.0.0 KabmoAndroid/9.9.9')).toBe('1.0.0');
+  });
+
+  test('does not match a lookalike token', () => {
+    expect(androidShellVersion('KabmoAndroidX/1.0.0')).toBeNull();
+    expect(androidShellVersion('Mozilla KabmoAndroid')).toBeNull();
+  });
+});
+
+/**
+ * The wider fact, and the one the INSTALL offer rests on: a reader on Chrome or
+ * Brave for Android carries no shell token, so "not the app" alone cannot tell
+ * them from a desktop where an APK is useless.
+ *
+ * The two failure modes are a device wrongly included (a button offering an
+ * install to a machine that cannot install it) and a real Android device wrongly
+ * excluded (the offer never appears where it was the point).
+ */
+describe('isAndroidDevice', () => {
+  test('recognises the real Android browsers', () => {
+    // The three the report names, plus Firefox — the platform token is the same.
+    expect(
+      isAndroidDevice(
+        'Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36',
+      ),
+    ).toBe(true);
+    expect(
+      isAndroidDevice(
+        'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36 Brave/124',
+      ),
+    ).toBe(true);
+    expect(isAndroidDevice('Mozilla/5.0 (Android 14; Mobile; rv:126.0) Gecko/126.0 Firefox/126.0')).toBe(true);
+  });
+
+  test('recognises the shell itself, which also sends the platform token', () => {
+    expect(
+      isAndroidDevice(
+        `Mozilla/5.0 (Linux; Android 15; Pixel 6 Build/AP4A; wv) AppleWebKit/537.36 (KHTML, like Gecko) `
+        + `Version/4.0 Chrome/124.0.6367.219 Mobile Safari/537.36 ${SHELL_UA_PREFIX}0.3.0`,
+      ),
+    ).toBe(true);
+  });
+
+  test('recognises an Android tablet, which sends no Mobile token', () => {
+    // The reason this matches `Android` and not `Mobile`: a tablet is a device
+    // the APK installs on, and it is the case a `Mobile` test would drop.
+    expect(
+      isAndroidDevice(
+        'Mozilla/5.0 (Linux; Android 13; SM-X700) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
+      ),
+    ).toBe(true);
+  });
+
+  test('excludes every platform the APK cannot install on', () => {
+    expect(isAndroidDevice('Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 Chrome/124.0 Safari/537.36')).toBe(false);
+    expect(isAndroidDevice('Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/124.0 Safari/537.36')).toBe(false);
+    expect(isAndroidDevice('Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/124.0 Safari/537.36')).toBe(false);
+    // An iPad sends `Mobile` and has no APK to install — the token this
+    // deliberately does NOT match.
+    expect(isAndroidDevice('Mozilla/5.0 (iPad; CPU OS 17_4 like Mac OS X) AppleWebKit/605.1.15 Version/17.4 Mobile/15E148 Safari/604.1')).toBe(false);
+    expect(isAndroidDevice('Mozilla/5.0 (iPhone; CPU iPhone OS 17_4 like Mac OS X) AppleWebKit/605.1.15 Mobile/15E148 Safari/604.1')).toBe(false);
+  });
+
+  test('is false for an empty or missing UA', () => {
+    expect(isAndroidDevice('')).toBe(false);
+    expect(isAndroidDevice(null)).toBe(false);
+    expect(isAndroidDevice(undefined)).toBe(false);
+  });
+
+  test('does not match a lookalike word', () => {
+    // `` is what stops a crafted or unrelated token from counting.
+    expect(isAndroidDevice('Mozilla/5.0 (compatible; NotAndroidBot/1.0)')).toBe(false);
+    expect(isAndroidDevice('Mozilla/5.0 AndroidX/1.0')).toBe(false);
+  });
+});

package/src/shared/lib/updates/shell-ua.ts

@@ -0,0 +1,56 @@
+/**
+ * The `KabmoAndroid/<version>` token in a request's User-Agent.
+ *
+ * The APK appends it (`KabmoWebView.configure`), and it is the console's only
+ * signal for two questions at once: "am I running inside the Android app" and
+ * "which build of it". The UA is the right channel because it crosses the very
+ * request that renders the shell, so the answer needs no bridge, no extra
+ * endpoint, and no round trip — the page is served already knowing.
+ *
+ * Parsed leniently and defensively: a browser can be made to send any UA, so a
+ * forged token buys nothing here (the value only decides whether to show a
+ * download button), and a malformed one must read as "not the app" rather than
+ * as version `''`.
+ */
+
+/** The token's name, before the slash. */
+export const SHELL_UA_PREFIX = 'KabmoAndroid/';
+
+/**
+ * Whether this request came from an Android device at all — the app or a
+ * browser on it.
+ *
+ * The download button has two reasons to appear and they are different offers:
+ * an installed APK that is behind (an UPDATE), and a reader using Chrome or
+ * Brave on a phone who may not know a native shell exists (an INSTALL). The
+ * second one needs this fact, which the shell token cannot supply: a browser
+ * carries no `KabmoAndroid/` token, and "no token" alone means "not the app" on
+ * every platform, including a desktop where an APK is useless.
+ *
+ * Matched on `Android`, the platform token every Android browser sends, and NOT
+ * on `Mobile`: an iPad sends `Mobile` and cannot install an APK, while an
+ * Android tablet sends `Android` without it.
+ */
+export function isAndroidDevice(userAgent: string | null | undefined): boolean {
+  if (!userAgent) return false;
+  return /\bAndroid\b/.test(userAgent);
+}
+
+/**
+ * The APK version that sent this request, or null when it is not the app.
+ *
+ * The FIRST matching token wins: the suffix is appended once, and a duplicate
+ * would mean something else crafted the string.
+ */
+export function androidShellVersion(userAgent: string | null | undefined): string | null {
+  if (!userAgent) return null;
+
+  for (const token of userAgent.split(/\s+/)) {
+    if (!token.startsWith(SHELL_UA_PREFIX)) continue;
+    const version = token.slice(SHELL_UA_PREFIX.length);
+    // A version, not an arbitrary string: `1`, `1.2`, `1.2.3`, optionally with a
+    // prerelease suffix. Anything else is a token this parser does not own.
+    if (/^\d+(\.\d+){0,2}(-[0-9A-Za-z.-]+)?$/.test(version)) return version;
+  }
+  return null;
+}

package/src/shared/lib/workspace/session-state/listeners.ts

@@ -21,6 +21,19 @@
 /** Listeners per session, then per slot (`ALL_SLOTS` = every slot of it). */
 const listeners = new Map<string, Map<string, Set<() => void>>>();
 
+/**
+ * Listeners for a session's blob being REPLACED wholesale (a fetch landing, a
+ * spawn-adoption migrate, a delete) — not for one slot being written.
+ *
+ * Separate from the per-slot bus because the two mean different things to a
+ * private copy. `useSessionState` hands every caller its own `useState`, which
+ * deliberately does not follow another component's writes to the same key; but
+ * a replacement invalidates the copy outright (the store now holds different
+ * state for the whole session), so a reader must re-read or it keeps rendering
+ * a stale — often fallback — value forever.
+ */
+const replacedListeners = new Map<string, Set<() => void>>();
+
 /** Bucket name for a listener that follows every slot of a session. */
 const ALL_SLOTS = '*';
 
@@ -57,6 +70,31 @@ function notifyBucket(bucket: Set<() => void> | undefined): void {
   for (const listener of [...bucket]) listener();
 }
 
+/**
+ * Listen for this session's blob being replaced wholesale. Returns the
+ * unsubscribe.
+ */
+export function subscribeSessionReplaced(sessionId: string | null, listener: () => void): () => void {
+  if (!sessionId) return () => {};
+  let bucket = replacedListeners.get(sessionId);
+  if (!bucket) {
+    bucket = new Set();
+    replacedListeners.set(sessionId, bucket);
+  }
+  bucket.add(listener);
+  return () => {
+    bucket.delete(listener);
+    if (bucket.size === 0) replacedListeners.delete(sessionId);
+  };
+}
+
+/** Announce that this session's whole blob changed under its readers. */
+export function notifySessionReplaced(sessionId: string): void {
+  const bucket = replacedListeners.get(sessionId);
+  if (!bucket) return;
+  for (const listener of [...bucket]) listener();
+}
+
 /** Fire the listeners of one slot, or of every slot when `key` is omitted. */
 export function notifySessionKey(sessionId: string, key?: string): void {
   const slots = listeners.get(sessionId);