@chorus-aidlc/chorus 0.17.0 → 0.17.2

package/cli/init/agent-type-map.mjs

@@ -12,7 +12,7 @@
 //      "claude-code" EXPLICITLY here. No caller ever passes the raw init id
 //      through to daemon.json; every write goes through agentTypeForSelection.
 //   2. Any selection the daemon cannot wake as a first-class backend
-//      (opencode / openclaw / pi, and dsh while its harness is dormant/offline)
+//      (opencode / openclaw, and dsh while its harness is dormant/offline)
 //      maps to the non-wakeable "offline" classification. Its key is still parked
 //      in agents[] for the `chorus mcp` proxy, but the daemon builds no spawner
 //      and dispatches no wake (spawner-select.mjs fail-closes on "offline").
@@ -22,7 +22,7 @@
 // woken as claude-code.
 
 /**
- * Selection id → daemon agentType. Only claude/codex/kiro are wakeable backends;
+ * Selection id → daemon agentType. claude/codex/kiro/pi are wakeable backends;
  * everything else is classified offline. `dsh` maps to offline because the dsh
  * harness is de-advertised (offline) — re-map it here to bring it back online.
  * @type {Readonly<Record<string, string>>}
@@ -31,9 +31,9 @@ export const SELECTION_TO_AGENT_TYPE = Object.freeze({
   claude: "claude-code", // explicit rename — never pass the init id "claude" through verbatim
   codex: "codex",
   kiro: "kiro",
+  pi: "pi", // wakeable via PiSpawner (add-daemon-pi-backend)
   opencode: "offline",
   openclaw: "offline",
-  pi: "offline",
   dsh: "offline",
 });
 
@@ -42,7 +42,7 @@ export const SELECTION_TO_AGENT_TYPE = Object.freeze({
  * daemon.json `agents[]`. Unknown ids fail closed to "offline" (never a wakeable
  * default), so an agent is only ever woken when its backend is explicitly known.
  * @param {string} selectionId
- * @returns {string} a KNOWN_AGENTS agentType ("claude-code" | "codex" | "kiro" | "offline")
+ * @returns {string} a KNOWN_AGENTS agentType ("claude-code" | "codex" | "kiro" | "pi" | "offline")
  */
 export function agentTypeForSelection(selectionId) {
   return SELECTION_TO_AGENT_TYPE[selectionId] ?? "offline";
@@ -51,7 +51,7 @@ export function agentTypeForSelection(selectionId) {
 /**
  * Whether a daemon agentType is one the daemon can actually wake. "offline" is the
  * one non-wakeable classification; every other value the init mapping produces
- * (claude-code / codex / kiro) is wakeable.
+ * (claude-code / codex / kiro / pi) is wakeable.
  * @param {string} agentType
  * @returns {boolean}
  */

package/cli/init/contracts.mjs

@@ -108,6 +108,8 @@ export const FAILURE_ACTIONS = Object.freeze([OUTCOME_ACTIONS.FAILED]);
  * @property {string} [agentId]     The current agent id (per-agent steps only).
  * @property {AgentAdapter} [adapter] The current agent's adapter (per-agent steps only).
  * @property {object} flags         Parsed init flags (see cli/init-args.mjs).
+ *   `flags.updateInstalled` is the orchestrator-resolved, invocation-wide
+ *   decision to refresh selected installed plugin payloads.
  * @property {{ log: (m: string) => void, ask: Function, isTTY: boolean }} io
  * @property {(path: string) => (string|null)} backup  Copy a file to <path>.chorus-bak
  *   once before overwrite; returns the backup path or null if the source is absent.

package/cli/init/install-methods.mjs

@@ -66,9 +66,10 @@ function readJsonSafe(path) {
 }
 
 // ---------------------------------------------------------------------------
-// Claude Code — VERIFIED against Claude Code 2.1.235:
+// Claude Code — VERIFIED LIVE against Claude Code 2.1.250:
 //   `claude plugin marketplace add <url|path|repo>`
 //   `claude plugin install <plugin@marketplace> -y`  (-y required when non-TTY)
+//   `claude plugin update <plugin@marketplace> -y`
 // State is read from ~/.claude/plugins/installed_plugins.json (read-only).
 // ---------------------------------------------------------------------------
 export function installClaude(ctx) {
@@ -77,6 +78,11 @@ export function installClaude(ctx) {
   const source = env.CHORUS_MARKETPLACE_SOURCE || CHORUS_MARKETPLACE_SOURCE;
   const state = safeState(ctx);
   if (state.pluginInstalled) {
+    if (ctx.flags?.updateInstalled) {
+      const r = run("claude", ["plugin", "update", CHORUS_PLUGIN_ID, "-y"], { env });
+      if (!r.ok) return out("claude", FAILED, `claude plugin update failed: ${errText(r)}`);
+      return out("claude", REPAIRED, `updated ${CHORUS_PLUGIN_ID} to latest via claude plugin update`);
+    }
     return out("claude", SKIPPED, `already installed${state.version ? ` (v${state.version})` : ""}`);
   }
   if (!state.marketplaceRegistered) {
@@ -91,6 +97,7 @@ export function installClaude(ctx) {
 // ---------------------------------------------------------------------------
 // Codex — VERIFIED against codex-cli 0.146.1 / 0.150.1:
 //   `codex plugin marketplace add <SOURCE>`   (SOURCE = local path | owner/repo[@ref] | Git URL)
+//   `codex plugin marketplace upgrade [MARKETPLACE_NAME]`
 //   `codex plugin add <PLUGIN@MARKETPLACE> --json`
 // config.toml is backed up before the CLI mutates it.
 //
@@ -153,6 +160,21 @@ export function installCodex(ctx) {
 
   if (state.pluginInstalled) {
     ctx.backup?.(configPath); // back up before we normalize the MCP block
+    if (ctx.flags?.updateInstalled) {
+      if (!state.marketplaceRegistered) {
+        const ra = run("codex", ["plugin", "marketplace", "add", source], { env });
+        if (!ra.ok) return out("codex", FAILED, `codex plugin marketplace add failed: ${errText(ra)}`);
+      }
+      const ru = run("codex", ["plugin", "marketplace", "upgrade", CHORUS_MARKETPLACE_NAME], { env });
+      if (!ru.ok) return out("codex", FAILED, `codex plugin marketplace upgrade failed: ${errText(ru)}`);
+      const rp = run("codex", ["plugin", "add", CHORUS_PLUGIN_ID, "--json"], { env });
+      if (!rp.ok) return out("codex", FAILED, `codex plugin add failed: ${errText(rp)}`);
+      return out(
+        "codex",
+        REPAIRED,
+        `refreshed ${CHORUS_MARKETPLACE_NAME} and reinstalled ${CHORUS_PLUGIN_ID}${ensureMcp()}`,
+      );
+    }
     return out("codex", SKIPPED, `already installed (config.toml)${ensureMcp()}`);
   }
 
@@ -171,8 +193,9 @@ export function installCodex(ctx) {
 }
 
 // ---------------------------------------------------------------------------
-// opencode — VERIFIED against opencode 1.14.33:
+// opencode — VERIFIED LIVE against opencode 1.14.33:
 //   `opencode plugin <module>`  ("install plugin and update config")
+//   `--global` targets the user config; `--force` replaces an existing version.
 // module name "opencode-chorus" from public/install-opencode.sh. opencode.json
 // is backed up before the CLI mutates it.
 // ---------------------------------------------------------------------------
@@ -195,15 +218,21 @@ export function installOpencode(ctx) {
   const home = env.HOME || homedir();
   const dir = env.OPENCODE_CONFIG_DIR || join(home, ".config", "opencode");
   const state = safeState(ctx);
-  if (state.pluginInstalled) return out("opencode", SKIPPED, "already in opencode.json plugin list");
+  if (state.pluginInstalled && !ctx.flags?.updateInstalled) {
+    return out("opencode", SKIPPED, "already in opencode.json plugin list");
+  }
 
   ctx.backup?.(join(dir, "opencode.json")); // back up before the CLI edits it
   // `-g` writes the GLOBAL ~/.config/opencode/opencode.json (the same file
   // readOpencodeInstallState checks); without it opencode installs project-local
   // (cwd), which would defeat idempotency for a machine-wide `chorus init`.
-  const r = run("opencode", ["plugin", OPENCODE_PLUGIN_MODULE, "-g"], { env });
+  const args = ["plugin", OPENCODE_PLUGIN_MODULE, "-g"];
+  if (state.pluginInstalled) args.push("--force");
+  const r = run("opencode", args, { env });
   if (!r.ok) return out("opencode", FAILED, `opencode plugin install failed: ${errText(r)}`);
-  return out("opencode", INSTALLED, `installed ${OPENCODE_PLUGIN_MODULE} via opencode plugin -g`);
+  return state.pluginInstalled
+    ? out("opencode", REPAIRED, `updated ${OPENCODE_PLUGIN_MODULE} to latest via opencode plugin -g --force`)
+    : out("opencode", INSTALLED, `installed ${OPENCODE_PLUGIN_MODULE} via opencode plugin -g`);
 }
 
 // ---------------------------------------------------------------------------
@@ -225,18 +254,35 @@ const DSH_BUNDLE = "@chorus-aidlc/chorus-dsh";
 export function readDshInstallState({ env = process.env, profile } = {}) {
   // Best-effort, per-profile idempotency probe. A dsh profile is a pnpm workspace
   // root under $DSH_HOME (docs/CONNECT_DSH.md); a profile that has added the bundle
-  // records it in that root's package.json. The exact layout is NOT verifiable here,
-  // so this degrades to "not installed" if it differs (dsh's own `add` is idempotent)
-  // — never a false positive, never a throw. Called with no `profile` (registry-level
-  // detection, which does not know the user's pick) it reports not-installed.
-  if (!profile) return { marketplaceRegistered: false, pluginInstalled: false };
+  // records it in that root's package.json. Before an interactive profile has
+  // been chosen, inspect the live profiles/<name> store so runInit can include
+  // dsh in its one invocation-wide installed-plugin refresh decision.
   const home = env.HOME || homedir();
   const dshHome = env.DSH_HOME || join(home, ".dsh");
-  const pkg = readJsonSafe(join(dshHome, profile, "package.json"));
-  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  let candidates;
+  if (profile) {
+    candidates = [
+      join(dshHome, "profiles", profile, "package.json"),
+      join(dshHome, profile, "package.json"),
+    ];
+  } else {
+    try {
+      candidates = readdirSync(join(dshHome, "profiles"), { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => join(dshHome, "profiles", entry.name, "package.json"));
+    } catch {
+      candidates = [];
+    }
+  }
+  const packagePath = candidates.find((path) => {
+    const pkg = readJsonSafe(path);
+    const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+    return Object.prototype.hasOwnProperty.call(deps, DSH_BUNDLE);
+  });
   return {
     marketplaceRegistered: false, // dsh has no marketplace concept
-    pluginInstalled: Object.prototype.hasOwnProperty.call(deps, DSH_BUNDLE),
+    pluginInstalled: !!packagePath,
+    packagePath: packagePath ?? (profile ? candidates[0] : undefined),
   };
 }
 
@@ -276,11 +322,16 @@ export async function installDsh(ctx) {
 
   // Idempotency: skip when the chosen profile already carries the bundle.
   const state = safeState(ctx, { profile });
-  if (state.pluginInstalled) return out("dsh", SKIPPED, `already installed in dsh profile '${profile}'`);
+  if (state.pluginInstalled && !ctx.flags?.updateInstalled) {
+    return out("dsh", SKIPPED, `already installed in dsh profile '${profile}'`);
+  }
+  if (state.pluginInstalled) ctx.backup?.(state.packagePath);
 
   const r = run("dsh", ["plugin", "--profile", profile, "add", DSH_BUNDLE, "-w"], { env });
   if (!r.ok) return out("dsh", FAILED, `dsh plugin add failed: ${errText(r)}`);
-  return out("dsh", INSTALLED, `installed ${DSH_BUNDLE} into dsh profile '${profile}'`);
+  return state.pluginInstalled
+    ? out("dsh", REPAIRED, `updated ${DSH_BUNDLE} to latest in dsh profile '${profile}'`)
+    : out("dsh", INSTALLED, `installed ${DSH_BUNDLE} into dsh profile '${profile}'`);
 }
 
 // ---------------------------------------------------------------------------
@@ -377,7 +428,7 @@ export function installOpenclaw(ctx) {
 
   // Already installed AND enabled → nothing to do. No version probe needed: an
   // enabled-and-loaded plugin necessarily already satisfied the host floor.
-  if (state.pluginInstalled && state.pluginEnabled) {
+  if (state.pluginInstalled && state.pluginEnabled && !ctx.flags?.updateInstalled) {
     return out("openclaw", SKIPPED, "already installed and enabled");
   }
 
@@ -395,18 +446,140 @@ export function installOpenclaw(ctx) {
   }
 
   // Installed-but-disabled → enable only (repair).
-  if (state.pluginInstalled) {
+  if (state.pluginInstalled && !ctx.flags?.updateInstalled) {
     const re = run("openclaw", ["plugins", "enable", OPENCLAW_PLUGIN_ID], { env });
     if (!re.ok) return out("openclaw", FAILED, `openclaw plugins enable failed: ${errText(re)}`);
     return out("openclaw", REPAIRED, `enabled ${OPENCLAW_PLUGIN_ID} (was installed but disabled)`);
   }
 
-  // Fresh → install from npm, then enable.
+  // Fresh or accepted refresh → install from npm, then ensure enabled. Back up
+  // the mutable host config before an installed payload is refreshed.
+  if (state.pluginInstalled) {
+    const home = env.HOME || homedir();
+    const dir = env.OPENCLAW_CONFIG_DIR || join(home, ".openclaw");
+    ctx.backup?.(join(dir, "openclaw.json"));
+  }
   const ri = run("openclaw", ["plugins", "install", OPENCLAW_NPM_SPEC], { env });
   if (!ri.ok) return out("openclaw", FAILED, `openclaw plugins install failed: ${errText(ri)}`);
   const re = run("openclaw", ["plugins", "enable", OPENCLAW_PLUGIN_ID], { env });
   if (!re.ok) return out("openclaw", FAILED, `openclaw plugins enable failed: ${errText(re)}`);
-  return out("openclaw", INSTALLED, `installed ${OPENCLAW_NPM_SPEC} and enabled ${OPENCLAW_PLUGIN_ID}`);
+  return state.pluginInstalled
+    ? out("openclaw", REPAIRED, `reinstalled latest ${OPENCLAW_NPM_SPEC} and ensured ${OPENCLAW_PLUGIN_ID} is enabled`)
+    : out("openclaw", INSTALLED, `installed ${OPENCLAW_NPM_SPEC} and enabled ${OPENCLAW_PLUGIN_ID}`);
+}
+
+// ---------------------------------------------------------------------------
+// Pi — VERIFIED against docs/CONNECT_PI.md + packages/chorus-pi/README.md
+// (chorus-pi ships to npm as @chorus-aidlc/chorus-pi):
+//   `pi install npm:pi-mcp-adapter`            (the MCP adapter — exposes chorus_* tools)
+//   `pi install npm:@chorus-aidlc/chorus-pi`   (the Chorus skills/agents/extension)
+// pi installs extensions straight from an npm source (the `npm:` prefix on the
+// spec, like OpenClaw). There is NO marketplace step and NO separate enable
+// step (unlike claude / codex / openclaw). pi has no permission system and loads
+// TypeScript via jiti, so the package publishes source as-is — nothing to build.
+//
+// TWO packages: pi reaches the Chorus MCP tools ONLY through `pi-mcp-adapter` (which reads
+// the mcp.json `chorus agents add` writes — see credential-seed's pi branch + pi-mcp-config.mjs);
+// chorus.ts does NOT register tools itself. So we install the adapter FIRST (the tool surface),
+// then chorus-pi (the skills / reviewer agents / session extension). Both are idempotent.
+//
+// Graceful degradation: if the `pi` binary is absent we surface the exact manual
+// commands as UNSUPPORTED guidance (never a hard FAILED — UNSUPPORTED is not a
+// FAILURE_ACTION, so `chorus init` does not abort) and run ZERO commands. This
+// follows the "no guessed command / no crash" rule the other adapters share.
+//
+// VERIFIED-gap: `@chorus-aidlc/chorus-pi` is published at the next coordinated
+// release (A2), so the npm-install path could not be exercised end-to-end on this
+// build host. The command shapes + graceful fallback are implemented; the spec's
+// `pi install npm:<pkg>` form is the documented, reviewed command (pi-mcp-adapter is
+// published — verified 2.32.1).
+// ---------------------------------------------------------------------------
+const PI_ADAPTER_SPEC = "npm:pi-mcp-adapter";
+const PI_NPM_SPEC = "npm:@chorus-aidlc/chorus-pi";
+
+/**
+ * Read pi's install state. `pi install` records each package's source in the
+ * agent settings file (`<PI_CODING_AGENT_DIR|~/.pi/agent>/settings.json`) under a
+ * `packages[]` array — entries are either a string source (`npm:@scope/pkg`) or an
+ * object carrying that source plus filtering. We substring-match the stringified
+ * entry so detection is robust to either shape. This is the file-read probe the pi
+ * adapter previously lacked (its descriptor had no `readState`, so the runtime
+ * defaulted `pluginInstalled:false` and every re-run reported a fresh INSTALL
+ * instead of the SKIPPED/upgrade messaging the other adapters give).
+ */
+export function readPiInstallState({ env = process.env, readJson = readJsonSafe } = {}) {
+  const home = env.HOME || homedir();
+  const agentDir = nonEmpty(env.PI_CODING_AGENT_DIR) || join(home, ".pi", "agent");
+  const settings = readJson(join(agentDir, "settings.json"));
+  const pkgs = Array.isArray(settings?.packages) ? settings.packages : [];
+  const hasPkg = (needle) =>
+    pkgs.some((p) => (typeof p === "string" ? p : JSON.stringify(p)).includes(needle));
+  const adapterInstalled = hasPkg("pi-mcp-adapter");
+  const pluginInstalled = hasPkg("@chorus-aidlc/chorus-pi");
+  return {
+    marketplaceRegistered: false, // pi has no marketplace concept
+    pluginInstalled: pluginInstalled && adapterInstalled,
+    chorusPiInstalled: pluginInstalled,
+    adapterInstalled,
+  };
+}
+
+export function installPi(ctx) {
+  const run = ctx.run ?? runCommand;
+  const env = ctx.env ?? process.env;
+
+  // `pi` must be on PATH to run the install. Probe via PATH (NOT `run`) so an
+  // absent pi surfaces the manual commands and executes NOTHING — and, because
+  // UNSUPPORTED is not a FAILURE_ACTION, never aborts `chorus init`. Injectable
+  // for unit tests (mirrors installDsh's pnpm precheck).
+  const hasBinary = ctx.binaryOnPath ?? binaryOnPath;
+  if (!hasBinary(["pi"], { env })) {
+    return out(
+      "pi",
+      UNSUPPORTED,
+      `pi CLI not found on PATH — install the Chorus extension manually once pi is available: ` +
+        `\`pi install ${PI_ADAPTER_SPEC} && pi install ${PI_NPM_SPEC}\``,
+    );
+  }
+
+  const state = safeState(ctx);
+  const bothInstalled = state.chorusPiInstalled && state.adapterInstalled;
+
+  // Already fully installed → recognize it (parity with codex/kiro's "already
+  // installed") and do NOTHING, unless the caller explicitly asked to update.
+  if (bothInstalled && !ctx.flags?.updateInstalled) {
+    return out(
+      "pi",
+      SKIPPED,
+      `already installed (${PI_ADAPTER_SPEC} + ${PI_NPM_SPEC} in pi settings) — re-run with --update-installed to upgrade`,
+    );
+  }
+
+  // Update requested on an existing install → use pi's OWN updater. `pi install`
+  // of an already-recorded package only re-writes the settings entry; it does NOT
+  // pull the newer published version, so it never clears pi's "Package updates
+  // available — Run pi update --extensions" nag. `pi update --extensions` (exactly
+  // what that nag tells the user to run) refreshes installed extensions — including
+  // chorus-pi + pi-mcp-adapter — to their latest published versions.
+  if (bothInstalled) {
+    const u = run("pi", ["update", "--extensions"], { env });
+    if (!u.ok) return out("pi", FAILED, `pi update --extensions failed: ${errText(u)}`);
+    return out("pi", REPAIRED, `updated installed pi extensions to latest via \`pi update --extensions\` (incl. ${PI_NPM_SPEC})`);
+  }
+
+  // Fresh or partial install → install what's needed (pi install is idempotent for
+  // any already-present one). The MCP adapter is the tool surface, so install it
+  // FIRST; then the chorus-pi package.
+  const ra = run("pi", ["install", PI_ADAPTER_SPEC], { env });
+  if (!ra.ok) return out("pi", FAILED, `pi install ${PI_ADAPTER_SPEC} failed: ${errText(ra)}`);
+  const r = run("pi", ["install", PI_NPM_SPEC], { env });
+  if (!r.ok) return out("pi", FAILED, `pi install failed: ${errText(r)}`);
+
+  // A partial pre-existing install we just completed → REPAIRED; a clean first
+  // install → INSTALLED (same distinction the other adapters draw).
+  return state.chorusPiInstalled || state.adapterInstalled
+    ? out("pi", REPAIRED, `reinstalled ${PI_ADAPTER_SPEC} + ${PI_NPM_SPEC} via pi install`)
+    : out("pi", INSTALLED, `installed ${PI_ADAPTER_SPEC} + ${PI_NPM_SPEC} via pi install`);
 }
 
 // ---------------------------------------------------------------------------
@@ -457,14 +630,16 @@ export async function installKiro(ctx) {
   const chorusUrl = nonEmpty(ctx.flags?.url) ?? nonEmpty(env.CHORUS_URL);
 
   const state = safeState(ctx);
-  if (state.pluginInstalled) return out("kiro", SKIPPED, `already installed (${kiroDir})`);
+  if (state.pluginInstalled && !ctx.flags?.updateInstalled) {
+    return out("kiro", SKIPPED, `already installed (${kiroDir})`);
+  }
 
   if (!chorusUrl) {
     return out("kiro", FAILED, "no Chorus URL — pass --url or set CHORUS_URL so the .kiro/ template can be downloaded from the connected instance");
   }
 
   // Any chorus-* asset already present ⇒ this is a delta repair, not a fresh drop.
-  const repairing = !!(state.skillsPresent || state.agentPresent || state.mcpServerPresent);
+  const repairing = !!(state.pluginInstalled || state.skillsPresent || state.agentPresent || state.mcpServerPresent);
   try {
     const res = await installFileTemplate({
       chorusUrl,
@@ -485,9 +660,13 @@ export async function installKiro(ctx) {
 }
 
 // ---------------------------------------------------------------------------
-// Guided (not automated). These agents have no verified native install path, so
-// — per the "no guessed command" rule — we surface a precise next step instead
-// of running an unverified command.
+// Guided (not automated) — the fallback mechanism for an agent that has no
+// verified native install path: surface a precise next step instead of running
+// an unverified command (the "no guessed command" rule). NO agent currently
+// ships as guided — claude / codex / opencode / openclaw / kiro / dsh / pi all
+// have real installers (pi flipped to `installPi` once @chorus-aidlc/chorus-pi
+// shipped to npm). `guided()` is kept as the mechanism for a future agent added
+// before its install command is verified.
 // ---------------------------------------------------------------------------
 export function guided(agentId, detail) {
   // Tag the returned function so adapters.mjs can tell a GUIDED (unsupported)
@@ -499,10 +678,6 @@ export function guided(agentId, detail) {
   return fn;
 }
 
-export const GUIDED_MESSAGES = {
-  // Pi HAS an extension surface (`pi install <source>`) — this message must NOT
-  // claim otherwise. What's missing is a published Chorus Pi extension for
-  // `chorus agents add` to install automatically, so the accurate guidance is the real
-  // manual command against that source once it's available.
-  pi: "Pi installs extensions with `pi install <source>`; Chorus does not yet publish a Pi extension for `chorus agents add` to automate, so install it manually with `pi install <source>` when a Chorus Pi source is available.",
-};
+// No agents are currently guided; kept as the stable export the adapter registry
+// and tests reference. A future not-yet-verified agent adds its message here.
+export const GUIDED_MESSAGES = {};

package/cli/init/pi-mcp-config.mjs

@@ -0,0 +1,166 @@
+// cli/init/pi-mcp-config.mjs
+// Writes the Chorus MCP server block into pi's global MCP config
+// (`~/.pi/agent/mcp.json` by default) so pi's `pi-mcp-adapter` exposes the
+// `chorus_*` tools to the pi agent — the ADAPTER path (chorus.ts never registers
+// tools itself). The Authorization header references the API key by ENV VAR
+// (`Bearer ${CHORUS_API_KEY}`, which pi-mcp-adapter interpolates at connect time),
+// so the `cho_` key lives in exactly ZERO files here — only the env-var reference.
+// The URL is not a secret, so it is written as a resolved literal (an interactive pi
+// then needs only CHORUS_API_KEY in its shell, not CHORUS_URL).
+//
+// This is the pi analogue of cli/init/codex-mcp-config.mjs (Codex's keyless
+// `[mcp_servers.chorus] bearer_token_env_var`) and the CC plugin `.mcp.json`
+// (`Authorization: Bearer ${CHORUS_URL}`-style ${VAR} interpolation). `pi install`
+// does NOT write an mcp.json for us, so `chorus agents add` writes it here (from the
+// credential-seed step, which already holds the resolved URL).
+//
+// CONFIG CONTRACT (VERIFIED against pi-mcp-adapter 2.32.1 npm readme, repo
+// github.com/nicobailon/pi-mcp-adapter):
+//   - The adapter discovers a Pi GLOBAL override at `<Pi agent dir>/mcp.json`
+//     (`~/.pi/agent/mcp.json` by default, or `$PI_CODING_AGENT_DIR/mcp.json` when set)
+//     — the same file `pi-mcp-adapter init` writes to by default, and higher precedence
+//     than the tool-agnostic `~/.config/mcp/mcp.json`.
+//   - An `mcpServers.<name>` entry supports `type:"http"`, a `url` (raw `${VAR}` /
+//     `$env:VAR` interpolation) and `headers` (also `${VAR}` / `$env:VAR`
+//     interpolation). We use `headers.Authorization = "Bearer ${CHORUS_API_KEY}"` —
+//     the cleanest keyless form, and a one-token change from the literal-Bearer shape
+//     CONNECT_PI.md previously documented.
+//
+// Standard JSON merge (mcp.json is JSON, unlike Codex's TOML): every other top-level
+// field and every OTHER `mcpServers.<name>` entry is preserved verbatim; only
+// `mcpServers.chorus` is upserted. Any legacy literal `bearerToken` on the chorus
+// entry is dropped and a literal `headers.Authorization` is replaced by the env-ref,
+// so a re-run MIGRATES an old literal key off disk. Atomic 0600 temp+rename;
+// idempotent (a re-run with the same url reproduces the file). IO is injectable for
+// tests. The API key is NEVER written — only the env-var reference.
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const API_KEY_ENV = "CHORUS_API_KEY";
+// A normal (non-template) string: `${CHORUS_API_KEY}` is emitted verbatim into the
+// JSON for pi-mcp-adapter to interpolate at connect time — no literal key on disk.
+const AUTHORIZATION_ENV_REF = "Bearer ${" + API_KEY_ENV + "}";
+
+/** A non-empty trimmed string, or undefined. */
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Resolve the pi GLOBAL MCP config path. Honors `PI_CODING_AGENT_DIR` (pi-mcp-adapter's
+ * own override of the Pi agent dir), then `HOME` (so tests can inject a temp home), else
+ * the OS home dir — ending in `mcp.json`. VERIFIED default `~/.pi/agent/mcp.json`.
+ * @param {Record<string, string | undefined>} env
+ */
+export function resolvePiMcpConfigPath(env) {
+  const base = nonEmpty(env.PI_CODING_AGENT_DIR) ?? join(nonEmpty(env.HOME) ?? homedir(), ".pi", "agent");
+  return join(base, "mcp.json");
+}
+
+/**
+ * Normalize a Chorus base URL to the MCP endpoint the same way the Codex writer
+ * (codex-mcp-config.mjs) and the hook wrapper do: a URL that already has a path segment
+ * beyond the host is used as-is; a bare host gains `/api/mcp`. Returns undefined for an
+ * empty URL.
+ * @param {string | undefined} rawUrl
+ */
+export function piMcpUrl(rawUrl) {
+  const u = nonEmpty(rawUrl);
+  if (!u) return undefined;
+  const trimmed = u.replace(/\/+$/, "");
+  const m = trimmed.match(/^https?:\/\/[^/]+(\/.*)?$/);
+  if (m && m[1] && m[1].length > 0) return trimmed; // already a full endpoint
+  return `${trimmed}/api/mcp`;
+}
+
+/** True for a plain (non-array) object. */
+function isPlainObject(v) {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+/**
+ * Upsert `mcpServers.chorus` in pi's global mcp.json to
+ *   { "type": "http", "url": "<mcp-endpoint>", "headers": { "Authorization": "Bearer ${CHORUS_API_KEY}" } }
+ * MERGE-SAFE: every other top-level field and every OTHER `mcpServers.<name>` entry is
+ * preserved verbatim; on the chorus entry itself every other key (e.g. `toolPrefix`,
+ * `includeTools`) is preserved, only `type`/`url`/`headers.Authorization` are set. A legacy
+ * literal `bearerToken` on the chorus entry is DROPPED and any literal `headers.Authorization`
+ * is replaced by the env-ref — migrating an old literal key off disk.
+ *
+ * Missing file → start from `{}`. An existing UNPARSEABLE file, a non-object root, or a
+ * present-but-non-object `mcpServers` → THROW (never clobber a file we cannot safely merge;
+ * the caller treats a throw as a write failure). Atomic 0600 temp+rename; idempotent (a re-run
+ * with the same url reproduces the file). The API key is NEVER written — only the env-var
+ * reference `${CHORUS_API_KEY}`.
+ * @param {{ configPath: string, url: string }} args
+ * @param {{
+ *   read?: (p: string) => string,
+ *   write?: (p: string, c: string, o: object) => void,
+ *   mkdir?: (p: string, o: object) => void,
+ *   rename?: (from: string, to: string) => void,
+ * }} [deps]
+ * @returns {string} the mcp.json path written
+ */
+export function writePiMcpServer({ configPath, url }, deps = {}) {
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+  const write = deps.write ?? writeFileSync;
+  const mkdir = deps.mkdir ?? mkdirSync;
+  const rename = deps.rename ?? renameSync;
+
+  const mcpUrl = piMcpUrl(url);
+  if (!mcpUrl) throw new Error("writePiMcpServer requires a url");
+
+  let raw;
+  try {
+    raw = read(configPath);
+  } catch {
+    raw = undefined; // no file yet — start fresh
+  }
+
+  let parsed = {};
+  if (typeof raw === "string" && raw.trim()) {
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`existing ${configPath} is not valid JSON (${err?.message ?? err}) — refusing to overwrite`);
+    }
+    if (!isPlainObject(parsed)) {
+      throw new Error(`existing ${configPath} is not a JSON object — refusing to overwrite`);
+    }
+  }
+
+  // Preserve an existing `mcpServers` object (and every server in it); a present-but-non-object
+  // `mcpServers` is unsafe to merge.
+  let servers = parsed.mcpServers;
+  if (servers === undefined || servers === null) {
+    servers = {};
+  } else if (!isPlainObject(servers)) {
+    throw new Error(`existing ${configPath} has a non-object "mcpServers" block — refusing to overwrite`);
+  }
+
+  // Preserve every OTHER key on the chorus entry (e.g. toolPrefix / includeTools), and every
+  // OTHER header, but drop the legacy literal `bearerToken` (a secret) and overwrite
+  // Authorization with the keyless env-ref.
+  const existingChorus = isPlainObject(servers.chorus) ? servers.chorus : {};
+  const existingHeaders = isPlainObject(existingChorus.headers) ? existingChorus.headers : {};
+  const chorusRest = { ...existingChorus };
+  delete chorusRest.bearerToken; // drop any legacy literal token (a secret) — we use the env-ref header
+
+  servers.chorus = {
+    ...chorusRest,
+    type: "http",
+    url: mcpUrl,
+    headers: { ...existingHeaders, Authorization: AUTHORIZATION_ENV_REF },
+  };
+  parsed.mcpServers = servers;
+
+  const content = `${JSON.stringify(parsed, null, 2)}\n`;
+
+  mkdir(dirname(configPath), { recursive: true });
+  const tmp = `${configPath}.tmp`;
+  write(tmp, content, { mode: 0o600 });
+  rename(tmp, configPath);
+  return configPath;
+}