@chorus-aidlc/chorus 0.15.0 → 0.16.1

package/cli/claude-spawner.mjs

@@ -284,7 +284,11 @@ export class ClaudeSpawner {
    *   so the waker can store the handle in its execution registry for the interrupt
    *   path BEFORE this promise resolves. It is invoked once, synchronously, only on a
    *   successful spawn; a spawn failure never calls it.
-   * @returns {Promise<{ sessionId: string, exitCode: number|null, isNew: boolean }>}
+   * @returns {Promise<{ sessionId: string, backendSessionId: string|null, exitCode: number|null, isNew: boolean }>}
+   *   `backendSessionId` is the Claude `--resume` anchor (the input `sessionId`) on a
+   *   terminal resolution after a spawn, so the conversation UI can offer a resumable
+   *   id — mirrors codex-spawner's shape. `null` on the pre-spawn failure paths (no
+   *   turn ran, nothing to resume).
    */
   async wake({ prompt, sessionId, isNew, mcpConfigPath, cwd, onMessage, onChild }) {
     const id = sessionId;
@@ -295,14 +299,14 @@ export class ClaudeSpawner {
       this.logger.error(
         `[Chorus] refusing to spawn: session id is not a valid lowercase UUID: ${id}`
       );
-      return { sessionId: typeof id === "string" ? id : "", exitCode: null, isNew: Boolean(isNew) };
+      return { sessionId: typeof id === "string" ? id : "", backendSessionId: null, exitCode: null, isNew: Boolean(isNew) };
     }
 
     const claudePath = this.claudePath ?? resolveClaudePath();
     if (!claudePath) {
       // No crash — surface visibly and resolve with a failure result.
       this.logger.error("[Chorus] cannot locate the `claude` executable on PATH; skipping wake");
-      return { sessionId: id, exitCode: null, isNew };
+      return { sessionId: id, backendSessionId: null, exitCode: null, isNew };
     }
 
     const args = buildArgs({ sessionId: id, isNew, mcpConfigPath, permissionMode: this.permissionMode });
@@ -345,7 +349,7 @@ export class ClaudeSpawner {
         });
       } catch (err) {
         this.logger.error(`[Chorus] failed to spawn claude: ${err}`);
-        resolve({ sessionId: id, exitCode: null, isNew });
+        resolve({ sessionId: id, backendSessionId: null, exitCode: null, isNew });
         return;
       }
 
