pi-onlyne 2.2.0 → 2.4.0

package/src/agent.mjs

@@ -57,8 +57,23 @@ export const HELLO_TIMEOUT_MS = 5_000;
 /** Default bound on one request round trip. */
 export const REQUEST_TIMEOUT_MS = 30_000;
 
-/** Capabilities this plugin implements on the wire. */
-export const CAPABILITIES = ["register", "report", "inject", "recycle"];
+/**
+ * Capabilities this plugin implements on the wire.
+ *
+ * `resume` is the one that changes what a `task` scope does with this runtime.
+ * Pi keeps its conversation in its own store (`--session-dir`), so a session the
+ * client releases is one it can bring back by starting the role's `resume` argv
+ * — `pi --session <id>` — over the same store. Without the declaration the
+ * client keeps the process instead and the scope degrades to "process alive,
+ * session alive"; with it, an idle `task` session has its process released and
+ * the family's next delivery lands in the same conversation.
+ *
+ * The release is this plugin's own exit, not a kill: `onRecycle` stops and calls
+ * `exitSession`, and pi flushes its session file at `agent_settled`. The client
+ * asks first and closes the container only after a grace, which is what makes
+ * the ordering safe (`AGENTS.md` §10).
+ */
+export const CAPABILITIES = ["register", "report", "inject", "recycle", "resume"];
 
 export class OnlyneAgent {
   /**
@@ -78,14 +93,17 @@ 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) {
     this.socketPath = options.socketPath;
+    this.resolveSocket = typeof options.resolveSocket === "function" ? options.resolveSocket : null;
     this.cwd = options.cwd;
     this.role = options.role;
     this.sessionId = options.sessionId;
     this.envTaskId = options.taskId;
+    this.resident = Boolean(options.resident);
     this.surface = options.surface;
     /** The widget panel's model (`activity.mjs`); seeded with the local role. */
     this.activity = options.activity ?? createActivity();
@@ -154,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 = [];
@@ -224,10 +254,35 @@ 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() {
     if (this.closed || this.socket) return;
+    if (this.resolveSocket) {
+      try {
+        const refreshed = this.resolveSocket();
+        if (typeof refreshed === "string" && refreshed.length > 0) {
+          this.socketPath = refreshed;
+        }
+      } catch {
+        /* keep previous socketPath */
+      }
+    }
     let socket;
     try {
       socket = this.createConnection(this.socketPath);
@@ -271,6 +326,7 @@ export class OnlyneAgent {
   /** Tear the current socket down and schedule the next attempt. */
   dropSocket() {
     const socket = this.socket;
+    const wasConnected = this.connected;
     this.socket = null;
     this.connected = false;
     this.handshaking = false;
@@ -278,7 +334,13 @@ export class OnlyneAgent {
     this.rejectAll("connection lost");
     this.stopHeartbeat();
     this.activity.set({ connection: this.closed ? "detached" : "reconnecting" });
-    this.notice("state", this.closed ? "detached" : "reconnecting");
+    if (!this.closed && (!this.resident || wasConnected)) {
+      this.notice("state", "reconnecting");
+    } else if (this.closed) {
+      this.notice("state", "detached");
+    } else {
+      this.redraw();
+    }
     if (socket && !socket.destroyed) socket.destroy();
     this.scheduleReconnect();
   }
@@ -321,6 +383,11 @@ export class OnlyneAgent {
     }
     this.welcome = welcome;
     this.connected = true;
+    const hadConnectFailure = this.lastError !== null;
+    this.lastError = null;
+    if (this.resident && hadConnectFailure) {
+      this.log(`connected role=${welcome.role} session=${this.sessionId ?? "resident"} socket=${this.socketPath}`);
+    }
     // The client names every delivery it already handed to this session, so a
     // process that restarts under a live client does not re-inject work its
     // predecessor read: the delivery guard is process memory, and this is how it
@@ -348,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);
     }
 
@@ -467,7 +539,15 @@ export class OnlyneAgent {
   }
 
   noteFailure(error) {
+    const prevCode = this.lastError?.code ?? null;
     this.lastError = error;
+    if (
+      this.resident &&
+      (error?.code === "ENOENT" || error?.code === "ECONNREFUSED") &&
+      prevCode === error.code
+    ) {
+      return;
+    }
     this.log(`socket error: ${error?.message ?? error}`);
   }
 
@@ -479,14 +559,20 @@ export class OnlyneAgent {
    * @param {"in" | "dup" | "out" | "warn" | "state"} kind
    * @param {string} text
    */
+  redraw() {
+    this.surface.status?.(this.activity.lines()[0]);
+    if (this.surface.available?.widget) {
+      this.surface.widget?.(this.activity.lines(), this.activity);
+    }
+  }
+
   notice(kind, text) {
     this.activity.note(kind, text);
+    this.redraw();
     if (this.surface.available?.widget) {
-      this.surface.widget?.(this.activity.lines());
       return;
     }
-    // No panel: the footer carries the steady header line, stderr the event.
-    this.surface.status?.(this.activity.lines()[0]);
+    // No panel: stderr carries the event.
     this.log(`${kind}: ${text}`);
   }
 
@@ -730,11 +816,14 @@ export class OnlyneAgent {
    * that is what every such frame meant.
    */
   keepsSession() {
-    return this.scope === "task" || this.scope === "role";
+    return this.resident || this.scope === "task" || this.scope === "role";
   }
 
   async onAssign(args) {
     if (typeof args.scope === "string" && args.scope) this.scope = args.scope;
+    if (this.resident && typeof args.session_id === "string" && args.session_id) {
+      this.sessionId = args.session_id;
+    }
     const envelope = args.envelope ?? {};
     const taskId = args.task_id ?? envelope.causality?.task ?? null;
     if (!taskId) {
@@ -762,12 +851,42 @@ 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";
     const held = this.tasks.get(taskId);
+    const fromLabel = describePrincipal(envelope.from);
+    const wakeMeta = {
+      role: this.role,
+      taskId,
+      kind,
+      from: fromLabel,
+      envelopeId: envelope.id ?? null,
+      bodyText: envelope.body?.text ?? text,
+    };
+    // A note is a message, not work: it is injected and acknowledged, and it
+    // opens no task record, so nothing beats for it, no turn end owes it an
+    // outcome and `onlyne_complete` is never required of it. A note naming a
+    // task this session is still working on lands mid-task, below.
+    if (kind === "note" && (!held || held.completed)) {
+      if (this.tasks.size > 0) this.agentState = "running";
+      this.surface.wakeUser?.(text, this.imageParts(envelope), wakeMeta);
+      this.surface.customEntry?.("onlyne-assign", {
+        taskId,
+        envelopeId: envelope.id ?? null,
+        kind: "note",
+        proseInjected: proseIsNew,
+        prose,
+        attachments: attachmentPaths,
+      });
+      this.notice("in", `note ${taskId.slice(0, 8)} from ${fromLabel}: ${headOf(envelope.body?.text)}`);
+      await this.ack(taskId, true, null);
+      return;
+    }
     // A completed record is not a live one: a new envelope for a task that
     // already settled is fresh work under an old id, so it gets a fresh record.
     if (held && !held.completed) {
@@ -800,17 +919,17 @@ export class OnlyneAgent {
       });
     }
     this.agentState = "running";
-    this.surface.wakeUser?.(text, this.imageParts(envelope));
+    this.surface.wakeUser?.(text, this.imageParts(envelope), wakeMeta);
     this.surface.customEntry?.("onlyne-assign", {
       taskId,
       envelopeId: envelope.id ?? null,
-      kind: envelope.kind ?? "task",
+      kind,
       proseInjected: proseIsNew,
       prose,
       attachments: attachmentPaths,
     });
     this.activity.set({ taskId, phase: "running" });
-    this.notice("in", `task ${taskId.slice(0, 8)} from ${describePrincipal(envelope.from)} (${envelope.kind ?? "task"}): ${headOf(envelope.body?.text)}`);
+    this.notice("in", `task ${taskId.slice(0, 8)} from ${fromLabel} (${kind}): ${headOf(envelope.body?.text)}`);
     this.startHeartbeat();
     await this.ack(taskId, true, null);
   }
@@ -843,7 +962,13 @@ export class OnlyneAgent {
   onNudge(frame, args) {
     const text = typeof args.text === "string" ? args.text : "";
     const taskId = typeof args.task_id === "string" && args.task_id ? args.task_id.slice(0, 8) : "?";
-    const handedOver = text.length > 0 && this.surface.wakeUser?.(text, []) === true;
+    const handedOver = text.length > 0 && this.surface.wakeUser?.(text, [], {
+      role: this.role,
+      taskId: args.task_id ?? null,
+      kind: "nudge",
+      from: "host",
+      bodyText: text,
+    }) === true;
     if (handedOver) this.notice("in", `nudge for task ${taskId}`);
     else this.notice("warn", `nudge for task ${taskId} was not handed to the model`);
     if (frame?.id === undefined || frame?.id === null) return;

package/src/agent.test.mjs

@@ -490,7 +490,7 @@ test("a fresh agent opens with hello, registers and reports ready", async () =>
     plugin: "pi-onlyne",
     version: PACKAGE_VERSION,
     kind: "agent",
-    capabilities: ["register", "report", "inject", "recycle"],
+    capabilities: ["register", "report", "inject", "recycle", "resume"],
     mount: { role: "planner", session: SESSION_ID, task_id: TASK_ID, pid: process.pid },
   });
 
@@ -540,6 +540,27 @@ test("an assign is injected once, acked, and a redelivery changes nothing", asyn
   assert.deepEqual(second[1], { task_id: TASK_ID, accepted: true, reason: "duplicate" });
 });
 
+// A note is communication, not work: the session is woken and the delivery is
+// acknowledged, and no task record opens, so nothing beats for it and no turn
+// end can demand a completion.
+test("a note is injected, acked, and opens no task", async () => {
+  const { agent, host, surface } = await startAgent();
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  const args = structuredClone(assignArgs());
+  args.envelope.kind = "note";
+  args.text = "From planner:\n\nwhich way is the flag?";
+  host.notify("assign", args);
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  assert.equal(surface.calls.wakeUser[0].text, args.text, "the frame's text is injected unchanged");
+  assert.equal(surface.calls.entries[0].data.kind, "note");
+  const acks = await waitFor(() => (host.of("assign_ack").length >= 1 ? host.of("assign_ack") : null));
+  assert.deepEqual(acks[0], { task_id: TASK_ID, accepted: true });
+  assert.deepEqual(agent.status().tasks, []);
+});
+
 // A follow-up arrives as its own envelope under the task id the session is
 // already running. Keying the injection guard on the task swallowed it: the
 // panel said `already injected`, nothing reached the model, and the row the
@@ -1578,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

@@ -9,11 +9,14 @@
 // deliberate off switch.
 
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 
 /** Where the switch file lives, relative to the pi working directory. */
 export const CONFIG_RELATIVE_PATH = join(".pi", "onlyne.json");
 
+/** Where the workspace's own client configuration lives. */
+export const WORKSPACE_CONFIG_RELATIVE_PATH = join(".onlyne", "config.toml");
+
 /** Defaults: on, and connecting as soon as a session starts. */
 export const DEFAULT_CONFIG = Object.freeze({
   enabled: true,
@@ -25,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"));
@@ -34,7 +37,17 @@ export function loadConfig(cwd, options = {}) {
   try {
     raw = readFile(path);
   } catch {
-    return { ...DEFAULT_CONFIG, path, warning: null, present: false };
+    return {
+      ...DEFAULT_CONFIG,
+      role: null,
+      sessionId: null,
+      workspace: null,
+      cluster: null,
+      resident: false,
+      path,
+      warning: null,
+      present: false,
+    };
   }
   let parsed;
   try {
@@ -42,18 +55,39 @@ export function loadConfig(cwd, options = {}) {
   } catch (error) {
     return {
       ...DEFAULT_CONFIG,
+      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`,
       present: true,
     };
   }
   if (!parsed || typeof parsed !== "object") {
-    return { ...DEFAULT_CONFIG, path, warning: `${path} must hold a JSON object; using defaults`, present: true };
+    return {
+      ...DEFAULT_CONFIG,
+      role: null,
+      sessionId: null,
+      workspace: null,
+      cluster: null,
+      resident: false,
+      path,
+      warning: `${path} must hold a JSON object; using defaults`,
+      present: true,
+    };
   }
   const watch = parsed.watch && typeof parsed.watch === "object" ? parsed.watch : {};
+  const rawSessionId = parsed.sessionId ?? parsed.session_id ?? parsed.session_alias;
   return {
     enabled: typeof parsed.enabled === "boolean" ? parsed.enabled : DEFAULT_CONFIG.enabled,
     autoStart: typeof watch.autoStart === "boolean" ? watch.autoStart : DEFAULT_CONFIG.autoStart,
+    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,
     present: true,
@@ -75,3 +109,144 @@ export function sessionIdentity(env) {
   if (!role || !sessionId || !taskId) return null;
   return { role, sessionId, taskId };
 }
+
+/**
+ * Parse the subset of `<workspace>/.onlyne/config.toml` relevant to a
+ * pre-started resident agent (`role`, `placement`, `[client.session]`).
+ *
+ * @param {string} raw
+ * @returns {{ role: string | null, placement: string | null, scope: string | null, sessionId: string | null }}
+ */
+export function parseWorkspaceConfigToml(raw) {
+  let section = "";
+  let role = null;
+  let placement = null;
+  let scope = null;
+  let sessionId = null;
+  for (const rawLine of String(raw).split(/\r?\n/)) {
+    const line = rawLine.replace(/#.*$/, "").trim();
+    if (!line) continue;
+    const secMatch = line.match(/^\[([^\]]+)\]$/);
+    if (secMatch) {
+      section = secMatch[1].trim();
+      continue;
+    }
+    const kvMatch = line.match(/^([A-Za-z0-9_.-]+)\s*=\s*"([^"]*)"/);
+    if (!kvMatch) continue;
+    const [, key, val] = kvMatch;
+    const trimmed = val.trim();
+    if (!trimmed) continue;
+    if (section === "" && key === "role") role = trimmed;
+    else if (section === "" && key === "placement") placement = trimmed.toLowerCase();
+    else if (section === "client.session" && key === "scope") scope = trimmed.toLowerCase();
+    else if (section === "client.session" && (key === "session_id" || key === "session_alias")) {
+      sessionId = sessionId ?? trimmed;
+    }
+  }
+  return { role, placement, scope, sessionId };
+}
+
+/**
+ * Discover a resident / pre-started session identity when the agent is launched
+ * before `onlyne-client` (no `ONLYNE_TASK_ID` in `env`).
+ *
+ * Activates when any of the following holds:
+ * 1. `ONLYNE_ROLE` is set in `env` (with optional `ONLYNE_SESSION_ID` / `ONLYNE_WORKSPACE`),
+ * 2. `.pi/onlyne.json` sets `"role"`, `"sessionId"`, or `"resident": true`, or
+ * 3. `<workspace>/.onlyne/config.toml` declares `placement = "external"`,
+ *    `[client.session] scope = "role"`, or `[client.session] session_id` / `session_alias`.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @param {string} cwd
+ * @param {{ readFile?: (path: string) => string }} [options]
+ * @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"));
+  const config = loadConfig(cwd, options);
+  const envRole = typeof env.ONLYNE_ROLE === "string" && env.ONLYNE_ROLE.trim() !== "" ? env.ONLYNE_ROLE.trim() : null;
+  const envSessionId =
+    typeof (env.ONLYNE_SESSION_ID ?? env.ONLYNE_SESSION_ALIAS) === "string" &&
+    (env.ONLYNE_SESSION_ID ?? env.ONLYNE_SESSION_ALIAS).trim() !== ""
+      ? (env.ONLYNE_SESSION_ID ?? env.ONLYNE_SESSION_ALIAS).trim()
+      : null;
+  const envTaskId =
+    typeof env.ONLYNE_TASK_ID === "string" && env.ONLYNE_TASK_ID.trim() !== "" ? env.ONLYNE_TASK_ID.trim() : null;
+  const envWorkspace =
+    typeof env.ONLYNE_WORKSPACE === "string" && env.ONLYNE_WORKSPACE.trim() !== ""
+      ? env.ONLYNE_WORKSPACE.trim()
+      : null;
+  const envResident =
+    typeof env.ONLYNE_RESIDENT === "string" &&
+    ["1", "true", "yes", "on"].includes(env.ONLYNE_RESIDENT.trim().toLowerCase());
+
+  const hintRole = envRole ?? config.role;
+  const explicitWorkspace = envWorkspace ?? config.workspace;
+  let workspaceRoot = explicitWorkspace
+    ? isAbsolute(explicitWorkspace)
+      ? explicitWorkspace
+      : resolve(cwd, explicitWorkspace)
+    : cwd;
+
+  let toml = { role: null, placement: null, scope: null, sessionId: null };
+  const candidateRoots = [];
+  if (explicitWorkspace) {
+    candidateRoots.push(workspaceRoot);
+  } else {
+    let cur = resolve(cwd);
+    for (let depth = 0; depth < 4; depth++) {
+      candidateRoots.push(cur);
+      if (hintRole) candidateRoots.push(join(cur, hintRole));
+      const parent = dirname(cur);
+      if (parent === cur) break;
+      cur = parent;
+    }
+  }
+  for (const candidate of candidateRoots) {
+    try {
+      const raw = readFile(join(candidate, WORKSPACE_CONFIG_RELATIVE_PATH));
+      const parsed = parseWorkspaceConfigToml(raw);
+      if (parsed.role && (!hintRole || parsed.role === hintRole)) {
+        toml = parsed;
+        workspaceRoot = candidate;
+        break;
+      }
+    } catch {
+      /* try next candidate */
+    }
+  }
+  if (!explicitWorkspace && !toml.role && hintRole && workspaceRoot === cwd) {
+    // If started in a cluster root (`<root>/.onlyne/spec.toml` exists), the
+    // role workspace will live at `<root>/<role>`.
+    try {
+      readFile(join(cwd, ".onlyne", "spec.toml"));
+      workspaceRoot = join(cwd, hintRole);
+    } catch {
+      /* cwd itself is the workspace root */
+    }
+  }
+
+  const role = envRole ?? config.role ?? toml.role;
+  if (!role) return null;
+
+  const optedIn = Boolean(
+    envRole ||
+      envResident ||
+      config.resident ||
+      config.role ||
+      config.sessionId ||
+      toml.placement === "external" ||
+      toml.scope === "role" ||
+      toml.sessionId,
+  );
+  if (!optedIn) return null;
+
+  return {
+    role,
+    sessionId: envSessionId ?? config.sessionId ?? toml.sessionId ?? null,
+    taskId: envTaskId,
+    cluster: config.cluster,
+    resident: true,
+    workspaceRoot,
+  };
+}

package/src/config.test.mjs

@@ -10,7 +10,14 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, test } from "node:test";
 
-import { CONFIG_RELATIVE_PATH, DEFAULT_CONFIG, loadConfig, sessionIdentity } from "./config.mjs";
+import {
+  CONFIG_RELATIVE_PATH,
+  DEFAULT_CONFIG,
+  WORKSPACE_CONFIG_RELATIVE_PATH,
+  loadConfig,
+  residentIdentity,
+  sessionIdentity,
+} from "./config.mjs";
 
 const cleanups = [];
 afterEach(() => {
@@ -78,3 +85,54 @@ test("the session identity gate needs all three variables", () => {
   assert.equal(sessionIdentity({}), null);
   assert.equal(sessionIdentity({ ONLYNE_ROLE: "", ONLYNE_SESSION_ID: "s", ONLYNE_TASK_ID: "t" }), null);
 });
+
+test("residentIdentity resolves pre-started sessions from env, .pi/onlyne.json, or .onlyne/config.toml", () => {
+  const dir = workspace();
+  // Plain workspace with no role or resident opt-in stays inert.
+  assert.equal(residentIdentity({}, dir), null);
+
+  // ONLYNE_ROLE alone activates resident mode for pre-started supervisor/agent.
+  assert.deepEqual(residentIdentity({ ONLYNE_ROLE: "supervisor" }, dir), {
+    role: "supervisor",
+    sessionId: null,
+    taskId: null,
+    cluster: null,
+    resident: true,
+    workspaceRoot: dir,
+  });
+
+  // .onlyne/config.toml with placement = "external" and session_id activates resident mode.
+  mkdirSync(join(dir, ".onlyne"), { recursive: true });
+  writeFileSync(
+    join(dir, WORKSPACE_CONFIG_RELATIVE_PATH),
+    'role = "planner"\nplacement = "external"\n\n[client.session]\nscope = "role"\nsession_id = "planner-main"\n',
+  );
+  assert.deepEqual(residentIdentity({}, dir), {
+    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,
+  });
+});