pi-onlyne 1.1.2 → 1.2.0

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 })
@@ -202,11 +249,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({
@@ -298,7 +346,8 @@ test("every heartbeat names the Orca pane this process was spawned in", async ()
     });
     // The binding rides beside the state dimensions instead of replacing them.
     assert.equal(observed.agent, "running");
-    assert.equal(observed.public, "working");
+    assert.equal(observed.resource, "attached");
+    assert.deepEqual(Object.keys(observed), [...OBSERVED_KEYS, "host"]);
     assert.equal(observed.version.generation, 1);
   });
 });
@@ -535,7 +584,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("turn hooks report running then idle, and the settle after them re-sends the assignment", async () => {
   const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
@@ -545,31 +594,34 @@ 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");
 });
 
 // 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,7 +640,7 @@ 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 () => {
+test("a busy pi holds the settle decision until it is idle", async () => {
   let idle = false;
   const surface = fakeSurface({ idle: () => idle });
   const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
@@ -597,14 +649,95 @@ test("a busy pi holds the completion until it is idle", async () => {
   host.notify("assign", assignArgs());
   await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
   agent.onTurnEnd();
-  agent.noteAssistantText("still working");
   agent.onSettled();
   await new Promise((resolve) => setTimeout(resolve, 80));
-  assert.deepEqual(host.of("report").filter((report) => report.kind === "complete"), []);
+  assert.equal(surface.calls.wakeUser.length, 1, "a busy pi is not reminded");
 
   idle = 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");
+});
+
+// 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("an idle without a completion is reminded, the idle past the bound fails the task, and a completed turn is not reminded", 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");
+
+  // Two idles, two reminders: the assignment comes back whole — header, task
+  // text and all — and the model is told why it is seeing it again.
+  for (const rung of [1, 2]) {
+    agent.onTurnStart();
+    agent.onTurnEnd();
+    agent.onSettled();
+    const sent = await waitFor(() =>
+      surface.calls.wakeUser.length === 1 + rung ? surface.calls.wakeUser : null,
+    );
+    const reminder = sent.at(-1);
+    assert.match(reminder.text, new RegExp(`reminder ${rung} of 2`));
+    assert.match(reminder.text, /build it/, "the reminder carries the task text");
+    assert.match(
+      reminder.text,
+      /\[onlyne\] task 11111111-1111-4111-8111-111111111111 from role:planner \(kind task\)/,
+      "and the identity and source the injection named",
+    );
+    assert.match(reminder.text, /\[onlyne\] attachment saved to: .*shot\.png/, "the path travels as text");
+    assert.deepEqual(reminder.parts, [], "and the image itself is not handed over twice");
+    assert.doesNotMatch(reminder.text, /Read the incoming task/, "the role prose is already in the context");
+    assert.deepEqual(
+      host.of("report").filter((report) => report.kind === "complete"),
+      [],
+      `rung ${rung}: an open task is not settled while it has a rung left`,
+    );
+  }
+
+  // The third idle: the bound is spent, so the open task fails and the session
+  // leaves — the tool was never called, and no completion was ever reported.
+  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, 3, "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 second = await startAgent();
+  second.agent.start();
+  await waitFor(() => second.host.of("report").length >= 1);
+  second.host.notify("assign", assignArgs());
+  await waitFor(() => (second.surface.calls.wakeUser.length === 1 ? true : null));
+  second.agent.onTurnStart();
+  second.agent.onTurnEnd();
+  await second.agent.completeFromTool({ outcome: "done", text: "built it" });
+  second.agent.onSettled();
+  await new Promise((resolve) => setTimeout(resolve, 60));
+  assert.equal(second.surface.calls.wakeUser.length, 1, "the completion is the exit: no reminder follows it");
+  assert.deepEqual(second.surface.calls.exits, ["done"]);
 });
 
 test("an assigned task that never ran is not completed", async () => {
@@ -660,9 +793,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();
@@ -767,10 +900,7 @@ test("a completion after a running beat publishes the settled observation before
   );
   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.deepEqual(dimensionKeys(settled), OBSERVED_KEYS, "the last observation states the agent and nothing else");
   assert.deepEqual(surface.calls.exits, ["done"]);
 });
 
