pi-onlyne 0.8.1 → 1.0.0

package/src/protocol.test.mjs

@@ -0,0 +1,296 @@
+// Protocol vocabulary tests. Every assertion about a frame's shape is anchored
+// either on a wire vector the Rust encoder produced or on the reducer rules in
+// `crates/onlyne-session/src/lifecycle.rs`.
+
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+import {
+  IMAGE_DATA_MAX_BYTES,
+  MAX_HEAD_CHARS,
+  PROTOCOL_VERSION,
+  SEQ_BASE,
+  completeReport,
+  headOf,
+  heartbeatReport,
+  helloArgs,
+  hostBinding,
+  imagePart,
+  injectionText,
+  normalizeOutcome,
+  observationFor,
+  readPluginVersion,
+  readyReport,
+  sendEnvelope,
+  stdinTaskText,
+  welcomeFrom,
+} from "./protocol.mjs";
+
+const VECTOR_DIR = fileURLToPath(new URL("../../../crates/onlyne-proto/tests/wire_vectors/", import.meta.url));
+const hasVectors = existsSync(VECTOR_DIR);
+const vectorFrame = (name) => JSON.parse(JSON.parse(readFileSync(`${VECTOR_DIR}${name}`, "utf8")).frame);
+const ASSIGN = () => vectorFrame("adapter_host_assign.json");
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+test("hello carries the package version and a flat agent mount", () => {
+  assert.equal(readPluginVersion(), packageJson.version);
+  const args = helloArgs({
+    role: "planner",
+    session: "8b1c",
+    taskId: "11111111-1111-4111-8111-111111111111",
+    pid: 4212,
+    capabilities: ["register", "report", "inject", "recycle"],
+  });
+  assert.deepEqual(args, {
+    protocol: PROTOCOL_VERSION,
+    plugin: "pi-onlyne",
+    version: packageJson.version,
+    kind: "agent",
+    capabilities: ["register", "report", "inject", "recycle"],
+    mount: {
+      role: "planner",
+      session: "8b1c",
+      task_id: "11111111-1111-4111-8111-111111111111",
+      pid: 4212,
+    },
+  });
+});
+
+test("hello names exactly the keys the host's own vector names", { skip: !hasVectors }, () => {
+  const reference = vectorFrame("adapter_plugin_hello_plan_example.json");
+  const ours = { op: "hello", args: helloArgs({ role: "planner", session: "8b1c", capabilities: ["register"] }) };
+  assert.deepEqual(Object.keys(ours.args).sort(), Object.keys(reference.args).sort());
+  assert.deepEqual(Object.keys(ours.args.mount).sort(), ["role", "session"]);
+  assert.equal(reference.args.mount.role, ours.args.mount.role);
+  assert.equal(ours.args.kind, reference.args.kind);
+  assert.equal(ours.args.protocol, reference.args.protocol);
+});
+
+test("welcome parses the host's response body and rejects junk", () => {
+  const args = {
+    protocol: 1,
+    role: "planner",
+    session_id: "s1",
+    generation: 1,
+    prose: "Read the incoming task",
+    server: { connected: true, cluster: "local", name: "server" },
+    host_capabilities: ["probe", "recycle"],
+  };
+  const welcome = welcomeFrom({ op: "welcome", args });
+  assert.deepEqual(welcome, {
+    protocol: 1,
+    role: "planner",
+    sessionId: "s1",
+    generation: 1,
+    prose: "Read the incoming task",
+    server: { connected: true, cluster: "local", name: "server" },
+    hostCapabilities: ["probe", "recycle"],
+  });
+  assert.deepEqual(welcomeFrom(args)?.role, "planner");
+  assert.equal(welcomeFrom(null), null);
+  assert.equal(welcomeFrom({ op: "welcome", args: { prose: "x" } }), null);
+  assert.deepEqual(welcomeFrom({ op: "welcome", args: { role: "builder" } }), {
+    protocol: 1,
+    role: "builder",
+    sessionId: null,
+    generation: 1,
+    prose: "",
+    server: null,
+    hostCapabilities: [],
+  });
+});
+
+test("ready matches the host's ready vector, which relays a cluster this plugin never speaks for", { skip: !hasVectors }, () => {
+  const reference = vectorFrame("adapter_plugin_report.json");
+  assert.equal(reference.op, "report");
+  assert.equal(reference.args.kind, "ready");
+  const { cluster_ref: relayed, ...local } = reference.args.data;
+  assert.equal(relayed, "cluster-b");
+  const ours = readyReport({ taskId: local.task_id, sessionId: local.session_id, generation: local.generation, seq: local.seq });
+  assert.deepEqual(ours, { kind: "ready", data: local });
+});
+test("heartbeat carries a full legal observation", () => {
+  const report = heartbeatReport({ taskId: "t1", generation: 2, seq: SEQ_BASE + 7, agent: "running" });
+  assert.equal(report.kind, "heartbeat");
+  assert.equal(report.data.task_id, "t1");
+  assert.equal(report.data.seq, SEQ_BASE + 7);
+  assert.deepEqual(report.data.observed, {
+    version: { generation: 2, seq: SEQ_BASE + 7 },
+    generation_live: true,
+    isolate_after: 1,
+    terminate_after: 3,
+    mismatch_count: 0,
+    agent: "running",
+    delivery: "none",
+    resource: "attached",
+    recovery: "none",
+    outcome: "pending",
+    public: "working",
+  });
+});
+
+test("every observation is a state tuple the reducer calls legal", () => {
+  // Mirrors onlyne-session's `project`: running works, idle/ready wait, booting creates.
+  const expected = { booting: "created", ready: "idle", running: "working", idle: "idle", gone: "created" };
+  for (const [agent, projected] of Object.entries(expected)) {
+    const observed = observationFor(agent, { generation: 1, seq: 1 });
+    assert.equal(observed.public, projected, `agent=${agent}`);
+    assert.notEqual(observed.isolate_after, 0);
+    assert.notEqual(observed.terminate_after, 0);
+    assert.equal(observed.outcome, "pending");
+    assert.equal(observed.delivery, "none");
+    assert.equal(observed.recovery, "none");
+  }
+});
+
+const PANE_KEY = "45e603f7-0772-48aa-bcf6-832272747713:b6d067b6-9255-4f5c-a13f-24f194ea0560";
+const PANE_ENV = {
+  ORCA_PANE_KEY: PANE_KEY,
+  ORCA_TAB_ID: "45e603f7-0772-48aa-bcf6-832272747713",
+  ORCA_LEAF_ID: "b6d067b6-9255-4f5c-a13f-24f194ea0560",
+  ORCA_TERMINAL_HANDLE: "term_1",
+};
+
+test("hostBinding names the Orca pane the environment exports", () => {
+  // The shape is `onlyne-session`'s `HostRef`: `{"orca":{…}}`, so the Rust side
+  // deserialises the observation without a second translation.
+  assert.deepEqual(hostBinding(PANE_ENV), {
+    orca: {
+      pane_key: PANE_KEY,
+      tab_id: "45e603f7-0772-48aa-bcf6-832272747713",
+      leaf_id: "b6d067b6-9255-4f5c-a13f-24f194ea0560",
+      handle: "term_1",
+    },
+  });
+});
+
+test("hostBinding reads the ids out of the pane key and invents nothing", () => {
+  // The pane key is `<tab_id>:<leaf_id>`; the handle is a separate export, and
+  // a missing one is absent rather than empty.
+  assert.deepEqual(hostBinding({ ORCA_PANE_KEY: PANE_KEY }), {
+    orca: {
+      pane_key: PANE_KEY,
+      tab_id: "45e603f7-0772-48aa-bcf6-832272747713",
+      leaf_id: "b6d067b6-9255-4f5c-a13f-24f194ea0560",
+    },
+  });
+  // An explicit id outranks the key's own spelling of it.
+  const explicit = hostBinding({ ...PANE_ENV, ORCA_TAB_ID: "aaaa1111-1111-4111-8111-111111111111" });
+  assert.equal(explicit.orca.tab_id, "aaaa1111-1111-4111-8111-111111111111");
+  assert.equal(explicit.orca.pane_key, "aaaa1111-1111-4111-8111-111111111111:b6d067b6-9255-4f5c-a13f-24f194ea0560");
+});
+
+test("hostBinding is null when the environment names no pane", () => {
+  assert.equal(hostBinding({}), null, "a plain shell is not in a pane");
+  assert.equal(hostBinding(undefined), null);
+  // A pane key without a leaf names no pane, and one id alone is not a pane.
+  assert.equal(hostBinding({ ORCA_PANE_KEY: "not-a-pane-key" }), null);
+  assert.equal(hostBinding({ ORCA_TAB_ID: "tab-only" }), null);
+});
+
+test("observationFor attaches the host only when there is one", () => {
+  const bare = observationFor("running", { generation: 1, seq: 2 });
+  assert.equal("host" in bare, false, "a tuple without a pane carries no host key");
+
+  const hosted = observationFor("running", { generation: 1, seq: 2, host: hostBinding(PANE_ENV) });
+  assert.deepEqual(hosted.host, hostBinding(PANE_ENV));
+  // The binding rides beside the dimensions: the tuple is still the same state.
+  const { host, ...dimensions } = hosted;
+  assert.deepEqual(dimensions, bare);
+});
+
+test("heartbeatReport carries the host inside observed", () => {
+  const report = heartbeatReport({ taskId: "t1", generation: 1, seq: SEQ_BASE + 1, agent: "idle", host: hostBinding(PANE_ENV) });
+  assert.equal(report.data.observed.host.orca.pane_key, PANE_KEY);
+  assert.equal(report.data.observed.agent, "idle");
+  assert.equal(
+    "host" in heartbeatReport({ taskId: "t1", generation: 1, seq: SEQ_BASE + 2, agent: "idle" }).data.observed,
+    false
+  );
+});
+
+test("a completion names an outcome and a single-line head", () => {
+  assert.deepEqual(completeReport({ taskId: "t1", outcome: "failed", head: "broke\non line two" }), {
+    kind: "complete",
+    data: { task_id: "t1", outcome: "failed", head: "broke on line two" },
+  });
+  // No head key at all when there is nothing to summarise.
+  assert.deepEqual(completeReport({ taskId: "t1", outcome: "done", head: "   " }), {
+    kind: "complete",
+    data: { task_id: "t1", outcome: "done" },
+  });
+  assert.equal(completeReport({ taskId: "t1", outcome: "weird" }).data.outcome, "done");
+  assert.equal(normalizeOutcome(undefined), "done");
+  assert.equal(normalizeOutcome("cancelled"), "cancelled");
+});
+
+test("the ledger head is capped at the plan's 200 characters", () => {
+  assert.equal(MAX_HEAD_CHARS, 200);
+  assert.equal(headOf("x".repeat(500)).length, 200);
+  assert.equal(headOf("  spaced   out \n text "), "spaced out text");
+  assert.equal(headOf(undefined), "");
+});
+
+test("an assignment becomes one message naming its origin and payload", { skip: !hasVectors }, () => {
+  const assign = ASSIGN().args;
+  const text = injectionText({ assign, proseIsNew: true });
+  assert.match(text, /^\[onlyne\] task 11111111-1111-4111-8111-111111111111 from role:planner \(kind task\)/);
+  assert.match(text, /\[onlyne\] role prose from the spec:\nRead the incoming task/);
+  assert.match(text, /\nbuild it\n?$/);
+
+  const repeat = injectionText({ assign, proseIsNew: false });
+  assert.doesNotMatch(repeat, /role prose from the spec/);
+  assert.match(repeat, /build it/);
+});
+
+test("an empty-bodied assignment still produces an instruction", () => {
+  const text = injectionText({
+    assign: { task_id: "t9", envelope: { id: "e9", kind: "note", from: { gateway: { gateway: "fg1", channel: "fake", conversation: "c1" } }, body: {} } },
+    proseIsNew: false,
+    attachmentPaths: ["/ws/.onlyne/tmp/attachments/a.png"],
+  });
+  assert.match(text, /from gateway:fg1:fake:c1/);
+  assert.match(text, /the task carried no text/);
+  assert.match(text, /\/ws\/\.onlyne\/tmp\/attachments\/a\.png/);
+});
+
+test("a note carries no idempotency key and a task carries both", { skip: !hasVectors }, () => {
+  const note = sendEnvelope({ from: "planner", to: "builder", kind: "note", text: "ping" });
+  assert.deepEqual(Object.keys(note).sort(), ["admin", "body", "from", "id", "kind", "protocol", "to", "ts"].sort());
+  assert.deepEqual(
+    Object.keys(note).sort(),
+    Object.keys(vectorFrame("adapter_plugin_send_note.json").args).sort(),
+  );
+  assert.match(note.id, UUID_RE);
+  assert.deepEqual(note.from, { role: { role: "planner" } });
+
+  const task = sendEnvelope({ from: "planner", to: "builder", kind: "task", text: "build it" });
+  assert.match(task.op_id, /^o-[0-9a-f-]{36}$/);
+  assert.match(task.causality.task, UUID_RE);
+  assert.equal(task.causality.hop, 0);
+  assert.equal(task.causality.attempt, 0);
+  assert.throws(() => sendEnvelope({ from: "planner", to: "builder" }), /body requires text or image/);
+});
+
+test("images are accepted only in the four core mimes and under the byte ceiling", () => {
+  const part = imagePart({ data: Buffer.from([1, 2, 3]), mime: "image/png", name: "shot.png" });
+  assert.equal(part.data_base64, Buffer.from([1, 2, 3]).toString("base64"));
+  assert.equal(part.mime, "image/png");
+  assert.equal(part.name, "shot.png");
+  assert.throws(() => imagePart({ data: Buffer.from([1]), mime: "image/svg+xml" }), /unsupported/);
+  assert.throws(
+    () => imagePart({ data: Buffer.alloc(IMAGE_DATA_MAX_BYTES + 1), mime: "image/png" }),
+    /exceeds/,
+  );
+});
+
+test("the stdin route recognises only the config_get overload", () => {
+  assert.deepEqual(stdinTaskText({ key: "stdin:do the thing" }), { text: "do the thing" });
+  assert.equal(stdinTaskText({ key: "model.name" }), null);
+  assert.equal(stdinTaskText({}), null);
+  assert.equal(stdinTaskText(undefined), null);
+});

