@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/server/lib/lifecycle/probe.test.ts

@@ -4,64 +4,34 @@
  */
 
 /**
- * `probe.ts` answers two questions a starting server depends on: "can I bind
- * this address" and "is a Kabmo server answering here". Getting either
- * wrong is expensive — a false "free" turns into an EADDRINUSE after the
- * server has already announced itself, and a false "occupied" blocks startup
- * on a port nobody holds — so the tests drive real listeners on ephemeral
- * ports (never a fixed one) and real HTTP stubs, and pin the address
- * translation rules that decide which address is asked about in the first
- * place.
+ * The ADDRESS RULES `probe.ts` applies before it asks anything: which address a
+ * bind host stands for, and whether that address can be bound.
+ *
+ * Getting either wrong is expensive — a false "free" turns into an EADDRINUSE
+ * after the server has already announced itself, and a false "occupied" blocks
+ * startup on a port nobody holds — so the cases drive real listeners on
+ * OS-assigned ports and pin the translation that decides which address is asked
+ * about in the first place. The health half of the module is `probe-health`.
  */
 
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import type { Server } from 'bun';
+import { afterAll, describe, expect, test } from 'bun:test';
 
-import { fetchHealth, isLoopbackHost, isPortAvailable, probeHost, waitForPortFree } from '@/server/lib/lifecycle/probe';
+import {
+  connectAddresses,
+  isLoopbackHost,
+  isPortAvailable,
+  probeAddresses,
+  probeHost,
+  unavailableAddresses,
+  waitForPortFree,
+} from '@/server/lib/lifecycle/probe';
+import { createLoopbackHarness, ipv6Loopback } from '@/test-support/loopback';
 
-const servers: Server<undefined>[] = [];
+const harness = createLoopbackHarness();
+const { occupy, occupyAt, freePort, freePortBothFamilies } = harness;
 
