pi-onlyne 2.1.0 → 2.3.0

package/src/index.ts

@@ -7,28 +7,49 @@
 // `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
+//   session_start      -> bind the env session id, read env + .pi/onlyne.json,
+//                         connect, register tools; a resident plugin that is
+//                         already connected only follows the switch
+//   session_switch     -> /new, /resume and /fork on a host that names them;
+//   session_branch       the same re-point a resident plugin does when current
+//   session_tree         pi reports the switch through session_start, and
+//                        after tree navigation
 //   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
+//   message_end        -> keep the last assistant text as the head fallback
+//   agent_settled      -> heartbeat{idle} when the session waits for input
 //   session_shutdown   -> detach{reason}
 //
+// The plugin keeps exactly one completion path: the model's explicit
+// `onlyne_complete` (and `recycle{outcome}`). A turn that ends without one
+// decides nothing here — the client's own turn-end rule owns it
+// (`docs/v2-CONTRACT.md` §3c: one nudge, then the delivery settles `blocked`)
+// and its sweeps own a session whose agent died. A turn error only supplies the
+// head fallback, because pi retries a retryable provider error and stays inside
+// the same run, and the client's nudge can restart a session a moment after it
+// settles — a report sent on a turn error would race work that is still going.
+//
 // 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.
+//
+// Only the session whose id equals `ONLYNE_SESSION_ID` mounts: a pi process runs
+// a subagent sidechain and `/new` sessions too, all inheriting this extension's
+// environment, and a sidechain that called `onlyne_complete` would settle the
+// parent's task. `session-scope.mjs` carries the rule, the guard behind it, and
+// what a call from a foreign session is told.
 
 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 { resolveSocketPath } from "./socket.mjs";
+import { ASSIGN_MESSAGE_TYPE, createAssignMessageComponent } from "./activity.mjs";
+import { loadConfig, residentIdentity, sessionIdentity } from "./config.mjs";
+import { resolveResidentSocketPath, resolveSocketPath } from "./socket.mjs";
 import { createSurface } from "./pi-surface.mjs";
+import { foreignSessionRefusal, mountsSession, ownsSession, sessionIdOf } from "./session-scope.mjs";
 
 /**
  * Node's process globals, declared here so the package needs no `@types/node`
@@ -67,11 +88,11 @@ interface PiSurface {
     registerTool: boolean;
     registerCommand: boolean;
   };
-  wakeUser(text: string, parts?: ImagePartInput[]): boolean;
+  wakeUser(text: string, parts?: ImagePartInput[], meta?: unknown): boolean;
   roleProse(text: string): boolean;
   applyRoleProse(event: { systemPromptOptions?: { sections?: Record<string, string> } }): boolean;
   customEntry(customType: string, data: unknown): boolean;
-  widget(lines: string[] | undefined): void;
+  widget(lines: string[] | undefined, activity?: unknown): void;
   status(text: string): void;
   welcome(welcome: WelcomeLike): void;
   isIdle(): boolean;
@@ -131,16 +152,43 @@ export default function onlyne(pi: ExtensionAPI) {
   let agent: OnlyneAgent | null = null;
   let surface: PiSurface | null = null;
   let registered = false;
+  /**
+   * The session id that mounted this plugin. A pi process can host more than
+   * one session — a `task` subagent runs a sidechain in the same process and
+   * inherits `ONLYNE_*`, and `/new` starts another — and every one of them
+   * loads this extension. The env names the one session that is the onlyne
+   * session, so the tools belong to it alone; an unbound session must not be
+   * able to settle this task by calling `onlyne_complete` from its sidechain.
+   */
+  let boundSessionId: string | null = null;
 
   const log = (line: string, data?: unknown) => {
     const detail = data === undefined ? "" : ` ${JSON.stringify(data)}`;
     process?.stderr?.write(`[pi-onlyne] ${line}${detail}\n`);
   };
 
