Route leftover steers through send not live deliver

Live parent tool.boundary still injects via Agent.deliver. Steers
left at idle, idle-with-fleet, or after interrupt must send so they
share sendQueue, inFlight, and token refresh with follow-ups.

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -83,8 +83,10 @@ In TUI chat mode there is no completion gate — the session stays open across t
 - Bridges reactor events to the OpenTUI host via a plain `EventEmitter`
 - **Mid-run injection** — Shell `session-queue` items drain at the parent
   `tool.boundary` through `SessionPort.deliver`. Production `routeQueuedDelivery`
-  sends steers via `agentProxy.deliver` (`Agent.deliver`) into the live reactor
-  and idle follow-ups via the existing send path. `/clear` and `/new` bump a
+  live-injects in-flight parent-boundary steers via `agentProxy.deliver`
+  (`Agent.deliver`) into the live reactor. Idle leftover, idle-with-fleet, and
+  post-interrupt steers, plus follow-ups (`kind === "queue"`), use the existing
+  send path. `/clear` and `/new` bump a
   delivery generation and call `SessionBridge.clearQueuedDelivery()` so queued
   input from the previous session cannot enter the new one.
 - **Session rotation** — Uses a serial session-operation queue (`createSessionOperationQueue`, not a boolean flag) so rotation, compaction continuation, and `agentProxy.deliver` never race a concurrent rebuild. Each operation chains onto the tail, ensuring in-flight work completes before the agent is torn down.

docs/TUI.md

@@ -481,7 +481,7 @@ events carrying the live-lane count and the bridge holds the run busy on it.
 During the hold, Enter upgrades to a new primary turn sent immediately —
 there is no parent tool left to steer — while Alt+Enter follow-ups keep
 waiting for true session-idle. A steer still pending when the hold engages
-delivers at once (the parent it was steering has stopped), and the last lane
+sends at once (the parent it was steering has stopped), and the last lane
 terminalizing releases the hold, drains follow-ups, and returns the session
 to idle.
 

src/tui/live-session-port.ts

@@ -23,7 +23,7 @@ export interface LiveSessionPortDeps {
   ) => SubmitClassification;
   /** Hard interrupt current run (runner close/rebuild). */
   interrupt: () => void;
-  /** Drained queue/steer item at tool boundary (or idle). Always forwarded. */
+  /** Drained queue/steer item. Kind routing (live inject vs send) is the host's. */
   deliver: (text: string, kind: QueueKind, attachments?: readonly PendingImageAttachment[]) => void;
 }
 

src/tui/prompt-attachments.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, test } from "bun:test";
 
 import type { AttachImageResult, PendingImageAttachment } from "./image-attachments.js";
-import { ingestPathMentions, spliceMentionCompletion } from "./prompt-attachments.js";
+import {
+  ingestOperatorPrompt,
+  ingestPathMentions,
+  spliceMentionCompletion,
+} from "./prompt-attachments.js";
 
 function attachment(name: string): PendingImageAttachment {
   return {
@@ -40,6 +44,30 @@ describe("ingestPathMentions", () => {
   });
 });
 
