@kabmo-labs/kabmo 0.1.0 → 0.2.0

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

@@ -0,0 +1,148 @@
+/**
+ * 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 the GitHub release asset, which means one
+ * unauthenticated REST read of the newest release.
+ *
+ * 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's APK.
+ *
+ * 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/latest`, {
+      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 {
+      html_url?: unknown;
+      assets?: unknown;
+    };
+    // A body that is not the release document is a failed probe, not an empty
+    // release: answering `{url: null, latest: null}` here would be
+    // indistinguishable from "a release with no APK", and the caller would cache
+    // that mistake for five minutes.
+    if (!Array.isArray(body.assets)) return cache.entry ?? null;
+
+    const assets = body.assets;
+    const asset = assets
+      .map((entry) => (entry && typeof entry === 'object' ? (entry as Record<string, unknown>) : null))
+      .find((entry) => entry && typeof entry.name === 'string' && versionFromAssetName(entry.name) !== null);
+
+    const name = typeof asset?.name === 'string' ? asset.name : '';
+    const url = typeof asset?.browser_download_url === 'string' ? asset.browser_download_url : null;
+    const release: AndroidRelease = {
+      url,
+      latest: versionFromAssetName(name),
+      releaseUrl: typeof body.html_url === 'string' ? body.html_url : null,
+    };
+
+    cache.entry = release;
+    cache.at = now;
+    return release;
+  } 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;
+  }
+}
+
+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 } 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,13 @@ 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.
+  const shellVersion = androidShellVersion(userAgent);
 
   const rendered = await renderShell();
   if (!rendered.ok) return shellUnavailableResponse(rendered.reason);
@@ -165,7 +172,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, 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,54 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { androidShellVersion, 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();
+  });
+});

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

@@ -0,0 +1,36 @@
+/**
+ * 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/';
+
+/**
+ * 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);

package/src/shared/lib/workspace/session-state/replacement.test.ts

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The store's WHOLESALE-REPLACEMENT notifications.
+ *
+ * `useSessionState` hands every caller a private copy that deliberately does
+ * not follow another component's per-slot write (a panel width is owned by one
+ * component). But the store also REPLACES a session's whole state — a blob
+ * landing, a hydrate, a spawn-adoption migrate, a delete — and there the copy's
+ * value was never written by anyone: it is the fallback the component read on
+ * the commit the session id changed. `ready` does not move across an adoption,
+ * so without this event every opened right-panel view collapsed at the first
+ * send of a new chat (measured: `true:git` → `true:files`).
+ *
+ * Split from `store.test.ts` for the per-file size ceiling.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+
+import { subscribeSessionReplaced } from '@/shared/lib/workspace/session-state/listeners';
+import {
+  clearSessionKey,
+  forgetSession,
+  getSessionValue,
+  hydrateSession,
+  loadSession,
+  migrateSessionState,
+  setSessionKey,
+} from '@/shared/lib/workspace/session-state/store';
+
+const originalWindow = Reflect.get(globalThis, 'window');
+/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
+const originalFetch = Bun.fetch;
+const touched: string[] = [];
+const unsubs: Array<() => void> = [];
+
+/** Register a session id so `afterEach` forgets it. */
+function use(id: string): string {
+  touched.push(id);
+  return id;
+}
+
+/** Follow wholesale blob replacements for a session, torn down with the rest. */
+function followReplaced(sessionId: string, listener: () => void): () => void {
+  const unsubscribe = subscribeSessionReplaced(sessionId, listener);
+  unsubs.push(unsubscribe);
+  return unsubscribe;
+}
+
+/** Count how many times a notification reaches a listener. */
+function counter(): { calls: number; listener: () => void } {
+  const state = { calls: 0, listener: () => { state.calls += 1; } };
+  return state;
+}
+
+afterEach(() => {
+  for (const unsubscribe of unsubs.splice(0)) unsubscribe();
+  for (const id of touched.splice(0)) forgetSession(id);
+  Reflect.set(globalThis, 'window', originalWindow);
+  Reflect.set(globalThis, 'fetch', originalFetch);
+});
+
+describe('session-state store: wholesale replacement notifications', () => {
+  test('migrateSessionState announces both ids as replaced', () => {
+    const from = use('new-replace');
+    const to = use('real-replace');
+    setSessionKey(from, 'layout.showRightPanel', true);
+    const fromProbe = counter();
+    const toProbe = counter();
+    followReplaced(from, fromProbe.listener);
+    followReplaced(to, toProbe.listener);
+
+    migrateSessionState(from, to);
+
+    expect(fromProbe.calls).toBe(1);
+    expect(toProbe.calls).toBe(1);
+    expect<boolean | undefined>(getSessionValue(to, 'layout.showRightPanel')).toBe(true);
+  });
+
+  test('a per-slot write is NOT a replacement', () => {
+    const id = use('slot-write');
+    const replaced = counter();
+    followReplaced(id, replaced.listener);
+
+    setSessionKey(id, 'layout.activeRightPanel', 'git');
+    clearSessionKey(id, 'layout.activeRightPanel');
+
+    // Only the wholesale paths (load/hydrate/migrate/forget) replace state;
+    // announcing a write here would make every editor and panel copy re-read
+    // on every keystroke elsewhere in the app.
+    expect(replaced.calls).toBe(0);
+  });
+
+  test('a blob landing, a hydrate and a delete all announce a replacement', async () => {
+    const id = use('replace-paths');
+    const probe = counter();
+    followReplaced(id, probe.listener);
+    Reflect.set(globalThis, 'window', {});
+    Reflect.set(globalThis, 'fetch', async () => ({ ok: true, json: async () => ({ state: { a: 1 } }) }));
+
+    await loadSession(id);
+    expect(probe.calls).toBe(1);
+
+    hydrateSession(id, { b: 2 });
+    expect(probe.calls).toBe(2);
+
+    forgetSession(id);
+    expect(probe.calls).toBe(3);
+  });
+
+  test('a subscriber on a null session id is never notified of a replacement', () => {
+    const probe = counter();
+    followReplaced(null as unknown as string, probe.listener);
+    const id = use('replace-null');
+    hydrateSession(id, { a: 1 });
+    expect(probe.calls).toBe(0);
+  });
+});

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

