pi-onlyne 1.1.2 → 1.2.1

package/src/background-work.mjs

@@ -0,0 +1,176 @@
+// The one question a background-task extension makes necessary: is this
+// session's work still running somewhere the agent loop cannot see?
+//
+// `pi-background-tasks` and its relatives take a long command off the loop — the
+// tool call returns a task id at once and the child process carries on. pi then
+// waits for input while the work runs, so `ctx.isIdle()` alone would report a
+// session as idle with a task in flight. This probe reads the extension's own
+// live task list over the pi EventBus, and only when the extension is installed:
+// without one of its tools there is nothing to recognise, nothing to query, and
+// nothing to wait for.
+//
+// The contract is that package's documented `eventbus-v1` surface
+// (`pi-background-tasks/docs/api/eventbus-v1.md`): one request frame in, one
+// response frame out, both closed objects carrying a schema id. A response that
+// never arrives, a frame that does not parse, an error response, and a host with
+// no EventBus all read as "no background work known" and leave the plugin's own
+// judgement untouched.
+
+/** The tools that mark the extension as installed. */
+export const BACKGROUND_TOOL_NAMES = Object.freeze([
+  "bg_run",
+  "bg_run_pi_attested",
+  "bg_status",
+  "bg_logs",
+  "bg_kill",
+  "bg_delegate",
+  "bg_result",
+  "fusion_reason",
+  "fusion_investigate",
+  "fusion_research",
+  "fusion_validate",
+  "fusion_web_fetch",
+]);
+
+const REQUEST_CHANNEL = "pi-background-tasks:request:v1";
+const RESPONSE_CHANNEL = "pi-background-tasks:response:v1";
+const REQUEST_SCHEMA = "pi-background-tasks.extension-request.v1";
+const RESPONSE_SCHEMA = "pi-background-tasks.extension-response.v1";
+
+/** Task statuses that mean the work is still going. */
+const LIVE_TASK_STATUS = "running";
+
+/** How long one status query waits for its answer. */
+export const DEFAULT_STATUS_TIMEOUT_MS = 500;
+
+/** @param {string} name */
+export function isBackgroundTool(name) {
+  return BACKGROUND_TOOL_NAMES.includes(name);
+}
+
+let requestCounter = 0;
+
+function nextRequestId() {
+  requestCounter += 1;
+  return `onlyne-bg-status-${requestCounter}`;
+}
+
+function isResponseFor(frame, requestId) {
+  return frame
+    && typeof frame === "object"
+    && frame.schema_version === RESPONSE_SCHEMA
+    && frame.request_id === requestId;
+}
+
+/**
+ * One live-task question, asked of the EventBus and answered by whatever is
+ * listening. Every failure mode is inert: the probe reports `false` and says why
+ * once, then lets the caller's own judgement stand.
+ *
+ * @param {{
+ *   events?: { emit: (channel: string, data: unknown) => void, on: (channel: string, handler: (data: unknown) => void) => () => void } | null,
+ *   getToolNames?: () => string[] | null,
+ *   log?: (line: string) => void,
+ *   timeoutMs?: number,
+ * }} options
+ */
+export function createBackgroundProbe({
+  events = null,
+  getToolNames = null,
+  log = () => {},
+  timeoutMs = DEFAULT_STATUS_TIMEOUT_MS,
+} = {}) {
+  let installed = null;
+  const warned = new Set();
+  let unsubscribe = null;
+
+  const warnOnce = (reason) => {
+    if (warned.has(reason)) return;
+    warned.add(reason);
+    log(`background work: ${reason}`);
+  };
+
+  /** True once one of the extension's tools is registered; cached either way. */
+  function isInstalled() {
+    if (installed !== null) return installed;
+    let names = null;
+    try {
+      names = typeof getToolNames === "function" ? getToolNames() : null;
+    } catch (error) {
+      warnOnce(`tool list unreadable: ${error.message}`);
+      return false;
+    }
+    const list = Array.isArray(names) ? names : [];
+    installed = list.some(isBackgroundTool);
+    if (!installed) log("background work: no background-task extension in this session");
+    return installed;
+  }
+
+  /**
+   * One status round trip. The answer arrives on the response channel, so the
+   * listener lives exactly as long as the wait and the timer bounds it.
+   * @returns {Promise<boolean>}
+   */
+  function running() {
+    if (!isInstalled()) return Promise.resolve(false);
+    const bus = events;
+    if (!bus || typeof bus.emit !== "function" || typeof bus.on !== "function") {
+      warnOnce("event bus unavailable");
+      return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+      const requestId = nextRequestId();
+      let settled = false;
+      let timer = null;
+      const finish = (answer) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (typeof unsubscribe === "function") unsubscribe();
+        unsubscribe = null;
+        resolve(answer);
+      };
+      try {
+        unsubscribe = bus.on(RESPONSE_CHANNEL, (frame) => {
+          if (!isResponseFor(frame, requestId)) return;
+          if (frame.ok !== true) {
+            warnOnce(`status query refused: ${String(frame.error ?? "unknown")}`);
+            finish(false);
+            return;
+          }
+          const tasks = frame.result?.tasks;
+          if (!Array.isArray(tasks)) {
+            warnOnce("status answer carried no task list");
+            finish(false);
+            return;
+          }
+          finish(tasks.some((task) => task?.status === LIVE_TASK_STATUS));
+        });
+        bus.emit(REQUEST_CHANNEL, {
+          schema_version: REQUEST_SCHEMA,
+          request_id: requestId,
+          operation: "status",
+          payload: {},
+        });
+      } catch (error) {
+        warnOnce(`status query failed: ${error.message}`);
+        finish(false);
+        return;
+      }
+      timer = setTimeout(() => {
+        warnOnce("status query timed out");
+        finish(false);
+      }, timeoutMs);
+      if (typeof timer?.unref === "function") timer.unref();
+    });
+  }
+
+  return {
+    installed: isInstalled,
+    running,
+    close() {
+      if (typeof unsubscribe === "function") unsubscribe();
+      unsubscribe = null;
+    },
+  };
+}

