pi-onlyne 1.2.1 → 2.0.0

package/src/socket.mjs

@@ -1,54 +1,285 @@
-// The adapter socket a pi session dials.
+// The adapter socket a pi session dials, resolved the v2 way.
 //
-// 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.
+// v2 keeps every local socket in one machine-level runtime directory —
+// `$ONLYNE_RUNTIME_DIR` when the operator sets it and non-empty, `/tmp/onlyne-<uid>/`
+// otherwise, `0700` — as `<digest>.sock`, `digest` the first 16 hex characters
+// of `sha256` over the canonical workspace root. Nothing binds inside the tree
+// any more: `<root>/.onlyne/run/s` and the `run/socket` marker v1 published the
+// served path in are both deleted, and `run/s` survives only as the spelling
+// operators print (`crates/onlyne-wire/src/socket.rs`).
 //
-// 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.
+// The client injects `ONLYNE_SOCKET` into every session process it spawns, so a
+// pi started by a client needs nothing else and this module's first answer —
+// that variable, verbatim — is what such a session uses. A pi started by hand
+// (`pi -e <plugin>`) carries no such variable, and there is no path inside the
+// tree to fall back on: it has to find the client the way the plan says an
+// external runtime does (`docs/v2-PLAN.md` line 289), by reading the
+// registration files in the runtime directory — `<digest>.json`, one per live
+// endpoint, holding `kind`, `role`, `root`, `pid`, `version` and `runtime`.
+//
+// So a hand-started pi reads those files and the order of its answers is:
+//
+//  1. the registration whose `root` is the workspace this process runs in — the
+//     exact tree, or the nearest registered root containing it, which is the
+//     tree the CLI's own upward walk lands on (`owner_root` in
+//     `crates/onlyne-cli/src/socket.rs`). No arbitrary pick can arise on this
+//     key: the roots containing one directory are a chain, so "nearest" is
+//     stated by the paths themselves, and two registrations naming one tree
+//     name one socket, because the socket is its digest.
+//  2. only when no registered root covers the working directory, the `runtime`
+//     field, which is the plan's discovery key for the external placement where
+//     one runtime serves several clients. Secondary in both senses: consulted
+//     last, and only a single matching client is an answer — several clients
+//     running pi sessions are refused by name rather than picked from, because
+//     a wrong pick dials a client that serves another role's sessions. (The
+//     field carries the session backend a client spawns under, `orca`/
+//     `acp`/`exec`, so today it names this plugin's runtime only where that
+//     backend is pi itself.)
+//  3. nothing at all: `SocketResolutionError` naming the workspace, the
+//     runtime directory and the registration file — and every registration the
+//     directory does hold — so the operator reads what was missing rather than
+//     a raw `ENOENT` for a path v2 never creates.
+//
+// The derivation below has to agree byte for byte with `workspace_digest` in
+// `crates/onlyne-wire/src/socket.rs` and `workspace_digest` in
+// `crates/onlyne-testkit/e2e/lib.sh`; a digest one byte off dials a path no
+// daemon holds.
+
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve, sep } from "node:path";
+
+/** Environment variable holding the path a client injected, used verbatim. */
+export const SOCKET_ENV = "ONLYNE_SOCKET";
+
+/** Environment variable that replaces the default runtime directory; `RUNTIME_DIR_ENV` in `crates/onlyne-wire/src/socket.rs`. */
+export const RUNTIME_DIR_ENV = "ONLYNE_RUNTIME_DIR";
+
+/** Socket leaf inside a runtime directory: `<digest>.sock`. */
+export const SOCKET_SUFFIX = ".sock";
+
+/** Registration leaf inside a runtime directory: `<digest>.json`. */
+export const REGISTRATION_SUFFIX = ".json";
 