-/** A live listener on an OS-assigned port; the port number is the test's. The
- *  pair shape keeps `server.port` (`number | undefined` in Bun's types) out
- *  of every call site. */
-function occupy(fetch: (request: Request) => Response | Promise<Response>, hostname = '127.0.0.1'): { server: Server<undefined>; port: number } {
-  const server = Bun.serve({ port: 0, hostname, fetch }) as Server<undefined>;
-  const port = server.port;
-  if (port === undefined) throw new Error('the OS did not assign an ephemeral port');
-  servers.push(server);
-  return { server, port };
-}
-
-/**
- * A port that nothing holds: take one from the OS, give it back, and wait for
- * the release to actually land — Bun closes a stopped listener's socket on a
- * later event-loop turn, so an immediate check would be a race, not a test.
- */
-async function freePort(): Promise<number> {
-  const held = occupy(() => new Response('unused'));
-  held.server.stop(true);
-  servers.splice(servers.indexOf(held.server), 1);
-  if (!(await waitForPortFree(held.port, '127.0.0.1', 2_000, 25))) {
-    throw new Error(`ephemeral port ${held.port} never became free`);
-  }
-  return held.port;
-}
-
-/**
- * The runner's own fetch, captured before any test runs. Another file in the
- * same `bun test` process may have left a stub installed on the global, and
- * every case here talks to a REAL listener it just started on loopback — so
- * the global is put back before each one rather than trusting the ambient one.
- */
-/** The runner's own fetch, reached through `Bun` so a stub leaked onto the global cannot be mistaken for it. */
-const realFetch = Bun.fetch;
-
-beforeEach(() => {
-  globalThis.fetch = realFetch;
-});
-
-afterEach(() => {
-  for (const server of servers.splice(0)) server.stop(true);
+afterAll(async () => {
+  await harness.dispose();
 });
 
 describe('probeHost', () => {
@@ -82,6 +52,31 @@ describe('probeHost', () => {
   });
 });
 
+describe('probeAddresses', () => {
+  test('a loopback name is every loopback family, because a bind picks one', () => {
+    // Measured: `Bun.serve({ hostname: 'localhost' })` listens on `[::1]` alone.
+    // Asking only about that family is how a stale instance kept `127.0.0.1`
+    // while the newcomer's own log reported the port free.
+    expect(probeAddresses('localhost')).toEqual(['127.0.0.1', '::1']);
+    expect(probeAddresses('LOCALHOST')).toEqual(['127.0.0.1', '::1']);
+    expect(probeAddresses(undefined)).toEqual(['127.0.0.1', '::1']);
+    expect(probeAddresses('  ')).toEqual(['127.0.0.1', '::1']);
+  });
+
+  test('a literal address is one address', () => {
+    expect(probeAddresses('127.0.0.1')).toEqual(['127.0.0.1']);
+    expect(probeAddresses('0.0.0.0')).toEqual(['0.0.0.0']);
+    expect(probeAddresses('192.168.1.4')).toEqual(['192.168.1.4']);
+  });
+
+  test('connect addresses translate a bind-any address, and keep the rest', () => {
+    expect(connectAddresses('0.0.0.0')).toEqual(['127.0.0.1']);
+    expect(connectAddresses('::')).toEqual(['127.0.0.1']);
+    expect(connectAddresses('localhost')).toEqual(['127.0.0.1', '::1']);
+    expect(connectAddresses('192.168.1.4')).toEqual(['192.168.1.4']);
+  });
+});
+
 describe('isLoopbackHost', () => {
   test('treats an unset address as private', () => {
     expect(isLoopbackHost(undefined)).toBe(true);
@@ -122,7 +117,6 @@ describe('isPortAvailable', () => {
     expect(await isPortAvailable(heldPort, '127.0.0.1')).toBe(false);
 
     held.stop(true);
-    servers.splice(servers.indexOf(held), 1);
     // An ephemeral port is released once the listener closes; the poll is what
     // callers use to wait for exactly that.
     expect(await waitForPortFree(heldPort, '127.0.0.1', 2_000, 25)).toBe(true);
@@ -140,12 +134,10 @@ describe('isPortAvailable', () => {
     // Linux refuses it (reads busy). Neither is pinned — both are honest
     // answers about the address asked for.
     loopback.server.stop(true);
-    servers.splice(servers.indexOf(loopback.server), 1);
 
     const wildcard = occupy(() => new Response('held'), '0.0.0.0');
     expect(await isPortAvailable(wildcard.port, '0.0.0.0')).toBe(false);
     wildcard.server.stop(true);
-    servers.splice(servers.indexOf(wildcard.server), 1);
 
     // The listener that held the port is gone, so the same question flips.
     expect(await waitForPortFree(loopback.port, '127.0.0.1', 2_000, 25)).toBe(true);
@@ -157,6 +149,35 @@ describe('isPortAvailable', () => {
     expect(await isPortAvailable(-1, '127.0.0.1')).toBe(false);
     expect(await isPortAvailable(Number.NaN, '127.0.0.1')).toBe(false);
   });
+
+  test.skipIf(!ipv6Loopback)('a name is busy when only ONE of its addresses is held', async () => {
+    // The reported failure, reduced: a stale instance holds `127.0.0.1:3000`,
+    // `bun run dev` binds `localhost` (i.e. `::1`) and finds that family free.
+    // Both servers then serve "port 3000" and the browser lands on whichever
+    // family it resolves — the stale one, in a different data mode.
+    const shared = await freePortBothFamilies();
+    const stale = occupyAt(shared, '127.0.0.1');
+    expect(await isPortAvailable(shared, 'localhost')).toBe(false);
+    expect(await unavailableAddresses(shared, 'localhost')).toEqual(['127.0.0.1']);
+    stale.stop(true);
+    expect(await waitForPortFree(shared, 'localhost', 2_000, 25)).toBe(true);
+
+    // The other family alone is just as busy.
+    const other = await freePortBothFamilies();
+    const v6 = occupyAt(other, '::1');
+    expect(await isPortAvailable(other, 'localhost')).toBe(false);
+    expect(await unavailableAddresses(other, 'localhost')).toEqual(['::1']);
+    v6.stop(true);
+  });
+
+  test('reports the address that is held, and none when the port is free', async () => {
+    const free = await freePort();
+    expect(await unavailableAddresses(free, '127.0.0.1')).toEqual([]);
+    expect(await unavailableAddresses(free, 'localhost')).toEqual([]);
+
+    const held = occupy(() => new Response('held'));
+    expect(await unavailableAddresses(held.port, '127.0.0.1')).toEqual(['127.0.0.1']);
+  });
 });
 
 describe('waitForPortFree', () => {
@@ -169,111 +190,3 @@ describe('waitForPortFree', () => {
     expect(await waitForPortFree(held.port, '127.0.0.1', 0)).toBe(false);
   });
 });
-
-describe('fetchHealth', () => {
-  test('returns the payload of a Kabmo listener, keeping only known fields', async () => {
-    const full = occupy(() => Response.json({
-      service: 'kabmo',
-      pid: 4242,
-      version: '3.10.1',
-      startedAt: '2026-01-01T00:00:00.000Z',
-      uptime: 12.5,
-      mock: false,
-      runtime: 'bun',
-      mode: 'dev',
-      port: 1234,
-      host: '127.0.0.1',
-      tls: false,
-      tray: true,
-      authEnabled: true,
-      fds: { open: 3352, highest: 3351, limit: 61_440, nearCliff: false },
-      extra: 'dropped',
-    }));
-
-    const health = await fetchHealth(full.port, '127.0.0.1', 1000, false);
-
-    expect(health).toEqual({
-      service: 'kabmo',
-      pid: 4242,
-      version: '3.10.1',
-      startedAt: '2026-01-01T00:00:00.000Z',
-      uptime: 12.5,
-      mock: false,
-      runtime: 'bun',
-      mode: 'dev',
-      port: 1234,
-      host: '127.0.0.1',
-      tls: false,
-      tray: true,
-      authEnabled: true,
-      // Carried, not dropped: `status` prints this as its warning line, and
-      // whitelisting it away left the report without one.
-      fds: { open: 3352, highest: 3351, limit: 61_440, nearCliff: false },
-    });
-  });
-
-  test('reports a malformed fds field as null rather than a half-trusted object', async () => {
-    const partial = occupy(() => Response.json({
-      service: 'kabmo',
-      fds: { open: 1, highest: 1, limit: 2 },
-    }));
-
-    const health = await fetchHealth(partial.port, '127.0.0.1', 1000, false);
-
-    expect(health?.service).toBe('kabmo');
-    expect(health?.fds).toBeNull();
-  });
-
-  test('drops fields whose type is wrong rather than passing them on', async () => {
-    const mistyped = occupy(() => Response.json({ service: 'kabmo', pid: '4242', version: 7, tls: 'yes' }));
-
-    const health = await fetchHealth(mistyped.port, '127.0.0.1', 1000, false);
-
-    expect(health?.service).toBe('kabmo');
-    expect(health?.pid).toBeUndefined();
-    expect(health?.version).toBeUndefined();
-    expect(health?.tls).toBeUndefined();
-  });
-
-  test('recognizes a pre-rename listener, and reports it under the current name', async () => {
-    // A server started before the rename is still running the old build: its
-    // health payload says `ompchamber`, and `status`/`stop` must still find it.
-    const legacy = occupy(() => Response.json({ service: 'ompchamber', pid: 4242, port: 3000 }));
-
-    const health = await fetchHealth(legacy.port, '127.0.0.1', 1000, false);
-
-    expect(health?.service).toBe('kabmo');
-    expect(health?.pid).toBe(4242);
-  });
-
-  test('ignores a listener that is not Kabmo', async () => {
-    const foreign = occupy(() => Response.json({ service: 'something-else', pid: process.pid }));
-    expect(await fetchHealth(foreign.port, '127.0.0.1', 1000, false)).toBeNull();
-  });
-
-  test('ignores error responses, non-JSON bodies, and non-objects', async () => {
-    const broken = occupy(() => new Response('nope', { status: 500 }));
-    expect(await fetchHealth(broken.port, '127.0.0.1', 1000, false)).toBeNull();
-
-    const html = occupy(() => new Response('<html>not json</html>', { headers: { 'content-type': 'text/html' } }));
-    expect(await fetchHealth(html.port, '127.0.0.1', 1000, false)).toBeNull();
-
-    const list = occupy(() => Response.json([{ service: 'kabmo' }]));
-    expect(await fetchHealth(list.port, '127.0.0.1', 1000, false)).toBeNull();
-  });
-
-  test('returns null for a port nobody listens on, and for a bad port', async () => {
-    expect(await fetchHealth(await freePort(), '127.0.0.1', 500)).toBeNull();
-    expect(await fetchHealth(0, '127.0.0.1', 500)).toBeNull();
-    expect(await fetchHealth(Number.NaN, '127.0.0.1', 500)).toBeNull();
-  });
-
-  test('a plaintext listener is not found over TLS, and the mode decides the scheme', async () => {
-    const plain = occupy(() => Response.json({ service: 'kabmo', pid: process.pid }));
-
-    expect(await fetchHealth(plain.port, '127.0.0.1', 1000, true)).toBeNull();
-    expect(await fetchHealth(plain.port, '127.0.0.1', 1000, false)).not.toBeNull();
-    // 'auto' cannot know which scheme a live instance chose, so it tries both.
-    expect(await fetchHealth(plain.port, '127.0.0.1', 1000)).not.toBeNull();
-  });
-});

package/src/server/lib/lifecycle/probe.ts

@@ -69,27 +69,100 @@ export function isLoopbackHost(host?: string | null): boolean {
 }
 
 /**
- * True when `port` can still be bound on `host`.
+ * Addresses a bind to `host` can land on.
+ *
+ * A NAME is not one address, and that is the whole bug this function exists
+ * for. `localhost` resolves to both loopback families, while Bun binds only the
+ * one it resolves first — verified: `Bun.serve({ hostname: 'localhost' })`
+ * listens on `[::1]` alone. Asking about that family alone answers "is the
+ * socket I am about to open free", which is not the question a port guard
+ * exists to answer: the other address stays available to a second server, and a
+ * client that resolves THAT one reaches it. Measured on a real dev run against a
+ * stale instance on `127.0.0.1:3000`: both servers reported the port as theirs,
+ * the browser landed on the old build (a MOCK instance), and the newcomer's own
+ * log said the port was free.
  *
- * The probe binds *the same address the server will bind* — a wildcard server
- * is probed with a wildcard bind. Probing loopback instead would ask a
- * different question: `net` sets SO_REUSEADDR, so a loopback bind can succeed
- * while `0.0.0.0:<port>` is already taken, and the port would look free right
- * up until the real `listen` failed.
+ * A literal address and a bind-any address are one address by definition. An
+ * arbitrary hostname is deliberately left alone: its resolution belongs to the
+ * OS, a second lookup here could disagree with the one the bind will use, and
+ * only loopback is guaranteed multi-family on every host.
  */
-export async function isPortAvailable(port: number, host?: string | null): Promise<boolean> {
-  if (!Number.isFinite(port) || port <= 0) return false;
-  const bindHost = (host ?? '').trim() || 'localhost';
+export function probeAddresses(host?: string | null): string[] {
+  const value = (host ?? '').trim();
+  if (value.length === 0 || value.toLowerCase() === 'localhost') return ['127.0.0.1', '::1'];
+  return [value];
+}
+
+/**
+ * Addresses a health request should be sent to, for a bind host.
+ *
+ * The same list as `probeAddresses`, with bind-any addresses translated to the
+ * loopback that reaches them. Kept separate because the two questions differ:
+ * occupancy is asked with a BIND (so `0.0.0.0` is a legitimate address to bind)
+ * while identification is asked with a CONNECT (where `0.0.0.0` is not an
+ * address at all).
+ */
+export function connectAddresses(host?: string | null): string[] {
+  return probeAddresses(host).map(probeHost);
+}
+
+/**
+ * Bind failures that mean "this host has no such address", not "someone holds
+ * it": a kernel booted without IPv6 answers `EADDRNOTAVAIL` for `::1`, and
+ * reading that as occupied would refuse every start on that machine.
+ */
+const ABSENT_ADDRESS_CODES: Record<string, true> = {
+  EADDRNOTAVAIL: true,
+  EAFNOSUPPORT: true,
+};
+
+/** Whether one address can be bound. */
+async function bindable(port: number, host: string): Promise<boolean> {
   const { promise, resolve } = Promise.withResolvers<boolean>();
   const probe = net.createServer();
   probe.unref();
-  probe.once('error', () => resolve(false));
-  probe.listen({ port, host: bindHost }, () => {
+  probe.once('error', (error: NodeJS.ErrnoException) => {
+    resolve(ABSENT_ADDRESS_CODES[error.code ?? ''] === true);
+  });
+  probe.listen({ port, host }, () => {
     probe.close(() => resolve(true));
   });
   return await promise;
 }
 
+/**
+ * Every address of `host` where `port` is already taken; empty means free.
+ *
+ * The list rather than a boolean, because the guard's failure message has to
+ * name the address that is held — "port busy" on a name that resolves to two
+ * addresses does not say which one the user has to free.
+ */
+export async function unavailableAddresses(port: number, host?: string | null): Promise<string[]> {
+  if (!Number.isFinite(port) || port <= 0) return [];
+  const blocked: string[] = [];
+  for (const address of probeAddresses(host)) {
+    if (!(await bindable(port, address))) blocked.push(address);
+  }
+  return blocked;
+}
+
+/**
+ * True when `port` can still be bound on `host`.
+ *
+ * The probe binds *the same addresses the server will bind* — a wildcard server
+ * is probed with a wildcard bind, and a name is probed on every address it
+ * resolves to. Probing loopback instead of a wildcard would ask a different
+ * question: `net` sets SO_REUSEADDR, so a loopback bind can succeed while
+ * `0.0.0.0:<port>` is already taken, and the port would look free right up
+ * until the real `listen` failed. Probing one family of a name asks a narrower
+ * question still: whether *this* socket is free, when the answer that matters
+ * is whether the port is free for the name a browser will type.
+ */
+export async function isPortAvailable(port: number, host?: string | null): Promise<boolean> {
+  if (!Number.isFinite(port) || port <= 0) return false;
+  return (await unavailableAddresses(port, host)).length === 0;
+}
+
 /** Poll until the port can be bound, or the deadline passes. */
 export async function waitForPortFree(
   port: number,
@@ -136,6 +209,20 @@ export interface HealthPayload {
   fds?: FdPressure | null;
 }
 
+/**
+ * A host as a URL authority.
+ *
+ * An IPv6 literal has to be bracketed: `http://::1:3000/api/health` is not a
+ * URL, and the failure is a throw rather than a connection attempt — so asking
+ * `::1` without this reads as "nothing there", which is the same silent answer
+ * the multi-address probe exists to stop. `localhost` never reaches this branch
+ * (no colon), and an already-bracketed address is left alone.
+ */
+function urlAuthority(host: string): string {
+  if (host.startsWith('[') || !host.includes(':')) return host;
+  return `[${host}]`;
+}
+
 /**
  * One health request over `scheme`.
  *
@@ -152,7 +239,7 @@ async function probeHealthOver(
   timeoutMs: number,
 ): Promise<HealthPayload | null> {
   try {
-    const response = await fetch(`${scheme}://${host}:${port}/api/health`, {
+    const response = await fetch(`${scheme}://${urlAuthority(host)}:${port}/api/health`, {
       headers: { accept: 'application/json' },
       signal: AbortSignal.timeout(timeoutMs),
       ...(scheme === 'https' ? { tls: { rejectUnauthorized: false } } : {}),
@@ -194,6 +281,15 @@ async function probeHealthOver(
  * caller here is asking "is a Kabmo server on this port", so a foreign
  * HTTP service answers null rather than a half-trusted object.
  *
+ * A NAME is asked on every address it resolves to, concurrently, and the first
+ * answer wins. A single-address request is the false negative that made a live
+ * instance invisible to `status` and `stop`: `localhost` resolves to both
+ * loopback families, a server binds only one of them, and a request aimed at the
+ * other reaches nothing — so a MOCK instance holding `127.0.0.1:3000` answered
+ * no CLI command while the browser kept landing on it. Concurrent rather than
+ * sequential because a port nobody serves must not cost one timeout per family,
+ * and ECONNREFUSED on the family with no listener returns immediately.
+ *
  * `tls: 'auto'` (the default) tries HTTPS first, then HTTP. Discovery cannot
  * know which a live instance chose, and the two are mutually exclusive on a port,
  * so one wasted request is the cheapest way to be right. A caller that DOES know
@@ -206,7 +302,19 @@ export async function fetchHealth(
   tls: boolean | 'auto' = 'auto',
 ): Promise<HealthPayload | null> {
   if (!Number.isFinite(port) || port <= 0) return null;
-  const target = probeHost(host);
+  const answers = await Promise.all(
+    connectAddresses(host).map((target) => probeHealthOn(port, target, timeoutMs, tls)),
+  );
+  return answers.find((answer) => answer !== null) ?? null;
+}
+
+/** One address, in whichever scheme the caller allows. */
+async function probeHealthOn(
+  port: number,
+  target: string,
+  timeoutMs: number,
+  tls: boolean | 'auto',
+): Promise<HealthPayload | null> {
   if (tls === true) return probeHealthOver('https', port, target, timeoutMs);
   if (tls === false) return probeHealthOver('http', port, target, timeoutMs);
 

package/src/server/lib/omp/rpc/frame-fold-signals.test.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * What a completed tool call republishes, and — the load-bearing half — what it
+ * does NOT.
+ *
+ * The shipped shape republished the whole `sidebar` structure here: every
+ * folder and session, re-scanned from disk. Measured on the author's install,
+ * that is 216 KB over 731 sessions PER TOOL CALL, against 87 bytes for the
+ * activity entry it actually needed to carry, and it is what made a phone's
+ * stream feel slow. These cases pin the split:
+ *
+ *   - the activity signal fires per tool call;
+ *   - the STRUCTURE signal does not, because nothing about the LIST changed (a
+ *     new session's file is the watcher's `rename` event, a rename is
+ *     `session_info_update`, and the turn boundary is `settleTerminalRun`);
+ *   - the data signal still fires, because a tool result IS a transcript entry.
+ *
+ * Split from `frame-fold.test.ts` when the two together crossed the repo's
+ * per-file ceiling.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { foldSessionFrame, type SessionFrameHost } from '@/server/lib/omp/rpc/frame-fold';
+import { onRealtimeSignal } from '@/server/lib/realtime/signals.server';
+import { ModeMirror } from '@/server/lib/omp/rpc/mode-mirror';
+
+/** The same minimal host the sibling suite uses. */
+function makeHost(overrides: Partial<SessionFrameHost> = {}): SessionFrameHost {
+  return {
+    sessionId: '',
+    autoTitleWindowUntil: 0,
+    autoTitleClaims: 0,
+    autoTitleDispatch: null,
+    autoTitlePending: true,
+    autoTitleRequested: false,
+    promptRunning: false,
+    streaming: false,
+    compacting: false,
+    awaitingAgentStart: false,
+    awaitingAgentStartDeadline: 0,
+    continuationGraceUntil: 0,
+    proc: { sendCommand: async () => undefined as never },
+    emit() {},
+    trackUiDialog() {},
+    observeSubagent() {},
+    syncRunModel() {},
+    modeMirror: new ModeMirror(),
+    isAlive: () => true,
+    isBusy: () => false,
+    send: async () => undefined,
+    ...overrides,
+  };
+}
+
+/**
+ * The `tool_execution_end` frame is what moves a running session's sidebar row
+ * between turn boundaries — and it must move ONLY the two live fields.
+ *
+ * The shipped shape republished the whole `sidebar` structure here: every
+ * folder and session, re-scanned from disk. Measured on the author's install,
+ * that is 216 KB over 731 sessions PER TOOL CALL, against 87 bytes for the
+ * activity entry it actually needed to carry — and it is what made a phone's
+ * stream feel slow. The rules pinned below are the ones that make the smaller
+ * payload sufficient:
+ *
+ *   - the activity signal fires per tool call;
+ *   - the STRUCTURE signal does not, because nothing about the list changed (a
+ *     new session's file is the watcher's `rename` event, a rename is
+ *     `session_info_update`, and the turn boundary is `settleTerminalRun`);
+ *   - the data signal still fires, because a tool result IS a transcript entry.
+ */
+describe('tool_execution_end publishes activity, never the structure', () => {
+  test('raises the activity signal and leaves the structure alone', () => {
+    const seen: string[] = [];
+    const off = onRealtimeSignal((event) => seen.push(event.signal));
+    try {
+      const host = makeHost({ sessionId: 's1' });
+      foldSessionFrame(host, { type: 'tool_execution_end' });
+    } finally {
+      off();
+    }
+
+    expect(seen).toContain('sidebar-activity');
+    expect(seen).not.toContain('sidebar-structure');
+    // The transcript grew, so the session's data topics re-read.
+    expect(seen).toContain('session-data-dirty');
+    expect(seen).toContain('workspace-dirty');
+  });
+
+  test('still publishes the structure at the turn boundary', () => {
+    // The other half of the split: the final answer appends after the last tool
+    // call, and the run's own settle is where the list catches up. Asserted
+    // through the scan cache, which is the observable a structure publish
+    // leaves behind (`settleTerminalRun` calls the publisher directly rather
+    // than raising the signal).
+    globalThis.__kabmoSidebarDataCache = {
+      data: {} as never,
+      expiresAt: Date.now() + 60_000,
+      inFlight: null,
+    };
+
+    const host = makeHost({ sessionId: 's1' });
+    foldSessionFrame(host, { type: 'agent_end', isTerminal: true, messages: [] });
+
+    expect(globalThis.__kabmoSidebarDataCache?.expiresAt).toBe(0);
+  });
+});

package/src/server/lib/omp/rpc/frame-fold.ts

@@ -117,14 +117,19 @@ function handleMessageEnd(host: SessionFrameHost, event: AgentEvent): void {
  * pays nothing. The session's data topics (todos, telemetry, queue) stay
  * turn-boundary-only on purpose: their resolvers are the expensive ones
  * (whole-transcript parses/scans).
+ *
+ * The SIDEBAR's activity stamp moved too, and it is published on its own topic.
+ * It used to republish the whole structure here — every folder and session —
+ * and that is what made a phone's stream feel slow: measured 216 KB over 731
+ * sessions per tool call, against 87 bytes for the activity payload. Nothing
+ * about the LIST changes on a transcript append, so nothing about the list is
+ * republished: a new session's file is the watcher's `rename` event, a rename is
+ * `session_info_update`, and the turn boundary is `settleTerminalRun` — each
+ * already publishes the structure for its own reason.
  */
 function handleToolExecutionEnd(host: SessionFrameHost): void {
   emitRealtimeSignal('workspace-dirty');
-  // The transcript appended too — the sidebar's `updated_at` (its ordering and
-  // time-ago labels) is read off a scan that only re-runs on this signal, and
-  // the sessions watcher deliberately ignores transcript appends. The coalesce +
-  // dedupe above bound the cost the same way.
-  publishSidebarStructure();
+  emitRealtimeSignal('sidebar-activity');
   // The session's DATA moved as well: a tool result is a transcript entry, so
   // the raw-messages paged view and the session-data topics re-read. Their
   // resolvers are the expensive ones (whole-transcript parses), but the