pi-onlyne 1.1.0 → 1.1.2

package/README.md

@@ -79,10 +79,10 @@ printf '{"packages":["../.onlyne/agent/onlyne-agent-pi"]}\n' > <ws>/.pi/settings
 ### From npm
 
 ```bash
-pi install pi-onlyne              # user-level: every pi process on this box loads it
+pi install npm:pi-onlyne          # user-level: every pi process on this box loads it
 ```
 
-The published package is `pi-onlyne` on npm; `pi install pi-onlyne@<version>` pins
+The published package is `pi-onlyne` on npm; `pi install npm:pi-onlyne@<version>` pins
 one. This route reaches ordinary interactive sessions too, and there the extension
 stays inert (no `ONLYNE_ROLE`, so no adapter). A role workspace needs no global
 install to get a panel: the file-level copy above, or `onlyne server generate`,
@@ -215,10 +215,10 @@ workspace, `relay.toml` in a manual installation.
 
 ```toml
 relay_required = ["writer"]        # these roles must have received a handoff
-relay_required_count = 2           # ... or this many distinct downstream roles
+relay_required_count = 2           # legacy alias of relay_count: this many distinct downstream roles
 ```
 
-`relay_required` wins when both keys are present.
+`relay_count` is the canonical count key. `relay_required_count` is its legacy alias, the spelling `relay.toml` itself uses. `relay_required` wins when both the list and the count keys are present.
 
 The policy belongs in the spec, not in the vendor directory. `onlyne generate --force`
 rewrites the copy this package is vendored into and takes a hand-written `relay.toml`
@@ -228,8 +228,8 @@ every session process it spawns:
 ```toml
 [[client]]
 role = "planner"
+relay_count = 2                    # this many distinct downstream roles
 relay_required = ["writer"]        # these roles must have received a handoff
-relay_count = 2                    # ... or this many distinct downstream roles
 ```
 
 The sources rank `environment > relay.toml > none`: `ONLYNE_RELAY_REQUIRED` (the list,
@@ -298,10 +298,12 @@ the shipped client.
   written, and a framing fault closes the connection and reconnects. Framing cannot
   resynchronise after a corrupt body, which is the same conclusion
   `crates/onlyne-frame/src/lib.rs` reaches.
-- **Task ids here are single-use.** The plugin acks duplicate `assign` deliveries for the
-  same task (`reason: "duplicate"`) without a second injection, and remembers the id for
-  the life of the connection. The client today mints a fresh uuid per task, so this only
-  ever fires on a genuine redelivery.
+- **Deliveries are idempotent; tasks are not.** The dedup key is the envelope id. The
+  same delivery twice gets one injection and an ack with `reason: "duplicate"`, and a
+  new envelope for a task that is already running reaches that session as another
+  message — the work record keeps its counters and its relay ledger, and only its
+  "turns since this instruction" watchdog restarts. The client mints a fresh uuid per
+  envelope, so `duplicate` fires on a genuine re-offer and on nothing else.
 
 - **Pane binding (Orca tabs).** Inside an Orca pane the plugin reports the pane it runs in on every
   heartbeat, as `observed.host.orca.pane_key` in the report's `Observation`
@@ -327,7 +329,7 @@ the shipped client.
 | `ONLYNE_ROLE` | yes | the mount role |
 | `ONLYNE_SESSION_ID` | yes | mounted session id; `session_id` equals `task_id` in the shipped client |
 | `ONLYNE_TASK_ID` | yes | the task this process serves; drives `session_register` and the initial `ready` |
-| `ONLYNE_SOCKET` | no | overrides the socket path (default `<cwd>/.onlyne/run/s`) |
+| `ONLYNE_SOCKET` | no | the socket the client serves for this workspace, injected into every session process it spawns; with the variable unset the plugin reads the marker `<cwd>/.onlyne/run/socket` for the path the daemon published, and falls back to `<cwd>/.onlyne/run/s` |
 | `ONLYNE_RELAY_REQUIRED` | no | the role's spec `relay_required`, comma-joined: the guard's list mode (§5) |
 | `ONLYNE_RELAY_COUNT` | no | the role's spec `relay_count`: the guard's count mode, which decides only when the list is empty (§5) |
 | `ORCA_PANE_KEY` | no | where this process runs (`<tab_id>:<leaf_id>`), reported on every heartbeat as `observed.host.orca.pane_key`; unset outside an Orca pane, which is why the field is then absent |
@@ -337,9 +339,10 @@ the shipped client.
 Constants worth knowing: the plugin heartbeats every 10 s (`heartbeat_timeout_ms` is 30 s),
 allows 5 s for `hello` and 30 s per request, and reconnects on a 1/2/4/8/16/30 s ladder.
 
-The plugin reads two files of its own: `<cwd>/.pi/onlyne.json` (the switch, §1) and
+The plugin reads three files of its own: `<cwd>/.pi/onlyne.json` (the switch, §1),
 `relay.toml` next to its `package.json` (the relay policy's fallback, read only when the
-client injected none, §5).
+client injected none, §5), and `<cwd>/.onlyne/run/socket` (the marker naming the socket
+path the client's daemon bound, read when the environment carried none, §8).
 
 ## 8. Troubleshooting
 
@@ -347,6 +350,7 @@ client injected none, §5).
 | --- | --- | --- |
 | `[pi-onlyne] session …` never appears | one of the three env vars is missing, or `enabled` is false | `env \| grep ONLYNE_`; `cat .pi/onlyne.json` |
 | `socket error: connect ENOENT …/.onlyne/run/s` | no `onlyne-client run` for this workspace | start the client, or `onlyne-client status` |