-import { readFileSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+/** The runtime this plugin is, the value it matches a client's `runtime` field against. */
+export const RUNTIME_NAME = "pi";
 
-/** 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");
+/** How many hex characters of the digest name a runtime file; `workspace_digest` hashes 8 bytes. */
+const DIGEST_LENGTH = 16;
 
-/** Marker beside it naming the path the daemon actually serves. */
-export const SOCKET_MARKER_RELATIVE_PATH = join(".onlyne", "run", "socket");
+/** Raised when no client registration answers for a workspace, or several do. */
+export class SocketResolutionError extends Error {
+  /**
+   * @param {string} message what was looked for and what was found
+   * @param {{ path: string, root: string, kind: string | null, runtime: string | null }[]} candidates
+   */
+  constructor(message, candidates = []) {
+    super(message);
+    this.name = "SocketResolutionError";
+    this.candidates = candidates;
+  }
+}
 
 /**
- * The socket path to dial for the workspace at `cwd`.
+ * The machine-level runtime directory: the override when set and non-empty,
+ * `/tmp/onlyne-<uid>` otherwise.
+ *
+ * Nothing is created or checked here, and the override is taken without
+ * trimming, both matching `runtime_dir_path` (an empty value is no override, a
+ * value holding only spaces is a directory name). The `/tmp` base is fixed
+ * rather than `os.tmpdir()` because a launchd-started daemon and an interactive
+ * shell see different `TMPDIR` values, and one base is what makes both compute
+ * the same path for the same root.
  *
  * @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`
+ * @param {{ uid?: number | null }} [options]
+ * @returns {string} an absolute directory path
  */
-export function resolveSocketPath(env, cwd, options = {}) {
+export function runtimeDir(env, options = {}) {
+  const override = typeof env[RUNTIME_DIR_ENV] === "string" ? env[RUNTIME_DIR_ENV] : "";
+  if (override !== "") return override;
+  const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : null);
+  // Off unix the reference has no uid to name: `%TEMP%` already scopes the
+  // directory per user and the endpoint's own owner-only descriptor guards it.
+  return uid === null ? join(tmpdir(), "onlyne-user") : join("/tmp", `onlyne-${uid}`);
+}
+
+/**
+ * The canonical spelling of `root`, the one `absolute_path` takes.
+ *
+ * A root that exists is resolved through its symlinks, which is what keeps
+ * macOS's `/var` and `/private/var` one digest. A root that does not exist has
+ * nothing to canonicalize and falls back to the lexical absolute.
+ *
+ * @param {string} root
+ * @param {{ realpath?: (path: string) => string }} [options]
+ * @returns {string}
+ */
+export function canonicalRoot(root, options = {}) {
+  const realpath = options.realpath ?? ((path) => realpathSync(path));
+  try {
+    return realpath(root);
+  } catch {
+    return resolve(isAbsolute(root) ? root : join(process.cwd(), root));
+  }
+}
+
+/**
+ * The identity of one owner tree: `sha256` over its canonical spelling, the
+ * first 16 lowercase hex characters.
+ *
+ * Separators become `/` and the whole spelling is lowercased before hashing, so
+ * `C:\Work` and `c:/work` digest alike — the reason a daemon and every client
+ * derive one file name without talking to each other.
+ *
+ * @param {string} root
+ * @param {{ realpath?: (path: string) => string }} [options]
+ * @returns {string} 16 hex characters
+ */
+export function workspaceDigest(root, options = {}) {
+  const spelling = canonicalRoot(root, options)
+    .replaceAll("\\", "/")
+    .replace(/[A-Z]/g, (character) => character.toLowerCase());
+  return createHash("sha256").update(spelling, "utf8").digest("hex").slice(0, DIGEST_LENGTH);
+}
+
+/**
+ * The socket one owner root is bound to: `<runtime_dir>/<digest>.sock`.
+ *
+ * @param {string} root the workspace root
+ * @param {Record<string, string | undefined>} env
+ * @param {{ readFile?: (path: string) => string, readDir?: (path: string) => string[], realpath?: (path: string) => string, uid?: number | null }} [options]
+ * @returns {string}
+ */
+export function socketPath(root, env, options = {}) {
+  return join(runtimeDir(env, options), `${workspaceDigest(root, options)}${SOCKET_SUFFIX}`);
+}
+
+/**
+ * The registration belonging to that socket: `<runtime_dir>/<digest>.json`.
+ *
+ * @param {string} root the workspace root
+ * @param {Record<string, string | undefined>} env
+ * @param {{ readFile?: (path: string) => string, readDir?: (path: string) => string[], realpath?: (path: string) => string, uid?: number | null }} [options]
+ * @returns {string}
+ */
+export function registrationPath(root, env, options = {}) {
+  return join(runtimeDir(env, options), `${workspaceDigest(root, options)}${REGISTRATION_SUFFIX}`);
+}
+
+/**
+ * Every client registration the runtime directory holds, in file-name order.
+ *
+ * A missing runtime directory is no registrations rather than an error: a
+ * plugin started before any daemon should see an empty machine. A file that is
+ * not `.json`, does not parse, or names no root is skipped, because one stray
+ * file must not blind the reader to every other tree — the same rule
+ * `list_registrations` follows in `crates/onlyne-wire/src/socket.rs`. A
+ * registration of another kind (a server root's admin endpoint, say) is skipped
+ * here as well: this plugin speaks the adapter protocol of a role workspace's
+ * client, and an admin socket answers those frames with `unknown op`.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @param {{ readFile?: (path: string) => string, readDir?: (path: string) => string[], realpath?: (path: string) => string, uid?: number | null }} [options]
+ * @returns {{ path: string, root: string, kind: string | null, runtime: string | null }[]}
+ */
+export function listClientRegistrations(env, options = {}) {
+  const readDir = options.readDir ?? ((path) => readdirSync(path));
   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 = "";
+  const dir = runtimeDir(env, options);
+  let names;
   try {
-    published = readFile(marker).trim();
+    names = readDir(dir);
   } catch {
-    published = "";
+    return [];
   }
-  if (published && isAbsolute(published)) return published;
-  return join(cwd, SOCKET_RELATIVE_PATH);
+  const found = [];
+  for (const name of [...names].sort()) {
+    if (typeof name !== "string" || !name.endsWith(REGISTRATION_SUFFIX)) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(readFile(join(dir, name)));
+    } catch {
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+    if (parsed.kind !== "client") continue;
+    if (typeof parsed.root !== "string" || parsed.root === "") continue;
+    found.push({
+      path: join(dir, name),
+      root: canonicalRoot(parsed.root, options),
+      kind: parsed.kind,
+      runtime: typeof parsed.runtime === "string" && parsed.runtime !== "" ? parsed.runtime : null,
+    });
+  }
+  return found;
+}
+
+/**
+ * The socket path to dial for the pi working directory `cwd`.
+ *
+ * @param {Record<string, string | undefined>} env the process environment
+ * @param {string} cwd the pi working directory, inside the role workspace
+ * @param {{ readFile?: (path: string) => string, readDir?: (path: string) => string[], realpath?: (path: string) => string, uid?: number | null, runtime?: string }} [options]
+ * @returns {string} an absolute path
+ * @throws {SocketResolutionError} when no client answers for the workspace, or several do
+ */
+export function resolveSocketPath(env, cwd, options = {}) {
+  const injected = typeof env[SOCKET_ENV] === "string" ? env[SOCKET_ENV].trim() : "";
+  if (injected) return injected;
+
+  const dir = runtimeDir(env, options);
+  const here = canonicalRoot(cwd, options);
+  const candidates = listClientRegistrations(env, options);
+
+  // The tree this process runs in answers first: the exact workspace, or the
+  // nearest registered root containing it — the same tree `owner_root` walks up
+  // to in `crates/onlyne-cli/src/socket.rs`, so a pi started in a subdirectory
+  // reaches the client of the workspace it belongs to. Roots containing one
+  // directory form a chain, so the longest one is this tree and never a coin
+  // toss; a second registration of that same tree names the same socket.
+  const covering = candidates.filter((entry) => covers(entry.root, here));
+  if (covering.length > 0) {
+    const nearest = covering.reduce((best, entry) => (entry.root.length > best.root.length ? entry : best));
+    return join(dir, `${workspaceDigest(nearest.root, options)}${SOCKET_SUFFIX}`);
+  }
+
+  // No registered root contains the working directory. The `runtime` field is
+  // the plan's discovery key for an external placement, where one runtime
+  // serves several clients (`docs/v2-PLAN.md` line 289); it stays secondary, so
+  // it is consulted only here, and only a single answer is an answer.
+  const runtime = (options.runtime ?? RUNTIME_NAME).toLowerCase();
+  const matching = candidates.filter((entry) => entry.runtime !== null && entry.runtime.toLowerCase() === runtime);
+  if (matching.length === 1) {
+    return join(dir, `${workspaceDigest(matching[0].root, options)}${SOCKET_SUFFIX}`);
+  }
+  const wanted = join(dir, `${workspaceDigest(here, options)}${REGISTRATION_SUFFIX}`);
+  let seen;
+  if (matching.length > 1) {
+    seen =
+      `and ${matching.length} clients there name runtime ${runtime} — ${describe(matching)} — ` +
+      "so which one serves this session is ambiguous";
+  } else if (candidates.length === 0) {
+    seen = "and the directory holds no client registration";
+  } else {
+    seen = `and the ${candidates.length} client registration(s) there belong to other roots: ${describe(candidates)}`;
+  }
+  throw new SocketResolutionError(
+    `onlyne: no client is registered for ${here}: looked for ${wanted} in ${dir}, ${seen}. ` +
+      "Start that workspace's client, or name the socket with ONLYNE_SOCKET",
+    matching.length > 0 ? matching : candidates,
+  );
+}
+
+/** `true` when `root` is `here` or a directory containing it. */
+function covers(root, here) {
+  return root === here || here.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+
+/** `<path> (root <root>, runtime <runtime>)` per entry, for an error message. */
+function describe(entries) {
+  return entries
+    .map((entry) => `${entry.path} (root ${entry.root}, runtime ${entry.runtime ?? "-"})`)
+    .join(", ");
 }

package/src/socket.test.mjs

@@ -1,79 +1,237 @@
 // 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.
+// The two answers have one order: the path the client injected, then the client
+// the runtime directory's registration files name for this workspace. Nothing
+// falls back to a path inside the tree — v2 binds nothing there, so a test that
+// expected `<workspace>/.onlyne/run/s` would pin a socket no daemon holds.
 
 import assert from "node:assert/strict";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, 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";
+import {
+  SOCKET_ENV,
+  SocketResolutionError,
+  canonicalRoot,
+  listClientRegistrations,
+  registrationPath,
+  resolveSocketPath,
+  runtimeDir,
+  socketPath,
+  workspaceDigest,
+} 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-"));
+/** One temp directory, removed after the test. */
+function scratch(prefix) {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
   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");
+/** One temp runtime directory holding the registrations written into it. */
+function runtime(registrations = []) {
+  const dir = scratch("pi-onlyne-runtime-");
+  for (const { name, body } of registrations) {
+    writeFileSync(join(dir, name), typeof body === "string" ? body : JSON.stringify(body));
+  }
+  return dir;
+}
+
+/** A registration file's name for `root`, the leaf `onlyne-wire` derives. */
+function registrationName(root) {
+  return `${workspaceDigest(root)}.json`;
+}
+
+/** The registration of one client whose sessions run under `runtime`. */
+function client(root, runtimeName = "pi") {
+  // The writer's spelling is the canonical one (`RegistrationFile::new`).
+  return { kind: "client", role: "planner", root: canonicalRoot(root), pid: 4242, version: "0.2.0", runtime: runtimeName };
+}
+
+/** The env a client-spawned session carries, with the runtime directory pinned. */
+function envFor(dir, extra = {}) {
+  return { ONLYNE_RUNTIME_DIR: dir, ...extra };
+}
+
+/** The refusal one resolve raises, which `assert.throws` does not hand back. */
+function refusal(resolve) {
+  try {
+    resolve();
+  } catch (error) {
+    assert.ok(error instanceof SocketResolutionError, `expected a SocketResolutionError, got ${error}`);
+    return error;
+  }
+  assert.fail("expected a SocketResolutionError");
+}
 
 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));
+  const workspace = scratch("pi-onlyne-ws-");
+  const dir = runtime([{ name: registrationName(workspace), body: client(workspace) }]);
+  const injected = join(dir, "some-other.sock");
+
+  assert.equal(resolveSocketPath(envFor(dir, { ONLYNE_SOCKET: injected }), workspace), injected);
   // A value wrapped in space names the same socket.
-  assert.equal(resolveSocketPath({ ONLYNE_SOCKET: `  ${SERVED}  ` }, dir), SERVED);
+  assert.equal(resolveSocketPath(envFor(dir, { ONLYNE_SOCKET: `  ${injected}  ` }), workspace), injected);
+  // It outranks a registration that answers for the same workspace.
+  assert.notEqual(injected, socketPath(workspace, envFor(dir)));
+
+  // A variable holding nothing answers nothing, so the registrations decide.
+  assert.equal(resolveSocketPath(envFor(dir, { ONLYNE_SOCKET: "   " }), workspace), socketPath(workspace, envFor(dir)));
+});
+
+test("the digest is the reference's, sixteen hex characters of sha256 over the canonical root", () => {
+  // Vectors from `crates/onlyne-wire/src/socket.rs::workspace_digest` and
+  // `crates/onlyne-testkit/e2e/lib.sh::workspace_digest`: python3 -c
+  // 'import hashlib;print(hashlib.sha256(PATH.encode()).hexdigest()[:16])'.
+  assert.equal(workspaceDigest("/srv/onlyne"), "8bc9cceef0a8586d");
+  assert.equal(workspaceDigest("/srv/onlyne/workspace"), "add3dd4d5bd2c91a");
+  // Separators become `/` and the spelling is lowercased before hashing.
+  assert.equal(workspaceDigest("/SRV/Onlyne"), "8bc9cceef0a8586d");
 
-  // 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));
+  // A root that exists is canonicalized, so one tree reached through two
+  // spellings digests once.
+  const real = scratch("pi-onlyne-ws-");
+  const link = join(scratch("pi-onlyne-link-"), "ws");
+  symlinkSync(real, link);
+  assert.equal(workspaceDigest(link), workspaceDigest(real));
 });
 
