@chorus-aidlc/chorus 0.11.1 → 0.12.1

package/cli/codex-spawner.mjs

@@ -0,0 +1,312 @@
+// cli/codex-spawner.mjs
+// Cross-platform headless Codex spawner — the `codex` counterpart to
+// ClaudeSpawner, satisfying the SAME backend-agnostic Spawner.wake(...) contract
+// so the daemon's wake pipeline (queue, waker, directed delivery, headless guard,
+// reporters) stays backend-neutral.
+//
+// Codex diverges structurally from Claude (verified against codex-cli 0.142.3 +
+// the ../codex source + a live `codex exec --json` run):
+//   • `codex exec --json` emits JSONL (one event per line); the prompt is read
+//     from STDIN (never argv). `codex exec resume <id> --json` continues a run.
+//   • The FIRST event is `{"type":"thread.started","thread_id":"<uuid>"}` — Codex
+//     GENERATES its own id (it does NOT accept a client `--session-id`). We capture
+//     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
+//     key reaches it via the configured bearer_token_env_var (default
+//     CHORUS_API_KEY) exported into the child ENV — never argv.
+//   • Permission is a SANDBOX mode, not a tool allowlist.
+//
+// Reuses claude-spawner's platform-neutral helpers: parseNdjsonChunk (NDJSON
+// stream parse) and the PATH-walk shape of resolveClaudePath.
+
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { win32 as pathWin32, posix as pathPosix } from "node:path";
+import { parseNdjsonChunk } from "./claude-spawner.mjs";
+import { getThreadId as defaultGetThreadId, setThreadId as defaultSetThreadId } from "./codex-session-map.mjs";
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+
+/**
+ * @typedef {Object} Spawner
+ * @property {(params: {
+ *   prompt: string, sessionId: string|null, isNew: boolean,
+ *   mcpConfigPath?: string, cwd?: string,
+ *   onMessage?: (obj: any) => void,
+ *   onChild?: (child: import("node:child_process").ChildProcess) => void
+ * }) => Promise<{ sessionId: string, exitCode: number|null, isNew: boolean }>} wake
+ *   The backend-agnostic wake contract. ClaudeSpawner and CodexSpawner both
+ *   implement it; the daemon injects one based on the resolved agent type.
+ */
+
+/**
+ * Map the daemon's backend-agnostic permission mode to a Codex sandbox posture.
+ * The expression is SUBCOMMAND-AWARE because the two surfaces differ (verified
+ * against codex 0.142.3): the top-level `codex exec` accepts `--sandbox <mode>`,
+ * but `codex exec resume` does NOT — passing `--sandbox` there errors with exit 2.
+ *   yolo   → --dangerously-bypass-approvals-and-sandbox  (valid on BOTH exec and
+ *            resume; full autonomy)
+ *   chorus → exec:   --sandbox read-only
+ *            resume: -c sandbox_mode="read-only"  (the `-c` config override is how
+ *            `codex exec resume` accepts a sandbox mode; `sandbox_mode` is a real
+ *            config key, value spelled `read-only` per protocol/src/config_types.rs,
+ *            confirmed via `--strict-config`).
+ * Anything other than yolo falls back to the restricted read-only posture.
+ * @param {"yolo"|"chorus"|undefined} permissionMode
+ * @param {{ resume?: boolean }} [opts]  resume:true selects the `codex exec resume` surface.
+ * @returns {string[]}
+ */
+export function sandboxFlags(permissionMode, opts = {}) {
+  if (permissionMode === "yolo") return ["--dangerously-bypass-approvals-and-sandbox"];
+  // restricted read-only posture, expressed per subcommand:
+  return opts.resume ? ["-c", 'sandbox_mode="read-only"'] : ["--sandbox", "read-only"];
+}
+
+/**
+ * Build the argv for a headless codex run. Prompt is NEVER here — it goes over
+ * stdin. `--skip-git-repo-check` lets a non-repo cwd still run.
+ * @param {{ isNew: boolean, threadId?: string|null, permissionMode?: "yolo"|"chorus" }} o
+ * @returns {string[]}
+ */
+export function buildCodexArgs({ isNew, threadId, permissionMode }) {
+  if (!isNew && threadId) {
+    const sandbox = sandboxFlags(permissionMode, { resume: true });
+    return ["exec", "resume", threadId, "--json", ...sandbox, "--skip-git-repo-check"];
+  }
+  const sandbox = sandboxFlags(permissionMode);
+  return ["exec", "--json", ...sandbox, "--skip-git-repo-check"];
+}
+
+/**
+ * Extract the Codex thread id from a stream event, or null. Accepts the live
+ * `thread.started` shape (authoritative) and the on-disk rollout `session_meta`
+ * shape as a defensive fallback.
+ * @param {any} obj
+ * @returns {string|null}
+ */
+export function extractThreadId(obj) {
+  if (!obj || typeof obj !== "object") return null;
+  if (obj.type === "thread.started" && typeof obj.thread_id === "string") return obj.thread_id;
+  if (obj.type === "session_meta" && obj.payload && typeof obj.payload.id === "string") {
+    return obj.payload.id;
+  }
+  return null;
+}
+
+/**
+ * Resolve the real `codex` executable WITHOUT a shell — same approach as
+ * resolveClaudePath. On Windows the bin may be `codex.cmd` (npm shim), which
+ * `spawn` can't exec directly without shell:true; we walk PATH for the platform
+ * candidates. `CHORUS_CODEX_PATH` overrides.
+ * @param {{ env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, isFile?: (p: string) => boolean }} [deps]
+ * @returns {string | null}
+ */
+export function resolveCodexPath(deps = {}) {
+  const env = deps.env ?? process.env;
+  const platform = deps.platform ?? process.platform;
+  const isFile =
+    deps.isFile ??
+    ((p) => {
+      try {
+        return statSync(p).isFile();
+      } catch {
+        return false;
+      }
+    });
+
+  if (env.CHORUS_CODEX_PATH && isFile(env.CHORUS_CODEX_PATH)) {
+    return env.CHORUS_CODEX_PATH;
+  }
+
+  const isWin = platform === "win32";
+  const p = isWin ? pathWin32 : pathPosix;
+  const names = isWin ? ["codex.cmd", "codex.exe", "codex"] : ["codex"];
+  const pathVar = env.PATH || env.Path || "";
+  const dirs = pathVar.split(p.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = p.join(dir, name);
+      if (isFile(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the actual command + argv to spawn. On Windows a `.cmd`/`.bat` shim is
+ * not a PE executable, so it must run via `cmd.exe /d /s /c <path> ...args`; we
+ * keep shell:false and pass argv as an array (no shell word-splitting/injection).
+ * @param {string} codexPath @param {string[]} args
+ * @param {NodeJS.Platform} [platform] @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ command: string, argv: string[] }}
+ */
+export function resolveSpawnCommand(codexPath, args, platform = process.platform, env = process.env) {
+  const isWin = platform === "win32";
+  const lower = codexPath.toLowerCase();
+  if (isWin && (lower.endsWith(".cmd") || lower.endsWith(".bat"))) {
+    const comspec = env.ComSpec || env.COMSPEC || "cmd.exe";
+    return { command: comspec, argv: ["/d", "/s", "/c", codexPath, ...args] };
+  }
+  return { command: codexPath, argv: args };
+}
+
+/**
+ * @typedef {Object} CodexSpawnerOptions
+ * @property {string} [codexPath]   Resolved codex path (resolved lazily if omitted).
+ * @property {(o: object) => any} [spawnImpl]   Injectable spawn (tests).
+ * @property {{info(m:string):void,warn(m:string):void,error(m:string):void}} [logger]
+ * @property {"chorus"|"yolo"} [permissionMode]  Maps to a Codex sandbox posture.
+ * @property {{ url: string, apiKey: string }} [creds]  Daemon creds — apiKey is exported
+ *   into the child env under the user config's bearer_token_env_var (default CHORUS_API_KEY).
+ * @property {NodeJS.Platform} [platform]  Injectable for tests; gates POSIX `detached`.
+ * @property {(anchor: string) => string|null} [getThreadIdFn]  Injectable session-map read.
+ * @property {(anchor: string, threadId: string) => void} [setThreadIdFn]  Injectable session-map write.
+ */
+
+export class CodexSpawner {
+  /** @param {CodexSpawnerOptions} [opts] */
+  constructor(opts = {}) {
+    this.codexPath = opts.codexPath ?? null;
+    this.spawnImpl = opts.spawnImpl ?? spawn;
+    this.logger = opts.logger ?? NOOP_LOGGER;
+    this.permissionMode = opts.permissionMode ?? "chorus";
+    this.creds = opts.creds ?? null;
+    this.platform = opts.platform ?? process.platform;
+    this.getThreadIdFn = opts.getThreadIdFn ?? defaultGetThreadId;
+    this.setThreadIdFn = opts.setThreadIdFn ?? defaultSetThreadId;
+    this.resolveCodexPathFn = opts.resolveCodexPathFn ?? resolveCodexPath;
+  }
+
+  /**
+   * Spawn a headless Codex run. Resolves when the subprocess exits. The prompt is
+   * written to stdin (never argv). `sessionId` is the Chorus anchor (direct idea
+   * uuid, or entity uuid). Codex owns its session id, so we IGNORE the passed
+   * `isNew`/`mcpConfigPath` and decide new-vs-resume from the persisted
+   * anchor→thread_id map: a recorded thread id → `resume`, otherwise a fresh run.
+   *
+   * @param {{ prompt: string, sessionId: string|null, isNew?: boolean, mcpConfigPath?: string,
+   *           cwd?: string, onMessage?: (obj: any) => void,
+   *           onChild?: (child: import("node:child_process").ChildProcess) => void }} params
+   * @returns {Promise<{ sessionId: string, exitCode: number|null, isNew: boolean }>}
+   */
+  async wake({ prompt, sessionId, cwd, onMessage, onChild }) {
+    const anchor = typeof sessionId === "string" ? sessionId : "";
+
+    // new-vs-resume is OWNED by this backend (Codex session model), not the
+    // waker's Claude transcript probe: a recorded thread id means resume.
+    const knownThreadId = anchor ? this.getThreadIdFn(anchor) : null;
+    const isNew = !knownThreadId;
+
+    const codexPath = this.codexPath ?? this.resolveCodexPathFn();
+    if (!codexPath) {
+      // No crash — surface visibly and resolve with a failure result.
+      this.logger.error("[Chorus] cannot locate the `codex` executable on PATH; skipping wake");
+      return { sessionId: anchor, exitCode: null, isNew };
+    }
+
+    const args = buildCodexArgs({ isNew, threadId: knownThreadId, permissionMode: this.permissionMode });
+    const { command, argv } = resolveSpawnCommand(codexPath, args, this.platform);
+
+    // POSIX: detached process group so the interrupt path can group-kill the tree
+    // (codex exec forks child shells for tools). Windows uses taskkill /T. stdio
+    // stays piped — prompt over stdin + NDJSON stdout parse are unaffected.
+    const detached = this.platform !== "win32";
+
+    // Daemon key via ENV under the var the user's [mcp_servers.chorus] references
+    // (bearer_token_env_var, default CHORUS_API_KEY) — NEVER argv. Merged over the
+    // inherited env so PATH / model auth (Bedrock profile) / CODEX_HOME survive.
+    const childEnv = { ...process.env, CHORUS_DAEMON_HEADLESS: "1" };
+    if (this.creds && this.creds.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
+
+    return new Promise((resolve) => {
+      let child;
+      try {
+        child = this.spawnImpl(command, argv, {
+          cwd: cwd ?? process.cwd(),
+          stdio: ["pipe", "pipe", "pipe"],
+          env: childEnv,
+          shell: false,
+          detached,
+          windowsHide: true,
+        });
+      } catch (err) {
+        this.logger.error(`[Chorus] failed to spawn codex: ${err}`);
+        resolve({ sessionId: anchor, exitCode: null, isNew });
+        return;
+      }
+
+      // Hand the live child to the caller (interrupt registry) before resolving.
+      // Never let a throwing callback escape into the spawn path.
+      if (onChild) {
+        try {
+          onChild(child);
+        } catch (err) {
+          this.logger.warn(`[Chorus] onChild handler threw: ${err}`);
+        }
+      }
+
+      let stdoutBuf = "";
+      let observedThreadId = knownThreadId || null;
+
+      child.stdout?.setEncoding?.("utf8");
+      child.stdout?.on("data", (chunk) => {
+        stdoutBuf = parseNdjsonChunk(
+          stdoutBuf,
+          String(chunk),
+          (obj) => {
+            const tid = extractThreadId(obj);
+            if (tid) observedThreadId = tid;
+            if (onMessage) {
+              try {
+                onMessage(obj);
+              } catch (err) {
+                this.logger.warn(`[Chorus] onMessage handler threw: ${err}`);
+              }
+            }
+          },
+          (msg) => this.logger.warn(`[Chorus] ${msg}`)
+        );
+      });
+
+      child.stderr?.setEncoding?.("utf8");
+      child.stderr?.on("data", (chunk) => {
+        const text = String(chunk).trim();
+        if (text) this.logger.warn(`[Chorus] codex stderr: ${text}`);
+      });
+
+      child.on("error", (err) => {
+        this.logger.error(`[Chorus] codex process error: ${err}`);
+        resolve({ sessionId: observedThreadId || anchor, exitCode: null, isNew });
+      });
+
+      child.on("close", (code) => {
+        if (code !== 0) {
+          this.logger.warn(`[Chorus] codex exited with code ${code}`);
+        }
+        // Persist anchor→thread_id only on a fresh, successful run that produced a
+        // new id — so a later wake for this anchor resumes it. Best-effort; the
+        // session map swallows its own IO errors.
+        if (code === 0 && isNew && anchor && observedThreadId) {
+          this.setThreadIdFn(anchor, observedThreadId);
+        }
+        resolve({ sessionId: observedThreadId || anchor, exitCode: code, isNew });
+      });
+
+      // Guard against an ASYNC stdin error (EPIPE) so it never becomes an
+      // uncaughtException that kills the daemon.
+      child.stdin?.on?.("error", (err) => {
+        this.logger.warn(`[Chorus] codex stdin error (ignored): ${err}`);
+      });
+
+      // Feed the prompt over stdin, then close it so the model runs.
+      try {
+        child.stdin?.write(prompt);
+        child.stdin?.end();
+      } catch (err) {
+        this.logger.warn(`[Chorus] failed writing prompt to codex stdin: ${err}`);
+      }
+    });
+  }
+}

package/cli/daemon-agent.mjs

@@ -1,15 +1,41 @@
 // cli/daemon-agent.mjs
-// Pure resolution + validation of the daemon's `--agent <type>` selection. The
-// flag/env exist to RESERVE the extension point for future agent backends
-// (e.g. codex); only `claude-code` is implemented in this change. Resolving an
+// Pure resolution + validation of the daemon's `--agent <type>` selection.
+// `claude-code` (the default) and `codex` are both implemented backends
+// (add-daemon-codex-backend cashed in the reserved `codex` slot). Resolving an
 // unknown value is a hard error (no silent fallback). Zero dependencies.
 
-/** The agent backends the daemon recognizes. Only `claude-code` is implemented. */
-export const KNOWN_AGENTS = ["claude-code"];
+/** The agent backends the daemon recognizes. Both are implemented (claude-code
+ * via ClaudeSpawner, codex via CodexSpawner — see spawner-select.mjs). */
+export const KNOWN_AGENTS = ["claude-code", "codex"];
 
 /** The default agent backend when neither --agent nor CHORUS_AGENT is set. */
 export const DEFAULT_AGENT = "claude-code";
 
+/**
+ * Per-backend CLI descriptor: the executable name the daemon resolves/spawns and
+ * the env var that overrides its path. Drives the startup banner's "CLI" row and
+ * the not-found warning so they name the SELECTED backend (not always `claude`).
+ * Unknown / undefined falls back to the default (claude-code) descriptor.
+ * @param {string} agentType
+ * @returns {{ name: string, envVar: string }}
+ */
+export function backendCli(agentType) {
+  if (agentType === "codex") return { name: "codex", envVar: "CHORUS_CODEX_PATH" };
+  return { name: "claude", envVar: "CHORUS_CLAUDE_PATH" };
+}
+
+/**
+ * Map the resolved agent backend to the `clientType` the daemon self-reports to
+ * the server (and that the connection registry + presence UI display). The server
+ * gates this against DAEMON_CLIENT_TYPES, so the values MUST match: `codex` →
+ * `codex`, `claude-code` → `claude_code`. Anything else falls back to claude_code.
+ * @param {string} agentType
+ * @returns {string}
+ */
+export function backendClientType(agentType) {
+  return agentType === "codex" ? "codex" : "claude_code";
+}
+
 /**
  * Resolve the agent type from flag → env → default, and validate it.
  * Precedence: explicit `--agent` flag > CHORUS_AGENT env > DEFAULT_AGENT.
@@ -31,7 +57,7 @@ export function resolveAgentType(flags, env) {
       value: raw,
       error:
         `Unknown --agent "${raw}". Accepted: ${KNOWN_AGENTS.join(", ")}. ` +
-        `(Only ${DEFAULT_AGENT} is implemented; the flag reserves the slot for future agents.)`,
+        `(Default is ${DEFAULT_AGENT}.)`,
     };
   }
   return { ok: true, agent: raw };

package/cli/daemon-banner.mjs

@@ -6,7 +6,10 @@
 //
 // SECURITY: the banner shows the credential SOURCE, never the raw API key
 // (owner decision: no masking needed because the key is simply not displayed).
-// Zero dependencies — ships in the npm package alongside chorus.mjs.
+// Zero dependencies (beyond the pure backendCli descriptor) — ships in the npm
+// package alongside chorus.mjs.
+
+import { backendCli } from "./daemon-agent.mjs";
 
 /**
  * @typedef {Object} BannerInfo
@@ -16,9 +19,11 @@
  * @property {string} agentUuid        authenticated agent uuid.
  * @property {"yolo"|"chorus"} permissionMode
  * @property {string} credentialSource resolved credential source (flag/env/login-file/…).
- * @property {string} agentType        local agent backend (e.g. claude-code).
- * @property {string|null} claudePath  resolved claude path, or null when not found.
+ * @property {string} agentType        local agent backend (claude-code | codex) — drives the CLI row label.
+ * @property {string|null} cliPath     resolved path of the SELECTED backend's CLI, or null when not found.
  * @property {string} [connection]     connection state line (default "connecting…").
+ * @property {string} [configPath]     absolute path to the daemon.json the CLI reads.
+ * @property {boolean} [configExists]  whether that daemon.json exists on disk.
  */
 
 /** Right-pad to width (banner box alignment). */
@@ -37,8 +42,13 @@ export function bannerRows(info) {
     info.permissionMode === "yolo"
       ? "YOLO ⚠  (full autonomy — Bash/write/any command)"
       : "chorus-only (Chorus MCP tools only)";
-  const claude = info.claudePath ? `found: ${info.claudePath}` : "NOT FOUND — install `claude` or set CHORUS_CLAUDE_PATH";
-  return [
+  // The CLI row names the SELECTED backend (claude-code → "claude", codex →
+  // "codex") so a `--agent codex` run never mislabels itself as claude.
+  const cli = backendCli(info.agentType);
+  const cliValue = info.cliPath
+    ? `found: ${info.cliPath}`
+    : `NOT FOUND — install \`${cli.name}\` or set ${cli.envVar}`;
+  const rows = [
     ["Version", `chorus v${info.version}`],
     ["Server", info.url],
     ["Agent", `${info.agentName} (${info.agentUuid})`],
@@ -46,8 +56,46 @@ export function bannerRows(info) {
     ["Permission", permission],
     ["Credentials", `source: ${info.credentialSource}`],
     ["Connection", info.connection ?? "connecting…"],
-    ["claude CLI", claude],
+    [`${cli.name} CLI`, cliValue],
   ];
+  // Config file row — shown only when the path is known. Tells the operator
+  // exactly which daemon.json the CLI read (and whether it exists), so a
+  // mis-located or absent config is obvious at a glance.
+  if (info.configPath) {
+    const exists = info.configExists ? "" : " (not found — using flags/env/defaults)";
+    rows.push(["Config", `${info.configPath}${exists}`]);
+  }
+  return rows;
+}
+
+/**
+ * The prominent warning shown at startup when the SELECTED backend's executable
+ * cannot be resolved. Mirrors `yoloWarningLine()`'s loud single-line style so a
+ * missing binary is visible in an unattended / systemd journal immediately,
+ * rather than only when a wake later fails. The daemon stays non-fatal — it still
+ * subscribes. Names the backend's own binary + override env var (claude /
+ * CHORUS_CLAUDE_PATH, or codex / CHORUS_CODEX_PATH).
+ * @param {string} agentType
+ * @returns {string}
+ */
+export function agentNotFoundWarningLine(agentType) {
+  const { name, envVar } = backendCli(agentType);
+  return (
+    `⚠ ${name} CLI NOT FOUND on PATH — wakes will FAIL until you install \`${name}\` ` +
+    `or set ${envVar}. For a systemd/boot service, ensure the unit's PATH ` +
+    "includes the directory holding the binary (e.g. ~/.local/bin). The daemon will " +
+    "still subscribe, but every task dispatch errors until this is fixed."
+  );
+}
+
+/**
+ * Back-compat alias — the original claude-only warning. Delegates to
+ * {@link agentNotFoundWarningLine} for the default claude-code backend so older
+ * imports keep working.
+ * @returns {string}
+ */
+export function claudeNotFoundWarningLine() {
+  return agentNotFoundWarningLine("claude-code");
 }
 
 /**

package/cli/daemon-config.mjs

@@ -13,6 +13,8 @@
 // IO (env / file read) is injectable so this is unit-testable without real disk.
 
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve as resolvePath } from "node:path";
 import { loginFilePath } from "./credentials.mjs";
 
 /** Built-in default escalation window (ms) — matches the spec's 10 seconds. */
@@ -82,3 +84,119 @@ export function resolveSigintTimeoutMs(flags = {}, deps = {}) {
   // 4. Built-in default
   return DEFAULT_SIGINT_TIMEOUT_MS;
 }
+
+// ===== Multi-path cwd set (T3 — 单 daemon 多路径引擎, FR-5/FR-8, DEC-2) =====
+//
+// A daemon may declare a SET of local working directories (a cwd LIST) it serves.
+// Each declared path becomes one INDEPENDENT connection (own SSE self-report +
+// own Waker bound to that cwd), so the same agent on the same host driving several
+// paths registers as several distinct rows instead of one. This is JUST a set of
+// paths: per the human's cwd⟂project correction (DEC-5) it carries NO path↔project
+// binding and there is NO project→cwd routing — the daemon only declares which
+// directories it serves.
+//
+// Layered resolution, mirroring resolveSigintTimeoutMs's precedence — first defined
+// source wins (the WHOLE set comes from the first source that yields any path):
+//
+//   --cwd flag(s)  > CHORUS_DAEMON_CWDS env (comma/`os.delimiter`-separated)
+//                  > ~/.chorus/daemon.json `cwds: [...]`
+//                  > [undefined]  (single connection at the daemon's process cwd)
+//
+// The `[undefined]` fallback is the HARD-1 / single-path default: an unspecified
+// cwd set means "serve one path, the process default" — exactly today's behavior.
+// The Waker/SseListener treat an `undefined` entry as "use process.cwd()".
+
+/** Expand a leading `~` to the home dir and resolve to an absolute path. */
+function normalizeCwd(value, home) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  let expanded = trimmed;
+  if (expanded === "~") expanded = home;
+  else if (expanded.startsWith("~/")) expanded = resolvePath(home, expanded.slice(2));
+  // Resolve relative paths against the daemon's process cwd so the declared path is
+  // always absolute (claude --resume scopes transcripts to the ABSOLUTE cwd).
+  return isAbsolute(expanded) ? expanded : resolvePath(expanded);
+}
+
+/**
+ * De-duplicate a list of normalized paths preserving first-seen order, dropping
+ * blanks/undefined. Returns the cleaned array (possibly empty).
+ * @param {Array<unknown>} list @param {string} home
+ * @returns {string[]}
+ */
+function cleanCwdList(list, home) {
+  const seen = new Set();
+  const out = [];
+  for (const raw of Array.isArray(list) ? list : []) {
+    const norm = normalizeCwd(raw, home);
+    if (norm === undefined || seen.has(norm)) continue;
+    seen.add(norm);
+    out.push(norm);
+  }
+  return out;
+}
+
+/**
+ * Resolve the SET of working directories this daemon serves (FR-5). One entry per
+ * connection the daemon will register. Each entry is an absolute path, EXCEPT the
+ * single-element `[undefined]` fallback which means "serve the process default cwd"
+ * (the unspecified / single-path / HARD-1 default — identical to today's behavior).
+ *
+ * Layered precedence (first source that yields ANY path wins for the whole set):
+ *   1. flags.cwd      — a string or string[] from repeatable `--cwd` flags.
+ *   2. env            — CHORUS_DAEMON_CWDS, split on the platform path delimiter or
+ *                       a comma (whichever the user used; both are accepted).
+ *   3. login/config   — ~/.chorus/daemon.json `cwds` (array of strings).
+ *   4. default        — `[undefined]` (one connection at the process cwd).
+ *
+ * The declaration is purely a list of paths — it does NOT carry, store, or upload
+ * any path↔project binding (DEC-5: cwd ⟂ project).
+ *
+ * @param {{ cwd?: string|string[] }} [flags]  Explicit `--cwd` value(s).
+ * @param {{
+ *   env?: Record<string, string|undefined>,
+ *   readJson?: (path: string) => (Record<string, unknown>|null),
+ *   loginPath?: string,
+ *   home?: string,
+ *   delimiter?: string,
+ * }} [deps]
+ * @returns {Array<string|undefined>}  A non-empty list; `[undefined]` ⇒ process cwd.
+ */
+export function resolveDaemonCwds(flags = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const home = deps.home ?? homedir();
+  // Accept both the OS path delimiter (":" on POSIX, ";" on Windows) and a comma, so
+  // CHORUS_DAEMON_CWDS=/a:/b and CHORUS_DAEMON_CWDS=/a,/b both work cross-platform.
+  const delimiters = new RegExp(`[${deps.delimiter ?? ""},]|${process.platform === "win32" ? ";" : ":"}`);
+
+  // 1. Explicit --cwd flag(s) — a string or an array (repeatable flag).
+  const flagList = Array.isArray(flags.cwd)
+    ? flags.cwd
+    : typeof flags.cwd === "string"
+      ? [flags.cwd]
+      : [];
+  const fromFlags = cleanCwdList(flagList, home);
+  if (fromFlags.length > 0) return fromFlags;
+
+  // 2. Environment variable (delimiter- or comma-separated).
+  const envRaw = env.CHORUS_DAEMON_CWDS;
+  if (typeof envRaw === "string" && envRaw.trim()) {
+    const fromEnv = cleanCwdList(envRaw.split(delimiters), home);
+    if (fromEnv.length > 0) return fromEnv;
+  }
+
+  // 3. Login/config file (~/.chorus/daemon.json `cwds`).
+  const file = readJson(loginPath);
+  if (file && Array.isArray(file.cwds)) {
+    const fromFile = cleanCwdList(file.cwds, home);
+    if (fromFile.length > 0) return fromFile;
+  }
+
+  // 4. Built-in default: a single connection at the daemon's process cwd. `undefined`
+  //    is the "unspecified" sentinel the Waker/SseListener degrade to process.cwd()
+  //    for (HARD-1 / single-path — exactly today's behavior).
+  return [undefined];
+}