@consiliency/agent-board-cli 1.24.0 → 1.25.0

package/dist/setup_writers.js

@@ -0,0 +1,653 @@
+// SETUP SL-2 — the `harness` step: register the board with one harness, in one scope, at the
+// versions this cli build baked (IF-0-SETUP-1, IF-0-SETUP-4).
+//
+//   harness   how                                                  setup's own exact check
+//   claude    `claude plugin marketplace add …@<releaseTag>`       our plugin row's version = the
+//             + `install` (or `update` over an older one)           baked mcp version and its ref = the
+//                                                                   baked release tag
+//   pi        `pi install [-l] npm:@consiliency/agent-board-pi@<v>` exactly that spec, once
+//   opencode  `opencode plugin @consiliency/agent-board-opencode@<v> [-g]`   exactly that spec, once
+//   codex     `[mcp_servers.agent-board]` in config.toml (writer)  the stanza deep-equals ours
+//   grok      `[mcp_servers.agent-board]` in config.toml (writer)  the stanza deep-equals ours
+//   agy       `mcpServers.agent-board` in mcp_config.json (writer) the stanza deep-equals ours
+//
+// Doctor's registration reader is version-blind (it asks "is there a board server"), so it is
+// never the exact check; it is the reader every written file must still satisfy, and the files
+// are located and read through doctor's own scope table (`HARNESS_CONFIG_SCOPES`) so the two
+// cannot disagree about where a harness looks. Auto-update is never enabled by anything here.
+//
+// Every `reason` is an authored code. File content (a server name, a path) only reaches the
+// human `fix`, and a server name only when it is a plain token.
+import { spawn } from "node:child_process";
+import { constants as FS, accessSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import * as fsp from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join } from "node:path";
+import { normalizeKeyReference } from "@consiliency/agent-board-client";
+import { ConfigEditRefused, upsertJsonMember, upsertTomlTable } from "./config_edit.js";
+import { REPORTABLE_TOKEN } from "./doctor.js";
+import { CLAUDE_PLUGIN_ID, CLAUDE_PLUGIN_MARKETPLACE, CLAUDE_PLUGIN_MCP_PACKAGE, CLAUDE_PLUGIN_SERVER, HARNESS_CONFIG_SCOPES, OPENCODE_PLUGIN_PACKAGE, PI_PACKAGE, claudeProjectKey, judgeMcpEntry, nodeRegistrationFs, own, packageIdentity, parseRestrictedToml, readClaudePluginScopes, readScopes, } from "./doctor_scopes.js";
+export const SETUP_SCOPES = Object.freeze(["user", "local"]);
+/** The server name setup writes; the same name the claude plugin registers. */
+export const BOARD_SERVER_NAME = CLAUDE_PLUGIN_SERVER;
+/** `Consiliency/message-board`: the marketplace source, pinned to the baked release tag. */
+export const CLAUDE_MARKETPLACE_REPO = "Consiliency/message-board";
+/**
+ * What codex hands an MCP child and nothing else (`process_ancestry.ts`, measured 2026-09-18 on
+ * codex 0.155.0, across three configurations including `shell_environment_policy.inherit=all`).
+ * The writer test pins this list against that measurement's own text.
+ */
+export const CODEX_CHILD_ENV = Object.freeze(["HOME", "LANG", "LOGNAME", "PATH", "SHELL", "TERM", "USER"]);
+/**
+ * Every non-secret input that decides where the identity file and the runtime records resolve
+ * (`identityConfigRoot`, `identityStateRoot`, `resolveHostSegment`). Written into the codex
+ * stanza's `env` when setup's own value is not the default, so the child resolves what setup
+ * wrote. Never a credential: the identity itself comes from the file.
+ */
+export const CODEX_PATH_INPUTS = Object.freeze(["XDG_CONFIG_HOME", "XDG_STATE_HOME", "MESSAGE_BOARD_WAKE_MACHINE_ID", "MESSAGE_BOARD_WAKE_HOSTNAME"]);
+/** `secret-tool` inherits the child env (`keystore_os_keychain.ts`): an os_keychain key needs the session bus. */
+export const KEYCHAIN_CHILD_INPUTS = Object.freeze(["DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR"]);
+const nonBlank = (value) => (value !== undefined && value.trim() !== "" ? value : undefined);
+const homeOf = (env) => nonBlank(env.HOME) ?? homedir();
+/** The `agent_socket:` socket spellings that mean `$SSH_AUTH_SOCK` (the client's `resolveSocketPath`). */
+const SOCKET_SENTINELS = new Set(["", "default", "$ssh_auth_sock", "ssh_auth_sock"]);
+/**
+ * The env an `agent_socket:` reference's socket resolves through, which codex does not hand its
+ * child: `MESSAGE_BOARD_AGENT_SOCKET_PATH` when setup's env sets it (it overrides the handle), else
+ * `SSH_AUTH_SOCK` when the handle names the socket only by that sentinel (an external agent). An
+ * absolute socket in the handle (a keyslot) needs nothing. null: the socket resolves to nothing
+ * here, so no child could reach it.
+ */
+export function agentSocketInputs(keyReference, env) {
+    if (keyReference === null)
+        return {};
+    let handle;
+    try {
+        const reference = normalizeKeyReference(keyReference);
+        if (reference.resolver !== "agent_socket")
+            return {};
+        handle = String(reference.handle);
+    }
+    catch {
+        return {};
+    }
+    const override = nonBlank(env.MESSAGE_BOARD_AGENT_SOCKET_PATH);
+    if (override !== undefined)
+        return { MESSAGE_BOARD_AGENT_SOCKET_PATH: override };
+    const hash = handle.indexOf("#");
+    const spec = (hash >= 0 ? handle.slice(0, hash) : handle).trim();
+    if (!SOCKET_SENTINELS.has(spec.toLowerCase()))
+        return {};
+    const sock = nonBlank(env.SSH_AUTH_SOCK);
+    return sock === undefined ? null : { SSH_AUTH_SOCK: sock };
+}
+/**
+ * The codex stanza's `env`: each frozen path input setup's env sets to a non-default value, the
+ * session bus for an os_keychain key, and the socket inputs of an agent_socket one. null when the
+ * key's socket cannot be resolved (see `agentSocketInputs`).
+ */
+export function codexStanzaEnv(env, keyReference) {
+    const home = homeOf(env);
+    const defaults = {
+        XDG_CONFIG_HOME: join(home, ".config"),
+        XDG_STATE_HOME: join(home, ".local", "state"),
+        MESSAGE_BOARD_WAKE_MACHINE_ID: undefined,
+        MESSAGE_BOARD_WAKE_HOSTNAME: undefined,
+    };
+    const out = {};
+    for (const name of CODEX_PATH_INPUTS) {
+        const value = nonBlank(env[name]);
+        if (value !== undefined && value !== defaults[name])
+            out[name] = value;
+    }
+    let resolver = null;
+    try {
+        resolver = keyReference === null ? null : normalizeKeyReference(keyReference).resolver;
+    }
+    catch {
+        resolver = null;
+    }
+    if (resolver === "os_keychain") {
+        for (const name of KEYCHAIN_CHILD_INPUTS) {
+            const value = nonBlank(env[name]);
+            if (value !== undefined)
+                out[name] = value;
+        }
+    }
+    const socket = agentSocketInputs(keyReference, env);
+    if (socket === null)
+        return null;
+    return { ...out, ...socket };
+}
+/** The environment codex actually gives the MCP child: the frozen seven from `env`, then the stanza's. */
+export function codexChildEnv(env, stanza) {
+    const out = {};
+    for (const name of CODEX_CHILD_ENV)
+        if (env[name] !== undefined)
+            out[name] = env[name];
+    const extra = stanza.env;
+    if (extra !== undefined && typeof extra === "object" && !Array.isArray(extra)) {
+        for (const [name, value] of Object.entries(extra))
+            if (typeof value === "string")
+                out[name] = value;
+    }
+    return out;
+}
+/**
+ * The stanza setup writes for an MCP-configured harness: `npx -y <mcp>@<pin> --harness <h>` (+ the
+ * codex env). null only for codex, when its key's agent socket resolves to nothing here.
+ */
+export function mcpStanza(harness, assets, env, keyReference) {
+    const stanza = { command: "npx", args: ["-y", `${CLAUDE_PLUGIN_MCP_PACKAGE}@${assets.mcpVersion}`, "--harness", harness] };
+    if (harness === "codex") {
+        const childEnv = codexStanzaEnv(env, keyReference);
+        if (childEnv === null)
+            return null;
+        if (Object.keys(childEnv).length > 0)
+            return { ...stanza, env: childEnv };
+    }
+    return stanza;
+}
+/**
+ * Whether an entry under our name runs OUR server: an argv element whose package identity is
+ * exactly `@consiliency/agent-board-mcp` (any version, as `npx -y <pkg>@<v>` passes it), or the
+ * package's bin `agent-board-mcp` as its own element. A substring is never enough: a lookalike
+ * package (`@example/agent-board-mcp-tools`, `@consiliency/agent-board-mcp-extra`) or a wrapper
+ * script whose path merely contains the name is someone else's, and is never overwritten.
+ */
+export function isOurServer(words) {
+    return words.some((word) => word === "agent-board-mcp" || packageIdentity(word) === CLAUDE_PLUGIN_MCP_PACKAGE);
+}
+/** The entry keys setup owns; any other key a user keeps in the entry survives an upgrade. */
+const OWNED_ENTRY_KEYS = new Set(["command", "args", "env"]);
+/**
+ * The `env` names setup owns: exactly the ones it may write. Any other name a user keeps in the
+ * entry's `env` survives an upgrade; an owned one setup no longer writes is dropped.
+ */
+export const OWNED_ENV_NAMES = new Set([
+    ...CODEX_PATH_INPUTS, ...KEYCHAIN_CHILD_INPUTS, "SSH_AUTH_SOCK", "MESSAGE_BOARD_AGENT_SOCKET_PATH",
+]);
+function scopeContext(env, cwd, fs, claudeManagedDir) {
+    return { cwd, home: homeOf(env), env, fs, claudeManagedDir };
+}
+const row = (harness, name) => {
+    const found = HARNESS_CONFIG_SCOPES[harness].find((candidate) => candidate.name === name);
+    if (!found)
+        throw new Error(`setup: doctor's scope table has no ${name} row`);
+    return found;
+};
+/**
+ * Whether `setup --harness <h> --scope <s>` is supported here. agy has no project scope; a codex
+ * project layer is loaded only under a trusted `[projects]` entry, judged by doctor's own walk
+ * (the `codex_project` row's `loaded`), so setup and doctor cannot disagree. Setup never writes trust.
+ */
+export function scopeRefusal(harness, scope, ctx) {
+    if (scope === "user")
+        return null;
+    if (harness === "agy") {
+        return { reason: "scope_unsupported", fix: "agy has no project scope (only ~/.gemini/config/mcp_config.json): re-run with --scope user" };
+    }
+    if (harness === "codex") {
+        const scopeCtx = scopeContext(ctx.env, ctx.cwd, ctx.fs ?? nodeRegistrationFs, ctx.claudeManagedDir ?? "/etc/claude-code");
+        const project = row("codex", "codex_project");
+        let trusted = false;
+        try {
+            trusted = project.loaded?.(join(ctx.cwd, ".codex", "config.toml"), scopeCtx) ?? true;
+        }
+        catch {
+            trusted = false;
+        }
+        if (!trusted) {
+            return {
+                reason: "codex_project_untrusted",
+                fix: "codex loads .codex/config.toml only in a trusted project: open codex in this directory and accept its trust prompt (it records trust_level = \"trusted\" under [projects] in ~/.codex/config.toml), then re-run setup. Setup never writes trust.",
+            };
+        }
+    }
+    return null;
+}
+export const defaultChildRunner = (file, args, options) => new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let child;
+    try {
+        child = spawn(file, [...args], { env: options.env, cwd: options.cwd, stdio: ["ignore", "pipe", "pipe"], timeout: options.timeoutMs ?? 600_000 });
+    }
+    catch {
+        resolve({ code: null, stdout, stderr });
+        return;
+    }
+    child.stdout.on("data", (chunk) => { stdout += String(chunk); });
+    child.stderr.on("data", (chunk) => { stderr += String(chunk); });
+    child.on("error", () => resolve({ code: null, stdout, stderr }));
+    child.on("close", (code, signal) => resolve({ code: signal ? null : code, stdout, stderr }));
+});
+/** An executable named `name` on `env`'s PATH (never `process.env`'s), or null. */
+export function which(name, env) {
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (!dir || !isAbsolute(dir))
+            continue;
+        const candidate = join(dir, name);
+        try {
+            if (!statSync(candidate).isFile())
+                continue;
+            accessSync(candidate, FS.X_OK);
+            return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Replace `path`'s content so a reader sees the old file or the new one. A symlink is written
+ * THROUGH (its target is replaced, the link kept) unless `followSymlinks` is false, which refuses.
+ * An existing file keeps its mode; a new one is 0600 in 0700 directories.
+ */
+async function writeConfigFile(path, text, followSymlinks) {
+    let target = path;
+    let mode = 0o600;
+    let symlink = false;
+    let stats = null;
+    try {
+        stats = lstatSync(path);
+    }
+    catch {
+        stats = null;
+    }
+    if (stats?.isSymbolicLink()) {
+        if (!followSymlinks)
+            return { reason: "config_symlink_refused", fix: `${path} is a symlink and --no-follow-symlinks was given: write the board entry yourself, or re-run without --no-follow-symlinks to write through it` };
+        try {
+            target = realpathSync(path);
+        }
+        catch {
+            return { reason: "config_symlink_dangling", fix: `${path} is a symlink to nothing: fix or remove the link, then re-run setup` };
+        }
+        symlink = true;
+        stats = lstatSync(target);
+    }
+    if (stats && !stats.isFile())
+        return { reason: "config_not_a_file", fix: `${target} is not a regular file` };
+    if (stats)
+        mode = stats.mode & 0o7777;
+    else
+        mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    const temp = join(dirname(target), `.${basename(target)}.setup-${process.pid}-${Date.now()}`);
+    const handle = await fsp.open(temp, FS.O_CREAT | FS.O_EXCL | FS.O_WRONLY | FS.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(text, "utf8");
+        await handle.chmod(mode);
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close();
+        await fsp.unlink(temp).catch(() => { });
+        throw error;
+    }
+    await handle.close();
+    try {
+        await fsp.rename(temp, target);
+    }
+    catch (error) {
+        await fsp.unlink(temp).catch(() => { });
+        throw error;
+    }
+    const dir = await fsp.open(dirname(target), "r");
+    try {
+        await dir.sync();
+    }
+    finally {
+        await dir.close();
+    }
+    return { symlink };
+}
+const readText = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+};
+const failed = (reason, fix) => ({ status: "failed", reason, fix });
+const token = (value) => (REPORTABLE_TOKEN.test(value) ? value : "(unprintable name)");
+/** The MCP-writer target file for a harness and scope, as doctor's scope rows locate it. */
+export function mcpTarget(harness, scope, ctx) {
+    const name = harness === "codex" ? (scope === "user" ? "codex_user" : "codex_project")
+        : harness === "grok" ? (scope === "user" ? "grok_user" : "grok_project")
+            : "agy_user";
+    const paths = row(harness, name).paths(ctx);
+    // A walked project row lists cwd first.
+    return scope === "user" ? paths[0] : join(ctx.cwd, harness === "codex" ? ".codex" : ".grok", "config.toml");
+}
+/** Board MCP servers registered anywhere in the harness's scopes (as doctor reads them), except `exempt`. */
+function boardEntries(harness, ctx, exempt) {
+    const scopes = readScopes(harness, ctx);
+    let disabled = new Set();
+    if (harness === "claude") {
+        try {
+            const doc = JSON.parse(readText(join(nonBlank(ctx.env.CLAUDE_CONFIG_DIR) ?? ctx.home, ".claude.json")) ?? "{}");
+            const list = own(own(own(doc, "projects"), claudeProjectKey(ctx)), "disabledMcpServers");
+            disabled = new Set(Array.isArray(list) ? list.filter((item) => typeof item === "string") : []);
+        }
+        catch {
+            disabled = new Set();
+        }
+    }
+    const entries = [];
+    for (const file of scopes.files) {
+        for (const entry of file.contribution.mcp) {
+            if (entry.disabled)
+                continue;
+            if (harness === "claude" && disabled.has(entry.name) && file.row !== "claude_managed_mcp" && file.row !== "claude_managed_settings")
+                continue;
+            if (!judgeMcpEntry(entry, ctx.fs).board)
+                continue;
+            if (exempt && file.path === exempt.path && entry.name === exempt.name)
+                continue;
+            entries.push({ row: file.row, path: file.path, name: entry.name });
+        }
+    }
+    return { entries, unparseable: scopes.unparseable };
+}
+function existingBoardServer(harness, seen) {
+    const where = `${seen.row} (${seen.path}), server ${token(seen.name)}`;
+    const fix = harness === "claude"
+        ? `a board MCP server is already registered: ${where}. Remove it, or turn it off for this directory with projects[<this project>].disabledMcpServers in ~/.claude.json, then re-run setup; setup never overwrites it`
+        : `a board MCP server is already registered: ${where}. Remove it (or re-run setup with the --scope that holds it), then re-run setup; setup never overwrites it`;
+    return failed("existing_board_server", fix);
+}
+async function installMcp(ctx, scopeCtx) {
+    const target = mcpTarget(ctx.harness, ctx.scope, scopeCtx);
+    const seen = boardEntries(ctx.harness, scopeCtx, { path: target, name: BOARD_SERVER_NAME });
+    if (seen.unparseable.length > 0)
+        return failed("config_unparseable", `these ${ctx.harness} config files do not parse, so setup cannot tell what they register: ${[...new Set(seen.unparseable)].join(", ")}`);
+    if (seen.entries.length > 0)
+        return existingBoardServer(ctx.harness, seen.entries[0]);
+    const stanza = mcpStanza(ctx.harness, ctx.assets, ctx.env, ctx.keyReference);
+    if (stanza === null) {
+        return failed("agent_socket_unresolved", "the key's agent socket resolves through SSH_AUTH_SOCK (or MESSAGE_BOARD_AGENT_SOCKET_PATH), which is unset here, and codex hands its MCP child neither: run setup from the shell whose agent holds the key");
+    }
+    const text = readText(target) ?? "";
+    const path = ctx.harness === "agy" ? ["mcpServers", BOARD_SERVER_NAME] : ["mcp_servers", BOARD_SERVER_NAME];
+    // An entry under our name that is not a board server is someone else's: never overwritten. Ours
+    // keeps every key the user added (only command, args and env are setup's), and a server the user
+    // turned off stays off.
+    let desired = stanza;
+    let disabledByUser = false;
+    try {
+        const doc = ctx.harness === "agy" ? (text.trim() === "" ? {} : JSON.parse(text)) : parseRestrictedToml(text);
+        const current = own(own(doc, path[0]), path[1]);
+        if (current !== undefined && current !== null && typeof current === "object") {
+            const command = own(current, "command");
+            const args = own(current, "args");
+            const words = [typeof command === "string" ? command : "", ...(Array.isArray(args) ? args.filter((arg) => typeof arg === "string") : [])];
+            if (!isOurServer(words)) {
+                return failed("existing_board_server", `${target} already has a server named ${BOARD_SERVER_NAME} that is not ${CLAUDE_PLUGIN_MCP_PACKAGE} (another package, or a wrapper): setup never overwrites it; rename or remove it, then re-run setup`);
+            }
+            const kept = {};
+            for (const key of Object.keys(current))
+                if (!OWNED_ENTRY_KEYS.has(key))
+                    kept[key] = own(current, key);
+            // `env` merges name by name: the user's names stay, setup's own come from the stanza.
+            const currentEnv = own(current, "env");
+            const env = {};
+            if (currentEnv !== null && typeof currentEnv === "object" && !Array.isArray(currentEnv)) {
+                for (const name of Object.keys(currentEnv))
+                    if (!OWNED_ENV_NAMES.has(name))
+                        env[name] = own(currentEnv, name);
+            }
+            for (const [name, value] of Object.entries(stanza.env ?? {}))
+                env[name] = value;
+            const { env: _stanzaEnv, ...rest } = stanza;
+            void _stanzaEnv;
+            desired = { ...rest, ...(Object.keys(env).length > 0 ? { env } : {}), ...kept };
+            disabledByUser = own(current, "enabled") === false || own(current, "disabled") === true;
+        }
+    }
+    catch {
+        return failed("config_unparseable", `${target} does not parse`);
+    }
+    const off = disabledByUser
+        ? { suffix: ",disabled_by_user", fix: `the board server in ${target} is turned off (enabled = false / disabled: true), and setup keeps your choice: remove that key to turn it on; until then doctor reports no registration` }
+        : { suffix: "", fix: undefined };
+    let edit;
+    try {
+        edit = ctx.harness === "agy"
+            ? upsertJsonMember(text, path, desired, { strict: true })
+            : upsertTomlTable(text, path, desired);
+    }
+    catch (error) {
+        if (error instanceof ConfigEditRefused) {
+            if (error.reason === "config_inline_table" || error.reason === "config_array_table") {
+                return failed(error.reason, `${target} defines mcp_servers (or the board entry) as an inline table, a dotted key or an array of tables, which TOML does not let a [mcp_servers.${BOARD_SERVER_NAME}] table extend: rewrite each server as its own [mcp_servers.<name>] table, then re-run setup`);
+            }
+            return failed(error.reason, `setup could not place the board entry in ${target} without disturbing it: add this stanza yourself: ${JSON.stringify(stanza)}`);
+        }
+        throw error;
+    }
+    if (edit.prior === "exact")
+        return { status: "already", reason: `exact${off.suffix}`, ...(off.fix ? { fix: off.fix } : {}) };
+    const written = await writeConfigFile(target, edit.text, ctx.followSymlinks);
+    if ("reason" in written)
+        return failed(written.reason, written.fix);
+    const reason = `${edit.prior === "differs" ? "upgraded" : "installed"}${written.symlink ? ",symlink_followed" : ""}${off.suffix}`;
+    return { status: "done", reason, ...(off.fix ? { fix: off.fix } : {}) };
+}
+/** The settings files a CLI install writes for this scope, as doctor's rows name them. */
+function cliWriteTargets(harness, scope, ctx) {
+    if (harness === "claude")
+        return row("claude", scope === "user" ? "claude_user_settings" : "claude_project_local_settings").paths(ctx);
+    if (harness === "pi")
+        return row("pi", scope === "user" ? "pi_user" : "pi_project").paths(ctx);
+    if (scope === "user")
+        return row("opencode", "opencode_user").paths(ctx);
+    return row("opencode", "opencode_project").paths(ctx).filter((path) => dirname(path) === ctx.cwd);
+}
+/** `readlink` on each target BEFORE the harness CLI writes it: a symlink is reported, or refused. */
+function symlinkCheck(ctx, targets) {
+    const links = targets.filter(isSymlink);
+    if (links.length === 0)
+        return { refusal: null, followed: false };
+    if (!ctx.followSymlinks) {
+        return { refusal: failed("config_symlink_refused", `${links.join(", ")} is a symlink and --no-follow-symlinks was given: register the board yourself, or re-run without --no-follow-symlinks`), followed: false };
+    }
+    return { refusal: null, followed: true };
+}
+async function runCli(ctx, cli, args) {
+    const outcome = await (ctx.run ?? defaultChildRunner)(cli, args, { env: ctx.env, cwd: ctx.cwd });
+    if (outcome.code === 0)
+        return null;
+    return failed("harness_cli_failed", `\`${basename(cli)} ${args.join(" ")}\` exited ${outcome.code ?? "abnormally"}: run it yourself and read what it reports, then re-run setup`);
+}
+const PACKAGE_ROWS = {
+    pi: { user: ["pi_user"], local: ["pi_project"] },
+    opencode: { user: ["opencode_user"], local: ["opencode_project", "opencode_project_dotdir"] },
+};
+function packageSpecsSeen(harness, ctx) {
+    const wanted = harness === "pi" ? PI_PACKAGE : OPENCODE_PLUGIN_PACKAGE;
+    const scopes = readScopes(harness, ctx);
+    const specs = scopes.files.flatMap((file) => file.contribution.packages
+        .filter((spec) => packageIdentity(spec) === wanted)
+        .map((spec) => ({ row: file.row, spec })));
+    return { specs, unparseable: scopes.unparseable };
+}
+async function installPackage(ctx, scopeCtx) {
+    const cli = which(ctx.harness, ctx.env);
+    if (cli === null)
+        return failed("harness_cli_missing", `the ${ctx.harness} CLI is not on PATH: install ${ctx.harness}, then re-run setup`);
+    const version = ctx.harness === "pi" ? ctx.assets.piVersion : ctx.assets.opencodeVersion;
+    const spec = ctx.harness === "pi" ? `${PI_PACKAGE}@${version}` : `${OPENCODE_PLUGIN_PACKAGE}@${version}`;
+    const ours = PACKAGE_ROWS[ctx.harness][ctx.scope];
+    const seenBoard = boardEntries(ctx.harness, scopeCtx);
+    if (seenBoard.entries.length > 0)
+        return existingBoardServer(ctx.harness, seenBoard.entries[0]);
+    const before = packageSpecsSeen(ctx.harness, scopeCtx);
+    if (before.unparseable.length > 0 || seenBoard.unparseable.length > 0) {
+        return failed("config_unparseable", `these ${ctx.harness} config files do not parse: ${[...new Set([...before.unparseable, ...seenBoard.unparseable])].join(", ")}`);
+    }
+    const elsewhere = before.specs.find((seen) => !ours.includes(seen.row));
+    if (elsewhere)
+        return failed("existing_board_package", `the board package is already registered in ${elsewhere.row}: remove it there (or re-run setup with that --scope), then re-run setup`);
+    const mine = before.specs.filter((seen) => ours.includes(seen.row));
+    if (mine.length > 1)
+        return failed("duplicate_board_package", `the board package is listed ${mine.length} times in this scope: keep one, then re-run setup`);
+    if (mine.length === 1 && mine[0].spec === spec)
+        return { status: "already", reason: "exact" };
+    const links = symlinkCheck(ctx, cliWriteTargets(ctx.harness, ctx.scope, scopeCtx));
+    if (links.refusal)
+        return links.refusal;
+    const upgrade = mine.length === 1;
+    const args = ctx.harness === "pi"
+        ? ["install", ...(ctx.scope === "local" ? ["-l"] : []), spec]
+        : ["plugin", spec, ...(ctx.scope === "user" ? ["-g"] : []), ...(upgrade ? ["-f"] : [])];
+    const cliFailure = await runCli(ctx, cli, args);
+    if (cliFailure)
+        return cliFailure;
+    // The count, not presence: an install that appended beside the old entry is not an upgrade.
+    const after = packageSpecsSeen(ctx.harness, scopeCtx);
+    if (after.specs.length !== 1 || after.specs[0].spec !== spec || !ours.includes(after.specs[0].row)) {
+        return failed("harness_install_unverified", `after \`${ctx.harness} ${args.join(" ")}\` the scope does not hold exactly one ${spec}: fix the entry by hand, then re-run setup`);
+    }
+    const reason = upgrade ? "upgraded" : "installed";
+    return { status: "done", reason: links.followed ? `${reason},symlink_followed` : reason };
+}
+/**
+ * Our plugin as installed AT one scope: that scope's `installed_plugins.json` row (for local, the row
+ * whose project is this directory), the enable in that scope's settings file, and the marketplace
+ * ref that file declares. The cwd-effective summary alone cannot say this: a local install makes
+ * the plugin effective here while a `--scope user` request is still unmet everywhere else.
+ */
+function claudeScopeInstall(ctx, scope) {
+    const configured = nonBlank(ctx.env.CLAUDE_CONFIG_DIR);
+    const configDir = configured !== undefined && isAbsolute(configured) ? configured : join(ctx.home, ".claude");
+    const json = (path) => {
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    };
+    const real = (path) => {
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return path;
+        }
+    };
+    const rows = own(own(json(join(configDir, "plugins", "installed_plugins.json")), "plugins"), CLAUDE_PLUGIN_ID);
+    const row = Array.isArray(rows)
+        ? rows.find((candidate) => own(candidate, "scope") === scope
+            && (scope === "user" || (typeof own(candidate, "projectPath") === "string" && real(own(candidate, "projectPath")) === real(ctx.cwd))))
+        : undefined;
+    const settings = json(cliWriteTargets("claude", scope, ctx)[0]);
+    const ref = own(own(own(own(settings, "extraKnownMarketplaces"), CLAUDE_PLUGIN_MARKETPLACE), "source"), "ref");
+    const version = own(row, "version");
+    return {
+        row: row !== undefined,
+        version: typeof version === "string" ? version : null,
+        enabled: own(own(settings, "enabledPlugins"), CLAUDE_PLUGIN_ID) === true,
+        // The user turned it off at this scope (`claude plugin disable`): setup never turns it back on.
+        disabled: own(own(settings, "enabledPlugins"), CLAUDE_PLUGIN_ID) === false,
+        ref: typeof ref === "string" ? ref : null,
+    };
+}
+/**
+ * Setup's exact check for claude: our plugin, at the baked version, from the baked release tag,
+ * effective here AND installed and enabled at the REQUESTED scope from that tag.
+ */
+export function claudePluginExact(ctx, assets, scope) {
+    const read = readClaudePluginScopes(ctx);
+    const summary = read.summary;
+    const atScope = claudeScopeInstall(ctx, scope);
+    const effective = summary.installed && summary.version === assets.mcpVersion && summary.sourceRef === assets.releaseTag && !read.failures.includes("plugin_stanza_mismatch");
+    return {
+        exact: effective && atScope.row && atScope.version === assets.mcpVersion && atScope.enabled && atScope.ref === assets.releaseTag,
+        installedAtScope: atScope.row,
+        enabledAtScope: atScope.row && atScope.enabled,
+        disabledAtScope: atScope.row && atScope.disabled,
+        pinnedAtScope: atScope.row && atScope.version === assets.mcpVersion && atScope.ref === assets.releaseTag,
+        foreign: read.failures.includes("foreign_board_plugin"),
+        unparseable: read.unparseable.length > 0 || read.untrusted,
+    };
+}
+async function installClaude(ctx, scopeCtx) {
+    const cli = which("claude", ctx.env);
+    if (cli === null)
+        return failed("harness_cli_missing", "the claude CLI is not on PATH: install Claude Code, then re-run setup");
+    const seen = boardEntries("claude", scopeCtx);
+    if (seen.unparseable.length > 0)
+        return failed("config_unparseable", `these claude config files do not parse: ${[...new Set(seen.unparseable)].join(", ")}`);
+    if (seen.entries.length > 0)
+        return existingBoardServer("claude", seen.entries[0]);
+    const before = claudePluginExact(scopeCtx, ctx.assets, ctx.scope);
+    if (before.foreign)
+        return failed("existing_board_plugin", "another Claude Code plugin already registers a board server or wake hook: disable it (claude plugin disable <id>), then re-run setup");
+    if (before.unparseable)
+        return failed("config_unparseable", "Claude Code's plugin records do not parse or name a path outside its cache: run `claude plugin list` and repair them, then re-run setup");
+    if (before.exact)
+        return { status: "already", reason: "exact" };
+    // A plugin the user disabled at this scope stays disabled, as an MCP harness's off switch does:
+    // pinned already → `already`; otherwise upgraded in place (`update` keeps the enable state).
+    const offFix = "the board plugin is disabled at this scope (claude plugin disable), and setup keeps your choice: `claude plugin enable agent-board@message-board` to turn it on; until then doctor reports no registration";
+    if (before.disabledAtScope && before.pinnedAtScope)
+        return { status: "already", reason: "exact,disabled_by_user", fix: offFix };
+    // readlink BEFORE `claude plugin … --scope` writes the settings file.
+    const links = symlinkCheck(ctx, cliWriteTargets("claude", ctx.scope, scopeCtx));
+    if (links.refusal)
+        return links.refusal;
+    const scopeArgs = ["--scope", ctx.scope];
+    const steps = [["plugin", "marketplace", "add", `${CLAUDE_MARKETPLACE_REPO}@${ctx.assets.releaseTag}`, ...scopeArgs]];
+    // An update only over OUR row at this scope; a plugin effective here from another scope is not it.
+    if (before.installedAtScope) {
+        steps.push(["plugin", "marketplace", "update", CLAUDE_PLUGIN_MARKETPLACE]);
+        steps.push(["plugin", "update", CLAUDE_PLUGIN_ID, ...scopeArgs]);
+        // Our row with NO enable at this scope (not a disable: that is the user's choice, kept above).
+        if (!before.enabledAtScope && !before.disabledAtScope)
+            steps.push(["plugin", "enable", CLAUDE_PLUGIN_ID, ...scopeArgs]);
+    }
+    else {
+        steps.push(["plugin", "install", CLAUDE_PLUGIN_ID, ...scopeArgs]);
+    }
+    for (const args of steps) {
+        const cliFailure = await runCli(ctx, cli, args);
+        if (cliFailure)
+            return cliFailure;
+    }
+    const after = claudePluginExact(scopeCtx, ctx.assets, ctx.scope);
+    if (before.disabledAtScope) {
+        if (!after.pinnedAtScope || !after.disabledAtScope) {
+            return failed("harness_install_unverified", `after the claude plugin update, the disabled plugin at this scope is not ${ctx.assets.mcpVersion} from ${ctx.assets.releaseTag} (or was re-enabled): run \`claude plugin list\``);
+        }
+        return { status: "done", reason: `upgraded${links.followed ? ",symlink_followed" : ""},disabled_by_user`, fix: offFix };
+    }
+    if (!after.exact) {
+        return failed("harness_install_unverified", `after the claude plugin install, the installed plugin is not ${ctx.assets.mcpVersion} from ${ctx.assets.releaseTag}: run \`claude plugin list\` and doctor --harness claude`);
+    }
+    const reason = before.installedAtScope ? "upgraded" : "installed";
+    return { status: "done", reason: links.followed ? `${reason},symlink_followed` : reason };
+}
+/** The `harness` step for one harness and scope. Never throws for a host condition. */
+export async function installHarness(ctx) {
+    const scopeCtx = scopeContext(ctx.env, ctx.cwd, ctx.fs ?? nodeRegistrationFs, ctx.claudeManagedDir ?? "/etc/claude-code");
+    const refusal = scopeRefusal(ctx.harness, ctx.scope, ctx);
+    if (refusal)
+        return failed(refusal.reason, refusal.fix);
+    if (ctx.harness === "claude")
+        return installClaude(ctx, scopeCtx);
+    if (ctx.harness === "pi" || ctx.harness === "opencode")
+        return installPackage(ctx, scopeCtx);
+    return installMcp(ctx, scopeCtx);
+}

package/keyslot/agent-board-keyslot-load@.service

@@ -0,0 +1,20 @@
+# Installed to ~/.config/systemd/user/ by scripts/keyslot/provision.sh (IF-0-KEYSEAL-2).
+# Loads the slot key into agent-board-keyslot@%i whenever that agent starts or restarts: a
+# sealed key by decrypting it into a pipe, or an opted-in unsealed key from its 0600 file (A1).
+# slot-%i is a per-slot symlink to the immutable loader version that slot runs (A1).
+[Unit]
+Description=Message Board key slot loader for %i (sealed key via a pipe, or opted-in unsealed key)
+Documentation=https://github.com/Consiliency/message-board
+BindsTo=agent-board-keyslot@%i.service
+After=agent-board-keyslot@%i.service
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+# Informational only: keyslot-load.sh sets its own socket from XDG_RUNTIME_DIR and %i,
+# because the manager exports an ambient SSH_AUTH_SOCK (M7).
+Environment=SSH_AUTH_SOCK=%t/agent-board/%i.sock
+ExecStart=%h/.local/libexec/agent-board/slot-%i/keyslot-load.sh %i
+
+[Install]
+WantedBy=agent-board-keyslot@%i.service