-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("the runtime directory is the override, or /tmp/onlyne-<uid>", () => {
+  assert.equal(runtimeDir({ ONLYNE_RUNTIME_DIR: "/tmp/pinned" }, { uid: 501 }), "/tmp/pinned");
+  // An empty override is no override; a whitespace-only one is the reference's
+  // business, and it is a directory name there rather than an empty value.
+  assert.equal(runtimeDir({ ONLYNE_RUNTIME_DIR: "" }, { uid: 501 }), "/tmp/onlyne-501");
+  assert.equal(runtimeDir({}, { uid: 501 }), "/tmp/onlyne-501");
+  assert.equal(runtimeDir({}, { uid: 0 }), "/tmp/onlyne-0");
 });
 
-test("a workspace with no marker keeps the canonical spelling", () => {
-  const dir = workspace();
-  assert.equal(resolveSocketPath({}, dir), join(dir, ".onlyne", "run", "s"));
+test("the socket is derived from the workspace root in the runtime directory", () => {
+  const workspace = scratch("pi-onlyne-ws-");
+  const dir = runtime([{ name: registrationName(workspace), body: client(workspace) }]);
+  const env = envFor(dir);
+
+  const resolved = resolveSocketPath(env, workspace);
+  assert.equal(resolved, join(dir, `${workspaceDigest(workspace)}.sock`));
+  assert.equal(resolved, socketPath(workspace, env));
+  assert.equal(registrationPath(workspace, env), join(dir, registrationName(workspace)));
+  // Nothing inside the workspace serves anything in v2.
+  assert.ok(!resolved.startsWith(workspace));
+
+  // The override moves the whole derivation, socket and registration alike.
+  const pinned = runtime([{ name: registrationName(workspace), body: client(workspace) }]);
+  assert.equal(resolveSocketPath(envFor(pinned), workspace), join(pinned, `${workspaceDigest(workspace)}.sock`));
+  assert.equal(socketPath(workspace, envFor(pinned)), join(pinned, `${workspaceDigest(workspace)}.sock`));
+});
+
+test("a pi started below the workspace root resolves the workspace's client", () => {
+  const workspace = scratch("pi-onlyne-ws-");
+  const nested = join(workspace, ".onlyne", "workspaces", "topology", "planner");
+  mkdirSync(nested, { recursive: true });
+  const dir = runtime([{ name: registrationName(workspace), body: client(workspace) }]);
+
+  assert.equal(resolveSocketPath(envFor(dir), nested), socketPath(workspace, envFor(dir)));
+  // The nearest registered root wins over one that only contains it, so a
+  // client of the outer tree never answers for a session inside the inner one.
+  const outer = scratch("pi-onlyne-ws-");
+  const inner = join(outer, "inner");
+  mkdirSync(inner);
+  const both = runtime([
+    { name: registrationName(outer), body: client(outer) },
+    { name: registrationName(inner), body: client(inner) },
+  ]);
+  assert.equal(resolveSocketPath({ ONLYNE_RUNTIME_DIR: both }, inner), socketPath(inner, { ONLYNE_RUNTIME_DIR: both }));
+});
+
+test("a registration that is not this plugin's surface is not an answer", () => {
+  const workspace = scratch("pi-onlyne-ws-");
+  // A server root's admin socket speaks the admin vocabulary, not the adapter
+  // protocol, and `list_registrations` would hand it over just the same.
+  const dir = runtime([
+    { name: registrationName(workspace), body: { kind: "server", role: null, root: workspace, pid: 1, version: "0.2.0", runtime: null } },
+    { name: "broken.json", body: "{ not a registration" },
+    { name: "notes.txt", body: "not a registration at all" },
+    { name: "rootless.json", body: { kind: "client", pid: 2 } },
+  ]);
+
+  assert.deepEqual(listClientRegistrations(envFor(dir)), []);
+  const error = refusal(() => resolveSocketPath(envFor(dir), workspace));
+  assert.match(error.message, /no client is registered for/);
+  assert.match(error.message, new RegExp(registrationName(workspace).replace(/\./g, "\\.")));
+  assert.match(error.message, /holds no client registration/);
+});
+
+test("a refused resolution names what was looked for", () => {
+  const workspace = scratch("pi-onlyne-ws-");
+  const empty = scratch("pi-onlyne-runtime-");
+  const nowhere = refusal(() => resolveSocketPath(envFor(empty), workspace));
+  assert.match(nowhere.message, new RegExp(workspaceDigest(workspace)));
+  assert.match(nowhere.message, new RegExp(empty));
+  assert.deepEqual(nowhere.candidates, []);
+
+  // Another tree's client is reported by name rather than dialled.
+  // An ACP client is another runtime's, so it is not this plugin's to dial and
+  // the refusal names it instead.
+  const other = scratch("pi-onlyne-ws-");
+  const dir = runtime([{ name: registrationName(other), body: client(other, "acp") }]);
+  const elsewhere = refusal(() => resolveSocketPath(envFor(dir), workspace));
+  assert.match(elsewhere.message, new RegExp(canonicalRoot(other).replace(/\./g, "\\.")));
+  assert.match(elsewhere.message, /belong to other roots/);
+  assert.match(elsewhere.message, /runtime acp/);
 });
 
-test("a marker that is empty, relative, or unreadable falls through silently", () => {
-  const empty = workspace("");
-  assert.equal(resolveSocketPath({}, empty), join(empty, SOCKET_RELATIVE_PATH));
+test("several matching clients are refused, not picked from", () => {
+  const workspace = scratch("pi-onlyne-ws-");
+  const first = scratch("pi-onlyne-ws-");
+  const second = scratch("pi-onlyne-ws-");
 
-  const relative = workspace("run/s");
-  assert.equal(resolveSocketPath({}, relative), join(relative, SOCKET_RELATIVE_PATH));
+  // Two clients run pi sessions and neither root contains this workspace: the
+  // external placement's discovery key has no single answer.
+  const dir = runtime([
+    { name: registrationName(first), body: client(first) },
+    { name: registrationName(second), body: client(second) },
+  ]);
+  const error = refusal(() => resolveSocketPath(envFor(dir), workspace));
+  assert.match(error.message, /name runtime pi/);
+  assert.match(error.message, /ambiguous/);
+  assert.equal(error.candidates.length, 2);
+
+  // Two registrations naming one tree are not ambiguous: the socket is the
+  // tree's digest, so both name one path and deduping is not a pick.
+  const duplicated = runtime([
+    { name: registrationName(workspace), body: client(workspace) },
+    { name: "hand-written.json", body: client(workspace) },
+  ]);
+  assert.equal(resolveSocketPath(envFor(duplicated), workspace), socketPath(workspace, envFor(duplicated)));
+
+  // One runtime match with no root of its own is the plan's external case, and
+  // one answer is an answer.
+  const single = runtime([{ name: registrationName(first), body: client(first) }]);
+  const sole = resolveSocketPath(envFor(single), workspace);
+  assert.equal(sole, socketPath(first, envFor(single)));
+  assert.equal(sole, join(single, `${workspaceDigest(first)}.sock`));
+});
 
-  // 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));
+test("a registration read through the injected filesystem names the same socket", () => {
+  const workspace = "/srv/onlyne/workspace";
+  const dir = "/tmp/onlyne-501";
+  const options = {
+    uid: 501,
+    realpath: (path) => path,
+    readDir: () => [registrationName(workspace), "unrelated.json"],
+    readFile: (path) => (path.endsWith(registrationName(workspace)) ? JSON.stringify(client(workspace)) : "{}"),
+  };
 
-  // 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));
+  assert.equal(
+    resolveSocketPath({ ONLYNE_RUNTIME_DIR: dir }, workspace, options),
+    `${dir}/add3dd4d5bd2c91a.sock`,
+  );
+  // The env is what names the socket a client injected, and it is still first.
+  assert.equal(resolveSocketPath({ ONLYNE_RUNTIME_DIR: dir, [SOCKET_ENV]: "/tmp/served" }, workspace, options), "/tmp/served");
 });

package/relay.toml.example

@@ -1,18 +0,0 @@
-# Manual-installation escape hatch for the relay guard.
-#
-# 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.
-#
-# relay_required wins over relay_count when both are present.
-
-# 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