@chorus-aidlc/chorus 0.16.4 → 0.17.1

package/cli/agents.mjs

@@ -0,0 +1,329 @@
+// cli/agents.mjs
+// `chorus agents` — manage this machine's configured agents (the ~/.chorus/daemon.json
+// agents[]): `list` (default), `add` (detect + install plugin + seed creds — the flow
+// formerly reached via `chorus init`, delegated to runInit), and `remove <name|uuid>`.
+// Listing lets a user/agent discover the valid `CHORUS_AGENT_PROFILE` /
+// `chorus mcp --agent <name|uuid>` values without hand-reading the JSON. The `cho_`
+// API key is NEVER emitted by list/remove — not masked, omitted entirely.
+//
+// Peer of the other `chorus` subcommands (login / daemon / mcp); dispatched from
+// chorus.mjs before the server boot path, so every `chorus agents …` help/list/remove
+// path never starts the embedded PostgreSQL.
+
+import { readFileSync } from "node:fs";
+import { loginFilePath } from "./credentials.mjs";
+import { updateDaemonConfig } from "./login.mjs";
+
+/** Read + parse a JSON file, returning null on any error (missing/malformed). */
+function readJsonSafe(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A non-empty trimmed string, or undefined. */
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/** Compact host for the table (host[:port] only — never userinfo); never throws. */
+function hostOf(url) {
+  if (!url) return "";
+  try {
+    return new URL(url).host;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Safe url for machine (--json) output: the origin only (scheme://host[:port]).
+ * Strips any userinfo / path / query so an accidental credential embedded in the
+ * url can never surface. Returns null when absent or unparseable (never echoes
+ * the raw string). Defense-in-depth — the stored API key lives in a separate
+ * `apiKey` field this command never reads.
+ */
+function originOf(url) {
+  if (!url) return null;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+/** Group help for `chorus agents` (list / add / remove). */
+export function agentsHelpText(version = "") {
+  const v = version ? ` v${version}` : "";
+  return `\
+Chorus${v} — manage this machine's configured agents
+
+USAGE
+  chorus agents [list]              List configured agents (name, UUID, backend)
+  chorus agents --json              Machine-readable list (API keys never included)
+  chorus agents add [flags]         Configure agent(s): detect, install plugin, seed
+                                    credentials (formerly \`chorus init\`; same flags —
+                                    see \`chorus agents add --help\`)
+  chorus agents remove <name|uuid>  Remove a configured agent from ~/.chorus/daemon.json
+
+Each listed UUID or name is a valid value for \`chorus mcp --agent <name|uuid>\` or the
+CHORUS_AGENT_PROFILE environment variable. The API key is never printed.
+`;
+}
+
+/**
+ * Build the redacted agent rows from a parsed daemon.json object.
+ * @param {Record<string, unknown>|null} file
+ * @returns {Array<{index:number, name?:string, uuid?:string, agentType?:string, url?:string, daemonWake?:unknown, flat?:boolean}>}
+ */
+export function collectAgents(file) {
+  if (!file) return [];
+  const rows = [];
+  if (Array.isArray(file.agents)) {
+    file.agents.forEach((a, i) => {
+      if (a && typeof a === "object") {
+        rows.push({
+          index: i,
+          name: nonEmpty(a.agentName) ?? nonEmpty(a.name) ?? nonEmpty(a.label),
+          uuid: nonEmpty(a.agentUuid),
+          agentType: nonEmpty(a.agentType),
+          url: nonEmpty(a.url) ?? nonEmpty(file.url),
+          daemonWake: a.daemonWake,
+        });
+      }
+    });
+  }
+  // Flat single-agent config (no agents[]): synthesize one row from the
+  // deprecated top-level fields so it still shows up.
+  if (rows.length === 0 && (nonEmpty(file.apiKey) || nonEmpty(file.agentUuid))) {
+    rows.push({
+      index: 0,
+      name: nonEmpty(file.agentName),
+      uuid: nonEmpty(file.agentUuid),
+      agentType: nonEmpty(file.agent),
+      url: nonEmpty(file.url),
+      flat: true,
+    });
+  }
+  return rows;
+}
+
+/**
+ * List configured agents (the `chorus agents` / `chorus agents list` body).
+ * Returns an exit code (never calls process.exit).
+ * @param {string[]} argv  flags after the (optional) `list` sub-verb.
+ * @param {object} [opts]
+ * @returns {number}
+ */
+function listAgents(argv = [], opts = {}) {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const env = opts.env ?? process.env;
+  const readJson = opts.readJson ?? readJsonSafe;
+  const loginPath = opts.loginPath ?? loginFilePath();
+  const version = opts.version ?? "";
+
+  let json = false;
+  for (const tok of argv) {
+    if (tok === "--help" || tok === "-h") {
+      out.write(agentsHelpText(version));
+      return 0;
+    }
+    if (tok === "--json") {
+      json = true;
+      continue;
+    }
+    err.write(`error: unknown flag: ${tok}\n\n${agentsHelpText(version)}`);
+    return 2;
+  }
+
+  const rows = collectAgents(readJson(loginPath));
+  const active = nonEmpty(env.CHORUS_AGENT_PROFILE);
+  const isActive = (r) => active !== undefined && (r.uuid === active || r.name === active);
+
+  if (json) {
+    // Redacted objects — the apiKey is intentionally never included.
+    const payload = rows.map((r) => ({
+      index: r.index,
+      name: r.name ?? null,
+      uuid: r.uuid ?? null,
+      agentType: r.agentType ?? null,
+      url: originOf(r.url),
+      daemonWake: r.daemonWake ?? null,
+      active: isActive(r),
+    }));
+    out.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return 0;
+  }
+
+  if (rows.length === 0) {
+    out.write(
+      `No agents configured in ${loginPath}.\n` +
+        "Run `chorus agents add` (or `chorus login`) to add one.\n",
+    );
+    return 0;
+  }
+
+  out.write(`Agents in ${loginPath}:\n`);
+  for (const r of rows) {
+    const mark = isActive(r) ? "* " : "  ";
+    const name = r.name ?? "(unnamed)";
+    const uuid = r.uuid ?? "(no uuid)";
+    const bits = [r.agentType ?? "?"];
+    if (r.daemonWake === false) bits.push("wake:off");
+    const host = hostOf(r.url);
+    if (host) bits.push(host);
+    out.write(`${mark}[${r.index}] ${name}  ${uuid}  (${bits.join(", ")})\n`);
+  }
+  if (active) {
+    out.write(
+      rows.some(isActive)
+        ? `\n* = active (CHORUS_AGENT_PROFILE="${active}")\n`
+        : `\n(note: CHORUS_AGENT_PROFILE="${active}" is set but matches no agent above)\n`,
+    );
+  }
+  out.write(
+    "\nPass a UUID or name to `chorus mcp --agent <name|uuid>` or set CHORUS_AGENT_PROFILE.\n" +
+      "API keys are never shown.\n",
+  );
+  return 0;
+}
+
+/** Usage for `chorus agents remove`. */
+function removeHelpText() {
+  return "USAGE\n  chorus agents remove <name|uuid>   Remove a configured agent from ~/.chorus/daemon.json\n";
+}
+
+/**
+ * `chorus agents remove <name|uuid>` — drop the matching `agents[]` entry.
+ * Merge-safe: rewrites daemon.json replacing `agents[]` with the filtered array,
+ * preserving every other agent and all top-level fields. The API key is NEVER
+ * printed. dependency-injected (readJson/writeConfig/loginPath) for tests.
+ * @param {string[]} argv  args after the `remove` word (argv[0] = target).
+ * @param {object} [opts]
+ * @returns {number}
+ */
+export function removeAgent(argv = [], opts = {}) {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const readJson = opts.readJson ?? readJsonSafe;
+  const loginPath = opts.loginPath ?? loginFilePath();
+  const writeConfig = opts.writeConfig ?? ((partial) => updateDaemonConfig(partial, { path: loginPath }));
+
+  const first = argv[0];
+  if (first === "--help" || first === "-h") {
+    out.write(removeHelpText());
+    return 0;
+  }
+  const target = nonEmpty(first);
+  if (!target) {
+    err.write("error: `chorus agents remove` requires an agent name or UUID.\n" + removeHelpText());
+    return 2;
+  }
+
+  const file = readJson(loginPath);
+  const agents = file && Array.isArray(file.agents) ? file.agents.filter((a) => a && typeof a === "object") : [];
+  const keysOf = (a) => [a.agentUuid, a.agentName, a.label, a.name].map(nonEmpty).filter((k) => k !== undefined);
+  const matches = [];
+  agents.forEach((a, i) => {
+    if (keysOf(a).includes(target)) matches.push(i);
+  });
+
+  if (matches.length === 0) {
+    err.write(`error: no configured agent matches "${target}" in ${loginPath}.\n`);
+    if (agents.length) {
+      err.write("Configured agents:\n");
+      agents.forEach((a, i) =>
+        err.write(`  [${i}] ${nonEmpty(a.agentName) ?? "(unnamed)"}  ${nonEmpty(a.agentUuid) ?? "(no uuid)"}\n`),
+      );
+    } else {
+      err.write("(none configured)\n");
+    }
+    return 1;
+  }
+  if (matches.length > 1) {
+    err.write(
+      `error: "${target}" is ambiguous — it matches ${matches.length} agents. Use the agent UUID to disambiguate.\n`,
+    );
+    return 2;
+  }
+
+  const idx = matches[0];
+  const removed = agents[idx];
+  const remaining = agents.filter((_, i) => i !== idx);
+  // Replace agents[] wholesale (updateDaemonConfig shallow-merges the patch, so a
+  // new `agents` array overwrites the old one) — preserves every top-level field.
+  writeConfig({ agents: remaining });
+
+  out.write(
+    `Removed agent ${nonEmpty(removed.agentName) ?? "(unnamed)"} (${nonEmpty(removed.agentUuid) ?? "no uuid"}) ` +
+      `from ${loginPath}. ${remaining.length} agent(s) remain.\n`,
+  );
+  // dsh: $DSH_HOME/.env holds a single shared url+key (not per-agent) and is left
+  // untouched. dsh maps to the "offline" daemon agentType bucket — surface the note there.
+  if (nonEmpty(removed.agentType) === "offline") {
+    out.write(
+      "Note: any dsh $DSH_HOME/.env credentials were left untouched (a single shared file) — clear them manually if needed.\n",
+    );
+  }
+  // Claude Code: `chorus agents add` may have written CHORUS_* into the user-global
+  // ~/.claude/settings.json env block. Reverse cleanup is out of scope — leave it in place
+  // (a later re-add overwrites it idempotently) but tell the operator, mirroring the dsh note.
+  if (nonEmpty(removed.agentType) === "claude-code") {
+    out.write(
+      "Note: any CHORUS_* keys written into ~/.claude/settings.json were left untouched — clear them manually if needed.\n",
+    );
+  }
+  // Codex: `chorus agents add` may have written CHORUS_* into ~/.codex/.env (and a keyless
+  // [mcp_servers.chorus] block that references CHORUS_API_KEY via bearer_token_env_var in
+  // ~/.codex/config.toml — no literal key). Reverse cleanup is out of scope — leave it, tell the operator.
+  if (nonEmpty(removed.agentType) === "codex") {
+    out.write(
+      "Note: any CHORUS_* env written into ~/.codex/.env " +
+        "(and the keyless [mcp_servers.chorus] block in ~/.codex/config.toml, which references the key via bearer_token_env_var) were left untouched — clear them manually if needed.\n",
+    );
+  }
+  return 0;
+}
+
+/**
+ * Run `chorus agents [list|add|remove] …`. Dispatches the sub-verb:
+ *   (none) / `list`   → list configured agents
+ *   `add [flags]`     → runInit (the flow formerly reached via `chorus init`)
+ *   `remove <n|uuid>` → removeAgent
+ * A group-level `--help`/`-h` prints the group usage. Never boots the server.
+ * Returns an exit code (or a Promise thereof for `add`).
+ * @param {string[]} argv  argv AFTER the `agents` word.
+ * @param {object} [opts]
+ * @returns {number | Promise<number>}
+ */
+export function runAgents(argv = [], opts = {}) {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const version = opts.version ?? "";
+  const first = argv[0];
+
+  if (first === "--help" || first === "-h") {
+    out.write(agentsHelpText(version));
+    return 0;
+  }
+  if (first === "add") {
+    // Delegate to the existing init flow (renamed entry). Dynamic import keeps the
+    // list/remove paths from loading the heavier init subsystem.
+    const runInit = opts.runInit ?? (async (a, o) => (await import("./init.mjs")).runInit(a, o));
+    return runInit(argv.slice(1), { version });
+  }
+  if (first === "remove") {
+    return removeAgent(argv.slice(1), opts);
+  }
+  // An unknown positional sub-verb (not `list`, not a flag) is a usage error.
+  if (first !== undefined && first !== "list" && !first.startsWith("-")) {
+    err.write(`error: unknown \`chorus agents\` subcommand: ${first}\n\n${agentsHelpText(version)}`);
+    return 2;
+  }
+  // Bare `chorus agents`, explicit `list`, or list flags (--json/--help handled inside).
+  return listAgents(first === "list" ? argv.slice(1) : argv, opts);
+}

package/cli/chorus-client.mjs

@@ -76,6 +76,56 @@ export class ChorusClient {
     }
   }
 
+  /**
+   * Like {@link callTool} but returns the tool result's text content VERBATIM,
+   * never JSON-parsed — the byte-faithful form the `chorus mcp call` CLI prints
+   * to stay a drop-in for `chorus-api.sh mcp-tool` (which emits
+   * `.result.content[].text`). `text` is the newline-join of every `content[]`
+   * block whose `type` is `text`. Lazy-connects; retries once on a stateless
+   * 404 / session-expired error, mirroring {@link callTool}.
+   * @param {string} name
+   * @param {Record<string, unknown>} [args]
+   * @returns {Promise<{ isError: boolean, text: string }>}
+   */
+  async callToolRaw(name, args = {}) {
+    if (!this.client || this.status !== "connected") await this.connect();
+    try {
+      return await this.#doCallToolRaw(name, args);
+    } catch (err) {
+      if (this.#isSessionExpired(err)) {
+        this.logger.warn("MCP session expired, reconnecting...");
+        this.status = "reconnecting";
+        this.client = null;
+        this.transport = null;
+        await this.connect();
+        return await this.#doCallToolRaw(name, args);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * List the tools this connection's API key is permitted to see. Lazy-connects;
+   * retries once on a stateless 404 / session-expired error.
+   * @returns {Promise<Array<{ name: string, description: string }>>}
+   */
+  async listTools() {
+    if (!this.client || this.status !== "connected") await this.connect();
+    try {
+      return await this.#doListTools();
+    } catch (err) {
+      if (this.#isSessionExpired(err)) {
+        this.logger.warn("MCP session expired, reconnecting...");
+        this.status = "reconnecting";
+        this.client = null;
+        this.transport = null;
+        await this.connect();
+        return await this.#doListTools();
+      }
+      throw err;
+    }
+  }
+
   async disconnect() {
     if (this.client) {
       try {
@@ -89,6 +139,25 @@ export class ChorusClient {
     this.status = "disconnected";
   }
 
+  /** @param {string} name @param {Record<string, unknown>} args */
+  async #doCallToolRaw(name, args) {
+    if (!this.client) throw new Error("MCP client not connected");
+    const result = await this.client.callTool({ name, arguments: args });
+    const blocks = /** @type {Array<{type:string,text?:string}>} */ (result.content ?? []);
+    const text = blocks
+      .filter((c) => c.type === "text")
+      .map((c) => c.text ?? "")
+      .join("\n");
+    return { isError: Boolean(result.isError), text };
+  }
+
+  async #doListTools() {
+    if (!this.client) throw new Error("MCP client not connected");
+    const result = await this.client.listTools();
+    const tools = /** @type {Array<{name:string,description?:string}>} */ (result.tools ?? []);
+    return tools.map((t) => ({ name: t.name, description: t.description ?? "" }));
+  }
+
   /** @param {string} name @param {Record<string, unknown>} args */
   async #doCallTool(name, args) {
     if (!this.client) throw new Error("MCP client not connected");

package/cli/claude-spawner.mjs

@@ -3,7 +3,7 @@
 // engineering point of the daemon: parsing stream-json is plain JS and
 // platform-neutral; the real work is spawning, and it is all Windows.
 //
-// Verified against Claude Code CLI 2.1.177:
+// Verified against Claude Code CLI 2.1.251:
 //   • `-p/--print` + `--output-format stream-json` emits NDJSON (one JSON object
 //     per line); every line carries `session_id`.
 //   • `--session-id <uuid>` sets the session id for a fresh run, and
@@ -32,6 +32,28 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 /** Matches a canonical lowercase UUID (any version). Chorus idea uuids are v4. */
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
+/** Backend-neutral failure classification consumed by the wake orchestrator. */
+export const SESSION_CONFLICT_FAILURE = "session_conflict";
+
+const STDERR_BUFFER_LIMIT = 64 * 1024;
+const SESSION_CONFLICT_RE = /\bsession id\b[^\r\n]{0,200}\bis already in use\b/i;
+const CLAUDE_PROJECT_KEY_CAP = 200;
+
+/**
+ * Claude Code 2.1.251's Java-style signed 32-bit string hash, rendered as the
+ * absolute value in base36. Iterating by index intentionally hashes UTF-16 code
+ * units (including each surrogate in an astral character) rather than code points.
+ * @param {string} value
+ * @returns {string}
+ */
+function projectKeyHash(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = ((hash << 5) - hash + value.charCodeAt(index)) | 0;
+  }
+  return Math.abs(hash).toString(36);
+}
+
 /**
  * True iff `id` is a well-formed, lowercase UUID. The daemon anchors the Claude
  * session id on a Chorus idea uuid (already lowercase v4); we validate before
@@ -45,22 +67,27 @@ export function isValidSessionId(id) {
 }
 
 /**
- * Claude Code's transcript directory for a working directory. Verified against the
- * live install: claude escapes the ABSOLUTE cwd by replacing both `/` and `.` with
- * `-` (e.g. `/home/u/dev/ai-pm` → `-home-u-dev-ai-pm`,
- * `/home/u/.cfg/x` → `-home-u--cfg-x`). On Windows the separators/drive differ, so
- * we escape backslashes and colons too; the rule there is best-effort and must be
- * re-verified against a Windows claude before claiming Windows resume support.
+ * Claude Code's transcript directory for a working directory. Verified against
+ * Claude Code 2.1.251's live Linux install and on-disk transcripts: every
+ * non-ASCII-alphanumeric UTF-16 code unit becomes `-`. That includes separators,
+ * dots, spaces, underscores, and non-ASCII characters; existing hyphens remain
+ * byte-identical because replacing `-` with `-` is a no-op. Escaped keys longer
+ * than 200 characters use the first 200 characters plus `-` and the base36
+ * Java-style signed 32-bit hash of the original cwd. The same expression produces
+ * the established Windows fixture, though the Windows on-disk layout remains
+ * best-effort until verified on a Windows Claude installation.
  * @param {string} cwd  Absolute working directory.
  * @param {NodeJS.Platform} [platform]
  * @returns {string}
  */
 export function escapeCwd(cwd, platform = process.platform) {
-  // Replace path separators and dots with `-`. On POSIX that's `/` and `.`; on
-  // Windows also `\` and the drive-colon. Collapsing both `/` and `.` is what
-  // produces the verified double-dash on a leading-dot segment.
-  const re = platform === "win32" ? /[\\/.:]/g : /[/.]/g;
-  return cwd.replace(re, "-");
+  // `platform` remains in the signature for fixture/API compatibility. Claude's
+  // observed sanitizer is platform-independent; platform path syntax supplies
+  // the differing separator/drive characters that this expression normalizes.
+  void platform;
+  const escaped = cwd.replace(/[^a-zA-Z0-9]/g, "-");
+  if (escaped.length <= CLAUDE_PROJECT_KEY_CAP) return escaped;
+  return `${escaped.slice(0, CLAUDE_PROJECT_KEY_CAP)}-${projectKeyHash(cwd)}`;
 }
 
 /**
@@ -284,7 +311,8 @@ 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, backendSessionId: string|null, exitCode: number|null, isNew: boolean }>}
+   * @returns {Promise<{ sessionId: string, backendSessionId: string|null, exitCode: number|null, isNew: boolean,
+   *                     failureClassification?: "session_conflict" }>}
    *   `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
@@ -329,6 +357,10 @@ export class ClaudeSpawner {
     if (this.creds) {
       if (this.creds.url) childEnv.CHORUS_URL = this.creds.url;
       if (this.creds.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
+      // Identity profile for the woken session — its hooks/skills pass this to
+      // `chorus mcp --agent`, which resolves the key from ~/.chorus/daemon.json.
+      if (this.creds.agentUuid || this.creds.agentName)
+        childEnv.CHORUS_AGENT_PROFILE = this.creds.agentUuid || this.creds.agentName;
     }
 
     return new Promise((resolve) => {
@@ -365,6 +397,8 @@ export class ClaudeSpawner {
       }
 
       let stdoutBuf = "";
+      let stderrBuf = "";
+      let sessionConflictSeen = false;
       let observedSessionId = id;
 
       child.stdout?.setEncoding?.("utf8");
@@ -388,7 +422,10 @@ export class ClaudeSpawner {
 
       child.stderr?.setEncoding?.("utf8");
       child.stderr?.on("data", (chunk) => {
-        const text = String(chunk).trim();
+        const rawText = String(chunk);
+        stderrBuf = (stderrBuf + rawText).slice(-STDERR_BUFFER_LIMIT);
+        if (SESSION_CONFLICT_RE.test(stderrBuf)) sessionConflictSeen = true;
+        const text = rawText.trim();
         if (text) this.logger.warn(`[Chorus] claude stderr: ${text}`);
       });
 
@@ -407,7 +444,11 @@ export class ClaudeSpawner {
         }
         // 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 });
+        const result = { sessionId: observedSessionId, backendSessionId: id, exitCode: code, isNew };
+        if (code !== null && code !== 0 && sessionConflictSeen) {
+          result.failureClassification = SESSION_CONFLICT_FAILURE;
+        }
+        resolve(result);
       });
 
       // Guard against an ASYNC stdin error (EPIPE): if claude exits/closes

package/cli/codex-spawner.mjs

@@ -14,12 +14,13 @@
 //     `resume <thread_id>`. (serde: ThreadEvent tag="type", rename="thread.started";
 //     ThreadStartedEvent.thread_id: String — codex-rs/exec/src/exec_events.rs.)
 //   • 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.)
+//     `chorus agents add` writes [mcp_servers.chorus] with bearer_token_env_var =
+//     "CHORUS_API_KEY" — a KEYLESS reference (no literal key in config.toml), and Codex
+//     resolves that env var into `Authorization: Bearer <key>` at connect. So the
+//     CHORUS_API_KEY the daemon exports into the child env below DOES reach Codex's MCP
+//     auth (as well as the plugin's shell tooling — chorus-api.sh / SessionStart hooks);
+//     never argv. (Multi-agent: two Codex agents with different keys each need their own
+//     CODEX_HOME so their config.toml + ~/.codex/.env don't collide.)
 //   • Permission is a SANDBOX mode, not a tool allowlist.
 //
 // Reuses claude-spawner's platform-neutral helpers: parseNdjsonChunk (NDJSON
@@ -276,6 +277,10 @@ export class CodexSpawner {
     if (this.creds) {
       if (this.creds.url) childEnv.CHORUS_URL = this.creds.url;
       if (this.creds.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
+      // Identity profile for the woken session — its hooks/skills pass this to
+      // `chorus mcp --agent`, which resolves the key from ~/.chorus/daemon.json.
+      if (this.creds.agentUuid || this.creds.agentName)
+        childEnv.CHORUS_AGENT_PROFILE = this.creds.agentUuid || this.creds.agentName;
     }
 
     return new Promise((resolve) => {