pi-onlyne 1.1.2 → 1.2.1

package/src/agent.test.mjs

@@ -3,7 +3,7 @@
 // wire vector, so the input side is byte-identical to what the client sends.
 
 import assert from "node:assert/strict";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -12,6 +12,7 @@ import { afterEach, test } from "node:test";
 
 import { OnlyneAgent } from "./agent.mjs";
 import { MAX_LINES, MAX_WIDTH } from "./activity.mjs";
+import { DEFAULT_IDLE_REMINDERS } from "./config.mjs";
 import { createFrameDecoder, encodeFrame } from "./frame.mjs";
 import { SEQ_BASE, readyReport } from "./protocol.mjs";
 
@@ -22,6 +23,15 @@ const ASSIGN_FRAME = existsSync(VECTOR_DIR)
   ? JSON.parse(JSON.parse(readFileSync(`${VECTOR_DIR}adapter_host_assign.json`, "utf8")).frame)
   : null;
 const TASK_ID = "11111111-1111-4111-8111-111111111111";
+/** A task the host hands this session, distinct from the id it was spawned with. */
+const ASSIGNED_TASK_ID = "33333333-3333-4333-8333-333333333333";
+/**
+ * The answer a real host gives one `handoff`: the child it minted, and the hop
+ * that child sits at. The hop is a figure no client can derive — it comes off
+ * the parent's causality — so a test asserting it reads the host's own number.
+ */
+const CHILD_TASK_ID = "22222222-2222-4222-8222-222222222222";
+const HANDOFF_ANSWER = { task_id: CHILD_TASK_ID, hop: 3, queued: true, op_id: `o-${CHILD_TASK_ID}` };
 const SESSION_ID = "8b1c";
 const PANE_KEY = "45e603f7-0772-48aa-bcf6-832272747713:b6d067b6-9255-4f5c-a13f-24f194ea0560";
 const PANE_TAB = "45e603f7-0772-48aa-bcf6-832272747713";
@@ -42,6 +52,34 @@ function heartbeats(host) {
     .map((args) => args.data.observed);
 }
 