@@ -821,7 +951,7 @@ test("a queued completion and its settled observation flush in order after recon
     ],
     "the settled observation rides after the flushed completion: " + JSON.stringify(reports),
   );
-  assert.equal(reports.at(-1).data.observed.outcome, "done");
+  assert.deepEqual(dimensionKeys(reports.at(-1).data.observed), OBSERVED_KEYS, "the flushed tail states the agent and nothing else");
 });
 
 test("an inbound image is written under the workspace and handed to pi", async () => {
@@ -1128,6 +1258,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 () => {

package/src/config.mjs

@@ -6,7 +6,8 @@
 // generate-time template advice), so the only consumer is this extension. A
 // malformed or missing file falls back to the defaults and reports a warning
 // instead of disabling the session: the extension's own `enabled` key is the one
-// deliberate off switch.
+// deliberate off switch. A key whose value is unusable — the idle bound below,
+// say — keeps the one default it names and leaves the rest of the file alone.
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -14,15 +15,26 @@ import { join } from "node:path";
 /** Where the switch file lives, relative to the pi working directory. */
 export const CONFIG_RELATIVE_PATH = join(".pi", "onlyne.json");
 
-/** Defaults: on, and connecting as soon as a session starts. */
-export const DEFAULT_CONFIG = Object.freeze({ enabled: true, autoStart: true });
+/**
+ * How many idle reminders one task may collect before the ladder fails it
+ * (`agent.mjs` `settleNow`): two, so the third idle without a completion is the
+ * failure.
+ */
+export const DEFAULT_IDLE_REMINDERS = 2;
+
+/** Defaults: on, connecting as soon as a session starts, and the idle bound. */
+export const DEFAULT_CONFIG = Object.freeze({
+  enabled: true,
+  autoStart: true,
+  idleReminders: DEFAULT_IDLE_REMINDERS,
+});
 
 /**
  * Read `.pi/onlyne.json`.
  *
  * @param {string} cwd
  * @param {{ readFile?: (path: string) => string }} [options]
- * @returns {{ enabled: boolean, autoStart: boolean, path: string, warning: string | null, present: boolean }}
+ * @returns {{ enabled: boolean, autoStart: boolean, idleReminders: number, path: string, warning: string | null, present: boolean }}
  */
 export function loadConfig(cwd, options = {}) {
   const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
@@ -48,11 +60,21 @@ export function loadConfig(cwd, options = {}) {
     return { ...DEFAULT_CONFIG, path, warning: `${path} must hold a JSON object; using defaults`, present: true };
   }
   const watch = parsed.watch && typeof parsed.watch === "object" ? parsed.watch : {};
+  // The bound is a count, so only a non-negative integer is a value: a string,
+  // a fraction or a negative would either count nothing or count forever.
+  // Zero is a value — it says the first idle without a completion is already
+  // the failure — and it is the operator's call to make.
+  const idleReminders = parsed.idleReminders;
+  const usable = Number.isInteger(idleReminders) && idleReminders >= 0;
   return {
     enabled: typeof parsed.enabled === "boolean" ? parsed.enabled : DEFAULT_CONFIG.enabled,
     autoStart: typeof watch.autoStart === "boolean" ? watch.autoStart : DEFAULT_CONFIG.autoStart,
+    idleReminders: usable ? idleReminders : DEFAULT_CONFIG.idleReminders,
     path,
-    warning: null,
+    warning:
+      idleReminders !== undefined && !usable
+        ? `${path} idleReminders must be a non-negative integer; using ${DEFAULT_CONFIG.idleReminders}`
+        : null,
     present: true,
   };
 }

package/src/index.ts

@@ -9,9 +9,9 @@
 //
 //   session_start    -> read env + .pi/onlyne.json, connect, register tools
 //   turn_start       -> heartbeat{running}
-//   turn_end         -> heartbeat{idle}
+//   turn_end         -> heartbeat{idle}; the settle window opens
 //   message_end      -> keep the last assistant text; a failed turn is `failed`
-//   agent_settled    -> completion exit: done|failed
+//   agent_settled    -> settle decision: the idle ladder, or `failed` at once
 //   session_shutdown -> detach{reason}
 
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -165,10 +165,11 @@ export default function onlyne(pi: ExtensionAPI) {
         name: "onlyne_complete",
         label: "Onlyne complete",
         description:
-          "End this onlyne task with an explicit outcome. Call it once, when the assigned work is finished (outcome=done), provably impossible (outcome=failed), or withdrawn (outcome=cancelled). Without this call the session still completes on its own: done, or failed when the turn errored. In a workspace whose relay policy (relay.toml) names the handoffs this session owes, the call is refused until each one has gone out.",
+          "End this onlyne task with an explicit outcome. Call it once, when the assigned work is finished (outcome=done), provably impossible (outcome=failed), or withdrawn (outcome=cancelled). This call is the only way the task reaches done: a turn that ends without it leaves the task open, the session re-sends you the assignment up to the workspace's idle-reminder bound, and the idle that finds the bound spent fails the task and ends the session. In a workspace whose relay policy (relay.toml) names the handoffs this session owes, the call is refused until each one has gone out.",
         promptSnippet: "Finish the current onlyne task with an outcome and a one-line summary",
         promptGuidelines: [
           "Use onlyne_complete at the end of an onlyne task, naming the outcome and the result in one line; the summary becomes the ledger head.",
+          "If the assignment is sent to you again while it is still open, the previous turn ended without a completion: finish the work and call onlyne_complete.",
           "If onlyne_complete answers 'relay guard', the session still owes a downstream handoff: make it with onlyne_send and call onlyne_complete again. Close the session anyway only when the handoff is genuinely impossible, with force: true and a reason.",
         ],
         parameters: Type.Object({
@@ -196,6 +197,36 @@ export default function onlyne(pi: ExtensionAPI) {
     } catch (error) {
       log(`registerTool(onlyne_complete) refused: ${error instanceof Error ? error.message : String(error)}`);
     }
+    try {
+      pi.registerTool(defineTool({
+        name: "onlyne_handoff",
+        label: "Onlyne handoff",
+        description:
+          "Hand this session's task on to the next hop of its family. The host mints one child task for the named role, names this task as the child's parent_task, raises the hop by one, and lets the family's budget, labels, origin and deadline ride along, so the child continues the run this session serves. Use it for the next slot of a ring or a chain; onlyne_send{kind:\"task\"} starts a new family at hop 0, and onlyne_send{kind:\"note\"} is free text.",
+        promptSnippet: "Hand this task on to the next role of its family",
+        promptGuidelines: [
+          "Use onlyne_handoff when the work goes on to the next role of the run this session serves: the child the host mints carries the same family id, hop budget, labels, origin and deadline, and this task becomes its parent_task.",
+          "Use onlyne_send with kind=\"task\" when a role should get work of its own: that child is hop 0 of a family this session starts.",
+          "Use onlyne_send with kind=\"note\" for free text to a role, which carries no task and no hop.",
+        ],
+        parameters: Type.Object({
+          to: Type.String({ description: "target role name, e.g. builder" }),
+          text: Type.String({ description: "handoff text for the next role of the run" }),
+          image: Type.Optional(Type.String({ description: "absolute path to a png/jpeg/gif/webp image to attach" })),
+        }),
+        async execute(_toolCallId, params) {
+          if (!agent) throw new Error("onlyne: session is not connected");
+          const result = await agent.handoffFromTool({
+            to: params.to,
+            text: params.text,
+            imagePath: params.image ?? null,
+          });
+          return textResult(`handed on to ${result.to} as ${result.taskId} at hop ${result.hop}`, result);
+        },
+      }));
+    } catch (error) {
+      log(`registerTool(onlyne_handoff) refused: ${error instanceof Error ? error.message : String(error)}`);
+    }
     try {
       pi.registerCommand("onlyne", {
         description: "Onlyne session status: connection, task, reports",
@@ -256,6 +287,7 @@ export default function onlyne(pi: ExtensionAPI) {
       taskId: identity.taskId,
       surface,
       relay,
+      idleReminders: config.idleReminders,
       log,
     });
     log(`session ${identity.sessionId} role=${identity.role} socket=${socketPath}`);