@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/omp/rpc/session-commands.ts

@@ -0,0 +1,293 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Command dispatch for a live omp session. Extracted from AgentSessionWrapper
+ * (rpc-manager.ts) so that file stays under the repo's per-file size ceiling.
+ * The host object exposes the wrapper's runtime state; behavior is unchanged.
+ */
+
+import { RpcCommandError, RpcCommandTimeoutError } from '@/server/lib/omp/rpc/process';
+import { AGENT_BUSY_MESSAGE, AGENT_BUSY_REFUSAL_RE, AWAITING_AGENT_START_TIMEOUT_MS, GET_STATE_TIMEOUT_MS, IMAGE_BEARING_COMMANDS, PASSTHROUGH_COMMANDS, PROMPT_ACK_TIMEOUT_MS, RESTARTING_MESSAGE, STEER_ACK_TIMEOUT_MS, WebRpcError, toImageContents, type RpcSessionState, validateAgentImages } from '@/server/lib/omp/rpc/constants';
+import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { scheduleQueueDelivery } from '@/server/lib/queue/delivery.server';
+import { clearStreamStatus, markStreamStatus } from '@/shared/lib/omp/session/stream-state.server';
+import { buildWebState } from '@/server/lib/omp/rpc/web-state';
+import {
+  refuseTuiOnlyPrompt,
+  refuseWhenBlockedOnDialog,
+  settleCommandTimeout,
+  type SessionCommandHost,
+} from '@/server/lib/omp/rpc/session-command-guards';
+
+export type { SessionCommandHost } from '@/server/lib/omp/rpc/session-command-guards';
+
+export async function dispatchSessionCommand(host: SessionCommandHost, command: Record<string, unknown>): Promise<unknown> {
+  if (host.restarting) throw new WebRpcError(RESTARTING_MESSAGE, 'session_restarting');
+  if (!host.isAlive()) throw new Error('Session is no longer running');
+  host.idle.reset();
+  const type = command.type as string;
+
+  if (IMAGE_BEARING_COMMANDS.has(type)) {
+    const imageError = validateAgentImages(command.images);
+    if (imageError) throw new Error(imageError);
+  }
+
+  switch (type) {
+    case 'prompt': {
+      if (host.bashRunning) {
+        throw new Error('Cannot send a prompt while a shell command is running');
+      }
+      // Checked before the streaming-behavior split: a steer of a TUI-only
+      // command is just as meaningless as a fresh one. `streaming` keeps the
+      // refusal from clearing a running turn's flags when the prompt was a
+      // steer aimed at that turn.
+      if (refuseTuiOnlyPrompt(host, command.message, Boolean(command.streamingBehavior))) return null;
+      const streamingBehavior = command.streamingBehavior as 'steer' | 'followUp' | undefined;
+      // The live `stream` row starts with the DISPATCH, not with agent_start:
+      // the spawn/ack round trip that precedes agent_start must not read as
+      // "nothing happened" in the sidebar after the user hit send. Skipped
+      // while a turn already streams — that row belongs to the running turn,
+      // and this dispatch's failure must never roll it back.
+      //
+      // `isRunning()`, NOT `streaming`: `streaming` only flips at `agent_start`,
+      // so a dispatch that arrives DURING the ack round trip of an earlier one
+      // saw `streaming === false` and claimed the turn slot for itself. The
+      // own `/kabmo-mode` commands are dispatched on that path (the
+      // plan-review `republish`, a mode toggle) and answer `agentInvoked:false`,
+      // so the claim made them release the RUNNING turn's `stream` row and emit
+      // a `prompt_result` — which the client folds as "the run settled",
+      // blanking the generating indicator mid-answer. `isRunning()` is true for
+      // the whole dispatch (promptRunning is set before the ack), so a secondary
+      // command now owns nothing and settles nothing.
+      const ownsStreamRow = !streamingBehavior && !host.isRunning() && Boolean(host.sessionId);
+      // A prompt that never started a turn leaves no run behind, so the row we
+      // wrote must go — unless a turn began meanwhile, which owns it now.
+      const releaseStreamRow = (): void => {
+        if (ownsStreamRow && !host.streaming) void clearStreamStatus(host.sessionId);
+      };
+      if (!streamingBehavior) {
+        host.promptRunning = true;
+        host.promptDispatchPendingCount += 1;
+        host.awaitingAgentStart = false;
+        host.awaitingAgentStartDeadline = 0;
+        host.continuationGraceUntil = 0;
+        // The row carries the model this run is served by: known here because
+        // the warmup `get_state` (and any `set_model`) reconciled it. A later
+        // `agent_start` re-marks the same row without a model, and the upsert's
+        // COALESCE keeps this pair.
+        if (ownsStreamRow) void markStreamStatus(host.sessionId, 'stream', host.runModel);
+      }
+      try {
+        const ack = await host.proc.sendCommand<{ agentInvoked?: boolean } | undefined>({
+          type: 'prompt',
+          message: command.message as string,
+          ...(toImageContents(command.images) ? { images: toImageContents(command.images) } : {}),
+          ...(streamingBehavior ? { streamingBehavior } : {}),
+        }, PROMPT_ACK_TIMEOUT_MS);
+        if (ack?.agentInvoked === false && !streamingBehavior) {
+          // Only a dispatch that CLAIMED the turn slot may settle it. A command
+          // dispatched while a run is in flight — a mode toggle, the plan-review
+          // `republish` — also answers `agentInvoked:false`, and settling on it
+          // cleared the RUNNING turn's flags and emitted a `prompt_result` the
+          // client folds as "the run ended", blanking the generating indicator
+          // mid-answer (measured). The non-owning dispatch leaves everything
+          // alone; the run it arrived under is still in flight.
+          if (ownsStreamRow) {
+            host.promptRunning = false;
+            host.awaitingAgentStart = false;
+            host.awaitingAgentStartDeadline = 0;
+            releaseStreamRow();
+            host.emit({ type: 'prompt_result', agentInvoked: false });
+            // Nothing ran (agent was idle and declined) — the queue may hold the
+            // next item; give it the same delivery window a run end would.
+            scheduleQueueDelivery(host);
+          }
+        } else if (!streamingBehavior && ack?.agentInvoked !== false && ownsStreamRow) {
+          host.awaitingAgentStart = true;
+          host.awaitingAgentStartDeadline = Date.now() + AWAITING_AGENT_START_TIMEOUT_MS;
+          // Nothing else watches this deadline. Without the watchdog a dispatch
+          // whose turn never opens (omp accepted the prompt and emitted no
+          // `agent_start` — measured with Kabmo's own `/kabmo-mode`,
+          // whose bare `{success:true}` ack reads as a run) leaves
+          // `promptRunning` true forever AND the `stream` row owned by a LIVE
+          // process, which the sidebar heal cannot reach. See the method.
+          host.armAgentStartWatchdog?.();
+        }
+      } catch (error) {
+        host.promptRunning = false;
+        host.awaitingAgentStart = false;
+        host.awaitingAgentStartDeadline = 0;
+        releaseStreamRow();
+        // The ack may simply be queued behind a running turn: omp accepts the
+        // prompt before the turn it starts. No reset, and the client must not
+        // resend — a duplicate prompt would run twice.
+        if (error instanceof RpcCommandTimeoutError) await settleCommandTimeout(host);
+        // omp's typed refusal for a PLAIN prompt dispatched mid-turn
+        // (`AgentBusyError`). Nothing was delivered, so this is not a command
+        // failure: the caller queues the message and re-sends it when the run
+        // ends. Reporting it as `session_busy` is what lets a client that did
+        // not know a run was in flight (a second tab, a reload, another
+        // instance) recover instead of losing the prompt.
+        if (error instanceof RpcCommandError && AGENT_BUSY_REFUSAL_RE.test(error.message)) {
+          throw new WebRpcError(AGENT_BUSY_MESSAGE, 'agent_busy');
+        }
+        throw error;
+      } finally {
+        if (!streamingBehavior) {
+          host.promptDispatchPendingCount = Math.max(0, host.promptDispatchPendingCount - 1);
+        }
+      }
+      return null;
+    }
+
+    case 'abort':
+      // Refused rather than waited on: a pending dialog parks omp's command
+      // loop, so this ack would never arrive (see the guard). Stop's own
+      // escalation (`force_reset`) is the escape hatch and is NOT guarded —
+      // destroying the child must stay reachable from a blocked session.
+      refuseWhenBlockedOnDialog(host);
+      await host.proc.sendCommand({ type: 'abort' });
+      host.promptRunning = false;
+      host.awaitingAgentStart = false;
+      host.awaitingAgentStartDeadline = 0;
+      host.continuationGraceUntil = 0;
+      if (host.sessionId) void markStreamStatus(host.sessionId, 'abort');
+      return null;
+
+    // Escape hatch behind the Stop button: `abort` resolves only once the turn
+    // actually stops, so a session wedged on a subagent never answers it. The
+    // caller (shared/lib/chat/omp/abort.ts) escalates to this after a grace
+    // period and accepts losing the in-flight work.
+    case 'force_reset':
+      await host.destroyAndWait();
+      return null;
+
+    case 'get_state': {
+      try {
+        const state = await host.proc.sendCommand<RpcSessionState>({ type: 'get_state' }, GET_STATE_TIMEOUT_MS);
+        return buildWebState(host, state);
+      } catch (error) {
+        if (error instanceof RpcCommandTimeoutError) await settleCommandTimeout(host);
+        throw error;
+      }
+    }
+
+    case 'set_model': {
+      const { provider, modelId } = command as { provider: string; modelId: string };
+      const model = await host.proc.sendCommand<{ id: string; provider: string }>({ type: 'set_model', provider, modelId });
+      // The ack names the model omp RESOLVED (an alias or fallback may differ
+      // from the request), which is what the indicator must report.
+      host.runModel = { provider: model.provider, modelId: model.id };
+      return { id: model.id, provider: model.provider };
+    }
+
+    case 'set_fast_mode': {
+      const enabled = command.enabled === true;
+      const result = await host.proc.sendCommand<{ enabled?: boolean; active?: boolean }>({ type: 'set_fast_mode', enabled });
+      host.fastModeEnabled = result?.enabled ?? enabled;
+      return { enabled: host.fastModeEnabled, active: result?.active ?? false };
+    }
+
+    case 'compact': {
+      try {
+        host.compacting = true;
+        try {
+          const result = await host.proc.sendCommand<{ summary?: string; tokensBefore?: number; estimatedTokensAfter?: number }>({
+            type: 'compact',
+            ...(command.customInstructions ? { customInstructions: command.customInstructions } : {}),
+          });
+          return result;
+        } finally {
+          host.compacting = false;
+        }
+      } finally {
+        clearSessionFileCaches();
+      }
+    }
+
+    case 'abort_compaction':
+      await host.proc.sendCommand({ type: 'abort' });
+      return null;
+
+    case 'set_session_name': {
+      const name = (command.name as string | undefined)?.trim();
+      if (!name) throw new Error('Session name cannot be empty');
+      await host.proc.sendCommand({ type: 'set_session_name', name });
+      clearSessionFileCaches();
+      return null;
+    }
+
+    case 'get_commands': {
+      const data = await host.proc.sendCommand<{ commands: unknown[] }>({
+        type: 'get_available_commands',
+      });
+      return data;
+    }
+
+    case 'bash': {
+      if (host.isRunning()) {
+        throw new Error('Cannot run a shell command while the session is busy');
+      }
+      host.bashRunning = true;
+      try {
+        return await host.proc.sendCommand<{ output?: string; exitCode?: number }>({ type: 'bash', command: command.command as string });
+      } finally {
+        host.bashRunning = false;
+        clearSessionFileCaches();
+      }
+    }
+
+    case 'extension_ui_response': {
+      // Fire-and-forget: omp answers ask/approval dialogs without a response
+      // frame, so a request/response round-trip would time out.
+      const { id, ...rest } = command as { id: string; [key: string]: unknown };
+      if (!id) throw new Error('extension_ui_response requires an id');
+      host.proc.sendFrame({ type: 'extension_ui_response', id, ...rest });
+      // Answered — stop offering it to clients that attach later.
+      host.resolvePendingUiDialog(id);
+      return null;
+    }
+
+    case 'steer':
+    case 'follow_up': {
+      if (!host.isRunning()) {
+        throw new WebRpcError('The session is idle — start a prompt first.', 'session_idle');
+      }
+      if (refuseTuiOnlyPrompt(host, command.message, true)) return null;
+      // Bounded, but never reset: omp queues the message before it parks on a
+      // pending dialog, so a late ack means "delivered, ack held" — destroying
+      // the child would discard the very steer the user is waiting on. The
+      // caller gets `rpc_command_timeout` and the message still runs.
+      await host.proc.sendCommand({
+        type,
+        message: command.message as string,
+        ...(toImageContents(command.images) ? { images: toImageContents(command.images) } : {}),
+      }, STEER_ACK_TIMEOUT_MS);
+      return null;
+    }
+
+    default: {
+      if (PASSTHROUGH_COMMANDS.has(type)) {
+        // `abort_and_prompt` is the client's steer (Ctrl+Enter / Send Now) and
+        // waits on an ack like `abort` does, so it takes the same two rules: a
+        // pending dialog refuses it up front, and a late ack times out instead
+        // of hanging the request. `abort_and_prompt` is deliberately NOT reset
+        // on timeout — omp aborts the old turn and queues the new prompt before
+        // it acks, so the work is already done and destroying the child would
+        // only throw it away.
+        if (type === 'abort_and_prompt') {
+          refuseWhenBlockedOnDialog(host);
+          const result = await host.proc.sendCommand(command as { type: string }, STEER_ACK_TIMEOUT_MS);
+          return result ?? null;
+        }
+        const result: unknown = await host.proc.sendCommand(command as { type: string });
+        if (type === 'set_thinking_level') clearSessionFileCaches();
+        return result ?? null;
+      }
+      throw new Error(`Unsupported command: ${type}`);
+    }
+  }
+}