package/src/background-work.test.mjs

@@ -0,0 +1,128 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { createBackgroundProbe } from "./background-work.mjs";
+
+const RESPONSE_CHANNEL = "pi-background-tasks:response:v1";
+const RESPONSE_SCHEMA = "pi-background-tasks.extension-response.v1";
+
+class FakeEventBus {
+  constructor(answer) {
+    this.answer = answer;
+    this.emits = [];
+    this.listeners = new Map();
+    this.drops = 0;
+  }
+
+  on(channel, handler) {
+    const handlers = this.listeners.get(channel) ?? new Set();
+    handlers.add(handler);
+    this.listeners.set(channel, handlers);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      this.drops += 1;
+      handlers.delete(handler);
+    };
+  }
+
+  emit(channel, data) {
+    this.emits.push({ channel, data });
+    if (channel !== "pi-background-tasks:request:v1") return;
+    this.answer?.(data, (frame) => {
+      for (const handler of [...(this.listeners.get(RESPONSE_CHANNEL) ?? [])]) {
+        handler(frame);
+      }
+    });
+  }
+
+  listenerCount() {
+    return [...this.listeners.values()].reduce((total, handlers) => total + handlers.size, 0);
+  }
+}
+
+function response(request, body) {
+  return {
+    schema_version: RESPONSE_SCHEMA,
+    request_id: request.request_id,
+    ...body,
+  };
+}
+
+function probeFor(answer, timeoutMs = 20) {
+  const events = new FakeEventBus(answer);
+  const probe = createBackgroundProbe({
+    events,
+    getToolNames: () => ["bg_run"],
+    timeoutMs,
+  });
+  return { events, probe };
+}
+
+test("a session without a background-task tool makes no EventBus query", async () => {
+  const events = new FakeEventBus(() => {
+    assert.fail("an uninstalled background-task extension must not be queried");
+  });
+  const probe = createBackgroundProbe({
+    events,
+    getToolNames: () => ["read_file"],
+  });
+
+  assert.equal(await probe.running(), false);
+  assert.deepEqual(events.emits, []);
+  assert.equal(events.listenerCount(), 0);
+});
+
+test("a live background task answers true and drops the response listener", async () => {
+  const { events, probe } = probeFor((request, respond) => {
+    respond(response(request, { ok: true, result: { tasks: [{ status: "running" }] } }));
+  });
+
+  assert.equal(await probe.running(), true);
+  assert.equal(events.emits.length, 1);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});
+
+test("a terminal background task list answers false and drops the response listener", async () => {
+  const { events, probe } = probeFor((request, respond) => {
+    respond(response(request, {
+      ok: true,
+      result: { tasks: [{ status: "completed" }, { status: "failed" }] },
+    }));
+  });
+
+  assert.equal(await probe.running(), false);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});
+
+test("a refused status query answers false and drops the response listener", async () => {
+  const { events, probe } = probeFor((request, respond) => {
+    respond(response(request, { ok: false, error: "status unavailable" }));
+  });
+
+  assert.equal(await probe.running(), false);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});
+
+test("a malformed status answer reads false and drops the response listener", async () => {
+  const { events, probe } = probeFor((request, respond) => {
+    respond(response(request, { ok: true, result: { tasks: "running" } }));
+  });
+
+  assert.equal(await probe.running(), false);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});
+
+test("a background-task service that never answers reads false and drops the response listener", async () => {
+  const { events, probe } = probeFor(null, 10);
+
+  assert.equal(await probe.running(), false);
+  assert.equal(events.emits.length, 1);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});

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,11 @@
 //
 //   session_start    -> read env + .pi/onlyne.json, connect, register tools
 //   turn_start       -> heartbeat{running}
