@kabmo-labs/kabmo 0.3.1 → 0.5.0

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

@@ -46,7 +46,7 @@ import { toManifest, toMarketplaceCatalog } from '@/server/lib/panels/manifest';
 import { basenameOf, bundleUrl, cssUrl, iconUrl, readmeUrlFor } from '@/server/lib/panels/assets.server';
 import { readBundledCatalog } from '@/server/lib/panels/bundled-catalog.server';
 import { describeIncompatibility, runningVersions } from '@/server/lib/panels/compat.server';
-import { pluginPanelKey } from '@/shared/lib/workspace/panel-ids';
+import { pluginEnablementKey } from '@/shared/lib/workspace/panel-ids';
 
 /** The marketplace root: `<data>/marketplace`, overridable for tests. */
 export function getMarketplaceDir(): string {
@@ -205,7 +205,7 @@ async function runPanelScan(): Promise<PanelScan> {
     // panel id (`plugin:<id>`), so one stored list answers for both kinds. Testing
     // the bare manifest id here made a disabled plugin still report `enabled:
     // true` while its panel stayed hidden — two answers for one question.
-    const enabled = !disabled.has(pluginPanelKey(manifest.id));
+    const enabled = !disabled.has(pluginEnablementKey(manifest.id));
     const entries = [manifest.app, manifest.server].filter((entry): entry is string => Boolean(entry));
     let missingEntry: string | undefined;
     for (const entry of entries) {

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

@@ -21,7 +21,8 @@
  */
 
 import { claimHeadQueueItem, hasQueuedItem, requeueHeadQueueItem } from '@/server/lib/queue/store.server';
-import { composeMessageWithTextAttachments } from '@/shared/lib/chat/attachments';
+import { applyModelSnapshot, promptCommand } from '@/server/lib/queue/payload';
+import { requestWaitingSweep } from '@/server/lib/waiting/sweep-trigger';
 import type { QueuedMessage } from '@/shared/types/chat';
 
 /** Settling time between agent_end and the next prompt dispatch. Small on
@@ -94,45 +95,15 @@ function clearPendingTimer(sessionId: string): void {
 
 /** Send one queued item to the session as a normal prompt. The model snapshot
  *  rides first (set_model / set_thinking_level) exactly like the composer's
- *  queued delivery did. Returns false when the dispatch failed. */
+ *  queued delivery did. Returns false when the dispatch failed.
+ *
+ *  The command itself is built by `queue/payload.ts`, shared with the waiting
+ *  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> {
   try {
-    if (item.model) {
-      await session.send({ type: 'set_model', provider: item.model.provider, modelId: item.model.modelId });
-      if (item.model.thinkingLevel !== 'auto') {
-        await session.send({ type: 'set_thinking_level', level: item.model.thinkingLevel });
-      }
-    }
-    // Attachments reach this point as the persisted display fields — the live
-    // `File` never survived the queue's JSON round trip. The base64 payload and
-    // the MIME type are therefore read from the fields that DID persist:
-    // `dataBase64` for the bytes, `type` for the media type. (Matching on a
-    // `data:` preview used to yield zero images, because the composer's preview
-    // is a `blob:` object URL that the server cannot read.)
-    const images = item.attachments
-      .filter((a) => typeof a?.dataBase64 === 'string' && a.dataBase64.length > 0)
-      .map((a) => ({
-        type: 'image' as const,
-        data: a.dataBase64 as string,
-        mimeType: typeof a.type === 'string' && a.type.startsWith('image/') ? a.type : 'image/png',
-      }));
-    // Text attachments are inlined into the prompt, exactly as the composer
-    // does at send time — the item's own `text` is the raw composer input, so
-    // without this a queued file would deliver as a bare filename mention.
-    const textFiles = item.attachments
-      .filter((a) => typeof a?.content === 'string' && a.content.length > 0)
-      .map((a) => ({
-        name: typeof a.name === 'string' && a.name ? a.name : 'attachment',
-        mimeType: typeof a.type === 'string' ? a.type : 'text/plain',
-        content: a.content as string,
-        size: typeof a.size === 'number' ? a.size : (a.content as string).length,
-      }));
-    await session.send({
-      type: 'prompt',
-      message: composeMessageWithTextAttachments(item.text, textFiles),
-      ...(images.length ? { images } : {}),
-      ...(item.model ? { accessMode: item.model.accessMode } : {}),
-    });
+    await applyModelSnapshot(session.send, item.model);
+    await session.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);
@@ -231,7 +202,13 @@ async function deliverNext(session: QueueDeliveryHost): Promise<boolean> {
     return false;
   }
   const item = await claimHeadQueueItem(sessionId);
-  if (!item) return false;
+  if (!item) {
+    // The queue just drained: a prompt held until this session finished may now
+    // be free to go. The sweep re-checks the queue itself, so requesting one
+    // here cannot release a prompt ahead of an item that is still waiting.
+    requestWaitingSweep();
+    return false;
+  }
   const ok = await dispatchQueuedItem(session, item);
   if (!ok) {
     await requeueHeadQueueItem(sessionId, item);
@@ -240,9 +217,24 @@ async function deliverNext(session: QueueDeliveryHost): Promise<boolean> {
     await armRetryIfQueued(session);
     return false;
   }
+  // This delivery may have been the last one: ask for a sweep so a dependent
+  // prompt does not sit until the next tick after the queue emptied.
+  requestWaitingSweep();
   return true;
 }
 
+/**
+ * Whether this process already holds a delivery slot for the session.
+ *
+ * Read by the waiting-prompt sweep: a run end arms a delivery 500 ms out, so a
+ * dependency that looks settled for a moment may still have its queued
+ * follow-up about to go out. Waiting for the slot to clear is what keeps a
+ * dependent prompt from starting a second turn in the gap.
+ */
+export function hasPendingDelivery(sessionId: string): boolean {
+  return getPendingTimers().has(sessionId);
+}
+
 /**
  * A user Stop: return anything already claimed for this session's pending
  * delivery to the queue and cancel the timer. The item keeps its head

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

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The one place a stored prompt becomes an omp command.
+ *
+ * Two dispatchers send prompts nobody typed in this tab: the follow-up queue
+ * (`queue/delivery.server.ts`) and a prompt held until another session finishes
+ * (`waiting/runtime.server.ts`). They carry the SAME persisted shape — a text,
+ * an attachment list whose live `File` did not survive the JSON round trip, and
+ * an optional model snapshot — so a second copy of this assembly is how the two
+ * drift (one inlining a text file, the other sending a bare filename).
+ *
+ * The attachment rules are read off the fields that DID persist:
+ *
+ *   - `dataBase64` holds an image's bytes; `type` its media type. Matching on a
+ *     `data:` preview yields zero images, because the composer's preview is a
+ *     `blob:` object URL the server cannot read.
+ *   - `content` is an inlined text file. Without it a queued attachment
+ *     delivers as a filename mention instead of the file.
+ */
+
+import type { Attachment, QueuedMessageModel } from '@/shared/types/chat';
+import { composeMessageWithTextAttachments } from '@/shared/lib/chat/attachments';
+
+export interface StoredPrompt {
+  text: string;
+  attachments: Attachment[];
+  model: QueuedMessageModel | null;
+}
+
+/** The `prompt` command (with any images) a stored prompt dispatches. */
+export function promptCommand(prompt: StoredPrompt): Record<string, unknown> {
+  const images = prompt.attachments
+    .filter((attachment) => typeof attachment?.dataBase64 === 'string' && attachment.dataBase64.length > 0)
+    .map((attachment) => ({
+      type: 'image' as const,
+      data: attachment.dataBase64 as string,
+      mimeType: typeof attachment.type === 'string' && attachment.type.startsWith('image/')
+        ? attachment.type
+        : 'image/png',
+    }));
+  const textFiles = prompt.attachments
+    .filter((attachment) => typeof attachment?.content === 'string' && attachment.content.length > 0)
+    .map((attachment) => ({
+      name: typeof attachment.name === 'string' && attachment.name ? attachment.name : 'attachment',
+      mimeType: typeof attachment.type === 'string' ? attachment.type : 'text/plain',
+      content: attachment.content as string,
+      size: typeof attachment.size === 'number' ? attachment.size : (attachment.content as string).length,
+    }));
+  return {
+    type: 'prompt',
+    message: composeMessageWithTextAttachments(prompt.text, textFiles),
+    ...(images.length ? { images } : {}),
+    ...(prompt.model ? { accessMode: prompt.model.accessMode } : {}),
+  };
+}
+
+/** Apply a stored model snapshot to a live child before its prompt. */
+export async function applyModelSnapshot(
+  send: (command: Record<string, unknown>) => Promise<unknown>,
+  model: QueuedMessageModel | null,
+): Promise<void> {
+  if (!model) return;
+  await send({ type: 'set_model', provider: model.provider, modelId: model.modelId });
+  // 'auto' thinking leaves omp's level alone: the snapshot records "no pick",
+  // not a level named auto.
+  if (model.thinkingLevel !== 'auto') {
+    await send({ type: 'set_thinking_level', level: model.thinkingLevel });
+  }
+}

package/src/server/lib/realtime/signals.server.ts

@@ -56,7 +56,16 @@ export type RealtimeSignal =
    * snapshot and then never moved — the panels rendered whatever existed when
    * they subscribed and only a reload showed the new state.
    */
-  | 'session-data-dirty';
+  | 'session-data-dirty'
+  /**
+   * A waiting prompt was created, cancelled, dispatched or failed.
+   *
+   * Both halves read it: the server republishes the `waiting` topic, and the
+   * client's dispatch watcher adopts the session a prompt became. Nothing else
+   * reports a dispatch — no user action causes it, and the spawned session's own
+   * transcript is seconds away.
+   */
+  | 'waiting-changed';
 
 export interface RealtimeSignalEvent {
   signal: RealtimeSignal;

package/src/server/lib/realtime/topics/catalog.server.ts

@@ -22,6 +22,7 @@ import {
   TOPIC_SIDEBAR,
   TOPIC_SIDEBAR_STATUS,
   TOPIC_USAGE,
+  TOPIC_WAITING,
   sessionPlanTopic,
   sessionQueueTopic,
   sessionTelemetryTopic,
@@ -67,6 +68,7 @@ export const EXACT_TOPICS = new Map<string, TopicDescriptor>([
   [TOPIC_USAGE, { resolve: () => globalDescriptor(TOPIC_USAGE).resolve(TOPIC_USAGE) }],
   [TOPIC_PANELS, { resolve: () => globalDescriptor(TOPIC_PANELS).resolve(TOPIC_PANELS) }],
   [TOPIC_MODELS, { resolve: () => globalDescriptor(TOPIC_MODELS).resolve(TOPIC_MODELS) }],
+  [TOPIC_WAITING, { resolve: () => globalDescriptor(TOPIC_WAITING).resolve(TOPIC_WAITING) }],
 ]);
 
 /** Suffixes a `session:<id>:<suffix>` topic may carry. */

package/src/server/lib/realtime/topics/global.server.ts

@@ -20,9 +20,11 @@ import {
   TOPIC_PANELS,
   TOPIC_SCHEDULE,
   TOPIC_USAGE,
+  TOPIC_WAITING,
 } from '@/shared/lib/realtime/protocol';
 import { type TopicDescriptor } from '@/server/lib/realtime/hub.server';
 import { listScheduledTasks } from '@/server/lib/schedule/store.server';
+import { listWaitingPrompts } from '@/server/lib/waiting/store.server';
 import { buildUsageReport } from '@/server/lib/usage/report.server';
 import { discoverPanelPlugins } from '@/server/lib/panels/registry.server';
 import { loadModelsWithCache } from '@/server/lib/models/registry.server';
@@ -34,6 +36,9 @@ import { loadModelsWithCache } from '@/server/lib/models/registry.server';
  */
 const RESOLVERS: Record<string, () => Promise<unknown>> = {
   [TOPIC_SCHEDULE]: () => listScheduledTasks(),
+  // The waiting list is the same read the runtime sweeps over, so a client and
+  // the dispatcher can never disagree about which prompt is still held.
+  [TOPIC_WAITING]: () => listWaitingPrompts(),
   // The SAME builder `GET /api/settings/usage` answers with: the panel renders
   // whichever path arrived first, so the two payloads must not diverge.
   [TOPIC_USAGE]: () => buildUsageReport(),

package/src/server/lib/realtime/topics.server.ts

@@ -20,6 +20,7 @@ import {
   TOPIC_SIDEBAR,
   TOPIC_SIDEBAR_STATUS,
   TOPIC_USAGE,
+  TOPIC_WAITING,
   isValidTopic,
   reposTopic,
   sessionTopic,
@@ -93,6 +94,7 @@ export function initRealtimeTopics(): void {
     else if (signal === 'workspace-dirty') republishWatchedWorkspaceTopics();
     else if (signal === 'session-data-dirty' && sessionId) republishSessionDataTopics(sessionId);
     else if (signal === 'repos-scanned' && root) publishTopic(reposTopic(root));
+    else if (signal === 'waiting-changed') publishTopic(TOPIC_WAITING);
   });
 }
 

package/src/server/lib/util/with-timeout.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Reject a promise that has not settled within `ms`.
+ *
+ * Both server-side dispatchers (a scheduled task, a prompt held until another
+ * session finishes) wait on a spawn and then on a prompt ack, and neither has a
+ * timeout of its own: an omp child that boots but never answers would leave the
+ * dispatch in flight for the life of the process. The caller owns the message,
+ * because it is the only place that knows what was being waited for.
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+  const { promise: guarded, resolve, reject } = Promise.withResolvers<T>();
+  const timer = setTimeout(() => reject(new Error(message)), ms);
+  promise.then(
+    (value) => {
+      clearTimeout(timer);
+      resolve(value);
+    },
+    (error) => {
+      clearTimeout(timer);
+      reject(error);
+    },
+  );
+  return guarded;
+}

package/src/server/lib/waiting/row-clock.server.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * When was a session's stream row last written?
+ *
+ * The dependency check needs this and the SIDEBAR does not, which is why it is
+ * a query of its own rather than a field on `SessionStreamState`: that payload
+ * is the `sidebar:status` wire contract, and widening it for one caller would
+ * put a field on every frame that no consumer reads.
+ *
+ * The conversion happens in SQLite. `updated_at` is written by
+ * `CURRENT_TIMESTAMP` — a UTC string with no zone marker — so parsing it in JS
+ * would silently read it as local time. `strftime('%s', …)` yields epoch
+ * seconds, which is the resolution the row is written at.
+ */
+
+import { getDb } from '@/server/db.server';
+
+/**
+ * Epoch ms of the session's last stream-status write, or null when the session
+ * has no row (or the clock cannot be read).
+ */
+export async function streamRowWrittenAt(sessionId: string): Promise<number | null> {
+  try {
+    const db = await getDb();
+    const row = (await db.get(
+      "SELECT CAST(strftime('%s', updated_at) AS INTEGER) AS epoch FROM session_stream_state WHERE session_id = ?",
+      [sessionId],
+    )) as { epoch?: number | null } | undefined;
+    return typeof row?.epoch === 'number' ? row.epoch * 1000 : null;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,278 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The waiting-prompt sweep: what it dispatches, what it holds, and what happens
+ * when the dispatch fails.
+ *
+ * Every outside dependency is INJECTED (`WaitingDeps`), never mocked through
+ * `mock.module` — that swaps a registry entry for the whole `bun test` run and
+ * broke six unrelated suites the last time it was tried here. Injection keeps
+ * the blast radius inside this file, and the rules worth pinning are all about
+ * ORDER rather than about omp:
+ *
+ *   - a prompt is dispatched exactly once, even for two sweeps that race;
+ *   - a dependency with a queue still waiting holds the prompt;
+ *   - a dispatch that throws is retried, then reported, and never silently
+ *     dropped;
+ *   - the prompt carries its attachments and its model snapshot.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { sweepWaitingPrompts, MAX_DISPATCH_ATTEMPTS, type StreamRowMap, type WaitingDeps } from '@/server/lib/waiting/runtime.server';
+import type { Attachment } from '@/shared/types/chat';
+import type { WaitingPrompt } from '@/shared/types/waiting';
+
+const NOW = 1_800_000_000_000;
+const OLD = NOW - 60_000;
+
+function prompt(overrides: Partial<WaitingPrompt> = {}): WaitingPrompt {
+  return {
+    id: 'wait-1',
+    pendingId: 'new-1',
+    dependsOn: 'dep-a',
+    dependsOnTitle: 'Session A',
+    prompt: 'do the thing',
+    attachments: [],
+    model: null,
+    modes: null,
+    cwd: '/tmp/project',
+    folderId: 1,
+    status: 'waiting',
+    sessionId: null,
+    error: null,
+    createdAt: OLD,
+    updatedAt: OLD,
+    ...overrides,
+  };
+}
+
+interface Harness {
+  deps: WaitingDeps;
+  /** Commands sent to each spawned session, in order. */
+  sent: Record<string, Record<string, unknown>[]>;
+  /** Session ids spawned, in order. */
+  spawned: string[];
+  /** Calls that changed a row, as `verb id`. */
+  writes: string[];
+  setStreams(rows: StreamRowMap): void;
+  setRowWrittenAt(at: number | null): void;
+  setQueued(queued: boolean): void;
+  setDelivering(delivering: boolean): void;
+  failSpawnWith(error: Error | null): void;
+  failSendWith(error: Error | null): void;
+}
+
+function harness(initial: WaitingPrompt[] = [prompt()]): Harness {
+  // The attempt counter is the store's own column, not part of the client-facing
+  // shape: the harness keeps it beside the rows rather than widening `WaitingPrompt`.
+  const attempts = new Map<string, number>();
+  let rows = initial.map((row) => ({ ...row }));
+  let streams: StreamRowMap = { 'dep-a': { status: 'finish' } };
+  let rowWrittenAt: number | null = OLD;
+  let queued = false;
+  let delivering = false;
+  let spawnError: Error | null = null;
+  let sendError: Error | null = null;
+  const sent: Harness['sent'] = {};
+  const spawned: string[] = [];
+  const writes: string[] = [];
+  let spawnCount = 0;
+
+  const deps: WaitingDeps = {
+    async startNewRpcSession() {
+      if (spawnError) throw spawnError;
+      spawnCount += 1;
+      const id = `spawned-${spawnCount}`;
+      spawned.push(id);
+      sent[id] = [];
+      return {
+        realSessionId: id,
+        session: {
+          async send(command) {
+            if (sendError) throw sendError;
+            sent[id].push(command);
+            return null;
+          },
+        },
+      };
+    },
+    getSession: () => undefined,
+    loadStreamStates: async () => streams,
+    streamRowWrittenAt: async () => rowWrittenAt,
+    hasQueuedItem: async () => queued,
+    hasPendingDelivery: () => delivering,
+    loadPersistedAccessMode: async () => 'always-ask',
+    listWaitingPrompts: async () => rows.map((row) => ({ ...row })),
+    claimWaitingPrompt: async (id) => {
+      const row = rows.find((entry) => entry.id === id);
+      if (!row || row.status !== 'waiting') return false;
+      row.status = 'dispatched';
+      writes.push(`claim ${id}`);
+      return true;
+    },
+    countWaitingAttempt: async (id) => {
+      const next = (attempts.get(id) ?? 0) + 1;
+      attempts.set(id, next);
+      return next;
+    },
+    markWaitingDispatched: async (id, sessionId) => {
+      const row = rows.find((entry) => entry.id === id);
+      if (row) {
+        row.status = 'dispatched';
+        row.sessionId = sessionId;
+      }
+      writes.push(`dispatched ${id} ${sessionId}`);
+    },
+    requeueWaitingPrompt: async (id) => {
+      const row = rows.find((entry) => entry.id === id);
+      if (row) row.status = 'waiting';
+      writes.push(`requeue ${id}`);
+    },
+    failWaitingPrompt: async (id, error) => {
+      const row = rows.find((entry) => entry.id === id);
+      if (row) {
+        row.status = 'error';
+        row.error = error;
+      }
+      writes.push(`fail ${id}`);
+    },
+    pruneWaitingPrompts: async () => 0,
+  };
+
+  return {
+    deps,
+    sent,
+    spawned,
+    writes,
+    setStreams: (next) => {
+      streams = next;
+    },
+    setRowWrittenAt: (next) => {
+      rowWrittenAt = next;
+    },
+    setQueued: (next) => {
+      queued = next;
+    },
+    setDelivering: (next) => {
+      delivering = next;
+    },
+    failSpawnWith: (error) => {
+      spawnError = error;
+    },
+    failSendWith: (error) => {
+      sendError = error;
+    },
+  };
+}
+
+describe('sweepWaitingPrompts', () => {
+  test('dispatches a prompt once its dependency has finished', async () => {
+    const h = harness();
+    expect(await sweepWaitingPrompts({ now: NOW, deps: h.deps })).toBe(1);
+    expect(h.spawned).toEqual(['spawned-1']);
+    expect(h.sent['spawned-1']).toEqual([{ type: 'prompt', message: 'do the thing' }]);
+    expect(h.writes).toContain('dispatched wait-1 spawned-1');
+  });
+
+  test('holds the prompt while the dependency still has a queued follow-up', async () => {
+    const h = harness();
+    h.setQueued(true);
+    expect(await sweepWaitingPrompts({ now: NOW, deps: h.deps })).toBe(0);
+    expect(h.spawned).toEqual([]);
+  });
+
+  test('holds the prompt while the dependency is still streaming', async () => {
+    const h = harness();
+    h.setStreams({ 'dep-a': { status: 'stream' } });
+    expect(await sweepWaitingPrompts({ now: NOW, deps: h.deps })).toBe(0);
+  });
+
+  // The row's clock is what closes the gap between a run end and the queue it
+  // arms 500 ms later, so a freshly written row must not release anything yet.
+  test('holds the prompt until the status row has aged past the grace', async () => {
+    const h = harness();
+    h.setRowWrittenAt(NOW - 100);
+    expect(await sweepWaitingPrompts({ now: NOW, deps: h.deps })).toBe(0);
+    expect(h.spawned).toEqual([]);
+  });
+
+  test('holds the prompt while a delivery slot is armed', async () => {
+    const h = harness();
+    h.setDelivering(true);
+    expect(await sweepWaitingPrompts({ now: NOW, deps: h.deps })).toBe(0);
+  });
+
+  // The claim is the concurrency answer: the second sweep must not spawn again.
+  test('two sweeps racing spawn exactly one session', async () => {
+    const h = harness();
+    const [first, second] = await Promise.all([
+      sweepWaitingPrompts({ now: NOW, deps: h.deps }),
+      sweepWaitingPrompts({ now: NOW, deps: h.deps }),
+    ]);
+    expect(first + second).toBe(1);
+    expect(h.spawned).toHaveLength(1);
+  });
+
+  test('a failed spawn returns the prompt to waiting instead of losing it', async () => {
+    const h = harness();
+    h.failSpawnWith(new Error('omp did not start'));
+    expect(await sweepWaitingPrompts({ now: NOW, deps: h.deps })).toBe(0);
+    expect(h.writes).toContain('requeue wait-1');
+    expect(h.writes).not.toContain('fail wait-1');
+  });
+
+  test('a prompt whose dispatch keeps failing is reported, not retried forever', async () => {
+    const h = harness();
+    h.failSpawnWith(new Error('omp did not start'));
+    for (let attempt = 0; attempt < MAX_DISPATCH_ATTEMPTS; attempt += 1) {
+      await sweepWaitingPrompts({ now: NOW, deps: h.deps });
+    }
+    expect(h.writes.filter((write) => write.startsWith('fail '))).toHaveLength(1);
+  });
+
+  // The wrapper's `send` reads its own runtime state through `this`, so a
+  // dispatch that passes the method detached runs against `undefined` — the
+  // real failure was `undefined is not an object (evaluating 'host.restarting')`
+  // on every prompt. The harness's send is an object METHOD for that reason,
+  // and this asserts the dispatcher never loses its receiver.
+  test('sends through the session, never a detached method', async () => {
+    const h = harness();
+    let receiver: unknown = null;
+    h.deps.startNewRpcSession = async () => {
+      const session = {
+        async send(this: unknown) {
+          receiver = this;
+          return null;
+        },
+      };
+      return { realSessionId: 'spawned-x', session };
+    };
+    await sweepWaitingPrompts({ now: NOW, deps: h.deps });
+    expect(receiver).not.toBeUndefined();
+  });
+
+  test('carries the attachment bytes and the model snapshot', async () => {
+    const attachment: Attachment = { id: 'a1', preview: '', name: 'shot.png', type: 'image/png', dataBase64: 'AAA' };
+    const h = harness([
+      prompt({
+        attachments: [attachment],
+        model: { provider: 'anthropic', modelId: 'claude', thinkingLevel: 'high', accessMode: 'yolo' },
+      }),
+    ]);
+    await sweepWaitingPrompts({ now: NOW, deps: h.deps });
+    const commands = h.sent['spawned-1'];
+    expect(commands[0]).toEqual({ type: 'set_model', provider: 'anthropic', modelId: 'claude' });
+    expect(commands[1]).toEqual({ type: 'set_thinking_level', level: 'high' });
+    expect(commands[2]).toMatchObject({ type: 'prompt', accessMode: 'yolo' });
+    expect((commands[2].images as { data: string }[])[0]?.data).toBe('AAA');
+  });
+
+  test('nothing is read or spawned when no prompt is waiting', async () => {
+    const h = harness([prompt({ status: 'dispatched', sessionId: 'done' })]);
+    expect(await sweepWaitingPrompts({ now: NOW, deps: h.deps })).toBe(0);
+    expect(h.spawned).toEqual([]);
+  });
+});