pi-onlyne 1.1.1 → 1.1.2

package/README.md

@@ -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,
@@ -329,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 |
@@ -339,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
 
@@ -349,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 |
@@ -368,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

@@ -284,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 里时未设置，这也是该字段缺席的原因 |
@@ -294,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. 故障排查
 
@@ -303,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` 看能力集 |
@@ -322,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,6 +1,6 @@
 {
   "name": "pi-onlyne",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Onlyne agent adapter for pi: the session lifecycle an onlyne role client expects from a pi host.",
   "type": "module",
   "license": "MIT",

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));
+});