@@ -391,14 +395,19 @@ export class ClaudeSpawner {
       child.on("error", (err) => {
         // e.g. ENOENT if the resolved path vanished — log, don't throw.
         this.logger.error(`[Chorus] claude process error: ${err}`);
-        resolve({ sessionId: observedSessionId, exitCode: null, isNew });
+        // backendSessionId is the `--resume` anchor (`id`), NOT observedSessionId:
+        // a fork-on-resume claude can emit a new stream session_id, but the daemon
+        // resumes and files the transcript under `id`, so `id` is the resumable value.
+        resolve({ sessionId: observedSessionId, backendSessionId: id, exitCode: null, isNew });
       });
 
       child.on("close", (code) => {
         if (code !== 0) {
           this.logger.warn(`[Chorus] claude exited with code ${code}`);
         }
-        resolve({ sessionId: observedSessionId, exitCode: code, isNew });
+        // backendSessionId is the `--resume` anchor (`id`), NOT observedSessionId (see
+        // the process-error handler above for why the anchor is the resumable value).
+        resolve({ sessionId: observedSessionId, backendSessionId: id, exitCode: code, isNew });
       });
 
       // Guard against an ASYNC stdin error (EPIPE): if claude exits/closes

package/cli/client-args.mjs

@@ -69,6 +69,7 @@ export function parseClientFlags(argv) {
     else if (a === "-d" || a === "--detach") out.detach = true;
     else if (a === "--force") out.force = true;
     else if (a === "--yes" || a === "-y") out.yes = true;
+    else if (a === "--add") out.add = true;
     else if (a === "--help" || a === "-h") out.help = true;
   }
   return out;
@@ -202,9 +203,16 @@ USAGE
 OPTIONS
   --url <url>              Remote Chorus server URL            (env: CHORUS_URL)
   --api-key <cho_...>      Agent API key                       (env: CHORUS_API_KEY)
+  --add                    Add this key as an ADDITIONAL agent (multi-agent daemon)
+                           instead of overwriting the single credential
   -h, --help               Show this help message
 
   With no flags, login prompts interactively for the URL and a masked API key,
   validates them against the server, and on success saves the credentials.
+
+  With --add, the validated key is appended to the daemon.json 'agents[]' array
+  so one daemon can serve several independent agents (see docs/DAEMON.md). The
+  first --add migrates an existing flat credential into agents[0]; a duplicate
+  key is refused and existing agents are never overwritten.
 `;
 }

package/cli/codex-spawner.mjs

@@ -13,9 +13,13 @@
 //     it and persist anchor→thread_id (codex-session-map.mjs) so a later wake can
 //     `resume <thread_id>`. (serde: ThreadEvent tag="type", rename="thread.started";
 //     ThreadStartedEvent.thread_id: String — codex-rs/exec/src/exec_events.rs.)
-//   • No `--mcp-config`: MCP comes from the user's ~/.codex/config.toml. The daemon
-//     exports its resolved URL for SessionStart hooks and its key for the configured
-//     bearer_token_env_var (default CHORUS_API_KEY) — never argv.
+//   • No `--mcp-config`: Codex reads MCP servers from the user's ~/.codex/config.toml.
+//     The Chorus MCP key there is USER-MANAGED: the installer writes a LITERAL Bearer
+//     header and Codex does NOT expand ${VAR} inside http_headers, so the CHORUS_API_KEY
+//     the daemon exports does NOT reach Codex's MCP auth. The daemon still exports
+//     CHORUS_URL / CHORUS_API_KEY into the child env — but only for the plugin's shell
+//     tooling (chorus-api.sh / SessionStart hooks), never argv and never Codex MCP.
+//     (Multi-agent: two Codex agents with different keys each need their own CODEX_HOME.)
 //   • Permission is a SANDBOX mode, not a tool allowlist.
 //
 // Reuses claude-spawner's platform-neutral helpers: parseNdjsonChunk (NDJSON

package/cli/credentials.mjs

@@ -70,6 +70,47 @@ export function readYoloAck(deps = {}) {
   return file ? nonEmpty(file.yoloAckAt) ?? null : null;
 }
 
+/**
+ * Resolve the DEFAULT url + apiKey layer (per-field, non-throwing) for the
+ * multi-agent config. Unlike `resolveCredentials` (which needs a COMPLETE pair
+ * and throws when none resolves), this resolves each field independently and
+ * returns `undefined` for any field no source supplies. It is the "top-level
+ * defaults" layer that each `agents[]` entry merges over: an agent that omits
+ * `url` inherits this default `url`, an agent that omits `apiKey` inherits this
+ * default `apiKey` (rarely useful, but symmetric with every other default).
+ *
+ * Same source order as `resolveCredentials`, applied per field:
+ *   flag > env > login file (top-level) > plugin fallback.
+ *
+ * @param {{ url?: string, apiKey?: string }} flags
+ * @param {ResolveDeps} [deps]
+ * @returns {{ url: string | undefined, apiKey: string | undefined }}
+ */
+export function resolveCredentialDefaults(flags = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const settingsPath = deps.settingsPath ?? claudeSettingsPath();
+
+  const file = readJson(loginPath);
+  const settings = readJson(settingsPath);
+  const pluginEnv =
+    settings && typeof settings.env === "object" && settings.env !== null
+      ? /** @type {Record<string, unknown>} */ (settings.env)
+      : null;
+
+  const pick = (flagVal, envKey, fileKey) =>
+    nonEmpty(flagVal) ??
+    nonEmpty(env[envKey]) ??
+    (file ? nonEmpty(file[fileKey]) : undefined) ??
+    (pluginEnv ? nonEmpty(pluginEnv[envKey]) : undefined);
+
+  return {
+    url: pick(flags.url, "CHORUS_URL", "url"),
+    apiKey: pick(flags.apiKey, "CHORUS_API_KEY", "apiKey"),
+  };
+}
+
 /**
  * @typedef {Object} ResolvedCredentials
  * @property {string} url

package/cli/daemon-config.mjs

@@ -15,11 +15,21 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, resolve as resolvePath } from "node:path";
-import { loginFilePath } from "./credentials.mjs";
+import { loginFilePath, resolveCredentials, resolveCredentialDefaults } from "./credentials.mjs";
+import { resolveAgentType, KNOWN_AGENTS } from "./daemon-agent.mjs";
+import { resolvePermissionMode } from "./daemon-permission-mode.mjs";
 
 /** Built-in default escalation window (ms) — matches the spec's 10 seconds. */
 export const DEFAULT_SIGINT_TIMEOUT_MS = 10_000;
 
+/**
+ * Built-in default per-agent wake concurrency. This was the process-wide
+ * hardcoded WakeQueue cap (`maxConcurrency ?? 4` in daemon.mjs) before it became
+ * a per-agent, configurable value — kept at 4 so an agent that specifies no
+ * `maxConcurrency` behaves exactly as the daemon did before.
+ */
+export const DEFAULT_MAX_CONCURRENCY = 4;
+
 /**
  * Coerce a value to a positive finite integer of milliseconds, or undefined when it
  * is absent / not a usable number. Accepts a number or a numeric string (env vars
@@ -235,3 +245,194 @@ export function resolveBrowseRoots(flags = {}, deps = {}) {
     : [];
   return fromFile.length ? fromFile : [normalizeCwd(home, home)];
 }
+
+// ===== Multi-agent config (daemon-multi-agent — N independent agents per daemon) =====
+//
+// One daemon process may serve a LIST of fully-independent agents, each with its
+// own credentials + working directories + backend + permission mode + concurrency.
+// `resolveAgentConfigs` returns that list as `AgentConfig[]`, every field already
+// merged with its default. Two shapes are supported:
+//
+//   1. `~/.chorus/daemon.json` has a non-empty `agents: [ … ]` array → one
+//      AgentConfig per entry, each entry's fields merged OVER the top-level
+//      defaults (per-agent value wins; an omitted field inherits the default).
+//   2. No `agents[]` (or empty) → exactly ONE AgentConfig synthesized from the
+//      existing flat resolution (resolveCredentials + resolveDaemonCwds +
+//      resolveAgentType + sigint + browseRoots). This is byte-for-byte the
+//      daemon's current single-agent behavior — old installs run unchanged, and
+//      flags / env still resolve this single agent's fields.
+//
+// Validation is strict and visible: a missing apiKey, an unresolvable url, an
+// unknown agentType, or an invalid permissionMode THROWS an Error naming the
+// offending agent. The daemon's top-level error handler turns that into a
+// non-zero exit — the resolver never silently drops or falls back to a default
+// agent (matching resolveCredentials' throw-on-nothing contract).
+
+/** A non-empty trimmed string, or undefined. */
+function nonEmptyStr(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * True iff `~/.chorus/daemon.json` declares a non-empty `agents[]` with at least
+ * one object entry — i.e. the daemon should run in multi-agent mode. Lets the
+ * daemon pick the multi-agent startup path (bypassing the flat single-credential
+ * preflight) without duplicating the file read. Never throws.
+ * @param {{ readJson?: (p: string) => (Record<string, unknown>|null), loginPath?: string }} [deps]
+ * @returns {boolean}
+ */
+export function hasConfiguredAgents(deps = {}) {
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const file = readJson(loginPath);
+  return Boolean(
+    file && Array.isArray(file.agents) && file.agents.some((a) => a && typeof a === "object"),
+  );
+}
+
+/**
+ * Coerce to a positive finite integer (count), or undefined. Accepts number or
+ * numeric string; rejects 0, negatives, NaN, Infinity. Used for maxConcurrency.
+ * @param {unknown} value @returns {number | undefined}
+ */
+function positiveInt(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  const n = typeof value === "number" ? value : Number(String(value).trim());
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return Math.floor(n);
+}
+
+/**
+ * @typedef {Object} AgentConfig  One fully-resolved agent runtime config.
+ * @property {string} url                       Chorus server URL for this agent.
+ * @property {string} apiKey                    This agent's `cho_` API key.
+ * @property {string} agentType                 Backend: claude-code | codex | kiro.
+ * @property {Array<string|undefined>} cwds     Served paths (`undefined` ⇒ process cwd).
+ * @property {"yolo"|"chorus"} permissionMode   Woken-agent permission posture.
+ * @property {number} maxConcurrency            This agent's wake-queue cap.
+ * @property {number} sigintTimeoutMs           Interrupt escalation window (ms).
+ * @property {string[]} browseRoots             Directory-discovery allowlist.
+ * @property {string} label                     Diagnostic label ("agent" or "agents[i]").
+ */
+
+/**
+ * Resolve the list of agents this daemon serves. See the block comment above.
+ *
+ * @param {{ url?: string, apiKey?: string, agent?: string, cwd?: string|string[],
+ *           browseRoot?: string|string[], sigintTimeout?: number|string,
+ *           chorusOnly?: boolean, yolo?: boolean }} [flags]
+ * @param {{
+ *   env?: Record<string, string|undefined>,
+ *   readJson?: (path: string) => (Record<string, unknown>|null),
+ *   loginPath?: string,
+ *   settingsPath?: string,
+ *   home?: string,
+ *   permissionMode?: "yolo"|"chorus",   // pre-resolved global posture (else computed)
+ * }} [deps]
+ * @returns {AgentConfig[]}  Non-empty list; throws on an invalid agent entry.
+ */
+export function resolveAgentConfigs(flags = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const home = deps.home ?? homedir();
+  const file = readJson(loginPath);
+
+  // Global default permission posture; a per-agent `permissionMode` overrides it.
+  // needConfirm/hasAck is vestigial, so isTTY/hasAck do not affect the resolved mode.
+  const defaultPermissionMode =
+    deps.permissionMode ??
+    resolvePermissionMode(flags, env, { isTTY: false, hasAck: false }).mode;
+
+  const agentEntries =
+    file && Array.isArray(file.agents)
+      ? file.agents.filter((a) => a && typeof a === "object")
+      : [];
+
+  // ---- Back-compat: no agents[] → exactly one agent from flat resolution ----
+  if (agentEntries.length === 0) {
+    const creds = resolveCredentials(flags, deps); // throws if no complete pair (today's behavior)
+    const at = resolveAgentType(flags, env, deps);
+    if (!at.ok) throw new Error(at.error);
+    return [
+      {
+        url: creds.url,
+        apiKey: creds.apiKey,
+        agentType: at.agent,
+        cwds: resolveDaemonCwds(flags, deps),
+        permissionMode: defaultPermissionMode,
+        maxConcurrency: positiveInt(file?.maxConcurrency) ?? DEFAULT_MAX_CONCURRENCY,
+        sigintTimeoutMs: resolveSigintTimeoutMs(flags, deps),
+        browseRoots: resolveBrowseRoots(flags, deps),
+        label: "agent",
+      },
+    ];
+  }
+
+  // ---- Multi-agent: each entry merged over the top-level defaults ----
+  const credDefaults = resolveCredentialDefaults(flags, deps);
+  const defaultCwds = resolveDaemonCwds(flags, deps);
+  const defaultAgentType = resolveAgentType(flags, env, deps); // top-level default (may be {ok:false} if top-level `agent` is garbage)
+  const defaultSigint = resolveSigintTimeoutMs(flags, deps);
+  const defaultBrowseRoots = resolveBrowseRoots(flags, deps);
+  const defaultMaxConcurrency = positiveInt(file?.maxConcurrency) ?? DEFAULT_MAX_CONCURRENCY;
+
+  return agentEntries.map((entry, i) => {
+    const label = nonEmptyStr(entry.label) ?? nonEmptyStr(entry.name) ?? `agents[${i}]`;
+
+    const url = nonEmptyStr(entry.url) ?? credDefaults.url;
+    const apiKey = nonEmptyStr(entry.apiKey) ?? credDefaults.apiKey;
+    if (!apiKey) {
+      throw new Error(`Agent ${label}: missing apiKey (no per-agent apiKey and no top-level default).`);
+    }
+    if (!url) {
+      throw new Error(`Agent ${label}: missing/unresolvable url (no per-agent url and no top-level default).`);
+    }
+
+    // agentType: per-agent value, else the top-level default (which must itself be valid).
+    let agentType;
+    if (nonEmptyStr(entry.agentType)) {
+      agentType = nonEmptyStr(entry.agentType);
+    } else if (defaultAgentType.ok) {
+      agentType = defaultAgentType.agent;
+    } else {
+      throw new Error(
+        `Agent ${label}: no agentType and the top-level agent default is invalid (${defaultAgentType.error}).`,
+      );
+    }
+    if (!KNOWN_AGENTS.includes(agentType)) {
+      throw new Error(
+        `Agent ${label}: unknown agentType "${agentType}". Accepted: ${KNOWN_AGENTS.join(", ")}.`,
+      );
+    }
+
+    // permissionMode: per-agent override (yolo|chorus only), else global posture.
+    let permissionMode = defaultPermissionMode;
+    if (entry.permissionMode !== undefined) {
+      const pm = nonEmptyStr(entry.permissionMode);
+      if (pm !== "yolo" && pm !== "chorus") {
+        throw new Error(
+          `Agent ${label}: invalid permissionMode "${entry.permissionMode}". Accepted: yolo, chorus.`,
+        );
+      }
+      permissionMode = pm;
+    }
+
+    // cwds: per-agent list (cleaned); an empty/blank list degrades to [undefined]
+    // (serve the process cwd). Omitted → inherit the top-level default set.
+    let cwds;
+    if (entry.cwds !== undefined) {
+      const cleaned = cleanCwdList(entry.cwds, home);
+      cwds = cleaned.length ? cleaned : [undefined];
+    } else {
+      cwds = defaultCwds;
+    }
+
+    const maxConcurrency = positiveInt(entry.maxConcurrency) ?? defaultMaxConcurrency;
+    const sigintTimeoutMs = positiveIntMs(entry.sigintTimeoutMs) ?? defaultSigint;
+    const browseRoots =
+      entry.browseRoots !== undefined ? cleanCwdList(entry.browseRoots, home) : defaultBrowseRoots;
+
+    return { url, apiKey, agentType, cwds, permissionMode, maxConcurrency, sigintTimeoutMs, browseRoots, label };
+  });
+}

package/cli/daemon-install-config.mjs

@@ -23,7 +23,7 @@
 
 import { homedir } from "node:os";
 import { resolveCredentials, loginFilePath } from "./credentials.mjs";
-import { updateDaemonConfig, prompt as defaultPrompt } from "./login.mjs";
+import { updateDaemonConfig, appendAgentConfig, prompt as defaultPrompt } from "./login.mjs";
 import { validateAndFetchIdentity } from "./chorus-client.mjs";
 import { normalizeCwd, cleanCwdList } from "./daemon-config.mjs";
 import { KNOWN_AGENTS, DEFAULT_AGENT } from "./daemon-agent.mjs";
@@ -132,6 +132,43 @@ export async function resolveInstallCredentials(flags = {}, env = {}, opts = {})
   //    field-merge writer preserves cwds / yoloAckAt / sigintTimeoutMs.
   writeConfig({ url, apiKey, agentUuid: identity.uuid, agentName: identity.name });
   log(`[Chorus] credentials saved for ${identity.name} (${identity.uuid}).`);
+
+  // Multi-agent (daemon-multi-agent): with `--add` on a TTY, offer to add more
+  // agents in the same run. Each additional key is validated then APPENDED to
+  // agents[] (the first agent above is folded into agents[0] on the first
+  // append). Opt-in via --add so a plain install prompts for nothing extra;
+  // never runs on a non-TTY / --yes / skip run. Hand-editing daemon.json remains
+  // fully supported regardless.
+  if (isTTY && !skip && flags.add === true) {
+    const appendAgent = opts.appendAgent ?? appendAgentConfig;
+    // Bound the loop so a stuck/looping prompt can never spin forever.
+    for (let added = 0; added < 32; added += 1) {
+      const more = nonEmpty(await ask("Add another agent? [y/N]: "));
+      if (!more || !/^y(es)?$/i.test(more)) break;
+      const u = nonEmpty(await ask("  Chorus URL: "));
+      const k = nonEmpty(await ask("  Chorus API key (cho_...): ", { mask: true }));
+      if (!u || !k) {
+        errLog("[Chorus] both a URL and an API key are required — skipping this agent.");
+        continue;
+      }
+      let id;
+      try {
+        id = await validate({ url: u, apiKey: k });
+      } catch (err) {
+        errLog(
+          `[Chorus] validation failed: ${err instanceof Error ? err.message : String(err)} — this agent was NOT added.`,
+        );
+        continue;
+      }
+      const res = appendAgent({ url: u, apiKey: k, agentUuid: id.uuid, agentName: id.name });
+      if (!res.ok) {
+        errLog(`[Chorus] agent ${id.name} (${id.uuid}) is already configured — skipping.`);
+        continue;
+      }
+      log(`[Chorus] added agent ${id.name} (${id.uuid}) — this daemon now serves ${res.agents.length} agents.`);
+    }
+  }
+
   return { ok: true, creds: { url, apiKey }, identity };
 }
 

package/cli/daemon.mjs

@@ -47,7 +47,13 @@ import { createInterruptReporter } from "./interrupt-reporter.mjs";
 import { createTurnReporter } from "./turn-reporter.mjs";
 import { createDaemonRestClient } from "./daemon-rest-client.mjs";
 import { createControlHandler } from "./control-handler.mjs";
-import { resolveSigintTimeoutMs, resolveDaemonCwds, resolveBrowseRoots } from "./daemon-config.mjs";
+import {
+  resolveSigintTimeoutMs,
+  resolveDaemonCwds,
+  resolveBrowseRoots,
+  resolveAgentConfigs,
+  hasConfiguredAgents,
+} from "./daemon-config.mjs";
 import { discoverDirectories, validateDirectory } from "./directory-discovery.mjs";
 import {
   startBackground,
@@ -544,6 +550,122 @@ export function buildDaemon(creds, deps = {}) {
   };
 }
 
+/**
+ * Fan-out builder: compose ONE `buildDaemon` runtime per agent config, so a single
+ * daemon process serves N fully-independent agents — each with its own creds,
+ * ChorusClient, LineageResolver, spawner (by its `agentType`), WakeQueue (its own
+ * `maxConcurrency`), and connections over its OWN cwds. For N=1 this is behaviorally
+ * identical to `buildDaemon({url,apiKey}, deps)`.
+ *
+ * Each agent's runtime is isolated: a build/start failure in one agent is logged and
+ * skipped, and the others keep serving. The aggregate `allConflict` settles only when
+ * EVERY agent's paths are all already served (nothing left to do at all).
+ *
+ * Injectable seams mirror `buildDaemon`; array-valued deps (`spawner`, `mcpClient`,
+ * `lineage`, `sseListener`, `makeSseListener`) are indexed PER agent for tests.
+ *
+ * @param {import("./daemon-config.mjs").AgentConfig[]} agentConfigs
+ * @param {object} [deps]
+ * @returns {{ agents: Array<{cfg: any, daemon: any}>, connections: any[],
+ *   waker: any, router: any, sseListener: any, allConflict: Promise<void>,
+ *   start: () => Promise<void>, stop: () => Promise<void> }}
+ */
+export function buildMultiAgentDaemon(agentConfigs, deps = {}) {
+  const logger = deps.logger ?? defaultLogger();
+  if (!Array.isArray(agentConfigs) || agentConfigs.length === 0) {
+    throw new Error("buildMultiAgentDaemon: at least one agent config is required");
+  }
+  const build = deps.build ?? buildDaemon;
+  const perAgent = (key, i) => {
+    const v = deps[key];
+    return Array.isArray(v) ? v[i] : i === 0 ? v : undefined;
+  };
+
+  const agents = agentConfigs
+    .map((cfg, i) => {
+      // Per-agent deps: cfg fields drive the per-agent runtime; injectable fakes are
+      // indexed per agent. `cwd` (singular) is cleared so a caller's single value can
+      // never leak across agents — each agent's `cwds` is authoritative.
+      const agentDeps = {
+        ...deps,
+        logger,
+        permissionMode: cfg.permissionMode,
+        agentType: cfg.agentType,
+        cwds: cfg.cwds,
+        cwd: undefined,
+        maxConcurrency: cfg.maxConcurrency,
+        sigintTimeoutMs: cfg.sigintTimeoutMs,
+        browseRoots: cfg.browseRoots,
+        mcpClient: perAgent("mcpClient", i),
+        lineage: perAgent("lineage", i),
+        spawner: perAgent("spawner", i),
+        sseListener: perAgent("sseListener", i),
+        makeSseListener: Array.isArray(deps.makeSseListener)
+          ? deps.makeSseListener[i]
+          : deps.makeSseListener,
+      };
+      try {
+        return { cfg, daemon: build({ url: cfg.url, apiKey: cfg.apiKey }, agentDeps) };
+      } catch (err) {
+        logger.error?.(
+          `[Chorus] agent ${cfg.label}: failed to build runtime — skipping ` +
+            `(${err instanceof Error ? err.message : String(err)})`,
+        );
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  if (agents.length === 0) {
+    throw new Error("buildMultiAgentDaemon: all agent runtimes failed to build");
+  }
+
+  const connections = agents.flatMap((a) => a.daemon.connections ?? []);
+  const primary = agents[0].daemon;
+  // Aggregate all-conflict: settles only when EVERY agent's paths are all already
+  // served by a live daemon (each agent's allConflict settles only in that case, and
+  // never otherwise). A single serving agent keeps the whole daemon alive.
+  const allConflict = Promise.all(
+    agents.map((a) => a.daemon.allConflict ?? new Promise(() => {})),
+  ).then(() => {});
+
+  return {
+    agents,
+    connections,
+    // Back-compat single aliases (first agent's primary connection) for inspection.
+    waker: primary.waker,
+    router: primary.router,
+    sseListener: primary.sseListener,
+    allConflict,
+    async start() {
+      // Start each agent independently; one agent's start failure is logged and
+      // isolated so the others still serve.
+      for (const a of agents) {
+        try {
+          await a.daemon.start();
+        } catch (err) {
+          logger.error?.(
+            `[Chorus] agent ${a.cfg.label}: start failed — ` +
+              `${err instanceof Error ? err.message : String(err)} (other agents continue)`,
+          );
+        }
+      }
+    },
+    async stop() {
+      for (const a of agents) {
+        try {
+          await a.daemon.stop();
+        } catch (err) {
+          logger.warn?.(
+            `[Chorus] agent ${a.cfg.label}: stop error — ` +
+              `${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      }
+    },
+  };
+}
+
 /**
  * Entry point for `chorus daemon`. Resolves credentials, validates them
  * (echoing the agent identity), and runs the daemon until terminated.
@@ -650,6 +772,105 @@ export async function runDaemon(flags = {}, deps = {}) {
   const cwds = resolveDaemonCwds({ cwd: flags.cwd }, { env });
   const browseRoots = resolveBrowseRoots({ browseRoot: flags.browseRoot }, { env });
 
+  // ===== Multi-agent mode (daemon-multi-agent) =====
+  // When daemon.json declares a non-empty agents[], run N fully-independent agents in
+  // one process. Each agent carries its OWN creds, so this bypasses the flat single-
+  // credential preflight (interactive credential completion is a single-agent
+  // affordance). Each agent authenticates on its own key; a failure is isolated
+  // (logged + that agent skipped) so the rest still serve.
+  if (hasConfiguredAgents({ readJson: deps.readJson, loginPath: deps.loginPath })) {
+    const buildMulti = deps.buildMulti ?? buildMultiAgentDaemon;
+    let agentConfigs;
+    try {
+      agentConfigs = resolveAgentConfigs(
+        {
+          url: flags.url,
+          apiKey: flags.apiKey,
+          agent: flags.agent,
+          cwd: flags.cwd,
+          browseRoot: flags.browseRoot,
+          sigintTimeout: flags.sigintTimeout,
+          chorusOnly: flags.chorusOnly,
+          yolo: flags.yolo,
+        },
+        { env, readJson: deps.readJson, loginPath: deps.loginPath },
+      );
+    } catch (err) {
+      errLog(`[Chorus] ${err instanceof Error ? err.message : String(err)}`);
+      return 1;
+    }
+
+    // Validate each agent independently. A validation failure logs + skips that agent
+    // (isolation) — the daemon still serves the agents that authenticated.
+    const okConfigs = [];
+    for (const cfg of agentConfigs) {
+      try {
+        const id = await validate({ url: cfg.url, apiKey: cfg.apiKey });
+        okConfigs.push(cfg);
+        log(
+          `[Chorus] agent ${cfg.label}: ${id.name} (${id.uuid}) — ${cfg.agentType}, ` +
+            `${cfg.permissionMode}, ${cfg.cwds.length} path(s), maxConcurrency=${cfg.maxConcurrency}`,
+        );
+        if (cfg.permissionMode === "yolo") errLog(`[Chorus] agent ${cfg.label}: ${yoloWarningLine()}`);
+      } catch (err) {
+        errLog(
+          `[Chorus] agent ${cfg.label}: credential validation failed — ` +
+            `${err instanceof Error ? err.message : String(err)} (skipping this agent)`,
+        );
+      }
+    }
+    if (okConfigs.length === 0) {
+      errLog(
+        `[Chorus] no agents authenticated — nothing to serve. Check the apiKeys in ${loginFilePath()}.`,
+      );
+      return 1;
+    }
+
+    const totalPaths = okConfigs.reduce((n, c) => n + c.cwds.length, 0);
+    log(
+      `[Chorus] multi-agent daemon starting — ${okConfigs.length} agent(s), ` +
+        `${totalPaths} connection(s), subscribing to ${okConfigs[0].url}/api/events/notifications`,
+    );
+    const multiDaemon = buildMulti(okConfigs, {
+      logger: { info: log, warn: errLog, error: errLog },
+      verbose,
+      fetchImpl: deps.fetchImpl,
+      killer: deps.killer,
+      sseListener: deps.sseListener,
+      makeSseListener: deps.makeSseListener,
+      spawner: deps.spawner,
+      mcpClient: deps.mcpClient,
+      lineage: deps.lineage,
+      build: deps.build,
+    });
+
+    const shutdownMulti = () => {
+      log("[Chorus] shutting down daemon...");
+      Promise.resolve(multiDaemon.stop()).finally(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdownMulti);
+    process.on("SIGTERM", shutdownMulti);
+    await multiDaemon.start();
+    log("[Chorus] multi-agent daemon running. Waiting for task dispatches (Ctrl+C to stop).");
+
+    const ALL_CONFLICT_M = Symbol("all-conflict");
+    const waitForeverM = deps.waitForever ?? (() => new Promise(() => {}));
+    const allConflictSignalM = multiDaemon.allConflict ?? new Promise(() => {});
+    const outcomeM = await Promise.race([
+      waitForeverM().then(() => 0),
+      allConflictSignalM.then(() => ALL_CONFLICT_M),
+    ]);
+    if (outcomeM === ALL_CONFLICT_M) {
+      errLog(
+        `[Chorus] every declared path for every agent is already served by a live daemon — ` +
+          `nothing to do. Stop the other daemon(s) or remove the conflicting path(s), then restart.`,
+      );
+      await multiDaemon.stop();
+      return 1;
+    }
+    return 0;
+  }
+
   // Foreground preflight: resolve/complete credentials + resolve the permission
   // posture (confirming yolo on a TTY). Reuses the same pfDeps bundle the detach
   // path uses. Returns a numeric exit code on failure, or