pi-onlyne 2.2.0 → 2.4.0

package/src/index.ts

@@ -8,7 +8,12 @@
 // a plain pi session and the extension stays silent rather than failing.
 //
 //   session_start      -> bind the env session id, read env + .pi/onlyne.json,
-//                         connect, register tools
+//                         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}
@@ -35,15 +40,33 @@
 // 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.
-
+//
+// One process also holds at most one resident claim. A resident pi is started
+// by hand rather than spawned by the client, so a `task` subagent's sidechain
+// inherits nothing that names a task and reaches the resident branch through a
+// second call of this factory with fresh closure state; the claim is what stops
+// it from opening a connection that impersonates the parent's resident alias
+// (`docs/v2.11-LIFECYCLE-IS-DECLARED-NOT-INFERRED.md` §4.2). Where the host
+// itself declares what the session is — omp marks every subagent context
+// `agent.kind === "sub"` — that declaration decides first, on both identity
+// paths, and the claim is the reading left for a host that declares nothing.
+//
 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";
+import {
+  declaredSubagent,
+  foreignSessionRefusal,
+  isSessionReplacement,
+  mountsSession,
+  ownsSession,
+  sessionIdOf,
+} from "./session-scope.mjs";
 
 /**
  * Node's process globals, declared here so the package needs no `@types/node`
@@ -82,11 +105,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;
+  applyRoleProse(event: { systemPromptOptions?: { sections?: Record<string, string> } }, fallback?: 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;
@@ -140,6 +163,18 @@ const textResult = (text: string, details?: unknown) => ({
   details,
 });
 
+/**
+ * The session this process has already taken as its resident, or `null` while
+ * no resident mount holds it.
+ *
+ * Module scope is the point: pi hosts a `task` subagent's sidechain in the same
+ * process by loading this extension again, so a guard that read the factory's
+ * own `boundSessionId` compared `null` against a name and let the child open a
+ * connection for the parent's resident alias
+ * (`docs/v2.11-LIFECYCLE-IS-DECLARED-NOT-INFERRED.md` §4.2).
+ */
+let residentClaim: string | null = null;
+
 export default function onlyne(pi: ExtensionAPI) {
   const env: Record<string, string | undefined> = typeof process === "undefined" ? {} : process.env;
   let context: ExtensionContext | null = null;
@@ -173,6 +208,16 @@ export default function onlyne(pi: ExtensionAPI) {
   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",
@@ -329,9 +374,68 @@ export default function onlyne(pi: ExtensionAPI) {
     }
   };
 
-  pi.on("session_start", async (_event, ctx) => {
-    const identity = sessionIdentity(env);
+  /**
+   * 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;
+    // The same declaration the mount gate reads, on the other door: a context
+    // the host declares a subagent must not re-point this plugin's connection
+    // onto a child, whatever session id it carries.
+    if (declaredSubagent(ctx)) return;
+    context = ctx;
+    const currentId = sessionIdOf(ctx?.sessionManager);
+    if (currentId) {
+      // `/new`, `/resume` and a tree jump replace the live session inside this
+      // process rather than starting a second resident, so the claim moves with
+      // it — but only the mount that holds the claim may move it. A factory that
+      // never mounted returned above, and one whose mount is not the claim
+      // holder leaves the claim where it is. The comparison reads the session
+      // this mount held until now, so it goes before the rebind.
+      if (boundSessionId === residentClaim) residentClaim = currentId;
+      boundSessionId = currentId;
+    }
+    if (surface?.available.widget) {
+      surface.widget(agent.activity.lines(), agent.activity);
+    }
+    surface?.status(agent.activity.lines()[0]);
+    // A surface that was replaced starts with no prose of its own, and the run
+    // after a switch still owes the model the role spec: the agent remembers
+    // what the last welcome carried and hands it over here.
+    agent.syncRoleProse();
+  }
+
+  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
+    const starting = sessionIdOf(ctx.sessionManager);
+    // The host's own declaration comes first, before either identity path: a
+    // session it declares a subagent — a `task` subagent, an `eval` child, a
+    // `/tan` clone, all re-bound through this factory in this process — is never
+    // the session a role's tools belong to, even when it inherits the client's
+    // environment or arrives with no session id at all
+    // (docs/v2.11-LIFECYCLE-IS-DECLARED-NOT-INFERRED.md §2 rule 2).
+    const subagent = declaredSubagent(ctx);
+    if (subagent) {
+      log(
+        `session ${starting} is subagent ${subagent.id ?? "?"} of ${subagent.parentId ?? "?"}; staying inert`
+      );
+      return;
+    }
+    // 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. A subagent on a host that declares no agent identity re-binds
+    // with reason "startup" and a different id, and is refused below.
+    if (!spawned && agent !== null && (event.reason !== "startup" || starting === boundSessionId)) {
+      syncSessionContext(event, ctx);
+      return;
+    }
     // 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
@@ -339,13 +443,34 @@ export default function onlyne(pi: ExtensionAPI) {
     // 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);
-    if (!mountsSession(identity.sessionId, starting)) {
-      log(`session ${starting} is not the onlyne session ${identity.sessionId}; staying inert`);
-      return;
+    if (spawned) {
+      if (!mountsSession(spawned.sessionId, starting)) {
+        log(`session ${starting} is not the onlyne session ${spawned.sessionId}; staying inert`);
+        return;
+      }
+    } else {
+      // The claim is process-wide, so it holds across factory calls: a `task`
+      // subagent's sidechain loads this extension again with fresh closure state
+      // and would otherwise mount the alias this process already serves. A
+      // `session_start` the host calls a replacement is the other reading: the
+      // live session is moving inside this process, so the claim moves with it
+      // instead of refusing the session that is now the resident. An older pi
+      // that names no session id is the one case with nothing to compare — it
+      // mounts as it did before, and claims nothing.
+      if (
+        residentClaim !== null &&
+        starting !== null &&
+        starting !== residentClaim &&
+        !isSessionReplacement(event)
+      ) {
+        log(`session ${starting} is not the resident session ${residentClaim}; staying inert`);
+        return;
+      }
+      if (starting !== null) residentClaim = starting;
     }
+    const wireSessionId = identity.sessionId ?? starting;
     context = ctx;
-    boundSessionId = identity.sessionId;
+    boundSessionId = spawned ? spawned.sessionId : (starting ?? wireSessionId);
     const config = loadConfig(ctx.cwd);
     if (config.warning) log(config.warning);
     if (!config.enabled) {
@@ -357,23 +482,36 @@ 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;
+    const declaredCluster = resident ? resident.cluster : null;
     try {
-      socketPath = resolveSocketPath(env, ctx.cwd);
+      socketPath = resident
+        ? resolveResidentSocketPath(env, targetWorkspace, identity.role, { cluster: declaredCluster })
+        : 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 });
+    // The prose a mount of this process already holds: the agent is replaced
+    // below, and the surface made now starts empty, so what the last welcome
+    // carried moves with it rather than being lost until the next handshake.
+    const carriedProse = agent?.latestProse ?? "";
+    surface = createSurface({ pi, log, context: () => context, sessionId: () => boundSessionId });
     agent = new OnlyneAgent({
       socketPath,
+      resolveSocket: resident
+        ? () => resolveResidentSocketPath(env, targetWorkspace, identity.role, { cluster: declaredCluster })
+        : undefined,
       cwd: ctx.cwd,
       role: identity.role,
-      sessionId: identity.sessionId,
+      sessionId: wireSessionId,
       taskId: identity.taskId,
+      resident: Boolean(resident),
       surface,
       log,
+      prose: carriedProse,
     });
-    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,
@@ -384,13 +522,28 @@ 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
   // 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);
+    // A surface created after the handshake holds no prose; the agent's copy of
+    // the last welcome is what the run that is starting carries instead of
+    // running without the role spec until the next connection.
+    surface?.applyRoleProse(event, agent?.latestProse ?? "");
   });
 
   pi.on("turn_start", async () => {
@@ -420,6 +573,10 @@ export default function onlyne(pi: ExtensionAPI) {
     agent?.stop(`pi:${event.reason ?? "quit"}`);
     surface?.closeBackground?.();
     surface?.widget?.(undefined);
+    // Only the mount holding the claim may release it: a child factory that
+    // never mounted has no `boundSessionId` of its own, and its shutdown must
+    // leave the resident's claim where it is.
+    if (boundSessionId !== null && boundSessionId === residentClaim) residentClaim = null;
     agent = null;
     surface = null;
     registered = false;

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 {
+      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 {
-      pi.sendUserMessage(content, { deliverAs: "followUp" });
+      if (idle) {
+        pi.sendUserMessage(content);
+      } else {
+        pi.sendUserMessage(content, { deliverAs: "followUp" });
+      }
       return true;
     } catch (error) {
       try {
@@ -180,7 +241,9 @@ export function createSurface({ pi, log, context, sessionId = null }) {
   let warnedNoSections = false;
 
   /**
-   * Hand the role prose over once.
+   * Take the role prose this surface is to carry: handed over with the
+   * handshake, and again whenever a surface that holds none has to be filled
+   * for the run that is starting.
    * @param {string} text
    * @returns {boolean} whether there is prose to carry
    */
@@ -198,10 +261,17 @@ export function createSurface({ pi, log, context, sessionId = null }) {
    * pi's own examples does this). pi rebuilds those options for every run, so the
    * section is written again rather than once — the write is idempotent, and the
    * first run records it in the transcript's system message.
+   *
+   * `fallback` is the prose this surface was never handed: a surface made after
+   * the handshake (a session switch re-binds the plugin onto one) starts empty,
+   * and the run that is starting still owes the model the role spec, so the
+   * caller passes what the agent remembers of the last welcome.
    * @param {{ systemPromptOptions?: { sections?: Record<string, string> } } | null} event
+   * @param {string} [fallback]
    * @returns {boolean} whether a section was written
    */
-  const applyRoleProse = (event) => {
+  const applyRoleProse = (event, fallback = "") => {
+    if (roleProseText.length === 0 && typeof fallback === "string") roleProseText = fallback;
     if (roleProseText.length === 0) return false;
     const sections = event?.systemPromptOptions?.sections;
     if (!sections) {

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";
 
@@ -186,6 +260,30 @@ test("a pi whose prompt options carry no sections reports it once and carries no
   assert.match(lines[0], /no instruction layer/);
 });
 
+test("a surface made after the handshake adopts the prose the agent remembers", () => {
+  const { surface } = fakeSurface();
+
+  // No `roleProse` call ever reached this surface — it was created after the
+  // welcome, by a session switch or a resumed mount — and the run that is
+  // starting is still owed the role spec.
+  const first = promptEvent();
+  assert.equal(surface.applyRoleProse(first, PROSE_TEXT), true);
+  assert.deepEqual(first.systemPromptOptions.sections, { [PROSE_SECTION]: PROSE_TEXT });
+
+  // The adopted text is the surface's own from then on: the next run carries it
+  // without the caller passing it again.
+  const second = promptEvent();
+  assert.equal(surface.applyRoleProse(second), true);
+  assert.deepEqual(second.systemPromptOptions.sections, { [PROSE_SECTION]: PROSE_TEXT });
+
+  // A fallback fills an empty surface only; prose the surface already holds is
+  // newer than what the agent last saw.
+  surface.roleProse("Answer in the log style.");
+  const third = promptEvent();
+  surface.applyRoleProse(third, PROSE_TEXT);
+  assert.deepEqual(third.systemPromptOptions.sections, { [PROSE_SECTION]: "Answer in the log style." });
+});
+
 /**
  * A surface over a fake pi that answers the two questions the phase is read
  * from, plus the cases where pi answers neither.