pi-onlyne 1.2.2 → 2.0.0

package/src/background-subagents.mjs

@@ -0,0 +1,192 @@
+// The other question a background extension makes necessary: is work this
+// session dispatched through the `Agent` tool still running where the agent loop
+// cannot see it?
+//
+// The subagents extension is not one of the `pi-background-tasks` family, and
+// its `Agent` call is not one of those tools. A field test on one session showed
+// all five `Agent` calls issued in a single assistant message, each returning at
+// once with `Agent started in background` and an output file under
+// `/tmp/pi-subagents-<uid>/` — so the tool hands back a handle and the child
+// carries on, and no `tool_execution_start` / `tool_execution_end` pair brackets
+// it. The tool is not pi's own either: the string does not appear in pi's dist,
+// and pi's extension API exposes no subagent or background-task query at all,
+// only `getActiveTools` / `getAllTools` / `setActiveTools`. So there is no event
+// to subscribe to and no frame to ask for; what the extension leaves behind is
+// an on-disk registry at `~/.pi/subagents/missions/<uuid>.json`, and this probe
+// reads that.
+//
+// Every failure mode is inert, exactly as in `background-work.mjs`: no
+// directory, an unreadable file, a missing field, malformed JSON, or a read that
+// throws all read as "no subagent work known" and leave the plugin's own
+// judgement untouched. A probe that throws is worse than one that answers
+// nothing.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Mission statuses that mean the work is over.
+ *
+ * The live spelling was never observed. The machine this was measured on had
+ * four missions, all of them terminal (`completed`, `failed`, `cancelled` for
+ * missions; `completed`, `failed` for `workflowChildren`; `stopped`, `complete`,
+ * `failed` for `runs[].status`), so the running value is unenumerated. The safe
+ * direction is therefore "anything not on this list is live": guessing the other
+ * way would read a genuinely running session as idle, which is the exact bug
+ * this probe exists to fix. The cost of being wrong this way is a session that
+ * waits a little longer than it had to — a new terminal spelling delays the
+ * phase, it does not lose work.
+ */
+export const TERMINAL_MISSION_STATUSES = Object.freeze([
+  "cancelled",
+  "complete",
+  "completed",
+  "failed",
+  "stopped",
+]);
+
+/**
+ * How many mission files one call will open. The registry is one JSON object per
+ * mission and grows without bound over a machine's life, so an uncapped scan
+ * would make the probe cost a function of history while the caller only ever
+ * cares about the present. The cap trades that for a bounded read: a session
+ * whose live work sits past the cap is reported as not running, the same fail-safe
+ * direction as every other answer here, and the newest files are read first
+ * because those are the ones just dispatched.
+ */
+export const DEFAULT_MAX_MISSION_FILES = 200;
+
+/**
+ * How many bytes one mission file may be before it is skipped. A mission
+ * transcript, not a mission, is the large artefact; anything past this is not
+ * the status record this probe reads.
+ */
+export const DEFAULT_MAX_MISSION_BYTES = 256 * 1024;
+
+/** @param {unknown} status */
+export function isTerminalMissionStatus(status) {
+  return typeof status === "string" && TERMINAL_MISSION_STATUSES.includes(status);
+}
+
+/**
+ * @param {unknown} mission
+ * @param {string | null} sessionId this session's id, or `null` when unknown
+ */
+export function isLiveMission(mission, sessionId = null) {
+  if (!mission || typeof mission !== "object") return false;
+  // A mission with no status is not live: absence of evidence is absence of
+  // work, the same direction `background-work.mjs` fails safe in.
+  if (typeof mission.status !== "string" || !mission.status) return false;
+  if (isTerminalMissionStatus(mission.status)) return false;
+  const owner = mission.ownerSessionId;
+  if (typeof sessionId === "string" && sessionId) {
+    // Scope by owner so the answer is "is *this* session's work still running",
+    // not "is anything on this machine running".
+    return typeof owner === "string" && owner === sessionId;
+  }
+  // The caller cannot name its own session, so a mission naming no session still
+  // counts: watching a silent subset would be worse than watching too much.
+  return true;
+}
+
+/** Newest first, so a capped scan spends its budget on the missions just dispatched. */
+function byNewestFirst(left, right) {
+  const a = right.mtimeMs ?? 0;
+  const b = left.mtimeMs ?? 0;
+  if (a !== b) return a - b;
+  return String(right.name).localeCompare(String(left.name));
+}
+
+/** @returns {string[]} the `.json` mission files, newest first and already capped. */
+function missionFiles(directory, maxFiles) {
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => {
+      let mtimeMs = 0;
+      try {
+        mtimeMs = fs.statSync(path.join(directory, entry.name)).mtimeMs;
+      } catch {
+        /* an entry that will not stat sorts as oldest and may be cut by the cap */
+      }
+      return { name: entry.name, mtimeMs };
+    })
+    .sort(byNewestFirst)
+    .slice(0, maxFiles)
+    .map((entry) => path.join(directory, entry.name));
+}
+
+function readMission(file, maxBytes) {
+  if (fs.statSync(file).size > maxBytes) return null;
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+/**
+ * One live-mission question, asked of the on-disk registry and answered by
+ * whatever the subagents extension left there. Inert by construction: a throw
+ * anywhere inside resolves to `false`.
+ *
+ * @param {{
+ *   homeDir?: string,
+ *   getSessionId?: () => string | null,
+ *   log?: (line: string) => void,
+ *   maxFiles?: number,
+ *   maxBytes?: number,
+ * }} options
+ */
+export function createSubagentProbe({
+  homeDir = os.homedir(),
+  getSessionId = null,
+  log = () => {},
+  maxFiles = DEFAULT_MAX_MISSION_FILES,
+  maxBytes = DEFAULT_MAX_MISSION_BYTES,
+} = {}) {
+  const warned = new Set();
+
+  const warnOnce = (reason) => {
+    if (warned.has(reason)) return;
+    warned.add(reason);
+    log(`subagent work: ${reason}`);
+  };
+
+  const sessionId = () => {
+    if (typeof getSessionId !== "function") return null;
+    return getSessionId() ?? null;
+  };
+
+  /**
+   * @returns {Promise<boolean>}
+   */
+  function running() {
+    try {
+      const directory = path.join(homeDir, ".pi", "subagents", "missions");
+      if (!fs.existsSync(directory)) {
+        // No registry at all means the extension has never run here; that is a
+        // steady state rather than a fault, so it is recorded once.
+        warnOnce("no subagent registry in this home");
+        return false;
+      }
+      for (const file of missionFiles(directory, maxFiles)) {
+        let mission = null;
+        try {
+          mission = readMission(file, maxBytes);
+        } catch (error) {
+          warnOnce(`mission unreadable: ${error.message}`);
+          continue;
+        }
+        if (mission === null) {
+          warnOnce("mission record too large to be a status record");
+          continue;
+        }
+        if (isLiveMission(mission, sessionId())) return true;
+      }
+      return false;
+    } catch (error) {
+      warnOnce(`registry unreadable: ${error.message}`);
+      return false;
+    }
+  }
+
+  return { running };
+}

package/src/background-subagents.test.mjs

@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+
+import { createSubagentProbe } from "./background-subagents.mjs";
+
+const SESSION = "s-ours";
+const OTHER = "s-theirs";
+
+/** A throwaway home with a missions registry, as the extension leaves it. */
+function homeWith(files) {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "onlyne-subagents-"));
+  const missions = path.join(homeDir, ".pi", "subagents", "missions");
+  fs.mkdirSync(missions, { recursive: true });
+  for (const [name, body] of Object.entries(files)) {
+    fs.writeFileSync(path.join(missions, name), typeof body === "string" ? body : JSON.stringify(body));
+  }
+  return { homeDir, missions };
+}
+
+function probeFor(homeDir, sessionId = SESSION) {
+  const logs = [];
+  const probe = createSubagentProbe({
+    homeDir,
+    getSessionId: () => sessionId,
+    log: (line) => logs.push(line),
+  });
+  return { logs, probe };
+}
+
+test("a registry of terminal missions reads as not running", async () => {
+  const { homeDir } = homeWith({
+    "a.json": { id: "a", status: "completed", ownerSessionId: SESSION },
+    "b.json": { id: "b", status: "failed", ownerSessionId: SESSION },
+    "c.json": { id: "c", status: "cancelled", ownerSessionId: SESSION },
+  });
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+});
+
+test("a mission whose status is not terminal reads as running", async () => {
+  // The live spelling was never observed, so any unrecognised value is treated as
+  // live; that is the safe direction, and this is what it looks like in a test.
+  const { homeDir } = homeWith({
+    "a.json": { id: "a", status: "running", ownerSessionId: SESSION },
+    "b.json": { id: "b", status: "something-new", ownerSessionId: SESSION },
+  });
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), true);
+});
+
+test("a mission owned by this session reads as running and another session's does not", async () => {
+  const theirs = homeWith({ "a.json": { id: "a", status: "running", ownerSessionId: OTHER } });
+  const { probe: other } = probeFor(theirs.homeDir, SESSION);
+  assert.equal(await other.running(), false, "another session's live mission is not this session's work");
+
+  const ours = homeWith({ "a.json": { id: "a", status: "running", ownerSessionId: SESSION } });
+  const { probe: mine } = probeFor(ours.homeDir, SESSION);
+  assert.equal(await mine.running(), true);
+});
+
+test("a caller that cannot name its own session counts a mission naming none", async () => {
+  const { homeDir } = homeWith({ "a.json": { id: "a", status: "running" } });
+  const { probe } = probeFor(homeDir, null);
+
+  assert.equal(await probe.running(), true, "watching a silent subset is worse than watching too much");
+});
+
+test("a missing registry reads as not running and does not throw", async () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "onlyne-subagents-empty-"));
+  const { logs, probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+  assert.equal(logs.length, 1, "the missing registry is said once");
+  assert.equal(await probe.running(), false);
+  assert.equal(logs.length, 1, "and not repeated on the next call");
+});
+
+test("a missions path that is a file rather than a directory reads as not running", async () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "onlyne-subagents-file-"));
+  const missions = path.join(homeDir, ".pi", "subagents");
+  fs.mkdirSync(missions, { recursive: true });
+  fs.writeFileSync(path.join(missions, "missions"), "not a directory");
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+});
+
+test("an unreadable mission file reads as not running and does not throw", async () => {
+  const { homeDir, missions } = homeWith({ "a.json": { id: "a", status: "completed" } });
+  fs.writeFileSync(path.join(missions, "b.json"), "{ not json");
+  fs.mkdirSync(path.join(missions, "c.json")); // a directory where a file is expected
+  fs.chmodSync(missions, 0o000);
+  const { probe } = probeFor(homeDir);
+  try {
+    assert.equal(await probe.running(), false);
+  } finally {
+    fs.chmodSync(missions, 0o755);
+  }
+});
+
+test("a mission with no status reads as not running", async () => {
+  const { homeDir } = homeWith({
+    "a.json": { id: "a", ownerSessionId: SESSION },
+    "b.json": { id: "b", status: null, ownerSessionId: SESSION },
+    "c.json": { id: "c", status: 42, ownerSessionId: SESSION },
+  });
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+});
+
+test("malformed JSON in a live-looking registry still answers", async () => {
+  const { homeDir, missions } = homeWith({ "a.json": "<<<not json>>>" });
+  fs.writeFileSync(path.join(missions, "b.json"), JSON.stringify({ status: "running", ownerSessionId: SESSION }));
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), true, "one bad file does not hide a live mission");
+});
+
+test("a mission larger than the byte bound is skipped, and the rest of the registry still answers", async () => {
+  const { homeDir, missions } = homeWith({
+    "a.json": { id: "a", status: "completed", ownerSessionId: SESSION, summary: "x".repeat(4096) },
+  });
+  fs.writeFileSync(path.join(missions, "huge.json"), JSON.stringify({
+    status: "running",
+    ownerSessionId: SESSION,
+    transcript: "x".repeat(300 * 1024),
+  }));
+  const { logs, probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+  assert.equal(logs.some((line) => line.includes("too large")), true);
+});
+
+test("a capped read spends its budget on the newest missions", async () => {
+  // The cap is asserted by which file the probe read, so each case puts the live
+  // mission on one side of the cap and the terminal one on the other.
+  const registry = {
+    "old.json": { id: "old", status: "running", ownerSessionId: SESSION },
+    "new.json": { id: "new", status: "completed", ownerSessionId: SESSION },
+  };
+  const { homeDir, missions } = homeWith(registry);
+  const old = new Date(Date.now() - 60_000);
+  fs.utimesSync(path.join(missions, "old.json"), old, old);
+  const capped = createSubagentProbe({ homeDir, getSessionId: () => SESSION, maxFiles: 1 });
+
+  // Only the newer file is inside the cap, and it is terminal.
+  assert.equal(await capped.running(), false);
+
+  // The same cap, the same two files, with the newer one now live: the answer
+  // flips only because the newer file is the one that got read.
+  fs.writeFileSync(
+    path.join(missions, "new.json"),
+    JSON.stringify({ id: "new", status: "running", ownerSessionId: SESSION }),
+  );
+  assert.equal(await createSubagentProbe({
+    homeDir,
+    getSessionId: () => SESSION,
+    maxFiles: 1,
+  }).running(), true);
+});

package/src/config.mjs

@@ -6,8 +6,7 @@
 // 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. 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.
+// deliberate off switch.
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -15,18 +14,10 @@ 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");
 
-/**
- * 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. */
+/** Defaults: on, and connecting as soon as a session starts. */
 export const DEFAULT_CONFIG = Object.freeze({
   enabled: true,
   autoStart: true,
-  idleReminders: DEFAULT_IDLE_REMINDERS,
 });
 
 /**
@@ -34,7 +25,7 @@ export const DEFAULT_CONFIG = Object.freeze({
  *
  * @param {string} cwd
  * @param {{ readFile?: (path: string) => string }} [options]
- * @returns {{ enabled: boolean, autoStart: boolean, idleReminders: number, path: string, warning: string | null, present: boolean }}
+ * @returns {{ enabled: boolean, autoStart: boolean, path: string, warning: string | null, present: boolean }}
  */
 export function loadConfig(cwd, options = {}) {
   const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
@@ -60,21 +51,11 @@ 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:
-      idleReminders !== undefined && !usable
-        ? `${path} idleReminders must be a non-negative integer; using ${DEFAULT_CONFIG.idleReminders}`
-        : null,
+    warning: null,
     present: true,
   };
 }

