@blackbelt-technology/pi-agent-dashboard 0.5.3 → 0.5.4

package/packages/extension/src/__tests__/bridge-shutdown-reset.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Tests for the bridge's shutdown-time shadow-queue reset.
+ *
+ * Pure-model mirror of bridge.ts:786 `shutdown` extension command. If
+ * production drifts from this shape, this test drifts in lockstep.
+ *
+ * Spec: openspec/specs/mid-turn-prompt-queue/spec.md — requirement
+ * "Session shutdown resets shadow queues and clears pi's native queues"
+ * (added by change reset-shadow-queues-on-shutdown).
+ *
+ * See change: reset-shadow-queues-on-shutdown.
+ */
+import { describe, it, expect, vi } from "vitest";
+
+interface ShadowQueue {
+  steering: string[];
+  followUp: string[];
+}
+
+type QueueUpdateEmit = { steering: string[]; followUp: string[] };
+
+interface PiLike {
+  clearSteeringQueue?: () => void;
+  clearFollowUpQueue?: () => void;
+}
+
+interface CachedCtxLike {
+  shutdown?: () => void;
+}
+
+/**
+ * Pure version of the shutdown extension command. Mirrors bridge.ts
+ * 1:1 — defensive pi clears (unconditional), conditional shadow reset
+ * + emit, then cachedCtx.shutdown, then process.exit safety net.
+ */
+function makeShutdown(opts: {
+  pi: PiLike;
+  cachedCtx: CachedCtxLike | null;
+  queue: ShadowQueue;
+  onEmit: (snapshot: QueueUpdateEmit) => void;
+  onProcessExit: () => void;
+  callLog: string[];
+}) {
+  return () => {
+    try {
+      if (typeof opts.pi.clearSteeringQueue === "function") {
+        opts.callLog.push("pi.clearSteeringQueue");
+        opts.pi.clearSteeringQueue();
+      }
+    } catch {
+      // swallow — teardown must not throw
+    }
+    try {
+      if (typeof opts.pi.clearFollowUpQueue === "function") {
+        opts.callLog.push("pi.clearFollowUpQueue");
+        opts.pi.clearFollowUpQueue();
+      }
+    } catch {
+      // swallow
+    }
+    if (opts.queue.steering.length > 0 || opts.queue.followUp.length > 0) {
+      opts.queue.steering = [];
+      opts.queue.followUp = [];
+      opts.callLog.push("emitQueueUpdate");
+      opts.onEmit({ steering: [], followUp: [] });
+    }
+    if (opts.cachedCtx?.shutdown) {
+      opts.callLog.push("cachedCtx.shutdown");
+      opts.cachedCtx.shutdown();
+    }
+    opts.callLog.push("setTimeout(process.exit)");
+    opts.onProcessExit();
+  };
+}
+
+describe("bridge shutdown: shadow-queue reset", () => {
+  it("non-empty steering: resets shadow, emits one final queue_update with empty arrays", () => {
+    const queue: ShadowQueue = { steering: ["focus on X"], followUp: [] };
+    const onEmit = vi.fn();
+    const callLog: string[] = [];
+    const pi: PiLike = { clearSteeringQueue: vi.fn(), clearFollowUpQueue: vi.fn() };
+    const cachedCtx: CachedCtxLike = { shutdown: vi.fn() };
+
+    makeShutdown({ pi, cachedCtx, queue, onEmit, onProcessExit: vi.fn(), callLog })();
+
+    expect(queue.steering).toEqual([]);
+    expect(queue.followUp).toEqual([]);
+    expect(onEmit).toHaveBeenCalledTimes(1);
+    expect(onEmit).toHaveBeenCalledWith({ steering: [], followUp: [] });
+  });
+
+  it("non-empty followUp: resets shadow, emits one final queue_update", () => {
+    const queue: ShadowQueue = { steering: [], followUp: ["run tests when done"] };
+    const onEmit = vi.fn();
+    const pi: PiLike = { clearSteeringQueue: vi.fn(), clearFollowUpQueue: vi.fn() };
+    const cachedCtx: CachedCtxLike = { shutdown: vi.fn() };
+
+    makeShutdown({ pi, cachedCtx, queue, onEmit, onProcessExit: vi.fn(), callLog: [] })();
+
+    expect(queue).toEqual({ steering: [], followUp: [] });
+    expect(onEmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("both queues non-empty: emits exactly once (not twice)", () => {
+    const queue: ShadowQueue = { steering: ["a", "b"], followUp: ["c"] };
+    const onEmit = vi.fn();
+    const pi: PiLike = { clearSteeringQueue: vi.fn(), clearFollowUpQueue: vi.fn() };
+
+    makeShutdown({
+      pi,
+      cachedCtx: { shutdown: vi.fn() },
+      queue,
+      onEmit,
+      onProcessExit: vi.fn(),
+      callLog: [],
+    })();
+
+    expect(queue).toEqual({ steering: [], followUp: [] });
+    expect(onEmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("both queues empty: does NOT emit queue_update, still calls pi.clear* defensively", () => {
+    const queue: ShadowQueue = { steering: [], followUp: [] };
+    const onEmit = vi.fn();
+    const clearSteer = vi.fn();
+    const clearFollow = vi.fn();
+    const pi: PiLike = { clearSteeringQueue: clearSteer, clearFollowUpQueue: clearFollow };
+
+    makeShutdown({
+      pi,
+      cachedCtx: { shutdown: vi.fn() },
+      queue,
+      onEmit,
+      onProcessExit: vi.fn(),
+      callLog: [],
+    })();
+
+    expect(onEmit).not.toHaveBeenCalled();
+    // Defensive clears run unconditionally — pi's queues may be non-empty
+    // from non-dashboard sources.
+    expect(clearSteer).toHaveBeenCalledTimes(1);
+    expect(clearFollow).toHaveBeenCalledTimes(1);
+  });
+
+  it("pi missing clearSteeringQueue / clearFollowUpQueue: still resets shadow + emits + does not throw", () => {
+    const queue: ShadowQueue = { steering: ["a"], followUp: ["b"] };
+    const onEmit = vi.fn();
+    const pi: PiLike = {}; // both functions absent — pi version skew
+    const cachedCtx: CachedCtxLike = { shutdown: vi.fn() };
+
+    expect(() => {
+      makeShutdown({ pi, cachedCtx, queue, onEmit, onProcessExit: vi.fn(), callLog: [] })();
+    }).not.toThrow();
+
+    expect(queue).toEqual({ steering: [], followUp: [] });
+    expect(onEmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("pi.clearSteeringQueue throws: teardown continues (shadow still reset, emit still fires, cachedCtx.shutdown still called)", () => {
+    const queue: ShadowQueue = { steering: ["a"], followUp: [] };
+    const onEmit = vi.fn();
+    const cachedShutdown = vi.fn();
+    const pi: PiLike = {
+      clearSteeringQueue: () => {
+        throw new Error("boom");
+      },
+      clearFollowUpQueue: vi.fn(),
+    };
+
+    expect(() => {
+      makeShutdown({
+        pi,
+        cachedCtx: { shutdown: cachedShutdown },
+        queue,
+        onEmit,
+        onProcessExit: vi.fn(),
+        callLog: [],
+      })();
+    }).not.toThrow();
+
+    expect(queue).toEqual({ steering: [], followUp: [] });
+    expect(onEmit).toHaveBeenCalledTimes(1);
+    expect(cachedShutdown).toHaveBeenCalledTimes(1);
+  });
+
+  it("order of operations: pi.clearSteeringQueue → pi.clearFollowUpQueue → emitQueueUpdate → cachedCtx.shutdown → process.exit", () => {
+    const queue: ShadowQueue = { steering: ["a"], followUp: ["b"] };
+    const callLog: string[] = [];
+    const pi: PiLike = { clearSteeringQueue: vi.fn(), clearFollowUpQueue: vi.fn() };
+    const cachedCtx: CachedCtxLike = { shutdown: vi.fn() };
+
+    makeShutdown({ pi, cachedCtx, queue, onEmit: vi.fn(), onProcessExit: vi.fn(), callLog })();
+
+    expect(callLog).toEqual([
+      "pi.clearSteeringQueue",
+      "pi.clearFollowUpQueue",
+      "emitQueueUpdate",
+      "cachedCtx.shutdown",
+      "setTimeout(process.exit)",
+    ]);
+  });
+
+  it("safety-net: cachedCtx.shutdown still called and process.exit scheduled when shadows are empty", () => {
+    const queue: ShadowQueue = { steering: [], followUp: [] };
+    const cachedShutdown = vi.fn();
+    const onProcessExit = vi.fn();
+    const pi: PiLike = { clearSteeringQueue: vi.fn(), clearFollowUpQueue: vi.fn() };
+
+    makeShutdown({
+      pi,
+      cachedCtx: { shutdown: cachedShutdown },
+      queue,
+      onEmit: vi.fn(),
+      onProcessExit,
+      callLog: [],
+    })();
+
+    expect(cachedShutdown).toHaveBeenCalledTimes(1);
+    expect(onProcessExit).toHaveBeenCalledTimes(1);
+  });
+
+  it("safety-net: process.exit scheduled even when cachedCtx is null", () => {
+    const queue: ShadowQueue = { steering: ["a"], followUp: [] };
+    const onProcessExit = vi.fn();
+    const pi: PiLike = { clearSteeringQueue: vi.fn(), clearFollowUpQueue: vi.fn() };
+
+    makeShutdown({
+      pi,
+      cachedCtx: null,
+      queue,
+      onEmit: vi.fn(),
+      onProcessExit,
+      callLog: [],
+    })();
+
+    expect(onProcessExit).toHaveBeenCalledTimes(1);
+  });
+});

package/packages/extension/src/__tests__/bridge-slash-command-routing.test.ts

@@ -59,10 +59,10 @@ function feedbackEvents(sink: ReturnType<typeof vi.fn>, command: string) {
     .map((m) => (m as any).event.data);
 }
 
-async function drive(text: string, stub: ReturnType<typeof makeStubPi>) {
+async function drive(text: string, stub: ReturnType<typeof makeStubPi>, delivery?: "steer" | "followUp") {
   const sink = vi.fn();
   const handler = createCommandHandler(stub.pi as any, "s1", { eventSink: sink });
-  await handler.handle({ type: "send_prompt", sessionId: "s1", text } as any);
+  await handler.handle({ type: "send_prompt", sessionId: "s1", text, delivery } as any);
   return sink;
 }
 
@@ -80,16 +80,32 @@ describe("bridge slash command routing (regression contract)", () => {
     expect(evs.map((e) => e.status)).toEqual(["started", "completed"]);
   });
 
-  it("extension cmd, NO dispatchCommand → stopgap error, no sendUserMessage, started+error", async () => {
-    // regression: see openspec/changes/fix-extension-slash-commands-in-dashboard/
+  it("extension cmd with delivery: steer → dispatchCommand called with streamingBehavior: steer", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    const sink = await drive("/ctx-stats", stub, "steer");
+
+    expect(stub.dispatchCommand).toHaveBeenCalledTimes(1);
+    expect(stub.dispatchCommand).toHaveBeenCalledWith("/ctx-stats", { streamingBehavior: "steer" });
+    expect(stub.sendUserMessage).not.toHaveBeenCalled();
+
+    const evs = feedbackEvents(sink, "/ctx-stats");
+    expect(evs.map((e) => e.status)).toEqual(["started", "completed"]);
+  });
+
+  it("extension cmd, NO dispatchCommand, not headless → error feedback with rpc-keeper hint, no sendUserMessage", async () => {
+    // Path D: extension commands cannot be dispatched for non-headless sessions.
+    // Emits error with hint to enable useRpcKeeper for headless mode.
+    // See change: fix-slash-dispatch-delivery.
     const stub = makeStubPi({ withDispatch: false });
     const sink = await drive("/ctx-stats", stub);
 
+    // sendUserMessage is NOT called — the command is handled (with error).
     expect(stub.sendUserMessage).not.toHaveBeenCalled();
 
+    // Error feedback emitted with rpc-keeper hint.
     const evs = feedbackEvents(sink, "/ctx-stats");
-    expect(evs.map((e) => e.status)).toEqual(["started", "error"]);
-    expect(evs[1].message).toMatch(/pi 0\.71\+/);
+    expect(evs.map((e) => e.status)).toEqual(["error"]);
+    expect(evs[0].message).toContain("useRpcKeeper");
   });
 
   it("extension cmd dispatch rejects → started+error with err.message, no sendUserMessage", async () => {
@@ -169,21 +185,28 @@ describe("bridge slash command routing (regression contract)", () => {
     expect(evs.filter((e) => e.status === "completed" || e.status === "error")).toHaveLength(1);
   });
 
-  it("never duplicates command_feedback on stopgap path", async () => {
+  it("error feedback on fallthrough path (dispatchCommand absent, non-headless)", async () => {
+    // Path D returns true with error feedback (including rpc-keeper hint).
+    // See change: fix-slash-dispatch-delivery.
     const stub = makeStubPi({ withDispatch: false });
     const sink = await drive("/ctx-stats", stub);
     const evs = feedbackEvents(sink, "/ctx-stats");
-    expect(evs.filter((e) => e.status === "started")).toHaveLength(1);
-    expect(evs.filter((e) => e.status === "completed" || e.status === "error")).toHaveLength(1);
+    expect(evs).toHaveLength(1);
+    expect(evs[0].status).toBe("error");
+    expect(evs[0].message).toContain("useRpcKeeper");
   });
 
-  it("anti-regression: /ctx-stats NEVER reaches sendUserMessage", async () => {
-    // regression: see openspec/changes/fix-extension-slash-commands-in-dashboard/
-    for (const withDispatch of [true, false]) {
-      const stub = makeStubPi({ withDispatch });
-      await drive("/ctx-stats", stub);
-      expect(stub.sendUserMessage, `withDispatch=${withDispatch}`).not.toHaveBeenCalled();
-    }
+  it("anti-regression: /ctx-stats does NOT reach sendUserMessage when dispatchCommand absent", async () => {
+    // Path D now emits error feedback instead of falling through silently.
+    // Extension commands can only be dispatched for headless sessions with
+    // the RPC keeper enabled. See change: fix-slash-dispatch-delivery.
+    const stub = makeStubPi({ withDispatch: false });
+    const sink = await drive("/ctx-stats", stub);
+    // sendUserMessage is NOT called — command handled with error feedback.
+    expect(stub.sendUserMessage).not.toHaveBeenCalled();
+    const evs = feedbackEvents(sink, "/ctx-stats");
+    expect(evs).toHaveLength(1);
+    expect(evs[0].status).toBe("error");
   });
 });
 
@@ -270,36 +293,37 @@ describe("tryDispatchExtensionCommand: Path B/C/D mutual exclusion", () => {
     expect(evs).toEqual(["started"]);
   });
 
-  it("Path D: no dispatchCommand + non-headless + connection → stopgap error; no connection.send", async () => {
+  it("Path D: no dispatchCommand + non-headless → returns true with error feedback including rpc-keeper hint", async () => {
     const { pi } = makePi({ withDispatch: false });
     const sink = vi.fn();
     const { conn, sent } = makeConn();
     setHeadless(false);
 
     const handled = await tryDispatchExtensionCommand(pi, "/ctx-stats", "sid", sink, conn);
-    expect(handled).toBe(true);
+    expect(handled).toBe(true); // handled with error feedback
     expect(sent.filter((m) => m.type === "dispatch_extension_command")).toEqual([]);
+    // Error feedback emitted with rpc-keeper hint.
     const evs = sink.mock.calls
       .map((c: any[]) => c[0])
       .filter((m: any) => m?.event?.eventType === "command_feedback");
-    expect(evs).toHaveLength(2);
-    expect(evs[0].event.data.status).toBe("started");
-    expect(evs[1].event.data.status).toBe("error");
-    expect(evs[1].event.data.message).toMatch(/pi 0\.71\+/);
+    expect(evs).toHaveLength(1);
+    expect((evs[0] as any).event.data.status).toBe("error");
+    expect((evs[0] as any).event.data.message).toContain("useRpcKeeper");
   });
 
-  it("Path C degrades to Path D when connection arg is undefined", async () => {
+  it("Path D: no dispatchCommand + no connection → returns true with error feedback", async () => {
     const { pi } = makePi({ withDispatch: false });
     const sink = vi.fn();
-    setHeadless(true);
+    setHeadless(false);
 
     const handled = await tryDispatchExtensionCommand(pi, "/ctx-stats", "sid", sink, undefined);
-    expect(handled).toBe(true);
+    expect(handled).toBe(true); // handled with error feedback
+    // Error feedback emitted with rpc-keeper hint.
     const evs = sink.mock.calls
       .map((c: any[]) => c[0])
       .filter((m: any) => m?.event?.eventType === "command_feedback");
-    // started + error (Path D fallback) — NOT just started.
-    expect(evs.map((e: any) => e.event.data.status)).toEqual(["started", "error"]);
+    expect(evs).toHaveLength(1);
+    expect((evs[0] as any).event.data.status).toBe("error");
   });
 
   it("non-extension /skill:foo → returns false; no path fires; no events", async () => {
@@ -332,19 +356,91 @@ describe("tryDispatchExtensionCommand: Path B/C/D mutual exclusion", () => {
       const { conn, sent } = makeConn();
       setHeadless(s.headless);
 
-      await tryDispatchExtensionCommand(pi, "/ctx-stats", "sid", sink, conn);
+      const handled = await tryDispatchExtensionCommand(pi, "/ctx-stats", "sid", sink, conn);
 
       const dispatchedB = !!dispatchCommand && dispatchCommand.mock.calls.length > 0;
       const dispatchedC = sent.some((m) => m.type === "dispatch_extension_command");
-      const errorD = sink.mock.calls.some((c: any[]) =>
-        (c[0] as any)?.event?.data?.status === "error");
+      const dispatchedD = sink.mock.calls
+        .map((c: any[]) => c[0])
+        .some((m: any) => m?.event?.eventType === "command_feedback" && m?.event?.data?.status === "error");
+
+      expect(handled, JSON.stringify(s)).toBe(true); // all paths now handle the command
 
-      const fired = [dispatchedB && "B", dispatchedC && "C", errorD && "D"].filter(Boolean);
+      const fired = [dispatchedB && "B", dispatchedC && "C", dispatchedD && "D"].filter(Boolean);
       expect(fired, JSON.stringify(s)).toEqual([s.expect]);
     }
   });
 });
 
+// See change: add-steering-message (task 4.4).
+// Verify the slash-routing fallback paths that call sendUserMessage honor the
+// delivery field — `"steer"` → deliverAs:"steer"; absent/"followUp" → deliverAs:"followUp".
+describe("bridge slash routing: delivery field → sendUserMessage deliverAs", () => {
+  function lastDeliverAs(sendUserMessage: ReturnType<typeof vi.fn>): string | undefined {
+    const lastCall = sendUserMessage.mock.calls.at(-1);
+    if (!lastCall) return undefined;
+    const opts = lastCall[1];
+    return opts?.deliverAs;
+  }
+
+  it("skill command + delivery:'steer' → sendUserMessage called with deliverAs:'steer'", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    await drive("/skill:foo", stub, "steer");
+    expect(stub.sendUserMessage).toHaveBeenCalledTimes(1);
+    expect(lastDeliverAs(stub.sendUserMessage)).toBe("steer");
+  });
+
+  it("skill command + delivery:'followUp' → sendUserMessage called with deliverAs:'followUp'", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    await drive("/skill:foo", stub, "followUp");
+    expect(stub.sendUserMessage).toHaveBeenCalledTimes(1);
+    expect(lastDeliverAs(stub.sendUserMessage)).toBe("followUp");
+  });
+
+  it("skill command + delivery omitted → sendUserMessage defaults to deliverAs:'followUp'", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    await drive("/skill:foo", stub);
+    expect(stub.sendUserMessage).toHaveBeenCalledTimes(1);
+    expect(lastDeliverAs(stub.sendUserMessage)).toBe("followUp");
+  });
+
+  it("prompt template + delivery:'steer' → deliverAs:'steer'", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    await drive("/review", stub, "steer");
+    expect(lastDeliverAs(stub.sendUserMessage)).toBe("steer");
+  });
+
+  it("passthrough text + delivery:'steer' → deliverAs:'steer'", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    await drive("hello world", stub, "steer");
+    expect(lastDeliverAs(stub.sendUserMessage)).toBe("steer");
+  });
+
+  it("passthrough text + delivery omitted → deliverAs:'followUp'", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    await drive("hello world", stub);
+    expect(lastDeliverAs(stub.sendUserMessage)).toBe("followUp");
+  });
+
+  it("unrecognized slash + delivery:'steer' → deliverAs:'steer'", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    await drive("/totally-unknown-command", stub, "steer");
+    expect(lastDeliverAs(stub.sendUserMessage)).toBe("steer");
+  });
+
+  it("bridge-native /__dashboard_reload fallback + delivery:'steer' → deliverAs:'steer'", async () => {
+    const stub = makeStubPi({ withDispatch: true });
+    await drive("/__dashboard_reload", stub, "steer");
+    expect(lastDeliverAs(stub.sendUserMessage)).toBe("steer");
+  });
+
+  it("getCommands throws fallback + delivery:'steer' → deliverAs:'steer'", async () => {
+    const stub = makeStubPi({ withDispatch: true, getCommandsThrows: true });
+    await drive("/ctx-stats", stub, "steer");
+    expect(lastDeliverAs(stub.sendUserMessage)).toBe("steer");
+  });
+});
+
 describe("hasDispatchCommand", () => {
   it("returns true when field is a function", () => {
     expect(hasDispatchCommand({ dispatchCommand: () => {} })).toBe(true);

package/packages/extension/src/__tests__/command-handler.test.ts

@@ -12,6 +12,7 @@ describe("CommandHandler", () => {
       setSessionName: vi.fn(),
       getSessionName: vi.fn(),
       on: vi.fn(),
+      exec: vi.fn(),
     };
   }
 
@@ -481,7 +482,7 @@ describe("CommandHandler", () => {
 
       await handler.handle({ type: "send_prompt", sessionId: "s1", text: "/some-command args" });
 
-      expect(sessionPrompt).toHaveBeenCalledWith("/some-command args");
+      expect(sessionPrompt).toHaveBeenCalledWith("/some-command args", undefined);
       expect(pi.sendUserMessage).not.toHaveBeenCalled();
     });
 
@@ -513,7 +514,8 @@ describe("CommandHandler", () => {
 
       await handler.handle({ type: "send_prompt", sessionId: "s1", text: "/some-command" });
 
-      expect(pi.sendUserMessage).toHaveBeenCalledWith("/some-command");
+      // Slash fallback forwards delivery (default 'followUp'). See change: add-steering-message.
+      expect(pi.sendUserMessage).toHaveBeenCalledWith("/some-command", { deliverAs: "followUp" });
       const feedbackCalls = eventSink.mock.calls.filter(
         (c) => (c[0] as any)?.event?.eventType === "command_feedback",
       );
@@ -526,7 +528,7 @@ describe("CommandHandler", () => {
 
       await handler.handle({ type: "send_prompt", sessionId: "s1", text: "/some-command args" });
 
-      expect(pi.sendUserMessage).toHaveBeenCalledWith("/some-command args");
+      expect(pi.sendUserMessage).toHaveBeenCalledWith("/some-command args", { deliverAs: "followUp" });
     });
 
     it("should route /quit to shutdown", async () => {
@@ -780,3 +782,103 @@ describe("parseSendPrompt", () => {
     });
   });
 });
+
+describe("CommandHandler delivery routing (pi-native queues)", () => {
+  // After change: add-followup-edit-and-steer-cancel, the bridge no longer
+  // owns a parallel queue. All passthrough sends go directly to pi.sendUserMessage;
+  // followUp delivery additionally calls pi.clearFollowUpQueue() first to enforce
+  // capacity-1 on the slot.
+  function createMockPi() {
+    return {
+      sendUserMessage: vi.fn(),
+      getCommands: vi.fn().mockReturnValue([]),
+      setSessionName: vi.fn(),
+      getSessionName: vi.fn(),
+      on: vi.fn(),
+      exec: vi.fn(),
+      clearFollowUpQueue: vi.fn(),
+      clearSteeringQueue: vi.fn(),
+    };
+  }
+
+  it("passthrough followUp APPENDS to pi's queue (v2: no pre-clear)", async () => {
+    const pi = createMockPi();
+    const handler = createCommandHandler(pi as any, "s1");
+
+    await handler.handle({ type: "send_prompt", sessionId: "s1", text: "after done", delivery: "followUp" });
+
+    // v2: cap-1 invariant dropped. clearFollowUpQueue is only called by explicit
+    // promote/remove/edit operations, not on every send.
+    expect(pi.clearFollowUpQueue).not.toHaveBeenCalled();
+    expect(pi.sendUserMessage).toHaveBeenCalledWith("after done", { deliverAs: "followUp" });
+  });
+
+  it("passthrough delivery absent defaults to followUp and APPENDS (v2)", async () => {
+    const pi = createMockPi();
+    const handler = createCommandHandler(pi as any, "s1");
+
+    await handler.handle({ type: "send_prompt", sessionId: "s1", text: "plain" });
+
+    expect(pi.clearFollowUpQueue).not.toHaveBeenCalled();
+    expect(pi.sendUserMessage).toHaveBeenCalledWith("plain", { deliverAs: "followUp" });
+  });
+
+  it("passthrough delivery steer does NOT call clearFollowUpQueue or clearSteeringQueue", async () => {
+    const pi = createMockPi();
+    const handler = createCommandHandler(pi as any, "s1");
+
+    await handler.handle({ type: "send_prompt", sessionId: "s1", text: "focus on X", delivery: "steer" });
+
+    expect(pi.clearFollowUpQueue).not.toHaveBeenCalled();
+    expect(pi.clearSteeringQueue).not.toHaveBeenCalled();
+    expect(pi.sendUserMessage).toHaveBeenCalledWith("focus on X", { deliverAs: "steer" });
+  });
+
+  it("passthrough with images preserves image content (v2: no pre-clear)", async () => {
+    const pi = createMockPi();
+    const images = [{ type: "image" as const, data: "AAA", mimeType: "image/png" }];
+    const handler = createCommandHandler(pi as any, "s1");
+
+    await handler.handle({ type: "send_prompt", sessionId: "s1", text: "img", images, delivery: "followUp" });
+
+    expect(pi.clearFollowUpQueue).not.toHaveBeenCalled();
+    expect(pi.sendUserMessage).toHaveBeenCalledTimes(1);
+    const [content, opts] = pi.sendUserMessage.mock.calls[0];
+    expect(opts).toEqual({ deliverAs: "followUp" });
+    expect(Array.isArray(content)).toBe(true);
+  });
+
+  it("bash commands bypass delivery routing entirely (no clearFollowUpQueue call)", async () => {
+    const pi = createMockPi();
+    pi.exec = vi.fn().mockResolvedValue({ stdout: "hi", stderr: "", exitCode: 0 });
+    const handler = createCommandHandler(pi as any, "s1");
+
+    await handler.handle({ type: "send_prompt", sessionId: "s1", text: "!ls" });
+
+    // Bash handler forwards stdout via sendUserMessage as its result, but
+    // delivery routing is not involved — no clearFollowUpQueue or deliverAs option.
+    expect(pi.clearFollowUpQueue).not.toHaveBeenCalled();
+    expect(pi.clearSteeringQueue).not.toHaveBeenCalled();
+  });
+
+  it("slash command with delivery=steer passes delivery to sessionPrompt; no pi call from handler", async () => {
+    const pi = createMockPi();
+    const sessionPrompt = vi.fn();
+    const handler = createCommandHandler(pi as any, "s1", { sessionPrompt });
+
+    await handler.handle({ type: "send_prompt", sessionId: "s1", text: "/some-command args", delivery: "steer" });
+
+    expect(sessionPrompt).toHaveBeenCalledWith("/some-command args", "steer");
+    expect(pi.sendUserMessage).not.toHaveBeenCalled();
+  });
+
+  it("abort no longer requires clearQueueOnAbort option", async () => {
+    const pi = createMockPi();
+    const abort = vi.fn();
+    const handler = createCommandHandler(pi as any, "s1", { abort });
+
+    await handler.handle({ type: "abort", sessionId: "s1" });
+
+    expect(abort).toHaveBeenCalledTimes(1);
+  });
+});