pi-onlyne 2.3.0 → 2.4.0

package/README.md

@@ -121,6 +121,9 @@ pi --session-id <id> -e /abs/path/to/plugins/onlyne-agent-pi -ns -nc
 | --- | --- | --- |
 | `enabled` | `true` | `false` turns the extension off for this workspace |
 | `watch.autoStart` | `true` | `false` registers the tools but opens no socket until `/onlyne connect` |
+| `role` | — | the role this session serves when the client injected no `ONLYNE_ROLE`; also what makes the file a resident opt-in |
+| `workspace` | — | the role workspace, when the session did not start inside it; a relative path resolves against the pi working directory |
+| `cluster` | — | the cluster whose client this session dials — the serving server's `[server] name`; unset means the tree decides |
 
 A missing file means every default. A malformed file prints one warning on stderr and
 keeps the defaults: a typo must not silently disable a role. The client does not read
@@ -128,6 +131,13 @@ this file (§11 of the plan downgraded the old readiness gates to generate-time
 advice), so only this extension consumes it; the key shape stays the one the templates
 carry.
 
+`cluster` is the answer for a session whose body runs in one cluster's tree while the
+role workspace belongs to another: with the key set, the client registered for this role
+in that cluster is dialed first, whatever tree the session runs in. A cluster holding two
+clients of the role is refused by name rather than picked from. With the key absent — or
+naming a cluster no client has registered — resolution falls back to the tree, exactly as
+it did before the key existed.
+
 Nothing else is needed. The workspace's `session_command` in `spec.toml` already spawns
 `pi` per task (`["pi", "--session-id", "{session}"]`), and the client injects the
 environment this extension keys on.

package/README.zh.md

@@ -112,6 +112,8 @@ pi --session-id <id> -e /abs/path/to/plugins/onlyne-agent-pi -ns -nc
 | --- | --- | --- |
 | `enabled` | `true` | `false` 时该工作区禁用扩展 |
 | `watch.autoStart` | `true` | `false` 时注册工具但不建连接，需 `/onlyne connect` |
+| `workspace` | — | 角色工作区路径（当会话未在其中启动时生效；相对路径相对 pi 工作目录解析） |
+| `cluster` | — | 本会话要连接的集群名（对应服务端的 `[server] name`；未设时由工作区目录树决定） |
 
 文件缺失即取各自默认值。文件格式错误时打印一行警告，并保留默认值：一个笔误不该静默关掉一个
 role。client 不读这个文件（计划 §11 已把旧 readiness 门降级为 generate 期模板提示），所以
@@ -120,6 +122,11 @@ role。client 不读这个文件（计划 §11 已把旧 readiness 门降级为
 其余无需配置。工作区 `spec.toml` 的 `session_command` 已经按任务拉起 `pi`
 （`["pi", "--session-id", "{session}"]`），client 负责注入本扩展识别的环境变量。
 
+`cluster` 专门解决“会话主体在一个集群的目录树下运行、但挂载的角色工作区属于另一个集群”的夹心代理场景：
+配置该键后，无论会话当前处于哪棵目录树下，都会优先连接该集群中为该角色注册的客户端。若同一集群内存在
+两个同名角色客户端，会直接显式报错拒绝，绝不随意选取。若未配置该键（或指定的集群未发现注册客户端），
+则优雅回退至原有的工作区目录树收敛规则。
+
 ## 2. 能力表
 
 `hello` 只声明真实实现的能力：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-onlyne",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Onlyne agent adapter for pi: the session lifecycle an onlyne role client expects from a pi host.",
   "type": "module",
   "license": "MIT",

package/src/agent.mjs

