@chorus-aidlc/chorus 0.16.4 → 0.17.1

package/cli/init/steps/daemon-setup.mjs

@@ -0,0 +1,246 @@
+// cli/init/steps/daemon-setup.mjs
+// The `once`-scoped daemon-setup step for `chorus init` (idea a7c2a3e8). It is the
+// reserved sibling slot in the step registry (see registry.mjs / contracts.mjs):
+// after credentials are seeded (order 10) and each agent's plugin is installed
+// (order 20), this step (order 30) configures the local Chorus daemon and, opt-in,
+// installs it as a boot-autostart service.
+//
+// Owner decisions (elaboration Round 1):
+//   - full_preflight    : reuse `daemon install`'s cwds + backend preflight so the
+//                         installed service is usable out of the box.
+//   - connection_only   : the credential model is Chorus URL + API key only — this
+//                         step collects NO provider secrets (AWS_/ANTHROPIC_/…).
+//   - default_off        : the interactive prompt defaults to No (opt-in).
+//   - explicit_flag      : a non-interactive run (non-TTY OR --yes) installs the
+//                         boot service ONLY when --daemon-autostart is passed.
+//   - linux_and_mac      : auto-start is real on Linux (systemd) and macOS (launchd);
+//                         unsupported platforms write daemon.json + print manual steps.
+//   - boot_and_now       : accepting installs AND enables the service (start now +
+//                         at every boot) via the shared installService.
+//   - report_skip_repair : a re-run where the service is already installed reports
+//                         "already configured" and does not rewrite.
+//
+// All collaborators are injected (matching credential-seed.mjs) so the step
+// unit-tests with fakes; production uses the real daemon-service / install-config
+// modules, and an integration test can drive REAL installService against a fake io.
+
+import { readFileSync } from "node:fs";
+import { STEP_SCOPES, OUTCOME_ACTIONS } from "../contracts.mjs";
+import { loginFilePath } from "../../credentials.mjs";
+import {
+  autostartCapability as defaultAutostartCapability,
+  detectSupervisor as defaultDetectSupervisor,
+  installService as defaultInstallService,
+  resolveServicePaths as defaultResolveServicePaths,
+} from "../../daemon-service.mjs";
+import {
+  resolveInstallCredentials as defaultResolveInstallCredentials,
+  resolveInstallCwds as defaultResolveInstallCwds,
+  resolveInstallAgent as defaultResolveInstallAgent,
+} from "../../daemon-install-config.mjs";
+import { isWakeableAgentType } from "../agent-type-map.mjs";
+
+const STEP_ID = "daemon-setup";
+const { INSTALLED, SKIPPED, FAILED } = OUTCOME_ACTIONS;
+const out = (action, detail) => ({ stepId: STEP_ID, action, detail });
+
+
+/**
+ * The daemon-setup step body.
+ * @param {import("../contracts.mjs").StepContext & {
+ *   autostartCapability?: Function, detectSupervisor?: Function,
+ *   installService?: Function, resolveServicePaths?: Function, serviceIo?: object,
+ *   resolveInstallCredentials?: Function, resolveInstallCwds?: Function,
+ *   resolveInstallAgent?: Function,
+ *   writeConfig?: Function, readJson?: Function, loginPath?: string,
+ *   resolve?: Function, validate?: Function, processCwd?: string,
+ * }} ctx
+ * @returns {Promise<import("../contracts.mjs").StepOutcome>}
+ */
+export async function setupDaemon(ctx) {
+  const env = ctx.env ?? process.env;
+  const io = ctx.io ?? {};
+  const isTTY = !!io.isTTY;
+  const flags = ctx.flags ?? {};
+  const log = typeof io.log === "function" ? io.log : () => {};
+
+  // Injectable collaborators (real defaults in production).
+  const capabilityOf = ctx.autostartCapability ?? defaultAutostartCapability;
+  const detect = ctx.detectSupervisor ?? defaultDetectSupervisor;
+  const install = ctx.installService ?? defaultInstallService;
+  const servicePaths = ctx.resolveServicePaths ?? defaultResolveServicePaths;
+  const serviceIo = ctx.serviceIo; // undefined ⇒ daemon-service uses its real defaultIO
+  const resolveCreds = ctx.resolveInstallCredentials ?? defaultResolveInstallCredentials;
+  const resolveCwds = ctx.resolveInstallCwds ?? defaultResolveInstallCwds;
+  const resolveAgent = ctx.resolveInstallAgent ?? defaultResolveInstallAgent;
+
+  // "Non-interactive" for the auto-start decision = non-TTY OR --yes (a --yes run in
+  // a TTY must never block on the prompt), matching `daemon install --yes`.
+  const nonInteractive = !isTTY || flags.yes === true;
+  const skip = nonInteractive; // suppress the resolvers' prompts in non-interactive mode
+
+  // Shared opts threaded into the reused preflight resolvers. undefined deps fall
+  // through to the resolvers' real defaults (updateDaemonConfig / readJsonSafe / …).
+  const preflightOpts = {
+    isTTY,
+    skip,
+    writeConfig: ctx.writeConfig,
+    readJson: ctx.readJson,
+    loginPath: ctx.loginPath,
+    prompt: io.ask,
+    log,
+  };
+
+  // Reuse the init step-1 selection (idea broaden-init-plugin-install): map each
+  // selected adapter id to its daemon agentType and record whether ANY is a
+  // daemon-wakeable backend. Each selected agent's own agents[] entry (with its
+  // agentType) was already written by the credential-seed step; here we only need
+  // the daemon-level default backend + the wakeability gate below. With NO
+  // selection (e.g. this step reused outside `chorus init`), the original
+  // prompt-driven behavior is preserved.
+  const selection = Array.isArray(ctx.selection)
+    ? ctx.selection.filter((id) => typeof id === "string" && id.trim())
+    : [];
+  const hasSelection = selection.length > 0;
+
+  // Will the daemon actually wake anything? credential-seed (order 10) just wrote each
+  // selected agent's `daemonWake` into daemon.json `agents[]` (a TTY opt-in lives there,
+  // NOT in flags), so read that file rather than re-derive from the selection/flags. An
+  // agent will be woken iff its backend is wakeable AND daemonWake is not false. offline
+  // OR daemonWake:false ⇒ not woken.
+  const readJson =
+    ctx.readJson ??
+    ((p) => {
+      try {
+        return JSON.parse(readFileSync(p, "utf8"));
+      } catch {
+        return null;
+      }
+    });
+  const cfgFile = readJson(ctx.loginPath ?? loginFilePath());
+  const configuredAgents =
+    cfgFile && Array.isArray(cfgFile.agents) ? cfgFile.agents.filter((a) => a && typeof a === "object") : [];
+  const willWake = configuredAgents.some(
+    (a) => isWakeableAgentType(a.agentType) && a.daemonWake !== false,
+  );
+
+  // 1. Preflight. With an init SELECTION, credential-seed (order 10) already wrote
+  //    each selected agent into daemon.json `agents[]` with its OWN cwds + agentType
+  //    — the authoritative per-agent config. The flat top-level `cwds`/`agent` are a
+  //    DEPRECATED single-agent leftover (persisting them here leaked a duplicate agent
+  //    config OUTSIDE the array), so we do NOT write them for a selection. Without a
+  //    selection (this step reused outside `chorus init`) we keep the original
+  //    single-agent preflight: persist top-level cwds + the resolved/prompted backend.
+  //    Connection-only either way: no provider secrets.
+  try {
+    if (!hasSelection) {
+      await resolveCwds(flags, preflightOpts);
+      await resolveAgent(flags, env, { ...preflightOpts, errLog: log });
+    }
+  } catch (err) {
+    return out(FAILED, `daemon preflight failed: ${err?.message ?? String(err)}`);
+  }
+
+  // 1b. Capability gate: if NO configured agent will be woken (every one is offline, or
+  //     a wakeable backend the operator left opted-out with daemonWake:false), the daemon
+  //     has nothing to wake. Their agents[] entries are already persisted (credential-seed)
+  //     for the `chorus mcp` proxy; skip the auto-start prompt AND the service install.
+  if (hasSelection && !willWake) {
+    log("[chorus agents add] no agent is enabled for daemon waking — the daemon would wake no local backend.");
+    log("[chorus agents add] agents' keys are configured in ~/.chorus/daemon.json for `chorus mcp`.");
+    return out(SKIPPED, "no agent enabled for daemon waking — agents[] persisted; boot service not installed");
+  }
+
+  const manual = () => {
+    log("[chorus agents add] daemon config written to ~/.chorus/daemon.json.");
+    log("[chorus agents add] start the daemon yourself: `chorus daemon` (foreground) or `chorus daemon -d` (background).");
+  };
+
+  // 2. Capability gate (decision: linux_and_mac). Only offer auto-start where a real
+  //    boot service exists; unsupported platforms write the config + print manual steps.
+  const capability = capabilityOf(serviceIo);
+  if (capability === "unsupported") {
+    const platformLabel = serviceIo?.platform ?? process.platform;
+    manual();
+    return out(SKIPPED, `daemon.json written; auto-start unsupported on ${platformLabel} — start with 'chorus daemon'`);
+  }
+
+  // 3. Decide whether to install (decision: default_off / explicit_flag).
+  if (nonInteractive) {
+    if (flags.daemonAutostart !== true) {
+      manual();
+      return out(SKIPPED, "daemon.json written; pass --daemon-autostart to install the boot service");
+    }
+  } else {
+    const answer = typeof io.ask === "function"
+      ? String((await io.ask("Install & enable the Chorus daemon to auto-start on boot? [y/N]: ")) ?? "").trim()
+      : "";
+    if (!/^y(es)?$/i.test(answer)) {
+      manual();
+      return out(SKIPPED, "declined auto-start; daemon.json written — start with 'chorus daemon'");
+    }
+  }
+
+  // 4. Idempotency short-circuit (decision: report_skip_repair) — BEFORE the
+  //    credential gate, so an already-installed healthy re-run neither re-validates
+  //    (which could fail on a transient server outage) nor rewrites the unit. A
+  //    missing/absent service falls through to install (which repairs the drift).
+  const sup = detect(serviceIo);
+  if ((sup.kind === "systemd" || sup.kind === "launchd") && sup.installed) {
+    return out(SKIPPED, `daemon already configured for auto-start (${sup.kind}) — left unchanged`);
+  }
+
+  // 5. Credential validate-or-abort gate — reached only when actually installing.
+  //    Reuse the SAME guarantee as `daemon install`: resolve → server-validate the
+  //    key → (for the legacy single-agent path) persist url+key+identity; abort
+  //    (install nothing) on failure. With an init SELECTION the per-agent creds are
+  //    already in agents[] (credential-seed) and resolveCredentials falls back to
+  //    agents[0], so we VALIDATE ONLY (no-op writeConfig) — persisting the flat
+  //    top-level url/apiKey/identity here would re-introduce the deprecated
+  //    outside-the-array agent config. This does NOT lean on credential-seed, whose
+  //    SKIPPED path performs no server validation and whose FAILED outcome does not
+  //    stop runInit.
+  let cred;
+  try {
+    cred = await resolveCreds(flags, env, {
+      isTTY,
+      skip,
+      resolve: ctx.resolve,
+      validate: ctx.validate,
+      writeConfig: hasSelection ? () => {} : ctx.writeConfig,
+      prompt: io.ask,
+      log,
+      errLog: log,
+    });
+  } catch (err) {
+    return out(FAILED, `credential preflight failed: ${err?.message ?? String(err)}`);
+  }
+  if (!cred || !cred.ok) {
+    return out(FAILED, "credentials could not be resolved/validated — no boot service installed");
+  }
+
+  // 6. Install & enable the boot service (decision: boot_and_now).
+  const cwdList = Array.isArray(flags.cwd) ? flags.cwd : typeof flags.cwd === "string" ? [flags.cwd] : [];
+  const spec = {
+    ...servicePaths(env),
+    // cwds/agent live in daemon.json (persisted above); the unit carries neither.
+    cwds: cwdList,
+    chorusOnly: flags.chorusOnly === true,
+    workingDir: ctx.processCwd ?? process.cwd(),
+  };
+  const r = install(spec, serviceIo);
+  if (r && r.installed) {
+    log("[chorus agents add] daemon installed & enabled — it will auto-start on boot.");
+    for (const s of r.steps ?? []) log(`[chorus agents add]   ${s}`);
+    return out(INSTALLED, `boot service installed (${r.platform}); manage with 'chorus daemon status|stop|restart|logs'`);
+  }
+  return out(FAILED, `service install failed: ${r?.error ?? "unknown error"}`);
+}
+
+/** @type {import("../contracts.mjs").InitStep} */
+export const daemonSetupStep = {
+  id: STEP_ID,
+  order: 30, // after credential-seed (10) and plugin-install (20)
+  scope: STEP_SCOPES.ONCE,
+  run: setupDaemon,
+};