+| `socket error: connect EINVAL …/.onlyne/run/s` on a deep workspace | macOS gives `sun_path` 104 bytes, so a socket path past 103 is refused; a generated role workspace nests three levels under its server root and a long root carries the canonical spelling over the bound. The client serves such a workspace from a short path under the temporary directory and publishes it in `<workspace>/.onlyne/run/socket` | `onlyne-client status` for the line `onlyne: client running … socket <path>`, which names the served path, plus the client log line carrying `socket = <path>`; `cat <workspace>/.onlyne/run/socket` holds that same path, and the plugin dials it when the environment injected nothing |
 | `reconnecting in 4000ms` in a loop | the client is down or the socket was replaced | `onlyne --server-root … roles` |
 | `ready refused: internal: unknown session for …` | the plugin mounted and reported for a task the client never staged (normal when pi is started by hand outside a task) | start pi under the client, not by hand |
 | `assign` never arrives | the client's `session_command` did not spawn pi, or `inject` was dropped | the client log for the spawn line; `/onlyne status` for the capability set |
@@ -366,7 +370,7 @@ client injected none, §5).
 
 ```bash
 cd plugins/onlyne-agent-pi
-node --test src/*.test.mjs        # framing, protocol, agent state machine, config, relay guard
+node --test src/*.test.mjs        # framing, protocol, agent state machine, config, relay guard, socket path
 ```
 
 `src/agent.live.test.mjs` skips itself unless `target/debug/onlyne-client` and

package/README.zh.md

@@ -73,10 +73,10 @@ printf '{"packages":["../.onlyne/agent/onlyne-agent-pi"]}\n' > <ws>/.pi/settings
 ### 从 npm 装
 
 ```bash
-pi install pi-onlyne              # 用户级：这台机器上每个 pi 进程都会加载
+pi install npm:pi-onlyne          # 用户级：这台机器上每个 pi 进程都会加载
 ```
 
-发布名是 npm 上的 `pi-onlyne`，`pi install pi-onlyne@<version>` 钉住某一版。这条路径会覆盖
+发布名是 npm 上的 `pi-onlyne`，`pi install npm:pi-onlyne@<version>` 钉住某一版。这条路径会覆盖
 普通交互会话，那里没有 `ONLYNE_ROLE`，扩展保持静默（见 §1 的身份门）。role workspace 想要面
 板，不必装到全局：上面那份文件级复制、或者 `onlyne server generate`，都把插件限定在服务这个
 role 的 workspace 里。
@@ -259,9 +259,10 @@ stderr 告警并忽略，把机会让回文件。
   `inject` 插件记录的重载。其他键记日志后忽略，绝不误读。
 - **`frame_too_large` / `bad_frame`**：超限正文在写出任何字节之前就被拒；帧错误关闭连接并重
   连。帧一旦损坏无法重新同步，这与 `crates/onlyne-frame/src/lib.rs` 的结论一致。
