@kabmo-labs/kabmo 0.5.2 → 0.6.0

package/src/server/lib/omp/session/title-request.server.test.ts

@@ -0,0 +1,183 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The shared `/rename` request lifecycle: claims, dispatch order, and the
+ * barrier a following prompt waits on.
+ *
+ * Each rule here was a defect measured against a real child:
+ *
+ *   - a single claim slot meant the SECOND attempt's claim overwrote the first,
+ *     so the first one's `command_output` reached the timeline as a notice row;
+ *   - unserialized dispatches raced, and omp cancels a superseded rename
+ *     WITHOUT emitting the frame that releases its claim;
+ *   - a prompt admitted before a finished run's rename let the rename name a
+ *     conversation that had already moved on.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  awaitTitleDispatch,
+  consumeAutoTitleOutput,
+  markTitleRequestSent,
+  releaseTitleClaim,
+  sendTitleRequest,
+  waitForTitleOutcome,
+  type TitleRequestHost,
+} from '@/server/lib/omp/session/title-request.server';
+
+interface FakeProc {
+  commands: Array<Record<string, unknown>>;
+  /** Held open so a test controls when a dispatch acknowledges. */
+  gate?: Promise<void>;
+  sendCommand<T>(command: { type: string; [key: string]: unknown }): Promise<T>;
+}
+
+function makeHost(options: { gate?: Promise<void> } = {}): { host: TitleRequestHost; proc: FakeProc } {
+  const proc: FakeProc = {
+    commands: [],
+    gate: options.gate,
+    async sendCommand<T>(command: { type: string; [key: string]: unknown }): Promise<T> {
+      proc.commands.push(command);
+      if (command.type === 'prompt' && proc.gate) await proc.gate;
+      return undefined as T;
+    },
+  };
+  const host: TitleRequestHost = {
+    sessionId: 'sess-1',
+    autoTitleWindowUntil: 0,
+    autoTitleClaims: 0,
+    autoTitleDispatch: null,
+    proc,
+  };
+  return { host, proc };
+}
+
+describe('title claims', () => {
+  test('one claim per request, and a second frame passes through', () => {
+    const { host } = makeHost();
+    markTitleRequestSent(host);
+
+    expect(consumeAutoTitleOutput(host)).toBe(true);
+    // The operator's own command output must reach the timeline.
+    expect(consumeAutoTitleOutput(host)).toBe(false);
+  });
+
+  test('two outstanding requests keep two claims', () => {
+    // The early attempt and the settle fallback can both be unanswered at once.
+    // One slot let the first one's frame render as a notice row.
+    const { host } = makeHost();
+    markTitleRequestSent(host);
+    markTitleRequestSent(host);
+
+    expect(host.autoTitleClaims).toBe(2);
+    expect(consumeAutoTitleOutput(host)).toBe(true);
+    expect(consumeAutoTitleOutput(host)).toBe(true);
+    expect(consumeAutoTitleOutput(host)).toBe(false);
+    expect(host.autoTitleWindowUntil).toBe(0);
+  });
+
+  test('an expired claim is dropped instead of swallowing an operator frame', () => {
+    const { host } = makeHost();
+    markTitleRequestSent(host);
+    host.autoTitleWindowUntil = Date.now() - 1;
+
+    expect(consumeAutoTitleOutput(host)).toBe(false);
+    expect(host.autoTitleClaims).toBe(0);
+  });
+
+  test('a release keeps the window armed while another claim is live', () => {
+    const { host } = makeHost();
+    markTitleRequestSent(host);
+    markTitleRequestSent(host);
+
+    releaseTitleClaim(host);
+    expect(host.autoTitleWindowUntil).toBeGreaterThan(Date.now());
+  });
+});
+
+/** Drain the microtask queue, so a promise that WOULD have resolved has. */
+async function flush(): Promise<void> {
+  for (let i = 0; i < 8; i += 1) await Promise.resolve();
+}
+
+describe('dispatch order', () => {
+  test('a second request is dispatched only after the first acknowledges', async () => {
+    const { promise: gate, resolve: open } = Promise.withResolvers<void>();
+    const { host, proc } = makeHost({ gate });
+
+    // The slot is owned by the CALLER, exactly as `triggerAutoSessionTitle`
+    // claims it before the first await.
+    const first = sendTitleRequest(host, '/rename', null);
+    host.autoTitleDispatch = first.then(
+      () => undefined,
+      () => undefined,
+    );
+    const second = sendTitleRequest(host, '/rename', host.autoTitleDispatch);
+    await flush();
+    expect(proc.commands).toHaveLength(1);
+
+    open();
+    await Promise.all([first, second]);
+    expect(proc.commands).toHaveLength(2);
+  });
+
+  test('a prompt that follows waits for the dispatch already in flight', async () => {
+    const { promise: gate, resolve: open } = Promise.withResolvers<void>();
+    const { host, proc } = makeHost({ gate });
+
+    const pending = sendTitleRequest(host, '/rename', null);
+    host.autoTitleDispatch = pending.then(
+      () => undefined,
+      () => undefined,
+    );
+
+    let released = false;
+    const barrier = awaitTitleDispatch(host).then(() => {
+      released = true;
+    });
+    // The dispatch has not acknowledged yet, so the barrier must still be
+    // waiting — this is the ordering the requirement depends on. Nothing but
+    // `open()` can resolve it, so a microtask flush is a complete check.
+    await flush();
+    expect(released).toBe(false);
+    expect(proc.commands).toHaveLength(1);
+
+    open();
+    await Promise.all([pending, barrier]);
+    expect(released).toBe(true);
+  });
+
+  test('the barrier is a no-op when nothing is in flight', async () => {
+    const { host } = makeHost();
+    await awaitTitleDispatch(host);
+    expect(host.autoTitleDispatch).toBeNull();
+  });
+});
+
+describe('waiting for the outcome', () => {
+  test('resolves when the claim is consumed, so the model pin outlives the ack', async () => {
+    const { host } = makeHost();
+    markTitleRequestSent(host);
+
+    let done = false;
+    const waiting = waitForTitleOutcome(host, 50).then(() => {
+      done = true;
+    });
+    await flush();
+    expect(done).toBe(false);
+
+    consumeAutoTitleOutput(host);
+    await waiting;
+    expect(done).toBe(true);
+  });
+
+  test('resolves immediately when no request is outstanding', async () => {
+    const { host } = makeHost();
+    await waitForTitleOutcome(host, 50);
+    expect(host.autoTitleClaims).toBe(0);
+  });
+});