package/cli/init/steps/plugin-install.mjs

@@ -0,0 +1,37 @@
+// cli/init/steps/plugin-install.mjs
+// The per-agent plugin-install step `chorus init` ships (idea c055e285, A1).
+// The orchestrator invokes run(ctx) once per selected agent with ctx.agentId +
+// ctx.adapter set; the step delegates to the agent's own installPlugin (whose
+// per-agent mechanics live in cli/init/install-methods.mjs). Per-agent failures
+// are isolated by returning a `failed` outcome — never throwing — so one agent
+// cannot abort the others.
+
+import { STEP_SCOPES, OUTCOME_ACTIONS } from "../contracts.mjs";
+
+/** @type {import("../contracts.mjs").InitStep} */
+export const pluginInstallStep = {
+  id: "plugin-install",
+  order: 20, // after credential-seed (order 10)
+  scope: STEP_SCOPES.PER_AGENT,
+  run(ctx) {
+    const adapter = ctx.adapter;
+    if (!adapter || typeof adapter.installPlugin !== "function") {
+      return {
+        stepId: "plugin-install",
+        agentId: ctx.agentId,
+        action: OUTCOME_ACTIONS.FAILED,
+        detail: "no adapter resolved for this agent",
+      };
+    }
+    try {
+      return adapter.installPlugin(ctx);
+    } catch (err) {
+      return {
+        stepId: "plugin-install",
+        agentId: adapter.id,
+        action: OUTCOME_ACTIONS.FAILED,
+        detail: `install threw: ${err?.message ?? String(err)}`,
+      };
+    }
+  },
+};

