@chorus-aidlc/chorus 0.16.4 → 0.17.0

package/cli/init/adapters.mjs

@@ -0,0 +1,137 @@
+// cli/init/adapters.mjs
+// The per-agent adapters `chorus init` configures. One descriptor per supported
+// coding-agent harness; buildAdapter() turns each into an AgentAdapter
+// (contracts.mjs). Detection is shared (cli/init/detect.mjs); the plugin-install
+// mechanism (descriptor.install) is added by the plugin-install task — until
+// then installPlugin reports "unsupported" rather than guessing a command.
+//
+// LAYOUT PROVENANCE (binary + config dir), so future edits don't drift into
+// LLM-guessed paths (verified against each agent's real CLI / install-*.sh):
+//   - claude   : bin `claude`;   dir ~/.claude              (this machine + docs/CONNECT_CLAUDE_CODE.md)
+//   - codex    : bin `codex`;    dir ~/.codex               (public/install-codex.sh: CODEX_HOME=$HOME/.codex)
+//   - kiro     : bin `kiro`;     dir ~/.kiro                (public/install-kiro.sh: ~/.kiro global)
+//   - opencode : bin `opencode`; dir ~/.config/opencode     (public/install-opencode.sh: OPENCODE_CONFIG_DIR)
+//   - openclaw : bin `openclaw`; dir ~/.openclaw|~/.config/openclaw  (NOT independently verified — probe both; see NOTE)
+//   - pi       : bin `pi`;       dir ~/.pi|~/.config/pi       (NOT independently verified — probe both; see NOTE)
+//   - dsh      : bin `dsh`;      dir $DSH_HOME|~/.dsh         ($DSH_HOME per dsh integration; see NOTE)
+//
+// NOTE: openclaw / pi / dsh config-dir specifics were not verifiable on this
+// build host (their CLIs/config were not all present); the descriptors probe the
+// most likely locations. A wrong config-dir guess only weakens the *config-dir*
+// half of the dual signal (the binary-on-PATH half still detects them) and never
+// blocks selection — undetected agents remain selectable. The plugin-install
+// task must still verify each install command against the real CLI.
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { detectSignals } from "./detect.mjs";
+import { OUTCOME_ACTIONS } from "./contracts.mjs";
+import { CHORUS_PLUGIN_ID, CHORUS_MARKETPLACE_NAME, CHORUS_MARKETPLACE_SOURCE } from "./chorus-plugin-consts.mjs";
+import {
+  installClaude,
+  installCodex,
+  installOpencode,
+  installDsh,
+  installOpenclaw,
+  installKiro,
+  readCodexInstallState,
+  readOpencodeInstallState,
+  readDshInstallState,
+  readOpenclawInstallState,
+  readKiroInstallState,
+  guided,
+  GUIDED_MESSAGES,
+} from "./install-methods.mjs";
+
+// Re-export the shared marketplace identifiers from their canonical home so
+// existing importers of these names from adapters.mjs keep working.
+export { CHORUS_PLUGIN_ID, CHORUS_MARKETPLACE_NAME, CHORUS_MARKETPLACE_SOURCE };
+
+/** Read + JSON-parse a file, or null on any error. Never throws. */
+function readJsonSafe(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Claude Code install-state reader (verified against CC 2.1.235 on-disk layout):
+ * `~/.claude/plugins/installed_plugins.json` (v2 keyed by `<plugin>@<marketplace>`)
+ * and `known_marketplaces.json`. Read-only — never hand-writes these files.
+ * @param {{ home?: string, readJson?: (p: string) => any }} [deps]
+ * @returns {{ marketplaceRegistered: boolean, pluginInstalled: boolean, version?: string }}
+ */
+export function readClaudeInstallState({ home = homedir(), readJson = readJsonSafe } = {}) {
+  const pluginsDir = join(home, ".claude", "plugins");
+  const installed = readJson(join(pluginsDir, "installed_plugins.json"));
+  const markets = readJson(join(pluginsDir, "known_marketplaces.json"));
+
+  const marketplaceRegistered = !!(markets && typeof markets === "object" && markets[CHORUS_MARKETPLACE_NAME]);
+
+  let pluginInstalled = false;
+  let version;
+  const entries = installed && typeof installed === "object" ? installed.plugins?.[CHORUS_PLUGIN_ID] : null;
+  if (Array.isArray(entries) && entries.length > 0) {
+    pluginInstalled = true;
+    version = entries[0]?.version;
+  }
+  return { marketplaceRegistered, pluginInstalled, version };
+}
+
+/**
+ * The supported-agent descriptors. `install` / `readState` are optional hooks the
+ * plugin-install task fills in per agent; absent ⇒ generic behavior.
+ * @type {Array<{
+ *   id: string, displayName: string, binaries: string[], configDirs: string[],
+ *   readState?: (deps: object) => object, install?: (ctx: object) => object,
+ * }>}
+ */
+export const AGENT_DESCRIPTORS = [
+  { id: "claude", displayName: "Claude Code", binaries: ["claude"], configDirs: ["~/.claude"], readState: readClaudeInstallState, install: installClaude },
+  { id: "codex", displayName: "Codex CLI", binaries: ["codex"], configDirs: ["~/.codex"], readState: readCodexInstallState, install: installCodex },
+  { 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: "dsh", displayName: "DeepSeek Harness (dsh)", binaries: ["dsh"], configDirs: ["$DSH_HOME", "~/.dsh"], readState: readDshInstallState, install: installDsh },
+];
+
+/**
+ * Build an AgentAdapter from a descriptor.
+ * @param {typeof AGENT_DESCRIPTORS[number]} d
+ * @returns {import("./contracts.mjs").AgentAdapter}
+ */
+export function buildAdapter(d) {
+  return {
+    id: d.id,
+    displayName: d.displayName,
+    detect: (env = process.env) => detectSignals(d, { env }),
+    readInstallState: (deps = {}) => {
+      const base = typeof d.readState === "function"
+        ? d.readState(deps)
+        : { marketplaceRegistered: false, pluginInstalled: false };
+      // `supported` = a REAL automated install path exists for this agent. A
+      // `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.
+      return { supported: typeof d.install === "function" && d.install.guided !== true, ...base };
+    },
+    installPlugin: (ctx = {}) =>
+      typeof d.install === "function"
+        ? d.install(ctx)
+        : {
+            stepId: "plugin-install",
+            agentId: d.id,
+            action: OUTCOME_ACTIONS.UNSUPPORTED,
+            detail: `no automated plugin install for ${d.displayName} yet — configure manually`,
+          },
+  };
+}
+
+/** All supported adapters, built from the descriptors. */
+export const ADAPTERS = AGENT_DESCRIPTORS.map(buildAdapter);

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

@@ -0,0 +1,60 @@
+// cli/init/agent-type-map.mjs
+// The single translation between a `chorus init` adapter selection id (see
+// cli/init/adapters.mjs — "claude" | "codex" | "kiro" | "opencode" | "openclaw" |
+// "pi" | "dsh") and the daemon's agentType vocabulary (cli/daemon-agent.mjs
+// KNOWN_AGENTS). It lives in ONE place so the credential-seed step (which writes
+// each selected agent's daemon.json agents[] entry) and the daemon-setup step
+// (which gates auto-start on whether any selected agent is wakeable) can never
+// disagree about how a selection maps to a backend.
+//
+// Two rules the callers rely on:
+//   1. The init id "claude" is NOT the daemon agentType — it renames to
+//      "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)
+//      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").
+//
+// Fail-closed by default: an unknown / unmapped id maps to "offline" rather than a
+// wakeable backend, so a future adapter added without a mapping is never silently
+// woken as claude-code.
+
+/**
+ * Selection id → daemon agentType. Only claude/codex/kiro 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>>}
+ */
+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",
+  opencode: "offline",
+  openclaw: "offline",
+  pi: "offline",
+  dsh: "offline",
+});
+
+/**
+ * Map a `chorus init` selection id to the daemon agentType written into
+ * 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")
+ */
+export function agentTypeForSelection(selectionId) {
+  return SELECTION_TO_AGENT_TYPE[selectionId] ?? "offline";
+}
+
+/**
+ * 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.
+ * @param {string} agentType
+ * @returns {boolean}
+ */
+export function isWakeableAgentType(agentType) {
+  return agentType !== "offline";
+}