-//   turn_end         -> heartbeat{idle}
+//   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    -> completion exit: done|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}
 
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -68,6 +70,10 @@ interface PiSurface {
   status(text: string): void;
   welcome(welcome: WelcomeLike): void;
   isIdle(): boolean;
+  /** The phase rule: true only while the session waits for user input. */
+  waitingForInput(): Promise<boolean>;
+  /** Drops the background-task probe's EventBus subscription. */
+  closeBackground?(): void;
   exit(reason: string): void;
 }
 
@@ -165,10 +171,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 +203,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 +293,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}`);
@@ -294,6 +332,7 @@ export default function onlyne(pi: ExtensionAPI) {
 
   pi.on("session_shutdown", async (event) => {
     agent?.stop(`pi:${event.reason ?? "quit"}`);
+    surface?.closeBackground?.();
     surface?.widget?.(undefined);
     agent = null;
     surface = null;

package/src/pi-surface.mjs

@@ -10,9 +10,13 @@
 //   status        ctx.ui.setStatus("onlyne", text)
 //   exit          ctx.shutdown()
 //   isIdle        ctx.isIdle()
+//   pending       ctx.hasPendingMessages()
+//   toolNames     pi.getAllTools()          (background-work.mjs)
+//   eventBus      pi.events                 (background-work.mjs)
 //   registerTool / registerCommand are probed by index.ts itself.
 
 import { WIDGET_KEY } from "./activity.mjs";
+import { createBackgroundProbe } from "./background-work.mjs";
 
 /**
  * @param {{ pi: any, log: (line: string) => void, context: () => any }} options
@@ -27,6 +31,30 @@ export function createSurface({ pi, log, context }) {
     }
   };
 
+  /**
+   * The one question behind every phase the plugin reports. pi answers it; a
+   * probe that is missing, throws, or arrives without a context answers `false`
+   * because an unwitnessed session is a running one as far as this plugin can
+   * prove (`background-work.mjs` carries the second half of the question).
+   */
+  const piWaitsForInput = () => {
+    const current = ctx();
+    if (!current) return false;
+    try {
+      if (!has(current.isIdle) || !current.isIdle()) return false;
+      if (has(current.hasPendingMessages) && current.hasPendingMessages()) return false;
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const background = createBackgroundProbe({
+    events: pi.events ?? null,
+    getToolNames: has(pi.getAllTools) ? () => (pi.getAllTools() ?? []).map((tool) => tool?.name) : null,
+    log,
+  });
+
   const available = {
     wakeUser: has(pi.sendUserMessage),
     proseContext: has(pi.sendMessage),
@@ -139,6 +167,18 @@ export function createSurface({ pi, log, context }) {
         return true;
       }
     },
+    /**
+     * The phase rule in one place: idle means waiting for user input, and a
+     * background-task extension holding live work keeps the session running
+     * even while pi itself waits.
+     */
+    async waitingForInput() {
+      if (!piWaitsForInput()) return false;
+      return !(await background.running());
+    },
+    closeBackground() {
+      background.close();
+    },
     exit(reason) {
       log(`exiting pi: ${reason}`);
       try {

package/src/protocol.mjs

@@ -111,9 +111,13 @@ export function readyReport({ taskId, sessionId, generation, seq }) {
 }
 
 /**
- * `report.heartbeat`. `observed` is a full `Observation` (`onlyne-session`'s
- * reducer type), not a loose status string: the host deserialises it and rejects
- * anything that is not a legal state tuple.
+ * `report.heartbeat`. `observed` is an `Observation` (`onlyne-session`'s reducer
+ * type), not a loose status string: the host deserialises the tuple, overwrites
+ * the six dimensions it owns — `delivery` and `recovery` from its intent drain
+ * and reducer history, `generation_live` and the reconcile tuning with its
+ * counter from the role's own records — and repairs whatever pairing that leaves
+ * before the reducer reads it. What
+ * this plugin puts into the body is `observationFor`'s exact key set.
  */
 export function heartbeatReport({ taskId, generation, seq, agent, host = null }) {
   return {
@@ -127,40 +131,6 @@ export function heartbeatReport({ taskId, generation, seq, agent, host = null })
   };
 }
 
-/**
- * The final observation of a settled session: `agent: idle` beside the outcome
- * the completion just stated.
- *
- * A session that only ever reported `running` and then completed leaves the
- * ledger's projection saying `running` forever, because nothing observes the
- * exit. This body is the tuple the host's own settle produces
- * (`onlyne-session/src/reconcile.rs::settle_body`) with the agent dimension
- * moved to `idle`, so `is_legal` accepts it: `outcome: done` requires
- * `delivery: accepted` and an idle agent requires `recovery: draining`, and any
- * other outcome carries the delivery unchanged.
- */
-export function settledReport({ taskId, outcome, generation, seq, host = null }) {
-  const normalized = normalizeOutcome(outcome);
-  const done = normalized === "done";
-  const observed = {
-    version: { generation, seq },
-    generation_live: true,
-    isolate_after: 1,
-    terminate_after: 3,
-    mismatch_count: 0,
-    agent: "idle",
-    delivery: done ? "accepted" : "none",
-    resource: "attached",
-    recovery: done ? "draining" : "none",
-    outcome: normalized,
-    // `project(idle, accepted, …, done)` is `exited`; every other outcome keeps
-    // the session `working` until its resource closes.
-    public: done ? "exited" : "working",
-  };
-  if (host) observed.host = host;
-  return { kind: "heartbeat", data: { task_id: taskId, generation, seq, observed } };
-}
-
 /** `report.complete` — the terminal fact the ledger keeps. */
 export function completeReport({ taskId, outcome, head }) {
   const report = { kind: "complete", data: { task_id: taskId, outcome: normalizeOutcome(outcome) } };
@@ -191,17 +161,29 @@ export function detachArgs(reason) {
 }
 
 /**
- * A legal `Observation` for one agent state.
+ * The observation for one agent state: the plugin's own report, on the wire as
+ * the `observed` body of a heartbeat.
  *
- * `onlyne-session`'s `is_legal` requires `public` to be `project(...)` of the
- * other dimensions and non-zero reconcile policy, so the tuple is built rather
- * than passed through: the plugin owns the agent dimension (the host never
- * synthesises turn state), and leaves delivery at `none`/outcome `pending`,
- * which is its own truth until it reports a completion.
+ * The plugin states three things and only three: the `agent` dimension (its turn
+ * hooks are the only witness), `resource: attached` — the process is running in
+ * the pane, which is the attach the host's dispatch path recorded — and the
+ * `host` binding. `delivery`, `recovery`, `generation_live`, `isolate_after`,
+ * `terminate_after` and `mismatch_count` are placeholders with a reason:
+ * `Observation` has no optional dimensions, the body must deserialize, and the
+ * client rewrites all six from its own records before the reducer reads them
+ * (`crates/onlyne-client/src/session/dispatch/reports.rs`) — the completion
+ * intent and its recovery label are the client's, the reconcile tuning and the
+ * counter beside it are the role's — so what the plugin sends there is never
+ * believed. Neither the task's outcome nor a public view
+ * belongs in a tuple any more — the ledger owns the result, `project` derives
+ * the view — so neither is sent.
  *
- * `host` is where this process runs (`hostBinding`); it is attached only when
- * the environment names a pane, so a pi outside Orca reports a tuple with no
- * host field at all.
+ * `gone` travels as `booting` on purpose: only the host's reconnect-grace window
+ * declares a session dead, and a beat that pre-declared `gone` would bury the
+ * row's agent before that window has run.
+ *
+ * `host` is attached only when the environment names a pane, so a pi outside
+ * Orca reports a tuple with no host field at all.
  * @param {"booting"|"ready"|"running"|"idle"|"gone"} agent
  */
 export function observationFor(agent, { generation, seq, host = null }) {
@@ -217,8 +199,6 @@ export function observationFor(agent, { generation, seq, host = null }) {
     delivery: "none",
     resource: "attached",
     recovery: "none",
-    outcome: "pending",
-    public: state === "running" ? "working" : state === "ready" || state === "idle" ? "idle" : "created",
   };
   if (host) observed.host = host;
   return observed;
@@ -331,13 +311,25 @@ export function normalizeOutcome(value) {
  * session transcript shows where the instruction came from; the role prose
  * (identical in `welcome` and `assign`) is folded in only when it has not
  * already been delivered.
+ *
+ * The header also carries the family's own figures — the hop this assignment
+ * sits at and the hops the family may spend — so a role reads its position off
+ * the instruction. Both appear only when the causality names a hop budget: the
+ * budget is what marks a payload as a member of a bounded family, and a payload
+ * that names none injects exactly the bytes it produced before this header
+ * carried them.
  * @param {{ assign: any, proseIsNew: boolean, attachmentPaths?: string[] }} options
  */
 export function injectionText({ assign, proseIsNew, attachmentPaths = [] }) {
   const envelope = assign.envelope ?? {};
+  const causality = envelope.causality ?? {};
   const taskId = assign.task_id ?? envelope.causality?.task ?? "unknown";
+  const position =
+    typeof causality.hop_budget === "number"
+      ? `, hop ${causality.hop ?? 0}, hop budget ${causality.hop_budget}`
+      : "";
   const lines = [
-    `[onlyne] task ${taskId} from ${describePrincipal(envelope.from)} (kind ${envelope.kind ?? "task"})`,
+    `[onlyne] task ${taskId} from ${describePrincipal(envelope.from)} (kind ${envelope.kind ?? "task"}${position})`,
   ];
   const prose = typeof assign.prose === "string" ? assign.prose.trim() : "";
   if (prose && proseIsNew) {