@consiliency/agent-board-cli 1.24.0 → 1.26.0

package/dist/setup_writers.js

@@ -0,0 +1,916 @@
+// 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    materialise the packaged marketplace into            our plugin row's version = the
+//             `claudeMarketplaceDir` (per user), then              baked mcp version, the scope's
+//             `claude plugin marketplace add <that dir>`           marketplace source is that
+//             + `install` (or `update` over an older one)           directory, and its content is
+//                                                                   byte-equal to the packaged copy
+//   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 { randomBytes } from "node:crypto";
+import { constants as FS, accessSync, chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } 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 { resolveMarketplaceDir } from "./assets.js";
+import { MARKETPLACE_MANIFEST_KEY, claudeMarketplaceDir, compareVersions, describeTrustProblem, isOurMarketplacePath, pluginVersionIn, readTree, resolveTrustChain, sameTree, } from "./claude_marketplace.js";
+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, claudeMarketplaceDeclarations, 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;
+/**
+ * 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, extra = {}) {
+    return { cwd, home: homeOf(env), env, fs, claudeManagedDir, ...extra };
+}
+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]);
+    // This scope's declared source must be exactly our per-user directory (#549): a github ref (a
+    // fleet host installed before it) or any other directory is migrated by re-declaring it.
+    const source = own(own(own(settings, "extraKnownMarketplaces"), CLAUDE_PLUGIN_MARKETPLACE), "source");
+    const path = own(source, "path");
+    const directory = own(source, "source") === "directory" && isOurMarketplacePath(path, ctx.env, ctx.home);
+    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,
+        directory,
+    };
+}
+/**
+ * Setup's exact check for claude: our plugin, at the baked version, from our per-user directory,
+ * effective here AND installed and enabled at the REQUESTED scope from that directory, with no layer
+ * setup may write (user, local) still declaring the marketplace another way, and our directory
+ * judged sound by doctor's own reader. `rewrote`: setup has just rewritten the directory because its
+ * content differed from the packaged bytes, so what Claude Code installed from it is not what this
+ * build ships — never exact.
+ */
+export function claudePluginExact(ctx, assets, scope, rewrote = false) {
+    const read = readClaudePluginScopes(ctx);
+    const summary = read.summary;
+    const atScope = claudeScopeInstall(ctx, scope);
+    const staleLayers = [...new Set(claudeMarketplaceDeclarations(ctx)
+            .filter((declaration) => !declaration.directory && (declaration.layer === "user" || declaration.layer === "local"))
+            .map((declaration) => declaration.layer))];
+    // Round 3 (C2): every row of ours setup can reach (user, and local for this cwd) must be at the baked
+    // version. A local row installed from the github ref is the FIRST applicable row in its project, so
+    // leaving it old leaves that project on the old plugin; setup updates it, and is not exact before.
+    const rowLayers = SETUP_SCOPES.filter((layer) => claudeScopeInstall(ctx, layer).row);
+    const staleRows = rowLayers.filter((layer) => claudeScopeInstall(ctx, layer).version !== assets.mcpVersion);
+    // The WINNING declaration must be our directory too: the disabled path returns on `pinned` alone.
+    const sourceSound = summary.sourceKind === "directory" && read.sourceUndetermined.length === 0
+        && !read.failures.some((failure) => failure.startsWith("plugin_source_"));
+    const effective = summary.installed && summary.version === assets.mcpVersion && !read.failures.includes("plugin_stanza_mismatch");
+    const pinned = atScope.row && atScope.version === assets.mcpVersion && atScope.directory && !rewrote && sourceSound && staleLayers.length === 0 && staleRows.length === 0;
+    return {
+        exact: effective && pinned && atScope.enabled,
+        installedAtScope: atScope.row,
+        enabledAtScope: atScope.row && atScope.enabled,
+        disabledAtScope: atScope.row && atScope.disabled,
+        pinnedAtScope: pinned,
+        foreign: read.failures.includes("foreign_board_plugin"),
+        unparseable: read.unparseable.length > 0 || read.untrusted,
+        staleLayers,
+        rowLayers,
+        staleRows,
+    };
+}
+const pinOf = (stats) => ({ dev: stats.dev, ino: stats.ino, uid: stats.uid });
+/** The path now, lstat'd: still the same real directory (same dev/ino/owner), never a symlink. */
+function samePin(path, pin) {
+    let stats;
+    try {
+        stats = lstatSync(path);
+    }
+    catch {
+        return pin === null;
+    }
+    return pin !== null && stats.isDirectory() && !stats.isSymbolicLink() && stats.dev === pin.dev && stats.ino === pin.ino && stats.uid === pin.uid;
+}
+/** The resolver's visited chain up to and including the parent: every directory entered, by identity. */
+const chainKey = (visited) => visited.filter((entry) => entry.role !== "dir").map((entry) => `${entry.path}\u0000${entry.dev}:${entry.ino}`).join("\n");
+const lstatOrNull = (path) => {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+};
+const SIBLING = /^\.claude-marketplace\.(tmp|old)-/;
+/**
+ * Make `claudeMarketplaceDir` hold exactly the packaged marketplace. It must be permanent (a
+ * directory-sourced plugin whose directory is gone fails to load: measured), so it is never the
+ * npx cache.
+ *
+ * Trust (B3): `checkTrustChain`, shared with doctor, over every existing path from `/` down. Our own
+ * `agent-board` or `claude-marketplace` directory that is group/world-writable is TIGHTENED to 0700
+ * rather than refused: setup owns both, nothing else is meant to write there, and a refusal would
+ * only ask the user to run the chmod setup can run; anything else untrusted is refused
+ * (`plugin_dir_untrusted`, naming the path). After `mkdir` the chain is judged again, and the parent
+ * and directory are pinned by dev/ino/owner; the pins are re-checked before the swap and before the
+ * old copy is removed, so a path swapped after the check is refused rather than written through or
+ * deleted through.
+ *
+ * Swap (S1): a sibling temp directory is built and renamed in; the old one is renamed aside first
+ * (Node cannot exchange two directories atomically, so the path is briefly absent). If the second
+ * rename fails, the old copy is renamed back. A failed removal of the old copy is a warning, not a
+ * failure. Stale temp/old siblings of ours from a crashed run are removed first.
+ */
+function materializeMarketplace(ctx, scopeCtx) {
+    let packagedDir;
+    try {
+        packagedDir = ctx.marketplaceSource ?? resolveMarketplaceDir();
+    }
+    catch {
+        packagedDir = "";
+    }
+    const packaged = packagedDir === "" ? null : readTree(packagedDir);
+    // The key is `/`-separated on every OS (S5): `readTree` never uses the platform separator.
+    if (packaged === null || packaged.kind !== "ok" || !packaged.files.has(MARKETPLACE_MANIFEST_KEY)) {
+        return failed("marketplace_unpackaged", "this cli build carries no claude-marketplace/ (the build did not copy it): reinstall @consiliency/agent-board-cli, then re-run setup");
+    }
+    const dir = claudeMarketplaceDir(ctx.env, scopeCtx.home);
+    const parent = dirname(dir);
+    const uid = scopeCtx.fs.getuid();
+    // win32 has no uid (getuid() is -1) or POSIX mode: `checkTrustChain` then keeps only the symlink rule (S5).
+    const platform = process.platform;
+    const notes = [];
+    const untrusted = (detail) => failed("plugin_dir_untrusted", `${detail}; setup installs the Claude Code plugin from ${dir} and never follows or takes over what it did not make: fix or remove it (or set XDG_DATA_HOME to a directory you own), then re-run setup`);
+    let pinnedChain = "";
+    const trust = () => resolveTrustChain(dir, { ...ctx.marketplaceTrust, uid, platform });
+    const judge = () => {
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const { problem, visited } = trust();
+            if (problem === null) {
+                pinnedChain = chainKey(visited);
+                return null;
+            }
+            if (!problem.tightenable)
+                return untrusted(describeTrustProblem(problem));
+            chmodSync(problem.path, 0o700);
+            if (!notes.includes("marketplace_dir_tightened"))
+                notes.push("marketplace_dir_tightened");
+        }
+        return untrusted(`${parent} could not be made private`);
+    };
+    const first = judge();
+    if (first)
+        return first;
+    // Leftovers of a crashed run: ours (owner, a real directory) only.
+    if (platform !== "win32" && lstatOrNull(parent)?.isDirectory()) {
+        for (const name of readdirSync(parent)) {
+            const stats = SIBLING.test(name) ? lstatOrNull(join(parent, name)) : null;
+            if (!(stats && stats.isDirectory() && !stats.isSymbolicLink() && stats.uid === uid))
+                continue;
+            try {
+                rmSync(join(parent, name), { recursive: true, force: true });
+            }
+            catch {
+                // `force` suppresses only ENOENT. A copy holding another uid's entry (the tree round 5 rebuilds)
+                // or a 0500 subdirectory cannot be removed: a note, as when the swap's own cleanup fails, never a throw.
+                if (!notes.includes("marketplace_old_copy_left"))
+                    notes.push("marketplace_old_copy_left");
+            }
+        }
+    }
+    // Round 5: an entry inside that another uid owns or can write is NOT equal, however its bytes read:
+    // it is rewritten below through the same swap, with safe modes.
+    const current = readTree(dir, { uid, platform, lstat: ctx.marketplaceTrust?.lstat });
+    if (current.kind === "ok" && sameTree(current.files, packaged.files))
+        return { dir, rewrote: false, notes };
+    // Never a silent downgrade of a TRUSTED directory a newer cli wrote (round 4). An untrusted tree never
+    // reaches here as `ok` (round 5): its version is untrusted too, so it is rebuilt like any other.
+    const skew = current.kind === "ok" ? compareVersions(pluginVersionIn(current.files), pluginVersionIn(packaged.files)) : null;
+    if (skew !== null && skew > 0) {
+        return failed("plugin_dir_newer", `${dir} holds a newer agent-board plugin (${pluginVersionIn(current.kind === "ok" ? current.files : new Map()) ?? "?"}) than this cli ships (${pluginVersionIn(packaged.files) ?? "?"}); setup does not downgrade it: run the newer cli's setup (npx -y @consiliency/agent-board-cli@latest setup --harness claude)`);
+    }
+    const suffix = `${process.pid}-${randomBytes(4).toString("hex")}`;
+    const temp = join(parent, `.claude-marketplace.tmp-${suffix}`);
+    const old = join(parent, `.claude-marketplace.old-${suffix}`);
+    const paths = { parent, dir, temp, old };
+    try {
+        // Every directory setup creates is mkdir'd 0700; a umask can only narrow that, never widen it.
+        mkdirSync(parent, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        return failed("plugin_dir_unwritable", `setup could not create ${parent}: check that its parent is writable by you, then re-run setup`);
+    }
+    // Re-judge now that the parent exists, then pin it and the directory for the rest of the run.
+    const second = judge();
+    if (second)
+        return second;
+    // The pins: every directory the resolver entered up to the parent (round 4), and the directory.
+    const chainPin = pinnedChain;
+    const sameChain = () => {
+        const again = trust();
+        return again.problem === null && chainKey(again.visited) === chainPin;
+    };
+    const dirStats = lstatOrNull(dir);
+    const dirPin = dirStats ? pinOf(dirStats) : null;
+    const changed = () => untrusted(`${parent} or ${dir} changed while setup was writing it`);
+    try {
+        mkdirSync(temp, { mode: 0o700 });
+        for (const [path, file] of packaged.files) {
+            const target = join(temp, ...path.split("/"));
+            mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+            writeFileSync(target, file.bytes, { flag: "wx", mode: 0o600 });
+            // Private modes (round 5): 0700 or 0600 — the exec bit, which equality compares, is kept.
+            chmodSync(target, file.executable ? 0o700 : 0o600);
+        }
+    }
+    catch {
+        if (sameChain())
+            rmSync(temp, { recursive: true, force: true });
+        return failed("plugin_dir_unwritable", `setup could not write the Claude Code marketplace into ${parent}: check that it is writable by you, then re-run setup`);
+    }
+    ctx.marketplaceStep?.("prepared", paths);
+    if (!sameChain() || !samePin(dir, dirPin)) {
+        if (sameChain())
+            rmSync(temp, { recursive: true, force: true });
+        return changed();
+    }
+    let moved = false;
+    try {
+        if (dirPin !== null) {
+            renameSync(dir, old);
+            moved = true;
+            ctx.marketplaceStep?.("moved_old", paths);
+        }
+        renameSync(temp, dir);
+    }
+    catch {
+        // Put the old copy back (the plugin keeps loading), and drop the temp tree.
+        if (moved && sameChain() && lstatOrNull(dir) === null && samePin(old, dirPin)) {
+            try {
+                renameSync(old, dir);
+            }
+            catch {
+                /* reported below: the path may now be absent */
+            }
+        }
+        if (sameChain())
+            rmSync(temp, { recursive: true, force: true });
+        return failed("plugin_dir_unwritable", `setup could not swap the new Claude Code marketplace into ${dir}${lstatOrNull(dir) === null ? " and the directory is now absent" : "; the previous copy is still in place"}: check that ${parent} is writable by you, then re-run setup`);
+    }
+    ctx.marketplaceStep?.("swapped", paths);
+    if (moved) {
+        // Only what setup itself renamed aside, and only through the parent it pinned.
+        if (!sameChain() || !samePin(old, dirPin)) {
+            notes.push("marketplace_old_copy_left");
+        }
+        else {
+            try {
+                rmSync(old, { recursive: true });
+            }
+            catch {
+                notes.push("marketplace_old_copy_left");
+            }
+        }
+    }
+    return { dir, rewrote: true, notes };
+}
+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");
+    // B1: every layer that declares our marketplace. Setup re-declares it (our own entry only) in each
+    // layer it may write — the requested scope, and user or local if they still declare it another
+    // way (a github-ref install, the documented `--scope local` one included). A layer it must not
+    // write (a checked-in project `.claude/settings.json`, managed settings) that would still WIN is
+    // refused, naming the file and the command.
+    const dir = claudeMarketplaceDir(ctx.env, scopeCtx.home);
+    const rank = { user: 0, project: 1, local: 2, managed: 3 };
+    const declarations = claudeMarketplaceDeclarations(scopeCtx);
+    const addScopes = [ctx.scope, ...before.staleLayers.filter((layer) => layer !== ctx.scope)];
+    const winner = [...declarations.map((declaration) => ({ ...declaration, directory: declaration.directory || addScopes.includes(declaration.layer) })),
+        { layer: ctx.scope, path: cliWriteTargets("claude", ctx.scope, scopeCtx)[0], directory: true }]
+        .sort((x, y) => rank[x.layer] - rank[y.layer]).at(-1);
+    if (winner && !winner.directory) {
+        return failed("marketplace_declared_elsewhere", winner.layer === "project"
+            ? `${winner.path} (checked in) declares the message-board marketplace from another source, and it outranks the ${ctx.scope} scope setup writes; setup does not edit a project's shared settings: run \`claude plugin marketplace add ${dir} --scope project\` (then commit that file), or remove the declaration, then re-run setup`
+            : `${winner.path} (managed settings) declares the message-board marketplace from another source, and it outranks every scope setup writes: ask your administrator to point it at ${dir} or remove it, then re-run setup`);
+    }
+    // The directory next: whether it had to be rewritten decides whether the install is exact.
+    const materialized = materializeMarketplace(ctx, scopeCtx);
+    if ("status" in materialized)
+        return materialized;
+    const { rewrote, notes } = materialized;
+    const withNotes = (result) => (notes.length === 0 ? result : {
+        ...result,
+        reason: `${result.reason},${notes.join(",")}`,
+        fix: [result.fix, notes.includes("marketplace_dir_tightened") ? `setup made ${dirname(dir)} or ${dir} private (0700): other users could write to it` : "",
+            notes.includes("marketplace_old_copy_left") ? `setup could not remove the previous copy beside ${dir} (.claude-marketplace.old-*): remove it by hand` : ""].filter(Boolean).join("; "),
+    });
+    const current = claudePluginExact(scopeCtx, ctx.assets, ctx.scope, rewrote);
+    if (current.exact)
+        return withNotes({ 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 (current.disabledAtScope && current.pinnedAtScope)
+        return withNotes({ status: "already", reason: "exact,disabled_by_user", fix: offFix });
+    // readlink BEFORE `claude plugin … --scope` writes a settings file.
+    const links = symlinkCheck(ctx, addScopes.flatMap((scope) => cliWriteTargets("claude", scope, scopeCtx)));
+    if (links.refusal)
+        return links.refusal;
+    // Re-declaring under the same name with another source REPLACES it in both files and keeps the
+    // installed row (measured, #549): the migration from a github-ref install is this same sequence.
+    const steps = addScopes.map((scope) => ["plugin", "marketplace", "add", dir, "--scope", scope]);
+    const scopeArgs = ["--scope", ctx.scope];
+    // Update OUR rows only: at the requested scope, and (C2) at user or local wherever setup just
+    // re-declared the marketplace, rewrote the directory, or the row is not at the baked version — so a
+    // migration converges in one run. `update` keeps each scope's enable state (a user's disable too).
+    const updateScopes = before.rowLayers.filter((layer) => layer === ctx.scope || rewrote || addScopes.includes(layer) || before.staleRows.includes(layer));
+    if (updateScopes.length > 0)
+        steps.push(["plugin", "marketplace", "update", CLAUDE_PLUGIN_MARKETPLACE]);
+    for (const layer of updateScopes)
+        steps.push(["plugin", "update", CLAUDE_PLUGIN_ID, "--scope", layer]);
+    if (before.installedAtScope) {
+        // 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);
+    // Name the file that still wins with another source, if one does: the fix is there.
+    const winning = claudeMarketplaceDeclarations(scopeCtx).at(-1);
+    const where = winning && !winning.directory ? `; ${winning.path} still declares the message-board marketplace from another source` : "";
+    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 ${dir} (or was re-enabled)${where}: run \`claude plugin list\``);
+        }
+        return withNotes({ 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 ${dir}${where}: run \`claude plugin list\` and doctor --harness claude`);
+    }
+    const reason = before.installedAtScope ? "upgraded" : "installed";
+    return withNotes({ 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", {
+        ...(ctx.marketplaceSource ? { claudeMarketplacePackaged: ctx.marketplaceSource } : {}),
+        ...(ctx.marketplaceTrust ? { claudeMarketplaceTrust: ctx.marketplaceTrust } : {}),
+    });
+    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);
+}