package/cli/init/chorus-plugin-consts.mjs

@@ -0,0 +1,16 @@
+// cli/init/chorus-plugin-consts.mjs
+// Canonical Chorus plugin/marketplace identifiers, shared by the adapters and the
+// per-agent install methods. Kept in its own module so adapters.mjs and
+// install-methods.mjs can both import them without a circular dependency.
+
+/** Plugin selector used by marketplace-based agents (Claude Code, Codex). */
+export const CHORUS_PLUGIN_ID = "chorus@chorus-plugins";
+/** Marketplace name as it appears in agents' on-disk state. */
+export const CHORUS_MARKETPLACE_NAME = "chorus-plugins";
+/**
+ * Remote marketplace source (owner decision: each agent's NATIVE REMOTE
+ * marketplace, not a local bundle). Overridable per invocation via
+ * CHORUS_MARKETPLACE_SOURCE. Accepted by `claude plugin marketplace add`
+ * (URL/path/repo). Codex prefers the `owner/repo` slug — see installCodex.
+ */
+export const CHORUS_MARKETPLACE_SOURCE = "https://github.com/Chorus-AIDLC/Chorus";

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

@@ -0,0 +1,183 @@
+// cli/init/codex-mcp-config.mjs
+// Writes the Chorus native-MCP server block into ~/.codex/config.toml using a KEYLESS
+// env-var reference — `bearer_token_env_var = "CHORUS_API_KEY"` — instead of a literal
+// `Authorization: Bearer <key>`. Codex loads ~/.codex/.env into its process env at arg0
+// startup and resolves that env var into `Authorization: Bearer <key>` at connect time
+// (config/src/mcp_types.rs StreamableHttp.bearer_token_env_var; codex-mcp resolve_bearer_token),
+// so the API key lives in exactly ONE place (~/.codex/.env). A daemon-woken Codex — whose
+// spawner exports CHORUS_API_KEY into the child env — then also authenticates to native MCP,
+// closing the gap a literal Bearer left (cli/codex-spawner.mjs:16-22).
+//
+// `codex plugin add` does NOT write [mcp_servers.chorus] (its marketplace `authentication:
+// ON_INSTALL` is metadata only — verified codex-cli 0.150.1), so `chorus agents add` writes it
+// here, AFTER the plugin install (authoritative, no race).
+//
+// TARGETED TEXTUAL upsert — no TOML-parser dependency (the repo stays pure-JS / cross-platform),
+// preserving every other section, key, and comment verbatim. The secret is NEVER written here
+// (bearer_token_env_var is a variable NAME, not the key).
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const BEARER_ENV_VAR = "CHORUS_API_KEY";
+
+/** A non-empty trimmed string, or undefined. */
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Resolve the Codex `~/.codex/config.toml` path. Honors `CODEX_HOME`, then `HOME` (so tests
+ * can inject a temp home), else the OS home dir — matching cli/codex-spawner.mjs +
+ * install-methods.mjs.
+ * @param {Record<string, string | undefined>} env
+ */
+export function resolveCodexConfigPath(env) {
+  const base = nonEmpty(env.CODEX_HOME) ?? join(nonEmpty(env.HOME) ?? homedir(), ".codex");
+  return join(base, "config.toml");
+}
+
+/**
+ * Normalize a Chorus base URL to the MCP endpoint the same way the hook wrapper
+ * (chorus-mcp-call.sh) does: 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 codexMcpUrl(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`;
+}
+
+// TOML basic-string value: escape backslash then double-quote. URLs don't contain these, but
+// escape defensively so we never emit invalid TOML.
+const toToml = (v) => `"${String(v).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+
+/**
+ * Upsert `[mcp_servers.chorus]` in `~/.codex/config.toml` to
+ *   url = "<mcp-endpoint>"
+ *   bearer_token_env_var = "CHORUS_API_KEY"
+ * and MIGRATE away any legacy literal auth: a `bearer_token = "..."` line is dropped, and a
+ * `[mcp_servers.chorus.http_headers]` `Authorization = "..."` line is removed (dropping the
+ * whole http_headers subtable when it becomes empty, preserving any OTHER header). Every other
+ * section/key/comment in the file is preserved verbatim.
+ *
+ * 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 NAME.
+ * @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 config.toml path written
+ */
+export function writeCodexMcpServer({ 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 = codexMcpUrl(url);
+  if (!mcpUrl) throw new Error("writeCodexMcpServer requires a url");
+
+  let existing = "";
+  try {
+    existing = read(configPath);
+  } catch {
+    existing = ""; // no file yet — start fresh
+  }
+
+  const lines = existing.length ? existing.split(/\r?\n/) : [];
+  if (lines.length && lines[lines.length - 1] === "") lines.pop();
+
+  const isHeader = (s) => /^\s*\[/.test(s);
+  const chorusHeaderRe = /^\s*\[mcp_servers\.chorus\]\s*$/;
+  const headersHeaderRe = /^\s*\[mcp_servers\.chorus\.http_headers\]\s*$/;
+  // A `key = value` line (not a comment or blank) — used to tell whether a subtable still has
+  // content after removing Authorization.
+  const isKvLine = (s) => /^\s*[^#\s][^=]*=/.test(s);
+
+  // Split into groups: a preamble (before the first table header) + one group per table header.
+  const groups = [];
+  let cur = { header: null, body: [] };
+  for (const line of lines) {
+    if (isHeader(line)) {
+      groups.push(cur);
+      cur = { header: line, body: [] };
+    } else {
+      cur.body.push(line);
+    }
+  }
+  groups.push(cur);
+
+  const outGroups = [];
+  let wroteChorus = false;
+  for (const g of groups) {
+    if (g.header === null) {
+      outGroups.push(...g.body); // preamble verbatim
+      continue;
+    }
+    if (chorusHeaderRe.test(g.header)) {
+      // Normalize the [mcp_servers.chorus] body: set url + bearer_token_env_var in place,
+      // drop any literal bearer_token, preserve every other key.
+      let seenUrl = false;
+      let seenBearerEnv = false;
+      const body = [];
+      for (const l of g.body) {
+        if (/^\s*url\s*=/.test(l)) {
+          body.push(`url = ${toToml(mcpUrl)}`);
+          seenUrl = true;
+          continue;
+        }
+        if (/^\s*bearer_token_env_var\s*=/.test(l)) {
+          body.push(`bearer_token_env_var = ${toToml(BEARER_ENV_VAR)}`);
+          seenBearerEnv = true;
+          continue;
+        }
+        if (/^\s*bearer_token\s*=/.test(l)) continue; // drop legacy literal bearer_token
+        body.push(l);
+      }
+      const head = [];
+      if (!seenUrl) head.push(`url = ${toToml(mcpUrl)}`);
+      if (!seenBearerEnv) head.push(`bearer_token_env_var = ${toToml(BEARER_ENV_VAR)}`);
+      outGroups.push(g.header, ...head, ...body);
+      wroteChorus = true;
+      continue;
+    }
+    if (headersHeaderRe.test(g.header)) {
+      // Strip the literal Authorization; drop the whole subtable if nothing else remains.
+      const body = g.body.filter((l) => !/^\s*Authorization\s*=/i.test(l));
+      if (body.some(isKvLine)) {
+        outGroups.push(g.header, ...body);
+      }
+      // else: drop the emptied subtable entirely
+      continue;
+    }
+    outGroups.push(g.header, ...g.body);
+  }
+
+  if (!wroteChorus) {
+    if (outGroups.length && outGroups[outGroups.length - 1] !== "") outGroups.push("");
+    outGroups.push(
+      "[mcp_servers.chorus]",
+      `url = ${toToml(mcpUrl)}`,
+      `bearer_token_env_var = ${toToml(BEARER_ENV_VAR)}`,
+    );
+  }
+
+  // Trim trailing blank lines so idempotent re-runs never accumulate them.
+  while (outGroups.length && outGroups[outGroups.length - 1] === "") outGroups.pop();
+  const content = outGroups.join("\n") + "\n";
+
+  mkdir(dirname(configPath), { recursive: true });
+  const tmp = `${configPath}.tmp`;
+  write(tmp, content, { mode: 0o600 });
+  rename(tmp, configPath);
+  return configPath;
+}

package/cli/init/contracts.mjs

@@ -0,0 +1,120 @@
+// cli/init/contracts.mjs
+// Shared contracts for `chorus init` (idea c055e285, A1 foundation). Two
+// extension points let sibling ideas grow the command without editing its core:
+//
+//   1. AgentAdapter — one per coding-agent harness (Claude Code, Codex, Kiro,
+//      opencode, OpenClaw, Pi, dsh). Adding an agent = adding an adapter to the
+//      registry (cli/init/registry.mjs). Detection, install-state read, and the
+//      plugin install all live behind this interface.
+//
+//   2. InitStep — one per configuration concern. THIS change ships the
+//      credential-seed step (scope "once") and the plugin-install step (scope
+//      "per-agent"). Sibling ideas register more steps (MCP proxy cc115e6b,
+//      daemon setup a7c2a3e8) into the same ordered registry.
+//
+// Iteration ownership (resolves proposal-review note #3): the ORCHESTRATOR
+// (runInit) owns per-agent iteration. A `per-agent` step's run(ctx) is invoked
+// once per selected agent with ctx.agentId set; a `once` step's run(ctx) is
+// invoked a single time with ctx.agentId undefined. Steps never loop the
+// selection themselves.
+//
+// Plain ESM, zero dependencies — ships verbatim in the npm package. This module
+// is intentionally (mostly) JSDoc typedefs plus a few frozen enums so the shape
+// is one source of truth for the whole cli/init tree and its tests.
+
+/**
+ * Step scopes. `once` runs a single time per `chorus init` invocation;
+ * `per-agent` runs once for each selected agent.
+ * @readonly
+ */
+export const STEP_SCOPES = Object.freeze({ ONCE: "once", PER_AGENT: "per-agent" });
+
+/**
+ * Terminal per-unit outcomes a step reports for the summary table.
+ * - installed: a fresh configuration was applied
+ * - repaired:  an existing but incomplete/broken configuration was fixed
+ * - skipped:   already configured / nothing to do
+ * - seeded:    a `once` step persisted shared state (e.g. credentials)
+ * - failed:    the unit could not be configured (detail carries the reason)
+ * - unsupported: the agent has no verified automated mechanism (guided message)
+ * @readonly
+ */
+export const OUTCOME_ACTIONS = Object.freeze({
+  INSTALLED: "installed",
+  REPAIRED: "repaired",
+  SKIPPED: "skipped",
+  SEEDED: "seeded",
+  FAILED: "failed",
+  UNSUPPORTED: "unsupported",
+});
+
+/** Outcome actions that mean "this unit did not succeed" — drive the exit code. */
+export const FAILURE_ACTIONS = Object.freeze([OUTCOME_ACTIONS.FAILED]);
+
+/**
+ * @typedef {Object} AgentDetection
+ * @property {string} id            Stable adapter id (e.g. "claude").
+ * @property {string} displayName   Human label (e.g. "Claude Code").
+ * @property {boolean} binaryOnPath Whether the agent's CLI resolves on PATH.
+ * @property {boolean} configDirPresent Whether the agent's config dir exists.
+ * @property {boolean} detected     `binaryOnPath || configDirPresent` — drives
+ *                                  default pre-selection only, never gates choice.
+ */
+
+/**
+ * @typedef {Object} AgentInstallState
+ * @property {boolean} supported    Whether an automated install is available on
+ *                                  this machine (false ⇒ guided message only).
+ * @property {boolean} marketplaceRegistered Whether the Chorus marketplace/source
+ *                                  is already registered for this agent.
+ * @property {boolean} pluginInstalled Whether the Chorus plugin is already installed.
+ * @property {string} [version]     Installed plugin version, when known.
+ * @property {string} [detail]      Optional human note (e.g. why unsupported).
+ */
+
+/**
+ * @typedef {Object} AgentAdapter
+ * @property {string} id
+ * @property {string} displayName
+ * @property {(env: NodeJS.ProcessEnv) => {binaryOnPath: boolean, configDirPresent: boolean}} detect
+ *   Pure-ish: may stat the filesystem and look up PATH; MUST NOT mutate anything.
+ * @property {(deps: object) => AgentInstallState} readInstallState
+ *   Read-only idempotency probe (e.g. parse the agent's own state files).
+ * @property {(ctx: StepContext) => StepOutcome} installPlugin
+ *   Register the agent's native remote marketplace and install/enable the Chorus
+ *   plugin surface. MUST be idempotent, MUST back up before overwrite via
+ *   ctx.backup(), and MUST NOT write any per-agent MCP/credential config.
+ */
+
+/**
+ * @typedef {Object} InitStep
+ * @property {string} id            Stable step id (e.g. "credential-seed").
+ * @property {number} order         Ascending run order.
+ * @property {("once"|"per-agent")} scope
+ * @property {(ctx: StepContext) => (StepOutcome | Promise<StepOutcome>)} run
+ */
+
+/**
+ * @typedef {Object} StepOutcome
+ * @property {string} stepId
+ * @property {string} [agentId]     Present for per-agent outcomes.
+ * @property {("installed"|"repaired"|"skipped"|"seeded"|"failed"|"unsupported")} action
+ * @property {string} detail        One-line human explanation for the summary.
+ */
+
+/**
+ * @typedef {Object} StepContext
+ * @property {string[]} selection   Selected agent ids (for `once` steps that need the set).
+ * @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).
+ * @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.
+ * @property {NodeJS.ProcessEnv} env
+ */
+
+/** True when an outcome represents a failure (drives the process exit code). */
+export function isFailureOutcome(outcome) {
+  return !!outcome && FAILURE_ACTIONS.includes(outcome.action);
+}

package/cli/init/detect.mjs

@@ -0,0 +1,97 @@
+// cli/init/detect.mjs
+// Cross-platform detection primitives for `chorus init` adapters. Dual signal:
+// a CLI binary resolvable on PATH, and/or an agent config directory present.
+// All IO (env, filesystem, platform, home) is injectable so adapters unit-test
+// without a real machine. Zero runtime dependencies beyond node core.
+
+import { existsSync as fsExistsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, delimiter as pathDelimiter } from "node:path";
+
+/**
+ * Expand a config-dir spec into an absolute path:
+ *   - a leading `~` → the home directory,
+ *   - a leading `$VAR` segment → env[VAR] (whole spec dropped if unset),
+ * Returns null when the spec cannot be resolved (e.g. `$DSH_HOME` unset).
+ * @param {string} spec
+ * @param {{ env?: Record<string,string|undefined>, home?: string }} [deps]
+ * @returns {string | null}
+ */
+export function expandPath(spec, { env = process.env, home = homedir() } = {}) {
+  if (typeof spec !== "string" || !spec) return null;
+  if (spec.startsWith("~")) {
+    return join(home, spec.slice(1).replace(/^[/\\]/, ""));
+  }
+  if (spec.startsWith("$")) {
+    const slash = spec.search(/[/\\]/);
+    const varName = (slash === -1 ? spec.slice(1) : spec.slice(1, slash));
+    const value = env[varName];
+    if (!value) return null; // unset env var → this candidate does not apply
+    const rest = slash === -1 ? "" : spec.slice(slash + 1);
+    return rest ? join(value, rest) : value;
+  }
+  return spec;
+}
+
+/**
+ * True if any of `names` resolves to an executable on PATH. Scans PATH entries
+ * and (on Windows) the PATHEXT extension list. Pure lookup — never executes.
+ * @param {string[]} names  candidate binary base names (e.g. ["claude"])
+ * @param {{
+ *   env?: Record<string,string|undefined>,
+ *   existsSync?: (p: string) => boolean,
+ *   platform?: NodeJS.Platform,
+ * }} [deps]
+ * @returns {boolean}
+ */
+export function binaryOnPath(names, { env = process.env, existsSync = fsExistsSync, platform = process.platform } = {}) {
+  const rawPath = env.PATH ?? env.Path ?? "";
+  if (!rawPath) return false;
+  const sep = platform === "win32" ? ";" : pathDelimiter;
+  const dirs = rawPath.split(sep).filter(Boolean);
+  const exts =
+    platform === "win32"
+      ? ["", ...String(env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean)]
+      : [""];
+  for (const name of names) {
+    if (!name) continue;
+    for (const dir of dirs) {
+      for (const ext of exts) {
+        // Windows filesystems are case-insensitive; try the ext as-given.
+        if (existsSync(join(dir, name + ext))) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * True if any of the config-dir specs (after expandPath) exists on disk.
+ * @param {string[]} specs
+ * @param {{
+ *   env?: Record<string,string|undefined>,
+ *   existsSync?: (p: string) => boolean,
+ *   home?: string,
+ * }} [deps]
+ * @returns {boolean}
+ */
+export function configDirPresent(specs, { env = process.env, existsSync = fsExistsSync, home = homedir() } = {}) {
+  for (const spec of specs || []) {
+    const resolved = expandPath(spec, { env, home });
+    if (resolved && existsSync(resolved)) return true;
+  }
+  return false;
+}
+
+/**
+ * Compute the dual-signal detection for one agent descriptor.
+ * @param {{ binaries: string[], configDirs: string[] }} descriptor
+ * @param {object} [deps]  forwarded to binaryOnPath / configDirPresent
+ * @returns {{ binaryOnPath: boolean, configDirPresent: boolean }}
+ */
+export function detectSignals(descriptor, deps = {}) {
+  return {
+    binaryOnPath: binaryOnPath(descriptor.binaries || [], deps),
+    configDirPresent: configDirPresent(descriptor.configDirs || [], deps),
+  };
+}