@chorus-aidlc/chorus 0.17.1 → 0.17.3

package/cli/dsh-spawner.mjs

@@ -28,7 +28,10 @@ function isFile(path) {
   }
 }
 
-/** Resolve the external SDK runtime. CHORUS_DSH_PATH overrides PATH. */
+/**
+ * Resolve the external `dsh` CLI (the profile launcher — dsh 0.1.2-rc.1 removed
+ * the standalone `dsh-jsonrpc-agent` bin). CHORUS_DSH_PATH overrides PATH.
+ */
 export function resolveDshPath(deps = {}) {
   const env = deps.env ?? process.env;
   const platform = deps.platform ?? process.platform;
@@ -38,9 +41,7 @@ export function resolveDshPath(deps = {}) {
 
   const windows = platform === "win32";
   const path = windows ? pathWin32 : pathPosix;
-  const names = windows
-    ? ["dsh-jsonrpc-agent.cmd", "dsh-jsonrpc-agent.exe", "dsh-jsonrpc-agent"]
-    : ["dsh-jsonrpc-agent"];
+  const names = windows ? ["dsh.cmd", "dsh.exe", "dsh"] : ["dsh"];
   const dirs = (env.PATH || env.Path || "").split(path.delimiter).filter(Boolean);
   for (const dir of dirs) {
     for (const name of names) {
@@ -51,9 +52,14 @@ export function resolveDshPath(deps = {}) {
   return null;
 }
 
-/** Resolve the required Cordis composition without placing it in argv. */
-export function resolveDshConfig(env = process.env) {
-  return nonEmpty(env.CHORUS_DSH_CONFIG) ?? nonEmpty(env.DSH_CORDIS_CONFIG);
+/**
+ * An operator-supplied managed home override. When set, the daemon boots
+ * `dsh --profile sdk` against this pre-composed DSH_HOME and skips managed
+ * profile preparation entirely (the escape hatch replacing the old
+ * DSH_CORDIS_CONFIG override — which is gone with the removed cordis.yml model).
+ */
+export function resolveDshHome(env = process.env) {
+  return nonEmpty(env.CHORUS_DSH_HOME);
 }
 
 /** Windows npm command shims need cmd.exe while retaining argv isolation. */
@@ -143,8 +149,9 @@ export class DshSpawner {
   }
 
   async wake({ prompt, sessionId: anchor, cwd, onMessage, onChild }) {
-    let dshPath = this.dshPath ?? this.resolveDshPathFn({ env: this.env, platform: this.platform });
-    let config = resolveDshConfig(this.env);
+    const dshPath = this.dshPath ?? this.resolveDshPathFn({ env: this.env, platform: this.platform });
+    let dshHome = resolveDshHome(this.env);
+    let patchPath = null;
     const result = (backendSessionId, exitCode) => ({
       sessionId: backendSessionId || anchor || "",
       backendSessionId: backendSessionId || null,
@@ -154,11 +161,11 @@ export class DshSpawner {
 
     if (!dshPath) {
       this.logger.error(
-        "[Chorus] cannot locate `dsh-jsonrpc-agent`; install it or set CHORUS_DSH_PATH",
+        "[Chorus] cannot locate the `dsh` CLI; install DeepSeek Harness (dsh) or set CHORUS_DSH_PATH",
       );
       return result(null, null);
     }
-    if (!config) {
+    if (!dshHome) {
       try {
         const managed = await this.prepareManagedConfigFn({
           env: this.env,
@@ -166,10 +173,10 @@ export class DshSpawner {
           dshPath,
           creds: this.creds,
         });
-        config = managed.configPath;
-        dshPath = managed.runtimePath ?? dshPath;
+        dshHome = managed.home;
+        patchPath = managed.patchPath ?? null;
       } catch (error) {
-        this.logger.error(`[Chorus] cannot prepare managed dsh config: ${errorText(error)}`);
+        this.logger.error(`[Chorus] cannot prepare managed dsh profile: ${errorText(error)}`);
         return result(null, null);
       }
     }
@@ -182,7 +189,7 @@ export class DshSpawner {
     const childEnv = {
       ...this.env,
       CHORUS_DAEMON_HEADLESS: "1",
-      DSH_CORDIS_CONFIG: config,
+      DSH_HOME: dshHome,
       DSH_CWD: cwd || process.cwd(),
     };
     if (this.creds?.url) childEnv.CHORUS_URL = this.creds.url;
@@ -195,7 +202,18 @@ export class DshSpawner {
     if (this.creds?.agentUuid || this.creds?.agentName)
       childEnv.CHORUS_AGENT_PROFILE = this.creds.agentUuid || this.creds.agentName;
 
-    const { command, argv } = resolveDshSpawnCommand(dshPath, this.platform, childEnv);
+    // `dsh --profile sdk` boots the managed profile from DSH_HOME. The Chorus
+    // rows auto-apply as a bundle layer, so `--patch` is added only for a
+    // non-default provider overlay. resolveDshSpawnCommand keeps the win32 .cmd
+    // wrapper prefix; the launcher argv follows it.
+    const launch = resolveDshSpawnCommand(dshPath, this.platform, childEnv);
+    const command = launch.command;
+    const argv = [
+      ...launch.argv,
+      "--profile",
+      "sdk",
+      ...(patchPath ? ["--patch", patchPath] : []),
+    ];
     let child;
     try {
       child = this.spawnImpl(command, argv, {

package/cli/init/adapters.mjs

@@ -35,13 +35,13 @@ import {
   installDsh,
   installOpenclaw,
   installKiro,
+  installPi,
   readCodexInstallState,
   readOpencodeInstallState,
   readDshInstallState,
   readOpenclawInstallState,
   readKiroInstallState,
-  guided,
-  GUIDED_MESSAGES,
+  readPiInstallState,
 } from "./install-methods.mjs";
 
 // Re-export the shared marketplace identifiers from their canonical home so
@@ -95,7 +95,7 @@ export const AGENT_DESCRIPTORS = [
   { id: "kiro", displayName: "Kiro CLI", binaries: ["kiro"], configDirs: ["~/.kiro"], readState: readKiroInstallState, install: installKiro },
   { id: "opencode", displayName: "opencode", binaries: ["opencode"], configDirs: ["~/.config/opencode", "~/.opencode"], readState: readOpencodeInstallState, install: installOpencode },
   { id: "openclaw", displayName: "OpenClaw", binaries: ["openclaw"], configDirs: ["~/.openclaw", "~/.config/openclaw"], readState: readOpenclawInstallState, install: installOpenclaw },
-  { id: "pi", displayName: "Pi", binaries: ["pi"], configDirs: ["~/.pi", "~/.config/pi"], install: guided("pi", GUIDED_MESSAGES.pi) },
+  { id: "pi", displayName: "Pi", binaries: ["pi"], configDirs: ["~/.pi", "~/.config/pi"], readState: readPiInstallState, install: installPi },
   { id: "dsh", displayName: "DeepSeek Harness (dsh)", binaries: ["dsh"], configDirs: ["$DSH_HOME", "~/.dsh"], readState: readDshInstallState, install: installDsh },
 ];
 
@@ -117,8 +117,8 @@ export function buildAdapter(d) {
       // `guided()` fallback also returns a function (so `typeof d.install ===
       // "function"` alone would report every fallback agent as supported — the
       // pre-existing latent bug); guided installers are tagged `.guided === true`,
-      // so exclude them here. Real installers (claude/codex/opencode + dsh/openclaw/
-      // kiro) → true; guided (pi) → false.
+      // so exclude them here. Every current agent (claude/codex/opencode + dsh/
+      // openclaw/kiro/pi) has a real installer → true; a future guided fallback → false.
       return { supported: typeof d.install === "function" && d.install.guided !== true, ...base };
     },
     installPlugin: (ctx = {}) =>

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/install-methods.mjs

@@ -468,6 +468,120 @@ export function installOpenclaw(ctx) {
     : 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`);
+}
+
 // ---------------------------------------------------------------------------
 // Kiro — NATIVE FILE-TEMPLATE install (Kiro has NO plugin CLI). Its "plugin" is a
 // set of loose files under .kiro/ (what public/install-kiro.sh drops). We
@@ -546,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)
@@ -560,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;
+}

package/cli/init/steps/credential-seed.mjs

@@ -53,6 +53,7 @@ import {
 import { resolveInstallCwds as defaultResolveInstallCwds } from "../../daemon-install-config.mjs";
 import { validateAndFetchIdentity } from "../../chorus-client.mjs";
 import { agentTypeForSelection, isWakeableAgentType } from "../agent-type-map.mjs";
+import { writePiMcpServer, resolvePiMcpConfigPath } from "../pi-mcp-config.mjs";
 
 const STEP_ID = "credential-seed";
 const { SEEDED, SKIPPED, FAILED } = OUTCOME_ACTIONS;
@@ -421,6 +422,23 @@ export function readCodexEnvProfile(envPath, deps = {}) {
   }
 }
 
+/**
+ * Whether an init selection id is Pi (`pi`). Pi's Chorus MCP access is via the ADAPTER
+ * path (`pi-mcp-adapter` reads an mcp.json — chorus.ts never registers tools itself), so
+ * — like Codex's `[mcp_servers.chorus]` — `chorus agents add` writes pi's global
+ * `~/.pi/agent/mcp.json` with an `mcpServers.chorus` entry whose Authorization references
+ * the API key by ENV VAR (`Bearer ${CHORUS_API_KEY}`), NO literal key on disk. Unlike dsh /
+ * Claude Code / Codex, pi has NO settings env-file to persist the key + profile into, so this
+ * write does NOT suppress the CHORUS_AGENT_PROFILE export hint: interactive pi still needs
+ * CHORUS_API_KEY (+ CHORUS_AGENT_PROFILE) exported in its shell. We gate on the selection id,
+ * NOT the mapped daemon agentType (`pi` → the shared "offline" type, so it can't single pi
+ * out). Mirrors {@link isDshSelection} / {@link isClaudeSelection} / {@link isCodexSelection}.
+ * @param {string} id
+ */
+function isPiSelection(id) {
+  return id === "pi";
+}
+
 /**
  * @param {import("../contracts.mjs").StepContext & {
  *   validateCredentials?: Function, appendAgent?: Function, writeLogin?: Function,
@@ -442,6 +460,7 @@ export async function seedCredentials(ctx) {
   const readSettingsProfile = ctx.readClaudeSettingsProfile ?? readClaudeSettingsProfile;
   const writeCodexEnv = ctx.writeCodexEnv ?? writeCodexEnvFile;
   const readCodexProfile = ctx.readCodexEnvProfile ?? readCodexEnvProfile;
+  const writePiMcp = ctx.writePiMcp ?? writePiMcpServer;
 
   const selection = Array.isArray(ctx.selection) ? ctx.selection.filter((id) => nonEmpty(id)) : [];
   if (selection.length === 0) {
@@ -708,13 +727,47 @@ export async function seedCredentials(ctx) {
       }
     }
 
-    // Combined side-file note + hint-suppression flags (dsh, claude, and codex are mutually
-    // exclusive selection ids, so at most one note/flag is set per iteration).
-    const sideNote = `${dshNote}${claudeNote}${codexNote}`;
+    // pi-only: ALSO write pi's global ~/.pi/agent/mcp.json so `pi-mcp-adapter` exposes the
+    // chorus_* tools to the pi agent (the ADAPTER path — chorus.ts never registers tools). The
+    // Authorization header references the key by env var (`Bearer ${CHORUS_API_KEY}`), so NO
+    // literal cho_ key is written — the pi analogue of Codex's keyless [mcp_servers.chorus]
+    // bearer_token_env_var and CC's plugin .mcp.json ${VAR} interpolation. The URL is not a
+    // secret, so it is a resolved literal. UNGATED by daemon.json dedup (an idempotent re-run
+    // still repairs a missing/stale mcp.json). Unlike dsh/claude/codex this write does NOT
+    // suppress the CHORUS_AGENT_PROFILE export hint: pi has NO settings env-file to persist the
+    // key + profile into, so interactive pi still needs CHORUS_API_KEY (+ CHORUS_AGENT_PROFILE)
+    // in its shell — the daemon spawner injects them for the wake path. `piMcpWritten` is
+    // reported for observability only; it is intentionally NOT in the hint-suppression set.
+    let piNote = "";
+    let piMcpWritten = false;
+    if (isPiSelection(id)) {
+      const configPath = resolvePiMcpConfigPath(env);
+      try {
+        const p = writePiMcp({ configPath, url });
+        piMcpWritten = true;
+        piNote =
+          `; wrote mcpServers.chorus (Authorization: Bearer \${CHORUS_API_KEY}) into ${p} (0600) — ` +
+          "pi-mcp-adapter exposes the chorus_* tools with the cho_ key env-sourced (no literal key on " +
+          "disk). Interactive pi still needs CHORUS_API_KEY (+ CHORUS_AGENT_PROFILE) exported in its " +
+          "shell; the daemon injects them for the wake path. Your cho_ key is not shown here.";
+      } catch (err) {
+        piNote =
+          `; WARNING: could not write ${configPath} (${err?.message ?? String(err)}). ` +
+          "pi will not reach Chorus MCP until an mcpServers.chorus entry with an env-referenced " +
+          `Authorization (Bearer \${CHORUS_API_KEY}) exists — add it to ${configPath}. ` +
+          "Your cho_ key is not shown here.";
+      }
+    }
+
+    // Combined side-file note + hint-suppression flags (dsh, claude, codex, and pi are mutually
+    // exclusive selection ids, so at most one note is set per iteration). piMcpWritten is carried
+    // for observability but is NOT a hint-suppression flag (see the pi branch above).
+    const sideNote = `${dshNote}${claudeNote}${codexNote}${piNote}`;
     const hintFlags = {
       ...(profileInEnv ? { profileInEnv: true } : {}),
       ...(settingsEnvWritten ? { settingsEnvWritten: true } : {}),
       ...(codexEnvWritten ? { codexEnvWritten: true } : {}),
+      ...(piMcpWritten ? { piMcpWritten: true } : {}),
     };
 
     if (!res.ok) {