+/**
+ * The exact keys of a plugin observation outside a pane. `agent`, `resource` and
+ * the reconcile defaults are what the plugin states; `delivery` and `recovery`
+ * ride as placeholders the client overwrites with its own records, and no
+ * outcome or public view travels in a tuple at all.
+ */
+const OBSERVED_KEYS = [
+  "version",
+  "generation_live",
+  "isolate_after",
+  "terminate_after",
+  "mismatch_count",
+  "agent",
+  "delivery",
+  "resource",
+  "recovery",
+];
+
+/**
+ * The observation's keys with the pane binding discounted: `host` rides along
+ * when the process was spawned in an Orca pane, and the test host's own
+ * environment decides whether it does.
+ */
+function dimensionKeys(observed) {
+  const { host, ...rest } = observed;
+  return Object.keys(rest);
+}
+
 /** Poll until `predicate` holds, so a test never races the event loop. */
 async function waitFor(predicate, { timeoutMs = 2_000, stepMs = 5 } = {}) {
   const deadline = Date.now() + timeoutMs;
@@ -63,9 +101,12 @@ async function waitFor(predicate, { timeoutMs = 2_000, stepMs = 5 } = {}) {
  * the client has acknowledged the outcome. `failSend` refuses every `send` the
  * way a client with no route to the target would. The ready and heartbeat
  * reports are never held: the handshake waits on them.
+ * `handoffError` refuses every `handoff` with that error body, the way a client
+ * that cannot find the task the session names would; with none, the fake answers
+ * the child the proto documents.
  */
 class FakeHost {
-  constructor({ coalesceAssign = null, holdCompletion = false, failSend = false } = {}) {
+  constructor({ coalesceAssign = null, holdCompletion = false, failSend = false, handoffError = null } = {}) {
     this.server = createServer((socket) => this.onConnection(socket));
     this.frames = [];
     this.sockets = new Set();
@@ -73,6 +114,7 @@ class FakeHost {
     this.coalesceAssign = coalesceAssign;
     this.holdCompletion = holdCompletion;
     this.failSend = failSend;
+    this.handoffError = handoffError;
     this.held = [];
   }
 
@@ -126,6 +168,11 @@ class FakeHost {
       }));
       return;
     }
+    if (frame.op === "handoff") {
+      body = this.handoffError
+        ? { ok: false, error: this.handoffError }
+        : { ok: true, data: HANDOFF_ANSWER };
+    }
     const reply = encodeFrame({ reply_to: frame.id, ...body });
     const push = frame.op === "hello" && this.coalesceAssign
       ? encodeFrame({ op: "assign", args: this.coalesceAssign })
@@ -159,6 +206,7 @@ class FakeHost {
 /** The effect surface the agent drives, recorded for assertions. */
 function fakeSurface(options = {}) {
   const calls = { wakeUser: [], prose: [], entries: [], status: [], exits: [], widget: [] };
+  const flag = (value, fallback) => (value === undefined ? fallback : typeof value === "function" ? value() : value);
   return {
     calls,
     available: {
@@ -190,6 +238,9 @@ function fakeSurface(options = {}) {
     widget: (lines) => calls.widget.push(lines),
     welcome: () => {},
     isIdle: () => (options.idle === undefined ? true : options.idle()),
+    async waitingForInput() {
+      return Boolean(flag(options.waiting, true) && !flag(options.backgroundWork, false));
+    },
     exit: (reason) => calls.exits.push(reason),
   };
 }
@@ -202,11 +253,12 @@ async function startAgent({
   coalesceAssign = null,
   holdCompletion = false,
   failSend = false,
+  handoffError = null,
   relay = null,
 } = {}) {
   const dir = mkdtempSync(join(tmpdir(), "pi-onlyne-agent-"));
   const socketPath = join(dir, "s");
-  const host = new FakeHost({ coalesceAssign, holdCompletion, failSend });
+  const host = new FakeHost({ coalesceAssign, holdCompletion, failSend, handoffError });
   await host.listen(socketPath);
   const logs = [];
   const agent = new OnlyneAgent({
@@ -297,8 +349,9 @@ test("every heartbeat names the Orca pane this process was spawned in", async ()
       orca: { pane_key: PANE_KEY, tab_id: PANE_TAB, leaf_id: PANE_LEAF, handle: "term_1" },
     });
     // The binding rides beside the state dimensions instead of replacing them.
-    assert.equal(observed.agent, "running");
-    assert.equal(observed.public, "working");
+    assert.equal(observed.agent, "idle", "the default fake surface is waiting for input");
+    assert.equal(observed.resource, "attached");
+    assert.deepEqual(Object.keys(observed), [...OBSERVED_KEYS, "host"]);
     assert.equal(observed.version.generation, 1);
   });
 });
@@ -348,7 +401,7 @@ test("a pi outside an Orca pane reports no host at all", async () => {
 
     const [observed] = await waitFor(() => (heartbeats(host).length ? heartbeats(host) : null));
     assert.equal("host" in observed, false, "no pane, no binding");
-    assert.equal(observed.agent, "running", "the tuple is still a full observation");
+    assert.equal(observed.agent, "idle", "the tuple is still a full observation");
   });
 });
 
@@ -535,7 +588,7 @@ test("an assign sharing the hello reply's chunk waits for the welcome", async ()
   assert.deepEqual(acks[0], { task_id: TASK_ID, accepted: true });
 });
 