-- **任务 id 在连接生命周期内一次性使用**：同一任务的重复 `assign` 插件只回
-  `reason: "duplicate"` 的 ack，不重复注入，并记住这个 id 直到连接结束。当今 client 每个任务
-  都是新 uuid，所以这条只在真正的重投上生效。
+- **投递按 envelope id 幂等，任务不按 id 一次性使用**：去重键是 envelope id。同一条投递重复
+  到达只注入一次，ack 带 `reason: "duplicate"`；正在运行的任务收到新 envelope，会作为新消息
+  注入同一个会话，工作记录保留自己的计数与转发账本，只把"自这条指令以来的轮数"看门狗归零。
+  client 每条 envelope 都发新 uuid，所以 `duplicate` 只在真正的重投上生效。
 
 - **pane 绑定（Orca tab）。** 在 Orca pane 里，插件在每个 heartbeat 上报自己跑在哪：报告
   `Observation` 里的 `observed.host.orca.pane_key`（`crates/onlyne-session/src/host.rs`），环境
@@ -283,7 +284,7 @@ stderr 告警并忽略，把机会让回文件。
 | `ONLYNE_ROLE` | 是 | 挂载的 role |
 | `ONLYNE_SESSION_ID` | 是 | 挂载的 session id；当前 client 中 session_id 等于 task_id |
 | `ONLYNE_TASK_ID` | 是 | 本进程服务的任务；驱动 `session_register` 与首条 `ready` |
-| `ONLYNE_SOCKET` | 否 | 覆盖 socket 路径（默认 `<cwd>/.onlyne/run/s`） |
+| `ONLYNE_SOCKET` | 否 | client 为该工作区实际服务的 socket 路径；凡 client 拉起的会话进程都会带上。变量未设置时，插件读标记文件 `<cwd>/.onlyne/run/socket`，取守护进程发布的那个路径，随后落到 `<cwd>/.onlyne/run/s` |
 | `ONLYNE_RELAY_REQUIRED` | 否 | 该 role 在 spec 里的 `relay_required`，逗号分隔：守卫的名单模式（§5） |
 | `ONLYNE_RELAY_COUNT` | 否 | 该 role 在 spec 里的 `relay_count`：守卫的 count 模式，只在名单为空时起作用（§5） |
 | `ORCA_PANE_KEY` | 否 | 本进程跑在哪（`<tab_id>:<leaf_id>`），每个 heartbeat 以 `observed.host.orca.pane_key` 上报；不在 Orca pane 里时未设置，这也是该字段缺席的原因 |
@@ -293,8 +294,10 @@ stderr 告警并忽略，把机会让回文件。
 值得记住的常量：插件每 10 秒发一次心跳（`heartbeat_timeout_ms` 是 30 秒），`hello` 最多等
 5 秒，单次请求超时 30 秒，重连按 1/2/4/8/16/30 秒阶梯退避。
 
-插件自己读两个文件：`<cwd>/.pi/onlyne.json`（开关，§1）与 `package.json` 旁边的
-`relay.toml`（接力策略的兜底，只在 client 没注入策略时才读，§5）。
+插件自己读三个文件：`<cwd>/.pi/onlyne.json`（开关，§1）、`package.json` 旁边的
+`relay.toml`（接力策略的兜底，只在 client 没注入策略时才读，§5）、
+`<cwd>/.onlyne/run/socket`（标记文件，写明 client 守护进程绑定的 socket 路径，只在环境里
+没带路径时才读，§8）。
 
 ## 8. 故障排查
 
@@ -302,6 +305,7 @@ stderr 告警并忽略，把机会让回文件。
 | --- | --- | --- |
 | 看不到 `[pi-onlyne] session …` | 三个环境变量缺一，或 `enabled` 为 false | `env \| grep ONLYNE_`；`cat .pi/onlyne.json` |
 | `socket error: connect ENOENT …/.onlyne/run/s` | 该工作区没有 `onlyne-client run` | 起 client，或 `onlyne-client status` |
