@chorus-aidlc/chorus 0.11.1 → 0.12.0

package/README.md

@@ -36,6 +36,8 @@ The labels under each stage are the **permissions** an actor needs at that stage
 
 ## What's New
 
+**[v0.12.0](https://chorus-ai.dev/blog/chorus-v0.12.0-release/)** — Addressable daemon instances: one `chorus daemon` can serve multiple working directories (`--cwd`), and each `(agent, host, cwd)` becomes an individually visible, individually targetable instance across presence, @-mention, and assignment. Pin an instance once on an idea and its proposals, tasks, and wakes inherit it; pinned wakes are delivered to exactly that instance instead of broadcast. Comment @-mentions render as live online-status badges, and comments switch to cursor-based infinite scroll.
+
 **[v0.11.0](https://chorus-ai.dev/blog/chorus-v0.11.0-release/)** — The Chorus Daemon: `chorus daemon` turns your machine into a resident agent runtime that wakes a local Claude Code on each dispatch. An Agent Connections surface gives live observability and control — streaming transcripts, instruction injection, and interrupt / resume — and a "Verify Elaborate" button wakes the assigned agent to write the proposal.
 
 **[v0.10.0](https://chorus-ai.dev/blog/chorus-v0.10.0-release/)** — Single-parent idea lineage: an idea may derive a child or be attached under another, forming a forest. The relation is intentionally weak — a parent surfaces a read-only "+N derived" rollup and does not constrain any child's elaboration, proposal, or task flow. Idea browsing consolidates onto the Dashboard (a three-way Ideas / Lineage / Stats view switch with an adaptive default); the standalone Idea List page is retired and its URLs 308-redirect to the Dashboard.
@@ -46,18 +48,6 @@ The labels under each stage are the **permissions** an actor needs at that stage
 
 **[v0.8.0](https://chorus-ai.dev/blog/chorus-v0.8.0-release/)** — OpenSpec-aware mode (Claude Code): auto-activates when an `openspec/` directory and the `openspec` CLI are both present, adds `/opsx/{explore,propose,apply,archive}` and a post-verify archive-trigger hook.
 
-**[v0.7.0](https://chorus-ai.dev/blog/chorus-v0.7.0-release/)** — Fine-grained agent permissions: 5 resources × 3 actions grid replaces the PM/Developer/Admin three-way choice, with presets + a Custom option for free combination.
-
-**[v0.6.7](https://chorus-ai.dev/blog/chorus-v0.6.7-release/)** — Chorus plugin for Codex CLI (one-command installer), workspace picker when one email belongs to multiple Companies, per-client connect guides.
-
-**[v0.6.6](https://chorus-ai.dev/blog/chorus-v0.6.6-release/)** — npm one-click install (`npx @chorus-aidlc/chorus`), document export (MD/PDF/Word), proposal revoke, faster agent checkin with work status at a glance.
-
-**[v0.6.2](https://chorus-ai.dev/blog/chorus-v0.6.2-release/)** — Embedded PGlite mode (zero-dependency deployment), structured logging with Pino, stateless MCP for horizontal scaling, default port changed to 8637.
-
-**[v0.6.1](https://chorus-ai.dev/blog/chorus-v0.6.1-release/)** — `/yolo` skill: full-auto AI-DLC pipeline (Idea → Proposal → Execute → Verify) with Agent Team parallel execution.
-
-**[v0.6.0](https://chorus-ai.dev/blog/chorus-v0.6.0-release/)** — IdeaTracker dashboard, independent review agents (proposal-reviewer + task-reviewer), real-time agent presence indicators, cross-column Kanban animation.
-
 > Full changelog: [CHANGELOG.md](CHANGELOG.md)
 
 ---
@@ -123,14 +113,58 @@ chorus daemon logs               # View daemon logs
 - **Claude Code integration** — Auto-detects `claude` CLI on your PATH
 - **Background mode** — Run with `-d` flag; manage with `stop/restart/logs`
 - **Permission modes** — Default is full access (yolo); use `--chorus-only` to restrict to Chorus MCP tools only
+- **Multi-path** — Serve several working directories from one daemon with repeatable `--cwd` (see below)
 - **Interactive setup** — Prompts for credentials on first start if not already configured
 
 The daemon requires authentication. Run `chorus login` first, or it will prompt for credentials interactively on first start (if running in a terminal).
 
+#### Serve multiple working directories
+
+One daemon can serve several local working directories at once — each declared path registers as an independent connection (its own session + wake loop) under the same agent. A path is **just** a directory the daemon serves; it carries no project binding.
+
+```bash
+chorus daemon --cwd ~/work/repo-a --cwd ~/work/repo-b   # repeatable flag
+CHORUS_DAEMON_CWDS="~/work/repo-a:~/work/repo-b" chorus daemon   # or env (`:`- or `,`-separated)
+```
+
+With no `--cwd`, the daemon serves the single directory it was launched from.
+
+#### Configuration file — `~/.chorus/daemon.json`
+
+`chorus login` writes credentials here (mode `0600`). You can also add daemon tunables to the **same** file. Every field is optional; flags and environment variables always take precedence over the file.
+
+```json
+{
+  "url": "https://chorus.example.com",
+  "apiKey": "cho_xxxxxxxxxxxxxxxxxxxxxxxx",
+  "agentUuid": "00000000-0000-0000-0000-000000000000",
+  "agentName": "My Daemon Agent",
+  "cwds": ["~/work/repo-a", "~/work/repo-b"],
+  "sigintTimeoutMs": 10000
+}
+```
+
+| Field | Type | Written by / used for | Precedence (highest first) |
+|-------|------|-----------------------|----------------------------|
+| `url` | string | Remote Chorus server URL | `--url` flag → `CHORUS_URL` → file |
+| `apiKey` | string | Agent API key (`cho_…`) | `--api-key` flag → `CHORUS_API_KEY` → file |
+| `agentUuid` / `agentName` | string | Authenticated identity (recorded at login) | written by `chorus login` |
+| `cwds` | string[] | Working directories the daemon serves (multi-path) | `--cwd` flag(s) → `CHORUS_DAEMON_CWDS` → file → launch dir |
+| `sigintTimeoutMs` | number | Grace window (ms) after SIGINT before a forceful kill (default `10000`) | `--sigint-timeout` flag → `CHORUS_DAEMON_SIGINT_TIMEOUT` → file → `10000` |
+| `yoloAckAt` | string | Internal — timestamp of a TTY yolo confirmation (managed automatically) | — |
+
+On startup the daemon banner prints the **exact `daemon.json` path it read** (and whether the file exists), so you always know which file to edit.
+
 ---
 
 ## Screenshots
 
+### Remote Agent Wake — Dispatch to a Directory, Watch It Run
+
+![Remote Agent Wake](docs/images/agent-daemon-wake.gif)
+
+Assign an idea to a specific directory on a remote agent, then open the conversation and watch the local Claude Code pick up the work and run in real time — no terminal, no manual resume.
+
 ### Proposal — AI Agent Generates Plans in Real Time
 
 ![Proposal Presence](docs/images/proposal-presence.gif)
@@ -257,7 +291,7 @@ A Cmd+K command palette for searching across all 6 entity types (Tasks, Ideas, P
 | Agent Integration | MCP SDK 1.26 (HTTP Streamable Transport) |
 | Auth | OIDC + PKCE / API Key / SuperAdmin |
 | i18n | next-intl (en, zh) |
-| Deployment | [Docker Hub](https://hub.docker.com/repository/docker/chorusaidlc/chorus-app/general) / Docker Compose / AWS CDK |
+| Deployment | [Docker Hub](https://hub.docker.com/r/chorusaidlc/chorus-app) / Docker Compose / AWS CDK |
 
 ---
 

package/README.zh.md

@@ -27,6 +27,8 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 
 ## 最近更新
 
+**[v0.12.0](https://chorus-ai.dev/zh/blog/chorus-v0.12.0-release/)** — 可寻址的 daemon 实例：一个 `chorus daemon` 可同时守多个工作目录（`--cwd`），每一个 `(agent, 主机, 目录)` 都成为一个能单独看见、单独点名的实例，贯穿 presence、@-mention 与任务指派。在想法上钉一次实例，其下的提案、任务与唤醒都会继承；带钉的唤醒被精确投递到那个实例，而非全员广播。评论区的 Agent @-mention 渲染为实时在线状态徽章，评论列表改为游标式无限滚动。
+
 **[v0.11.0](https://chorus-ai.dev/zh/blog/chorus-v0.11.0-release/)** — Chorus Daemon：`chorus daemon` 将本机变为常驻 Agent 运行时，在每次派发时唤起本地 Claude Code。Agent Connections 界面提供实时可观测与控制：流式 transcript、指令注入、打断 / 恢复；新增"完成细化"按钮，唤起被指派的 Agent 撰写提案。
 
 **[v0.10.0](https://chorus-ai.dev/zh/blog/chorus-v0.10.0-release/)** — 单父想法血缘：一条想法可派生子想法或挂靠至另一条之下，构成森林结构。该关联为弱关联，父想法仅呈现只读的 "+N derived" 汇总，不约束子想法的细化、提案与任务流程。想法浏览统一收敛至 Dashboard（Ideas / Lineage / Stats 三档视图切换，支持自适应默认）；独立的 Idea List 页面下线，原 URL 经 308 重定向至 Dashboard。
@@ -37,18 +39,6 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 
 **[v0.8.0](https://chorus-ai.dev/zh/blog/chorus-v0.8.0-release/)** — OpenSpec-aware 模式（仅 Claude Code）：当仓库下同时存在 `openspec/` 目录和 `openspec` CLI 时自动启用，新增 `/opsx/{explore,propose,apply,archive}` 与 task verify 后的 archive-trigger 钩子。
 
-**[v0.7.0](https://chorus-ai.dev/zh/blog/chorus-v0.7.0-release/)** — 细粒度 Agent 权限：5 类资源 × 3 个动作组成的网格，取代 PM / Developer / Admin 三选一。保留原有预设，新增 Custom 选项自由组合。
-
-**[v0.6.7](https://chorus-ai.dev/zh/blog/chorus-v0.6.7-release/)** — Codex CLI 版 Chorus 插件（一条命令装完）、同一邮箱属于多个 Company 时的工作区选择器、每种客户端的接入文档。
-
-**[v0.6.6](https://chorus-ai.dev/zh/blog/chorus-v0.6.6-release/)** — npm 一键安装（`npx @chorus-aidlc/chorus`）、文档导出（MD/PDF/Word）、Proposal 撤回、优化 Agent Checkin 快速获取工作状态。
-
-**[v0.6.2](https://chorus-ai.dev/zh/blog/chorus-v0.6.2-release/)** — 嵌入式 PGlite 模式（零依赖部署）、Pino 结构化日志、无状态 MCP 支持水平扩展、默认端口改为 8637。
-
-**[v0.6.1](https://chorus-ai.dev/zh/blog/chorus-v0.6.1-release/)** — `/yolo` 技能：全自动 AI-DLC 流水线（Idea → Proposal → Execute → Verify），支持 Agent Team 并行执行。
-
-**[v0.6.0](https://chorus-ai.dev/zh/blog/chorus-v0.6.0-release/)** — IdeaTracker 面板、独立审阅 Agent（proposal-reviewer + task-reviewer）、实时 Agent Presence 指示器、跨列 Kanban 动画。
-
 > 完整更新日志：[CHANGELOG.md](CHANGELOG.md)
 
 ---
@@ -114,14 +104,58 @@ chorus daemon logs               # 查看 daemon 日志
 - **Claude Code 集成** — 自动检测 PATH 中的 `claude` CLI
 - **后台模式** — 使用 `-d` 标志后台运行；用 `stop/restart/logs` 管理
 - **权限模式** — 默认完全访问（yolo）；使用 `--chorus-only` 限制为仅 Chorus MCP 工具
+- **多路径** — 用可重复的 `--cwd` 让单个 daemon 同时服务多个工作目录（见下文）
 - **交互式设置** — 首次启动时如未配置凭证会提示输入
 
 daemon 需要先认证。首次使用请先运行 `chorus login`，或者 daemon 会在首次启动时交互式提示输入凭证（如果在终端中运行）。
 
+#### 服务多个工作目录
+
+一个 daemon 可以同时服务多个本地工作目录——每个声明的路径会注册为一条独立连接（各自拥有会话与唤起循环），归属同一个 Agent。路径**仅仅**是 daemon 服务的目录，不携带任何项目绑定。
+
+```bash
+chorus daemon --cwd ~/work/repo-a --cwd ~/work/repo-b   # 可重复传入
+CHORUS_DAEMON_CWDS="~/work/repo-a:~/work/repo-b" chorus daemon   # 或用环境变量（`:` 或 `,` 分隔）
+```
+
+不传 `--cwd` 时，daemon 只服务它的启动目录这一个路径。
+
+#### 配置文件 —— `~/.chorus/daemon.json`
+
+`chorus login` 会把凭证写入此文件（权限 `0600`）。你也可以把 daemon 的调优项写进**同一个**文件。所有字段都是可选的；命令行参数和环境变量的优先级始终高于文件。
+
+```json
+{
+  "url": "https://chorus.example.com",
+  "apiKey": "cho_xxxxxxxxxxxxxxxxxxxxxxxx",
+  "agentUuid": "00000000-0000-0000-0000-000000000000",
+  "agentName": "My Daemon Agent",
+  "cwds": ["~/work/repo-a", "~/work/repo-b"],
+  "sigintTimeoutMs": 10000
+}
+```
+
+| 字段 | 类型 | 写入方 / 用途 | 优先级（从高到低） |
+|------|------|---------------|--------------------|
+| `url` | string | 远程 Chorus 服务器 URL | `--url` 参数 → `CHORUS_URL` → 文件 |
+| `apiKey` | string | Agent API Key（`cho_…`） | `--api-key` 参数 → `CHORUS_API_KEY` → 文件 |
+| `agentUuid` / `agentName` | string | 认证身份（登录时记录） | 由 `chorus login` 写入 |
+| `cwds` | string[] | daemon 服务的工作目录（多路径） | `--cwd` 参数 → `CHORUS_DAEMON_CWDS` → 文件 → 启动目录 |
+| `sigintTimeoutMs` | number | SIGINT 后强制结束前的宽限窗口（毫秒，默认 `10000`） | `--sigint-timeout` 参数 → `CHORUS_DAEMON_SIGINT_TIMEOUT` → 文件 → `10000` |
+| `yoloAckAt` | string | 内部字段——TTY 下 yolo 确认的时间戳（自动管理） | — |
+
+daemon 启动时的横幅会打印它**实际读取的 `daemon.json` 路径**（以及该文件是否存在），让你随时清楚该编辑哪个文件。
+
 ---
 
 ## 界面预览
 
+### 远程唤醒 Agent——派活到指定目录，实时看它跑
+
+![远程唤醒 Agent](docs/images/agent-daemon-wake.gif)
+
+把一条想法派给远程 Agent 的某个目录，打开对话窗口，就能实时看到本地的 Claude Code 接活、开跑，全程不用碰终端，也不用手动 resume。
+
 ### Proposal——AI Agent 实时生成计划
 
 ![Proposal Presence](docs/images/proposal-presence.gif)
@@ -248,7 +282,7 @@ Cmd+K 命令面板，支持跨 6 种实体类型搜索。支持范围筛选（
 | Agent 集成 | MCP SDK 1.26 (HTTP Streamable Transport) |
 | 认证 | OIDC + PKCE / API Key / SuperAdmin |
 | i18n | next-intl (en, zh) |
-| 部署 | [Docker Hub](https://hub.docker.com/repository/docker/chorusaidlc/chorus-app/general) / Docker Compose / AWS CDK |
+| 部署 | [Docker Hub](https://hub.docker.com/r/chorusaidlc/chorus-app) / Docker Compose / AWS CDK |
 
 ---
 

package/chorus.mjs

@@ -34,6 +34,10 @@ import {
   daemonHelpText,
   loginHelpText,
 } from "./cli/client-args.mjs";
+// Server-only signal-handler installer, guarded so a client subcommand
+// (`chorus daemon` / `chorus login`) never registers the server's handlers.
+// Pure module → unit-testable without this entry's import-time side effects.
+import { installServerSignalHandlers } from "./cli/server-signal-handlers.mjs";
 
 /** Read the package version once for help/version output. */
 function pkgVersion() {
@@ -159,10 +163,13 @@ ENVIRONMENT VARIABLES
 DAEMON / LOGIN (client mode)
   --url <url>              Remote Chorus server URL      (env: CHORUS_URL)
   --api-key <cho_...>      Agent API key                 (env: CHORUS_API_KEY)
-  --yolo                   Give the woken Claude FULL permissions             (env: CHORUS_YOLO=1)
+  --chorus-only            Restrict the woken Claude to Chorus MCP tools only  (env: CHORUS_CHORUS_ONLY=1)
+                           (comment/claim/report/status — no Bash / file edits).
+                           Opt out of the default full-autonomy posture.
+  --yolo                   Full autonomy for the woken Claude — the DEFAULT     (env: CHORUS_YOLO=1)
                            (--dangerously-skip-permissions: Bash, file writes,
-                           any command). Default is Chorus-MCP-tools-only.
-  --sigint-timeout <ms>    Grace window after SIGINT before a forceful kill   (env: CHORUS_DAEMON_SIGINT_TIMEOUT)
+                           any command). Already on unless --chorus-only is set.
+  --sigint-timeout <ms>    Grace window after SIGINT before a forceful kill    (env: CHORUS_DAEMON_SIGINT_TIMEOUT)
                            when an interrupt is received (default: 10000).
                            Also configurable via ~/.chorus/daemon.json sigintTimeoutMs.
 
@@ -170,9 +177,9 @@ DAEMON / LOGIN (client mode)
   ~/.chorus/daemon.json (from 'chorus login') > Claude Code plugin config.
 
   The daemon spawns the local 'claude' CLI headlessly per task dispatch; it must
-  be on PATH. Override with CHORUS_CLAUDE_PATH. By default the woken Claude may
-  use only Chorus MCP tools (comment/claim/report/status) — pass --yolo for full
-  autonomy (real code-writing AI-DLC), which is dangerous: run it sandboxed.
+  be on PATH. Override with CHORUS_CLAUDE_PATH. By default the woken Claude runs
+  with FULL autonomy (real code-writing AI-DLC), which is dangerous: run it
+  sandboxed, or pass --chorus-only to restrict it to Chorus MCP tools.
 
 EXAMPLES
   chorus                                     # Embedded PGlite (default)
@@ -180,8 +187,8 @@ EXAMPLES
   chorus --data-dir /var/lib/chorus          # Custom data directory
   DATABASE_URL=postgres://... chorus --use-pglite=false   # External PostgreSQL
   chorus login                               # Interactive: validate key, save credentials
-  chorus daemon                              # Connect & wake local Claude Code (Chorus tools only)
-  chorus daemon --yolo                       # Full autonomy: woken Claude can run Bash / edit files
+  chorus daemon                              # Connect & wake local Claude Code (full autonomy by default)
+  chorus daemon --chorus-only                # Restrict the woken Claude to Chorus MCP tools only
   CHORUS_URL=https://... CHORUS_API_KEY=cho_... chorus daemon
 `);
   process.exit(0);
@@ -451,12 +458,21 @@ function shutdown() {
   }
 }
 
-process.on("SIGINT", shutdown);
-process.on("SIGTERM", shutdown);
-process.on("exit", () => {
-  if (pgliteProcess && !pgliteProcess.killed) {
-    pgliteProcess.kill("SIGKILL");
-  }
+// Install the server's SIGINT/SIGTERM/exit handlers ONLY on the server launch
+// path. On a client subcommand (`chorus daemon` / `chorus login`) this installs
+// nothing, so the daemon's OWN graceful shutdown handler is the sole signal
+// disposition — otherwise the server's handler (registered first) would pre-empt
+// it with a synchronous `process.exit(0)`, leaving the daemon to disconnect
+// non-gracefully (stale presence) and printing a misleading bare "Shutting down...".
+installServerSignalHandlers({
+  isSubcommand,
+  processRef: process,
+  shutdown,
+  cleanupExit: () => {
+    if (pgliteProcess && !pgliteProcess.killed) {
+      pgliteProcess.kill("SIGKILL");
+    }
+  },
 });
 
 // ---------------------------------------------------------------------------

package/cli/client-args.mjs

@@ -28,10 +28,16 @@ export const KNOWN_AGENTS = new Set(["claude-code"]);
  * "false" (important for layered env/flag precedence downstream).
  *
  * @param {string[]} argv
+ * The new repeatable `--cwd <path>` (space + `=`) declares a working directory the
+ * daemon serves; repeating it (`--cwd a --cwd b`) declares the SET of paths for the
+ * single-daemon multi-path engine (T3). It is collected into a `cwd: string[]` array
+ * preserving order; absent ⇒ `cwd` is unset (the layered resolver then falls back to
+ * env / config / the process cwd). It is JUST a path list — no project binding.
+ *
  * @returns {{
  *   url?: string, apiKey?: string, yolo?: boolean, sigintTimeout?: string,
  *   agent?: string, chorusOnly?: boolean, verbose?: boolean, detach?: boolean,
- *   help?: boolean,
+ *   cwd?: string[], help?: boolean,
  * }}
  */
 export function parseClientFlags(argv) {
@@ -47,6 +53,11 @@ export function parseClientFlags(argv) {
     else if (a.startsWith("--sigint-timeout=")) out.sigintTimeout = a.slice("--sigint-timeout=".length);
     else if (a === "--agent") out.agent = argv[i + 1];
     else if (a.startsWith("--agent=")) out.agent = a.slice("--agent=".length);
+    else if (a === "--cwd" || a.startsWith("--cwd=")) {
+      // Repeatable: collect every --cwd into an ordered array (the cwd SET).
+      const value = a === "--cwd" ? argv[i + 1] : a.slice("--cwd=".length);
+      if (typeof value === "string") (out.cwd ??= []).push(value);
+    }
     else if (a === "--chorus-only") out.chorusOnly = true;
     else if (a === "--verbose") out.verbose = true;
     else if (a === "-d" || a === "--detach") out.detach = true;
@@ -103,6 +114,11 @@ OPTIONS
   --chorus-only            Restrict the woken agent to Chorus  (env: CHORUS_CHORUS_ONLY=1)
                            MCP tools only (no Bash / file edits) — reclaims the
                            safe posture from the default yolo.
+  --cwd <path>             A working directory the daemon serves. Repeatable —
+                           (env: CHORUS_DAEMON_CWDS) each --cwd registers an independent
+                           connection for that path, so one daemon can serve several
+                           local paths at once. Default: the directory it was launched
+                           from. (Also configurable as "cwds":[…] in ~/.chorus/daemon.json.)
   -d, --detach             Run detached in the background (pidfile + logfile)
   --verbose                More detailed per-wake logging
   --sigint-timeout <ms>    Grace window after SIGINT before a forceful kill

package/cli/daemon-banner.mjs

@@ -19,6 +19,8 @@
  * @property {string} agentType        local agent backend (e.g. claude-code).
  * @property {string|null} claudePath  resolved claude path, 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). */
@@ -38,7 +40,7 @@ export function bannerRows(info) {
       ? "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 [
+  const rows = [
     ["Version", `chorus v${info.version}`],
     ["Server", info.url],
     ["Agent", `${info.agentName} (${info.agentUuid})`],
@@ -48,6 +50,14 @@ export function bannerRows(info) {
     ["Connection", info.connection ?? "connecting…"],
     ["claude CLI", claude],
   ];
+  // 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;
 }
 
 /**

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];
+}