@kabmo-labs/kabmo 0.0.1 → 0.2.0

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

@@ -0,0 +1,142 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The batch routes' request contract.
+ *
+ * These are pure request-shape checks and they must not reach the filesystem or
+ * spawn an omp child — which is half the point of asserting them: the batch
+ * verbs are reachable from a click, so a malformed body has to be refused
+ * before any id is resolved against the sessions root.
+ *
+ * The refusal half is the other point: a batch that names a pending `new-…`
+ * chat must answer a per-id verdict and still delete the rest, because the
+ * dialog reports counts rather than aborting.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { batchDeleteSessions } from '@/server/routes/sessions/batch-delete';
+import { batchDeleteFolders } from '@/server/routes/folders/batch-delete';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+
+const AGENT_DIR = path.join(os.tmpdir(), `omc-batch-delete-${process.pid}`, 'agent');
+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;
+  Bun.env.PI_CODING_AGENT_DIR = AGENT_DIR;
+  clearSessionFileCaches();
+});
+
+afterAll(() => {
+  clearSessionFileCaches();
+  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> {
+  return batchDeleteSessions({
+    request: new Request(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    }),
+    params: {},
+  } as never) as Promise<Response>;
+}
+
+function postFolder(body: unknown): Promise<Response> {
+  return batchDeleteFolders({
+    request: new Request('http://localhost/api/folders/batch-delete', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    }),
+    params: {},
+  } as never) as Promise<Response>;
+}
+
+describe('batchDeleteSessions request shape', () => {
+  test('a wrong verb is a 405', async () => {
+    const res = (await batchDeleteSessions({
+      request: new Request('http://localhost/api/sessions/batch-delete', { method: 'DELETE' }),
+      params: {},
+    } as never)) as Response;
+    expect(res.status).toBe(405);
+  });
+
+  test('a non-array ids field is a 400', async () => {
+    const res = await post({ ids: 'a' }, 'http://localhost/api/sessions/batch-delete');
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ error: 'ids must be an array of session ids' });
+  });
+
+  test('an empty selection is a 400 rather than a no-op success', async () => {
+    const res = await post({ ids: [] }, 'http://localhost/api/sessions/batch-delete');
+    expect(res.status).toBe(400);
+  });
+
+  test('an over-long selection is refused', async () => {
+    const ids = Array.from({ length: 501 }, (_, index) => `s-${index}`);
+    const res = await post({ ids }, 'http://localhost/api/sessions/batch-delete');
+    expect(res.status).toBe(400);
+  });
+
+  test('a pending chat is refused per id while the rest still runs', async () => {
+    // No files exist, so the real id answers not_found — the point is that the
+    // pending one is refused by its OWN rule and the batch continues.
+    const res = await post(
+      { ids: ['new-1758800000000', '00000000-0000-0000-0000-000000000000'] },
+      'http://localhost/api/sessions/batch-delete',
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as { success: boolean; removed: string[]; refused: { id: string; code?: string }[] };
+    expect(body.success).toBe(false);
+    expect(body.removed).toEqual([]);
+    expect(body.refused.map((entry) => entry.id)).toEqual([
+      'new-1758800000000',
+      '00000000-0000-0000-0000-000000000000',
+    ]);
+    expect(body.refused[0].code).toBe('session_pending');
+    expect(body.refused[1].code).toBe('not_found');
+  });
+
+  test('a traversal id is refused without touching the tree', async () => {
+    const res = await post({ ids: ['..'] }, 'http://localhost/api/sessions/batch-delete');
+    const body = await res.json() as { refused: { code?: string }[] };
+    expect(body.refused[0].code).toBe('invalid_id');
+  });
+});
+
+describe('batchDeleteFolders request shape', () => {
+  test('a non-array ids field is a 400', async () => {
+    const res = await postFolder({ ids: 1 });
+    expect(res.status).toBe(400);
+  });
+
+  test('an unknown workspace is refused per id', async () => {
+    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/sessions/batch-delete.ts

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * POST /api/sessions/batch-delete — remove several sessions in one request.
+ *
+ * The sidebar's batch mode is one user action over N rows, so it is one request:
+ * a client loop would pay N round trips and republish the sidebar N times, and
+ * the confirmation dialog would have to reassemble N answers into one summary.
+ *
+ * Each id goes through the SAME sequence as the single DELETE
+ * (`removeSession`), and a refusal is a verdict rather than an abort: a batch
+ * that contained one mid-run session must still delete the other nineteen, and
+ * the caller is told exactly which ids were refused and why. `removed` is what
+ * the dialog counts; `refused` is what it lists.
+ */
+
+import { json } from '@/server/lib/remix-compat';
+import type { ActionFunctionArgs } from '@/server/lib/remix-compat';
+import { methodNotAllowed, parseJsonBody } from '@/server/lib/route-adapter';
+import { removeSession } from '@/server/lib/omp/session/delete-flow.server';
+
+/** One request cannot carry an unbounded selection. */
+const MAX_BATCH = 500;
+
+export async function batchDeleteSessions({ request }: ActionFunctionArgs) {
+  if (request.method !== 'POST') {
+    return methodNotAllowed({ request, params: {} });
+  }
+
+  const parsed = await parseJsonBody<{ ids?: unknown }>(request);
+  if (!parsed.ok) return json({ error: 'Invalid JSON body' }, { status: 400 });
+
+  const raw = parsed.body.ids;
+  if (!Array.isArray(raw) || raw.some((id) => typeof id !== 'string' || id.length === 0)) {
+    return json({ error: 'ids must be an array of session ids' }, { status: 400 });
+  }
+  const ids = [...new Set(raw as string[])];
+  if (ids.length === 0) return json({ error: 'No sessions selected' }, { status: 400 });
+  if (ids.length > MAX_BATCH) {
+    return json({ error: `At most ${MAX_BATCH} sessions can be deleted at once.` }, { status: 400 });
+  }
+
+  const removed: string[] = [];
+  const refused: { id: string; error: string; code?: string }[] = [];
+
+  // Sequential, deliberately: every removal may have to destroy an omp child
+  // and wait for its exit, and running those in parallel would open one
+  // transcript writer per session at once for no gain — the work is dominated
+  // by process teardown, not by the filesystem.
+  for (const id of ids) {
+    const result = await removeSession(id);
+    if (result.ok) removed.push(id);
+    else refused.push({ id, error: result.error ?? 'Could not delete the session.', code: result.code });
+  }
+
+  return json({ success: refused.length === 0, removed, refused });
+}

package/src/server/routes/sessions/delete.ts

@@ -9,26 +9,15 @@
  * transcript, this one is the destructive path the user opts into from the
  * sidebar's trash button.
  *
- * Order matters and is enforced here, not by the callers:
- *  1. refuse a session whose omp child is mid-turn (a run, a live subagent, or
- *     a dialog the agent is blocked on) — the delete would kill work the user
- *     can still see, and omp would flush the file back on shutdown anyway;
- *  2. destroy the child and AWAIT its exit — omp writes session state on
- *     shutdown and would otherwise recreate the transcript just removed;
- *  3. purge side questions, then the transcript, artifacts and Kabmo rows.
- *
- * A pending `new-…` session is refused: it is a client-side placeholder with
- * nothing stored anywhere yet, so deleting it is the same as navigating away.
+ * The sequence (pending/id guard, busy refusal, child teardown, purge) lives in
+ * `removeSession` because the batch route performs the same one per id; this
+ * handler only maps the verdict onto a response.
  */
 
 import { json } from '@/server/lib/remix-compat';
 import type { ActionFunctionArgs } from '@/server/lib/remix-compat';
 import { methodNotAllowed } from '@/server/lib/route-adapter';
-import { getRpcSession } from '@/server/lib/omp/rpc/session-registry';
-import { purgeSessionData } from '@/server/lib/omp/session/delete.server';
-import { purgeBtwForSession } from '@/server/lib/btw/purge.server';
-import { isSinglePathSegment } from '@/server/lib/fs/path-segment';
-import { isMockMode } from '@/server/mock.server';
+import { removeSession } from '@/server/lib/omp/session/delete-flow.server';
 
 export async function deleteSession({ request, params }: ActionFunctionArgs) {
   if (request.method !== 'DELETE') {
@@ -37,47 +26,20 @@ export async function deleteSession({ request, params }: ActionFunctionArgs) {
 
   const sessionId = params.sessionId;
   if (!sessionId) return json({ error: 'Missing session id' }, { status: 400 });
-  if (sessionId.startsWith('new-')) {
-    return json({ error: 'This chat has not been created yet.', code: 'session_pending' }, { status: 400 });
-  }
-  // The id names a directory under the sessions root and another under the btw
-  // root, so it must be exactly one path segment — see `isSinglePathSegment`
-  // for the `.` case that made this load-bearing. Both purges re-check it
-  // independently; refusing here is what turns the attempt into a 400.
-  if (!isSinglePathSegment(sessionId)) {
-    return json({ error: 'Invalid session id' }, { status: 400 });
-  }
-
-  // A live child is the only other writer of the transcript. Busy means a turn,
-  // a live subagent, or a dialog omp is parked on — all things the user can
-  // still act on, so the delete is refused with a reason rather than silently
-  // taking them down.
-  const live = getRpcSession(sessionId);
-  if (live?.isAlive()) {
-    if (live.isBusy()) {
-      return json(
-        { error: 'This session is working. Stop the run before deleting it.', code: 'session_busy' },
-        { status: 409 },
-      );
-    }
-    await live.destroyAndWait();
-  }
-
-  // Side questions live outside the session file and are removed first: their
-  // children must be gone before the parent transcript they were snapshotted
-  // from disappears.
-  const btwTopicsRemoved = isMockMode() ? 0 : await purgeBtwForSession(sessionId);
-  const purged = await purgeSessionData(sessionId);
 
-  if (!purged.found) {
-    return json({ error: 'Session not found' }, { status: 404 });
+  const result = await removeSession(sessionId);
+  if (!result.ok) {
+    return json(
+      { error: result.error, code: result.code },
+      { status: result.status },
+    );
   }
 
   return json({
     success: true,
     sessionId,
-    fileRemoved: purged.fileRemoved,
-    artifactsRemoved: purged.artifactsRemoved,
-    btwTopicsRemoved,
+    fileRemoved: result.fileRemoved,
+    artifactsRemoved: result.artifactsRemoved,
+    btwTopicsRemoved: result.btwTopicsRemoved,
   });
 }

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

@@ -14,9 +14,14 @@ import {
 import { listSubagents, readSubagentTranscript } from '@/server/routes/sessions/subagents';
 import { cancelSubagent, steerSubagent } from '@/server/routes/sessions/subagent-control';
 import { deleteSession } from '@/server/routes/sessions/delete';
+import { batchDeleteSessions } from '@/server/routes/sessions/batch-delete';
 
 export const sessionsBindings: HandlerBinding[] = [
   ...bindingsFor(sessionsList, '/api/sessions/list'),
+  // Registered BEFORE the `:sessionId` routes: the segment is static, and the
+  // batch route is POST while `:sessionId` answers DELETE, so an id route
+  // winning the match would turn every batch into a 405.
+  { method: 'POST', path: '/api/sessions/batch-delete', handler: batchDeleteSessions },
   ...bindingsFor(sessionsFolder, '/api/sessions/:sessionId'),
   // DELETE-only on the same path the folder loader answers GET on: mounting it
   // through `actionBindings` would register a 405 GET fallback that Elysia

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/apply.ts

@@ -115,7 +115,7 @@ export async function action({ request, params }: ActionFunctionArgs) {
         // still on the old build would mislead, and `restarting` is what tells
         // the console to wait for the replacement and reload.
         const result = target === 'kabmo' && applied.result.success && applied.updated
-          ? withRestartPlan(applied.result, scheduleSelfRestart())
+          ? withRestartPlan(applied.result, scheduleSelfRestart('update', applied.installed ?? null))
           : applied.result;
         handlers.send('result', result);
       } catch (err) {

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/batch-select.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The batch-selection rules, in isolation.
+ *
+ * Each of these decides what a header checkbox reports or what a Delete sends,
+ * so the failure mode is a delete of the wrong rows — not a cosmetic bug. The
+ * archived rule is the one that matters most: a row the filter hides cannot be
+ * unselected, so "select all" must never reach it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import {
+  liveSelection,
+  selectableSessionIds,
+  selectionSummary,
+  toggleSelection,
+} from '@/shared/lib/workspace/batch-select';
+
+describe('toggleSelection', () => {
+  test('adds an id it does not hold, preserving click order', () => {
+    expect(toggleSelection(['a'], 'b')).toEqual(['a', 'b']);
+  });
+
+  test('removes an id it holds', () => {
+    expect(toggleSelection(['a', 'b', 'c'], 'b')).toEqual(['a', 'c']);
+  });
+
+  test('does not mutate the input', () => {
+    const selected = ['a'];
+    toggleSelection(selected, 'b');
+    expect(selected).toEqual(['a']);
+  });
+});
+
+describe('selectionSummary', () => {
+  test('reports all only when every available id is selected', () => {
+    expect(selectionSummary(['a', 'b'], ['a', 'b'])).toEqual({ count: 2, all: true, some: false });
+  });
+
+  test('reports some for a partial selection', () => {
+    expect(selectionSummary(['a'], ['a', 'b'])).toEqual({ count: 1, all: false, some: true });
+  });
+
+  test('an empty available list is neither all nor some', () => {
+    // A header checkbox over a workspace with no rows must not claim "all".
+    expect(selectionSummary([], [])).toEqual({ count: 0, all: false, some: false });
+  });
+
+  test('an id outside the available list does not count', () => {
+    expect(selectionSummary(['z'], ['a'])).toEqual({ count: 0, all: false, some: false });
+  });
+});
+
+describe('selectableSessionIds', () => {
+  const sessions = [
+    { id: 'a', is_archived: 0 },
+    { id: 'b', is_archived: 1 },
+    { id: 'c' },
+  ];
+
+  test('offers the live rows and skips the archived ones', () => {
+    expect(selectableSessionIds(sessions, false)).toEqual(['a', 'c']);
+  });
+
+  test('follows the archive filter when it is on', () => {
+    expect(selectableSessionIds(sessions, true)).toEqual(['b']);
+  });
+
+  test('ids are strings, matching what a checkbox reports', () => {
+    expect(selectableSessionIds([{ id: 7 }], false)).toEqual(['7']);
+  });
+});
+
+describe('liveSelection', () => {
+  test('drops an id that is no longer in the list', () => {
+    // The two-tab case: one tab deleted the session, so this bar must stop
+    // counting it and must never send it.
+    expect(liveSelection(['a', 'gone'], ['a', 'b'])).toEqual(['a']);
+  });
+
+  test('keeps the recorded order', () => {
+    expect(liveSelection(['b', 'a'], ['a', 'b'])).toEqual(['b', 'a']);
+  });
+
+  test('an empty available list empties the selection', () => {
+    expect(liveSelection(['a'], [])).toEqual([]);
+  });
+});

package/src/shared/lib/workspace/batch-select.ts

@@ -0,0 +1,86 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Batch selection, stated once for both sidebars and both nouns.
+ *
+ * The sidebar offers TWO selection modes and they are deliberately separate,
+ * because the thing being deleted is not the same noun:
+ *
+ *   - `session` — started from a workspace's own `⋯` menu, and scoped to that
+ *     workspace. Deleting removes the sessions; the workspace stays.
+ *   - `workspace` — started from the top toolbar. Deleting removes the
+ *     workspace registration (and, with it, the rows the sidebar drew for it).
+ *
+ * One mode is active at a time, and entering either one is an explicit act: the
+ * checkboxes do not exist until the user asks for them, because a sidebar that
+ * draws a checkbox on every row by default turns every click into a decision
+ * between selecting and opening.
+ *
+ * Selection is an ARRAY of ids rather than a `Set`: it is persisted nowhere and
+ * compared only against the rows on screen, so an immutable array keeps the
+ * hook's updates trivial and the helpers below pure and unit-testable.
+ */
+
+export type BatchMode = 'session' | 'workspace';
+
+/** Toggle one id in the selection, preserving order. */
+export function toggleSelection(selected: readonly string[], id: string): string[] {
+  return selected.includes(id)
+    ? selected.filter((entry) => entry !== id)
+    : [...selected, id];
+}
+
+/**
+ * What a tri-state control (a header checkbox, a count) reports about a set of
+ * available ids. `all` is false for an empty list: a header checkbox over a
+ * workspace with no sessions must not claim everything is selected.
+ */
+export interface SelectionSummary {
+  count: number;
+  all: boolean;
+  some: boolean;
+}
+
+export function selectionSummary(selected: readonly string[], available: readonly string[]): SelectionSummary {
+  const chosen = new Set(selected);
+  const count = available.filter((id) => chosen.has(id)).length;
+  return {
+    count,
+    all: available.length > 0 && count === available.length,
+    some: count > 0 && count < available.length,
+  };
+}
+
+/**
+ * Every session id a folder's rows can offer to a session-mode selection.
+ * Archived rows follow the sidebar's own filter, so "select all" can never
+ * select a row the user cannot see (and therefore cannot unselect).
+ */
+export function selectableSessionIds(
+  sessions: readonly { id: number | string; is_archived?: number }[],
+  showArchived: boolean,
+): string[] {
+  return sessions
+    .filter((session) => (showArchived ? session.is_archived === 1 : session.is_archived !== 1))
+    .map((session) => String(session.id));
+}
+
+/**
+ * The selected ids that are still present in `available`, in the order the
+ * selection recorded them.
+ *
+ * A selection is deliberately NOT pruned as the list changes: a row can vanish
+ * for one render (a folder collapsing under a filter, a push mid-refresh), and
+ * an effect that dropped it would silently discard a choice. But the count the
+ * bar prints and the ids Delete sends must both be the LIVE set — measured with
+ * two tabs open: one deleted a session, and the other's bar went on reading
+ * "1 of 0 sessions selected" with Delete enabled for an id that no longer
+ * existed anywhere.
+ */
+export function liveSelection(selected: readonly string[], available: readonly string[]): string[] {
+  const alive = new Set(available);
+  return selected.filter((id) => alive.has(id));
+}