+| 深层工作区里 `socket error: connect EINVAL …/.onlyne/run/s` | macOS 的 `sun_path` 只有 104 字节，超过 103 的 socket 路径会被内核拒绝；生成的 role 工作区在 server root 下再套三层，root 一长，规范写法就越过这个上界。client 面对这种工作区会把 socket 放到临时目录下的短路径上服务，并把选中的路径发布进 `<workspace>/.onlyne/run/socket` | 看 `onlyne-client status` 打印的 `onlyne: client running … socket <路径>`，那一行点出实际服务的路径，再看 client 日志里带 `socket = <路径>` 的那行；`cat <workspace>/.onlyne/run/socket` 得到同一个路径——环境里没带变量时，插件拨的就是它 |
 | 反复 `reconnecting in 4000ms` | client 已停或 socket 被替换 | `onlyne --server-root … roles` |
 | `ready refused: internal: unknown session for …` | 插件为 client 从未暂存的任务报了 ready（手工起 pi 时的正常现象） | 让 client 拉起 pi，而不是手工起 |
 | `assign` 一直不来 | client 的 `session_command` 没能拉起 pi，或 `inject` 被降级 | client 日志里的 spawn 行；`/onlyne status` 看能力集 |
@@ -321,7 +325,7 @@ stderr 告警并忽略，把机会让回文件。
 
 ```bash
 cd plugins/onlyne-agent-pi
-node --test src/*.test.mjs        # 帧编解码、协议词汇、agent 状态机、配置、接力守卫
+node --test src/*.test.mjs        # 帧编解码、协议词汇、agent 状态机、配置、接力守卫、socket 路径
 ```
 
 `src/agent.live.test.mjs` 只在 `target/debug/onlyne-client` 与 `onlyne-server` 存在时运行。

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "pi-onlyne",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Onlyne agent adapter for pi: the session lifecycle an onlyne role client expects from a pi host.",
   "type": "module",
-  "main": "./src/index.ts",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,12 +31,10 @@
     ]
   },
   "scripts": {
-    "test": "node --test src/*.test.mjs",
-    "test:live": "node --test src/agent.live.test.mjs"
+    "test": "node --test src/*.test.mjs"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
-  },
-  "peerDevDependencies": {}
+  }
 }

package/relay.toml.example

@@ -1,13 +1,18 @@
-# Onlyne relay guard policy — copy to `relay.toml` next to this package's `package.json`.
+# Manual-installation escape hatch for the relay guard.
 #
-# Manual installations only. A generated workspace states the same policy in the
-# server spec's `[[client]]` entry (`relay_required` / `relay_count`), which the
-# client injects as `ONLYNE_RELAY_REQUIRED` / `ONLYNE_RELAY_COUNT`. Those
-# environment variables win, and a file they shadow is ignored outright.
+# A generated workspace gets its guard policy from spec.toml ([[client]] rows
+# `relay_required = ["writer"]`, `relay_count = 2` — `relay_required_count` is
+# accepted as the guard file's own spelling), which the client injects into
+# every session it spawns. This file is for installations that manage their
+# own workspace: drop it beside package.json and the guard reads it when the
+# environment carries no policy. Environment wins over this file; no policy in
+# either place leaves the guard off.
 #
-# Closed subset: flat `key = value` lines, the two keys below, one-line arrays of
-# double-quoted strings, `#` comments. Anything outside that warns on stderr and
-# is ignored. `relay_required` wins when both keys are present.
+# relay_required wins over relay_count when both are present.
 
-relay_required = ["writer"]        # these roles must have received a handoff
-relay_required_count = 2           # ... or this many distinct downstream roles
+# Downstream roles one of this role's sessions must have handed work to before
+# it may report a terminal outcome:
+#   relay_required = ["writer", "auditor"]
+
+# ... or this many distinct downstream roles:
+#   relay_required_count = 2

package/src/agent.mjs

