@chorus-aidlc/chorus 0.10.0 → 0.11.0

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

@@ -4,7 +4,7 @@ description: Chorus AI Agent collaboration platform — overview, common tools,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.10.0"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

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

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, self-chec
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.10.0"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

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

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.10.0"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -298,4 +298,5 @@ This is a soft heuristic, not a rule — use judgment. Cycle prevention is autom
 ## Next
 
 - Once elaboration is resolved, use the `proposal-chorus` skill (`<BASE_URL>/skill/proposal-chorus/SKILL.md`) to create a Proposal with document and task drafts
+- **Human "Verify Elaborate" handoff:** when a human clicks **Verify Elaborate** on the idea-detail panel, Chorus resolves the elaboration and wakes the Idea's assigned daemon agent to write the proposal — so the woken agent picks up this idea→proposal handoff automatically (no human-authored proposal needed).
 - For platform overview and shared tools, see the `chorus` skill (`<BASE_URL>/skill/chorus/SKILL.md`)

package/.next/standalone/public/skill/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chorus-skill",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Chorus AI Agent collaboration platform skill. Supports PM, Developer, and Admin roles via MCP tools for the Idea-Proposal-Task workflow.",
   "author": "chorus",
   "license": "AGPL-3.0",

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

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.10.0"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/proposal-reviewer-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only adversarial Chorus proposal reviewer — audits PRD/task
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.10.0"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/quick-dev-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.10.0"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

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

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.10.0"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

package/.next/standalone/public/skill/task-reviewer-chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Read-only adversarial Chorus task reviewer — independently verifi
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.10.0"
+  version: "0.11.0"
   category: project-management
   mcp_server: chorus
 ---

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.0"
   category: project-management
   mcp_server: chorus
 ---

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.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 +100,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,8 @@ Idea ──> Proposal ──> [Document + Task DAG] ──> Execute ──> Veri
 
 ## 最近更新
 
+**[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 +91,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;
+}