@chorus-aidlc/chorus 0.10.0 → 0.11.1

package/.next/standalone/public/skill/yolo-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Full-auto AI-DLC pipeline — drive a single prompt from Idea throu
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.10.0"
+  version: "0.11.1"
   category: project-management
   mcp_server: chorus
 ---
@@ -25,6 +25,7 @@ You take a natural-language description of what to build, and you handle everyth
 2. **Proposal Review** — adversarial review loop against the `proposal-reviewer-chorus` skill.
 3. **Execution** — dependency-ordered, wave-based task dispatch.
 4. **Verification** — adversarial review loop against the `task-reviewer-chorus` skill + admin verify.
+4.5. **Code-Review Gateway** — adversarial review loop against the `code-reviewer-chorus` skill over the Idea's aggregate change, before ship (FAIL → add fix tasks → re-run).
 5. **Report** — completion summary + a mandatory Idea Completion Report.
 
 ```
@@ -47,6 +48,9 @@ Verification loop  (up to maxTaskReviewRounds, default 3)
    |   PASS / PASS WITH NOTES -> mark AC + verify ;  FAIL -> reopen
    |   verify unblocks dependents -> loop back to Execution
    v
+Code-Review Gateway  (all tasks done; up to maxCodeReviewRounds, default 3)
+   |   PASS / PASS WITH NOTES -> ship ;  FAIL -> add fix tasks -> Execution -> re-run
+   v
 Done  -->  Report summary + mandatory Idea Completion Report
 ```
 