@@ -152,7 +152,13 @@ export class OnlyneAgent {
      * sent — the guard judges this session's own deliveries, not history.
      */
     this.deliveredTo = new Set();
-    this.injectedTasks = new Set();
+    /**
+     * The deliveries this process has already handed to the model, keyed by
+     * envelope id (a delivery's own identity). Keying it by task id would swallow
+     * every later envelope for a live task — the follow-up that never arrives —
+     * and the guard below answers a true re-delivery with `duplicate`.
+     */
+    this.injectedDeliveries = new Set();
     this.deliveredProse = new Set();
     /** Pushes that arrived before the handshake finished; see `onFrame`. */
     this.handshaking = false;
@@ -564,13 +570,16 @@ export class OnlyneAgent {
       this.log("assign carried no task id; ignored");
       return;
     }
-    if (this.injectedTasks.has(taskId)) {
+    // The delivery's own identity, so a re-offer of the same message is caught
+    // and a genuinely new message for a running task gets through.
+    const deliveryId = envelope.id ?? `task:${taskId}`;
+    if (this.injectedDeliveries.has(deliveryId)) {
       this.stats.duplicates += 1;
-      this.notice("dup", `task ${taskId.slice(0, 8)} already injected`);
+      this.notice("dup", `~~ task ${taskId.slice(0, 8)} re-delivered, already injected`);
       await this.ack(taskId, true, "duplicate");
       return;
     }
-    this.injectedTasks.add(taskId);
+    this.injectedDeliveries.add(deliveryId);
     this.stats.assigns += 1;
     if (typeof args.generation === "number") this.generation = args.generation;
 
@@ -580,18 +589,32 @@ export class OnlyneAgent {
     if (proseIsNew) this.deliveredProse.add(prose);
     const text = injectionText({ assign: { ...args, task_id: taskId }, proseIsNew, attachmentPaths: attachments.map((item) => item.path) });
 
-    this.tasks.set(taskId, {
-      taskId,
-      envelopeId: envelope.id ?? null,
-      // Who handed this task over: the relay guard's count mode does not count
-      // a send straight back to it (`relay.mjs`).
-      upstream: envelope.from?.role?.role ?? null,
-      turnsSinceAssign: 0,
-      turns: 0,
-      errored: false,
-      head: "",
-      failed: false,
-    });
+    const held = this.tasks.get(taskId);
+    // 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) {
+      // A new envelope for a task this session already holds — a follow-up, a
+      // redirect, a bounce back through a relay. The work record stays where it
+      // is: its delivered set keeps the relay guard's count, and its completion
+      // state still settles the task. Only the "since this instruction" counter
+      // moves, so the settled-without-completing watchdog measures the newest one.
+      held.turnsSinceAssign = 0;
+      held.envelopeId = envelope.id ?? held.envelopeId;
+      if (held.failed) held.failed = false;
+    } else {
+      this.tasks.set(taskId, {
+        taskId,
+        envelopeId: envelope.id ?? null,
+        // Who handed this task over: the relay guard's count mode does not count
+        // a send straight back to it (`relay.mjs`).
+        upstream: envelope.from?.role?.role ?? null,
+        turnsSinceAssign: 0,
+        turns: 0,
+        errored: false,
+        head: "",
+        failed: false,
+      });
+    }
     this.agentState = "running";
     this.surface.wakeUser?.(text, attachments.map((item) => item.part));
     this.surface.customEntry?.("onlyne-assign", {

package/src/agent.test.mjs

@@ -458,6 +458,50 @@ 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 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
+// server kept re-offering never settled.
+test("a new envelope for a running task reaches the model and keeps its record", async () => {
+  const { agent, host, surface } = await startAgent();
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  host.notify("assign", assignArgs());
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+  const record = agent.tasks.get(TASK_ID);
+  // Turns already run under this task, without driving the turn hooks: a real
+  // turn end also arms the settle fallback, which would complete the task.
+  record.turns = 3;
+  record.turnsSinceAssign = 2;
+
+  const base = assignArgs();
+  const follow = {
+    ...base,
+    envelope: {
+      ...base.envelope,
+      id: "4a3b2c1d-6e7f-4a90-8b1c-2d3e4f506172",
+      body: { text: "actually, use the q8 variant" },
+    },
+  };
+  host.notify("assign", follow);
+  await waitFor(() => (surface.calls.wakeUser.length === 2 ? true : null));
+  assert.match(surface.calls.wakeUser[1].text, /q8 variant/);
+  const acks = await waitFor(() => (host.of("assign_ack").length === 2 ? host.of("assign_ack") : null));
+  assert.deepEqual(acks[1], { task_id: TASK_ID, accepted: true });
+
+  assert.equal(agent.tasks.get(TASK_ID), record, "the running work record survives");
+  assert.equal(record.turns, 3, "what the session already did under this task is not erased");
+  assert.equal(record.turnsSinceAssign, 0, "the watchdog counts from the newest instruction");
+  assert.equal(record.envelopeId, "4a3b2c1d-6e7f-4a90-8b1c-2d3e4f506172");
+
+  // The same envelope again is the true duplicate, and it changes nothing.
+  host.notify("assign", follow);
+  const third = await waitFor(() => (host.of("assign_ack").length === 3 ? host.of("assign_ack") : null));
+  assert.equal(surface.calls.wakeUser.length, 2);
+  assert.deepEqual(third[2], { task_id: TASK_ID, accepted: true, reason: "duplicate" });
+});
+
 // The live case in crates/onlyne-testkit/e2e/pi-live.sh found this: the client
 // hands over a staged session by writing the hello reply and the first assign
 // together, so both frames arrive in one read. The assignment must not be

package/src/index.ts

@@ -20,6 +20,7 @@ import { Type } from "typebox";
 import { OnlyneAgent } from "./agent.mjs";
 import { loadConfig, sessionIdentity } from "./config.mjs";
 import { loadRelay, relayEnabled } from "./relay.mjs";
+import { resolveSocketPath } from "./socket.mjs";
 import { createSurface } from "./pi-surface.mjs";
 
 /**
@@ -32,9 +33,6 @@ declare const process: {
   stderr: { write(chunk: string): void };
 };
 
-/** Socket every role workspace serves; `crates/onlyne-client/src/adapter_socket.rs`. */
-const SOCKET_RELATIVE_PATH = ".onlyne/run/s";
-
 /** One image part handed to the pi message surface. */
 interface ImagePartInput {
   mime: string;
@@ -235,7 +233,9 @@ export default function onlyne(pi: ExtensionAPI) {
       log(`disabled by ${config.path}`);
       return;
     }
-    const socketPath = env.ONLYNE_SOCKET || `${ctx.cwd}/${SOCKET_RELATIVE_PATH}`;
+    // Environment first (the client injects the path it serves), then the
+    // marker the daemon publishes, then the canonical `run/s` (socket.mjs).
+    const socketPath = resolveSocketPath(env, ctx.cwd);
     // The guard's policy comes from the spec through the client's environment;
     // a hand-written `relay.toml` beside the package is the fallback a manual
     // installation still has (relay.mjs).

package/src/socket.mjs

@@ -0,0 +1,54 @@
+// The adapter socket a pi session dials.
+//
+// macOS gives `sun_path` 104 bytes, so the kernel refuses a unix socket path
+// past 103 (`UNIX_SOCKET_PATH_MAX` in `crates/onlyne-layout/src/lib.rs`). A
+// generated role workspace nests three levels below its server root
+// (`<root>/.onlyne/ws/<topology>/<role>/.onlyne/run/s`), so a deep root carries
+// the canonical spelling past that bound. The client answers by serving such a
+// workspace from a short path under the temporary directory
+// (`<temp>/onlyne-<16hex>/s`) and publishing the choice it bound in the marker
+// file `<workspace>/.onlyne/run/socket`, one line holding the absolute served
+// path. `onlyne-layout::SocketEndpoint::publish` writes that file; every reader
+// in the product reaches one live socket through it.
+//
+// So the plugin has three answers in order, cheapest first: the path the client
+// injected when it spawned this process (`ONLYNE_SOCKET`), the path the running
+// daemon published in the marker, and the canonical spelling. The third one is
+// a complete answer for every workspace short enough to serve from `run/s`,
+// because `bind_socket` writes the marker at every start and such a tree
+// publishes `run/s` in it; the two readings give one path. A marker that is
+// missing, unreadable, or blank holds no published override, so resolution
+// falls through silently. That keeps a hand-started pi in a workspace with a
+// running daemon on the right socket with no environment at all.
+
+import { readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+/** The canonical socket leaf every role workspace names; `SOCKET_FILE_NAME` in `crates/onlyne-layout/src/lib.rs`. */
+export const SOCKET_RELATIVE_PATH = join(".onlyne", "run", "s");
+
+/** Marker beside it naming the path the daemon actually serves. */
+export const SOCKET_MARKER_RELATIVE_PATH = join(".onlyne", "run", "socket");
+
+/**
+ * The socket path to dial for the workspace at `cwd`.
+ *
+ * @param {Record<string, string | undefined>} env the process environment
+ * @param {string} cwd the pi working directory, the role workspace itself
+ * @param {{ readFile?: (path: string) => string }} [options]
+ * @returns {string} an absolute path: the injected one, the published one, or `run/s`
+ */
+export function resolveSocketPath(env, cwd, options = {}) {
+  const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+  const injected = typeof env.ONLYNE_SOCKET === "string" ? env.ONLYNE_SOCKET.trim() : "";
+  if (injected) return injected;
+  const marker = join(cwd, SOCKET_MARKER_RELATIVE_PATH);
+  let published = "";
+  try {
+    published = readFile(marker).trim();
+  } catch {
+    published = "";
+  }
+  if (published && isAbsolute(published)) return published;
+  return join(cwd, SOCKET_RELATIVE_PATH);
+}

package/src/socket.test.mjs

@@ -0,0 +1,79 @@
+// Which socket path a pi session dials.
+//
+// The three answers have to stay in one order: what the client injected, what
+// the daemon published in `<run>/socket`, and the canonical `<run>/s`. A
+// workspace deep enough that the canonical spelling passes macOS' 103-byte
+// `sun_path` bound is served from a short path under the temporary directory,
+// and the marker is the only place inside the tree that names it.
+
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, test } from "node:test";
+
+import { SOCKET_MARKER_RELATIVE_PATH, SOCKET_RELATIVE_PATH, resolveSocketPath } from "./socket.mjs";
+
+const cleanups = [];
+afterEach(() => {
+  while (cleanups.length > 0) cleanups.pop()();
+});
+
+/** One temp workspace whose `run/` directory exists, optionally with a marker body. */
+function workspace(markerBody) {
+  const dir = mkdtempSync(join(tmpdir(), "pi-onlyne-socket-"));
+  cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+  mkdirSync(join(dir, ".onlyne", "run"), { recursive: true });
+  if (markerBody !== undefined) writeFileSync(join(dir, SOCKET_MARKER_RELATIVE_PATH), markerBody);
+  return dir;
+}
+
+/** The short path a daemon serves an over-long workspace from. */
+const SERVED = join(tmpdir(), "onlyne-0123456789abcdef", "s");
+
+test("the injected environment variable decides first", () => {
+  const dir = workspace(`${SERVED}\n`);
+  assert.equal(resolveSocketPath({ ONLYNE_SOCKET: SERVED }, dir), SERVED);
+  // Any other published answer loses to the environment.
+  assert.equal(resolveSocketPath({ ONLYNE_SOCKET: join(dir, SOCKET_RELATIVE_PATH) }, dir), join(dir, SOCKET_RELATIVE_PATH));
+  // A value wrapped in space names the same socket.
+  assert.equal(resolveSocketPath({ ONLYNE_SOCKET: `  ${SERVED}  ` }, dir), SERVED);
+
+  // A variable holding nothing answers nothing, so the tree decides.
+  const bare = workspace();
+  assert.equal(resolveSocketPath({ ONLYNE_SOCKET: "   " }, bare), join(bare, SOCKET_RELATIVE_PATH));
+  assert.equal(resolveSocketPath({}, bare), join(bare, SOCKET_RELATIVE_PATH));
+});
+
+test("a published marker moves the session onto the served path", () => {
+  const dir = workspace(`${SERVED}\n`);
+  const resolved = resolveSocketPath({}, dir);
+  assert.equal(resolved, SERVED);
+  // The moved path lives outside the workspace, which is the whole point of the
+  // marker: the tree's own `run/s` would be refused by the kernel here.
+  assert.ok(!resolved.startsWith(dir));
+});
+
+test("a workspace with no marker keeps the canonical spelling", () => {
+  const dir = workspace();
+  assert.equal(resolveSocketPath({}, dir), join(dir, ".onlyne", "run", "s"));
+});
+
+test("a marker that is empty, relative, or unreadable falls through silently", () => {
+  const empty = workspace("");
+  assert.equal(resolveSocketPath({}, empty), join(empty, SOCKET_RELATIVE_PATH));
+
+  const relative = workspace("run/s");
+  assert.equal(resolveSocketPath({}, relative), join(relative, SOCKET_RELATIVE_PATH));
+
+  // A `socket` leaf holding a directory makes the read itself fail.
+  const unreadable = workspace();
+  rmSync(join(unreadable, SOCKET_MARKER_RELATIVE_PATH), { force: true });
+  mkdirSync(join(unreadable, SOCKET_MARKER_RELATIVE_PATH));
+  assert.equal(resolveSocketPath({}, unreadable), join(unreadable, SOCKET_RELATIVE_PATH));
+
+  // A workspace with no `run/` at all still names one canonical path.
+  const bare = mkdtempSync(join(tmpdir(), "pi-onlyne-socket-"));
+  cleanups.push(() => rmSync(bare, { recursive: true, force: true }));
+  assert.equal(resolveSocketPath({}, bare), join(bare, SOCKET_RELATIVE_PATH));
+});