@@ -93,6 +93,7 @@ export class OnlyneAgent {
    *   helloTimeoutMs?: number,
    *   createConnection?: (path: string) => any,
    *   timer?: { set: (fn: () => void, ms: number) => any, clear: (handle: any) => void },
+   *   prose?: string,
    * }} options
    */
   constructor(options) {
@@ -171,6 +172,18 @@ export class OnlyneAgent {
      */
     this.injectedDeliveries = new Set();
     this.deliveredProse = new Set();
+    /**
+     * The newest role prose the client sent. `welcome` carries it and an
+     * `assign` names it again; it is kept here, not only in the surface,
+     * because a surface is replaced while this process keeps running — a
+     * `/new` or `/resume` re-binds the plugin onto a fresh one — and the prose
+     * is the role's instruction layer, not a message that could be replayed
+     * from the transcript.
+     */
+    this.latestProse = typeof options.prose === "string" ? options.prose : "";
+    // A surface handed over at construction is owed the prose this agent was
+    // started with: it holds none of its own yet.
+    if (this.latestProse) this.surface?.roleProse?.(this.latestProse);
     /** Pushes that arrived before the handshake finished; see `onFrame`. */
     this.handshaking = false;
     this.deferredPushes = [];
@@ -241,6 +254,21 @@ export class OnlyneAgent {
     };
   }
 
+  /**
+   * Hand the newest role prose to the current surface again.
+   *
+   * The surface keeps the prose for the instruction layer, and a surface made
+   * after the handshake — or after this process moved onto another session —
+   * starts with none of it. The delivery guard must not be the reason it stays
+   * empty, so whoever binds a surface calls this.
+   * @returns {boolean} whether there was prose to hand over
+   */
+  syncRoleProse() {
+    if (typeof this.latestProse !== "string" || this.latestProse.length === 0) return false;
+    this.surface?.roleProse?.(this.latestProse);
+    return true;
+  }
+
   // ------------------------------------------------------------- transport
 
   connect() {
@@ -387,8 +415,13 @@ export class OnlyneAgent {
     });
     this.notice("state", `connected role=${welcome.role} gen=${welcome.generation} host=${welcome.hostCapabilities.join(",")}`);
     const prose = welcome.prose.trim();
-    if (prose && !this.deliveredProse.has(prose)) {
+    if (prose) {
+      this.latestProse = prose;
       this.deliveredProse.add(prose);
+      // Every welcome hands the prose over, not only the first one. A
+      // reconnect, a `--resume` and a surface re-created in this process all
+      // start empty, and the prose is a system-prompt section rather than a
+      // message, so writing it again duplicates nothing in the transcript.
       this.surface.roleProse?.(prose);
     }
 
@@ -818,9 +851,10 @@ export class OnlyneAgent {
     const attachmentPaths = Array.isArray(args.attachments) ? args.attachments : [];
     const prose = typeof args.prose === "string" ? args.prose.trim() : "";
     const proseIsNew = prose.length > 0 && !this.deliveredProse.has(prose);
-    if (proseIsNew) {
+    if (prose.length > 0) {
+      this.latestProse = prose;
       this.deliveredProse.add(prose);
-      this.surface.roleProse?.(prose);
+      if (proseIsNew) this.surface.roleProse?.(prose);
     }
 
     const kind = envelope.kind ?? "task";

package/src/agent.test.mjs

@@ -1599,3 +1599,64 @@ test("a host without the widget keeps the footer line and the stderr line", asyn
   assert.ok(logs.some((line) => line.startsWith("in: task 11111111")), logs.join(" | "));
 });
 
+// The prose is a system-prompt section, not a message: rewriting it in a second
+// run duplicates nothing, so a reconnect hands it over again rather than
+// leaving the surface of a resumed session without the role spec.
+test("a reconnect hands the role prose to the surface again", async () => {
+  const { agent, host, surface } = await startAgent();
+  agent.start();
+  await waitFor(() => (host.of("report").length >= 1 ? true : null));
+  assert.deepEqual(surface.calls.prose, ["Read the incoming task"]);
+
+  const connections = host.connections;
+  agent.dropSocket();
+  await waitFor(() => (host.connections > connections ? true : null));
+  await waitFor(() => (surface.calls.prose.length === 2 ? true : null));
+  assert.deepEqual(surface.calls.prose, ["Read the incoming task", "Read the incoming task"]);
+  assert.equal(agent.latestProse, "Read the incoming task");
+});
+
+// A surface is replaced while the process keeps its session: the new one holds
+// no prose of its own, and what the last welcome carried is what fills it.
+test("a replaced surface is handed the prose the agent remembers", async () => {
+  const { agent, host } = await startAgent();
+  agent.start();
+  await waitFor(() => (host.of("report").length >= 1 ? true : null));
+
+  const replacement = fakeSurface();
+  agent.surface = replacement;
+  assert.equal(agent.syncRoleProse(), true);
+  assert.deepEqual(replacement.calls.prose, ["Read the incoming task"]);
+
+  // A surface a session switch never filled is still refilled before its first
+  // run, so an agent that remembers nothing yet answers without a throw.
+  const empty = new OnlyneAgent({
+    socketPath: join(tmpdir(), "pi-onlyne-unused-socket"),
+    cwd: tmpdir(),
+    role: "planner",
+    sessionId: SESSION_ID,
+    taskId: TASK_ID,
+    surface: fakeSurface(),
+  });
+  assert.equal(empty.syncRoleProse(), false);
+  assert.equal(empty.latestProse, "");
+});
+
+// The mount `index.ts` builds after a `/new` or a resumed session starts over
+// with a new surface, and the prose it was started with is what the new surface
+// carries from its first run.
+test("a mount built over a live session carries the prose into its surface", () => {
+  const surface = fakeSurface();
+  const agent = new OnlyneAgent({
+    socketPath: join(tmpdir(), "pi-onlyne-unused-socket"),
+    cwd: tmpdir(),
+    role: "planner",
+    sessionId: SESSION_ID,
+    taskId: TASK_ID,
+    surface,
+    prose: "Read the incoming task",
+  });
+  assert.deepEqual(surface.calls.prose, ["Read the incoming task"]);
+  assert.equal(agent.latestProse, "Read the incoming task");
+});
+

package/src/config.mjs

@@ -28,7 +28,7 @@ export const DEFAULT_CONFIG = Object.freeze({
  *
  * @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, role: string | null, sessionId: string | null, workspace: string | null, cluster: string | null, resident: boolean, path: string, warning: string | null, present: boolean }}
  */
 export function loadConfig(cwd, options = {}) {
   const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
@@ -42,6 +42,7 @@ export function loadConfig(cwd, options = {}) {
       role: null,
       sessionId: null,
       workspace: null,
+      cluster: null,
       resident: false,
       path,
       warning: null,
@@ -57,6 +58,7 @@ export function loadConfig(cwd, options = {}) {
       role: null,
       sessionId: null,
       workspace: null,
+      cluster: null,
       resident: false,
       path,
       warning: `${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}); using defaults`,
@@ -69,6 +71,7 @@ export function loadConfig(cwd, options = {}) {
       role: null,
       sessionId: null,
       workspace: null,
+      cluster: null,
       resident: false,
       path,
       warning: `${path} must hold a JSON object; using defaults`,
@@ -83,6 +86,7 @@ export function loadConfig(cwd, options = {}) {
     role: typeof parsed.role === "string" && parsed.role.trim() !== "" ? parsed.role.trim() : null,
     sessionId: typeof rawSessionId === "string" && rawSessionId.trim() !== "" ? rawSessionId.trim() : null,
     workspace: typeof parsed.workspace === "string" && parsed.workspace.trim() !== "" ? parsed.workspace.trim() : null,
+    cluster: typeof parsed.cluster === "string" && parsed.cluster.trim() !== "" ? parsed.cluster.trim() : null,
     resident: typeof parsed.resident === "boolean" ? parsed.resident : false,
     path,
     warning: null,
@@ -155,7 +159,7 @@ export function parseWorkspaceConfigToml(raw) {
  * @param {Record<string, string | undefined>} env
  * @param {string} cwd
  * @param {{ readFile?: (path: string) => string }} [options]
- * @returns {{ role: string, sessionId: string | null, taskId: string | null, resident: true, workspaceRoot: string } | null}
+ * @returns {{ role: string, sessionId: string | null, taskId: string | null, cluster: string | null, resident: true, workspaceRoot: string } | null}
  */
 export function residentIdentity(env, cwd, options = {}) {
   const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
@@ -241,6 +245,7 @@ export function residentIdentity(env, cwd, options = {}) {
     role,
     sessionId: envSessionId ?? config.sessionId ?? toml.sessionId ?? null,
     taskId: envTaskId,
+    cluster: config.cluster,
     resident: true,
     workspaceRoot,
   };

package/src/config.test.mjs

@@ -96,6 +96,7 @@ test("residentIdentity resolves pre-started sessions from env, .pi/onlyne.json,
     role: "supervisor",
     sessionId: null,
     taskId: null,
+    cluster: null,
     resident: true,
     workspaceRoot: dir,
   });
@@ -110,6 +111,27 @@ test("residentIdentity resolves pre-started sessions from env, .pi/onlyne.json,
     role: "planner",
     sessionId: "planner-main",
     taskId: null,
+    cluster: null,
+    resident: true,
+    workspaceRoot: dir,
+  });
+});
+
+test("the switch file's cluster is trimmed, optional, and reaches residentIdentity", () => {
+  const dir = workspace(JSON.stringify({ role: "lazuli", cluster: "  workshop " }));
+  assert.equal(loadConfig(dir).cluster, "workshop");
+
+  // Absent, blank and non-string all mean no declaration, never a guess.
+  for (const body of [{ role: "lazuli" }, { role: "lazuli", cluster: "" }, { role: "lazuli", cluster: 42 }]) {
+    assert.equal(loadConfig(workspace(JSON.stringify(body))).cluster, null);
+  }
+
+  // The identity carries the declaration so the resolver can pass it through.
+  assert.deepEqual(residentIdentity({}, dir), {
+    role: "lazuli",
+    sessionId: null,
+    taskId: null,
+    cluster: "workshop",
     resident: true,
     workspaceRoot: dir,
   });

package/src/index.ts

@@ -40,7 +40,17 @@
 // 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";
 
@@ -49,7 +59,14 @@ import { ASSIGN_MESSAGE_TYPE, createAssignMessageComponent } from "./activity.mj
 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`
@@ -90,7 +107,7 @@ interface PiSurface {
   };
   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, activity?: unknown): void;
   status(text: string): void;
@@ -146,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;
@@ -353,47 +382,91 @@ export default function onlyne(pi: ExtensionAPI) {
    */
   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
-    // 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);
+    // 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. The sidechain a `task` subagent runs re-binds every extension
-    // with reason "startup" and a different id, and stays inert.
+    // 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
+    // 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.
     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;
+    } 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;
@@ -410,19 +483,24 @@ export default function onlyne(pi: ExtensionAPI) {
     // 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 = resident
-        ? resolveResidentSocketPath(env, targetWorkspace, identity.role)
+        ? 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;
+    // 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)
+        ? () => resolveResidentSocketPath(env, targetWorkspace, identity.role, { cluster: declaredCluster })
         : undefined,
       cwd: ctx.cwd,
       role: identity.role,
@@ -431,6 +509,7 @@ export default function onlyne(pi: ExtensionAPI) {
       resident: Boolean(resident),
       surface,
       log,
+      prose: carriedProse,
     });
     log(`session ${wireSessionId ?? "resident"} role=${identity.role} socket=${socketPath}`);
     registerSurface();
@@ -461,7 +540,10 @@ export default function onlyne(pi: ExtensionAPI) {
   // 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 () => {
@@ -491,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

@@ -241,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
    */
@@ -259,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

@@ -260,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.