package/src/server/lib/omp/rpc/session-registration.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Registering a freshly-spawned omp child in the session registry.
+ *
+ * Split out of `session-registry.ts` (which sits at the repo's per-file ceiling)
+ * so the identity rules read as one unit rather than being interleaved with the
+ * spawn plumbing.
+ *
+ * The whole reason this is not two `registry.set` calls is that the id omp
+ * REPORTS can differ from the id the caller ASKED for, and the registry has to
+ * answer for both.
+ */
+
+import type { AgentSessionWrapper } from '@/server/lib/omp/rpc/manager';
+
+/**
+ * Register `created` under the id omp reported AND, when that differs, under the
+ * id the caller asked for.
+ *
+ * The two differ whenever omp FORKS a resumed session instead of continuing it.
+ * omp 18.10.0 made that routine rather than exotic: a session marked moved away
+ * (`omp session moved`, or a `departed` transfer marker) forks on resume, and omp
+ * writes the fork to a fresh file under a fresh id — verified on 18.10.0 by
+ * resuming a departed file, which answered a new `sessionId` and a new
+ * `sessionFile` in another directory.
+ *
+ * Keying the registry on the requested id alone therefore MISSED on the very next
+ * message: the send re-resolved the ORIGINAL file and spawned again, so one
+ * conversation produced a chain of forks — a child and a sidebar row each, with
+ * nothing on screen to explain the duplication. Measured on the real spawn path:
+ * two sends on one departed session produced two children with two different ids
+ * where the second must have found the first.
+ *
+ * The alias makes the registry answer for the id the CLIENT holds — its URL, its
+ * topic subscription, its next POST. It is only installed for an id no other
+ * wrapper owns (the caller reaches this point only after its own lookup missed),
+ * and it is removed with the wrapper, so a dead child can never answer for it.
+ */
+export function registerSpawnedSession(
+  registry: Map<string, AgentSessionWrapper>,
+  created: AgentSessionWrapper,
+  requestedId: string,
+  realSessionId: string,
+): void {
+  created.onDestroy(() => {
+    if (registry.get(created.sessionId) === created) registry.delete(created.sessionId);
+    if (registry.get(realSessionId) === created) registry.delete(realSessionId);
+    // The alias must go too, or a dead wrapper would answer for the requested id
+    // and every later send would treat the session as live.
+    if (registry.get(requestedId) === created) registry.delete(requestedId);
+  });
+  registry.set(realSessionId, created);
+  if (requestedId !== realSessionId && !registry.has(requestedId)) registry.set(requestedId, created);
+}

package/src/server/lib/omp/rpc/session-registry.test.ts

@@ -0,0 +1,234 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The global session registry's identity bookkeeping and the prewarm claim.
+ *
+ * Two things here are load-bearing and invisible at the call site. The claim in
+ * `startNewRpcSession` is a synchronous check-and-set: if it were not, two
+ * sends racing the same prewarmed child would both adopt it and one would talk
+ * to a process the other owns. And the registry's lookups answer the sidebar's
+ * "needs input" and "running" badges, so a session reported under the wrong id
+ * (or reported while dead) shows a spinner or a prompt on the wrong row.
+ *
+ * No omp child is ever spawned: the prewarmed entry is a fake handle, and only
+ * paths that adopt or read one are exercised. The cold-spawn branches
+ * (mode mismatch, dead entry, spawn failure) all end in a real spawn and are
+ * therefore not covered here.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { removeDir } from '@/test-support/remove-dir';
+
+import {
+  getAwaitingInputSessionIds,
+  getLiveRunSessionIds,
+  getRpcSession,
+  listRpcSessions,
+  startNewRpcSession,
+} from '@/server/lib/omp/rpc/session-registry';
+import { stopDiscoveryRootsWatch } from '@/server/lib/omp/config/roots-watch.server';
+import type { AgentSessionWrapper } from '@/server/lib/omp/rpc/manager';
+import { DEFAULT_APPROVAL_MODE } from '@/shared/lib/omp/config/access-mode';
+
+interface FakeSession {
+  session: AgentSessionWrapper;
+  destroys: number;
+  fireDestroy(): void;
+}
+
+function makeSession(options: {
+  sessionId: string;
+  cwd?: string;
+  alive?: boolean;
+  running?: boolean;
+  dialogs?: number;
+}): FakeSession {
+  const alive = options.alive ?? true;
+  let destroys = 0;
+  let destroyCallback: (() => void) | null = null;
+  const fake = {
+    sessionId: options.sessionId,
+    cwd: options.cwd ?? process.cwd(),
+    isAlive: () => alive,
+    isRunning: () => options.running ?? false,
+    getPendingUiDialogs: () =>
+      Array.from({ length: options.dialogs ?? 0 }, (_, index) => ({ type: 'extension_ui_request', id: `dialog-${index}` })),
+    onDestroy: (callback: () => void) => {
+      destroyCallback = callback;
+    },
+    destroyAndWait: async () => {
+      destroys += 1;
+    },
+  };
+  return {
+    session: fake as unknown as AgentSessionWrapper,
+    get destroys() {
+      return destroys;
+    },
+    fireDestroy: () => destroyCallback?.(),
+  } as FakeSession;
+}
+
+let root: string;
+let savedDbPath: string | undefined;
+let savedAgentDir: string | undefined;
+let savedSyncWorkspace: string | undefined;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), 'kabmo-test-'));
+  savedDbPath = Bun.env.KABMO_DB_PATH;
+  savedAgentDir = Bun.env.PI_CODING_AGENT_DIR;
+  savedSyncWorkspace = Bun.env.SYNC_WORKSPACE;
+  // A throwaway database and agent dir keep the discovery-roots reconcile (which
+  // every adopt path awaits) inside the temp tree instead of the user's config.
+  Bun.env.KABMO_DB_PATH = join(root, 'db.sqlite');
+  Bun.env.PI_CODING_AGENT_DIR = join(root, 'agent');
+  Bun.env.SYNC_WORKSPACE = 'false';
+  delete globalThis.__ompSessions;
+  delete globalThis.__ompStartLocks;
+  delete globalThis.__ompPrewarmed;
+  delete globalThis.__kabmoDb;
+});
+
+afterEach(() => {
+  stopDiscoveryRootsWatch();
+  delete globalThis.__ompSessions;
+  delete globalThis.__ompStartLocks;
+  delete globalThis.__ompPrewarmed;
+  // CLOSE the db handle before dropping it and deleting the tree: a bare
+  // `delete` abandons the connection, and on Windows the still-open handle makes
+  // the `rm` fail with EBUSY.
+  globalThis.__kabmoDb?.resolved?.raw.close();
+  delete globalThis.__kabmoDb;
+  if (savedDbPath === undefined) delete Bun.env.KABMO_DB_PATH;
+  else Bun.env.KABMO_DB_PATH = savedDbPath;
+  if (savedAgentDir === undefined) delete Bun.env.PI_CODING_AGENT_DIR;
+  else Bun.env.PI_CODING_AGENT_DIR = savedAgentDir;
+  if (savedSyncWorkspace === undefined) delete Bun.env.SYNC_WORKSPACE;
+  else Bun.env.SYNC_WORKSPACE = savedSyncWorkspace;
+  removeDir(root);
+});
+
+function registry(): Map<string, AgentSessionWrapper> {
+  globalThis.__ompSessions ??= new Map();
+  return globalThis.__ompSessions;
+}
+
+function prewarmPool(): Map<string, never> {
+  globalThis.__ompPrewarmed ??= new Map();
+  return globalThis.__ompPrewarmed as unknown as Map<string, never>;
+}
+
+describe('registry lookups', () => {
+  test('a live session is found by id, an unknown id is not', () => {
+    const fake = makeSession({ sessionId: 'sess-1' });
+    registry().set('sess-1', fake.session);
+    expect(getRpcSession('sess-1')).toBe(fake.session);
+    expect(getRpcSession('sess-2')).toBeUndefined();
+  });
+
+  test('a dead session is dropped from the live list but stays addressable', () => {
+    const live = makeSession({ sessionId: 'live' });
+    const dead = makeSession({ sessionId: 'dead', alive: false });
+    registry().set('live', live.session);
+    registry().set('dead', dead.session);
+    expect(listRpcSessions()).toEqual([live.session]);
+    expect(getRpcSession('dead')).toBe(dead.session);
+  });
+});
+
+describe('getAwaitingInputSessionIds', () => {
+  test('only an alive session with a pending dialog is reported', () => {
+    registry().set('idle', makeSession({ sessionId: 'idle' }).session);
+    registry().set('asking', makeSession({ sessionId: 'asking', dialogs: 1 }).session);
+    registry().set('dead-asking', makeSession({ sessionId: 'dead-asking', alive: false, dialogs: 1 }).session);
+    expect(getAwaitingInputSessionIds()).toEqual(['asking']);
+  });
+
+  test('a session whose own id is empty is reported under its registry key', () => {
+    registry().set('map-key', makeSession({ sessionId: '', dialogs: 2 }).session);
+    expect(getAwaitingInputSessionIds()).toEqual(['map-key']);
+  });
+});
+
+describe('getLiveRunSessionIds', () => {
+  test('reports running sessions only, and de-duplicates the identity fallback', () => {
+    registry().set('running', makeSession({ sessionId: 'running', running: true }).session);
+    registry().set('idle', makeSession({ sessionId: 'idle' }).session);
+    registry().set('dead-running', makeSession({ sessionId: 'dead-running', alive: false, running: true }).session);
+    registry().set('map-key', makeSession({ sessionId: '', running: true }).session);
+    expect(getLiveRunSessionIds()).toEqual(new Set(['running', 'map-key']));
+  });
+});
+
+describe('startNewRpcSession claims a prewarmed entry', () => {
+  test('the claim is synchronous: the entry is marked and removed before readiness resolves', async () => {
+    const fake = makeSession({ sessionId: 'sess-1' });
+    let release: (wrapper: AgentSessionWrapper) => void = () => {};
+    const ready = new Promise<AgentSessionWrapper>((resolve) => {
+      release = resolve;
+    });
+    const entry = { cwd: root, approvalMode: DEFAULT_APPROVAL_MODE, modeEnv: undefined, ready, claimed: false };
+    prewarmPool().set(root, entry as never);
+
+    const started = startNewRpcSession(root);
+    // Nothing has been adopted yet, but the entry is already spoken for: a
+    // second caller (or the recycle pass) can no longer take it.
+    expect(entry.claimed).toBe(true);
+    expect(prewarmPool().has(root)).toBe(false);
+
+    release(fake.session);
+    const result = await started;
+    expect(result.session).toBe(fake.session);
+    expect(result.realSessionId).toBe('sess-1');
+    expect(fake.destroys).toBe(0);
+  });
+
+  test('the adopted wrapper is registered under its real id and leaves on destroy', async () => {
+    const fake = makeSession({ sessionId: 'sess-42' });
+    prewarmPool().set(root, {
+      cwd: root,
+      approvalMode: DEFAULT_APPROVAL_MODE,
+      modeEnv: undefined,
+      ready: Promise.resolve(fake.session),
+      claimed: false,
+    } as never);
+
+    await startNewRpcSession(root);
+    expect(getRpcSession('sess-42')).toBe(fake.session);
+    expect(listRpcSessions()).toEqual([fake.session]);
+
+    fake.fireDestroy();
+    expect(getRpcSession('sess-42')).toBeUndefined();
+  });
+
+  test('a prewarmed entry for another cwd is left untouched', async () => {
+    const other = join(root, 'other-workspace');
+    const fake = makeSession({ sessionId: 'sess-7' });
+    const otherEntry = {
+      cwd: other,
+      approvalMode: DEFAULT_APPROVAL_MODE,
+      modeEnv: undefined,
+      ready: Promise.resolve(fake.session),
+      claimed: false,
+    };
+    prewarmPool().set(other, otherEntry as never);
+    prewarmPool().set(root, {
+      cwd: root,
+      approvalMode: DEFAULT_APPROVAL_MODE,
+      modeEnv: undefined,
+      ready: Promise.resolve(makeSession({ sessionId: 'sess-8' }).session),
+      claimed: false,
+    } as never);
+
+    await startNewRpcSession(root);
+    expect(otherEntry.claimed).toBe(false);
+    expect(prewarmPool().get(other)).toBe(otherEntry as never);
+  });
+});