ompchamber 1.2.0 → 2.0.0

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

@@ -33,6 +33,9 @@ function makeHost(options: {
   sessionName?: string;
   sessionId?: string;
   inFlight?: boolean;
+  pending?: boolean;
+  requested?: boolean;
+  windowUntil?: number;
 }): { host: AutoTitleHost; proc: FakeProc } {
   const proc: FakeProc = {
     commands: [],
@@ -51,7 +54,9 @@ function makeHost(options: {
     host: {
       sessionId: 'sess-1',
       autoTitleInFlight: options.inFlight ?? false,
-      autoTitleWindowUntil: 0,
+      autoTitleWindowUntil: options.windowUntil ?? 0,
+      autoTitlePending: options.pending ?? true,
+      autoTitleRequested: options.requested ?? false,
       proc: proc as unknown as AutoTitleHost['proc'],
     },
     proc,
@@ -66,7 +71,7 @@ function sentRenames(proc: FakeProc): Array<Record<string, unknown>> {
 describe('triggerAutoSessionTitle', () => {
   test('names an unnamed session through omp own /rename', async () => {
     const { host, proc } = makeHost({});
-    await triggerAutoSessionTitle(host);
+    await triggerAutoSessionTitle(host, 'opening');
 
     const renames = sentRenames(proc);
     expect(renames).toHaveLength(1);
@@ -77,17 +82,21 @@ describe('triggerAutoSessionTitle', () => {
   });
 
   test('never overwrites a name the operator set', async () => {
-    const { host, proc } = makeHost({ sessionName: 'My Deliberate Name' });
-    await triggerAutoSessionTitle(host);
-
-    expect(sentRenames(proc)).toHaveLength(0);
-    // No request was sent, so nothing may claim the output window either.
-    expect(host.autoTitleWindowUntil).toBe(0);
+    // At either stage: the name is re-read from omp, so a rename made in
+    // another tab survives both the early attempt and the fallback.
+    for (const stage of ['opening', 'settle'] as const) {
+      const { host, proc } = makeHost({ sessionName: 'My Deliberate Name' });
+      await triggerAutoSessionTitle(host, stage);
+
+      expect(sentRenames(proc)).toHaveLength(0);
+      // No request was sent, so nothing may claim the output window either.
+      expect(host.autoTitleWindowUntil).toBe(0);
+    }
   });
 
   test('treats a whitespace-only name as unnamed', async () => {
     const { host, proc } = makeHost({ sessionName: '   ' });
-    await triggerAutoSessionTitle(host);
+    await triggerAutoSessionTitle(host, 'opening');
 
     expect(sentRenames(proc)).toHaveLength(1);
   });
@@ -97,18 +106,107 @@ describe('triggerAutoSessionTitle', () => {
     // between the trigger and the read) — titling this session would name the
     // wrong one.
     const { host, proc } = makeHost({ sessionId: 'someone-else' });
-    await triggerAutoSessionTitle(host);
+    await triggerAutoSessionTitle(host, 'opening');
 
     expect(sentRenames(proc)).toHaveLength(0);
   });
 
   test('does not stack a second request while one is in flight', async () => {
     const { host, proc } = makeHost({ inFlight: true });
-    await triggerAutoSessionTitle(host);
+    await triggerAutoSessionTitle(host, 'opening');
 
     expect(sentRenames(proc)).toHaveLength(0);
     expect(proc.commands).toHaveLength(0);
   });
+
+  test('the early attempt does not consume the eligibility latch', async () => {
+    // The fallback exists precisely because the early attempt can come back
+    // empty. If `opening` consumed the latch, a provider error at the first
+    // user message would leave the session unnamed for good.
+    const { host } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+
+    expect(host.autoTitlePending).toBe(true);
+    expect(host.autoTitleRequested).toBe(true);
+  });
+
+  test('the fallback retries once the early attempt came back empty', async () => {
+    // The real sequence: the early `/rename` is accepted, omp answers
+    // `command_output` (consuming the window) with no title, and the run then
+    // ends — the fallback is what names the session.
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+    expect(consumeAutoTitleOutput(host)).toBe(true);
+
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(sentRenames(proc)).toHaveLength(2);
+    expect(host.autoTitlePending).toBe(false);
+  });
+
+  test('the fallback stands down while the early generation is in flight', async () => {
+    // A short run can end before the tiny model answers (~4s). Re-asking there
+    // would reserve a new title revision and cancel the generation already in
+    // flight, for a title derived from the same opening turn.
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+    expect(host.autoTitleWindowUntil).toBeGreaterThan(Date.now());
+
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(sentRenames(proc)).toHaveLength(1);
+    // The latch is still consumed: the attempt in flight owns this
+    // conversation's title from here.
+    expect(host.autoTitlePending).toBe(false);
+  });
+
+  test('fires the early attempt once per run', async () => {
+    // A queued steer message also settles as a user message inside the same
+    // run; re-asking on it would cancel the first generation for no gain.
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+    await triggerAutoSessionTitle(host, 'opening');
+
+    expect(sentRenames(proc)).toHaveLength(1);
+  });
+
+  test('titles from the first run only', async () => {
+    // The regression this latch exists for: a second turn used to fire its own
+    // `/rename`, and omp derives that title from the NEWEST turns — so the
+    // session ended up named after message two.
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host, 'opening');
+    await triggerAutoSessionTitle(host, 'settle');
+    expect(sentRenames(proc)).toHaveLength(1);
+
+    // A later run reaches neither stage with the latch consumed.
+    await triggerAutoSessionTitle(host, 'opening');
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(sentRenames(proc)).toHaveLength(1);
+  });
+
+  test('skips a conversation that already has a first turn behind it', async () => {
+    // A child resumed for an existing session (`--resume` after the idle
+    // reclaim) reports a non-zero message count, so its next turn must not
+    // name it — the session is either titled already or deliberately unnamed.
+    const { host, proc } = makeHost({ pending: false });
+    await triggerAutoSessionTitle(host, 'opening');
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(sentRenames(proc)).toHaveLength(0);
+    expect(host.autoTitleWindowUntil).toBe(0);
+  });
+
+  test('consumes the latch even when generation is skipped', async () => {
+    // A declined generation must not leave the door open for the next turn:
+    // otherwise a first turn whose title the provider refused gets re-asked
+    // after every later message, which is the same bug one step later.
+    const { host } = makeHost({});
+    await triggerAutoSessionTitle(host, 'settle');
+
+    expect(host.autoTitlePending).toBe(false);
+  });
 });
 
 describe('auto-title output window', () => {

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

@@ -15,23 +15,51 @@
  *
  * The generate path itself is NOT gated: `/rename` with no args reaches
  * `session.generateTitle()` through `executeAcpBuiltinSlashCommand`, which
- * rpc-mode dispatches for a `prompt` frame before any turn starts. Verified
- * against omp 18.2.10 — the ack returns `{agentInvoked:false}` immediately, the
- * generation lands ~4s later as `session_info_update` + `command_output`, and
- * no entry is written to the transcript.
+ * rpc-mode dispatches for a `prompt` frame BEFORE that frame is forwarded as a
+ * turn — so the request can be sent at any point in a run and never becomes
+ * part of the conversation. Verified against omp 18.3.0 — the ack returns
+ * `{agentInvoked:false}` immediately, the generation lands ~3-4s later as
+ * `session_info_update` + `command_output`, and no entry is written to the
+ * transcript.
  *
  * WHY THE NAME MUST BE EMPTY FIRST: `/rename` persists through
  * `setSessionName(title, "user")`. omp's own guard only refuses an `"auto"`
  * write over a `"user"` title, so a `/rename` fired against an already-named
  * session would overwrite the operator's own name. The unnamed check below is
- * therefore the safety property, not a nicety — it is re-read from `get_state`
+ * therefore a safety property, not a nicety — it is re-read from `get_state`
  * on every attempt rather than cached, so a rename made in another tab is
  * respected.
  *
- * Firing after every settled run (not just the first) mirrors omp: a session
- * whose opening message was a bare greeting stays unnamed, and the next real
- * message titles it. The low-signal filter on omp's side returns no title for
- * such input, so the retry costs one tiny-model call and nothing else.
+ * ONE ATTEMPT PER CONVERSATION, RETRIED ONCE INSIDE THE FIRST RUN. The title
+ * is derived from the FIRST run and never re-asked after it. omp's `/rename`
+ * derives its title from the newest turns (and `generateRenameTitle` reserves a
+ * fresh title revision, which cancels any generation still in flight), so a
+ * second attempt after turn two would name the session after whatever the
+ * conversation had become by then — and could even discard a slow first
+ * generation.
+ *
+ * There are exactly two triggers, both inside that first run:
+ *
+ *   1. the first settled USER message — the earliest point at which the
+ *      transcript carries the conversation's opening intent. (`agent_start` is
+ *      too early to be usable: omp pushes it before the turn opens, so the
+ *      transcript is still empty there and the title context comes back blank.
+ *      See the `message_end` branch of frame-fold.)
+ *   2. the terminal `agent_end`, as a fallback when the early attempt produced
+ *      no title — a provider error, a timeout, a child that went away, or the
+ *      tiny model declining.
+ *
+ * The eligibility latch `autoTitlePending` is consumed by the fallback, so that
+ * is the last chance this conversation gets and a later run can never title it.
+ * `autoTitleRequested` is what keeps the early trigger from firing again on a
+ * queued steer message. A session that a skill invocation opened has no
+ * user-role message at all (omp delivers it as a `custom` message), so the
+ * early trigger never fires there and the fallback is what names it.
+ *
+ * A first message that omp's low-signal filter rejects ("hi") therefore leaves
+ * the session unnamed for good, which is the honest outcome: the fallback does
+ * re-ask, and omp declines a second time (measured on omp 18.3.0 — the
+ * rejection is a property of the opening message, not of when it is asked).
  */
 
 import { readSettingsJson } from '@/server/lib/db/settings-store';
@@ -63,15 +91,24 @@ const GENERATE_TITLE_COMMAND = '/rename';
  */
 const AUTO_TITLE_OUTPUT_WINDOW_MS = 60_000;
 
-/** Wrapper state this module reads and writes. The in-flight flag and the
- *  output window are owned by the caller because they are per-session runtime
- *  state, not policy. */
+/** Wrapper state this module reads and writes. The in-flight flag, the
+ *  output window and the one-shot latch are owned by the caller because they
+ *  are per-session runtime state, not policy. */
 export interface AutoTitleHost {
   sessionId: string;
   autoTitleInFlight: boolean;
   /** Epoch ms until which frames belong to our own background rename; 0 when
    *  no request is outstanding. */
   autoTitleWindowUntil: number;
+  /** True only while this conversation is still eligible for a title at all.
+   *  Seeded from omp's own message count when the child is spawned, so it
+   *  survives an idle reclaim (a `--resume` child reports the messages it
+   *  restored) and is consumed by the first run's terminal `agent_end` — the
+   *  fallback's last chance. */
+  autoTitlePending: boolean;
+  /** True once the early attempt (the first settled user message) has been
+   *  made, so a queued steer message cannot re-ask inside the same run. */
+  autoTitleRequested: boolean;
   proc: {
     sendCommand<T = unknown>(command: { type: string; [key: string]: unknown }, timeoutMs?: number): Promise<T>;
   };
@@ -113,14 +150,49 @@ async function isAutoTitleEnabled(): Promise<boolean> {
 }
 
 /**
- * Generate and persist a session title when the session has none yet.
+ * Which of the two attempts inside the first run is asking.
+ *
+ * - `opening` — the first settled USER message. Earliest usable point, and it
+ *   does NOT consume the eligibility latch, so `settle` can still retry.
+ * - `settle` — the terminal `agent_end`. The fallback, and the attempt that
+ *   consumes the latch: after it, this conversation is never titled again.
+ */
+export type AutoTitleStage = 'opening' | 'settle';
+
+/**
+ * Ask omp to name this session from its opening turns.
  *
- * Called once per settled run. Every bail-out is deliberate: a named session
- * must never be renamed by this path, and a generation already in flight must
- * not be duplicated. Failures are swallowed — an auto-title is a convenience,
- * and the next turn retries.
+ * Called twice at most, both inside the conversation's first run: once when the
+ * first user message settles (`opening`), and once at the terminal `agent_end`
+ * as a fallback (`settle`). A second run never gets either — see the module
+ * doc for why a title derived from a later turn is the bug this gate prevents.
+ *
+ * Every bail-out is deliberate: a named session is never renamed by this path
+ * (the name is re-read from omp, so a rename made in another tab is respected),
+ * a generation already in flight is never duplicated, and failures are
+ * swallowed — an auto-title is a convenience, and a session whose opening
+ * message was low-signal ("hi") simply keeps its placeholder.
  */
-export async function triggerAutoSessionTitle(host: AutoTitleHost): Promise<void> {
+export async function triggerAutoSessionTitle(host: AutoTitleHost, stage: AutoTitleStage): Promise<void> {
+  if (!host.autoTitlePending) return;
+  if (stage === 'opening') {
+    // One early attempt per run. A queued steer message also settles as a user
+    // message inside the same run, and re-asking on it would cancel the first
+    // generation for no gain — the context is the same turn either way.
+    if (host.autoTitleRequested) return;
+    // Consumed before the first await: two user messages settling in the same
+    // tick must not both pass the gate.
+    host.autoTitleRequested = true;
+  } else {
+    // Consumed before the first await: the fallback is this conversation's last
+    // chance, and two settles must never both pass the gate.
+    host.autoTitlePending = false;
+    // The early attempt is still generating. Its `command_output` has not
+    // arrived, so omp is mid-generation and a second `/rename` now would
+    // reserve a new title revision and cancel it — same title context, wasted
+    // model call. Leave the early attempt to finish.
+    if (host.autoTitleWindowUntil > Date.now()) return;
+  }
   if (host.autoTitleInFlight || !host.sessionId) return;
   if (!(await isAutoTitleEnabled())) return;
 
@@ -128,7 +200,9 @@ export async function triggerAutoSessionTitle(host: AutoTitleHost): Promise<void
   try {
     // Re-read the name from omp rather than trusting a cached value: a rename
     // made in another tab (or by omp's own TUI on the same session file) would
-    // otherwise be overwritten by the `"user"` write `/rename` performs.
+    // otherwise be overwritten by the `"user"` write `/rename` performs. This is
+    // also what makes the fallback a no-op when the early attempt already
+    // landed — the name is simply there by then.
     const state = await host.proc.sendCommand<RpcSessionState>({ type: 'get_state' }, GET_STATE_TIMEOUT_MS);
     if (state.sessionName?.trim()) return;
     // The session changed under us (a reset, or a `switch_session`): the name
@@ -145,7 +219,8 @@ export async function triggerAutoSessionTitle(host: AutoTitleHost): Promise<void
     markTitleRequestSent(host);
   } catch {
     // Provider error, timeout, or a child that went away — leave the session
-    // unnamed; the next settled run tries again.
+    // unnamed; the settle attempt (or the next run, for an aborted turn) tries
+    // again.
   } finally {
     host.autoTitleInFlight = false;
   }

package/src/server/lib/omp/session/sidebar-data.server.ts

@@ -22,7 +22,7 @@ import { isValidSessionSortOption, sortFolders } from '@/shared/lib/workspace/si
 import { loadOmpSidebarData } from '@/server/lib/omp/session/reader';
 import { sessionHasSubagents } from '@/server/lib/omp/session/subagent-presence';
 import { healStaleStreamStatuses, loadStreamStatuses } from '@/shared/lib/omp/session/stream-state.server';
-import { getAwaitingInputSessionIds, getRunningRpcSessionIds } from '@/server/lib/omp/rpc/session-registry';
+import { getAwaitingInputSessionIds } from '@/server/lib/omp/rpc/session-registry';
 import type { SessionItemData, SessionSortOption, WorkspaceFolderData } from '@/shared/types';
 import type { OmpSession } from '@/shared/types/omp/session';
 
@@ -110,17 +110,22 @@ export async function loadSidebarData(): Promise<SessionListPayload> {
   const sidebarSort = await serverSidebarSort();
 
   // Live stream status per session (spinner / one-shot done badge), written by
-  // the RPC manager on agent_start/agent_end and by the abort command. `stream`
-  // rows whose session is no longer running are stale (restart mid-run) and heal to
-  // `finish` right here — the authoritative status travels with the same
-  // fetch that refreshes the sidebar list.
+  // the RPC manager on agent_start/agent_end and by the abort command. A
+  // `stream` row whose owning chamber process is gone is stale (that process
+  // exited mid-run) and heals to `finish` right here — the authoritative status
+  // travels with the same fetch that refreshes the sidebar list.
   const streamStatuses: Record<string, 'stream' | 'finish' | 'abort'> = {};
   // Sessions blocked on a dialog nobody has answered yet. Read live from the
   // process registry (never persisted): the child that owns the question is the
   // same thing that owns the flag, so a restart cannot leave a stale badge.
   const awaitingInput = new Set<string>();
   if (!mock) {
-    await healStaleStreamStatuses(new Set(getRunningRpcSessionIds()));
+    // The database is shared by every chamber instance on the machine, so a
+    // `stream` row may belong to a process this one cannot see. Ownership is
+    // read from the row itself (its `owner_pid`) against OS liveness — never
+    // against this process's own runtime registry, which would make two
+    // instances report different statuses for the same run.
+    await healStaleStreamStatuses();
     Object.assign(streamStatuses, await loadStreamStatuses());
     for (const id of getAwaitingInputSessionIds()) awaitingInput.add(id);
   }

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

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * What a queue dispatch actually sends: the model snapshot it was queued with,
+ * the attachment payloads it can carry, and the timer-free nudge.
+ *
+ * The scheduling contract — when a delivery runs, defers, or recovers — lives
+ * in `delivery.server.test.ts`; both files share `delivery-harness.ts`, which
+ * owns the store mock and the fake clock.
+ */
+
+import { afterAll, afterEach, describe, expect, jest, mock, test } from 'bun:test';
+import type { QueuedMessage } from '@/shared/types/chat';
+import { MODEL, beginQueueTest, deliverQueueNow, flush, makeHost, queue, queueItem, settleDelivery } from '@/server/lib/queue/delivery-harness';
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+afterAll(() => {
+  mock.restore();
+});
+
+describe('queue dispatch', () => {
+  test('delivers the head with the model snapshot it was queued with', async () => {
+    const sessionId = beginQueueTest();
+    queue.set(sessionId, [queueItem('queued hello')]);
+    const { host, sent } = makeHost(sessionId);
+
+    await settleDelivery(host);
+
+    expect(sent).toEqual([
+      { type: 'set_model', provider: 'kenari', modelId: 'deepseek-v4-pro' },
+      { type: 'set_thinking_level', level: 'max' },
+      { type: 'prompt', message: 'queued hello', accessMode: 'yolo' },
+    ]);
+    expect(queue.get(sessionId)).toEqual([]);
+  });
+
+  test("an 'auto' thinking level is left to the session", async () => {
+    const sessionId = beginQueueTest();
+    queue.set(sessionId, [queueItem('no level', { ...MODEL, thinkingLevel: 'auto' })]);
+    const { host, sent } = makeHost(sessionId);
+
+    await settleDelivery(host);
+
+    expect(sent).toEqual([
+      { type: 'set_model', provider: 'kenari', modelId: 'deepseek-v4-pro' },
+      { type: 'prompt', message: 'no level', accessMode: 'yolo' },
+    ]);
+  });
+
+  test('an item with no model snapshot is sent without touching the model', async () => {
+    const sessionId = beginQueueTest();
+    queue.set(sessionId, [queueItem('session model', null)]);
+    const { host, sent } = makeHost(sessionId);
+
+    await settleDelivery(host);
+
+    expect(sent).toEqual([{ type: 'prompt', message: 'session model' }]);
+  });
+
+  // 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
+  // fields the delivery must use instead — `dataBase64` for the bytes, `type`
+  // for the media type, `content` for an inline-able text file.
+  test('a queued image rides its persisted base64 payload', async () => {
+    const sessionId = beginQueueTest();
+    const item = queueItem('with image', null);
+    item.attachments = [
+      { id: 'i', name: 'shot.png', type: 'image/png', size: 4, preview: 'blob:http://x/1', dataBase64: 'iVBORw0KGgo=' },
+    ] as QueuedMessage['attachments'];
+    queue.set(sessionId, [item]);
+    const { host, sent } = makeHost(sessionId);
+
+    await settleDelivery(host);
+
+    expect(sent).toEqual([
+      {
+        type: 'prompt',
+        message: 'with image',
+        images: [{ type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' }],
+      },
+    ]);
+  });
+
+  test('a queued text file is inlined into the delivered prompt', async () => {
+    const sessionId = beginQueueTest();
+    const item = queueItem('review this', null);
+    item.attachments = [
+      { id: 't', name: 'notes.md', type: 'text/markdown', size: 5, preview: '', content: '# hi' },
+    ] as QueuedMessage['attachments'];
+    queue.set(sessionId, [item]);
+    const { host, sent } = makeHost(sessionId);
+
+    await settleDelivery(host);
+
+    const prompt = sent.find((c) => c.type === 'prompt');
+    expect(prompt?.message).toBe('review this\n\nAttached file: notes.md\n```markdown\n# hi\n```');
+  });
+
+  test('an attachment without a payload is not sent as a blank image', async () => {
+    const sessionId = beginQueueTest();
+    const item = queueItem('no payload', null);
+    item.attachments = [
+      { id: 'i', name: 'broken.png', type: 'image/png', size: 4, preview: 'blob:http://x/1', dataBase64: '' },
+    ] as QueuedMessage['attachments'];
+    queue.set(sessionId, [item]);
+    const { host, sent } = makeHost(sessionId);
+
+    await settleDelivery(host);
+
+    expect(sent).toEqual([{ type: 'prompt', message: 'no payload' }]);
+  });
+
+  // The nudge is the RECOVERY path, so it must not itself depend on the
+  // mechanism it recovers from. A long-lived `--hot` dev server can stop firing
+  // `setTimeout` callbacks entirely; a nudge that merely re-armed the settle
+  // timer would fail exactly like the delivery it was meant to rescue. Here no
+  // timer is ever advanced — the delivery must complete synchronously.
+  test('a nudge delivers immediately without waiting on any timer', async () => {
+    const sessionId = beginQueueTest();
+    queue.set(sessionId, [queueItem('nudged')]);
+    const { host, sent } = makeHost(sessionId);
+
+    // The boolean is the client poll's stop signal: it is how the page knows a
+    // tick actually sent something rather than finding nothing to do.
+    const delivered = await deliverQueueNow(host);
+    await flush();
+
+    expect(delivered).toBe(true);
+    expect(sent.filter((c) => c.type === 'prompt').length).toBe(1);
+    expect(queue.get(sessionId)).toEqual([]);
+  });
+
+  test('a nudge on a busy session leaves the item queued and reports no delivery', async () => {
+    const sessionId = beginQueueTest();
+    queue.set(sessionId, [queueItem('busy nudge')]);
+    const { host, sent } = makeHost(sessionId);
+    host.isBusy = () => true;
+
+    const delivered = await deliverQueueNow(host);
+    await flush();
+
+    expect(delivered).toBe(false);
+    expect(sent).toEqual([]);
+    expect(queue.get(sessionId)?.length).toBe(1);
+  });
+
+  test('a nudge with an empty queue reports no delivery', async () => {
+    const sessionId = beginQueueTest();
+    const { host } = makeHost(sessionId);
+
+    const delivered = await deliverQueueNow(host);
+
+    expect(delivered).toBe(false);
+  });
+});

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

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared harness for the queue-delivery tests — `delivery.server.test.ts`
+ * (scheduling, retry, wedge recovery) and `delivery-dispatch.server.test.ts`
+ * (what a dispatch sends, and the timer-free nudge).
+ *
+ * The store mock is registered HERE, exactly once. `mock.module` swaps a
+ * registry entry that `delivery.server.ts` resolves at import time, so a second
+ * registration in another test file would leave one file's tests driving a
+ * queue map the other file asserts against — a split that passes or fails by
+ * file order. The in-memory queue below is that shared map; per-test isolation
+ * comes from `beginQueueTest`'s unique session id, not from a fresh module.
+ *
+ * Time is fake: every test drives the clock explicitly, so nothing here waits
+ * on the wall clock.
+ */
+
+import { jest, mock } from 'bun:test';
+import type { QueuedMessage } from '@/shared/types/chat';
+import type { QueueDeliveryHost } from '@/server/lib/queue/delivery.server';
+
+/** In-memory stand-in for the SQLite-backed queue. */
+export const queue = new Map<string, QueuedMessage[]>();
+
+mock.module('@/server/lib/queue/store.server', () => ({
+  claimHeadQueueItem: async (sessionId: string): Promise<QueuedMessage | null> => {
+    const items = queue.get(sessionId);
+    return items?.shift() ?? null;
+  },
+  hasQueuedItem: async (sessionId: string): Promise<boolean> => (queue.get(sessionId)?.length ?? 0) > 0,
+  requeueHeadQueueItem: async (sessionId: string, item: QueuedMessage): Promise<void> => {
+    const items = queue.get(sessionId) ?? [];
+    items.unshift(item);
+    queue.set(sessionId, items);
+  },
+}));
+
+// Dynamic import is load-bearing: the module must be evaluated AFTER the
+// `mock.module` call above, so its store bindings resolve to the mock. A static
+// import is hoisted above the registration and would bind the real SQLite store.
+export const { deliverQueueNow, scheduleQueueDelivery } = await import('@/server/lib/queue/delivery.server');
+
+export const MODEL = { provider: 'kenari', modelId: 'deepseek-v4-pro', thinkingLevel: 'max', accessMode: 'yolo' as const };
+
+export function queueItem(text: string, model: QueuedMessage['model'] = MODEL): QueuedMessage {
+  return { id: `item-${text}`, text, attachments: [], model };
+}
+
+/** Records the RPCs a delivery pushes at the session. */
+export function makeHost(sessionId: string): { host: QueueDeliveryHost; sent: Record<string, unknown>[] } {
+  const sent: Record<string, unknown>[] = [];
+  const host: QueueDeliveryHost = {
+    sessionId,
+    isAlive: () => true,
+    isBusy: () => false,
+    send: async (command) => {
+      sent.push(command);
+      return {};
+    },
+  };
+  return { host, sent };
+}
+
+/** Let the delivery's promise chain settle without advancing the clock. */
+export async function flush(): Promise<void> {
+  for (let i = 0; i < 20; i++) await Promise.resolve();
+}
+
+let counter = 0;
+
+/** Per-test setup: an empty queue, fake timers, and a session id of its own. */
+export function beginQueueTest(): string {
+  const sessionId = `queue-test-${counter++}`;
+  queue.clear();
+  jest.useFakeTimers();
+  return sessionId;
+}
+
+/** One scheduled delivery, past the 500ms settle delay and settled. */
+export async function settleDelivery(host: QueueDeliveryHost): Promise<void> {
+  scheduleQueueDelivery(host);
+  jest.advanceTimersByTime(600);
+  await flush();
+}