@chorus-aidlc/chorus 0.21.0 → 0.21.1

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

@@ -0,0 +1,160 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runCommand } from "./run-command.mjs";
+import {
+  PI_SUPPORTED_RANGE, PI_MIN_SUPPORTED_VERSION, PI_MAX_SUPPORTED_MAJOR,
+  PI_NATIVE_MCP_MIN_VERSION, PI_LEGACY_ADAPTER_SPEC,
+} from "./pi-compatibility.mjs";
+
+export const PI_CHORUS_SPEC = "npm:@chorus-aidlc/chorus-pi";
+const ADAPTER = "npm:pi-mcp-adapter";
+const object = (value) => value && typeof value === "object" && !Array.isArray(value);
+const compare = (left, right) => {
+  for (let index = 0; index < 3; index++) {
+    if (left[index] !== right[index]) return left[index] - right[index];
+  }
+  return 0;
+};
+
+export function parsePiVersion(output) {
+  const unknown = { mode: "unknown", version: null, supported: null,
+    reason: "Pi version unknown; run pi --version and confirm a stable supported host before completing MCP setup." };
+  if (typeof output !== "string") return unknown;
+  const matches = [...output.matchAll(/(?<![\w.+-])v?(\d+)\.(\d+)\.(\d+)(-[\w.-]+)?(?:\+[\w.-]+)?(?![\w.+-])/g)];
+  if (matches.length !== 1) return unknown;
+  const match = matches[0];
+  const parts = match.slice(1, 4).map(Number);
+  if (match[4] || parts.some((part) => !Number.isSafeInteger(part)) || match.slice(1, 4).some((part) => /^0\d/.test(part))) return unknown;
+  const version = parts.join(".");
+  const mode = compare(parts, PI_NATIVE_MCP_MIN_VERSION) >= 0 ? "native" : "legacy";
+  const supported = compare(parts, PI_MIN_SUPPORTED_VERSION) >= 0 && parts[0] < PI_MAX_SUPPORTED_MAJOR;
+  return { mode, version, supported, reason: supported ? `Pi ${version}: ${mode} MCP backend.`
+    : `Pi ${version} is unsupported; Chorus requires stable Pi ${PI_SUPPORTED_RANGE}. No package commands were run.` };
+}
+
+export function probePiBackend({ run = runCommand, env = process.env, cwd } = {}) {
+  try {
+    const result = run("pi", ["--version"], { env, cwd, timeoutMs: 5_000 });
+    return parsePiVersion(result?.ok ? result.stdout : undefined);
+  } catch {
+    return parsePiVersion(undefined);
+  }
+}
+
+export function piAgentDir(env = process.env) {
+  return env.PI_CODING_AGENT_DIR?.trim() || join(env.HOME || homedir(), ".pi", "agent");
+}
+
+export function piPackageSource(entry, spec) {
+  const source = typeof entry === "string" ? entry : object(entry) ? entry.source : undefined;
+  return typeof source === "string" && (source === spec || (source.startsWith(`${spec}@`) && source.length > spec.length + 1)) ? source : undefined;
+}
+
+function readSettings(path) {
+  try { return JSON.parse(readFileSync(path, "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return undefined; throw error; }
+}
+
+export function inspectPiSettings({ env = process.env, cwd = process.cwd(), readJson = readSettings } = {}) {
+  const scopes = [
+    { scope: "global", path: join(piAgentDir(env), "settings.json") },
+    { scope: "current-project", path: join(cwd, ".pi", "settings.json") },
+  ];
+  return scopes.map((entry) => {
+    try {
+      const settings = readJson(entry.path);
+      if (settings !== undefined && (!object(settings) ||
+        (settings.packages !== undefined && (!Array.isArray(settings.packages) || settings.packages.some((pkg) =>
+          typeof pkg !== "string" && !(object(pkg) && typeof pkg.source === "string")))) ||
+        (settings.extensions !== undefined && (!Array.isArray(settings.extensions) || settings.extensions.some((extension) => typeof extension !== "string"))))) throw new Error();
+      const packages = settings?.packages ?? [];
+      return { ...entry, packages, adapters: packages.map((pkg) => piPackageSource(pkg, ADAPTER)).filter(Boolean),
+        chorus: packages.map((pkg) => piPackageSource(pkg, PI_CHORUS_SPEC)).filter(Boolean),
+        nativeDisabled: settings?.extensions?.includes("-builtin:mcp") ?? false, uncertain: false };
+    } catch {
+      return { ...entry, packages: [], adapters: [], chorus: [], nativeDisabled: false, uncertain: true };
+    }
+  });
+}
+
+export function piMigrationWarnings(backend, scopes) {
+  const warnings = [];
+  for (const entry of scopes) {
+    if (entry.uncertain) warnings.push(`Cannot safely read ${entry.scope} Pi settings; package/MCP conflict state is uncertain. Inspect that settings.json manually.`);
+    if (backend.mode !== "native" || backend.supported === false) continue;
+    if (entry.adapters.length) warnings.push(`The ${entry.scope} pi-mcp-adapter replaces native MCP. To use native MCP, manually remove its package entry from ${entry.scope} settings.json (preserve other packages and filters); no adapter was removed or updated.`);
+    if (entry.nativeDisabled) warnings.push(`Native MCP is disabled by -builtin:mcp in ${entry.scope} settings.json. Manually re-enable it before expecting native tools; the filter was preserved.`);
+  }
+  return warnings;
+}
+
+export function readPiPackageState(options = {}) {
+  const scopes = inspectPiSettings(options);
+  const global = scopes[0];
+  const backend = options.backend ?? probePiBackend(options);
+  const chorusPiInstalled = global.chorus.length > 0;
+  const adapterInstalled = global.adapters.length > 0;
+  const adapterCompatible = adapterInstalled && global.adapters.every((source) => source === PI_LEGACY_ADAPTER_SPEC);
+  return { marketplaceRegistered: false, chorusPiInstalled, adapterInstalled, adapterCompatible, backend, scopes,
+    pluginInstalled: backend.supported === true && chorusPiInstalled && (backend.mode === "native" || adapterCompatible) };
+}
+
+export function managePiPackages({ backend, scopes, run = runCommand, env = process.env, cwd, update = false }) {
+  const warnings = piMigrationWarnings(backend, scopes);
+  const details = [backend.reason, ...warnings];
+  const global = scopes[0];
+  let complete = backend.supported === true, changed = false, failed = false;
+  const finish = () => ({ complete, changed, failed, warnings, detail: details.join(" ") });
+  if (backend.supported === false || global.uncertain) {
+    complete = false;
+    return finish();
+  }
+  const components = backend.mode === "legacy"
+    ? [{ spec: PI_LEGACY_ADAPTER_SPEC, sources: global.adapters, adapter: true }, { spec: PI_CHORUS_SPEC, sources: global.chorus }]
+    : [{ spec: PI_CHORUS_SPEC, sources: global.chorus }];
+  const help = new Map();
+  for (const component of components) {
+    const { spec, sources, adapter } = component;
+    const present = sources.length > 0;
+    if (adapter && present && sources.some((source) => source !== PI_LEGACY_ADAPTER_SPEC)) {
+      complete = false;
+      details.push(`Legacy adapter constraints/source are not the verified ${PI_LEGACY_ADAPTER_SPEC} policy pin; settings preserved. Review compatibility manually; latest/ranges are not verified.`);
+      continue;
+    }
+    if (present && !update) continue;
+    if (adapter && present) {
+      details.push(`Retained verified compatibility pin ${PI_LEGACY_ADAPTER_SPEC}; no unbounded adapter update.`);
+      continue;
+    }
+    if (present && sources.some((source) => source !== spec && source !== `${spec}@latest`)) {
+      complete = false;
+      details.push("Chorus version constraints preserved; latest refresh incomplete. Other eligible components were attempted.");
+      continue;
+    }
+    const operation = present ? "update" : "install";
+    if (!help.has(operation)) {
+      const result = run("pi", [operation, "--help"], { env, cwd });
+      help.set(operation, result?.ok && /--no-approve\b/.test(result.stdout) &&
+        (operation !== "update" || /--extension\s+<source>/.test(result.stdout)));
+    }
+    if (!help.get(operation)) {
+      complete = false;
+      details.push(`Pi targeted ${operation} unsupported; no all-extension update was run.`);
+      continue;
+    }
+    const args = present ? ["update", "--extension", sources[0], "--no-approve"] : ["install", spec, "--no-approve"];
+    changed = true;
+    let result;
+    try { result = run("pi", args, { env, cwd }); } catch { result = { ok: false }; }
+    if (!result?.ok) {
+      complete = false;
+      failed = true;
+      details.push(`Pi ${operation} failed for ${adapter ? "the compatibility adapter" : "Chorus"}; setup incomplete.`);
+      if (adapter && !update) break;
+    }
+  }
+  if (complete) details.push(`${changed ? "Refreshed" : "Already installed"} required ${backend.mode} packages only; MCP connectivity is not verified.`);
+  else details.push("MCP setup incomplete; resolve the diagnostics and rerun.");
+  return finish();
+}

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

@@ -1,40 +1,5 @@
-// 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 { closeSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -49,14 +14,13 @@ function nonEmpty(value) {
 }
 
 /**
- * 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`.
+ * Resolve the global native mcp.json or legacy adapter5 mcp-adapter.json path.
+ * Honors PI_CODING_AGENT_DIR, then HOME, then the OS home directory.
  * @param {Record<string, string | undefined>} env
  */
-export function resolvePiMcpConfigPath(env) {
+export function resolvePiMcpConfigPath(env, backend = {}) {
   const base = nonEmpty(env.PI_CODING_AGENT_DIR) ?? join(nonEmpty(env.HOME) ?? homedir(), ".pi", "agent");
-  return join(base, "mcp.json");
+  return join(base, backend.mode === "legacy" && backend.supported !== false ? "mcp-adapter.json" : "mcp.json");
 }
 
 /**
@@ -81,7 +45,7 @@ function isPlainObject(v) {
 }
 
 /**
- * Upsert `mcpServers.chorus` in pi's global mcp.json to
+ * Upsert `mcpServers.chorus` in the selected backend's global config 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`,
@@ -94,16 +58,16 @@ function isPlainObject(v) {
  * 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 {{ configPath: string, url: string, backend?: object }} args
  * @param {{
  *   read?: (p: string) => string,
- *   write?: (p: string, c: string, o: object) => void,
+ *   write?: (descriptor: number, content: string) => void,
  *   mkdir?: (p: string, o: object) => void,
  *   rename?: (from: string, to: string) => void,
  * }} [deps]
- * @returns {string} the mcp.json path written
+ * @returns {string} the config path written
  */
-export function writePiMcpServer({ configPath, url }, deps = {}) {
+export function writePiMcpServer({ configPath, url, backend = {} }, deps = {}) {
   const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
   const write = deps.write ?? writeFileSync;
   const mkdir = deps.mkdir ?? mkdirSync;
@@ -112,24 +76,34 @@ export function writePiMcpServer({ configPath, url }, deps = {}) {
   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()) {
+  function load(path) {
+    let raw;
     try {
-      parsed = JSON.parse(raw);
-    } catch (err) {
-      throw new Error(`existing ${configPath} is not valid JSON (${err?.message ?? err}) — refusing to overwrite`);
+      raw = read(path);
+    } catch (error) {
+      if (error.code === "ENOENT") return undefined;
+      throw new Error(`cannot read ${path} safely — refusing to overwrite`);
+    }
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch {
+      throw new Error(`existing ${path} is not valid JSON — refusing to overwrite`);
+    }
+    if (!isPlainObject(parsed)) throw new Error(`existing ${path} is not a JSON object — refusing to overwrite`);
+    if (parsed.mcpServers !== undefined && !isPlainObject(parsed.mcpServers)) {
+      throw new Error(`existing ${path} has a non-object "mcpServers" block — refusing to overwrite`);
     }
-    if (!isPlainObject(parsed)) {
-      throw new Error(`existing ${configPath} is not a JSON object — refusing to overwrite`);
+    if (parsed.mcpServers?.chorus !== undefined && !isPlainObject(parsed.mcpServers.chorus)) {
+      throw new Error(`existing ${path} has a non-object Chorus server — refusing to overwrite`);
     }
+    if (parsed.settings !== undefined && !isPlainObject(parsed.settings)) {
+      throw new Error(`existing ${path} has non-object settings — refusing to overwrite`);
+    }
+    return parsed;
   }
+  const legacy = backend.mode === "legacy" && backend.supported !== false;
+  let parsed = load(configPath);
+  if (legacy && parsed === undefined) parsed = load(join(dirname(configPath), "mcp.json"));
+  parsed ??= {};
 
   // Preserve an existing `mcpServers` object (and every server in it); a present-but-non-object
   // `mcpServers` is unsafe to merge.
@@ -150,6 +124,7 @@ export function writePiMcpServer({ configPath, url }, deps = {}) {
 
   servers.chorus = {
     ...chorusRest,
+    ...(legacy && existingChorus.directTools === undefined && parsed.settings?.directTools === undefined ? { directTools: true } : {}),
     type: "http",
     url: mcpUrl,
     headers: { ...existingHeaders, Authorization: AUTHORIZATION_ENV_REF },
@@ -159,8 +134,17 @@ export function writePiMcpServer({ configPath, url }, deps = {}) {
   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);
+  const tmp = `${configPath}.${randomUUID()}.tmp`;
+  const descriptor = openSync(tmp, "wx", 0o600);
+  try {
+    try {
+      write(descriptor, content);
+    } finally {
+      closeSync(descriptor);
+    }
+    rename(tmp, configPath);
+  } finally {
+    try { unlinkSync(tmp); } catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
   return configPath;
 }

package/cli/init/registry.mjs

@@ -17,6 +17,7 @@
 import { ADAPTERS } from "./adapters.mjs";
 import { credentialSeedStep } from "./steps/credential-seed.mjs";
 import { pluginInstallStep } from "./steps/plugin-install.mjs";
+import { codexRestartStep } from "./steps/codex-restart.mjs";
 import { daemonSetupStep } from "./steps/daemon-setup.mjs";
 
 /** @typedef {import("./contracts.mjs").AgentAdapter} AgentAdapter */
@@ -32,10 +33,10 @@ export const AGENT_REGISTRY = [...ADAPTERS];
 
 /**
  * Configuration steps, run in ascending `order`: credential-seed (10),
- * plugin-install (20), daemon-setup (30). Sibling ideas push their steps too.
+ * plugin-install (20), codex-restart (25), daemon-setup (30).
  * @type {InitStep[]}
  */
-export const STEP_REGISTRY = [credentialSeedStep, pluginInstallStep, daemonSetupStep];
+export const STEP_REGISTRY = [credentialSeedStep, pluginInstallStep, codexRestartStep, daemonSetupStep];
 
 /**
  * Run every adapter's detection and return one AgentDetection per supported agent.

package/cli/init/run-command.mjs

@@ -9,7 +9,7 @@ import { spawnSync } from "node:child_process";
  * Run a command synchronously.
  * @param {string} cmd
  * @param {string[]} args
- * @param {{ env?: NodeJS.ProcessEnv, timeoutMs?: number, cwd?: string }} [opts]
+ * @param {{ env?: NodeJS.ProcessEnv, timeoutMs?: number, cwd?: string, maxBuffer?: number, killSignal?: string }} [opts]
  * @returns {{ ok: boolean, code: number|null, stdout: string, stderr: string, error?: string }}
  */
 export function runCommand(cmd, args = [], opts = {}) {
@@ -18,6 +18,8 @@ export function runCommand(cmd, args = [], opts = {}) {
       env: opts.env ?? process.env,
       cwd: opts.cwd,
       timeout: opts.timeoutMs ?? 120_000,
+      maxBuffer: opts.maxBuffer,
+      killSignal: opts.killSignal,
       encoding: "utf8",
     });
     if (r.error) {

package/cli/init/steps/codex-restart.mjs

@@ -0,0 +1,95 @@
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseEnv } from "node:util";
+import { OUTCOME_ACTIONS, STEP_SCOPES } from "../contracts.mjs";
+import { runCommand } from "../run-command.mjs";
+import { resolveCodexEnvPath } from "./credential-seed.mjs";
+
+const MANAGED_KEYS = ["CHORUS_URL", "CHORUS_API_KEY", "CHORUS_AGENT_PROFILE"];
+const MAX_OUTPUT = 64 * 1024;
+
+export const codexRestartStep = {
+  id: "codex-restart",
+  order: 25,
+  scope: STEP_SCOPES.PER_AGENT,
+  async run(ctx) {
+    if (ctx.agentId !== "codex" || ctx.flags?.pluginOnly) return [];
+
+    const env = ctx.env ?? process.env;
+    const envPath = resolveCodexEnvPath(env);
+    const codexHome = dirname(envPath);
+    const guidance = `Configuration directory: ${JSON.stringify(codexHome)}. ` +
+      "For manual recovery, inspect `codex app-server daemon restart --help` for support first. " +
+      "Before restarting a running daemon, load CHORUS_URL, CHORUS_API_KEY and CHORUS_AGENT_PROFILE " +
+      "from that directory's .env as environment data (not shell code), using the same CODEX_HOME. " +
+      "Restarting can interrupt other Codex sessions; no daemon is started or upgraded by this step.";
+    const outcome = (action, detail) => ({ stepId: "codex-restart", agentId: "codex", action, detail });
+    const defer = (reason) => outcome(OUTCOME_ACTIONS.SKIPPED, `Codex App Server restart deferred: ${reason}. ${guidance}`);
+    const prior = ctx.priorOutcomes ?? [];
+    const seeded = prior.some((entry) => entry.stepId === "credential-seed" &&
+      [OUTCOME_ACTIONS.SEEDED, OUTCOME_ACTIONS.SKIPPED].includes(entry.action) && entry.codexEnvWritten === true);
+    const configured = prior.some((entry) => entry.stepId === "plugin-install" && entry.agentId === "codex" &&
+      [OUTCOME_ACTIONS.INSTALLED, OUTCOME_ACTIONS.REPAIRED, OUTCOME_ACTIONS.SKIPPED].includes(entry.action) &&
+      entry.codexMcpWritten === true);
+    if (!seeded || !configured) return defer("credential persistence or plugin configuration did not complete");
+    if (!ctx.io?.isTTY || ctx.flags?.yes || env.CHORUS_DAEMON_HEADLESS === "1" || typeof ctx.io?.ask !== "function") {
+      return defer("a dedicated interactive confirmation is required (--yes does not authorize restart)");
+    }
+
+    let childEnv;
+    try {
+      const persisted = parseEnv(readFileSync(envPath, "utf8"));
+      if (MANAGED_KEYS.some((key) => !persisted[key]?.trim())) return defer("saved environment is incomplete");
+      childEnv = { ...env, CODEX_HOME: codexHome };
+      for (const key of MANAGED_KEYS) childEnv[key] = persisted[key];
+    } catch {
+      return defer("saved environment could not be read");
+    }
+
+    const run = ctx.run ?? runCommand;
+    const command = async (args, timeoutMs = 5_000) => {
+      try {
+        const result = await run("codex", ["app-server", "daemon", ...args], {
+          env: childEnv, timeoutMs, maxBuffer: MAX_OUTPUT, killSignal: "SIGKILL",
+        });
+        if (!result?.ok || typeof result.stdout !== "string" || result.stdout.length > MAX_OUTPUT ||
+          (result.stderr?.length ?? 0) > MAX_OUTPUT) return null;
+        return result;
+      } catch {
+        return null;
+      }
+    };
+    const help = await command(["restart", "--help"]);
+    if (!help || !/\bUsage:\s+codex app-server daemon restart\b/.test(help.stdout)) {
+      return defer("restart support could not be confirmed (missing/older CLI or failed probe)");
+    }
+    const version = await command(["version"]);
+    let status;
+    try {
+      status = JSON.parse(version?.stdout).status;
+    } catch {
+      return defer("daemon state could not be determined");
+    }
+    if (status === "stopped") return defer("no running daemon; nothing was started");
+    if (status !== "running") return defer("daemon state is unknown");
+
+    let answer;
+    try {
+      answer = await ctx.io.ask(
+        "Restart the running Codex App Server with the saved Chorus environment? " +
+        "This can interrupt other Codex sessions and active work. [y/N] ",
+      );
+    } catch {
+      return defer("confirmation was unavailable");
+    }
+    if (typeof answer !== "string" || !/^(?:y|yes)$/i.test(answer.trim())) return defer("not explicitly confirmed");
+
+    const restarted = await command(["restart"], 30_000);
+    if (!restarted) {
+      return outcome(OUTCOME_ACTIONS.FAILED, "Codex App Server restart command failed or timed out; " +
+        `saved configuration remains in place. ${guidance}`);
+    }
+    return outcome(OUTCOME_ACTIONS.REPAIRED,
+      "Codex App Server restart command succeeded with the saved environment; credentials and MCP connectivity were not verified.");
+  },
+};

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

@@ -54,6 +54,7 @@ import { resolveInstallCwds as defaultResolveInstallCwds } from "../../daemon-in
 import { validateAndFetchIdentity } from "../../chorus-client.mjs";
 import { agentTypeForSelection, isWakeableAgentType } from "../agent-type-map.mjs";
 import { writePiMcpServer, resolvePiMcpConfigPath } from "../pi-mcp-config.mjs";
+import { probePiBackend } from "../pi-mcp-backend.mjs";
 
 const STEP_ID = "credential-seed";
 const { SEEDED, SKIPPED, FAILED } = OUTCOME_ACTIONS;
@@ -356,7 +357,7 @@ function isCodexSelection(id) {
  * literal `[mcp_servers.chorus]` Bearer lives separately in `config.toml` and is untouched.
  * @param {Record<string, string | undefined>} env
  */
-function resolveCodexEnvPath(env) {
+export function resolveCodexEnvPath(env) {
   const base = nonEmpty(env.CODEX_HOME) ?? join(nonEmpty(env.HOME) ?? homedir(), ".codex");
   return join(base, ".env");
 }
@@ -423,16 +424,13 @@ 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
+ * Whether an init selection id is Pi (`pi`). Native MCP or the legacy adapter reads
+ * the selected global config 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}.
+ * not other hosts. Mirrors {@link isDshSelection} / {@link isClaudeSelection} / {@link isCodexSelection}.
  * @param {string} id
  */
 function isPiSelection(id) {
@@ -706,8 +704,8 @@ export async function seedCredentials(ctx) {
           // "start codex from an exporting shell", no wrapper. Key never echoed.
           codexNote =
             `; wrote CHORUS_URL/CHORUS_API_KEY/CHORUS_AGENT_PROFILE into ${p} (0600)${repointWarn} — ` +
-            "interactive Codex (plugin hooks: SessionStart check-in / PostToolUse, AND shell-tool " +
-            "`chorus` calls) authenticates with no manual export. Your cho_ key is not shown here.";
+            "new Codex processes load this environment for plugin hooks and shell-tool `chorus` calls; " +
+            "running App Server sessions may still use the old environment. Your cho_ key is not shown here.";
         } catch (err) {
           // Write failed (locked/unwritable). Emit an actionable, non-secret WARNING; the export
           // hint is still shown (codexEnvWritten stays false). No launcher wrapper.
@@ -727,8 +725,7 @@ export async function seedCredentials(ctx) {
       }
     }
 
-    // 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
+    // pi-only: write the selected native or legacy backend's global MCP configuration. 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
@@ -741,18 +738,22 @@ export async function seedCredentials(ctx) {
     let piNote = "";
     let piMcpWritten = false;
     if (isPiSelection(id)) {
-      const configPath = resolvePiMcpConfigPath(env);
+      const backend = probePiBackend({ run: ctx.run, env, cwd: ctx.cwd });
+      const configPath = resolvePiMcpConfigPath(env, backend);
       try {
-        const p = writePiMcp({ configPath, url });
+        const p = writePiMcp({ configPath, url, backend });
         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 " +
+          (backend.supported !== true ? `${backend.reason} MCP setup is incomplete. ` : backend.mode === "native"
+            ? "native MCP uses its default codemode; no adapter is required. "
+            : "legacy pi-mcp-adapter 5.0.0 uses mcp-adapter.json (takes precedence over migrated mcp.json). Fresh Chorus configuration enables directTools:true; existing user choices are preserved. Direct tool exposure is required for workflow/reviewer tool names. ") +
+          "Package/configuration setup does not verify live MCP connectivity. No literal key is written. " +
+          "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) {
+      } catch {
         piNote =
-          `; WARNING: could not write ${configPath} (${err?.message ?? String(err)}). ` +
+          `; WARNING: could not write ${configPath} safely; inspect existing configuration without overwriting it. ` +
           "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.";

package/cli/init.mjs

@@ -125,10 +125,10 @@ export async function runInit(argv = [], deps = {}) {
       if (step.scope === STEP_SCOPES.PER_AGENT) {
         for (const agentId of selectedIds) {
           const adapter = adapters.get(agentId);
-          outcomes.push(await step.run({ ...baseCtx, agentId, adapter }));
+          outcomes.push(await step.run({ ...baseCtx, agentId, adapter, priorOutcomes: outcomes.flat() }));
         }
       } else {
-        outcomes.push(await step.run(baseCtx));
+        outcomes.push(await step.run({ ...baseCtx, priorOutcomes: outcomes.flat() }));
       }
     } catch (err) {
       // A crashing step becomes a visible failed outcome, never a silent abort.

package/cli/upgrade-plugins.mjs

@@ -7,6 +7,7 @@ import { readClaudeInstallState } from "./init/adapters.mjs";
 import { installClaude, installCodex, installKiro, readCodexInstallState } from "./init/install-methods.mjs";
 import { normalizeAssetBase } from "./init/file-template.mjs";
 import { runUpgradeCommand, sanitizeUpgradeOutput, upgradeFailure } from "./upgrade-process.mjs";
+import { probePiBackend, inspectPiSettings, managePiPackages } from "./init/pi-mcp-backend.mjs";
 
 const HOSTS = {
   claude: { binary: "claude", variable: "CLAUDE_CONFIG_DIR", dir: [".claude"] },
@@ -86,47 +87,11 @@ function readJson(path, io) {
   catch (e) { if (e.code === "ENOENT") return undefined; throw e; }
 }
 
-// Verified against installed pi update/install --help (2026-09-30). Probe the
-// actual target host as older releases have only the all-extension updater.
-export function upgradePi(target, { run, fs: io = fs }) {
-  const settings = readJson(join(target.destination, "settings.json"), io);
-  if (settings !== undefined && (!object(settings) || (settings.packages !== undefined && !Array.isArray(settings.packages)))) {
-    throw new Error("invalid Pi settings");
-  }
-  const packages = settings?.packages ?? [];
-  let complete = true, changed = false, constrained = false;
-  const help = run("pi", ["update", "--help"]);
-  const targeted = help.ok && /--extension\s+<source>/.test(help.stdout) && /--no-approve\b/.test(help.stdout);
-  let installHelp;
-  for (const spec of ["npm:pi-mcp-adapter", "npm:@chorus-aidlc/chorus-pi"]) {
-    const sources = packages.map((entry) => {
-      const source = typeof entry === "string" ? entry : entry?.source;
-      return source;
-    }).filter((source) => source === spec || (typeof source === "string" && source.startsWith(`${spec}@`)));
-    const present = sources.length > 0;
-    // Pi updates by identity but retains configured constraints. Pinned versions
-    // are a successful no-op; ranges/tags can also exclude the latest release.
-    // Preserve those settings and report incomplete rather than silently unpin.
-    if (sources.some((source) => source !== spec && source !== `${spec}@latest`)) {
-      complete = false;
-      constrained = true;
-      continue;
-    }
-    if (present && !targeted) { complete = false; continue; }
-    if (!present) {
-      installHelp ??= run("pi", ["install", "--help"]);
-      if (!installHelp.ok || !/--no-approve\b/.test(installHelp.stdout)) { complete = false; continue; }
-    }
-    const r = run("pi", present ? ["update", "--extension", spec, "--no-approve"] : ["install", spec, "--no-approve"]);
-    changed = true; // A failed command can still leave a partial change.
-    if (!r.ok) complete = false;
-  }
-  return {
-    complete, changed,
-    detail: complete ? "Refreshed Chorus and pi-mcp-adapter only."
-      : constrained ? "Pi refresh incomplete: configured package version constraints were preserved; remove those constraints to permit latest updates. Other eligible components were attempted."
-        : "Pi refresh incomplete: targeted update/install unsupported or failed; no all-extension update was run.",
-  };
+export function upgradePi(target, { run, fs: io = fs, cwd = process.cwd() }) {
+  const env = { ...target.env, PI_CODING_AGENT_DIR: target.destination };
+  const backend = probePiBackend({ run, env });
+  const scopes = inspectPiSettings({ env, cwd, readJson: (path) => readJson(path, io) });
+  return managePiPackages({ backend, scopes, run, env, update: true });
 }
 
 export async function upgradePlugins(deps = {}) {
@@ -160,14 +125,14 @@ export async function upgradePlugins(deps = {}) {
     try {
       // Package commands must not discover project-local plugin configuration.
       scratch = io.mkdtempSync(join(tmpdir(), "chorus-upgrade-"));
-      const run = (cmd, args) => {
-        if (!args.includes("--help")) changed = true;
-        const result = (deps.run ?? runUpgradeCommand)(cmd, args, { env: target.env, platform, cwd: scratch, timeoutMs: 120_000 });
+      const run = (cmd, args, options = {}) => {
+        if (!args.includes("--help") && !args.includes("--version")) changed = true;
+        const result = (deps.run ?? runUpgradeCommand)(cmd, args, { env: target.env, platform, cwd: scratch, timeoutMs: options.timeoutMs ?? 120_000 });
         if (!result.ok) failures.push(`${cmd} ${args.slice(0, 2).join(" ")}: ${upgradeFailure(result, { env: target.env })}`);
         return result;
       };
       if (target.type === "pi") {
-        const result = upgradePi(target, { run, fs: io });
+        const result = upgradePi(target, { run, fs: io, cwd: deps.cwd });
         results.push({ target: label, ...result, detail: safe([result.detail, ...failures].join("\n")) });
         continue;
       }