@@ -68,7 +68,7 @@
  * - chat.draftAttachments     attachment metadata array
  */
 
-import { notifySessionKey } from '@/shared/lib/workspace/session-state/listeners';
+import { notifySessionKey, notifySessionReplaced } from '@/shared/lib/workspace/session-state/listeners';
 
 type SessionState = Record<string, unknown>;
 
@@ -263,8 +263,10 @@ export async function loadSession(sessionId: string): Promise<void> {
   }
   evictIfNeeded(sessionId);
   // The blob replaces every slot at once, so a follower that read the store
-  // before it arrived (no pick yet) has to re-read.
+  // before it arrived (no pick yet) has to re-read — including a private copy
+  // held by `useSessionState`, which does not follow per-slot writes.
   notifySessionKey(sessionId);
+  notifySessionReplaced(sessionId);
 }
 
 /** Seed the cache synchronously (e.g. from SSR-provided data). */
@@ -274,6 +276,7 @@ export function hydrateSession(sessionId: string | null, state: SessionState): v
   touchCacheEntry(sessionId);
   evictIfNeeded(sessionId);
   notifySessionKey(sessionId);
+  notifySessionReplaced(sessionId);
 }
 
 /**
@@ -308,6 +311,7 @@ export function forgetSession(sessionId: string): void {
   dirtySessions.delete(sessionId);
   lastTouched.delete(sessionId);
   notifySessionKey(sessionId);
+  notifySessionReplaced(sessionId);
 }
 
 /**
@@ -327,4 +331,11 @@ export function migrateSessionState(fromId: string, toId: string): void {
   // The adopted slot gained the whole transient state; the transient one lost it.
   notifySessionKey(toId);
   notifySessionKey(fromId);
+  // Both entries were REPLACED, not written slot by slot. `ready` does not
+  // change across an adoption (it was already true for the pending id), so
+  // without this a private copy kept the fallback it read on the commit the
+  // URL moved — the reported "opening panels in a new chat and sending the
+  // first prompt closes them all".
+  notifySessionReplaced(toId);
+  notifySessionReplaced(fromId);
 }