+describe("ingestOperatorPrompt", () => {
+  test("merges pending attachments and expands a missing @mention", async () => {
+    const pending = attachment("clip.png");
+    const result = await ingestOperatorPrompt(
+      "use @missing.ts",
+      "/repo",
+      async () => {
+        throw new Error("must not load");
+      },
+      [pending],
+    );
+    expect(result.text).toContain("@missing.ts (not found)");
+    expect(result.attachments).toEqual([pending]);
+  });
+
+  test("does not send — only returns ingested text and attachments", async () => {
+    const result = await ingestOperatorPrompt("just words", "/repo", async () => {
+      throw new Error("must not load");
+    });
+    expect(result.text).toBe("just words");
+    expect(result.attachments).toEqual([]);
+  });
+});
+
 describe("spliceMentionCompletion", () => {
   test("replaces the typed token and keeps the trailing text", () => {
     const value = "read @src/tu rest";

src/tui/prompt-attachments.ts

@@ -9,6 +9,7 @@ import {
   type AttachImageResult,
   type PendingImageAttachment,
 } from "./image-attachments.js";
+import { resolveAtMentions } from "./mention-resolution.js";
 
 export type { PendingImageAttachment };
 
@@ -42,6 +43,21 @@ export async function ingestPathMentions(
   return { text: out, attachments };
 }
 
+/**
+ * Shared operator-prompt ingest for send and live-steer deliver: inline image
+ * paths become attachments and @mentions are expanded. Does not send.
+ */
+export async function ingestOperatorPrompt(
+  text: string,
+  cwd: string,
+  load: (path: string) => Promise<AttachImageResult>,
+  pending: readonly PendingImageAttachment[] = [],
+): Promise<PathMentionIngestion> {
+  const ingested = await ingestPathMentions(text, cwd, load);
+  const resolved = await resolveAtMentions(ingested.text, cwd);
+  return { text: resolved, attachments: [...pending, ...ingested.attachments] };
+}
+
 export interface MentionSplice {
   readonly value: string;
   readonly cursor: number;

src/tui/queued-delivery-hop.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Last-hop pins for drained queue items: live parent-boundary steers
+ * Agent.deliver (deliverSteer); leftover / fleet-hold / interrupt use send.
+ */
+import { describe, expect, test } from "bun:test";
+import { attachSessionBridge, type SessionBridge } from "./runtime-bridge";
+import { createLiveSessionPort } from "./live-session-port";
+import { createAppShell } from "./shell";
+import { withTestRenderer } from "./harness";
+import { routeQueuedDelivery } from "./queued-delivery.js";
+import { badgeCount } from "./session-queue";
+
+function lastHopPort(bridgeRef: { current: SessionBridge | undefined }) {
+  const sends: string[] = [];
+  const steers: string[] = [];
+  const port = createLiveSessionPort({
+    send: (text) => {
+      sends.push(text);
+    },
+    interrupt: () => {},
+    deliver: routeQueuedDelivery({
+      send: (text) => {
+        sends.push(text);
+      },
+      deliverSteer: (text) => {
+        steers.push(text);
+      },
+      parentCycleLive: () => bridgeRef.current?.parentCycleLive === true,
+    }),
+  });
+  return { port, sends, steers };
+}
+
+describe("queued delivery last hop", () => {
+  test("busy parent tool.boundary steer last-hops to deliverSteer, not send", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+          run: "busy",
+        });
+        const bridgeRef: { current: SessionBridge | undefined } = { current: undefined };
+        const { port, sends, steers } = lastHopPort(bridgeRef);
+        const bridge = attachSessionBridge(shell, port);
+        bridgeRef.current = bridge;
+        try {
+          bridge.submit("asap", "steer");
+          expect(badgeCount(shell.session)).toBe(1);
+          bridge.handle({ type: "tool.boundary" });
+          expect(steers).toEqual(["asap"]);
+          expect(sends).toEqual([]);
+        } finally {
+          bridge.dispose();
+          shell.dispose();
+        }
+      },
+      { width: 80, height: 24 },
+    );
+  });
+
+  test("text-only settle leftover steer last-hops to send", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+          run: "busy",
+        });
+        const bridgeRef: { current: SessionBridge | undefined } = { current: undefined };
+        const { port, sends, steers } = lastHopPort(bridgeRef);
+        const bridge = attachSessionBridge(shell, port);
+        bridgeRef.current = bridge;
+        try {
+          bridge.submit("leftover", "steer");
+          bridge.handle({ type: "inference.start", data: {} });
+          bridge.handle({ type: "inference.text.delta", data: { token: "hi" } });
+          bridge.handle({ type: "inference.done", data: {} });
+          expect(sends).toEqual(["leftover"]);
+          expect(steers).toEqual([]);
+        } finally {
+          bridge.dispose();
+          shell.dispose();
+        }
+      },
+      { width: 80, height: 24 },
+    );
+  });
+
+  test("interrupt leftover steer last-hops to send", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+          run: "busy",
+        });
+        const bridgeRef: { current: SessionBridge | undefined } = { current: undefined };
+        const { port, sends, steers } = lastHopPort(bridgeRef);
+        const bridge = attachSessionBridge(shell, port);
+        bridgeRef.current = bridge;
+        try {
+          bridge.submit("after stop", "steer");
+          bridge.interrupt();
+          expect(sends).toEqual(["after stop"]);
+          expect(steers).toEqual([]);
+        } finally {
+          bridge.dispose();
+          shell.dispose();
+        }
+      },
+      { width: 80, height: 24 },
+    );
+  });
+
+  test("idle-with-fleet leftover steer last-hops to send", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+          run: "idle",
+        });
+        const bridgeRef: { current: SessionBridge | undefined } = { current: undefined };
+        const { port, sends, steers } = lastHopPort(bridgeRef);
+        const bridge = attachSessionBridge(shell, port);
+        bridgeRef.current = bridge;
+        try {
+          bridge.submit("dispatch", "immediate");
+          bridge.submit("one more worker", "steer");
+          bridge.handle({ type: "fleet", running: 1 });
+          bridge.handle({ type: "inference.start", data: {} });
+          bridge.handle({ type: "inference.done", data: {} });
+          expect(sends).toEqual(["dispatch", "one more worker"]);
+          expect(steers).toEqual([]);
+        } finally {
+          bridge.dispose();
+          shell.dispose();
+        }
+      },
+      { width: 80, height: 24 },
+    );
+  });
+
+  test("/clear drops queued steers so a later boundary does not deliver or send", async () => {
+    await withTestRenderer(
+      async (h) => {
+        const shell = createAppShell(h.renderer, {
+          terminal: { columns: 80, rows: 24 },
+          wireKeys: false,
+          run: "busy",
+        });
+        const bridgeRef: { current: SessionBridge | undefined } = { current: undefined };
+        const { port, sends, steers } = lastHopPort(bridgeRef);
+        const bridge = attachSessionBridge(shell, port);
+        bridgeRef.current = bridge;
+        try {
+          bridge.submit("old steer", "steer");
+          expect(badgeCount(shell.session)).toBe(1);
+          bridge.clearQueuedDelivery();
+          bridge.handle({ type: "tool.boundary" });
+          expect(sends).toEqual([]);
+          expect(steers).toEqual([]);
+        } finally {
+          bridge.dispose();
+          shell.dispose();
+        }
+      },
+      { width: 80, height: 24 },
+    );
+  });
+});