package/src/relay.mjs

@@ -0,0 +1,299 @@
+// The relay guard's policy: `<plugin package dir>/relay.toml`.
+//
+// The guard exists because a session narrated work in progress and then
+// reported `done` with its todos untouched, leaving the downstream writer
+// waiting on a handoff that never happened. The policy below is the minimum a
+// session owes downstream before `onlyne_complete` may end it, expressed in
+// delivery facts only: which roles this session handed something to, never
+// what the text said (that is the critic layer's business, not the adapter's).
+//
+// The file sits next to `package.json`, so the policy travels with the plugin
+// copy a generated workspace carries: `onlyne server generate` copies the
+// package to `<ws>/.onlyne/agent/<pkg-name>/` and `.pi/settings.json` loads
+// that copy (`crates/onlyne-server/src/generate.rs`). It is deliberately not
+// `<ws>/.onlyne/config.toml`: the client parses that file as `ClientConfig`,
+// which is `#[serde(deny_unknown_fields)]` and `additionalProperties: false`
+// (`crates/onlyne-config/src/client.rs`, `schema/config-client.schema.json`),
+// so a plugin-owned key there would make the client refuse to start. A `[local]`
+// fragment merged into it has the same problem.
+//
+// The accepted body is a closed subset of TOML — flat `key = value` lines, the
+// two keys below, one-line arrays of double-quoted strings — because this
+// package parses its own files by hand and the runtime has no npm dependencies.
+// Anything outside the subset is reported on stderr and ignored, the same
+// degrade-don't-disable way `.pi/onlyne.json` behaves. A missing file is the
+// default, which is "no guard": absent policy means the plugin behaves exactly
+// as it did before this module existed.
+//
+//   relay_required = ["writer"]      # these roles must have received a handoff
+//   relay_required_count = 2         # ... or this many distinct downstream roles
+//
+// `relay_required` wins when both are present.
+//
+// The file is the manual installation's escape hatch. A generated workspace
+// carries the same policy in its spec, and the client injects it into every
+// session process it spawns, so the environment comes first:
+//
+//   ONLYNE_RELAY_REQUIRED=writer,auditor   # the spec's `relay_required`
+//   ONLYNE_RELAY_COUNT=2                   # the spec's `relay_count`
+//
+// A variable that is set and unparsable is reported on stderr and ignored, and
+// with nothing usable in the environment the file is read as before.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** File name, resolved next to the plugin's `package.json`. */
+export const RELAY_FILE = "relay.toml";
+
+/** Fixed marker a waived completion's ledger head starts with. */
+export const FORCED_PREFIX = "relay-guard-forced: ";
+
+/** No policy: an empty list and no count, both frozen together. */
+export const DEFAULT_RELAY = Object.freeze({ required: Object.freeze([]), count: null });
+
+/** The client's injected policy variables, filled from the spec's entry. */
+export const RELAY_ENV_REQUIRED = "ONLYNE_RELAY_REQUIRED";
+export const RELAY_ENV_COUNT = "ONLYNE_RELAY_COUNT";
+
+/**
+ * The policy file this module reads by default: beside `package.json`, the way
+ * `protocol.mjs` reads the plugin version.
+ */
+export function relayPath() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", RELAY_FILE);
+}
+
+/**
+ * Whether a loaded policy guards anything: a non-empty list, or a positive
+ * count. A malformed key leaves its own dimension off, so one bad line cannot
+ * silently arm the guard with the wrong rule.
+ *
+ * @param {{ required?: string[], count?: number | null } | null | undefined} config
+ */
+export function relayEnabled(config) {
+  if (!config) return false;
+  if (Array.isArray(config.required) && config.required.length > 0) return true;
+  return Number.isInteger(config.count) && config.count > 0;
+}
+
+/**
+ * Parse one `relay.toml` body.
+ *
+ * @param {string} text
+ * @param {string} [name] file name for diagnostics
+ * @returns {{ required: string[], count: number | null, warning: string | null }}
+ */
+export function parseRelay(text, name = RELAY_FILE) {
+  const config = { required: [], count: null };
+  const warnings = [];
+  const warn = (line, detail) => warnings.push(`${name}:${line}: ${detail}`);
+
+  String(text)
+    .split(/\r?\n/)
+    .forEach((raw, index) => {
+      const line = index + 1;
+      const body = stripComment(raw).trim();
+      if (!body) return;
+      const assignment = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(\S.*)$/.exec(body);
+      if (!assignment) {
+        warn(line, `not a \`key = value\` line (${JSON.stringify(raw.trim())}); ignored`);
+        return;
+      }
+      const [, key, value] = assignment;
+      if (key === "relay_required") {
+        const list = parseStringArray(value);
+        if (list === null) {
+          warn(line, 'relay_required must be one line of double-quoted names, e.g. ["writer"]; ignored');
+          return;
+        }
+        config.required = list;
+        return;
+      }
+      if (key === "relay_required_count") {
+        const count = /^[0-9]+$/.test(value) ? Number(value) : 0;
+        if (count < 1) {
+          warn(line, "relay_required_count must be a positive integer; ignored");
+          return;
+        }
+        config.count = count;
+        return;
+      }
+      warn(line, `unknown key ${JSON.stringify(key)}; ignored`);
+    });
+
+  return { ...config, warning: warnings.length > 0 ? warnings.join("; ") : null };
+}
+
+/**
+ * The policy the client injected from the spec, when it injected one.
+ *
+ * The list is one comma-joined variable, in the order the spec wrote it; blank
+ * entries are dropped, so a stray comma is not a role name. A variable that is
+ * set but unparsable is reported and ignored rather than adopted, which keeps a
+ * typo from arming the guard with a rule nobody wrote — and `specified` then
+ * says the environment supplied nothing, so the file still gets its turn.
+ *
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {{ required: string[], count: number | null, specified: boolean, warning: string | null }}
+ */
+export function envRelay(env = process.env) {
+  const warnings = [];
+  let required = null;
+  let count = null;
+
+  const rawRequired = env[RELAY_ENV_REQUIRED];
+  if (rawRequired !== undefined) {
+    const names = String(rawRequired)
+      .split(",")
+      .map((name) => name.trim())
+      .filter(Boolean);
+    if (names.length > 0) required = names;
+    else warnings.push(`${RELAY_ENV_REQUIRED}: no role names in ${JSON.stringify(rawRequired)}; ignored`);
+  }
+
+  const rawCount = env[RELAY_ENV_COUNT];
+  if (rawCount !== undefined) {
+    const text = String(rawCount).trim();
+    const parsed = /^[0-9]+$/.test(text) ? Number(text) : 0;
+    if (parsed > 0) count = parsed;
+    else warnings.push(`${RELAY_ENV_COUNT} must be a positive integer, got ${JSON.stringify(rawCount)}; ignored`);
+  }
+
+  return {
+    required: required ?? [],
+    count,
+    specified: required !== null || count !== null,
+    warning: warnings.length > 0 ? warnings.join("; ") : null,
+  };
+}
+
+/**
+ * Read the policy: what the client injected from the spec first, then the file
+ * beside `package.json`.
+ *
+ * `source` names the winner, and `present` answers the narrower question the
+ * file itself raises: the environment winning means the file was never read, so
+ * a stale `relay.toml` cannot outlive the spec entry that replaced it.
+ *
+ * @param {{ readFile?: (path: string) => string, path?: string, env?: Record<string, string | undefined> }} [options]
+ * @returns {{ required: string[], count: number | null, path: string, present: boolean, source: "env" | "file" | "none", warning: string | null }}
+ */
+export function loadRelay(options = {}) {
+  const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+  const path = options.path ?? relayPath();
+  const injected = envRelay(options.env ?? process.env);
+  if (injected.specified) {
+    return {
+      required: injected.required,
+      count: injected.count,
+      path,
+      present: false,
+      source: "env",
+      warning: injected.warning,
+    };
+  }
+  let raw;
+  try {
+    raw = readFile(path);
+  } catch {
+    return {
+      ...DEFAULT_RELAY,
+      path,
+      present: false,
+      source: "none",
+      warning: injected.warning,
+    };
+  }
+  const parsed = parseRelay(raw, path);
+  return {
+    required: parsed.required,
+    count: parsed.count,
+    path,
+    present: true,
+    source: "file",
+    warning: [injected.warning, parsed.warning].filter(Boolean).join("; ") || null,
+  };
+}
+
+/**
+ * The verdict for one `onlyne_complete`, as a refusal message or `null`.
+ *
+ * `delivered` is the set of roles this session's own successful `onlyne_send`
+ * calls reached. List mode is literal: every named role must be in it. Count
+ * mode counts distinct downstream roles, so a send to this role itself and a
+ * send back to the role that assigned the task (the upstream) do not count —
+ * neither of them hands work further down the cluster.
+ *
+ * @param {{ required?: string[], count?: number | null } | null} config
+ * @param {Iterable<string>} delivered
+ * @param {{ role?: string | null, upstream?: string | null }} [context]
+ * @returns {string | null}
+ */
+export function relayRefusal(config, delivered, context = {}) {
+  if (!relayEnabled(config)) return null;
+  const sent = new Set([...delivered].map((name) => String(name)));
+
+  if (Array.isArray(config.required) && config.required.length > 0) {
+    const missing = config.required.filter((name) => !sent.has(name));
+    if (missing.length === 0) return null;
+    return refusalText(
+      `missing handoff to: ${missing.join(", ")}`,
+      `this session delivered to: ${listOf([...sent])}`,
+    );
+  }
+
+  const { role = null, upstream = null } = context;
+  const downstream = [...sent].filter((name) => name !== role && name !== upstream);
+  if (downstream.length >= config.count) return null;
+  return refusalText(
+    `missing handoff: ${config.count - downstream.length} of ${config.count} required distinct downstream roles`,
+    `delivered downstream: ${listOf(downstream)}`,
+  );
+}
+
+/** The one refusal sentence: what is missing, what exists, and the way out. */
+function refusalText(shortfall, evidence) {
+  return (
+    `relay guard: ${shortfall} (${evidence}); ` +
+    "send the missing edge with onlyne_send, then call onlyne_complete again — or call it with " +
+    'force:true and a non-empty reason to waive the guard and stamp the ledger head with ' +
+    `"${FORCED_PREFIX}<reason>"`
+  );
+}
+
+/** A comma-joined list, or `none` when there is nothing to name. */
+function listOf(names) {
+  return names.length > 0 ? names.join(", ") : "none";
+}
+
+/** Everything before an unquoted `#`; the subset has no multi-line strings. */
+function stripComment(line) {
+  let quoted = false;
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    if (char === '"' && line[index - 1] !== "\\") quoted = !quoted;
+    else if (char === "#" && !quoted) return line.slice(0, index);
+  }
+  return line;
+}
+
+/** One line of double-quoted strings, or `null` for anything else. */
+function parseStringArray(body) {
+  const trimmed = body.trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return null;
+  const items = [];
+  let rest = trimmed.slice(1, -1).trim();
+  if (rest === "") return items;
+  for (;;) {
+    const item = /^"((?:[^"\\]|\\.)*)"\s*/.exec(rest);
+    if (!item) return null;
+    items.push(item[1].replace(/\\(.)/g, "$1"));
+    rest = rest.slice(item[0].length).trimStart();
+    if (rest === "") return items;
+    if (!rest.startsWith(",")) return null;
+    rest = rest.slice(1).trimStart();
+    if (rest === "") return null; // a trailing comma is not TOML
+  }
+}