-test("turn hooks report running then idle, and a settle completes done with the head", async () => {
+test("a waiting turn end reports idle, and the settle after it re-sends the assignment", async () => {
   const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
@@ -545,31 +598,57 @@ test("turn hooks report running then idle, and a settle completes done with the
   agent.onTurnStart();
   const running = await waitFor(() => host.of("report").find((report) => report.data?.observed?.agent === "running"));
   assert.equal(running.kind, "heartbeat");
-  assert.equal(running.data.observed.public, "working");
+  assert.equal(running.data.observed.resource, "attached");
+  assert.deepEqual(dimensionKeys(running.data.observed), OBSERVED_KEYS, "a running beat carries exactly the dimensions the plugin can see");
   assert.equal(running.data.observed.version.generation, 1);
 
   agent.onTurnEnd();
   const idle = await waitFor(() => host.of("report").find((report) => report.data?.observed?.agent === "idle"));
-  assert.equal(idle.data.observed.public, "idle");
+  assert.equal(idle.kind, "heartbeat");
+  assert.deepEqual(dimensionKeys(idle.data.observed), OBSERVED_KEYS, "an idle beat claims no dimension the plugin does not own");
 
   agent.noteAssistantText("OK");
   agent.onSettled();
-  const complete = await waitFor(() => host.of("report").find((report) => report.kind === "complete"));
-  assert.deepEqual(complete, { kind: "complete", data: { task_id: TASK_ID, outcome: "done", head: "OK" } });
-  assert.deepEqual(agent.status().tasks, []);
-  // The completion ends the session: the process that ran it is asked to leave.
-  assert.deepEqual(surface.calls.exits, ["done"]);
-  // Heartbeats stop with the last task, so a settled session stops writing.
-  const reports = host.of("report").length;
-  await new Promise((resolve) => setTimeout(resolve, 120));
-  assert.equal(host.of("report").length, reports);
+  // A turn that ends without a completion leaves the task open: the settle sends
+  // the assignment again rather than reporting an outcome the model never
+  // claimed. `onlyne_complete` is the only path to `done`.
+  const reminded = await waitFor(() =>
+    surface.calls.wakeUser.length === 2 ? surface.calls.wakeUser : null,
+  );
+  assert.match(reminded[1].text, /build it/, "the reminder carries the task text");
+  assert.deepEqual(host.of("report").filter((report) => report.kind === "complete"), []);
+  assert.deepEqual(surface.calls.exits, [], "a task with a rung left is not failed");
+});
+
+test("a busy turn end reports no idle beat and does not settle the ladder", async () => {
+  const surface = fakeSurface({ waiting: false });
+  const { agent, host } = await startAgent({ surface });
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+  host.notify("assign", assignArgs());
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  agent.onTurnStart();
+  await waitFor(() => host.of("report").find((report) => report.data?.observed?.agent === "running"));
+  agent.onTurnEnd();
+  agent.onSettled();
+  await waitFor(() => heartbeats(host).length >= 3);
+
+  assert.equal(
+    heartbeats(host).some((observed) => observed.agent === "idle"),
+    false,
+    "the turn-end beat follows the busy surface rather than assuming the hook means idle",
+  );
+  assert.equal(surface.calls.wakeUser.length, 1, "the ladder waits while the turn is still running");
+  assert.deepEqual(surface.calls.exits, []);
 });
 
 // The live case found this ordering too: pi's turn-end hook fires in the same
 // millisecond as the settle that reports the completion, so the turn-end
-// heartbeat lands after the completion report. `observed` is a whole snapshot,
-// and one carrying `delivery: none`/`outcome: pending` puts the session back to
-// `idle` after the host has already recorded `exited`.
+// heartbeat lands after the completion report. The beat no longer carries a
+// delivery or recovery the host would believe — the client composes those from
+// its own records — but a snapshot of an agent dimension nobody is watching any
+// more is still a frame the protocol does not need, so the plugin stays quiet.
 test("a turn-end heartbeat after the completion never leaves the plugin", async () => {
   const { agent, host, surface } = await startAgent();
   agent.start();
@@ -588,23 +667,172 @@ test("a turn-end heartbeat after the completion never leaves the plugin", async
   assert.deepEqual(host.of("report").slice(reports), [], "the completion is the last report");
 });
 
-test("a busy pi holds the completion until it is idle", async () => {
-  let idle = false;
-  const surface = fakeSurface({ idle: () => idle });
+test("a busy pi holds the settle decision until it is waiting for input", async () => {
+  let waiting = false;
+  const surface = fakeSurface({ waiting: () => waiting });
+  const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+  host.notify("assign", assignArgs());
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+  agent.onTurnEnd();
+  agent.onSettled();
+  await new Promise((resolve) => setTimeout(resolve, 80));
+  assert.equal(surface.calls.wakeUser.length, 1, "a busy pi is not reminded");
+
+  waiting = true;
+  const reminded = await waitFor(() =>
+    surface.calls.wakeUser.length === 2 ? surface.calls.wakeUser : null,
+  );
+  assert.match(reminded[1].text, /build it/, "the decision waits for the idle it is about");
+});
+
+test("queued input keeps the session non-idle and holds the ladder off", async () => {
+  let queued = false;
+  const surface = fakeSurface({ waiting: () => !queued });
+  const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+  host.notify("assign", assignArgs());
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  agent.onTurnStart();
+  queued = true;
+  agent.onTurnEnd();
+  agent.onSettled();
+  await waitFor(() => heartbeats(host).at(-1)?.agent === "running");
+  await new Promise((resolve) => setTimeout(resolve, 80));
+
+  assert.equal(surface.calls.wakeUser.length, 1, "a queued continuation is not an idle episode");
+  assert.deepEqual(surface.calls.exits, []);
+});
+
+test("a live background task holds the ladder off until its task is terminal", async () => {
+  let backgroundWork = true;
+  const surface = fakeSurface({ backgroundWork: () => backgroundWork });
   const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
   host.notify("assign", assignArgs());
   await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  agent.onTurnStart();
   agent.onTurnEnd();
-  agent.noteAssistantText("still working");
   agent.onSettled();
+  await waitFor(() => heartbeats(host).at(-1)?.agent === "running");
   await new Promise((resolve) => setTimeout(resolve, 80));
+  assert.equal(surface.calls.wakeUser.length, 1, "work off the agent loop keeps the ladder off");
+
+  backgroundWork = false;
+  agent.onSettled();
+  const reminded = await waitFor(() =>
+    surface.calls.wakeUser.length === 2 ? surface.calls.wakeUser : null,
+  );
+  assert.match(reminded[1].text, /build it/, "the terminal task releases the idle ladder");
+});
+
+// The idle ladder (`docs/SWARM-REFACTOR-GRILLME.md` §4.2): a turn that ends
+// without a completion exit re-sends the assignment, and the idle that finds the
+// bound spent fails the task instead of settling it `done`. The bound is the
+// workspace's (`config.mjs`, two by default) and the count lives on the record
+// `onAssign` wrote for the task, which is why a task can be reminded twice and
+// failed on the third idle without the tool ever being called.
+test("only settled idles spend ladder rungs, ordinary turns reset them, and the bound fails the task", async () => {
+  const { agent, host, surface } = await startAgent();
+  assert.equal(agent.idleReminders, DEFAULT_IDLE_REMINDERS, "the bound is the workspace's, two by default");
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+  // The assignment carries an image, so the reminder has an attachment path to
+  // name and a part it must not hand over twice.
+  const bytes = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+  const assignment = structuredClone(assignArgs());
+  assignment.envelope.body = {
+    text: "build it",
+    image: { data_base64: bytes.toString("base64"), mime: "image/png", name: "shot.png" },
+  };
+  host.notify("assign", assignment);
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+  assert.equal(surface.calls.wakeUser[0].parts.length, 1, "the injection carries the image");
+
+  // The first turn belongs to the session itself. Its settled idle spends rung
+  // one. The turn that reminder wakes does not reset the episode, so its own
+  // settled idle spends rung two rather than starting over.
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
+  const first = await waitFor(() =>
+    surface.calls.wakeUser.length === 2 ? surface.calls.wakeUser : null,
+  );
+  const firstReminder = first.at(-1);
+  assert.match(firstReminder.text, /reminder 1 of 2/);
+  assert.match(firstReminder.text, /build it/, "the reminder carries the task text");
+  assert.match(
+    firstReminder.text,
+    /\[onlyne\] task 11111111-1111-4111-8111-111111111111 from role:planner \(kind task\)/,
+    "and the identity and source the injection named",
+  );
+  assert.match(firstReminder.text, /\[onlyne\] attachment saved to: .*shot\.png/, "the path travels as text");
+  assert.deepEqual(firstReminder.parts, [], "and the image itself is not handed over twice");
+  assert.doesNotMatch(firstReminder.text, /Read the incoming task/, "the role prose is already in the context");
+
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
+  const secondRung = await waitFor(() =>
+    surface.calls.wakeUser.length === 3 ? surface.calls.wakeUser : null,
+  );
+  assert.match(secondRung.at(-1).text, /reminder 2 of 2/, "the reminder-woken turn keeps the episode's count");
   assert.deepEqual(host.of("report").filter((report) => report.kind === "complete"), []);
 
-  idle = true;
+  // The next turn is the one the second reminder wakes, so it does not reset
+  // the episode. Let that turn end without a settle, then start a turn of the
+  // session's own: that ordinary turn begins a fresh episode.
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
+  const reset = await waitFor(() =>
+    surface.calls.wakeUser.length === 4 ? surface.calls.wakeUser : null,
+  );
+  assert.match(reset.at(-1).text, /reminder 1 of 2/, "an ordinary turn clears the episode's rung count");
+
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
+  const secondFresh = await waitFor(() =>
+    surface.calls.wakeUser.length === 5 ? surface.calls.wakeUser : null,
+  );
+  assert.match(secondFresh.at(-1).text, /reminder 2 of 2/);
+
+  // The third idle in the fresh episode spends the bound, so the open task
+  // fails and the session leaves — the tool was never called.
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
   const complete = await waitFor(() => host.of("report").find((report) => report.kind === "complete"));
-  assert.equal(complete.data.head, "still working");
+  assert.deepEqual(complete.data, {
+    task_id: TASK_ID,
+    outcome: "failed",
+    head: "no completion after 2 idle reminders",
+  });
+  assert.deepEqual(surface.calls.exits, ["failed"], "the ladder's failure leaves the session");
+  assert.equal(surface.calls.wakeUser.length, 5, "the bound is spent: no third reminder");
+
+  // A turn that hands the outcome over is never reminded: the tool call is the
+  // exit the ladder exists to get.
+  const completed = await startAgent();
+  completed.agent.start();
+  await waitFor(() => completed.host.of("report").length >= 1);
+  completed.host.notify("assign", assignArgs());
+  await waitFor(() => (completed.surface.calls.wakeUser.length === 1 ? true : null));
+  completed.agent.onTurnStart();
+  completed.agent.onTurnEnd();
+  await completed.agent.completeFromTool({ outcome: "done", text: "built it" });
+  completed.agent.onSettled();
+  await new Promise((resolve) => setTimeout(resolve, 60));
+  assert.equal(completed.surface.calls.wakeUser.length, 1, "the completion is the exit: no reminder follows it");
+  assert.deepEqual(completed.surface.calls.exits, ["done"]);
 });
 
 test("an assigned task that never ran is not completed", async () => {
@@ -660,9 +888,9 @@ test("an explicit tool outcome wins and a second completion is refused", async (
 });
 
 // The completion body is what the tool call handed over. The sentence a turn
-// ends on is only the fallback for a task whose argument carries nothing, and
-// the auto rule reports exactly that fallback field — so an explicit argument
-// can never be displaced, in either call path.
+// ends on is only the fallback for a call whose argument carries nothing, and a
+// call that carries a `text` reports it byte for byte — so the argument can
+// never be displaced, before or after the call.
 test("an explicit tool argument is the head over the last assistant text", async () => {
   const { agent, host, surface } = await startAgent();
   agent.start();
@@ -740,12 +968,7 @@ test("the exit waits for the client's acknowledgement of the completion report",
   assert.deepEqual(surface.calls.exits, ["done"]);
 });
 
-// A session that only ever reported `running` and then completed leaves the
-// ledger saying `running` forever: the client settles the row from the
-// completion report and hears nothing more. One final observation, sent after
-// the completion is acknowledged and before the process leaves, is what makes
-// an exited session read idle.
-test("a completion after a running beat publishes the settled observation before the exit", async () => {
+test("the completion report is the last frame the host receives before the exit", async () => {
   const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
@@ -759,23 +982,14 @@ test("a completion after a running beat publishes the settled observation before
 
   await agent.complete(TASK_ID, "done", "OK");
   const reports = host.of("report").filter((report) => report.kind !== "ready");
-  const kinds = reports.map((report) => report.kind);
-  assert.deepEqual(
-    kinds.slice(-2),
-    ["complete", "heartbeat"],
-    "the settled observation follows the completion: " + JSON.stringify(kinds),
-  );
-  const settled = reports.at(-1).data.observed;
-  assert.equal(settled.agent, "idle");
-  assert.equal(settled.outcome, "done");
-  assert.equal(settled.delivery, "accepted");
-  assert.equal(settled.recovery, "draining");
-  assert.equal(settled.public, "exited");
+  assert.equal(reports.at(-1).kind, "complete", "a running beat is not followed by a settled observation");
   assert.deepEqual(surface.calls.exits, ["done"]);
 });
 
-test("a session whose last beat was idle publishes no extra observation", async () => {
-  const { agent, host, surface } = await startAgent();
+test("a reconnect beat re-derives the phase from the surface", async () => {
+  let waiting = true;
+  const surface = fakeSurface({ waiting: () => waiting });
+  const { agent, host } = await startAgent({ surface });
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
   host.notify("assign", assignArgs());
@@ -783,45 +997,21 @@ test("a session whose last beat was idle publishes no extra observation", async
   agent.onTurnStart();
   agent.onTurnEnd();
   await waitFor(() => host.of("report").find((report) => report.data?.observed?.agent === "idle"));
-  agent.noteAssistantText("OK");
-  const before = host.of("report").filter((report) => report.kind === "heartbeat").length;
-
-  await agent.complete(TASK_ID, "done", "OK");
-  assert.equal(
-    host.of("report").filter((report) => report.kind === "heartbeat").length,
-    before,
-    "an already-idle session needs no second idle observation",
-  );
-  assert.deepEqual(surface.calls.exits, ["done"]);
-});
-
-test("a queued completion and its settled observation flush in order after reconnect", async () => {
-  const { agent, host, surface } = await startAgent();
-  agent.start();
-  await waitFor(() => host.of("report").length >= 1);
-  host.notify("assign", assignArgs());
-  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
-  agent.onTurnStart();
-  agent.onTurnEnd();
-  agent.noteAssistantText("done offline");
 
+  const beforeReconnect = host.frames.length;
+  waiting = false;
   for (const socket of [...host.sockets]) socket.destroy();
   await waitFor(() => (agent.status().connected === false ? true : null));
-  await agent.completeFromTool({ outcome: "done" });
-  assert.deepEqual(surface.calls.exits, [], "nothing exits before the report lands");
-
-  await waitFor(() => (host.connections >= 2 ? true : null));
-  await waitFor(() => (surface.calls.exits.length === 1 ? true : null));
-  const reports = host.of("report").filter((report) => report.kind !== "ready");
-  assert.deepEqual(
-    reports.slice(-2).map((report) => [report.kind, report.data.observed?.agent ?? null]),
-    [
-      ["complete", null],
-      ["heartbeat", "idle"],
-    ],
-    "the settled observation rides after the flushed completion: " + JSON.stringify(reports),
+  const beat = await waitFor(() => host.frames
+    .slice(beforeReconnect)
+    .map((entry) => entry.frame)
+    .find((frame) => frame.op === "report" && frame.args?.kind === "heartbeat"));
+  assert.equal(beat.args.data.observed.agent, "running", "the reconnect asks the surface again");
+  assert.equal(
+    heartbeats(host).at(-1).agent,
+    "running",
+    "the old idle beat does not survive the reconnect",
   );
-  assert.equal(reports.at(-1).data.observed.outcome, "done");
 });
 
 test("an inbound image is written under the workspace and handed to pi", async () => {
@@ -856,7 +1046,7 @@ test("a probe is answered with a heartbeat for the live task", async () => {
   const heartbeat = await waitFor(() =>
     host.of("report").find((report) => report.kind === "heartbeat" && report.data.task_id === TASK_ID),
   );
-  assert.equal(heartbeat.data.observed.agent, "running");
+  assert.equal(heartbeat.data.observed.agent, "idle", "the probe re-derives a waiting session");
   assert.ok(heartbeat.data.seq > SEQ_BASE, "each heartbeat advances the plugin's own sequence");
 });
 
@@ -1128,6 +1318,90 @@ test("the handoff ledger belongs to the session, not to one task", async () => {
   assert.equal(completions(host).length, 1);
 });
 
+// ------------------------------------------------------------ the handoff tool
+
+test("a handoff names the task this session holds and hands the answer back", async () => {
+  const { agent, host } = await startAgent();
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  // The task the host handed this session is the family's parent, so that id is
+  // the one the request names: the spawn id stays behind it.
+  const args = structuredClone(assignArgs());
+  args.task_id = ASSIGNED_TASK_ID;
+  args.envelope.causality.task = ASSIGNED_TASK_ID;
+  host.notify("assign", args);
+  await waitFor(() => (host.of("assign_ack").length === 1 ? true : null));
+
+  const result = await agent.handoffFromTool({ to: "builder", text: "take it from here" });
+  assert.deepEqual(host.of("handoff"), [
+    { task_id: ASSIGNED_TASK_ID, to: "builder", text: "take it from here", image: null },
+  ]);
+  assert.deepEqual(result, {
+    taskId: CHILD_TASK_ID,
+    hop: HANDOFF_ANSWER.hop,
+    queued: true,
+    opId: `o-${CHILD_TASK_ID}`,
+    to: "builder",
+  });
+});
+
+test("a handoff reads the image the model named and types it from its path", async () => {
+  const { agent, host, dir } = await startAgent();
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  const bytes = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+  const shot = join(dir, "shot.png");
+  writeFileSync(shot, bytes);
+  await agent.handoffFromTool({ to: "builder", text: "the shot", imagePath: shot });
+  assert.deepEqual(host.of("handoff")[0].image, {
+    data_base64: bytes.toString("base64"),
+    mime: "image/png",
+    name: "shot.png",
+  });
+
+  // A path this plugin cannot type is refused here, so no half-typed handoff
+  // reaches the wire.
+  const bad = join(dir, "shot.bmp");
+  writeFileSync(bad, bytes);
+  await assert.rejects(
+    () => agent.handoffFromTool({ to: "builder", text: "the shot", imagePath: bad }),
+    /unsupported image type/,
+  );
+  assert.equal(host.of("handoff").length, 1);
+});
+
+test("a send types its image from the path too", async () => {
+  const { agent, host, dir } = await startAgent();
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  const path = join(dir, "diagram.webp");
+  writeFileSync(path, Buffer.from([1, 2, 3]));
+  await agent.sendFromTool({ to: "writer", text: "the diagram", imagePath: path });
+
+  assert.deepEqual(host.of("send")[0].body.image, {
+    data_base64: "AQID",
+    mime: "image/webp",
+    name: "diagram.webp",
+  });
+});
+
+test("a handoff the client refuses throws the client's own reason", async () => {
+  const { agent, host } = await startAgent({
+    handoffError: { code: "no_family", message: "no task family for that id" },
+  });
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  await assert.rejects(
+    () => agent.handoffFromTool({ to: "builder", text: "take it" }),
+    /no_family: no task family for that id/,
+  );
+  assert.equal(host.of("handoff").length, 1, "a refusal is not retried");
+});
+
 // ---------------------------------------------------------------- the panel
 
 test("a pi with the widget gets the panel and keeps a quiet scrollback", async () => {