@openviking/opencode-plugin 2026.9.10 → 2026.9.21

package/lib/shared/uri-guard.mjs

@@ -1,4 +1,8 @@
 // GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+import { readFileSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
 const DEFAULT_URI_KEYS = [
   "filePath",
   "file_path",
@@ -7,7 +11,6 @@ const DEFAULT_URI_KEYS = [
   "uri",
   "target_uri",
   "targetUri",
-  "pattern",
 ];
 
 export function normalizeToolName(value) {
@@ -76,3 +79,172 @@ export function buildGuardMessage(uri, hint = {}) {
   if (example) lines.push(`Example: ${example}`);
   return lines.join("\n");
 }
+
+export function buildGuardNotice(uri, hint = {}) {
+  const lines = [
+    `[OpenViking memory plugin] URI guard: this shell command contains the viking:// URI ${uri}.`,
+    "viking:// URIs are OpenViking virtual paths, not local files, so cat, ls, grep and other file commands cannot open them.",
+    `If you meant to read or search OpenViking content, use ${hint.tool || "the OpenViking MCP tools"} instead.`,
+  ];
+  if (hint.example) lines.push(`Example: ${hint.example}`);
+  lines.push("If the URI is intentional data (an ov CLI argument, an HTTP payload, a search pattern), ignore this notice.");
+  return lines.join("\n");
+}
+
+/** The hints a host gets when it names no table of its own. */
+export const DEFAULT_TOOL_HINTS = {
+  read: {
+    tool: "OpenViking MCP read",
+    example: (uri) => `read(uris="${uri}")`,
+  },
+  glob: {
+    tool: "OpenViking MCP glob or list",
+    example: (uri, input = {}) => (
+      `glob(pattern="${String(input.pattern ?? "**/*").replaceAll('"', '\\"')}", uri="${uri}")`
+    ),
+  },
+  grep: {
+    tool: "OpenViking MCP grep or search",
+    example: (uri, input = {}) => (
+      `grep(uri="${uri}", pattern="${String(input.pattern ?? "").replaceAll('"', '\\"')}")`
+    ),
+  },
+  edit: {
+    tool: "OpenViking MCP edit",
+    example: (uri) => `edit(uri="${uri}", old_string="...", new_string="...")`,
+  },
+  write: {
+    tool: "OpenViking MCP write",
+    example: (uri) => `write(uri="${uri}", content="...")`,
+  },
+  bash: {
+    tool: "OpenViking MCP read or search",
+    example: (uri) => `read(uris="${uri}")`,
+  },
+  runcommand: {
+    tool: "OpenViking MCP read or search",
+    example: (uri) => `read(uris="${uri}")`,
+  },
+  shell: {
+    tool: "OpenViking MCP read or search",
+    example: (uri) => `read(uris="${uri}")`,
+  },
+};
+
+// Tools whose argument is a command line rather than a location. A viking:// URI
+// in one is data (an `ov` argument, an HTTP payload, a grep pattern) as often as
+// a path the model hoped to open, so the command runs and the model gets a notice.
+const SHELL_TOOL_NAMES = new Set(["bash", "shell", "runcommand"]);
+
+// `pattern` is where glob looks but what grep looks for: a grep for the text
+// "viking://" in a local tree is not a path. The generic sweep still reaches
+// glob's pattern.
+const TEXT_ARGS_BY_TOOL = { grep: ["pattern"] };
+
+function resolveGuardedUri(toolName, input, { hints = DEFAULT_TOOL_HINTS } = {}) {
+  const name = normalizeToolName(toolName);
+  const hint = hints[name];
+  if (!hint) return null;
+  const textArgs = TEXT_ARGS_BY_TOOL[name];
+  const uri = findVikingUri(input, DEFAULT_URI_KEYS, textArgs ? [...DEFAULT_CONTENT_KEYS, ...textArgs] : DEFAULT_CONTENT_KEYS);
+  if (!uri) return null;
+  return {
+    uri,
+    shell: SHELL_TOOL_NAMES.has(name),
+    hint: {
+      tool: hint.tool,
+      example: typeof hint.example === "function" ? hint.example(uri, input) : hint.example,
+    },
+  };
+}
+
+/**
+ * The deny decision for one tool call, or null when the call may proceed.
+ *
+ * A file tool whose path is a viking:// URI cannot succeed, and a write would
+ * leave a junk local file, so it is denied. A shell tool is never denied here;
+ * `evaluateUriNotice` covers it. `hints` carries the host's replacement tool
+ * names and example calls, and a tool without a hint is not guarded.
+ */
+export function evaluateUriGuard(toolName, input = {}, opts = {}) {
+  const match = resolveGuardedUri(toolName, input, opts);
+  if (!match || match.shell) return null;
+  return { uri: match.uri, reason: buildGuardMessage(match.uri, match.hint) };
+}
+
+/** The notice for a shell command that carries a viking:// URI, or null. The command still runs. */
+export function evaluateUriNotice(toolName, input = {}, opts = {}) {
+  const match = resolveGuardedUri(toolName, input, opts);
+  if (!match?.shell) return null;
+  return { uri: match.uri, reason: buildGuardNotice(match.uri, match.hint) };
+}
+
+/** The PreToolUse deny envelope claude-code, trae and zcode all read. */
+export function denyHookSpecificOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+/** The PreToolUse notice envelope: no permissionDecision, so the host's own permission flow still runs. */
+export function noticeHookSpecificOutput(reason) {
+  return { hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: reason } };
+}
+
+/** A hook event's tool name and input, under any of the spellings the hosts use. */
+export function readToolEvent(event = {}) {
+  return {
+    toolName: event.tool_name ?? event.toolName ?? event.name ?? event.tool,
+    toolInput: event.tool_input ?? event.toolInput ?? event.input ?? {},
+  };
+}
+
+/** The whole PreToolUse guard: a deny envelope, a notice envelope, or {}. */
+export function preToolUseOutput(event = {}, opts = {}) {
+  const { toolName, toolInput } = readToolEvent(event);
+  const denied = evaluateUriGuard(toolName, toolInput, opts);
+  if (denied) return denyHookSpecificOutput(denied.reason);
+  const notice = evaluateUriNotice(toolName, toolInput, opts);
+  return notice ? noticeHookSpecificOutput(notice.reason) : {};
+}
+
+/** Cursor's beforeReadFile deny envelope. */
+export function denyCursorPermission(reason) {
+  return { permission: "deny", user_message: reason };
+}
+
+function readHookInput() {
+  try {
+    const raw = readFileSync(0, "utf8").trim();
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Run a guard as a hook process: read the event off stdin, print the envelope.
+ *
+ * A guard is also imported by its harness tests, so the body only runs when the
+ * module is the process entrypoint. An empty envelope prints nothing — every
+ * host treats unrecognized or empty output as "no opinion", and one of them
+ * rejects any key it does not know.
+ */
+function isEntrypoint(moduleUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return resolve(process.argv[1]) === fileURLToPath(moduleUrl);
+  }
+}
+
+export function runUriGuardHook(moduleUrl, evaluate) {
+  if (!isEntrypoint(moduleUrl)) return;
+  const output = evaluate(readHookInput());
+  if (Object.keys(output).length > 0) process.stdout.write(`${JSON.stringify(output)}\n`);
+}

package/lib/shared/workspace-config.mjs

@@ -0,0 +1,433 @@
+// GENERATED FROM examples/memory-plugin-shared/lib. DO NOT EDIT.
+/**
+ * Layered workspace configuration.
+ *
+ * A workspace may carry two files under `<root>/.openviking/`: `config.json`,
+ * which the team commits, and `config.local.json`, which stays private. A third
+ * layer lives per machine in the user registry. All three share this schema and
+ * this merge, so there is one set of rules to learn and one to test.
+ *
+ * These files are trusted without a prompt — a hook is non-interactive, and any
+ * approval gate degrades into "run one command per workspace first". What is
+ * refused instead is structural, and costs nobody anything:
+ *
+ *   - connection and credential keys are stripped, loudly. "Which server does
+ *     my data go to" must stay answerable without reading a repository.
+ *   - `${VAR}` is never expanded here. Variable expansion is a property of the
+ *     layer, not of the parser: a committed file that could expand `${HOME}`
+ *     could exfiltrate the environment.
+ *
+ * Everything else a workspace file sets takes effect. What it turns off is
+ * announced rather than blocked.
+ */
+
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
+
+import { WORKSPACE_ENUMS, WORKSPACE_KNOB_MAP, WORKSPACE_RANGES } from "./config-schema.mjs";
+import { CONFIG_DIR_NAME, LOCAL_FILE, TEAM_FILE } from "./workspace-identity.mjs";
+
+/**
+ * `JSON.parse` keeps `__proto__` as an own property, and assigning it walks
+ * into `Object.prototype`. Since `process.env` reads through the prototype
+ * chain and the environment outranks ovcli.conf, one such key in a committed
+ * file would set `OPENVIKING_URL` and `OPENVIKING_API_KEY` for the whole
+ * process — the exact thing every other rule here exists to prevent.
+ */
+const UNSAFE_KEYS = ["__proto__", "constructor", "prototype"];
+
+// Deep enough for any real config; a file can nest far past the stack limit
+// inside the 64 KiB cap, and an overflow here would take out sibling layers.
+const MAX_DEPTH = 32;
+
+export { CONFIG_DIR_NAME, TEAM_FILE, LOCAL_FILE };
+export const CONFIG_VERSION = 1;
+export const MAX_CONFIG_BYTES = 64 * 1024;
+
+/**
+ * Keys no workspace file may set, at any depth. Connection and credentials
+ * belong to ovcli.conf and the environment, full stop — this is the invariant
+ * git spells `protected configuration`.
+ */
+export const FORBIDDEN_KEYS = [
+  "url",
+  "base_url",
+  "mcp_url",
+  "api_key",
+  "bearer_token",
+  "root_api_key",
+  "gateway_token",
+  "oidc_token",
+  "ldap_username",
+  "ldap_password",
+  "account",
+  "account_id",
+  "user",
+  "user_id",
+  "auth_mode",
+  "extra_headers",
+  "credential_source",
+  "cli_config_file",
+  "config_file",
+  // The camelCase spellings the harness loaders use. The projection into
+  // harness knobs is an allowlist, so these could never take effect anyway —
+  // but someone who writes `apiKey` here deserves to be told it was ignored,
+  // not to have it vanish.
+  "baseUrl",
+  "mcpUrl",
+  "apiKey",
+  "bearerToken",
+  "rootApiKey",
+  "gatewayToken",
+  "accountId",
+  "userId",
+  "authMode",
+  "extraHeaders",
+  "credentialSource",
+  "credentialPath",
+  "configPath",
+];
+
+/**
+ * Sections whose keys are the user's own vocabulary, not ours. The ban below is
+ * recursive so no section can smuggle a credential to a consumer that spreads
+ * it into a request — but a free-form map's `user` key is a label, and
+ * mangling it would be a bug, not a defence.
+ */
+export const FREE_FORM_SECTIONS = ["labels"];
+
+/**
+ * The workspace schema is a projection of `config-schema.mjs`: the dotted key,
+ * its enum members and its range all come from the one knob declaration, so a
+ * knob cannot be spelled one way here and another way in the loaders.
+ */
+const ENUMS = WORKSPACE_ENUMS;
+const RANGES = WORKSPACE_RANGES;
+const KNOB_MAP = WORKSPACE_KNOB_MAP;
+
+export const WORKSPACE_SCHEMA_KEYS = Object.keys(KNOB_MAP);
+
+/** -1, 0 or 1 over dotted numeric versions; a non-numeric tail is ignored. */
+function compareVersions(left, right) {
+  const parse = (value) => String(value || "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const a = parse(left);
+  const b = parse(right);
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const diff = (a[i] || 0) - (b[i] || 0);
+    if (diff) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * `min_client_version` warns and never blocks. A committed file that could stop
+ * an older plugin from running would be a denial of service anyone with commit
+ * access could mount, so it says "this was written for a newer client" and the
+ * settings still apply.
+ */
+export function checkMinClientVersion(declared, clientVersion, warnings = []) {
+  const required = String(declared || "").trim();
+  const current = String(clientVersion || "").trim();
+  if (!required || !current) return true;
+  if (compareVersions(current, required) >= 0) return true;
+  warnings.push(
+    `this workspace asks for OpenViking plugin ${required} and this one is ${current}; `
+    + "settings it introduced will be ignored rather than blocking the session",
+  );
+  return false;
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Strip banned keys wherever they appear, collecting one warning per hit. They
+ * are removed rather than rejected: a file is not made unusable by carrying a
+ * key this layer refuses to honour.
+ */
+function stripForbidden(value, banned, warnings, path = "", depth = 0) {
+  if (depth > MAX_DEPTH) throw new RangeError(`nested more than ${MAX_DEPTH} levels at '${path}'`);
+  if (Array.isArray(value)) {
+    return value.map((item, index) => stripForbidden(item, banned, warnings, `${path}[${index}]`, depth + 1));
+  }
+  if (!isPlainObject(value)) return value;
+
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    const here = path ? `${path}.${key}` : key;
+    if (UNSAFE_KEYS.includes(key)) {
+      warnings.push(`ignored '${here}': a config file may not reach the object prototype`);
+      continue;
+    }
+    if (banned.includes(key)) {
+      warnings.push(`ignored '${here}': connection and credential settings belong in ovcli.conf or the environment`);
+      continue;
+    }
+    // Matched on the key itself, not on depth: a registry entry keeps the same
+    // section under `settings.`, and it must not end up stricter than the
+    // committed file it outranks.
+    out[key] = FREE_FORM_SECTIONS.includes(key)
+      ? stripUnsafeOnly(child, warnings, here, depth + 1)
+      : stripForbidden(child, banned, warnings, here, depth + 1);
+  }
+  return out;
+}
+
+/** A free-form section keeps its own vocabulary, minus the prototype keys. */
+function stripUnsafeOnly(value, warnings, path, depth) {
+  return stripForbidden(value, [], warnings, path, depth);
+}
+
+/**
+ * Read one layer file. Every failure is a warning and an empty layer — a hook
+ * must not die because a config file is odd.
+ */
+export function readWorkspaceFile(path, { root = "", layer = "" } = {}) {
+  const warnings = [];
+  const empty = { path, layer, exists: false, data: null, warnings };
+
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch {
+    return empty;
+  }
+  empty.exists = true;
+  if (!stat.isFile()) {
+    warnings.push(`${path} is not a regular file`);
+    return empty;
+  }
+  if (stat.size > MAX_CONFIG_BYTES) {
+    warnings.push(`${path} is larger than ${MAX_CONFIG_BYTES} bytes`);
+    return empty;
+  }
+  // A symlink out of the workspace would let a repository read a file the user
+  // never meant to expose to it.
+  if (root) {
+    try {
+      const rel = relative(realpathSync(root), realpathSync(path));
+      if (!rel || rel.startsWith("..") || isAbsolute(rel)) {
+        warnings.push(`${path} resolves outside the workspace`);
+        return empty;
+      }
+    } catch {
+      warnings.push(`${path} could not be resolved`);
+      return empty;
+    }
+  }
+
+  let parsed;
+  try {
+    // Deliberately bare: no `${VAR}` expansion reaches a workspace file.
+    parsed = JSON.parse(readFileSync(path, "utf-8"));
+  } catch (err) {
+    warnings.push(`${path} is not valid JSON (${err?.message || err})`);
+    return empty;
+  }
+  if (!isPlainObject(parsed)) {
+    warnings.push(`${path} must contain a JSON object`);
+    return empty;
+  }
+  if (parsed.version !== CONFIG_VERSION) {
+    warnings.push(`${path} declares version ${JSON.stringify(parsed.version)}; this client understands ${CONFIG_VERSION}`);
+    return empty;
+  }
+
+  const { version, $schema, min_client_version: minClientVersion, ...rest } = parsed;
+  let data;
+  try {
+    data = stripForbidden(rest, FORBIDDEN_KEYS, warnings);
+  } catch (err) {
+    warnings.push(`${path} is nested too deeply (${err?.message || err})`);
+    return empty;
+  }
+  if (minClientVersion) data.min_client_version = String(minClientVersion);
+
+  return { path, layer, exists: true, data, warnings };
+}
+
+function shadow(provenance, here, value, source) {
+  const previous = provenance[here];
+  const shadowed = previous ? [{ value: previous.value, source: previous.source }, ...previous.shadowed] : [];
+  provenance[here] = { value, source, shadowed };
+  return provenance[here];
+}
+
+function mergeInto(target, source, layer, provenance, path = "", depth = 0) {
+  if (depth > MAX_DEPTH) throw new RangeError(`nested more than ${MAX_DEPTH} levels at '${path}'`);
+  for (const [key, value] of Object.entries(source)) {
+    if (UNSAFE_KEYS.includes(key)) continue;
+    const here = path ? `${path}.${key}` : key;
+
+    if (isPlainObject(value)) {
+      // A section replacing a scalar is still a change of the effective value,
+      // so the scalar has to be recorded as shadowed rather than left standing
+      // in provenance as if it were still in force.
+      if (!isPlainObject(target[key])) {
+        if (target[key] !== undefined) shadow(provenance, here, "(section)", layer);
+        target[key] = {};
+      }
+      mergeInto(target[key], value, layer, provenance, here, depth + 1);
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      // `"!reset"` drops everything the lower layers contributed, the way
+      // EditorConfig's `unset` and git's empty `safe.directory` do.
+      const reset = value[0] === "!reset";
+      const incoming = reset ? value.slice(1) : value;
+      const inheritable = !reset && Array.isArray(target[key]);
+      const merged = inheritable ? [...target[key]] : [];
+      for (const item of incoming) if (!merged.includes(item)) merged.push(item);
+
+      // Only a genuine union credits both layers. A list landing on a scalar,
+      // or on nothing, belongs to this layer alone.
+      const previous = provenance[here];
+      if (inheritable && previous) {
+        provenance[here] = {
+          value: merged,
+          source: [previous.source, layer].filter(Boolean).join(" + "),
+          shadowed: previous.shadowed,
+        };
+      } else {
+        shadow(provenance, here, merged, reset ? `${layer} (reset)` : layer);
+      }
+      target[key] = merged;
+      continue;
+    }
+
+    shadow(provenance, here, value, layer);
+    target[key] = value;
+  }
+}
+
+/**
+ * Merge layers given lowest-precedence first, returning the effective value
+ * plus, for every key, where it came from and what it covered up — the same
+ * question `git config --show-origin --show-scope` answers.
+ */
+export function mergeConfigLayers(layers, warnings = []) {
+  const value = {};
+  const provenance = {};
+  for (const { layer, data } of layers) {
+    if (!isPlainObject(data)) continue;
+    try {
+      mergeInto(value, data, layer, provenance);
+    } catch (err) {
+      // One pathological layer must not take the others down with it.
+      warnings.push(`skipped ${layer}: ${err?.message || err}`);
+    }
+  }
+  return { value, provenance };
+}
+
+function get(object, path) {
+  return path.split(".").reduce((node, key) => (isPlainObject(node) ? node[key] : undefined), object);
+}
+
+function set(object, path, value) {
+  const keys = path.split(".");
+  const last = keys.pop();
+  let node = object;
+  for (const key of keys) {
+    if (!isPlainObject(node[key])) node[key] = {};
+    node = node[key];
+  }
+  node[last] = value;
+}
+
+/**
+ * Clamp numbers and reject unknown enum values, warning once per key.
+ *
+ * A repository can raise a cost knob, so the ceiling is enforced here rather
+ * than trusted; an out-of-range value is clamped instead of rejected so a typo
+ * degrades rather than disables.
+ */
+export function normalizeWorkspaceConfig(value, warnings = []) {
+  for (const [path, { min, max, integer }] of Object.entries(RANGES)) {
+    const raw = get(value, path);
+    if (raw === undefined) continue;
+    // `Number()` turns null, true and [] into finite numbers, which would
+    // silently pin a knob to a bound instead of reporting a bad value.
+    const number = typeof raw === "number" || typeof raw === "string" ? Number(raw) : NaN;
+    if (!Number.isFinite(number)) {
+      warnings.push(`ignored '${path}': ${JSON.stringify(raw)} is not a number`);
+      set(value, path, undefined);
+      continue;
+    }
+    const clamped = Math.min(max, Math.max(min, integer ? Math.floor(number) : number));
+    if (clamped !== number) warnings.push(`clamped '${path}' from ${number} to ${clamped} (allowed ${min}..${max})`);
+    set(value, path, clamped);
+  }
+
+  for (const [path, allowed] of Object.entries(ENUMS)) {
+    if (!allowed) continue;
+    const raw = get(value, path);
+    if (raw === undefined) continue;
+    if (!allowed.includes(raw)) {
+      warnings.push(`ignored '${path}': ${JSON.stringify(raw)} is not one of ${allowed.join(", ")}`);
+      set(value, path, undefined);
+    }
+  }
+  return value;
+}
+
+/**
+ * Flatten the merged workspace config into the flat knobs a harness loader
+ * reads, so the new layers slot in exactly where the ovcli `plugin` section
+ * already does and everything downstream — including the env vars that still
+ * win — keeps working unchanged.
+ */
+export function projectWorkspaceSettings(value) {
+  const settings = {};
+  for (const [path, knob] of Object.entries(KNOB_MAP)) {
+    const raw = get(value, path);
+    if (raw !== undefined) settings[knob] = raw;
+  }
+  return settings;
+}
+
+export function workspaceConfigPaths(root) {
+  if (!root) return [];
+  const dir = join(root, CONFIG_DIR_NAME);
+  return [
+    { layer: `${TEAM_FILE} (workspace)`, path: join(dir, TEAM_FILE) },
+    { layer: `${LOCAL_FILE} (workspace)`, path: join(dir, LOCAL_FILE) },
+  ];
+}
+
+/**
+ * The two workspace-file layers, lowest precedence first. Callers stack the
+ * registry above these and the ovcli.conf plugin section below them.
+ */
+export function loadWorkspaceLayers(root, { clientVersion = "" } = {}) {
+  const warnings = [];
+  const layers = [];
+  for (const { layer, path } of workspaceConfigPaths(root)) {
+    const file = readWorkspaceFile(path, { root, layer });
+    warnings.push(...file.warnings);
+    if (!file.data) continue;
+    const { min_client_version: declared, ...data } = file.data;
+    checkMinClientVersion(declared, clientVersion, warnings);
+    layers.push({ layer, data, path });
+  }
+  return { layers, warnings };
+}
+
+/**
+ * Settings a workspace file turned off. Announced at session start and in
+ * doctor, because trusting the file is a decision the user should be able to
+ * see rather than one made silently on their behalf.
+ */
+export function announcedOverrides(provenance) {
+  const announced = [];
+  for (const [key, entry] of Object.entries(provenance)) {
+    const fromWorkspace = String(entry.source || "").includes("(workspace)");
+    if (!fromWorkspace) continue;
+    if (entry.value === false || key === "peer.id" || key === "peer.source" || key.startsWith("bypass.")) {
+      announced.push({ key, value: entry.value, source: entry.source });
+    }
+  }
+  return announced;
+}

package/lib/shared/workspace-peer.mjs

@@ -40,6 +40,69 @@ export const DEFAULT_PEER_SOURCE = "git";
 
 const VARIABLE_RE = /\{([a-z_]+)\}/g;
 
+/**
+ * Layers `resolvePluginPeerId` must not read off the merged settings, because
+ * each has a rank of its own: the environment ranks above every file, and
+ * ov.conf's harness block ranks below all of them.
+ */
+const PEER_LAYERS_RANKED_SEPARATELY = new Set(["env", "ov.conf"]);
+
+function trimmed(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * The peer some layer named, in the one order every harness follows.
+ *
+ * Both halves of a loader's configuration carry a peer: `resolveSettings()`
+ * reads the workspace file, the machine registry and ovcli.conf's `plugin`
+ * section, while the credential chain ends in ovcli.conf's `actor_peer_id`. The
+ * more specific layer wins, so a `peerId` written for this harness outranks the
+ * account-wide actor peer — codex resolved it that way and opencode and pi
+ * resolved it the other way round, which meant one ovcli.conf produced two
+ * different peers depending on which host read it.
+ *
+ * ov.conf's harness block, where this tuning used to live, stays at the bottom.
+ * It gets its own rank rather than riding the credential chain, which drops it
+ * entirely once the credentials are pinned to ovcli.conf.
+ *
+ * `OPENVIKING_PEER_ID` still outranks every file, except when the credentials
+ * are pinned to ovcli.conf, where the environment is meant not to apply at all.
+ * A host that names a peer itself (dsh's cordis patch) outranks all of them.
+ *
+ * Returns "" when nobody named one, which is what makes
+ * `resolveEffectivePeerId()` derive one from `peer.source`.
+ */
+export function resolvePluginPeerId({
+  settings = {},
+  configured = null,
+  sources = {},
+  credentials = {},
+  hostInput = "",
+  env = process.env,
+  credentialSource = credentials?.credentialSource || "",
+} = {}) {
+  const host = trimmed(hostInput);
+  if (host) return host;
+
+  if (credentialSource !== "ovcli") {
+    const fromEnv = trimmed(env?.OPENVIKING_PEER_ID);
+    if (fromEnv) return fromEnv;
+  }
+
+  if (configured?.has?.("peerId") && !PEER_LAYERS_RANKED_SEPARATELY.has(sources?.peerId)) {
+    const named = trimmed(settings?.peerId);
+    if (named) return named;
+  }
+
+  const fromCredentials = trimmed(credentials?.peerId);
+  if (fromCredentials) return fromCredentials;
+
+  if (sources?.peerId === "ov.conf") return trimmed(settings?.peerId);
+
+  return "";
+}
+
 export function deriveWorkspacePeerId(cwd) {
   return legacySanitize(cwd);
 }