@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,316 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The sessions route group's request contract: id safety, name validation, the
+ * per-session UI-state blob, and the follow-up queue's per-item mutations.
+ *
+ * Every case is a refusal or a boundary whose wrong answer would be silent: a
+ * `.` session id must be a 404 before any path join (the delete route's own
+ * blast-radius guard, reused here), a blank or over-long rename must be a 400
+ * with its code rather than a truncated write, and a queue mutation must return
+ * the canonical queue instead of trusting a client's full-list replacement.
+ *
+ * The routes are called directly, as the other route tests do. The database is
+ * a temp SQLite file (never the developer's) and `PI_CODING_AGENT_DIR` a temp
+ * tree holding one real session file, so the id resolver is exercised for real
+ * while nothing outside `/tmp` is read.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { getDb } from '@/server/db.server';
+import type { DbClient } from '@/server/lib/db/client';
+import type { ActionFunctionArgs, LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { invalidateOmpSidebarData } from '@/server/lib/omp/session/reader';
+import { ModeMirror } from '@/server/lib/omp/rpc/mode-mirror';
+import { recordSpawnProvenance } from '@/server/lib/omp/rpc/spawn-provenance';
+import { removeDir } from '@/test-support/remove-dir';
+import {
+  archiveSession,
+  getSessionModes,
+  getSessionState,
+  markSeen,
+  putSessionState,
+  renameSession,
+} from '@/server/routes/sessions/session';
+
+// `tmpdir()`, not `/tmp`: there is no `/tmp` on Windows, so the literal
+// resolved against the current drive and the tree was never where the suite
+// (or the delete) looked for it.
+const ROOT = path.join(os.tmpdir(), `omc-sessions-routes-${process.pid}`);
+const AGENT = path.join(ROOT, 'agent');
+const SESSION_ID = '11111111-2222-3333-4444-555555555555';
+const UNKNOWN = '00000000-0000-0000-0000-000000000000';
+/** A live session whose JSONL does not exist yet — the window omp creates on
+ *  every new chat, before its first assistant message. */
+const NO_FILE_LIVE = '99999999-8888-7777-6666-555555555555';
+
+let db: DbClient;
+let priorDbPath: string | undefined;
+let priorMock: string | undefined;
+let priorAgentDir: string | undefined;
+let priorSlot: typeof globalThis.__kabmoDb;
+let priorSessions: typeof globalThis.__ompSessions;
+
+beforeAll(async () => {
+  removeDir(ROOT);
+  const project = path.join(AGENT, 'sessions', 'proj');
+  fs.mkdirSync(project, { recursive: true });
+  // One real session file, with a plan-mode entry, so the id resolver and the
+  // transcript reader are exercised against a file rather than a stub.
+  fs.writeFileSync(
+    path.join(project, `${SESSION_ID}.jsonl`),
+    [
+      // A session header needs its `timestamp`: `scanSessionInfo` derives
+      // `created` from it and `toOmpSession` calls `toISOString()`, so a
+      // header without one takes the whole sidebar down with
+      // `RangeError: Invalid Date`.
+      JSON.stringify({ type: 'session', id: SESSION_ID, cwd: '/tmp', timestamp: '2026-09-30T10:00:00.000Z' }),
+      JSON.stringify({ type: 'custom', customType: 'chamber-plan-state', data: { enabled: true } }),
+      '',
+    ].join('\n'),
+  );
+
+  priorAgentDir = Bun.env.PI_CODING_AGENT_DIR;
+  priorDbPath = Bun.env.KABMO_DB_PATH;
+  priorMock = Bun.env.MOCK;
+  priorSlot = globalThis.__kabmoDb;
+  priorSessions = globalThis.__ompSessions;
+
+  Bun.env.PI_CODING_AGENT_DIR = AGENT;
+  Bun.env.KABMO_DB_PATH = path.join(ROOT, 'db.sqlite');
+  Bun.env.MOCK = 'false';
+  // The db handle is process-wide; CLOSE the one a sibling suite left before
+  // dropping it — an abandoned connection keeps its file locked, and on Windows
+  // the teardown delete then fails with EBUSY. The temp file stays on disk so a
+  // later suite that inherits the slot cannot fall back to the real database.
+  globalThis.__kabmoDb?.resolved?.raw.close();
+  globalThis.__kabmoDb = undefined;
+  clearSessionFileCaches();
+  invalidateOmpSidebarData();
+  db = await getDb();
+});
+
+afterAll(() => {
+  clearSessionFileCaches();
+  invalidateOmpSidebarData();
+  // The live-child cases register a fake wrapper in the process-wide registry;
+  // a sibling suite must not inherit it as a real session.
+  delete globalThis.__ompSessions;
+  if (priorAgentDir === undefined) delete Bun.env.PI_CODING_AGENT_DIR;
+  else Bun.env.PI_CODING_AGENT_DIR = priorAgentDir;
+  if (priorDbPath === undefined) delete Bun.env.KABMO_DB_PATH;
+  else Bun.env.KABMO_DB_PATH = priorDbPath;
+  if (priorMock === undefined) delete Bun.env.MOCK;
+  else Bun.env.MOCK = priorMock;
+  // Close before restoring the slot and deleting: a live connection makes a
+  // Windows delete fail with EBUSY, and a throw from `afterAll` reports a
+  // failure of the file.
+  globalThis.__kabmoDb?.resolved?.raw.close();
+  globalThis.__kabmoDb = priorSlot;
+  if (priorSessions === undefined) delete globalThis.__ompSessions;
+  else globalThis.__ompSessions = priorSessions;
+  removeDir(ROOT);
+});
+
+function formPost(body: Record<string, string>, url = 'http://localhost/api/x'): Request {
+  const form = new FormData();
+  for (const [key, value] of Object.entries(body)) form.append(key, value);
+  return new Request(url, { method: 'POST', body: form });
+}
+function jsonRequest(method: string, body: unknown, url = 'http://localhost/api/x'): Request {
+  return new Request(url, {
+    method,
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+/** The loader args a route needs: `params` plus the request every session
+ *  route reads (the peer-relay guard inspects its headers). */
+function loaderArgs(sessionId: string): LoaderFunctionArgs {
+  return {
+    params: { sessionId },
+    request: new Request(`http://localhost/api/sessions/${encodeURIComponent(sessionId)}/modes`),
+  } as unknown as LoaderFunctionArgs;
+}
+
+describe('getSessionModes', () => {
+  test('a missing id is a 400', async () => {
+    const res = (await getSessionModes({ params: {}, request: new Request('http://localhost/api/x') } as unknown as LoaderFunctionArgs) as unknown as Response);
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ error: 'Missing session id' });
+  });
+
+  test('a value that is not one path segment is a 404 before any lookup', async () => {
+    for (const id of ['.', '..', 'a/b', 'a\\b']) {
+      const res = (await getSessionModes(loaderArgs(id)) as unknown as Response);
+      expect(res.status).toBe(404);
+      expect(await res.json()).toMatchObject({ error: 'Session not found' });
+    }
+  });
+
+  test('an unknown but well-formed id is a 404', async () => {
+    expect((await getSessionModes(loaderArgs(UNKNOWN))).status).toBe(404);
+  });
+
+  // The window omp creates on every new chat: the child is live and already in
+  // the mode the user picked, and the JSONL does not exist yet (omp writes it at
+  // the first assistant message). Answering 404 there told the composer "no
+  // session" for a running chat, and reset the toggles the user had just
+  // pressed, so the live child answers instead.
+  test('a live session with no file yet answers its own modes, not a 404', async () => {
+    const wrapper = { modeMirror: new ModeMirror(), isAlive: () => true };
+    globalThis.__ompSessions ??= new Map();
+    globalThis.__ompSessions.set(NO_FILE_LIVE, wrapper as never);
+    recordSpawnProvenance(wrapper as never, 'yolo', { CHAMBER_MODES: 'plan' });
+    try {
+      const res = (await getSessionModes(loaderArgs(NO_FILE_LIVE)) as unknown as Response);
+      expect(res.status).toBe(200);
+      expect(await res.json()).toMatchObject({ sessionId: NO_FILE_LIVE, modes: { plan: true, goal: false } });
+    } finally {
+      globalThis.__ompSessions.delete(NO_FILE_LIVE);
+    }
+  });
+
+  // A toggle moves the child, and the entry recording it lands a moment later —
+  // so the file can still describe the state the user just left.
+  test('a child that has reported a mode outranks the file', async () => {
+    const wrapper = { modeMirror: new ModeMirror(), isAlive: () => true };
+    wrapper.modeMirror.observeMarker({ marker: 'CHAMBER_PLAN_STATE:' as never, payload: { enabled: false } });
+    globalThis.__ompSessions ??= new Map();
+    globalThis.__ompSessions.set(SESSION_ID, wrapper as never);
+    try {
+      const res = (await getSessionModes(loaderArgs(SESSION_ID)) as unknown as Response);
+      // The file on disk says plan: true.
+      expect(await res.json()).toMatchObject({ modes: { plan: false } });
+    } finally {
+      globalThis.__ompSessions.delete(SESSION_ID);
+    }
+  });
+
+  test('a dead session with no file is still a 404', async () => {
+    globalThis.__ompSessions ??= new Map();
+    globalThis.__ompSessions.set(NO_FILE_LIVE, { modeMirror: new ModeMirror(), isAlive: () => false } as never);
+    try {
+      expect((await getSessionModes(loaderArgs(NO_FILE_LIVE))).status).toBe(404);
+    } finally {
+      globalThis.__ompSessions.delete(NO_FILE_LIVE);
+    }
+  });
+
+  test('a real session file answers its persisted selection', async () => {
+    const res = (await getSessionModes(loaderArgs(SESSION_ID)) as unknown as Response);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ sessionId: SESSION_ID, modes: { plan: true, goal: false } });
+  });
+});
+
+describe('archiveSession', () => {
+  test('a wrong verb is a 405', async () => {
+    const res: Response = (await archiveSession({ request: new Request('http://localhost/api/x', { method: 'GET' }), params: { sessionId: SESSION_ID } } as unknown as ActionFunctionArgs) as unknown as Response);
+    expect(res.status).toBe(405);
+  });
+
+  test('a missing id is a 400', async () => {
+    const res: Response = (await archiveSession({ request: formPost({ archived: 'true' }), params: {} } as unknown as ActionFunctionArgs) as unknown as Response);
+    expect(res.status).toBe(400);
+  });
+
+  test('archiving inserts the row and unarchiving removes it', async () => {
+    const archive = async (archived: boolean): Promise<Response> =>
+      archiveSession({ request: formPost({ archived: String(archived) }), params: { sessionId: SESSION_ID } } as unknown as ActionFunctionArgs) as unknown as Response;
+
+    expect(await (await archive(true)).json()).toMatchObject({ success: true, archived: true });
+    expect(await db.get('SELECT session_id FROM archived_sessions WHERE session_id = ?', [SESSION_ID])).toBeTruthy();
+    expect(await (await archive(false)).json()).toMatchObject({ success: true, archived: false });
+    expect(await db.get('SELECT session_id FROM archived_sessions WHERE session_id = ?', [SESSION_ID])).toBeNull();
+  });
+});
+
+describe('renameSession', () => {
+  const rename = async (name: string, sessionId = UNKNOWN): Promise<Response> =>
+    renameSession({ request: formPost({ name }), params: { sessionId } } as unknown as ActionFunctionArgs) as unknown as Response;
+
+  test('a wrong verb is a 405', async () => {
+    const res = (await renameSession({ request: new Request('http://localhost/api/x', { method: 'GET' }), params: { sessionId: SESSION_ID } } as unknown as ActionFunctionArgs)) as Response;
+    expect(res.status).toBe(405);
+  });
+
+  test('a missing id is a 400', async () => {
+    const res = (await renameSession({ request: formPost({ name: 'x' }), params: {} } as unknown as ActionFunctionArgs)) as Response;
+    expect(res.status).toBe(400);
+  });
+
+  test('a blank name is refused with its code', async () => {
+    const res: Response = await rename('   ');
+    expect(res.status).toBe(400);
+    expect(await res.json()).toMatchObject({ code: 'session_name_required' });
+  });
+
+  test('the 200-character ceiling is a boundary, not an off-by-one', async () => {
+    // 201 is refused...
+    const tooLong: Response = await rename('x'.repeat(201));
+    expect(tooLong.status).toBe(400);
+    expect(await tooLong.json()).toMatchObject({ code: 'session_name_too_long' });
+  });
+
+  test('a valid rename for an unknown session is a 404, not a write', async () => {
+    const res: Response = await rename('a real name');
+    expect(res.status).toBe(404);
+    expect(await res.json()).toMatchObject({ error: 'Session not found' });
+  });
+});
+
+describe('per-session UI state', () => {
+  const put = async (body: unknown): Promise<Response> =>
+    putSessionState({ request: jsonRequest('POST', body), params: { sessionId: 'state-test' } } as unknown as ActionFunctionArgs) as unknown as Response;
+
+  test('a missing id is a 400', async () => {
+    const res = (await putSessionState({ request: jsonRequest('POST', { state: {} }),
+      params: {},
+    } as unknown as ActionFunctionArgs) as unknown as Response);
+    expect(res.status).toBe(400);
+  });
+
+  test('a wrong verb is a 405', async () => {
+    const res = (await putSessionState({ request: jsonRequest('PUT', { state: {} }),
+      params: { sessionId: 'state-test' },
+    } as unknown as ActionFunctionArgs) as unknown as Response);
+    expect(res.status).toBe(405);
+  });
+
+  test('only an object state is accepted', async () => {
+    for (const body of [{}, { state: null }, { state: [] }, { state: 'x' }, []]) {
+      expect((await put(body)).status).toBe(400);
+    }
+  });
+
+  test('a valid state round-trips through the store', async () => {
+    const res: Response = await put({ state: { sidebar: 'open', n: 3 } });
+    expect(res.status).toBe(200);
+    const read = (await getSessionState({ params: { sessionId: 'state-test' } } as unknown as ActionFunctionArgs) as unknown as Response);
+    expect(await read.json()).toMatchObject({ sessionId: 'state-test', state: { sidebar: 'open', n: 3 } });
+  });
+
+  test('a missing id on the read is a 400', async () => {
+    expect((await getSessionState({ params: {} } as unknown as ActionFunctionArgs)).status).toBe(400);
+  });
+});
+
+describe('markSeen', () => {
+  test('a missing id is a 400', async () => {
+    expect((await markSeen({ params: {} } as unknown as ActionFunctionArgs)).status).toBe(400);
+  });
+
+  test('acking a session with no stored status is a no-op success', async () => {
+    const res = (await markSeen({ params: { sessionId: 'nothing-stored' } } as unknown as ActionFunctionArgs) as unknown as Response);
+    expect(await res.json()).toMatchObject({ success: true, deleted: false });
+  });
+});

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

@@ -0,0 +1,291 @@
+import { json } from '@/server/lib/remix-compat';
+import type { ActionFunctionArgs, LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { methodNotAllowed } from '@/server/lib/route-adapter';
+import { getDb } from '@/server/db.server';
+import { markStreamSeen } from '@/shared/lib/omp/session/stream-state.server';
+import { isMockMode } from '@/server/mock.server';
+import { getRpcSession } from '@/server/lib/omp/rpc/manager';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { resolveSessionFileOr404 } from '@/server/lib/omp/session/locator';
+import { setSessionTitle } from '@/server/lib/omp/session/title-slot';
+import { renameSessionWithAi } from '@/server/lib/omp/session/rename-with-ai.server';
+import { isSinglePathSegment } from '@/server/lib/fs/path-segment';
+import { loadPersistedModes } from '@/server/lib/omp/session/modes';
+import { liveModeSelection } from '@/server/lib/omp/mode/live-selection';
+import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
+
+/**
+ * GET /api/sessions/:sessionId/modes — the plan/goal mode selection.
+ *
+ * Read from the session's own transcript, because the modes are not a layout
+ * preference: they are state the AGENT ran under, and the records are written
+ * by the child process as it transitions. That makes this the one source a
+ * second tab, a restarted Kabmo and a CLI-driven session all agree on.
+ *
+ * The transcript is not always there to read. omp writes the JSONL at the first
+ * ASSISTANT message, so a new chat is live — and in whatever mode the user just
+ * picked — with no file for the first seconds-to-minutes. A live child is
+ * therefore asked FIRST: the wrapper mirrors the extension's own mode markers,
+ * and its spawn environment carries the selection the child was started with.
+ * Answering 404 there told the composer "no session" for a session that is
+ * demonstrably running, and reset the toggles the user had just pressed
+ * (measured: the file appeared 40 s after the id was adopted).
+ *
+ * Once the child has SPOKEN the answer comes from it even when a transcript
+ * exists: a toggle moves the child and the entry recording it lands a moment
+ * later, so the file can still describe the previous state. A child that has
+ * reported nothing is described better by the file than by the environment it
+ * happened to be spawned with. A session with no live child and no file is a
+ * genuine 404, like every other session route.
+ *
+ * Deliberately NOT relayed to a peer instance when this one holds no child:
+ * omp creates the ownership lease together with the session file (measured —
+ * both absent after a spawn and both present after the first prompt), so in the
+ * window this route exists for there is no lease to resolve an owner from and
+ * the relay could never fire.
+ */
+export async function getSessionModes({ params }: LoaderFunctionArgs) {
+  const sessionId = params.sessionId;
+  if (!sessionId) return json({ error: 'Missing session id' }, { status: 400 });
+  if (!isSinglePathSegment(sessionId)) return json({ error: 'Session not found' }, { status: 404 });
+
+  const live = liveModeSelection(sessionId);
+  if (live?.spoken) return json({ sessionId, modes: live.modes });
+
+  const resolved = await resolveSessionFileOr404(sessionId);
+  if ('response' in resolved) {
+    // A live child with no transcript yet: it is the only thing that can
+    // describe this session, and "not found" would be a lie about a process
+    // that is running.
+    if (live) return json({ sessionId, modes: live.modes });
+    return resolved.response;
+  }
+  return json({ sessionId, modes: live?.modes ?? (await loadPersistedModes(resolved.filePath)) });
+}
+
+/**
+ * POST /api/sessions/:sessionId/archive — toggle archive state for a session.
+ *
+ * Archive state is stored in the `archived_sessions` table keyed by the
+ * session id (numeric SQLite id in mock mode, omp session UUID string in
+ * real mode). The session row itself is never touched, so un-archiving is
+ * always possible and no data is lost.
+ */
+export async function archiveSession({ request, params }: ActionFunctionArgs) {
+  if (request.method !== 'POST') {
+    return methodNotAllowed({ request, params });
+  }
+
+  const db = await getDb();
+  const sessionId = params.sessionId;
+  if (!sessionId) {
+    return json({ error: 'Missing session id' }, { status: 400 });
+  }
+
+  const formData = await request.formData();
+  const archived = formData.get('archived') === 'true';
+
+  if (archived) {
+    await db.run(
+      'INSERT OR IGNORE INTO archived_sessions (session_id) VALUES (?)',
+      [sessionId],
+    );
+  } else {
+    await db.run('DELETE FROM archived_sessions WHERE session_id = ?', [sessionId]);
+  }
+
+  // Archiving moves the session between the sidebar's archive view and its
+  // normal list, so the structure changed.
+  emitRealtimeSignal('sidebar-structure');
+  return json({ success: true, sessionId, archived });
+}
+
+const MAX_SESSION_NAME_LENGTH = 200;
+
+/**
+ * POST /api/sessions/:sessionId/rename — persist a new display name.
+ *
+ * Real mode: a live omp process owns its session file, so the rename is
+ * forwarded over RPC when one is running (and falls back to the on-disk
+ * 256-byte title slot when it is not). Mock mode: the title lives in the
+ * SQLite `sessions` row (sidebar) and `chat_sessions` row (chat header).
+ */
+export async function renameSession({ request, params }: ActionFunctionArgs) {
+  if (request.method !== 'POST') {
+    return methodNotAllowed({ request, params });
+  }
+
+  const sessionId = params.sessionId;
+  if (!sessionId) {
+    return json({ error: 'Missing session id' }, { status: 400 });
+  }
+
+  try {
+    const formData = await request.formData();
+    const name = String(formData.get('name') ?? '').trim();
+
+    if (!name) {
+      return json(
+        { error: 'Session name cannot be empty', code: 'session_name_required' },
+        { status: 400 },
+      );
+    }
+    if (name.length > MAX_SESSION_NAME_LENGTH) {
+      return json(
+        { error: 'Session name is too long', code: 'session_name_too_long' },
+        { status: 400 },
+      );
+    }
+
+    if (isMockMode()) {
+      const db = await getDb();
+      const result = await db.run('UPDATE sessions SET title = ? WHERE id = ?', [name, sessionId]);
+      await db.run(
+        'UPDATE chat_sessions SET title = ?, updated_at = CURRENT_TIMESTAMP WHERE session_id = ?',
+        [name, sessionId],
+      );
+      if (!result.changes) {
+        return json({ error: 'Session not found' }, { status: 404 });
+      }
+      emitRealtimeSignal('sidebar-structure');
+      return json({ success: true, sessionId, name });
+    }
+
+    // A running omp process owns its session file; let omp's own writer win so
+    // the in-memory title cannot clobber ours on the next flush.
+    const rpc = getRpcSession(sessionId);
+    if (rpc?.isAlive()) {
+      try {
+        await rpc.send({ type: 'set_session_name', name });
+        emitRealtimeSignal('sidebar-structure');
+        return json({ success: true, sessionId, name });
+      } catch {
+        // Fall through to the on-disk title slot below.
+      }
+    }
+
+    const resolved = await resolveSessionFileOr404(sessionId);
+    if ('response' in resolved) return resolved.response;
+    const { filePath } = resolved;
+
+    await setSessionTitle(filePath, name, 'user');
+    // The mtime-keyed scan cache cannot see an in-place 256-byte slot write.
+    clearSessionFileCaches();
+    emitRealtimeSignal('sidebar-structure');
+    return json({ success: true, sessionId, name });
+  } catch (error) {
+    return json(
+      { error: error instanceof Error ? error.message : String(error) },
+      { status: 400 },
+    );
+  }
+}
+
+/**
+ * POST /api/sessions/:sessionId/rename-with-ai — let omp name the session from
+ * its own transcript ("Rename with AI" in the session row's menu).
+ *
+ * Unlike the automatic titling Kabmo already does, this is an explicit
+ * request, so it renames a session that already has a name.
+ */
+export async function renameWithAi({ request, params }: ActionFunctionArgs) {
+  if (request.method !== 'POST') {
+    return methodNotAllowed({ request, params });
+  }
+
+  const sessionId = params.sessionId;
+  if (!sessionId) return json({ error: 'Missing session id' }, { status: 400 });
+  // A pending `new-…` chat has no transcript anywhere, and omp has nothing to
+  // derive a title from. The menu omits the item; this is the backstop.
+  if (sessionId.startsWith('new-')) {
+    return json({ error: 'This chat has not been created yet.', code: 'session_pending' }, { status: 400 });
+  }
+  if (!isSinglePathSegment(sessionId)) {
+    return json({ error: 'Invalid session id' }, { status: 400 });
+  }
+
+  const result = await renameSessionWithAi(sessionId);
+  if (!result.ok) return json({ error: result.error }, { status: result.status });
+
+  // The rename is a fixed-width in-place slot write, which the scan cache's
+  // mtime key cannot see — the same reason the auto-title path clears it.
+  return json({ success: true, sessionId, name: result.title });
+}
+
+/**
+ * GET /api/sessions/:sessionId/state — load the persisted per-session UI
+ * state blob. Keyed by the session id (numeric in mock mode, omp session
+ * UUID string in real mode), same keying as `archived_sessions`.
+ */
+export async function getSessionState({ params }: LoaderFunctionArgs) {
+  const sessionId = params.sessionId;
+  if (!sessionId) {
+    return json({ error: 'Missing session id' }, { status: 400 });
+  }
+
+  const db = await getDb();
+  const row = await db.get(
+    'SELECT state FROM session_ui_state WHERE session_id = ?',
+    [sessionId],
+  );
+
+  let state: Record<string, unknown> = {};
+  if (row && typeof row.state === 'string' && row.state) {
+    try {
+      const parsed = JSON.parse(row.state);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        state = parsed as Record<string, unknown>;
+      }
+    } catch {
+      // Corrupt blob — treat as empty state so the session still opens.
+    }
+  }
+
+  return json({ sessionId, state });
+}
+
+/**
+ * POST /api/sessions/:sessionId/state — persist the per-session UI state
+ * blob. The body is `{ state: <arbitrary JSON object> }`; the client sends
+ * its full state map so the endpoint stays a dumb key/value store.
+ */
+export async function putSessionState({ request, params }: ActionFunctionArgs) {
+  if (request.method !== 'POST') {
+    return methodNotAllowed({ request, params });
+  }
+
+  const sessionId = params.sessionId;
+  if (!sessionId) {
+    return json({ error: 'Missing session id' }, { status: 400 });
+  }
+
+  const body = (await request.json()) as { state?: unknown };
+  if (!body || typeof body !== 'object' || Array.isArray(body) || typeof body.state !== 'object' || body.state === null || Array.isArray(body.state)) {
+    return json({ error: 'Invalid body: expected { state: object }' }, { status: 400 });
+  }
+
+  const db = await getDb();
+  await db.run(
+    `INSERT OR REPLACE INTO session_ui_state (session_id, state, updated_at)
+     VALUES (?, ?, CURRENT_TIMESTAMP)`,
+    [sessionId, JSON.stringify(body.state)],
+  );
+
+  return json({ success: true, sessionId });
+}
+
+/**
+ * POST /api/sessions/:sessionId/stream-seen — acknowledge the session's
+ * one-shot stream badge (`finish` / `abort`). Called when the
+ * session is opened; deletes the terminal row so the check shows exactly
+ * once. A `stream` row (live run) is never deleted — a client acking from a
+ * stale status map must not kill the spinner of a running session.
+ */
+export async function markSeen({ params }: ActionFunctionArgs) {
+  const sessionId = params.sessionId;
+  if (!sessionId) {
+    return json({ error: 'Missing session id' }, { status: 400 });
+  }
+  const deleted = await markStreamSeen(sessionId);
+  return json({ success: true, sessionId, deleted });
+}

package/src/server/routes/sessions/subagent-control.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Control of ONE running subagent, without touching the parent turn.
+ *
+ * omp exposes `cancel_subagent` (hard-kill one running subagent) and
+ * `steer_subagent` (send it a message as its user) on RPC. Both act on the
+ * session's live child, so they are dispatched through the same wrapper the
+ * chat uses — and like every other command they must NOT boot an omp process to
+ * answer: a subagent is by definition something the session's own child is
+ * running, so a session this process does not manage has none to cancel.
+ *
+ * The id is the roster id the session file and `get_subagents` both report
+ * (measured on omp 18.8.3: `Sleeper`, `ListOmpws` — a slug, not a uuid). It is
+ * validated against the same grammar the transcript path derivation uses,
+ * because the value arrives from the client.
+ */
+
+import { json } from '@/server/lib/remix-compat';
+import type { ActionFunctionArgs } from '@/server/lib/remix-compat';
+import { requireParam } from '@/server/lib/route-adapter';
+import { getRpcSession } from '@/server/lib/omp/rpc/manager';
+import { rpcErrorResponse } from '@/server/lib/omp/rpc/errors';
+import { SUBAGENT_ID_MAX_LENGTH, SUBAGENT_ID_RE } from '@/server/lib/omp/subagent/history/paths';
+
+/** `POST /api/sessions/:sessionId/subagents/:subagentId/cancel`. */
+export async function cancelSubagent({ request, params }: ActionFunctionArgs) {
+  const sessionId = requireParam(params, 'sessionId');
+  const subagentId = requireParam(params, 'subagentId');
+  if (!sessionId || !subagentId) return json({ error: 'Missing session or subagent id' }, { status: 400 });
+  if (request.method !== 'POST') return json({ error: 'Method not allowed' }, { status: 405 });
+  if (!SUBAGENT_ID_RE.test(subagentId) || subagentId.length > SUBAGENT_ID_MAX_LENGTH) {
+    return json({ error: 'Invalid subagent id', code: 'invalid_subagent_id' }, { status: 400 });
+  }
+
+  const session = getRpcSession(sessionId);
+  if (!session?.isAlive()) {
+    return json({ error: 'Session is not running', code: 'session_not_running' }, { status: 409 });
+  }
+  try {
+    const result = await session.send({ type: 'cancel_subagent', subagentId });
+    return json({ success: true, data: result ?? null });
+  } catch (error) {
+    return rpcErrorResponse(error);
+  }
+}
+
+/** `POST /api/sessions/:sessionId/subagents/:subagentId/steer` — body `{ message }`. */
+export async function steerSubagent({ request, params }: ActionFunctionArgs) {
+  const sessionId = requireParam(params, 'sessionId');
+  const subagentId = requireParam(params, 'subagentId');
+  if (!sessionId || !subagentId) return json({ error: 'Missing session or subagent id' }, { status: 400 });
+  if (request.method !== 'POST') return json({ error: 'Method not allowed' }, { status: 405 });
+  if (!SUBAGENT_ID_RE.test(subagentId) || subagentId.length > SUBAGENT_ID_MAX_LENGTH) {
+    return json({ error: 'Invalid subagent id', code: 'invalid_subagent_id' }, { status: 400 });
+  }
+
+  const body = (await request.json().catch(() => null)) as { message?: unknown } | null;
+  const message = typeof body?.message === 'string' ? body.message.trim() : '';
+  if (!message) return json({ error: 'message is required' }, { status: 400 });
+
+  const session = getRpcSession(sessionId);
+  if (!session?.isAlive()) {
+    return json({ error: 'Session is not running', code: 'session_not_running' }, { status: 409 });
+  }
+  try {
+    const result = await session.send({ type: 'steer_subagent', subagentId, message });
+    return json({ success: true, data: result ?? null });
+  } catch (error) {
+    return rpcErrorResponse(error);
+  }
+}