@kabmo-labs/kabmo 0.3.1 → 0.4.0

package/src/server/lib/waiting/runtime.server.ts

@@ -0,0 +1,313 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The waiting-prompt clock: a prompt held until another session finishes.
+ *
+ * Same shape as the scheduled-task runtime, and for the same reason — omp has
+ * no notion of a prompt that has not been sent, so the wait is Kabmo's own and
+ * has to outlive the tab that created it. A client-side watcher would be gone
+ * on reload, invisible to a second tab, and unable to survive a closed browser.
+ *
+ * Two triggers keep it moving, plus a tick:
+ *
+ *   1. a dependency's run end (`terminal-settle.ts`) schedules a sweep, so the
+ *      normal case dispatches within a second;
+ *   2. the follow-up queue's delivery path schedules one when it drains, so a
+ *      dependency that had a queue of its own is not waited on past its last
+ *      prompt;
+ *   3. a 5 s tick covers a lost timer, a restart, and a dependency that ends
+ *      while this process was not watching (a second Kabmo instance owns the
+ *      child, but the ROW is shared).
+ *
+ * The claim in `store.server.ts` is what makes several processes safe: only the
+ * caller whose UPDATE changed the row may spawn.
+ */
+
+import {
+  startNewRpcSession,
+  type AgentSessionWrapper,
+} from '@/server/lib/omp/rpc/manager';
+import { getRpcSession } from '@/server/lib/omp/rpc/session-registry';
+import { kabmoModeEnv } from '@/server/lib/omp/extensions/locator';
+import { hasQueuedItem } from '@/server/lib/queue/store.server';
+import { hasPendingDelivery } from '@/server/lib/queue/delivery.server';
+import { applyModelSnapshot, promptCommand } from '@/server/lib/queue/payload';
+import { loadStreamStates } from '@/shared/lib/omp/session/stream-state.server';
+import { streamRowWrittenAt } from '@/server/lib/waiting/row-clock.server';
+import type { ApprovalMode } from '@/shared/lib/omp/config/access-mode';
+import { loadPersistedAccessMode } from '@/shared/lib/omp/config/access-mode.server';
+import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
+import { publishSidebarStructure } from '@/server/lib/realtime/topics.server';
+import { withTimeout } from '@/server/lib/util/with-timeout';
+import { dependencyVerdict, type DependencyState } from '@/server/lib/waiting/settle';
+import { setWaitingSweepHandler } from '@/server/lib/waiting/sweep-trigger';
+import {
+  claimWaitingPrompt,
+  countWaitingAttempt,
+  failWaitingPrompt,
+  listWaitingPrompts,
+  markWaitingDispatched,
+  pruneWaitingPrompts,
+  requeueWaitingPrompt,
+} from '@/server/lib/waiting/store.server';
+import type { WaitingPrompt } from '@/shared/types/waiting';
+
+/** How often the clock is consulted. */
+const TICK_MS = 5_000;
+
+/** Delay before the first tick: boot work owns the first seconds. */
+const FIRST_TICK_DELAY_MS = 3_000;
+
+/** How long a spawn + delivery may take before the attempt is called failed. */
+const DISPATCH_TIMEOUT_MS = 120_000;
+
+/** A prompt whose dispatch failed this many times is reported, not retried. */
+export const MAX_DISPATCH_ATTEMPTS = 3;
+
+/** The prompt-sending surface a dispatch needs; narrower than the wrapper so a
+ *  test can drive the whole path without spawning a process. */
+export interface WaitingSessionHandle {
+  send(command: Record<string, unknown>): Promise<unknown>;
+}
+
+/**
+ * Everything a dispatch reaches outside this module, injected rather than
+ * imported at the call site — the same reason `ScheduleDeps` is: `mock.module`
+ * would swap the registry entry for every other suite in the same `bun test`
+ * run, and the store and the spawn path are both process-wide singletons.
+ */
+export interface WaitingDeps {
+  startNewRpcSession(
+    cwd: string,
+    mode?: ApprovalMode,
+    modeEnv?: Record<string, string>,
+  ): Promise<{ session: WaitingSessionHandle; realSessionId: string }>;
+  getSession(sessionId: string): AgentSessionWrapper | undefined;
+  loadStreamStates(): Promise<StreamRowMap>;
+  /** Epoch ms of a session's last status write, or null when unknown. */
+  streamRowWrittenAt(sessionId: string): Promise<number | null>;
+  hasQueuedItem(sessionId: string): Promise<boolean>;
+  hasPendingDelivery(sessionId: string): boolean;
+  loadPersistedAccessMode(): Promise<ApprovalMode>;
+  listWaitingPrompts(): Promise<WaitingPrompt[]>;
+  claimWaitingPrompt(id: string): Promise<boolean>;
+  countWaitingAttempt(id: string): Promise<number>;
+  markWaitingDispatched(id: string, sessionId: string): Promise<void>;
+  requeueWaitingPrompt(id: string, error: string): Promise<void>;
+  failWaitingPrompt(id: string, error: string): Promise<void>;
+  pruneWaitingPrompts(): Promise<number>;
+}
+
+/**
+ * Built lazily, never as a module-level constant.
+ *
+ * `terminal-settle.ts` imports this module (a run end schedules a sweep) and
+ * this module reaches back into the RPC registry — a cycle. Reading the spawn
+ * function while the registry module is still evaluating would capture an
+ * uninitialized binding, so the object is assembled at call time instead.
+ */
+function defaultDeps(): WaitingDeps {
+  return {
+    startNewRpcSession,
+    getSession: getRpcSession,
+    loadStreamStates,
+    streamRowWrittenAt,
+    hasQueuedItem,
+    hasPendingDelivery,
+    loadPersistedAccessMode,
+    listWaitingPrompts: () => listWaitingPrompts(),
+    claimWaitingPrompt,
+    countWaitingAttempt,
+    markWaitingDispatched,
+    requeueWaitingPrompt,
+    failWaitingPrompt,
+    pruneWaitingPrompts: () => pruneWaitingPrompts(),
+  };
+}
+
+interface WaitingRuntimeSlot {
+  timer: ReturnType<typeof setInterval> | null;
+  /** In-flight sweep, so a slow dispatch does not overlap the next tick. */
+  sweeping: boolean;
+  /** A one-shot sweep requested by a run end, coalesced. */
+  pending: ReturnType<typeof setTimeout> | null;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoWaitingRuntime: WaitingRuntimeSlot | undefined;
+}
+
+function slot(): WaitingRuntimeSlot {
+  return (globalThis.__kabmoWaitingRuntime ??= { timer: null, sweeping: false, pending: null });
+}
+
+/** One session's stream row, as the dependency check reads it. */
+export interface StreamRow {
+  status: 'stream' | 'finish' | 'abort';
+}
+
+/** The stream rows keyed by session id — one read serves a whole sweep. */
+export type StreamRowMap = Record<string, StreamRow>;
+
+/** The dependency's state, as `settle.ts` reads it. */
+export async function readDependencyState(
+  sessionId: string,
+  deps: WaitingDeps,
+  streams?: StreamRowMap,
+): Promise<DependencyState> {
+  const rows = streams ?? (await deps.loadStreamStates());
+  const wrapper = deps.getSession(sessionId);
+  return {
+    stream: rows[sessionId],
+    rowWrittenAt: await deps.streamRowWrittenAt(sessionId),
+    busy: wrapper ? wrapper.isBusy() : false,
+    queued: await deps.hasQueuedItem(sessionId),
+    delivering: deps.hasPendingDelivery(sessionId),
+  };
+}
+
+/**
+ * Spawn the session this prompt belongs to and send it.
+ *
+ * The prompt is assembled by `queue/payload.ts`, the same builder the follow-up
+ * queue uses: both send a prompt nobody typed in this tab, from the same
+ * persisted shape.
+ */
+async function dispatchWaitingPrompt(
+  prompt: WaitingPrompt,
+  deps: WaitingDeps,
+): Promise<{ sessionId: string }> {
+  const accessMode = prompt.model?.accessMode ?? (await deps.loadPersistedAccessMode());
+  const modeEnv = prompt.modes ? kabmoModeEnv(prompt.modes) : undefined;
+  const { session, realSessionId } = await deps.startNewRpcSession(prompt.cwd, accessMode, modeEnv);
+  // A CLOSURE, never `session.send` itself: the wrapper's `send` reaches its own
+  // runtime state through `this`, so passing the method detached makes it run
+  // against `undefined` — measured as `undefined is not an object (evaluating
+  // 'host.restarting')` and a prompt recorded as failed.
+  const send = (command: Record<string, unknown>) => session.send(command);
+  await applyModelSnapshot(send, prompt.model);
+  await send(promptCommand({ text: prompt.prompt, attachments: prompt.attachments, model: prompt.model }));
+  return { sessionId: realSessionId };
+}
+
+/**
+ * Sweep every waiting prompt whose dependency has provably finished.
+ *
+ * Serial on purpose: the claim already decided who may spawn, and several
+ * omp children booting at once fight over the CPU the first one needs.
+ */
+export async function sweepWaitingPrompts(
+  options: { now?: number; deps?: WaitingDeps } = {},
+): Promise<number> {
+  const deps = options.deps ?? defaultDeps();
+  const now = options.now ?? Date.now();
+  const waiting = (await deps.listWaitingPrompts()).filter((prompt) => prompt.status === 'waiting');
+  if (waiting.length === 0) return 0;
+
+  // One stream read for the whole pass: the rows are one table, and every
+  // prompt names a session id in it.
+  const streams = await deps.loadStreamStates();
+  let dispatched = 0;
+  for (const prompt of waiting) {
+    const state = await readDependencyState(prompt.dependsOn, deps, streams);
+    if (!dependencyVerdict(state, now).settled) continue;
+    if (!(await deps.claimWaitingPrompt(prompt.id))) continue;
+    try {
+      const { sessionId } = await withTimeout(
+        dispatchWaitingPrompt(prompt, deps),
+        DISPATCH_TIMEOUT_MS,
+        'The waiting prompt was not accepted in time.',
+      );
+      await deps.markWaitingDispatched(prompt.id, sessionId);
+      dispatched += 1;
+      // The session exists but omp has not written its transcript: the sidebar
+      // row has to come from the structure republish, exactly as it does for a
+      // spawn the composer started.
+      publishSidebarStructure();
+      emitRealtimeSignal('session-attached', sessionId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const attempts = await deps.countWaitingAttempt(prompt.id);
+      if (attempts >= MAX_DISPATCH_ATTEMPTS) {
+        await deps.failWaitingPrompt(prompt.id, message);
+      } else {
+        // The prompt has NOT been delivered: returning it to `waiting` retries
+        // on the next sweep rather than dropping a prompt the user still wants.
+        await deps.requeueWaitingPrompt(prompt.id, message);
+      }
+    }
+    emitRealtimeSignal('waiting-changed');
+  }
+  // Retention is checked on the same pass: a terminal row is only needed long
+  // enough for the client that created it to read the outcome.
+  void deps.pruneWaitingPrompts().catch(() => {});
+  return dispatched;
+}
+
+/** Run one sweep, coalescing a burst of triggers into one pass. */
+function sweepOnce(deps: WaitingDeps): void {
+  const state = slot();
+  if (state.sweeping) return;
+  state.sweeping = true;
+  sweepWaitingPrompts({ deps })
+    .catch((error) => console.error('[waiting] sweep failed:', error))
+    .finally(() => {
+      state.sweeping = false;
+    });
+}
+
+/**
+ * Ask for a sweep shortly. Called when a run ends and when a queue drains.
+ *
+ * The delay is the dependency's own settle grace: sweeping instantly would find
+ * the row it just watched end still inside its grace window and do nothing.
+ */
+export function scheduleWaitingSweep(delayMs = 1_600): void {
+  const state = slot();
+  if (state.pending) clearTimeout(state.pending);
+  state.pending = setTimeout(() => {
+    state.pending = null;
+    sweepOnce(defaultDeps());
+  }, delayMs);
+  state.pending.unref();
+}
+
+/** Start the tick. Idempotent: a second call is a no-op while one is running. */
+export function startWaitingRuntime(): void {
+  const state = slot();
+  if (state.timer) return;
+  // The queue's delivery path asks for a sweep through this slot rather than by
+  // importing this module: it would close a cycle, because this one reads the
+  // queue to decide whether a dependency still has work.
+  setWaitingSweepHandler((delayMs) => scheduleWaitingSweep(delayMs));
+  const tick = () => sweepOnce(defaultDeps());
+  setTimeout(tick, FIRST_TICK_DELAY_MS).unref();
+  state.timer = setInterval(tick, TICK_MS);
+  // A timer must never hold the process open: the listener is what keeps the
+  // server alive, and a shutdown should not wait for the next tick.
+  state.timer.unref();
+}
+
+/** Stop the tick (shutdown, tests). */
+export function stopWaitingRuntime(): void {
+  const state = slot();
+  setWaitingSweepHandler(null);
+  if (state.pending) {
+    clearTimeout(state.pending);
+    state.pending = null;
+  }
+  if (state.timer) {
+    clearInterval(state.timer);
+    state.timer = null;
+  }
+}
+
+/** Whether a prompt's dependency currently looks settled (the route's guard). */
+export async function isDependencySettled(sessionId: string, deps: WaitingDeps = defaultDeps()): Promise<boolean> {
+  return dependencyVerdict(await readDependencyState(sessionId, deps)).settled;
+}
+

package/src/server/lib/waiting/schema.server.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Waiting-prompt schema, kept out of `db.server.ts`'s bootstrap block for the
+ * same reason `btw/schema.server.ts` and `schedule/schema.server.ts` are:
+ * called once per database open, from `initSchema`.
+ *
+ * `status` is stored rather than derived. "waiting" is a clock state, and the
+ * claim that releases a prompt is a WRITE — two Kabmo instances share this file,
+ * so the row itself has to say whether the prompt was already sent.
+ */
+
+import type { DbClient } from '@/server/lib/db/client';
+
+const WAITING_SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS waiting_prompts (
+    id TEXT PRIMARY KEY,
+    pending_id TEXT,
+    depends_on TEXT NOT NULL,
+    depends_on_title TEXT,
+    message TEXT NOT NULL DEFAULT '',
+    attachments TEXT NOT NULL DEFAULT '[]',
+    provider TEXT,
+    model_id TEXT,
+    thinking_level TEXT,
+    access_mode TEXT,
+    modes TEXT,
+    cwd TEXT NOT NULL DEFAULT '',
+    folder_id INTEGER,
+    status TEXT NOT NULL,
+    session_id TEXT,
+    error TEXT,
+    attempts INTEGER NOT NULL DEFAULT 0,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS idx_waiting_status ON waiting_prompts (status, depends_on);
+`;
+
+/** Idempotent: the waiting prompts' own table, created on every database open. */
+export async function ensureWaitingSchema(db: DbClient): Promise<void> {
+  await db.exec(WAITING_SCHEMA_SQL);
+}

package/src/server/lib/waiting/settle.test.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The dependency check, which is the whole "is it finished yet?" rule.
+ *
+ * Every case below is a state a real session reaches and a condition whose
+ * absence shipped a bug of its own: `finish` written before the turn's
+ * bookkeeping settles, a follow-up queued at the run end, a delivery armed
+ * 500 ms out, and a row whose one-second clock is younger than the decision.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { dependencyVerdict, SETTLE_GRACE_MS } from '@/server/lib/waiting/settle';
+
+const NOW = 1_800_000_000_000;
+const OLD = NOW - SETTLE_GRACE_MS - 5_000;
+
+const settled = { busy: false, queued: false, delivering: false };
+
+describe('dependencyVerdict', () => {
+  test('a session still streaming is never settled', () => {
+    expect(dependencyVerdict({ ...settled, stream: { status: 'stream', updatedAt: OLD } }, NOW)).toEqual({
+      settled: false,
+      reason: 'streaming',
+    });
+  });
+
+  test('a finished run with nothing pending is settled', () => {
+    expect(dependencyVerdict({ ...settled, stream: { status: 'finish', updatedAt: OLD } }, NOW)).toEqual({
+      settled: true,
+      reason: null,
+    });
+  });
+
+  // Stop is a finish for the purposes of the wait: the user ended the run, and a
+  // dependent prompt has no reason to wait for a turn that will never resume.
+  test('an aborted run counts as finished', () => {
+    expect(dependencyVerdict({ ...settled, stream: { status: 'abort', updatedAt: OLD } }, NOW).settled).toBe(true);
+  });
+
+  test('a session with no stream row at all counts as finished', () => {
+    expect(dependencyVerdict({ ...settled, stream: undefined }, NOW)).toEqual({ settled: true, reason: 'no-row' });
+  });
+
+  // The three "there is still work here" conditions, each measured against a run
+  // whose status row already says finish.
+  test('a live wrapper that is still busy blocks the release', () => {
+    expect(dependencyVerdict({ ...settled, busy: true, stream: { status: 'finish', updatedAt: OLD } }, NOW)).toEqual({
+      settled: false,
+      reason: 'busy',
+    });
+  });
+
+  test('a queued follow-up blocks the release', () => {
+    expect(dependencyVerdict({ ...settled, queued: true, stream: { status: 'finish', updatedAt: OLD } }, NOW)).toEqual({
+      settled: false,
+      reason: 'queued',
+    });
+  });
+
+  test('an armed delivery slot blocks the release', () => {
+    expect(
+      dependencyVerdict({ ...settled, delivering: true, stream: { status: 'finish', updatedAt: OLD } }, NOW),
+    ).toEqual({ settled: false, reason: 'delivering' });
+  });
+
+  test('a status row younger than the grace window is not yet trusted', () => {
+    expect(
+      dependencyVerdict(
+        { ...settled, stream: { status: 'finish', updatedAt: NOW - SETTLE_GRACE_MS + 1 } },
+        NOW,
+      ),
+    ).toEqual({ settled: false, reason: 'grace' });
+  });
+
+  // The clock is optional: a row written before the column was read has none,
+  // and refusing to release on that would strand every prompt created against it.
+  test('a row with no clock is settled rather than held forever', () => {
+    expect(dependencyVerdict({ ...settled, stream: { status: 'finish', updatedAt: null } }, NOW).settled).toBe(true);
+  });
+});

package/src/server/lib/waiting/settle.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * When is the session a prompt is waiting for actually finished?
+ *
+ * "The stream row says `finish`" is not the answer on its own, and each of the
+ * other conditions below is a measured failure of trusting it alone:
+ *
+ *   - **A live wrapper can still be busy.** `agent_end` is written before the
+ *     turn's bookkeeping settles, and a compaction, a subagent or an open ask
+ *     dialog keeps `isBusy()` true with no `stream` row to say so. A prompt sent
+ *     into that state is refused by omp mid-turn and dropped.
+ *   - **A queued follow-up is about to be delivered.** The run end arms the
+ *     queue 500 ms out, so `finish` followed by a claim is the normal sequence
+ *     for a session the user kept typing into. Waiting on `hasQueuedItem` alone
+ *     still races the window between the claim and the prompt.
+ *   - **A pending delivery timer is the same fact, one step earlier.**
+ *   - **The row's clock is coarse.** `CURRENT_TIMESTAMP` has one-second
+ *     resolution, so a `finish` written this second may be a row an `agent_start`
+ *     is about to overwrite. A grace window on top of it closes the gap.
+ *
+ * The check is deliberately conservative: a dependency that is not yet provably
+ * finished is simply re-checked on the next sweep. Nothing is lost by waiting a
+ * second longer, and a prompt delivered into a running turn is lost entirely.
+ */
+
+import type { SessionStreamStatus } from '@/shared/lib/omp/session/stream-state.server';
+
+/** Slack applied after a dependency's last stream write, in ms. */
+export const SETTLE_GRACE_MS = 1_500;
+
+/** Everything the check reads, injected so a test needs no database or child. */
+export interface DependencyState {
+  /** The dependency's stream row, or undefined when it has none. */
+  stream: { status: SessionStreamStatus; updatedAt?: number | null } | undefined;
+  /** Epoch ms the row was last written, or null when the caller cannot tell. */
+  rowWrittenAt?: number | null;
+  /** Whether a live wrapper for it is still working (dialog, subagent, turn). */
+  busy: boolean;
+  /** Whether its follow-up queue still holds an item. */
+  queued: boolean;
+  /** Whether this process has a delivery slot armed for it. */
+  delivering: boolean;
+}
+
+export interface DependencyVerdict {
+  settled: boolean;
+  /** Why it is not settled yet — shown nowhere, logged and asserted in tests. */
+  reason: 'no-row' | 'streaming' | 'busy' | 'queued' | 'delivering' | 'grace' | null;
+}
+
+/**
+ * Whether a dependency has provably finished: no run, no queue, no delivery in
+ * flight, and its last status write is older than the grace window.
+ */
+export function dependencyVerdict(state: DependencyState, now = Date.now()): DependencyVerdict {
+  const status = state.stream?.status;
+  if (status === 'stream') return { settled: false, reason: 'streaming' };
+  // No row at all is a session Kabmo has never seen run — an id typed by hand,
+  // or one whose row the heal pass released. Nothing can be waited on, so it
+  // counts as finished rather than blocking the prompt forever.
+  if (state.stream === undefined) return { settled: true, reason: 'no-row' };
+  if (state.busy) return { settled: false, reason: 'busy' };
+  if (state.queued) return { settled: false, reason: 'queued' };
+  if (state.delivering) return { settled: false, reason: 'delivering' };
+  // The grace is about ORDER, not about the row's own fields: a run end writes
+  // `finish` and arms the follow-up queue 500 ms later, so a caller supplies the
+  // write's clock separately (see `streamRowWrittenAt`).
+  const writtenAt = state.rowWrittenAt ?? state.stream.updatedAt;
+  if (typeof writtenAt === 'number' && now - writtenAt < SETTLE_GRACE_MS) {
+    return { settled: false, reason: 'grace' };
+  }
+  return { settled: true, reason: null };
+}

package/src/server/lib/waiting/store.server.test.ts

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The waiting-prompt store, against a real temp database.
+ *
+ * The rules pinned here are the ones a second caller would break silently: the
+ * claim is what makes two sweeps (or two Kabmo instances on the shared file)
+ * safe, a terminal row has to stay readable long enough for the client that
+ * created it to learn the outcome, and a retry must not look like a delivery.
+ */
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+import { getDb } from '@/server/db.server';
+import {
+  cancelWaitingPrompt,
+  claimWaitingPrompt,
+  countWaitingAttempt,
+  createWaitingPrompt,
+  failWaitingOn,
+  failWaitingPrompt,
+  getWaitingPrompt,
+  listWaitingOn,
+  listWaitingPrompts,
+  markWaitingDispatched,
+  pruneWaitingPrompts,
+  requeueWaitingPrompt,
+  WAITING_RETENTION_MS,
+} from '@/server/lib/waiting/store.server';
+
+const ROOT = path.join(os.tmpdir(), `kabmo-waiting-store-${process.pid}`);
+
+beforeAll(async () => {
+  fs.mkdirSync(ROOT, { recursive: true });
+  isolateDb();
+});
+
+afterAll(async () => {
+  releaseDb();
+  fs.rmSync(ROOT, { recursive: true, force: true });
+});
+
+beforeEach(async () => {
+  const db = await getDb();
+  await db.run('DELETE FROM waiting_prompts');
+});
+
+const input = {
+  pendingId: 'new-1700000000000',
+  dependsOn: 'session-a',
+  dependsOnTitle: 'Session A',
+  prompt: 'summarise the diff',
+  attachments: [{ id: 'a1', preview: '', name: 'notes.txt', type: 'text/plain', content: 'hello' }],
+  model: { provider: 'anthropic', modelId: 'claude', thinkingLevel: 'high', accessMode: 'yolo' },
+  modes: { plan: true, goal: false },
+  cwd: '/tmp/project',
+  folderId: 3,
+};
+
+describe('waiting prompt store', () => {
+  test('round-trips every field the dispatcher needs', async () => {
+    const created = await createWaitingPrompt(input);
+    expect(created.status).toBe('waiting');
+    const stored = await getWaitingPrompt(created.id);
+    expect(stored).toMatchObject({
+      pendingId: 'new-1700000000000',
+      dependsOn: 'session-a',
+      dependsOnTitle: 'Session A',
+      prompt: 'summarise the diff',
+      cwd: '/tmp/project',
+      folderId: 3,
+      modes: { plan: true, goal: false },
+    });
+    expect(stored?.model).toEqual({
+      provider: 'anthropic',
+      modelId: 'claude',
+      thinkingLevel: 'high',
+      accessMode: 'yolo',
+    });
+    expect(stored?.attachments[0]?.content).toBe('hello');
+  });
+
+  test('the claim is won once, and only from `waiting`', async () => {
+    const created = await createWaitingPrompt(input);
+    expect(await claimWaitingPrompt(created.id)).toBe(true);
+    expect(await claimWaitingPrompt(created.id)).toBe(false);
+  });
+
+  test('a requeued prompt can be claimed again', async () => {
+    const created = await createWaitingPrompt(input);
+    await claimWaitingPrompt(created.id);
+    await requeueWaitingPrompt(created.id, 'omp did not start');
+    const stored = await getWaitingPrompt(created.id);
+    expect(stored?.status).toBe('waiting');
+    expect(stored?.error).toBe('omp did not start');
+    expect(await claimWaitingPrompt(created.id)).toBe(true);
+  });
+
+  test('a dispatch records the session it became', async () => {
+    const created = await createWaitingPrompt(input);
+    await claimWaitingPrompt(created.id);
+    await markWaitingDispatched(created.id, 'omp-session-9');
+    expect((await getWaitingPrompt(created.id))?.sessionId).toBe('omp-session-9');
+  });
+
+  // A claimed prompt that then failed to deliver is a FAILURE, not a delivery:
+  // leaving it at `dispatched` would tell the client its prompt arrived.
+  test('a claimed prompt can still be failed', async () => {
+    const created = await createWaitingPrompt(input);
+    await claimWaitingPrompt(created.id);
+    await failWaitingPrompt(created.id, 'the child died');
+    expect(await getWaitingPrompt(created.id)).toMatchObject({ status: 'error', error: 'the child died' });
+  });
+
+  test('cancel reaches only a prompt that has not been claimed', async () => {
+    const created = await createWaitingPrompt(input);
+    expect(await cancelWaitingPrompt(created.id)).toBe(true);
+    expect((await getWaitingPrompt(created.id))?.status).toBe('cancelled');
+    expect(await cancelWaitingPrompt(created.id)).toBe(false);
+
+    const claimed = await createWaitingPrompt(input);
+    await claimWaitingPrompt(claimed.id);
+    expect(await cancelWaitingPrompt(claimed.id)).toBe(false);
+    expect((await getWaitingPrompt(claimed.id))?.status).toBe('dispatched');
+  });
+
+  test('deleting a session fails everything waiting on it, by name', async () => {
+    const first = await createWaitingPrompt(input);
+    const second = await createWaitingPrompt({ ...input, dependsOn: 'session-b' });
+    expect(await listWaitingOn('session-a')).toHaveLength(1);
+    expect(await failWaitingOn('session-a', 'The session being waited for was deleted.')).toBe(1);
+    expect(await getWaitingPrompt(first.id)).toMatchObject({
+      status: 'error',
+      error: 'The session being waited for was deleted.',
+    });
+    expect((await getWaitingPrompt(second.id))?.status).toBe('waiting');
+  });
+
+  test('the list carries waiting rows plus recent outcomes, and prunes the rest', async () => {
+    const waiting = await createWaitingPrompt(input);
+    const done = await createWaitingPrompt(input);
+    await claimWaitingPrompt(done.id);
+    await markWaitingDispatched(done.id, 'omp-1');
+
+    const now = Date.now();
+    expect((await listWaitingPrompts(now)).map((row) => row.id)).toContain(waiting.id);
+    expect((await listWaitingPrompts(now)).map((row) => row.id)).toContain(done.id);
+
+    // Past retention the terminal row goes; the waiting one stays, because it
+    // has no outcome yet.
+    expect(await pruneWaitingPrompts(now + WAITING_RETENTION_MS + 1)).toBe(1);
+    const remaining = await listWaitingPrompts(now + WAITING_RETENTION_MS + 1);
+    expect(remaining.map((row) => row.id)).toEqual([waiting.id]);
+  });
+
+  test('attempts are counted for the failure ceiling', async () => {
+    const created = await createWaitingPrompt(input);
+    expect(await countWaitingAttempt(created.id)).toBe(1);
+    expect(await countWaitingAttempt(created.id)).toBe(2);
+  });
+});