@@ -453,6 +457,33 @@ After verifying every task in the wave, return to **Phase 3** and re-run `chorus
 
 ---
 
+### Phase 4.5: Code-Review Gateway (mandatory pre-ship)
+
+Once **every** task of the idea's proposal is verified (`done`) — Phase 3 finds no more unblocked tasks and none remain non-terminal — run the final ship-time code-review gateway **before** the Phase 5b completion report. This is the same **Independent Review pattern** as Phases 2 and 4, pointed at the `code-reviewer-chorus` skill — but it reviews the **whole Idea's aggregate code change** (across all tasks), not a single task, and posts its verdict on the **Idea**.
+
+> **Independent Review pattern (framework-neutral).** Spawn a **read-only** sub-agent and have it load the `code-reviewer-chorus` skill (`<BASE_URL>/skill/code-reviewer-chorus/SKILL.md`), pass it the `ideaUuid` and the current review round number, and instruct it to post exactly one `VERDICT` comment on the **idea**. It reviews cross-task integration, architecture/convention consistency, security, regression/performance, and feature-level test coverage — dimensions a single-task review cannot see — and may run read-only tests/build/lint, but never writes. After it returns, read the verdict via `chorus_get_comments({ targetType: "idea", targetUuid: "<idea-uuid>" })`.
+>
+> - Claude Code: dispatch a read-only sub-agent with the Task/Agent tool, mounting the `code-reviewer-chorus` skill.
+> - Codex: `spawn_agent` with the `code-reviewer-chorus` skill and the `ideaUuid`.
+
+> **Inline self-review fallback (no sub-agents available).** Perform the review inline as the main agent: read `code-reviewer-chorus`, follow its procedure (fetch the idea, its approved proposals + documents + tasks; infer the aggregate diff from task reports + `git log/diff`; review the six whole-feature dimensions; run the project's build/test), and post your own `VERDICT` comment on the idea.
+
+Act on the verdict:
+
+- **`VERDICT: PASS` / `PASS WITH NOTES`** — the feature is cleared to ship. Proceed to Phase 5 / 5b.
+- **`VERDICT: FAIL`** — do NOT ship. Read the BLOCKERs, then fix them via the **quick-dev** workflow (`<BASE_URL>/skill/quick-dev-chorus/SKILL.md`): call `chorus_create_tasks` with `proposalUuid` set to the **current approved proposal** so the fix tasks attach to it (not standalone) — do **not** reopen the already-verified tasks. Drive the fix tasks through Phase 3 → Phase 4, then re-spawn the code-reviewer for the next round. Loop bounded by `maxCodeReviewRounds` (default **3**; 0 = unlimited).
+
+```
+ESCALATE: "Idea '<title>' failed code review after 3 rounds. Last BLOCKERs: <list>.
+           Manual intervention needed. Idea UUID: <idea-uuid>."
+```
+
+**No VERDICT comment after the code-reviewer returns?** It exhausted its turn budget (it carries a larger budget than the task-reviewer because it reviews the whole feature). Respawn it once with a concise-budget hint; if still none, treat as **PASS WITH NOTES** and proceed — do not loop forever.
+
+> The gateway is **behavioral**, consistent with the other two reviewers: its verdict is advisory and does not change the Idea's stored status; the orchestrator honors it. It runs **before** the completion report so the report is never written while a FAIL is outstanding.
+
+---
+
 ### Phase 5: Report
 
 When all waves complete, output a markdown summary:
@@ -485,6 +516,8 @@ When all waves complete, output a markdown summary:
 
 A successful yolo run always finishes the Idea. Call `chorus_create_report` **exactly once**, with `proposalUuid` set to the **last verified proposal**. The tool's own description carries the section template — follow it. Surface the returned `documentUuid` in the Phase 5 summary table. Skipping this is a protocol violation.
 
+> **Order:** write the completion report only **after** the Phase 4.5 code-review gateway returns PASS / PASS WITH NOTES. Never write it while a code-review FAIL is outstanding — the report is a ship-time summary, and the gateway is what clears the feature to ship.
+
 ```
 result = chorus_create_report({
   proposalUuid: "<last-verified-proposal-uuid>",
@@ -503,6 +536,7 @@ result = chorus_create_report({
 | Project creation fails | Report the error; suggest the user create the project manually and rerun with an existing-project hint. |
 | Proposal review FAILs after `maxProposalReviewRounds` (3) | Stop the pipeline; report the persisting BLOCKERs; recommend manual review of the proposal. |
 | Task review FAILs after `maxTaskReviewRounds` (3) | Flag the task as escalation-needed; continue with the other tasks. |
+| Code-review gateway FAILs after `maxCodeReviewRounds` (3) | Stop before ship; escalate the persisting feature-level BLOCKERs to a human (Idea UUID); do not write the completion report. |
 | Reviewer returns no VERDICT | Respawn the reviewer once with a concise-budget hint; if still none, treat as PASS WITH NOTES and proceed. |
 | Worker crashes / never submits | Log it, leave the task non-`to_verify`; re-pick it in a later wave or escalate if it stays stuck. |
 | No unblocked tasks but some not done | Stuck DAG (failed reviews or bad dependencies). Break with an escalation report; do not loop. |

package/README.md

@@ -36,6 +36,10 @@ The labels under each stage are the **permissions** an actor needs at that stage
 
 ## What's New
 
+**[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.
+
 **[v0.9.4](https://chorus-ai.dev/blog/chorus-v0.9.4-release/)** — OpenClaw plugin rewritten on the OpenClaw 2026.4.27 Plugin SDK (native MCP registration, `runEmbeddedAgent` for SSE wake, reviewers as native skills); Codex plugin hooks now ship inside the package, with an installer that cleans up legacy hook copies in the user directory.
 
 **[v0.9.0](https://chorus-ai.dev/blog/chorus-v0.9.0-release/)** — Brainstorm skill for fuzzy ideas (open-ended chat before structured Q&A) and idea-completion reports (every shipped idea gets a Summary / Decisions / Follow-ups writeup, surfaced on the idea overview).
@@ -98,6 +102,31 @@ DATABASE_URL=postgresql://user:pass@host:5432/chorus chorus
 | **Docker (full stack)** | [`docker compose up`](#quick-start-with-docker-recommended) (PostgreSQL + Redis + Chorus) |
 | **AWS CDK** | [Deploy to AWS](#deploy-to-aws) |
 
+### `chorus daemon` — Connect as Agent Runtime
+
+The `chorus daemon` connects your local machine to a remote Chorus server as an agent runtime and executes tasks assigned by Chorus.
+
+> **Current version:** Only **Claude Code** is supported. Support for other agent CLIs (Codex, Copilot, etc.) is planned for future releases.
+
+```bash
+chorus login                     # Authenticate (opens browser)
+chorus daemon                    # Start daemon in foreground
+chorus daemon -d                 # Start daemon in background (detached)
+chorus daemon stop               # Stop background daemon
+chorus daemon status             # Check daemon status
+chorus daemon restart            # Restart background daemon
+chorus daemon logs               # View daemon logs
+```
+
+**Key features:**
+
+- **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
+- **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).
+
 ---
 
 ## Screenshots

package/README.zh.md

@@ -27,6 +27,10 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 
 ## 最近更新
 
+**[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。
+
 **[v0.9.4](https://chorus-ai.dev/zh/blog/chorus-v0.9.4-release/)** — OpenClaw 插件基于 OpenClaw 2026.4.27 Plugin SDK 全面重写（原生 MCP 注册、`runEmbeddedAgent` 处理 SSE 唤醒、reviewer 改为原生 skill）；Codex 插件 hook 改为随插件包分发，安装器同时清理用户目录中的历史 hook 拷贝。
 
 **[v0.9.0](https://chorus-ai.dev/zh/blog/chorus-v0.9.0-release/)** — 头脑风暴 skill 帮你把模糊的想法聊出形状（在结构化多选题前先开放式对话），想法落地后自动生成总结报告（Summary / Decisions / Follow-ups 三段式，挂在想法概览页）。
@@ -89,6 +93,31 @@ DATABASE_URL=postgresql://user:pass@host:5432/chorus chorus
 | **Docker（完整版）** | [`docker compose up`](#docker-一键启动推荐)（PostgreSQL + Redis + Chorus） |
 | **AWS CDK** | [部署到 AWS](#部署到-aws) |
 
+### `chorus daemon` — 作为 Agent 运行时连接
+
+`chorus daemon` 将你的本地机器作为 Agent 运行时连接到远程 Chorus 服务器并执行 Chorus 分配的任务。
+
+> **当前版本：** 仅支持 **Claude Code**。对其他 Agent CLI（Codex、Copilot 等）的支持计划在未来版本中实现。
+
+```bash
+chorus login                     # 认证（打开浏览器）
+chorus daemon                    # 前台启动 daemon
+chorus daemon -d                 # 后台启动 daemon（分离模式）
+chorus daemon stop               # 停止后台 daemon
+chorus daemon status             # 查看 daemon 状态
+chorus daemon restart            # 重启后台 daemon
+chorus daemon logs               # 查看 daemon 日志
+```
+
+**主要特性：**
+
+- **Claude Code 集成** — 自动检测 PATH 中的 `claude` CLI
+- **后台模式** — 使用 `-d` 标志后台运行；用 `stop/restart/logs` 管理
+- **权限模式** — 默认完全访问（yolo）；使用 `--chorus-only` 限制为仅 Chorus MCP 工具
+- **交互式设置** — 首次启动时如未配置凭证会提示输入
+
+daemon 需要先认证。首次使用请先运行 `chorus login`，或者 daemon 会在首次启动时交互式提示输入凭证（如果在终端中运行）。
+
 ---
 
 ## 界面预览

package/chorus.mjs

@@ -16,6 +16,73 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// ---------------------------------------------------------------------------
+// Subcommand router (client-mode commands)
+// ---------------------------------------------------------------------------
+// `chorus` with no subcommand (or the existing server flags) launches the
+// Next.js server exactly as before. `chorus daemon` and `chorus login` are
+// client commands that connect OUT to a remote Chorus server. Their modules are
+// lazy-imported so the server-launch path pays no startup cost.
+
+const SUBCOMMANDS = new Set(["daemon", "login"]);
+
+// Client-subcommand arg parsing + help text live in cli/client-args.mjs so they
+// are pure and unit-testable (this entry module runs side effects at import).
+import {
+  parseClientFlags,
+  parseDaemonAction,
+  daemonHelpText,
+  loginHelpText,
+} from "./cli/client-args.mjs";
+
+/** Read the package version once for help/version output. */
+function pkgVersion() {
+  return JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8")).version;
+}
+
+async function runSubcommand(name, rest) {
+  const flags = parseClientFlags(rest);
+
+  // Per-subcommand --help / -h fast-path: print subcommand-specific help and
+  // exit WITHOUT starting the daemon/login. (The server --help fast-path below
+  // is skipped for subcommands, so this is the only place client help is shown.)
+  if (flags.help) {
+    process.stdout.write(name === "login" ? loginHelpText(pkgVersion()) : daemonHelpText(pkgVersion()));
+    return 0;
+  }
+
+  if (name === "login") {
+    const { runLogin } = await import("./cli/login.mjs");
+    return runLogin(flags);
+  }
+  if (name === "daemon") {
+    const action = parseDaemonAction(rest);
+    const { runDaemon } = await import("./cli/daemon.mjs");
+    // Lifecycle sub-actions (stop/status/restart/logs) are handled by the
+    // background-lifecycle module the daemon wires in; `run` is the normal
+    // long-lived daemon. We pass the resolved action through so a later task
+    // can dispatch it without re-parsing.
+    return runDaemon({ ...flags, action });
+  }
+  return 1;
+}
+
+{
+  const sub = process.argv[2];
+  if (sub && SUBCOMMANDS.has(sub)) {
+    runSubcommand(sub, process.argv.slice(3))
+      .then((code) => process.exit(typeof code === "number" ? code : 0))
+      .catch((err) => {
+        console.error(`Fatal error in 'chorus ${sub}':`, err);
+        process.exit(1);
+      });
+    // Stop the server-launch module body from executing in this process tick.
+    // The promise above owns process lifetime from here.
+  }
+}
+
+const isSubcommand = SUBCOMMANDS.has(process.argv[2]);
+
 // ---------------------------------------------------------------------------
 // Dependency resolution (hoist-safe — see issue #214)
 // ---------------------------------------------------------------------------
@@ -57,16 +124,21 @@ function hasFlag(long, short) {
   return args.includes(long) || args.includes(short);
 }
 
-// --help / --version fast paths
-if (hasFlag("--help", "-h")) {
+// --help / --version fast paths (skipped when a client subcommand was dispatched —
+// e.g. `chorus login --help` belongs to the subcommand, not the server)
+if (!isSubcommand && hasFlag("--help", "-h")) {
   const pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
   process.stdout.write(`
 Chorus v${pkg.version} — AI Agent & Human collaboration platform
 
 USAGE
-  chorus [options]
+  chorus [options]                 Start the Chorus server (default)
+  chorus login [--url --api-key]   Authenticate as an agent; saves ~/.chorus/daemon.json
+  chorus daemon [--url --api-key]  Connect to a remote Chorus server, subscribe to the
+                                   agent notification stream, and wake a local headless
+                                   Claude Code on task dispatch
 
-OPTIONS
+SERVER OPTIONS
   -p, --port <port>        HTTP server port             (default: 8637, env: PORT)
   -d, --data-dir <path>    Data directory for PGlite    (default: ~/.chorus-data, env: CHORUS_DATA_DIR)
       --hostname <host>    Bind address                 (default: 0.0.0.0)
@@ -84,16 +156,38 @@ ENVIRONMENT VARIABLES
   NEXTAUTH_SECRET          Session signing secret (auto-generated if unset)
   COOKIE_SECURE            Set to "true" for HTTPS deployments
 
+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)
+                           (--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)
+                           when an interrupt is received (default: 10000).
+                           Also configurable via ~/.chorus/daemon.json sigintTimeoutMs.
+
+  Credential resolution order: flags > CHORUS_URL/CHORUS_API_KEY env >
+  ~/.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.
+
 EXAMPLES
   chorus                                     # Embedded PGlite (default)
   chorus --port 3000                         # Custom port
   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_URL=https://... CHORUS_API_KEY=cho_... chorus daemon
 `);
   process.exit(0);
 }
 
-if (hasFlag("--version", "-v")) {
+if (!isSubcommand && hasFlag("--version", "-v")) {
   const pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
   process.stdout.write(`${pkg.version}\n`);
   process.exit(0);
@@ -103,12 +197,19 @@ if (hasFlag("--version", "-v")) {
 // Configuration
 // ---------------------------------------------------------------------------
 
-const port = Number(getArg("--port", "-p") ?? process.env.PORT ?? 8637);
-const dataDir = resolve(
-  getArg("--data-dir", "-d") ?? process.env.CHORUS_DATA_DIR ?? join(homedir(), ".chorus-data")
-);
-const hostname = getArg("--hostname") ?? "0.0.0.0";
-const PGLITE_PORT = Number(getArg("--pglite-port") ?? process.env.CHORUS_PGLITE_PORT ?? 5433);
+// Server-only configuration. Guarded by `!isSubcommand` because these parse
+// SERVER flags — notably `-d` is the server's `--data-dir` short alias, which
+// collides with the daemon's `-d`/--detach. For `chorus daemon -d`, the
+// subcommand dispatch above owns the process; computing `resolve(getArg("--data-dir","-d"))`
+// here would see `-d` as a bare boolean `true` and throw `resolve(true)` on the
+// same tick, crashing before the daemon detaches. Skipping for subcommands keeps
+// the server-flag surface entirely out of the client-command path.
+const port = isSubcommand ? 0 : Number(getArg("--port", "-p") ?? process.env.PORT ?? 8637);
+const dataDir = isSubcommand
+  ? ""
+  : resolve(getArg("--data-dir", "-d") ?? process.env.CHORUS_DATA_DIR ?? join(homedir(), ".chorus-data"));
+const hostname = isSubcommand ? "" : getArg("--hostname") ?? "0.0.0.0";
+const PGLITE_PORT = isSubcommand ? 0 : Number(getArg("--pglite-port") ?? process.env.CHORUS_PGLITE_PORT ?? 5433);
 
 // ---------------------------------------------------------------------------
 // Utilities
@@ -362,8 +463,11 @@ process.on("exit", () => {
 // Run
 // ---------------------------------------------------------------------------
 
-main().catch((err) => {
-  console.error("Fatal error:", err);
-  if (pgliteProcess && !pgliteProcess.killed) pgliteProcess.kill("SIGTERM");
-  process.exit(1);
-});
+// Only launch the server when no client subcommand was dispatched above.
+if (!isSubcommand) {
+  main().catch((err) => {
+    console.error("Fatal error:", err);
+    if (pgliteProcess && !pgliteProcess.killed) pgliteProcess.kill("SIGTERM");
+    process.exit(1);
+  });
+}

package/cli/backfill.mjs

@@ -0,0 +1,190 @@
+// cli/backfill.mjs
+// Reconnect backfill: after the SSE stream reconnects, recover anything that
+// arrived during the gap so a dispatch made while the daemon was briefly
+// disconnected is not lost (cli-daemon spec "Reconnect with backfill"). Two
+// sources, both re-driven through the SAME router/queue + shared `seen` set:
+//
+//   1. NOTIFICATIONS — pull unread notifications via MCP and re-emit each as a
+//      synthetic `new_notification` event (the original OpenClaw onReconnect logic).
+//      This recovers autonomous wakes (task_assigned / mentioned / elaboration / …),
+//      whose actionable payload lives on the re-fetchable notification.
+//
+//   2. PENDING TURNS — re-derive UNSTARTED (status `pending`) DaemonSessionTurns for
+//      this connection's origin-pinned sessions from the TURN TABLE (子1 —
+//      daemon-session-conversation), NOT from notifications. The turn is persisted at
+//      the notification chokepoint before/at notification creation, so it survives a
+//      lost delivery ping; a `human_instruction`'s free-text body lives ONLY on the
+//      turn, making the turn table its sole reliable backfill source. Read via
+//      `GET /api/daemon/pending-turns?connectionUuid=…` (Bearer agent key, global
+//      fetch — zero new deps), each re-dispatched through `router.dispatchPendingTurn`.
+//
+// The pending-turns READ goes through the SHARED daemon REST client
+// (`cli/daemon-rest-client.mjs`), which owns the `GET /api/daemon/pending-turns` request,
+// Bearer auth, the connectionUuid guard, and the no-silent-errors handling (network error
+// / non-2xx / bad JSON / missing turns array are all logged with cause and surfaced).
+// This module keeps only the backfill-domain concerns: the notification source, the
+// `onlyTurnUuid` precision filter, the `seen` dedup, and re-dispatch.
+//
+// De-dupes against the shared `seen` set so a reconnect storm doesn't double-wake.
+//
+// The returned `backfill` function also exposes `backfill.pendingTurnsOnly` — the
+// connection-scoped pending-turns sweep ALONE — so the LIVE `deliver_turn` control ping
+// (子2 — origin-only live delivery) can reuse the EXACT same sweep without re-running the
+// notification source. Live ping and reconnect backfill therefore converge on one sweep +
+// one `seen` set, so a turn runs at most once regardless of which path observes it first.
+
+import { createDaemonRestClient } from "./daemon-rest-client.mjs";
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+
+/**
+ * Build an onReconnect handler that (1) re-emits missed unread notifications into
+ * `dispatch`, and (2) — when a connectionUuid + pending-turn dispatcher are wired —
+ * re-derives this connection's unstarted (pending) turns from the turn table and
+ * re-dispatches each. Both paths share the `seen` set so already-handled work is not
+ * re-run.
+ *
+ * @param {{
+ *   mcpClient: { callTool: (name: string, args?: Record<string, unknown>) => Promise<unknown> },
+ *   dispatch: (event: { type: string, notificationUuid: string }) => void,
+ *   seen?: Set<string>,
+ *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
+ *   limit?: number,
+ *   // 子1 — pending-turn backfill (all optional; when absent, only the notification
+ *   // backfill runs, preserving the original behavior/wiring):
+ *   url?: string,                              Chorus base URL (for the pending-turns read).
+ *   apiKey?: string,                           `cho_` agent API key.
+ *   getConnectionUuid?: () => (string|null),   The daemon's registered connection uuid
+ *                                              (learned from the SSE handshake). Null until
+ *                                              then — the pending-turns read is skipped while null.
+ *   dispatchPendingTurn?: (turn: { turnUuid: string, sessionId: string, directIdeaUuid: string|null, trigger: string, promptText: string|null }) => void,
+ *   fetchImpl?: typeof fetch,                  Injectable for tests.
+ * }} opts
+ * @returns {() => Promise<void>}
+ */
+export function createBackfill(opts) {
+  const { mcpClient, dispatch } = opts;
+  const seen = opts.seen ?? new Set();
+  const logger = opts.logger ?? NOOP_LOGGER;
+  const limit = opts.limit ?? 50;
+  // 子1 pending-turn backfill wiring (optional).
+  const url = opts.url ?? null;
+  const apiKey = opts.apiKey ?? null;
+  const getConnectionUuid = opts.getConnectionUuid ?? null;
+  const dispatchPendingTurn = opts.dispatchPendingTurn ?? null;
+  // The pending-turns READ is delegated to the shared client. Built only when the
+  // pending-turn backfill is wired (url + apiKey + getConnectionUuid present); otherwise
+  // backfillPendingTurns is an early no-op (notification-only callers / older tests).
+  const pendingTurnsClient =
+    url && apiKey && getConnectionUuid
+      ? createDaemonRestClient({ url, apiKey, getConnectionUuid, fetchImpl: opts.fetchImpl, logger })
+      : null;
+
+  /** Re-emit unread notifications missed during the gap (autonomous wakes). */
+  async function backfillNotifications() {
+    let result;
+    try {
+      result = /** @type {{ notifications?: Array<{ uuid: string }> }} */ (
+        await mcpClient.callTool("chorus_get_notifications", {
+          status: "unread",
+          limit,
+          autoMarkRead: false,
+        })
+      );
+    } catch (err) {
+      logger.warn(`[Chorus] backfill fetch failed: ${err}`);
+      return;
+    }
+
+    const notifications = result?.notifications;
+    if (!Array.isArray(notifications)) {
+      logger.warn("[Chorus] backfill: no notifications array in response");
+      return;
+    }
+
+    let redispatched = 0;
+    for (const n of notifications) {
+      if (!n || typeof n.uuid !== "string") continue;
+      // Pre-check only — do NOT mark seen here. The router (dispatch) is the
+      // single owner of marking-at-dispatch; if backfill marked first, the
+      // router's own `seen.has(...)` early-return would fire and the wake would
+      // never enqueue (every backfilled dispatch silently dropped). This
+      // pre-check is just a cheap early-out for notifications already handled.
+      if (seen.has(n.uuid)) continue;
+      redispatched++;
+      dispatch({ type: "new_notification", notificationUuid: n.uuid });
+    }
+    if (redispatched > 0) {
+      logger.info(`[Chorus] backfill re-dispatched ${redispatched} missed notification(s)`);
+    }
+  }
+
+  /**
+   * Re-derive this connection's UNSTARTED (pending) turns from the turn table (子1)
+   * and re-dispatch them through the router. No-op (silently skipped) when the
+   * pending-turn wiring is absent or the connectionUuid is not known yet. Never throws
+   * into the reconnect path — a failure is logged and swallowed.
+   *
+   * `onlyTurnUuid` (子2 — origin-only live delivery): when set, dispatch ONLY the turn
+   * with that uuid out of the fetched set, so a live `deliver_turn` ping runs PRECISELY
+   * the turn it announced and never drags the connection's other still-pending turns
+   * along. When omitted (the reconnect path), dispatch ALL pending turns — the lost-ping
+   * safety net that recovers everything missed during a gap.
+   *
+   * @param {string} [onlyTurnUuid]
+   */
+  async function backfillPendingTurns(onlyTurnUuid) {
+    if (!pendingTurnsClient || !dispatchPendingTurn) {
+      // Pending-turn backfill not wired (e.g. notification-only callers / older tests).
+      return;
+    }
+    // The shared client reads `GET /api/daemon/pending-turns?connectionUuid=…`, skipping
+    // (no log) while the connectionUuid is not known yet — a normal early state — and
+    // surfacing a network error / non-2xx / bad JSON / missing turns array with its cause
+    // (logged) as `result.ok === false`. We just consume the parsed turns; never throw.
+    const result = await pendingTurnsClient.readPendingTurns();
+    if (!result.ok || !result.data) {
+      // Either nothing to read yet (skipped) or a logged failure — nothing to dispatch.
+      return;
+    }
+    const turns = result.data.turns;
+
+    let redispatched = 0;
+    for (const t of turns) {
+      if (!t || typeof t.turnUuid !== "string") continue;
+      // Live `deliver_turn` precision: when a specific turnUuid was announced, dispatch
+      // ONLY it — skip every other pending turn of the connection (they are recovered by
+      // the arg-less reconnect sweep, not by a single-turn live ping).
+      if (onlyTurnUuid && t.turnUuid !== onlyTurnUuid) continue;
+      // The router (dispatchPendingTurn) is the single owner of marking-seen (keyed
+      // `turn:<uuid>`), exactly like the notification path — so do NOT mark here.
+      if (seen.has(`turn:${t.turnUuid}`)) continue;
+      redispatched++;
+      dispatchPendingTurn(t);
+    }
+    if (redispatched > 0) {
+      const scope = onlyTurnUuid ? `turn ${onlyTurnUuid}` : `${redispatched} pending turn(s)`;
+      logger.info(`[Chorus] backfill re-derived ${scope} from the turn table`);
+    }
+  }
+
+  async function backfill() {
+    // Run both sources. Each swallows its own errors so one failing source never
+    // aborts the other (a notification-fetch failure must not lose pending turns, and
+    // vice versa).
+    await backfillNotifications();
+    await backfillPendingTurns();
+  }
+
+  // Expose the CONNECTION-SCOPED pending-turns sweep on its own so the LIVE
+  // `deliver_turn` control ping (子2 — origin-only live delivery) reuses the EXACT same
+  // sweep the reconnect path runs — no second sweep, no second code path. The control
+  // handler triggers `backfill.pendingTurnsOnly()`; it shares the same `seen` set +
+  // `dispatchPendingTurn`, so a turn delivered live and also re-derived on reconnect runs
+  // at most once. Non-throwing (the inner sweep swallows + logs its own errors). The live
+  // `deliver_turn` ping passes the precise `turnUuid` so ONLY that turn runs; an arg-less
+  // call (reconnect) sweeps all pending.
+  /** @type {(onlyTurnUuid?: string) => Promise<void>} */
+  backfill.pendingTurnsOnly = backfillPendingTurns;
+  return backfill;
+}