@chorus-aidlc/chorus 0.15.1 → 0.16.2

package/cli/daemon.mjs

@@ -8,6 +8,12 @@
 // so a human can `claude --resume <idea-uuid>`); new-vs-resume is decided by
 // probing the on-disk transcript — there is no persisted session-id map.
 //
+// Wake coalescing (add-daemon-wake-coalescing): the WakeQueue is PER-CONNECTION
+// and serializes per DIRECT idea (= per session). Wakes that pile up on the same
+// key while a turn runs are drained together and delivered as ONE batch — a
+// single runBatch → waker.wakeBatch → one `claude --resume` turn — so N
+// same-session queued wakes coalesce into one turn, never N sequential turns.
+//
 // Connection / session / transcript reporting to the server is intentionally
 // NOT done here — the no-op UploadHooks reserve those seams for the derived
 // observability idea.
@@ -47,7 +53,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,
@@ -141,10 +153,7 @@ export function buildDaemon(creds, deps = {}) {
   // passed through so the Codex backend can export the daemon key into the woken
   // process env (the Claude backend ignores creds — it gets its key via --mcp-config).
   const spawner = deps.spawner ?? selectSpawner(agentType, { logger, permissionMode, creds });
-  // The WakeQueue serializes per DIRECT idea (keyFor's key). It is shared across all
-  // path-connections: serialization-per-idea still holds, and maxConcurrency caps the
-  // whole process's in-flight wakes rather than per-cwd — the right global budget.
-  const queue = new WakeQueue({ maxConcurrency: deps.maxConcurrency ?? 4, logger });
+  const maxConcurrency = deps.maxConcurrency ?? 4;
 
   // ===== Multi-path: the SET of cwds this daemon serves (T3 — FR-5) =====
   // Each declared path becomes one INDEPENDENT connection (own SSE self-report + own
@@ -332,6 +341,11 @@ export function buildDaemon(creds, deps = {}) {
         selectWaker(notification).markQueued(notification, key, attribution),
       wake: (notification, key, attribution) =>
         selectWaker(notification).wake(notification, key, attribution),
+      // Coalesced batch (add-daemon-wake-coalescing): every item shares the key → the same
+      // session → the same cwd (a session's cwd is pinned), so route the whole batch to the
+      // waker selected by the first item's runtimeCwd.
+      wakeBatch: (notifications, key, attribution) =>
+        selectWaker(notifications[0]).wakeBatch(notifications, key, attribution),
       markInterrupting(entityType, entityUuid) {
         for (const candidate of runtimeWakers.values()) {
           if (candidate.executions.has(`${entityType}:${entityUuid}`)) {
@@ -345,6 +359,19 @@ export function buildDaemon(creds, deps = {}) {
       buildExecutionSnapshot: () =>
         [...runtimeWakers.values()].flatMap((candidate) => candidate.buildExecutionSnapshot()),
     };
+    // The WakeQueue serializes per DIRECT idea (keyFor's key) and coalesces same-key pending
+    // wakes into one batch (add-daemon-wake-coalescing §C1/§C4). It is PER-CONNECTION so the
+    // batch runs on THIS connection's own waker facade — the runBatch drains the per-key data
+    // items { notification, attribution } and hands the whole batch to waker.wakeBatch (all
+    // items on one key share the session anchor, so items[0].attribution is the batch
+    // attribution). maxConcurrency caps this connection's in-flight batches.
+    const queue = new WakeQueue({
+      maxConcurrency,
+      logger,
+      runBatch: (key, items) =>
+        waker.wakeBatch(items.map((i) => i.notification), key, items[0].attribution),
+    });
+
     // The router reads THIS connection's own uuid lazily (same source the control handler
     // uses) to suppress a DIRECTED (pinned) wake stamped for a different connection
     // (fix-pinned-wake-directed-delivery, T2). Null until the SSE handshake assigns it — a
@@ -364,8 +391,20 @@ export function buildDaemon(creds, deps = {}) {
     // all scoped to THIS connection's uuid/router/backfill (see the original wiring
     // comments retained on the shared helpers). The control handler verifies a control
     // event against this connection's own connectionUuid before acting.
-    const redispatchResume = (entityType, entityUuid, resumeReason, runtimeCwd) => {
-      router.dispatchResume?.({ entityType, entityUuid, resumeReason, runtimeCwd });
+    const redispatchResume = (
+      entityType,
+      entityUuid,
+      resumeReason,
+      runtimeCwd,
+      orchestrator,
+    ) => {
+      router.dispatchResume?.({
+        entityType,
+        entityUuid,
+        resumeReason,
+        runtimeCwd,
+        orchestrator,
+      });
     };
     const deliverTurn = (turnUuid) => backfill?.pendingTurnsOnly?.(turnUuid);
     const onControl = createControlHandler({
@@ -477,6 +516,7 @@ export function buildDaemon(creds, deps = {}) {
       connectionState,
       waker,
       runtimeWakers,
+      queue,
       router,
       backfill,
       sseListener,
@@ -495,9 +535,11 @@ export function buildDaemon(creds, deps = {}) {
     mcpClient,
     lineage,
     spawner,
-    queue,
     // Back-compat single-connection aliases (the common single-path case). The full
-    // set is exposed as `connections` for multi-path inspection/tests.
+    // set is exposed as `connections` for multi-path inspection/tests. The WakeQueue is
+    // now per-connection (add-daemon-wake-coalescing) so its runBatch can run on the right
+    // connection's waker facade; the primary connection's queue is aliased here.
+    queue: primary.queue,
     waker: primary.waker,
     router: primary.router,
     sseListener: primary.sseListener,
@@ -520,8 +562,10 @@ export function buildDaemon(creds, deps = {}) {
       //    and latch the queue (queued-but-unstarted wakes never spawn).
       for (const c of connections) {
         c.sseListener.disconnect?.();
+        // Latch each connection's OWN queue (queues are per-connection now — add-daemon-
+        // wake-coalescing) so queued-but-unstarted wakes never spawn.
+        c.queue?.stop?.();
       }
-      queue.stop();
       // 2. Interrupt every in-flight wake subprocess via the shared kill escalation.
       //    Each wake's exit path — seeing shuttingDown — reports its turn
       //    interrupted(shutdown) and suppresses the execution crash report.
@@ -532,7 +576,11 @@ export function buildDaemon(creds, deps = {}) {
       //    the kill escalation window plus a hard 5s cap for the exit path's REST
       //    reports. A wake that outlives this does NOT hang the shutdown — its
       //    orphaned turn is the server-side offline reconcile's job (the backstop).
-      const drained = await queue.drain(sigintTimeoutMs + 5_000);
+      //    Drain every connection's queue in parallel; `drained` is true only if all did.
+      const drainResults = await Promise.all(
+        connections.map((c) => c.queue?.drain?.(sigintTimeoutMs + 5_000) ?? true),
+      );
+      const drained = drainResults.every(Boolean);
       if (!drained) {
         logger.warn(
           "[Chorus] shutdown: in-flight wake(s) did not finish within the bound — exiting anyway (server reconcile will finalize their turns)",
@@ -544,6 +592,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 +814,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

package/cli/event-router.mjs

@@ -37,8 +37,8 @@ export class EventRouter {
   /**
    * @param {{
    *   mcpClient: { callTool: (name: string, args?: Record<string, unknown>) => Promise<any> },
-   *   waker: { keyFor: (n: any) => Promise<{ key: string, rootIdeaUuid: string|null, directIdeaUuid: string|null }>, wake: (n: any, key: string, attribution?: any) => Promise<void>, markQueued?: (n: any, key: string, attribution?: any) => void },
-   *   queue: { enqueue: (key: string, task: () => Promise<void>) => void },
+   *   waker: { keyFor: (n: any) => Promise<{ key: string, rootIdeaUuid: string|null, directIdeaUuid: string|null }>, wakeBatch: (ns: any[], key: string, attribution?: any) => Promise<void>, markQueued?: (n: any, key: string, attribution?: any) => void },
+   *   queue: { enqueue: (key: string, item: { notification: any, attribution: any }) => void },
    *   wakeActions: Set<string>,
    *   getConnectionUuid?: () => (string|null),  This daemon's registered connection uuid
    *                                             (null until the SSE handshake reports it).
@@ -228,7 +228,8 @@ export class EventRouter {
    * reason ("user" | "crash") threaded from the control event; it is stamped on the
    * synthetic notification as `resumedFrom` so the prompt builder can state a crash
    * explicitly. Absent/unknown → not stamped → the user-resume prompt.
-   * @param {{ entityType?: string, entityUuid?: string, resumeReason?: string }} target
+   * @param {{ entityType?: string, entityUuid?: string, resumeReason?: string,
+   *   orchestrator?: { type?: string, uuid?: string, name?: string } | null }} target
    */
   dispatchResume(target) {
     const entityType = target?.entityType;
@@ -247,6 +248,11 @@ export class EventRouter {
       entityUuid,
       ...(resumedFrom ? { resumedFrom } : {}),
       ...(typeof target?.runtimeCwd === "string" ? { runtimeCwd: target.runtimeCwd } : {}),
+      ...(target?.orchestrator?.type === "agent" &&
+      typeof target.orchestrator.uuid === "string" &&
+      typeof target.orchestrator.name === "string"
+        ? { orchestrator: target.orchestrator }
+        : {}),
     };
     this.#resolveAndEnqueue(n, `resume:${entityType}:${entityUuid}`).catch((err) => {
       this.logger.error(`[Chorus] failed to dispatch resume for ${entityType}:${entityUuid}: ${err}`);
@@ -383,7 +389,10 @@ export class EventRouter {
     } catch (err) {
       this.logger.warn(`[Chorus] markQueued failed for pending turn ${turnUuid}: ${err}`);
     }
-    this.queue.enqueue(key, () => this.waker.wake(n, key, attribution));
+    // Enqueue an opaque DATA payload (add-daemon-wake-coalescing §C4), NOT a thunk: the
+    // queue coalesces all same-key pending items and hands the whole batch to its runBatch
+    // (wired to waker.wakeBatch in daemon.mjs). markQueued was already called per-item above.
+    this.queue.enqueue(key, { notification: n, attribution });
   }
 
   /**
@@ -531,6 +540,9 @@ export class EventRouter {
     } catch (err) {
       this.logger.warn(`[Chorus] markQueued failed for ${label}: ${err}`);
     }
-    this.queue.enqueue(key, () => this.waker.wake(n, key, attribution));
+    // Enqueue an opaque DATA payload (add-daemon-wake-coalescing §C4), NOT a thunk: the
+    // queue coalesces all same-key pending items and hands the whole batch to its runBatch
+    // (wired to waker.wakeBatch in daemon.mjs). markQueued was already called per-item above.
+    this.queue.enqueue(key, { notification: n, attribution });
   }
 }

package/cli/login.mjs

@@ -144,15 +144,86 @@ export function recordYoloAck(yoloAckAt, deps = {}) {
   return updateDaemonConfig({ yoloAckAt }, deps);
 }
 
+/** A non-empty trimmed string, or undefined. */
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Append a new agent to `~/.chorus/daemon.json`'s `agents[]` (daemon-multi-agent),
+ * via the same field-merge writer, WITHOUT overwriting any existing agent.
+ *
+ * Migration rule: if the file is still a flat single-agent config (top-level
+ * `apiKey`, no `agents[]`), the flat fields are first folded into `agents[0]` so
+ * the newly added key becomes `agents[1]` — the result is unambiguous (once
+ * `agents[]` exists, the flat top-level fields serve only as defaults, never as a
+ * standalone agent). Duplicate protection: if the new `apiKey` already matches an
+ * existing agent (or the pre-migration flat key), nothing is written.
+ *
+ * @param {{ url?: string, apiKey: string, agentType?: string, agentUuid?: string, agentName?: string }} agentObj
+ * @param {{ path?: string, 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 {{ ok: true, path: string, agents: object[], index: number } | { ok: false, reason: "duplicate" }}
+ */
+export function appendAgentConfig(agentObj, deps = {}) {
+  const path = deps.path ?? loginFilePath();
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+
+  let current = {};
+  try {
+    const parsed = JSON.parse(read(path));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) current = parsed;
+  } catch {
+    // treat as empty
+  }
+
+  const existingAgents =
+    Array.isArray(current.agents) ? current.agents.filter((a) => a && typeof a === "object") : [];
+
+  /** @type {object[]} */
+  let agents;
+  if (existingAgents.length > 0) {
+    agents = existingAgents.slice();
+  } else if (nonEmpty(current.apiKey)) {
+    // Migrate the flat single-agent config into agents[0] so the new key is agents[1].
+    const flat = { apiKey: current.apiKey };
+    if (nonEmpty(current.url)) flat.url = current.url;
+    if (nonEmpty(current.agent)) flat.agentType = current.agent;
+    if (Array.isArray(current.cwds)) flat.cwds = current.cwds;
+    if (nonEmpty(current.agentName)) flat.agentName = current.agentName;
+    if (nonEmpty(current.agentUuid)) flat.agentUuid = current.agentUuid;
+    agents = [flat];
+  } else {
+    agents = [];
+  }
+
+  // Never add a duplicate: refuse if this apiKey already backs an agent (checking
+  // both the agents[] entries and any pre-migration flat top-level key).
+  const existingKeys = new Set(agents.map((a) => a.apiKey).filter(Boolean));
+  if (nonEmpty(current.apiKey)) existingKeys.add(current.apiKey);
+  if (existingKeys.has(agentObj.apiKey)) {
+    return { ok: false, reason: "duplicate" };
+  }
+
+  agents.push(agentObj);
+  const writtenPath = updateDaemonConfig({ agents }, deps);
+  return { ok: true, path: writtenPath, agents, index: agents.length - 1 };
+}
+
 /**
  * Run the login flow: collect url + key (flags or interactive), validate
  * against the server, and on success persist + echo identity. Returns an exit
  * code (0 success, non-zero failure). Never throws.
  *
- * @param {{ url?: string, apiKey?: string }} flags
+ * With `flags.add`, the validated key is APPENDED as an additional agent
+ * (daemon-multi-agent) via {@link appendAgentConfig} instead of overwriting the
+ * single flat credential — so one daemon can serve several agents. On an invalid
+ * key, or a duplicate, nothing is written.
+ *
+ * @param {{ url?: string, apiKey?: string, agent?: string, add?: boolean }} flags
  * @param {{
  *   validate?: typeof validateAndFetchIdentity,
  *   write?: typeof writeLoginFile,
+ *   appendAgent?: typeof appendAgentConfig,
  *   prompt?: typeof prompt,
  *   log?: (m: string) => void,
  *   errLog?: (m: string) => void,
@@ -162,6 +233,7 @@ export function recordYoloAck(yoloAckAt, deps = {}) {
 export async function runLogin(flags = {}, deps = {}) {
   const validate = deps.validate ?? validateAndFetchIdentity;
   const write = deps.write ?? writeLoginFile;
+  const appendAgent = deps.appendAgent ?? appendAgentConfig;
   const ask = deps.prompt ?? prompt;
   const log = deps.log ?? ((m) => process.stdout.write(m + "\n"));
   const errLog = deps.errLog ?? ((m) => process.stderr.write(m + "\n"));
@@ -183,10 +255,26 @@ export async function runLogin(flags = {}, deps = {}) {
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     errLog(`Login failed: ${msg}`);
-    errLog("Credentials were NOT saved.");
+    errLog(flags.add ? "No agent was added." : "Credentials were NOT saved.");
     return 1;
   }
 
+  // --add: append as an additional agent (multi-agent) instead of overwriting.
+  if (flags.add) {
+    const agentObj = { url, apiKey, agentUuid: identity.uuid, agentName: identity.name };
+    if (nonEmpty(flags.agent)) agentObj.agentType = nonEmpty(flags.agent);
+    const res = appendAgent(agentObj);
+    if (!res.ok) {
+      errLog(
+        `Agent ${identity.name} (${identity.uuid}) is already configured (same API key) — nothing changed.`,
+      );
+      return 1;
+    }
+    log(`Added agent ${identity.name} (${identity.uuid}) as agents[${res.index}] in ${res.path}.`);
+    log(`This daemon now serves ${res.agents.length} agent(s).`);
+    return 0;
+  }
+
   const path = write({ url, apiKey, agentUuid: identity.uuid, agentName: identity.name });
   log(`Logged in as ${identity.name} (${identity.uuid}).`);
   log(`Credentials saved to ${path}.`);