package/src/index.ts

@@ -7,21 +7,26 @@
 // `crates/onlyne-client/src/dispatch.rs`); with any of the three missing this is
 // a plain pi session and the extension stays silent rather than failing.
 //
-//   session_start    -> read env + .pi/onlyne.json, connect, register tools
-//   turn_start       -> heartbeat{running}
-//   turn_end         -> one turn of a run ended; the phase is re-derived from pi
-//                       and the settle window opens
-//   message_end      -> keep the last assistant text; a failed turn is `failed`
-//   agent_settled    -> heartbeat{idle} when the session waits for input, then
-//                       the settle decision: the idle ladder, or `failed` at once
-//   session_shutdown -> detach{reason}
+//   session_start      -> read env + .pi/onlyne.json, connect, register tools
+//   before_agent_start -> the role prose becomes one section of the system
+//                         prompt the run is about to send (the instruction layer)
+//   turn_start         -> heartbeat{running}
+//   turn_end           -> one turn of a run ended; the phase is re-derived from pi
+//                         and the fallback window for a witnessed failure opens
+//   message_end        -> keep the last assistant text; a failed turn is `failed`
+//   agent_settled      -> heartbeat{idle} when the session waits for input, and the
+//                         report a failed turn owes is sent from here
+//   session_shutdown   -> detach{reason}
+//
+// Host frames are dispatched in `agent.mjs`, not here: `assign` and `nudge` are
+// injected as user messages, `probe` is answered with a heartbeat, and `recycle`
+// settles the task and stops the plugin.
 
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { OnlyneAgent } from "./agent.mjs";
 import { loadConfig, sessionIdentity } from "./config.mjs";