package/cli/init-args.mjs

@@ -0,0 +1,140 @@
+// cli/init-args.mjs
+// Argument parsing + help text for `chorus init` (idea c055e285, A1). Pure and
+// side-effect-free so it is unit-testable — chorus.mjs (which runs side effects
+// at import) imports these helpers, mirroring cli/client-args.mjs.
+//
+// Zero dependencies — ships verbatim in the npm package alongside chorus.mjs.
+
+/**
+ * Parse `chorus init` flags out of an arg list. Recognizes:
+ *   --agents <csv>   comma-separated agent ids (space + `=` forms), repeatable
+ *                    (values accumulate); e.g. `--agents claude,codex`
+ *   --all            configure every supported agent
+ *   --yes / -y       skip confirmations (implied when non-TTY)
+ *   --url <url>      Chorus URL (space + `=`) — for the credential-seed step
+ *   --api-key <k>    Chorus API key (space + `=`)
+ *   --help / -h
+ *
+ * Only keys that appear are set, so callers can distinguish "unset" from a
+ * falsy value. `agents` is normalized to a de-duped, order-preserving array of
+ * lowercased ids (empty tokens dropped); absent ⇒ `agents` is unset.
+ *
+ * @param {string[]} argv
+ * @returns {{ agents?: string[], all?: boolean, yes?: boolean, url?: string,
+ *   apiKey?: string, dshProfile?: string, daemonAutostart?: boolean,
+ *   daemonWake?: string[], daemonWakeAll?: boolean, help?: boolean }}
+ */
+export function parseInitFlags(argv) {
+  const out = {};
+  /** @type {string[]} */
+  const agentTokens = [];
+  /** @type {string[]} */
+  const daemonWakeTokens = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--agents") agentTokens.push(argv[i + 1] ?? "");
+    else if (a.startsWith("--agents=")) agentTokens.push(a.slice("--agents=".length));
+    else if (a === "--all") out.all = true;
+    else if (a === "--yes" || a === "-y") out.yes = true;
+    else if (a === "--daemon-autostart") out.daemonAutostart = true;
+    else if (a === "--daemon-wake-all") out.daemonWakeAll = true;
+    else if (a === "--daemon-wake") daemonWakeTokens.push(argv[i + 1] ?? "");
+    else if (a.startsWith("--daemon-wake=")) daemonWakeTokens.push(a.slice("--daemon-wake=".length));
+    else if (a === "--url") out.url = argv[i + 1];
+    else if (a.startsWith("--url=")) out.url = a.slice("--url=".length);
+    else if (a === "--api-key") out.apiKey = argv[i + 1];
+    else if (a.startsWith("--api-key=")) out.apiKey = a.slice("--api-key=".length);
+    else if (a === "--dsh-profile") out.dshProfile = argv[i + 1];
+    else if (a.startsWith("--dsh-profile=")) out.dshProfile = a.slice("--dsh-profile=".length);
+    else if (a === "--help" || a === "-h") out.help = true;
+  }
+  // Normalize a comma-separated, repeatable token list into a de-duped lowercased id
+  // array (shared shape for --agents and --daemon-wake).
+  const normalizeIds = (tokens) => {
+    const seen = new Set();
+    /** @type {string[]} */
+    const ids = [];
+    for (const tok of tokens) {
+      for (const raw of String(tok).split(",")) {
+        const id = raw.trim().toLowerCase();
+        if (id && !seen.has(id)) {
+          seen.add(id);
+          ids.push(id);
+        }
+      }
+    }
+    return ids;
+  };
+  if (agentTokens.length) {
+    // Even a `--agents ""`/`--agents ,` that yields nothing still marks intent to
+    // pass agents explicitly; expose the (possibly empty) array so the selector
+    // can tell "user tried to specify agents" from "user gave no --agents at all".
+    out.agents = normalizeIds(agentTokens);
+  }
+  if (daemonWakeTokens.length) out.daemonWake = normalizeIds(daemonWakeTokens);
+  return out;
+}
+
+/**
+ * Help text for `chorus agents add [--help]` (formerly `chorus init`). Pure —
+ * takes the version so the caller (which already read package.json) does no IO here.
+ * @param {string} version
+ * @returns {string}
+ */
+export function initHelpText(version) {
+  return `
+Chorus agents add v${version} — one command to configure this machine's coding agents
+for Chorus. Detects installed agents, lets you pick which to configure, installs
+each one's Chorus plugin via that agent's own marketplace, and captures your
+Chorus credentials once into ~/.chorus/daemon.json. (Formerly \`chorus init\`.)
+
+USAGE
+  chorus agents add                          Interactive: detect, select, configure
+  chorus agents add --all                    Configure every supported agent
+  chorus agents add --agents claude,codex    Configure only the named agents
+
+OPTIONS
+  --agents <a,b>           Comma-separated agent ids to configure (repeatable).
+                           Valid ids come from the adapter registry; an unknown
+                           id is rejected with the list of valid ids.
+  --all                    Configure every supported agent.
+  --url <url>              Chorus server URL     (env: CHORUS_URL) — seeded once.
+  --api-key <cho_...>      Agent API key         (env: CHORUS_API_KEY) — seeded once.
+  --dsh-profile <name>     dsh profile to install the Chorus bundle into
+                           (env: CHORUS_DSH_PROFILE). Required for dsh in a
+                           non-interactive run; prompted on a TTY.
+  --daemon-wake <a,b>      Enable daemon auto-waking for these selected agents
+                           (repeatable). Wakeable agents (claude/codex/kiro) default
+                           to NOT woken; this opts specific ones in. On a TTY you are
+                           prompted per agent instead.
+  --daemon-wake-all        Enable daemon auto-waking for every selected wakeable agent.
+  --daemon-autostart       Install & enable the daemon boot service (Linux systemd /
+                           macOS launchd) in a non-interactive run. Ignored where
+                           auto-start is unsupported (e.g. Windows). In an
+                           interactive TTY run the daemon-setup step prompts instead
+                           (default: No).
+  -y, --yes                Accept confirmation prompts, including refreshing
+                           installed plugins to latest (implied when non-TTY).
+  -h, --help               Show this help message.
+
+NON-INTERACTIVE
+  When stdin/stdout is not a TTY, you MUST pass --agents or --all — the command
+  will not guess which agents to configure and aborts otherwise. The daemon boot service is
+  installed non-interactively ONLY when you pass --daemon-autostart; otherwise the
+  daemon config is written and you start it yourself with 'chorus daemon'.
+  With an explicit selection, --yes and non-TTY runs refresh selected installed
+  plugins to their latest available versions without prompting.
+
+SCOPE
+  This installs the plugin SURFACE, seeds credentials into the daemon config, and
+  optionally configures + auto-starts the local daemon. Live MCP tools for each
+  agent arrive with a sibling feature (the 'chorus mcp' proxy). The legacy
+  install-*.sh scripts are left untouched.
+
+EXAMPLES
+  chorus agents add
+  chorus agents add --all --yes
+  chorus agents add --agents claude,codex --url https://chorus.example.com --api-key cho_xxx --yes
+  chorus agents add --all --yes --daemon-autostart
+`;
+}