+  /**
+   * Guard one tool call: the caller must be the session that mounted this
+   * plugin (`session-scope.mjs` carries the rule and the reason).
+   */
+  const refuseForeignSession = (caller: string | null): never => {
+    throw new Error(foreignSessionRefusal(boundSessionId, caller));
+  };
+
   /** Tools and the `/onlyne` command exist only inside an onlyne session. */
   const registerSurface = () => {
     if (registered || !surface) return;
     registered = true;
+    if ("registerMessageRenderer" in pi && typeof pi.registerMessageRenderer === "function") {
+      try {
+        pi.registerMessageRenderer(ASSIGN_MESSAGE_TYPE, (message, options, theme) => {
+          if (!message?.details || typeof message.details !== "object") return undefined;
+          return createAssignMessageComponent(message.details, message.content, theme, !options?.expanded);
+        });
+      } catch (error) {
+        log(`registerMessageRenderer(${ASSIGN_MESSAGE_TYPE}) refused: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
     try {
       pi.registerTool(defineTool({
         name: "onlyne_send",
@@ -157,7 +205,9 @@ export default function onlyne(pi: ExtensionAPI) {
           kind: Type.Optional(Type.String({ description: '"note" (default) or "task"' })),
           image: Type.Optional(Type.String({ description: "absolute path to a png/jpeg/gif/webp image to attach" })),
         }),
-        async execute(_toolCallId, params) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+          const caller = sessionIdOf(ctx?.sessionManager);
+          if (!ownsSession(boundSessionId, caller)) refuseForeignSession(caller);
           if (!agent) throw new Error("onlyne: session is not connected");
           const result = await agent.sendFromTool({
             to: params.to,
@@ -189,7 +239,9 @@ export default function onlyne(pi: ExtensionAPI) {
           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) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+          const caller = sessionIdOf(ctx?.sessionManager);
+          if (!ownsSession(boundSessionId, caller)) refuseForeignSession(caller);
           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
@@ -202,6 +254,17 @@ export default function onlyne(pi: ExtensionAPI) {
             details: params.details,
             files: params.files,
           });
+          // The client that had already settled this task answers with its own
+          // record, and the sentence says so rather than claiming a completion
+          // this call did not cause.
+          if (result.alreadySettled) {
+            const settled = result.alreadySettled;
+            const head = settled.head ? `: ${settled.head}` : "";
+            return textResult(
+              `task already settled as ${settled.state} at ${settled.settled_at}${head} — this call changed nothing`,
+              { outcome: result.outcome, alreadySettled: settled }
+            );
+          }
           // 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.
@@ -226,7 +289,9 @@ export default function onlyne(pi: ExtensionAPI) {
           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) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+          const caller = sessionIdOf(ctx?.sessionManager);
+          if (!ownsSession(boundSessionId, caller)) refuseForeignSession(caller);
           if (!agent) throw new Error("onlyne: session is not connected");
           const result = await agent.handoffFromTool({
             to: params.to,
@@ -246,6 +311,17 @@ export default function onlyne(pi: ExtensionAPI) {
       pi.registerCommand("onlyne", {
         description: "Onlyne session status: connection, task, reports",
         handler: async (argLine, commandContext) => {
+          // The command drives this plugin's connection, so it belongs to the
+          // bound session for the same reason the tools do: a sidechain that
+          // issued `/onlyne disconnect` would detach the real session.
+          const caller = sessionIdOf(commandContext?.sessionManager);
+          if (!ownsSession(boundSessionId, caller)) {
+            commandContext.ui.notify(
+              foreignSessionRefusal(boundSessionId, caller),
+              "info"
+            );
+            return;
+          }
           if (!agent) {
             commandContext.ui.notify("onlyne: no session (ONLYNE_* env is absent)", "info");
             return;
@@ -269,10 +345,59 @@ export default function onlyne(pi: ExtensionAPI) {
     }
   };
 
-  pi.on("session_start", async (_event, ctx) => {
+  /**
+   * Re-point the plugin at the session pi made current. The socket belongs to
+   * the role, not to the session file that mounted it: /new, /resume, /fork and
+   * a tree jump replace the live session in this process, and the tools must
+   * follow it instead of refusing every call as foreign.
+   */
+  const syncSessionContext = (_event: unknown, ctx: ExtensionContext) => {
+    if (!agent) return;
     context = ctx;
-    const identity = sessionIdentity(env);
+    const currentId = sessionIdOf(ctx?.sessionManager);
+    if (currentId) {
+      boundSessionId = currentId;
+    }
+    if (surface?.available.widget) {
+      surface.widget(agent.activity.lines(), agent.activity);
+    }
+    surface?.status(agent.activity.lines()[0]);
+  };
+
+  pi.on("session_start", async (event, ctx) => {
+    const spawned = sessionIdentity(env);
+    const resident = spawned ? null : residentIdentity(env, ctx.cwd);
+    const identity = spawned ?? resident;
     if (!identity) return; // not an onlyne session: stay out of the way
+    // Only the session the client names may mount. A pi process runs more than
+    // one session — a `task` subagent's sidechain, `/new` — and each of them
+    // loads this extension with the same inherited environment, so without this
+    // check a subagent's `onlyne_complete` settles the parent's task (observed:
+    // librarian task cfa73386). An unknown id means an older pi that does not
+    // expose one; the env-bound mount is then the only candidate and stays the
+    // behaviour, with no line to explain.
+    const starting = sessionIdOf(ctx.sessionManager);
+    // A resident plugin already holds its connection, so another session_start
+    // in this process is a re-point, not a mount: /new, /resume and /fork
+    // replace the live session, and pi can re-bind this same session's
+    // extensions. The sidechain a `task` subagent runs re-binds every extension
+    // with reason "startup" and a different id, and stays inert.
+    if (!spawned && agent !== null && (event.reason !== "startup" || starting === boundSessionId)) {
+      syncSessionContext(event, ctx);
+      return;
+    }
+    if (spawned) {
+      if (!mountsSession(spawned.sessionId, starting)) {
+        log(`session ${starting} is not the onlyne session ${spawned.sessionId}; staying inert`);
+        return;
+      }
+    } else if (boundSessionId !== null && starting !== null && starting !== boundSessionId) {
+      log(`session ${starting} is not the resident onlyne session ${boundSessionId}; staying inert`);
+      return;
+    }
+    const wireSessionId = identity.sessionId ?? starting;
+    context = ctx;
+    boundSessionId = spawned ? spawned.sessionId : (starting ?? wireSessionId);
     const config = loadConfig(ctx.cwd);
     if (config.warning) log(config.warning);
     if (!config.enabled) {
@@ -284,23 +409,30 @@ export default function onlyne(pi: ExtensionAPI) {
     // 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;
+    const targetWorkspace = resident ? resident.workspaceRoot : ctx.cwd;
     try {
-      socketPath = resolveSocketPath(env, ctx.cwd);
+      socketPath = resident
+        ? resolveResidentSocketPath(env, targetWorkspace, identity.role)
+        : resolveSocketPath(env, ctx.cwd);
     } catch (error) {
       log(`socket unresolved: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (socketPath === null) return;
-    surface = createSurface({ pi, log, context: () => context, sessionId: identity.sessionId });
+    surface = createSurface({ pi, log, context: () => context, sessionId: () => boundSessionId });
     agent = new OnlyneAgent({
       socketPath,
+      resolveSocket: resident
+        ? () => resolveResidentSocketPath(env, targetWorkspace, identity.role)
+        : undefined,
       cwd: ctx.cwd,
       role: identity.role,
-      sessionId: identity.sessionId,
+      sessionId: wireSessionId,
       taskId: identity.taskId,
+      resident: Boolean(resident),
       surface,
       log,
     });
-    log(`session ${identity.sessionId} role=${identity.role} socket=${socketPath}`);
+    log(`session ${wireSessionId ?? "resident"} role=${identity.role} socket=${socketPath}`);
     registerSurface();
     if (!surface.available.wakeUser) {
       // Without an injection surface the payload travels through config_get,
@@ -311,6 +443,18 @@ export default function onlyne(pi: ExtensionAPI) {
     if (config.autoStart) agent.start();
   });
 
+  // `session_switch` and `session_branch` name the same transitions in the omp
+  // lineage of this API; current pi reports them as `session_start` with a
+  // reason and keeps `session_tree` for navigation, so one helper serves all.
+  // The installed typings no longer declare the first two, but the host stores
+  // handlers by name, which this narrow cast is the whole boundary of.
+  const legacySessionEvents = pi as unknown as {
+    on(event: "session_switch" | "session_branch", handler: (event: unknown, ctx: ExtensionContext) => void): void;
+  };
+  legacySessionEvents.on("session_switch", syncSessionContext);
+  legacySessionEvents.on("session_branch", syncSessionContext);
+  pi.on("session_tree", async (event, ctx) => syncSessionContext(event, ctx));
+
   // 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
@@ -351,5 +495,6 @@ export default function onlyne(pi: ExtensionAPI) {
     surface = null;
     registered = false;
     context = null;
+    boundSessionId = null;
   });
 }

package/src/pi-surface.mjs

@@ -18,7 +18,7 @@
 //   subagentRegistry  ~/.pi/subagents/missions  (background-subagents.mjs)
 //   registerTool / registerCommand are probed by index.ts itself.
 
-import { WIDGET_KEY } from "./activity.mjs";
+import { ASSIGN_MESSAGE_TYPE, WIDGET_KEY } from "./activity.mjs";
 import { createSubagentProbe } from "./background-subagents.mjs";
 import { createBackgroundProbe } from "./background-work.mjs";
 
@@ -34,6 +34,7 @@ export const PROSE_SECTION = "onlyne-role-prose";
  * @param {{ pi: any, log: (line: string) => void, context: () => any, sessionId?: string | null }} options
  */
 export function createSurface({ pi, log, context, sessionId = null }) {
+  let currentSessionId = typeof sessionId === "function" ? sessionId : () => sessionId;
   const has = (value) => typeof value === "function";
   const ctx = () => {
     try {
@@ -71,7 +72,7 @@ export function createSurface({ pi, log, context, sessionId = null }) {
   // leave a subagent running with no tool event to bracket it. Scoped to this
   // session's own missions when the plugin knows its id.
   const subagents = createSubagentProbe({
-    getSessionId: () => sessionId,
+    getSessionId: () => currentSessionId(),
     log,
   });
 
@@ -95,7 +96,9 @@ export function createSurface({ pi, log, context, sessionId = null }) {
   const available = {
     wakeUser: has(pi.sendUserMessage),
     customEntry: has(pi.appendEntry),
-    widget: has(ctx()?.ui?.setWidget),
+    get widget() {
+      return has(ctx()?.ui?.setWidget);
+    },
     status: true,
     exit: true,
     isIdle: true,
@@ -103,9 +106,19 @@ export function createSurface({ pi, log, context, sessionId = null }) {
     registerCommand: has(pi.registerCommand),
   };
 
-  const widget = (lines) => {
+  const widget = (lines, activity = null) => {
     try {
-      ctx()?.ui?.setWidget?.(WIDGET_KEY, lines);
+      const ui = ctx()?.ui;
+      if (!has(ui?.setWidget)) return;
+      if (lines === undefined) {
+        ui.setWidget(WIDGET_KEY, undefined);
+        return;
+      }
+      if (activity && typeof activity.component === "function") {
+        ui.setWidget(WIDGET_KEY, (tui, theme) => activity.component(theme, tui));
+        return;
+      }
+      ui.setWidget(WIDGET_KEY, lines);
     } catch {
       /* widget is decoration; never let it break the protocol */
     }
@@ -120,7 +133,7 @@ export function createSurface({ pi, log, context, sessionId = null }) {
   };
 
   /**
-   * One pi user message; images ride along as pi image content parts.
+   * One delivery, one message; images ride along as pi image content parts.
    *
    * pi reads an image part as the flat `ImageContent` of its message types —
    * `data` plus `mimeType` — and normalizes every part before the message is
@@ -128,8 +141,21 @@ export function createSurface({ pi, log, context, sessionId = null }) {
    * pi reports that failure in its own pane and hands nothing back to this
    * plugin, so an unusable part is dropped here and the assignment still
    * travels: the delivery text already names the path the client wrote.
+   *
+   * With `meta` and `pi.sendMessage`, the `onlyne_assign` card IS the delivery:
+   * a custom message reaches the model, and it is what the transcript draws, so
+   * a delivery does not also arrive as a second user message. `triggerTurn` is
+   * what an idle session owes it (a `display: true` custom message renders
+   * without starting a turn of its own); while a turn is running the card queues
+   * behind it as a follow-up instead of interrupting tool execution.
+   *
+   * A pi without `sendMessage` takes the plain `sendUserMessage` below — idle
+   * without `deliverAs` so the delivery starts the turn it owes, `followUp` when
+   * busy (`deliverAs: "followUp"` only enqueues and requires a prior
+   * assistant/toolResult tail to auto-continue). That path is the pre-card
+   * shape, kept so an older pi still receives a delivery.
    */
-  const wakeUser = (text, parts = []) => {
+  const wakeUser = (text, parts = [], meta = null) => {
     if (!available.wakeUser) {
       log("pi has no sendUserMessage; the assignment reached the session log only");
       return false;
@@ -150,8 +176,43 @@ export function createSurface({ pi, log, context, sessionId = null }) {
             mimeType: part.mime,
           })),
         ];
+    const current = ctx();
+    let idle = false;
     try {
-      pi.sendUserMessage(content, { deliverAs: "followUp" });
+      if (has(current?.isIdle)) idle = current.isIdle() === true;
+    } catch {
+      idle = false;
+    }
+    if (meta && typeof meta === "object" && has(pi.sendMessage)) {
+      try {
+        pi.sendMessage(
+          {
+            customType: ASSIGN_MESSAGE_TYPE,
+            content,
+            display: true,
+            details: {
+              role: meta.role ?? null,
+              taskId: meta.taskId ?? null,
+              kind: meta.kind ?? "task",
+              from: meta.from ?? null,
+              envelopeId: meta.envelopeId ?? null,
+              bodyText: meta.bodyText ?? text,
+            },
+          },
+          idle ? { triggerTurn: true } : { deliverAs: "followUp" },
+        );
+        return true;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`sendMessage refused: ${message}; the delivery takes the user-message route`);
+      }
+    }
+    try {
+      if (idle) {
+        pi.sendUserMessage(content);
+      } else {
+        pi.sendUserMessage(content, { deliverAs: "followUp" });
+      }
       return true;
     } catch (error) {
       try {

package/src/pi-surface.test.mjs

@@ -16,6 +16,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
+import { ASSIGN_MESSAGE_TYPE } from "./activity.mjs";
 import { PROSE_SECTION, createSurface } from "./pi-surface.mjs";
 
 /**
@@ -40,7 +41,7 @@ const PNG_CONTENT = [
  * know an option does.
  * @param {{ refuse?: (content: unknown, options: unknown) => boolean }} [options]
  */
-function fakeSurface({ refuse = null } = {}) {
+function fakeSurface({ refuse = null, ctx = null } = {}) {
   const calls = [];
   const messages = [];
   const lines = [];
@@ -50,14 +51,12 @@ function fakeSurface({ refuse = null } = {}) {
         calls.push({ content, options });
         if (refuse?.(content, options)) throw new Error("this pi does not take that option");
       },
-      // Recorded, never expected: no part of this plugin is a conversation
-      // message any more, and the prose is the one that could creep back.
       sendMessage(message, options) {
         messages.push({ message, options });
       },
     },
     log: (line) => lines.push(line),
-    context: () => null,
+    context: () => ctx,
   });
   return { calls, messages, lines, surface };
 }
@@ -128,6 +127,81 @@ test("delivery asks for followUp and a refusal of that option retries with the s
   assert.deepEqual(refusing.lines, [], "a delivery that landed on the retry is not a failure");
 });
 
+test("a card delivery is one message: it starts the idle turn and queues while busy", () => {
+  // One delivery, one message. omp's rule for a custom message decides the
+  // option: with no `deliverAs` a `display: true` message renders without
+  // starting a turn, `triggerTurn` starts one when the session is idle, and
+  // `deliverAs: "followUp"` only queues behind a running turn.
+  const turns = [];
+  const queued = [];
+  const userMessages = [];
+  const cards = [];
+  let idle = true;
+  const surface = createSurface({
+    pi: {
+      sendMessage(message, options) {
+        cards.push({ message, options });
+        if (options?.triggerTurn === true && idle) {
+          turns.push(message.content);
+          return;
+        }
+        if (options?.deliverAs === "followUp") queued.push(message.content);
+      },
+      sendUserMessage(content, options) {
+        userMessages.push({ content, options });
+      },
+    },
+    log: () => {},
+    context: () => ({ isIdle: () => idle }),
+  });
+
+  const meta = {
+    role: "caerulea",
+    taskId: "97971b93-0000-4000-8000-000000000000",
+    kind: "note",
+    from: "role:_supervisor",
+    envelopeId: "env-1",
+    bodyText: "ping from supervisor",
+  };
+  const text = "From _supervisor:\n\nping from supervisor";
+  assert.equal(surface.wakeUser(text, [], meta), true);
+  assert.equal(cards.length, 1);
+  assert.equal(cards[0].message.customType, ASSIGN_MESSAGE_TYPE);
+  assert.equal(cards[0].message.display, true);
+  assert.equal(cards[0].message.details.kind, "note");
+  assert.equal(cards[0].message.details.from, "role:_supervisor");
+  assert.deepEqual(cards[0].options, { triggerTurn: true });
+  assert.deepEqual(turns, [text], "an idle session starts its turn from the card");
+  assert.deepEqual(userMessages, [], "the delivery is one message, never a card plus a prompt");
+
+  // While busy (`isIdle() === false`), the next card queues as followUp instead
+  // of interrupting the running turn.
+  idle = false;
+  const second = "From _supervisor:\n\nsecond note while busy";
+  assert.equal(surface.wakeUser(second, [], meta), true);
+  assert.equal(cards.length, 2);
+  assert.deepEqual(cards[1].options, { deliverAs: "followUp" });
+  assert.deepEqual(queued, [second]);
+  assert.deepEqual(turns, [text], "a busy session queues rather than starting a second turn");
+  assert.deepEqual(userMessages, []);
+});
+
+test("a pi without sendMessage takes the delivery as a plain user message", () => {
+  const calls = [];
+  const surface = createSurface({
+    pi: {
+      sendUserMessage(content, options) {
+        calls.push({ content, options });
+      },
+    },
+    log: () => {},
+    context: () => ({ isIdle: () => true }),
+  });
+
+  assert.equal(surface.wakeUser(TASK_TEXT, [], { kind: "note" }), true);
+  assert.deepEqual(calls, [{ content: TASK_TEXT, options: undefined }]);
+});
+
 /** One role prose, in the shape the client renders and `agent.mjs` hands over. */
 const PROSE_TEXT = "Read the incoming task.\n\nAnswer in the house style.\n";
 

package/src/session-scope.mjs

@@ -0,0 +1,90 @@
+// One question, asked twice: is the session in front of us the one the client
+// spawned this process for?
+//
+// A pi process runs more than one session. The client spawns pi with
+// `--session-id <the delivery's session>` and injects `ONLYNE_*` into the
+// process environment, and pi then runs other sessions inside that same process
+// with the same environment: a `task` subagent's sidechain
+// (`@tintinweb/pi-subagents` re-binds every extension for the child,
+// `session.bindExtensions`), and `/new`. Each of those loads this extension and
+// sees the parent's `ONLYNE_SESSION_ID`, so a rule that read the environment
+// alone would mount a second connection for the parent's session and let a
+// subagent's `onlyne_complete` settle the parent's task — which is exactly what
+// happened live (librarian task cfa73386, 2026-08-11: a writer subagent settled
+// its parent at 05:15:47 while the parent kept writing).
+//
+// So the rule is the session's own id, read off the pid pi gave the handler, and
+// the environment is only the expectation it is measured against. The two
+// readings are separate on purpose: `mountsSession` is the door (does this
+// session get a connection and the tools at all), `ownsSession` is the guard
+// behind it (may this caller's tool call move the task), and a pi that cannot
+// report a session id at all is the one case where both answer yes — refusing
+// every call on an older pi would break the ordinary session to prevent nothing,
+// because the env-bound mount is still the only one that connected.
+
+/**
+ * The id of the session a pi extension context belongs to.
+ *
+ * `null` means this pi cannot tell — no `sessionManager`, or one without
+ * `getSessionId` — which is the honest reading of an unknown, and both rules
+ * below treat it as "allowed" for the reason in the header.
+ *
+ * @param {{ getSessionId?: () => unknown } | null | undefined} sessionManager
+ * @returns {string | null}
+ */
+export function sessionIdOf(sessionManager) {
+  try {
+    const id = sessionManager?.getSessionId?.();
+    return typeof id === "string" && id.length > 0 ? id : null;
+  } catch {
+    // A context that throws is a context this plugin cannot read; the caller
+    // gets the same answer as one that is absent.
+    return null;
+  }
+}
+
+/**
+ * Whether the session pi is starting is the one the client spawned this process
+ * for, and therefore whether it may mount.
+ *
+ * @param {string} identitySessionId `ONLYNE_SESSION_ID`, the client's own word
+ * @param {string | null} startingSessionId the session's own id, or `null`
+ * @returns {boolean}
+ */
+export function mountsSession(identitySessionId, startingSessionId) {
+  return startingSessionId === null || startingSessionId === identitySessionId;
+}
+
+/**
+ * Whether a call comes from the session that mounted this plugin.
+ *
+ * The guard behind the tools and the `/onlyne` command: a sidechain that reached
+ * a tool through its parent's registration must not settle the parent's task,
+ * and the sentence it earns says so rather than reporting an outcome nobody
+ * asked this session for.
+ *
+ * @param {string | null} boundSessionId the session that mounted, or `null`
+ *   before one has
+ * @param {string | null} callingSessionId the session the call came from
+ * @returns {boolean}
+ */
+export function ownsSession(boundSessionId, callingSessionId) {
+  if (callingSessionId === null) return true;
+  return boundSessionId !== null && callingSessionId === boundSessionId;
+}
+
+/**
+ * The one sentence a call from a foreign session earns, for a tool error and for
+ * a command notice alike.
+ *
+ * @param {string | null} boundSessionId
+ * @param {string | null} callingSessionId
+ * @returns {string}
+ */
+export function foreignSessionRefusal(boundSessionId, callingSessionId) {
+  return (
+    `onlyne: session ${callingSessionId} did not mount these tools; they belong to onlyne ` +
+    `session ${boundSessionId}, and a subagent or another session in the same pi process ` +
+    `must not settle this task`
+  );
+}