-import { loadRelay, relayEnabled } from "./relay.mjs";
 import { resolveSocketPath } from "./socket.mjs";
 import { createSurface } from "./pi-surface.mjs";
 
@@ -54,7 +59,6 @@ interface WelcomeLike {
 interface PiSurface {
   available: {
     wakeUser: boolean;
-    proseContext: boolean;
     customEntry: boolean;
     widget: boolean;
     status: boolean;
@@ -64,7 +68,8 @@ interface PiSurface {
     registerCommand: boolean;
   };
   wakeUser(text: string, parts?: ImagePartInput[]): boolean;
-  proseContext(text: string, welcome: WelcomeLike): boolean;
+  roleProse(text: string): boolean;
+  applyRoleProse(event: { systemPromptOptions?: { sections?: Record<string, string> } }): boolean;
   customEntry(customType: string, data: unknown): boolean;
   widget(lines: string[] | undefined): void;
   status(text: string): void;
@@ -141,10 +146,10 @@ export default function onlyne(pi: ExtensionAPI) {
         name: "onlyne_send",
         label: "Onlyne send",
         description:
-          "Send one message to another role in this onlyne cluster. kind=note (default) is free text; kind=task hands work to the role and creates a session for it.",
-        promptSnippet: "Send a note or a task to another onlyne role",
+          "Send one message to another role. kind=note (default) is free text; kind=task hands work to that role and opens a task for it.",
+        promptSnippet: "Send a note or a task to another role",
         promptGuidelines: [
-          "Use onlyne_send when a task needs another onlyne role's work; it submits the envelope to the cluster and returns once the router has queued it.",
+          "Use onlyne_send when something has to reach another role; the call returns once the message is queued.",
         ],
         parameters: Type.Object({
           to: Type.String({ description: "target role name, e.g. builder" }),
@@ -160,7 +165,9 @@ export default function onlyne(pi: ExtensionAPI) {
             kind: params.kind,
             imagePath: params.image ?? null,
           });
-          return textResult(`queued ${result.kind} to ${result.to}`, result);
+          // The recipient and nothing else: a tool result is model-visible, and
+          // there is no fact about this send the model needs beyond where it went.
+          return textResult(`sent to ${result.to}`, { to: result.to });
         },
       }));
     } catch (error) {
@@ -171,33 +178,34 @@ 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). 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",
+          "End the current task with an explicit outcome: done (the work is finished), failed (it is provably impossible), cancelled (it was withdrawn), or blocked (something outside this session stops it). summary is the one-line result and details is the full one; files names the paths the result rests on. If the workspace requires a handoff before the task may end, the call is refused until that handoff has gone out.",
+        promptSnippet: "Finish the current 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.",
+          "Use onlyne_complete at the end of the current task, naming the outcome and the result in one line.",
         ],
         parameters: Type.Object({
-          outcome: Type.Optional(Type.String({ description: '"done" (default), "failed", or "cancelled"' })),
-          text: Type.Optional(Type.String({ description: "one-line result summary" })),
-          force: Type.Optional(Type.Boolean({ description: "waive the relay guard; requires a non-empty reason" })),
-          reason: Type.Optional(Type.String({ description: "why the relay guard is waived; stamped into the ledger head after `relay-guard-forced: `" })),
+          outcome: Type.String({ description: '"done", "failed", "cancelled", or "blocked"' }),
+          summary: Type.String({ description: "one-line result summary" }),
+          details: Type.Optional(Type.String({ description: "the full result, delivered as it stands" })),
+          files: Type.Optional(Type.Array(Type.String(), { description: "absolute paths of the files the result names" })),
         }),
         async execute(_toolCallId, params) {
           if (!agent) throw new Error("onlyne: session is not connected");
           // The exit is not a tool-result flag: pi 0.85.1 has no tool-result
           // `terminate` handling. `agent.complete` asks the surface to shut the
-          // process down once the client has acknowledged the report. A relay
-          // refusal throws out of here as a tool error, which leaves the session
-          // mounted for the handoff that clears it.
+          // process down once the client has acknowledged the report. A refusal
+          // from the client throws out of here as a tool error, so the model
+          // reads the host's own sentence.
           const result = await agent.completeFromTool({
             outcome: params.outcome,
-            text: params.text,
-            force: params.force,
-            reason: params.reason,
+            summary: params.summary,
+            details: params.details,
+            files: params.files,
           });
-          return textResult(`onlyne task ${result.taskId} -> ${result.outcome}`, result);
+          // The outcome and nothing else: the ledger's head stays a display
+          // field (docs/v2-CONTRACT.md §3c), and the task's identity is not a
+          // fact the model is meant to hold.
+          return textResult(`reported ${result.outcome}`, { outcome: result.outcome });
         },
       }));
     } catch (error) {
@@ -208,16 +216,14 @@ export default function onlyne(pi: ExtensionAPI) {
         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",
+          "Hand the current task on to another role, which continues it. Call it when this task's work goes on to another role.",
+        promptSnippet: "Hand the current task on to another role",
         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.",
+          "Use onlyne_handoff when this task's work goes on to another role; the receiving role continues it.",
         ],
         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" }),
+          text: Type.String({ description: "handoff text for the receiving role" }),
           image: Type.Optional(Type.String({ description: "absolute path to a png/jpeg/gif/webp image to attach" })),
         }),
         async execute(_toolCallId, params) {
@@ -227,7 +233,10 @@ export default function onlyne(pi: ExtensionAPI) {
             text: params.text,
             imagePath: params.image ?? null,
           });