package/cli/init.mjs

@@ -0,0 +1,243 @@
+// cli/init.mjs
+// `chorus init` orchestrator (idea c055e285, A1). Dependency-injected so it
+// unit-tests without real detection / prompts / filesystem, mirroring the pure
+// entry-point style of cli/embedded-db.mjs and cli/client-args.mjs.
+//
+// Flow: parse flags → detect agents → resolve selection → run ordered steps →
+// print per-agent summary → exit code. The ORCHESTRATOR owns per-agent
+// iteration: `once` steps run a single time; `per-agent` steps run once per
+// selected agent with ctx.agentId + ctx.adapter set (contracts.mjs).
+
+import { createInterface } from "node:readline";
+import { copyFileSync, existsSync } from "node:fs";
+import { parseInitFlags, initHelpText } from "./init-args.mjs";
+import { resolveSelection as defaultResolveSelection } from "./init/select.mjs";
+import { STEP_SCOPES, OUTCOME_ACTIONS, isFailureOutcome } from "./init/contracts.mjs";
+
+/** Build the default runtime IO (real terminal). Only called at run time. */
+function defaultIo() {
+  const isTTY = !!(process.stdin.isTTY && process.stdout.isTTY);
+  return {
+    log: (m) => console.log(m),
+    isTTY,
+    ask: isTTY
+      ? (query) =>
+          new Promise((resolve) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(query, (answer) => {
+              rl.close();
+              resolve(answer);
+            });
+          })
+      : undefined,
+  };
+}
+
+/** Copy a file to `<path>.chorus-bak` once before overwrite (idempotent). */
+function backupFile(path) {
+  try {
+    if (!existsSync(path)) return null;
+    const bak = `${path}.chorus-bak`;
+    if (!existsSync(bak)) copyFileSync(path, bak);
+    return bak;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run `chorus init`.
+ * @param {string[]} argv  args after the `init` subcommand token
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   version?: string,
+ *   io?: { log: Function, ask?: Function, isTTY?: boolean },
+ *   parse?: (argv: string[]) => object,
+ *   resolveSelection?: Function,
+ *   detectAgents?: (env: NodeJS.ProcessEnv) => object[],
+ *   orderedSteps?: () => object[],
+ *   getAdapter?: (id: string) => (object | undefined),
+ *   backup?: (path: string) => (string | null),
+ * }} [deps]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runInit(argv = [], deps = {}) {
+  const env = deps.env ?? process.env;
+  const io = deps.io ?? defaultIo();
+  const parse = deps.parse ?? parseInitFlags;
+  const resolveSelection = deps.resolveSelection ?? defaultResolveSelection;
+  const backup = deps.backup ?? backupFile;
+
+  const flags = parse(argv);
+
+  if (flags.help) {
+    io.log(initHelpText(deps.version ?? ""));
+    return 0;
+  }
+
+  // Lazy defaults so importing this module never requires the registry to be
+  // fully populated (the registry is filled incrementally by sibling tasks).
+  const detectAgents =
+    deps.detectAgents ?? ((e) => import("./init/registry.mjs").then((m) => m.detectAgents(e)));
+  const orderedSteps =
+    deps.orderedSteps ?? (() => import("./init/registry.mjs").then((m) => m.orderedSteps()));
+  const getAdapter =
+    deps.getAdapter ?? ((id) => import("./init/registry.mjs").then((m) => m.getAdapter(id)));
+
+  const detections = await detectAgents(env);
+  const { selectedIds, error } = await resolveSelection({ flags, detections, io });
+  if (error) {
+    io.log(`[chorus agents add] ${error}`);
+    return 1;
+  }
+  if (!selectedIds || selectedIds.length === 0) {
+    io.log("[chorus agents add] Nothing to configure.");
+    return 0;
+  }
+
+  io.log(`[chorus agents add] Configuring: ${selectedIds.join(", ")}`);
+
+  // Resolve adapters once: update-intent detection and per-agent steps must see
+  // the same adapter instances/state readers.
+  const adapters = new Map();
+  for (const agentId of selectedIds) {
+    adapters.set(agentId, await getAdapter(agentId));
+  }
+  const updateInstalled = await resolveUpdateInstalled({
+    selectedIds,
+    adapters,
+    flags,
+    env,
+    io,
+  });
+  const resolvedFlags = { ...flags, updateInstalled };
+
+  const steps = await orderedSteps();
+  // `ctxExtras` lets a caller/test inject step-context collaborators (e.g. a
+  // fake credential validator or command runner) so an end-to-end run is
+  // hermetic; production passes none and steps use their real defaults.
+  const baseCtx = { selection: selectedIds, flags: resolvedFlags, io, env, backup, ...(deps.ctxExtras ?? {}) };
+  /** @type {import("./init/contracts.mjs").StepOutcome[]} */
+  const outcomes = [];
+
+  for (const step of steps) {
+    try {
+      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 }));
+        }
+      } else {
+        outcomes.push(await step.run(baseCtx));
+      }
+    } catch (err) {
+      // A crashing step becomes a visible failed outcome, never a silent abort.
+      outcomes.push({
+        stepId: step.id,
+        action: OUTCOME_ACTIONS.FAILED,
+        detail: `step threw: ${err?.message ?? String(err)}`,
+      });
+    }
+  }
+
+  summarize(outcomes.flat(), io, selectedIds);
+  return outcomes.flat().some(isFailureOutcome) ? 1 : 0;
+}
+
+/**
+ * Resolve one installed-plugin update decision for the whole invocation.
+ * Unsupported/guided adapters and selected adapters without an installed
+ * Chorus payload do not trigger the question. `--yes` and non-TTY runs accept
+ * automatically; an interactive answer defaults to no.
+ */
+export async function resolveUpdateInstalled({ selectedIds, adapters, flags, env, io }) {
+  let anyInstalled = false;
+  for (const agentId of selectedIds) {
+    const adapter = adapters.get(agentId);
+    if (!adapter || typeof adapter.readInstallState !== "function") continue;
+    try {
+      const profile = flags.dshProfile ?? env.CHORUS_DSH_PROFILE;
+      const state = await adapter.readInstallState({ env, profile });
+      if (state?.supported === true && state?.pluginInstalled === true) {
+        anyInstalled = true;
+        break;
+      }
+    } catch {
+      // State probes are advisory and read-only. A broken probe must not block
+      // normal repair/install work; the installer will report its own outcome.
+    }
+  }
+  if (!anyInstalled) return false;
+  if (flags.yes || !io.isTTY) return true;
+  if (typeof io.ask !== "function") return false;
+  const answer = String(await io.ask("Update installed Chorus plugins to the latest available versions? [y/N] ")).trim();
+  return /^(?:y|yes)$/i.test(answer);
+}
+
+/** Print the per-outcome summary table. */
+export function summarize(outcomes, io, selectedIds = []) {
+  io.log("");
+  io.log("[chorus agents add] Summary:");
+  if (outcomes.length === 0) {
+    io.log("  (no steps registered yet)");
+  }
+  for (const o of outcomes) {
+    const who = o.agentId ? `${o.agentId}` : o.stepId;
+    io.log(`  - ${who}: ${o.action}${o.detail ? ` — ${o.detail}` : ""}`);
+  }
+  const failed = outcomes.filter(isFailureOutcome);
+  if (failed.length) {
+    io.log(`[chorus agents add] ${failed.length} step(s) failed — see above.`);
+  } else if (selectedIds.length) {
+    io.log("[chorus agents add] Done. Next: run the daemon / connect MCP to activate tools.");
+  }
+
+  profileExportHint(outcomes, io);
+}
+
+/**
+ * Print an optional `export CHORUS_AGENT_PROFILE=…` hint for every agent whose
+ * identity credential-seed captured. Setting it in an interactive shell lets that
+ * shell's Chorus hooks/skills act as a specific agent — the CLI resolves the key
+ * from ~/.chorus/daemon.json by profile, so the API key need not be exported for
+ * the wrapper/doc-mirror MCP path. It is OPTIONAL and ADDITIVE (Claude Code's
+ * built-in MCP client still reads CHORUS_URL/CHORUS_API_KEY from the env);
+ * daemon-woken sessions receive CHORUS_AGENT_PROFILE from the spawner automatically.
+ *
+ * EXCEPTIONS — dsh, Claude Code, and Codex: when credential-seed persisted the profile
+ * into `$DSH_HOME/.env` (outcome `profileInEnv: true`) dsh loads it into the session env
+ * on its own; when it wrote the full CHORUS_* env into `~/.claude/settings.json`
+ * (outcome `settingsEnvWritten: true`) Claude Code injects it at session start; and when
+ * it wrote the CHORUS_* env into `~/.codex/.env` (outcome `codexEnvWritten: true`) Codex
+ * loads it into its process env at startup, reaching both its plugin hooks and shell tool.
+ * Either way a manual export is redundant — that agent is omitted from the hint. Every other
+ * agent (Kiro, …) has no such file channel and still gets the hint.
+ * @param {import("./init/contracts.mjs").StepOutcome[]} outcomes
+ * @param {{ log: Function }} io
+ */
+export function profileExportHint(outcomes, io) {
+  const seen = new Set();
+  const profiles = [];
+  for (const o of outcomes) {
+    // dsh persists CHORUS_AGENT_PROFILE in $DSH_HOME/.env and loads it into the
+    // session env itself — no manual export needed, so skip it here. Claude Code
+    // likewise has its full CHORUS_* env written into ~/.claude/settings.json
+    // (settingsEnvWritten), and Codex into ~/.codex/.env (codexEnvWritten) — those sessions
+    // are fully wired, so skip them too.
+    if (o && (o.profileInEnv === true || o.settingsEnvWritten === true || o.codexEnvWritten === true)) continue;
+    if (o && typeof o.agentUuid === "string" && o.agentUuid && !seen.has(o.agentUuid)) {
+      seen.add(o.agentUuid);
+      profiles.push({ agentUuid: o.agentUuid, agentName: typeof o.agentName === "string" ? o.agentName : "" });
+    }
+  }
+  if (profiles.length === 0) return;
+
+  io.log("");
+  io.log("[chorus agents add] Optional — act as an agent in THIS shell without exporting its API key");
+  io.log("  (Chorus hooks/skills resolve the key from ~/.chorus/daemon.json by profile):");
+  for (const p of profiles) {
+    io.log(`    export CHORUS_AGENT_PROFILE="${p.agentUuid}"${p.agentName ? `   # ${p.agentName}` : ""}`);
+  }
+  io.log("  One per shell — pick the identity it should act as; add it to ~/.bashrc / ~/.zshrc");
+  io.log("  to persist. Daemon-woken sessions set CHORUS_AGENT_PROFILE automatically.");
+}