package/src/server/lib/omp/session/title-request.server.ts

@@ -0,0 +1,213 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * ONE background `/rename` request: its dispatch order, its claim on the frames
+ * that answer it, and the barrier a following prompt waits on.
+ *
+ * Split from `auto-title.server.ts` because two callers share it — Kabmo's
+ * auto-titling and the session row's "Rename with AI" — and because the three
+ * rules below each fix a defect that made a rename silently not happen.
+ *
+ * ## 1. Claims are COUNTED, not a single slot
+ *
+ * A title request is answered by a `command_output` ("Session renamed to …" /
+ * "Could not generate a session title"), which must stay out of the timeline.
+ * The frame carries no correlation id, so attribution is by request. One slot
+ * was enough while only one request could be outstanding; a settle attempt that
+ * follows an early one re-arms the slot and the FIRST request's frame then
+ * reaches the timeline as a notice row. Measured on a real session: the early
+ * attempt answered 52 s in, after the run had already ended.
+ *
+ * ## 2. Dispatches are SERIALIZED on the host
+ *
+ * omp's `RpcUserInputGate` orders the operator's prompts, but Kabmo sends its
+ * own `/rename` straight to the process — outside that gate. Two dispatches
+ * therefore race their frames, and a request whose dispatch loses the race is
+ * cancelled by omp (`renameTitle` reserves a title revision) without ever
+ * emitting the `command_output` that would release its claim.
+ *
+ * ## 3. A prompt that follows a run end WAITS for the dispatch
+ *
+ * The requirement is that the rename a finished run asked for is ON THE WIRE
+ * before the next prompt is. Both are separate frames on one stdin, so without
+ * a barrier the operator's second prompt can be admitted first and the rename
+ * then names a conversation that has already moved on. The wait is bounded and
+ * cheap: the dispatch resolves on omp's ack (measured ~3 ms), never on the
+ * generation.
+ */
+
+import { PROMPT_ACK_TIMEOUT_MS } from '@/server/lib/omp/rpc/constants';
+
+/** omp's builtin that generates a title from the conversation. Sent with no
+ *  args so omp derives it through its own `renameTitle`. */
+export const GENERATE_TITLE_COMMAND = '/rename';
+
+/**
+ * How long a claim may suppress a `command_output`. Long enough for a title
+ * generation (measured 4-52 s on a real child), short enough that a claim whose
+ * request was cancelled cannot swallow an operator's own command output for
+ * the rest of the session.
+ */
+export const TITLE_CLAIM_WINDOW_MS = 60_000;
+
+/**
+ * Ceiling on the barrier a prompt pays. The dispatch itself is an ack round
+ * trip (~3 ms); this only bounds a child that stopped answering, so a wedged
+ * rename can never hold the operator's next prompt.
+ */
+export const TITLE_DISPATCH_BARRIER_MS = 10_000;
+
+/** How long the session-model pin is held for a request whose outcome never
+ *  arrives (a cancelled generation emits no frame). */
+export const TITLE_OUTCOME_HOLD_MS = 65_000;
+
+/** Host surface a title request needs. Owned by the session wrapper. */
+export interface TitleRequestHost {
+  sessionId: string;
+  /** Epoch ms until which claims may suppress a `command_output`; 0 when no
+   *  claim is outstanding. */
+  autoTitleWindowUntil: number;
+  /** Outstanding requests, one claim each. */
+  autoTitleClaims: number;
+  /** In-flight DISPATCH (not generation), or null when the wire is idle. */
+  autoTitleDispatch: Promise<void> | null;
+  proc: {
+    sendCommand<T = unknown>(command: { type: string; [key: string]: unknown }, timeoutMs?: number): Promise<T>;
+  };
+}
+
+/** Resolvers waiting for a claim to be consumed, keyed by the host so a
+ *  re-evaluated module cannot leak them into another wrapper. */
+const outcomeWaiters = new WeakMap<object, Set<() => void>>();
+
+function notifyClaimChanged(host: TitleRequestHost): void {
+  const listeners = outcomeWaiters.get(host);
+  if (!listeners) return;
+  for (const listener of [...listeners]) listener();
+}
+
+/**
+ * Claim the frames this request is about to produce.
+ *
+ * Called BEFORE the send, never after its ack: omp answers the prompt within
+ * the same tick (measured ~3 ms), so a claim armed on the ack can already be
+ * too late for the frame it was meant to cover.
+ */
+export function markTitleRequestSent(host: TitleRequestHost): void {
+  host.autoTitleClaims += 1;
+  host.autoTitleWindowUntil = Date.now() + TITLE_CLAIM_WINDOW_MS;
+}
+
+/** Drop one claim (a request that never reached omp, or one whose frame
+ *  arrived). */
+export function releaseTitleClaim(host: TitleRequestHost): void {
+  if (host.autoTitleClaims > 0) host.autoTitleClaims -= 1;
+  if (host.autoTitleClaims === 0) host.autoTitleWindowUntil = 0;
+  notifyClaimChanged(host);
+}
+
+/**
+ * True when this frame answers a title request and must stay out of the
+ * timeline, consuming its claim. One frame per claim; a second `command_output`
+ * inside the window belongs to something the operator typed.
+ */
+export function consumeAutoTitleOutput(host: TitleRequestHost): boolean {
+  if (host.autoTitleClaims <= 0) return false;
+  if (host.autoTitleWindowUntil !== 0 && Date.now() > host.autoTitleWindowUntil) {
+    // The claim outlived its window: the request was cancelled or never
+    // answered, and an operator's own output must not be swallowed by it.
+    host.autoTitleClaims = 0;
+    host.autoTitleWindowUntil = 0;
+    notifyClaimChanged(host);
+    return false;
+  }
+  releaseTitleClaim(host);
+  return true;
+}
+
+/**
+ * Send `/rename`, ordered behind any dispatch already in flight.
+ *
+ * `after` is the slot to queue behind, and it must be captured BEFORE the
+ * caller claims the slot for itself — passing the host's current slot from
+ * inside a run that already owns it would make the promise wait on itself.
+ *
+ * Resolves on omp's ack — the generation continues on its own and is reported
+ * by the frames the claim covers.
+ */
+export function sendTitleRequest(
+  host: TitleRequestHost,
+  message: string = GENERATE_TITLE_COMMAND,
+  after: Promise<void> | null = host.autoTitleDispatch,
+): Promise<void> {
+  // The slot is owned by the CALLER (`triggerAutoSessionTitle` /
+  // `awaitTitleFrame`), which claims it synchronously so a prompt sent in the
+  // same tick is ordered behind the whole request, not just its dispatch. This
+  // function only queues behind what was already there.
+  return (after ?? Promise.resolve()).then(async () => {
+    markTitleRequestSent(host);
+    try {
+      await host.proc.sendCommand({ type: 'prompt', message }, PROMPT_ACK_TIMEOUT_MS);
+    } catch (error) {
+      // A request that never reached omp can never be answered, so its claim
+      // would sit on the window and swallow the next real command output.
+      releaseTitleClaim(host);
+      throw error;
+    }
+  });
+}
+
+/**
+ * Wait for the dispatch already in flight, bounded. A prompt that follows a run
+ * end calls this so the rename the run asked for is written to the child's
+ * stdin first (see rule 3 in the module doc).
+ */
+export async function awaitTitleDispatch(host: { autoTitleDispatch?: Promise<void> | null }): Promise<void> {
+  const pending = host.autoTitleDispatch;
+  if (!pending) return;
+  const { promise, resolve } = Promise.withResolvers<void>();
+  const timer = setTimeout(resolve, TITLE_DISPATCH_BARRIER_MS);
+  timer.unref?.();
+  try {
+    await Promise.race([pending, promise]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Wait until the claims outstanding at call time have been consumed (or the
+ * deadline passes).
+ *
+ * This is what keeps the session-model pin in place for the whole request: omp
+ * resolves the title role when the generation STARTS and again for the card
+ * request that follows a successful title, so releasing the pin on the ack
+ * would name the session with the configured role — the exact failure the pin
+ * exists to avoid.
+ */
+export function waitForTitleOutcome(host: TitleRequestHost, timeoutMs = TITLE_OUTCOME_HOLD_MS): Promise<void> {
+  const start = host.autoTitleClaims;
+  if (start <= 0) return Promise.resolve();
+  const { promise, resolve } = Promise.withResolvers<void>();
+  const listeners = outcomeWaiters.get(host) ?? new Set<() => void>();
+  outcomeWaiters.set(host, listeners);
+  let settled = false;
+  const finish = () => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    listeners.delete(check);
+    if (listeners.size === 0 && outcomeWaiters.get(host) === listeners) outcomeWaiters.delete(host);
+    resolve();
+  };
+  const check = () => {
+    if (host.autoTitleClaims < start) finish();
+  };
+  listeners.add(check);
+  const timer = setTimeout(finish, timeoutMs);
+  timer.unref?.();
+  return promise;
+}

package/src/server/lib/panels/baseline.server.test.ts

@@ -27,12 +27,12 @@ import { isolateDb, releaseDb } from '@/test-support/isolated-db';
 import { getDb } from '@/server/db.server';
 import { writeSettingsJson } from '@/server/lib/db/settings-store';
 
-beforeEach(() => {
-  isolateDb();
+beforeEach(async () => {
+  await isolateDb();
 });
 
-afterEach(() => {
-  releaseDb();
+afterEach(async () => {
+  await releaseDb();
 });
 
 describe('baselines', () => {

package/src/server/lib/panels/compat.server.test.ts

@@ -55,19 +55,19 @@ async function scanWith(manifest: unknown) {
   return discoverPanelPlugins();
 }
 
-beforeEach(() => {
+beforeEach(async () => {
   root = fs.mkdtempSync(join(tmpdir(), 'kabmo-compat-'));
   process.env.KABMO_MARKETPLACE_DIR = root;
   fs.mkdirSync(root, { recursive: true });
   // The scan reads the disabled set, which is a DATABASE read — so the suite
   // needs a database of its own before the first scan, or it opens the real one.
-  isolateDb();
+  await isolateDb();
   invalidatePanelScan();
 });
 
-afterEach(() => {
+afterEach(async () => {
   delete process.env.KABMO_MARKETPLACE_DIR;
-  releaseDb();
+  await releaseDb();
   invalidatePanelScan();
   fs.rmSync(root, { recursive: true, force: true });
 });

package/src/server/lib/panels/registry-bundled.server.test.ts

@@ -53,18 +53,18 @@ function withStore(run: (bundled: string) => Promise<void>): Promise<void> {
   });
 }
 
-beforeEach(() => {
+beforeEach(async () => {
   root = fs.mkdtempSync(join(tmpdir(), 'kabmo-store-'));
   process.env.KABMO_MARKETPLACE_DIR = root;
   // The scan reads the disabled set, so it needs a database of its own before
   // the first read — see `@/test-support/isolated-db`.
-  isolateDb();
+  await isolateDb();
   invalidatePanelScan();
 });
 
-afterEach(() => {
+afterEach(async () => {
   delete process.env.KABMO_MARKETPLACE_DIR;
-  releaseDb();
+  await releaseDb();
   invalidatePanelScan();
   fs.rmSync(root, { recursive: true, force: true });
 });

package/src/server/lib/panels/registry.server.test.ts

@@ -62,19 +62,19 @@ function writePlugin(dirName: string, manifest: unknown): string {
   return dir;
 }
 
-beforeEach(() => {
+beforeEach(async () => {
   root = fs.mkdtempSync(join(tmpdir(), 'kabmo-marketplace-'));
   process.env.KABMO_MARKETPLACE_DIR = root;
   // The scan reads the disabled set, which is a DATABASE read — so the suite
   // needs a database of its own before the first scan, or it opens the real one
   // and a `setPluginEnabled` below rewrites a live install.
-  isolateDb();
+  await isolateDb();
   invalidatePanelScan();
 });
 
-afterEach(() => {
+afterEach(async () => {
   delete process.env.KABMO_MARKETPLACE_DIR;
-  releaseDb();
+  await releaseDb();
   invalidatePanelScan();
   fs.rmSync(root, { recursive: true, force: true });
 });

package/src/server/lib/panels/state.server.test.ts

@@ -38,12 +38,12 @@ async function readChamberBlob(): Promise<Record<string, unknown>> {
   return readSettingsJson<Record<string, unknown>>(db, 'omp_chamber_settings', {});
 }
 
-beforeEach(() => {
-  isolateDb();
+beforeEach(async () => {
+  await isolateDb();
 });
 
-afterEach(() => {
-  releaseDb();
+afterEach(async () => {
+  await releaseDb();
 });
 
 describe('hiddenRightPanels migration', () => {

package/src/server/lib/panels/sync.server.test.ts

@@ -47,7 +47,7 @@ function writePlugin(dir: string, manifest: unknown, files: Record<string, strin
   }
 }
 
-beforeEach(() => {
+beforeEach(async () => {
   root = fs.mkdtempSync(join(tmpdir(), 'omp-sync-work-'));
   store = fs.mkdtempSync(join(tmpdir(), 'omp-sync-store-'));
   work = fs.mkdtempSync(join(tmpdir(), 'omp-sync-repos-'));
@@ -55,14 +55,14 @@ beforeEach(() => {
   process.env.KABMO_BUNDLED_MARKETPLACE_DIR = store;
   // The baseline and refusal records live in `app_settings`, so this suite needs
   // an isolated database: a shared handle would read the developer's real one.
-  isolateDb();
+  await isolateDb();
   invalidatePanelScan();
 });
 
-afterEach(() => {
+afterEach(async () => {
   delete process.env.KABMO_MARKETPLACE_DIR;
   delete process.env.KABMO_BUNDLED_MARKETPLACE_DIR;
-  releaseDb();
+  await releaseDb();
   invalidatePanelScan();
   fs.rmSync(root, { recursive: true, force: true });
   fs.rmSync(store, { recursive: true, force: true });

package/src/server/lib/plugins/background.test.ts

@@ -26,11 +26,11 @@ let root = '';
 
 beforeAll(async () => {
   root = await mkdtemp(join(tmpdir(), 'omp-plugin-background-'));
-  isolateDb();
+  await isolateDb();
 });
 
 afterAll(async () => {
-  releaseDb();
+  await releaseDb();
   await rm(root, { recursive: true, force: true });
 });
 

package/src/server/lib/plugins/e2e.test.ts

@@ -39,7 +39,7 @@ beforeAll(async () => {
   marketplaceRoot = await mkdtemp(join(tmpdir(), 'omp-plugin-e2e-'));
   previousOverride = Bun.env.KABMO_MARKETPLACE_DIR;
   Bun.env.KABMO_MARKETPLACE_DIR = marketplaceRoot;
-  isolateDb();
+  await isolateDb();
 
   // Copy the bundled plugin into the working marketplace and build it there —
   // the same two steps an install performs.
@@ -58,7 +58,7 @@ beforeAll(async () => {
 
 afterAll(async () => {
   await disposePlugin(PLUGIN_ID);
-  releaseDb();
+  await releaseDb();
   if (previousOverride === undefined) delete Bun.env.KABMO_MARKETPLACE_DIR;
   else Bun.env.KABMO_MARKETPLACE_DIR = previousOverride;
   await rm(marketplaceRoot, { recursive: true, force: true });

package/src/server/lib/plugins/platform.test.ts

@@ -37,11 +37,11 @@ let root = '';
 
 beforeAll(async () => {
   root = await mkdtemp(join(tmpdir(), 'omp-plugin-platform-'));
-  isolateDb();
+  await isolateDb();
 });
 
 afterAll(async () => {
-  releaseDb();
+  await releaseDb();
   await rm(root, { recursive: true, force: true });
 });
 

package/src/server/lib/queue/delivery-dispatch.server.test.ts

@@ -14,6 +14,7 @@
 
 import { afterAll, afterEach, beforeAll, describe, expect, jest, mock, test } from 'bun:test';
 import type { QueuedMessage } from '@/shared/types/chat';
+import type { QueueDeliveryHost } from '@/server/lib/queue/delivery.server';
 import {
   MODEL,
   beginQueueTest,
@@ -81,6 +82,39 @@ describe('queue dispatch', () => {
     expect(sent).toEqual([{ type: 'prompt', message: 'session model' }]);
   });
 
+  // The real wrapper's `send` is a CLASS METHOD that reads its own runtime state
+  // through `this`, so a dispatch that hands it over detached runs against
+  // `undefined`. Measured in production on every queued item that carried a
+  // model snapshot: `undefined is not an object (evaluating 'e.restarting')`,
+  // the item was re-queued, and the queue retried it every 2s forever — the
+  // follow-up only ever left the queue when the operator re-sent it by hand.
+  // `makeHost`'s arrow function cannot see this, so the host here is an object
+  // whose `send` reads a field of itself.
+  test('the model snapshot and the prompt keep the session as their receiver', async () => {
+    const sessionId = beginQueueTest();
+    queue.set(sessionId, [queueItem('receiver check')]);
+    const sent: Record<string, unknown>[] = [];
+    let receiverLost = false;
+    const host: QueueDeliveryHost = {
+      sessionId,
+      isAlive: () => true,
+      isBusy: () => false,
+      // `this` is the host: the detached call sites read `restarting` off it.
+      restarting: false,
+      async send(this: { restarting: boolean }, command: Record<string, unknown>) {
+        if (this?.restarting !== false) receiverLost = true;
+        sent.push(command);
+        return {};
+      },
+    } as QueueDeliveryHost;
+
+    await settleDelivery(host);
+
+    expect(receiverLost).toBe(false);
+    expect(sent.map((c) => c.type)).toEqual(['set_model', 'set_thinking_level', 'prompt']);
+    expect(queue.get(sessionId)).toEqual([]);
+  });
+
   // Attachments reach the server as the persisted display fields only: the
   // composer's `File` never survives the queue row's JSON round trip, and its
   // image preview is a `blob:` object URL the server cannot read. These pin the

package/src/server/lib/queue/delivery.server.ts

@@ -101,9 +101,18 @@ function clearPendingTimer(sessionId: string): void {
  *  prompt's dispatcher: both send a prompt nobody typed in this tab, from the
  *  same persisted shape. */
 async function dispatchQueuedItem(session: QueueDeliveryHost, item: QueuedMessage): Promise<boolean> {
+  // BOUND, never passed detached: the wrapper's `send` reaches its own runtime
+  // state through `this`, so `applyModelSnapshot(session.send, …)` ran it against
+  // `undefined` — measured in production as `undefined is not an object
+  // (evaluating 'e.restarting')` on every queued item that carried a model
+  // snapshot. The item was then re-queued and retried every 2s forever, and the
+  // client's nudge hit the same path, so the follow-up never left the queue and
+  // only a manual re-send got it out. The waiting-prompt dispatcher binds for the
+  // same reason (`waiting/runtime.server.ts`).
+  const send = session.send.bind(session);
   try {
-    await applyModelSnapshot(session.send, item.model);
-    await session.send(promptCommand({ text: item.text, attachments: item.attachments, model: item.model }));
+    await applyModelSnapshot(send, item.model);
+    await send(promptCommand({ text: item.text, attachments: item.attachments, model: item.model }));
     return true;
   } catch (error) {
     console.error(`[queue] delivery failed for session ${session.sessionId}:`, error);