-          return textResult(`handed on to ${result.to} as ${result.taskId} at hop ${result.hop}`, result);
+          // The recipient and nothing else: the child's id and the hop are the
+          // host's bookkeeping, and a result naming them would teach the model
+          // to read itself as one node of a numbered chain.
+          return textResult(`handed on to ${result.to}`, { to: result.to });
         },
       }));
     } catch (error) {
@@ -270,21 +279,18 @@ export default function onlyne(pi: ExtensionAPI) {
       log(`disabled by ${config.path}`);
       return;
     }
-    // Environment first (the client injects the path it serves), then the
-    // marker the daemon publishes, then the canonical `run/s` (socket.mjs).
-    const socketPath = resolveSocketPath(env, ctx.cwd);
-    // The guard's policy comes from the spec through the client's environment;
-    // a hand-written `relay.toml` beside the package is the fallback a manual
-    // installation still has (relay.mjs).
-    const relay = loadRelay();
-    if (relay.warning) log(relay.warning);
-    if (relayEnabled(relay)) {
-      const origin = relay.source === "env" ? "the client's environment" : relay.path;
-      log(
-        `relay guard from ${origin}: required=${JSON.stringify(relay.required)} count=${relay.count ?? "-"}`,
-      );
+    // The path the client injected, or the client the runtime directory's
+    // registration files name for this workspace (socket.mjs). A session with
+    // neither has no socket to dial, and saying so is the whole answer: this
+    // stays a plain pi session instead of retrying a path nothing serves.
+    let socketPath: string | null = null;
+    try {
+      socketPath = resolveSocketPath(env, ctx.cwd);
+    } catch (error) {
+      log(`socket unresolved: ${error instanceof Error ? error.message : String(error)}`);
     }
-    surface = createSurface({ pi, log, context: () => context });
+    if (socketPath === null) return;
+    surface = createSurface({ pi, log, context: () => context, sessionId: identity.sessionId });
     agent = new OnlyneAgent({
       socketPath,
       cwd: ctx.cwd,
@@ -292,8 +298,6 @@ export default function onlyne(pi: ExtensionAPI) {
       sessionId: identity.sessionId,
       taskId: identity.taskId,
       surface,
-      relay,
-      idleReminders: config.idleReminders,
       log,
     });
     log(`session ${identity.sessionId} role=${identity.role} socket=${socketPath}`);
@@ -307,6 +311,15 @@ export default function onlyne(pi: ExtensionAPI) {
     if (config.autoStart) agent.start();
   });
 
+  // The role prose is instruction-layer text: `before_agent_start` hands the
+  // handler the prompt options the run is about to render, and a section written
+  // there is part of the system prompt rather than one more message the model has
+  // to read as an utterance. Outside an onlyne session there is no surface and
+  // nothing to add.
+  pi.on("before_agent_start", async (event) => {
+    surface?.applyRoleProse(event);
+  });
+
   pi.on("turn_start", async () => {
     agent?.onTurnStart();
   });