src/tui/queued-delivery.test.ts

@@ -10,54 +10,69 @@ const image: PendingImageAttachment = {
   contentHash: "hash-1",
 };
 
+function recordHops(parentCycleLive: () => boolean) {
+  const sends: string[] = [];
+  const steers: string[] = [];
+  const deliver = routeQueuedDelivery({
+    send: (text) => {
+      sends.push(text);
+    },
+    deliverSteer: (text) => {
+      steers.push(text);
+    },
+    parentCycleLive,
+  });
+  return { deliver, sends, steers };
+}
+
 describe("routeQueuedDelivery", () => {
-  test("steer calls deliverSteer only", () => {
-    const sends: string[] = [];
-    const steers: string[] = [];
-    const deliver = routeQueuedDelivery({
-      send: (text) => {
-        sends.push(text);
-      },
-      deliverSteer: (text) => {
-        steers.push(text);
-      },
-    });
+  test("live parent-boundary steer calls deliverSteer only", () => {
+    const { deliver, sends, steers } = recordHops(() => true);
     deliver("asap", "steer");
     expect(steers).toEqual(["asap"]);
     expect(sends).toEqual([]);
   });
 
-  test("queue calls send only", () => {
-    const sends: string[] = [];
-    const steers: string[] = [];
-    const deliver = routeQueuedDelivery({
-      send: (text) => {
-        sends.push(text);
-      },
-      deliverSteer: (text) => {
-        steers.push(text);
-      },
-    });
+  test("leftover steer (idle / fleet-hold / post-interrupt) calls send only", () => {
+    const { deliver, sends, steers } = recordHops(() => false);
+    deliver("leftover", "steer");
+    expect(sends).toEqual(["leftover"]);
+    expect(steers).toEqual([]);
+  });
+
+  test("queue calls send only, even while the parent cycle is live", () => {
+    const { deliver, sends, steers } = recordHops(() => true);
     deliver("later", "queue");
     expect(sends).toEqual(["later"]);
     expect(steers).toEqual([]);
   });
 
-  test("forwards attachments on both kinds", () => {
+  test("forwards attachments on both hops", () => {
     const sent: (readonly PendingImageAttachment[] | undefined)[] = [];
     const steered: (readonly PendingImageAttachment[] | undefined)[] = [];
-    const deliver = routeQueuedDelivery({
+    const live = routeQueuedDelivery({
+      send: (_text, attachments) => {
+        sent.push(attachments);
+      },
+      deliverSteer: (_text, attachments) => {
+        steered.push(attachments);
+      },
+      parentCycleLive: () => true,
+    });
+    const leftover = routeQueuedDelivery({
       send: (_text, attachments) => {
         sent.push(attachments);
       },
       deliverSteer: (_text, attachments) => {
         steered.push(attachments);
       },
+      parentCycleLive: () => false,
     });
-    deliver("asap", "steer", [image]);
-    deliver("later", "queue", [image]);
+    live("asap", "steer", [image]);
+    leftover("later", "steer", [image]);
+    leftover("follow", "queue", [image]);
     expect(steered).toEqual([[image]]);
-    expect(sent).toEqual([[image]]);
+    expect(sent).toEqual([[image], [image]]);
   });
 });