@chorus-aidlc/chorus 0.16.1 → 0.16.2

package/cli/event-router.mjs

@@ -37,8 +37,8 @@ export class EventRouter {
   /**
    * @param {{
    *   mcpClient: { callTool: (name: string, args?: Record<string, unknown>) => Promise<any> },
-   *   waker: { keyFor: (n: any) => Promise<{ key: string, rootIdeaUuid: string|null, directIdeaUuid: string|null }>, wake: (n: any, key: string, attribution?: any) => Promise<void>, markQueued?: (n: any, key: string, attribution?: any) => void },
-   *   queue: { enqueue: (key: string, task: () => Promise<void>) => void },
+   *   waker: { keyFor: (n: any) => Promise<{ key: string, rootIdeaUuid: string|null, directIdeaUuid: string|null }>, wakeBatch: (ns: any[], key: string, attribution?: any) => Promise<void>, markQueued?: (n: any, key: string, attribution?: any) => void },
+   *   queue: { enqueue: (key: string, item: { notification: any, attribution: any }) => void },
    *   wakeActions: Set<string>,
    *   getConnectionUuid?: () => (string|null),  This daemon's registered connection uuid
    *                                             (null until the SSE handshake reports it).
@@ -228,7 +228,8 @@ export class EventRouter {
    * reason ("user" | "crash") threaded from the control event; it is stamped on the
    * synthetic notification as `resumedFrom` so the prompt builder can state a crash
    * explicitly. Absent/unknown → not stamped → the user-resume prompt.
-   * @param {{ entityType?: string, entityUuid?: string, resumeReason?: string }} target
+   * @param {{ entityType?: string, entityUuid?: string, resumeReason?: string,
+   *   orchestrator?: { type?: string, uuid?: string, name?: string } | null }} target
    */
   dispatchResume(target) {
     const entityType = target?.entityType;
@@ -247,6 +248,11 @@ export class EventRouter {
       entityUuid,
       ...(resumedFrom ? { resumedFrom } : {}),
       ...(typeof target?.runtimeCwd === "string" ? { runtimeCwd: target.runtimeCwd } : {}),
+      ...(target?.orchestrator?.type === "agent" &&
+      typeof target.orchestrator.uuid === "string" &&
+      typeof target.orchestrator.name === "string"
+        ? { orchestrator: target.orchestrator }
+        : {}),
     };
     this.#resolveAndEnqueue(n, `resume:${entityType}:${entityUuid}`).catch((err) => {
       this.logger.error(`[Chorus] failed to dispatch resume for ${entityType}:${entityUuid}: ${err}`);
@@ -383,7 +389,10 @@ export class EventRouter {
     } catch (err) {
       this.logger.warn(`[Chorus] markQueued failed for pending turn ${turnUuid}: ${err}`);
     }
-    this.queue.enqueue(key, () => this.waker.wake(n, key, attribution));
+    // Enqueue an opaque DATA payload (add-daemon-wake-coalescing §C4), NOT a thunk: the
+    // queue coalesces all same-key pending items and hands the whole batch to its runBatch
+    // (wired to waker.wakeBatch in daemon.mjs). markQueued was already called per-item above.
+    this.queue.enqueue(key, { notification: n, attribution });
   }
 
   /**
@@ -531,6 +540,9 @@ export class EventRouter {
     } catch (err) {
       this.logger.warn(`[Chorus] markQueued failed for ${label}: ${err}`);
     }
-    this.queue.enqueue(key, () => this.waker.wake(n, key, attribution));
+    // Enqueue an opaque DATA payload (add-daemon-wake-coalescing §C4), NOT a thunk: the
+    // queue coalesces all same-key pending items and hands the whole batch to its runBatch
+    // (wired to waker.wakeBatch in daemon.mjs). markQueued was already called per-item above.
+    this.queue.enqueue(key, { notification: n, attribution });
   }
 }

package/cli/prompts.mjs

@@ -25,6 +25,7 @@
  * @property {string} actorType
  * @property {string} actorUuid
  * @property {string} actorName
+ * @property {{type: string, uuid: string, name: string} | null} [orchestrator]
  * @property {string} [instructionText]  Free-text body of a `human_instruction` wake
  *   (子1 — daemon-session-conversation). The server denormalizes the canonical turn
  *   promptText onto the wake notification so the daemon reads it in the
@@ -40,6 +41,29 @@ function mentionGuidance(n, entityType) {
   );
 }
 
+/**
+ * Orchestrator-handoff guidance, appended to every wake body by buildPrompt. This is
+ * the SINGLE home of the "hand back to the agent that dispatched you" instruction —
+ * it is runtime PE (it depends on who the wake resolved as orchestrator), so it lives
+ * here in the wake prompt, NOT in the static skill docs. Its OpenClaw twin is
+ * `buildOrchestratorGuidance` in packages/openclaw-plugin/src/event-router.ts —
+ * KEEP THE TWO WORDINGS IN SYNC.
+ * Returns null unless the resource has an AGENT orchestrator; a human-assigned
+ * resource hands back to the human via the per-event actor @mention (mentionGuidance).
+ * @param {NotificationDetail} n
+ */
+function orchestratorGuidance(n) {
+  if (n.orchestrator?.type !== "agent") return null;
+  return (
+    `Your orchestrator for this resource is @${n.orchestrator.name}.\n` +
+    `At a human-only gate you cannot cross, or when this child resource is complete, hand control ` +
+    `back by commenting on the resource and mentioning ` +
+    `@[${n.orchestrator.name}](agent:${n.orchestrator.uuid}) with the decision needed or completion ` +
+    `evidence, then leave any human-gated resource pending and end the turn. Do not @mention the ` +
+    `orchestrator for ordinary internal progress.`
+  );
+}
+
 /**
  * Shared headless preamble prepended to EVERY wake prompt (add-daemon-headless-
  * interaction-guard). A daemon-woken session is a headless `claude -p` run with no
@@ -96,7 +120,98 @@ export const HEADLESS_PREAMBLE = [
 export function buildPrompt(n) {
   const body = buildPromptBody(n);
   if (body == null) return null;
-  return `${HEADLESS_PREAMBLE}\n\n${body}`;
+  const handoff = orchestratorGuidance(n);
+  return `${HEADLESS_PREAMBLE}\n\n${body}${handoff ? `\n\n${handoff}` : ""}`;
+}
+
+/**
+ * Build ONE combined wake prompt for a coalesced batch of same-session notifications
+ * (add-daemon-wake-coalescing, tech design §C2). The daemon serializes wakes per session
+ * key; while a turn runs, later same-key wakes pile up and — when the slot frees — are
+ * drained together into a single `claude --resume` turn. This composes their one prompt.
+ *
+ * Rules:
+ *  - **Size 1** → delegate to `buildPrompt(n)` verbatim, so the single-event path is
+ *    BYTE-IDENTICAL to today (and all current prompt tests keep passing). This is keyed on
+ *    the count of RENDERABLE events (non-null body): a batch that reduces to a single
+ *    renderable event — e.g. a real wake plus an empty `human_instruction` — also takes
+ *    the single-event path.
+ *  - **Size > 1 renderable** → `HEADLESS_PREAMBLE` ONCE (it is a per-turn guard, paid once
+ *    per turn, not per event), then a short backlog preamble, then one labeled block per
+ *    event in ARRIVAL order, each block being the reused per-action `buildPromptBody(n)` so
+ *    every event keeps its own tool hints and @mention guidance.
+ *  - **Same-entity collapse (Q2)**: events sharing `(action, entityUuid)` collapse into one
+ *    block at the group's FIRST-SEEN position, noting the occurrence count and showing the
+ *    NEWEST message. This is safe only because such actions' full content is re-derivable
+ *    server-side (comments via chorus_get_comments, task lifecycle via chorus_get_*).
+ *  - **`human_instruction` is NEVER collapsed (Q3, Round-1 BLOCKER-2)**: every queued chat
+ *    message carries `action=human_instruction` and `entityUuid=directIdeaUuid`, and its
+ *    text lives ONLY on the turn/notification (not re-fetchable), so collapsing to
+ *    newest-only would silently drop earlier chat and defeat the feature. Each renders its
+ *    full body as its own block, in arrival order.
+ *  - Events whose body is null (empty `human_instruction`, non-wake action) are omitted; a
+ *    batch with no renderable event returns null (the router then spawns nothing).
+ *
+ * @param {NotificationDetail[]} notifications  Arrival-ordered batch (FIFO drain order).
+ * @returns {string | null}
+ */
+export function buildBatchPrompt(notifications) {
+  if (!Array.isArray(notifications) || notifications.length === 0) return null;
+
+  // Keep only events with a renderable per-action body, in arrival order.
+  const items = [];
+  for (const n of notifications) {
+    const body = buildPromptBody(n);
+    if (body != null) items.push({ n, body });
+  }
+  if (items.length === 0) return null;
+  // One renderable event → byte-identical single-event prompt (delegates to buildPrompt so
+  // the exact "PREAMBLE\n\nbody" shape is preserved). Covers a true batch of size 1 and a
+  // batch that reduced to one renderable event after null-body events were dropped.
+  if (items.length === 1) return buildPrompt(items[0].n);
+
+  // Group into ordered blocks. Collapsible actions merge by (action, entityUuid) at their
+  // first-seen slot; human_instruction is exempt and always gets its own block.
+  const blocks = [];
+  const collapseIndex = new Map(); // "action::entityUuid" -> index into `blocks`
+  for (const { n, body } of items) {
+    if (n.action === "human_instruction") {
+      blocks.push({ notif: n, body, count: 1 });
+      continue;
+    }
+    const groupKey = `${n.action}::${n.entityUuid ?? ""}`;
+    const existing = collapseIndex.get(groupKey);
+    if (existing != null) {
+      const g = blocks[existing];
+      g.count += 1;
+      g.notif = n; // newest wins (arrival order → last member is newest)
+      g.body = body; // newest body
+    } else {
+      collapseIndex.set(groupKey, blocks.length);
+      blocks.push({ notif: n, body, count: 1 });
+    }
+  }
+
+  // Backlog preamble. N = number of renderable events that arrived (not the collapsed block
+  // count) — collapse is a rendering optimization; each collapsed block states its own count.
+  const backlogPreamble =
+    `You have ${items.length} queued Chorus events on this session that arrived while you ` +
+    `were busy — handle them together, in order; each is labeled with its type below.`;
+
+  const rendered = blocks.map((g, idx) => {
+    const n = g.notif;
+    const entityType = n.entityType || "session";
+    const entityUuid = n.entityUuid || "";
+    const header = `### Event ${idx + 1} — ${n.action} on ${entityType} ${entityUuid}`.replace(/\s+$/, "");
+    const collapseNote =
+      g.count > 1
+        ? `\n(${g.count} ${n.action} events on this ${entityType} arrived — showing the newest ` +
+          `below; earlier ones are re-derivable via the entity's own chorus_get_* tools.)`
+        : "";
+    return `${header}${collapseNote}\n\n${g.body}`;
+  });
+
+  return [HEADLESS_PREAMBLE, backlogPreamble, ...rendered].join("\n\n");
 }
 
 /**

package/cli/turn-reporter.mjs

@@ -52,7 +52,7 @@ export const TURN_INTERRUPT_REASONS = new Set([
  *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
  *   fetchImpl?: typeof fetch,             Injectable for tests.
  * }} opts
- * @returns {(params: { sessionId: string, status: "running"|"ended"|"interrupted", entityType?: string|null, entityUuid?: string|null, interruptedReason?: "user"|"crash"|"shutdown"|"invalid_path"|null, transcriptRelayError?: string|null, usage?: import("./upload-hooks.mjs").TokenUsage|null }) => Promise<void>}
+ * @returns {(params: { sessionId: string, status: "running"|"ended"|"interrupted", entityType?: string|null, entityUuid?: string|null, interruptedReason?: "user"|"crash"|"shutdown"|"invalid_path"|null, transcriptRelayError?: string|null, usage?: import("./upload-hooks.mjs").TokenUsage|null, coalescedCount?: number }) => Promise<void>}
  */
 export function createTurnReporter(opts) {
   const logger = opts.logger ?? NOOP_LOGGER;
@@ -76,6 +76,7 @@ export function createTurnReporter(opts) {
     transcriptRelayError,
     usage,
     backendSessionId,
+    coalescedCount,
   }) {
     if (typeof sessionId !== "string" || !sessionId || !TURN_STATUSES.has(status)) {
       logger.warn(
@@ -111,6 +112,9 @@ export function createTurnReporter(opts) {
       // only on a terminal edge. No validation here — usage is an opaque nested object.
       usage,
       backendSessionId,
+      // Coalesced-wake count (add-daemon-wake-coalescing): threaded straight through; the
+      // client sends it only on the → running edge and only when > 1 (a single wake omits it).
+      coalescedCount,
     });
   };
 }

package/cli/wake-queue.mjs

@@ -1,14 +1,22 @@
 // cli/wake-queue.mjs
-// Per-key FIFO scheduler with a global concurrency cap. This is what makes the
-// idea_root session anchor safe (cli-daemon spec "Per-root-idea wake
-// serialization", design.md "Concurrency model"):
-//   • within one key (root idea) → strictly serial, FIFO. The 2nd wake waits
-//     for the 1st subprocess to exit, so we never run two
+// Per-key FIFO scheduler with a global concurrency cap, coalescing same-key
+// wakes into batches. This is what makes the idea_root session anchor safe
+// (cli-daemon spec "Per-root-idea wake serialization", design.md "Concurrency
+// model") AND implements daemon-wake-coalescing (design.md §C1):
+//   • within one key (root idea) → strictly serial, FIFO. The next batch waits
+//     for the current runBatch to settle, so we never run two
 //     `claude --resume <sameSessionId>` against one session.
+//   • coalescing: when a key's slot frees, the ENTIRE pending array for that key
+//     is drained (splice) and delivered to runBatch ONCE as a single batch. So
+//     N events that pile up while the previous turn runs become ONE turn.
+//     Natural batching only — NO debounce/collect timer, NO batch-size cap.
 //   • across keys → concurrent, bounded by maxConcurrency.
 //   • enqueue() returns immediately — never blocks the SSE loop.
-//   • a task that throws is logged and the next task for that key proceeds (a
-//     poisoned wake must not wedge the key's queue forever).
+//   • a batch whose runBatch throws is logged and the next batch for that key
+//     proceeds (a poisoned wake must not wedge the key's queue forever).
+// The queue carries opaque DATA items (the router passes `{ notification,
+// attribution }`); it never introspects them — the runBatch callback (supplied
+// at construction, wired to waker.wakeBatch in daemon.mjs) does.
 // Plain ESM, zero deps, in-memory.
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
@@ -18,41 +26,49 @@ export class WakeQueue {
    * @param {{
    *   maxConcurrency?: number,
    *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
+   *   runBatch?: (key: string, items: any[]) => Promise<void>,
    * }} [opts]
    */
   constructor(opts = {}) {
     this.maxConcurrency = opts.maxConcurrency ?? 4;
     this.logger = opts.logger ?? NOOP_LOGGER;
-    /** @type {Map<string, Array<() => Promise<void>>>} pending tasks per key. */
+    // The batch runner: called ONCE per drained batch with every pending item
+    // for the key. Defaults to a no-op so an unwired queue never throws (the
+    // daemon always supplies the real waker.wakeBatch runner).
+    this.runBatch = opts.runBatch ?? (async () => {});
+    /** @type {Map<string, any[]>} pending data items per key. */
     this.pending = new Map();
-    /** @type {Set<string>} keys with a task currently running. */
+    /** @type {Set<string>} keys with a batch currently running. */
     this.running = new Set();
     /** @type {string[]} keys waiting for a global concurrency slot. */
     this.readyKeys = [];
     this.activeCount = 0;
-    // Graceful-shutdown latch: once set, #pump starts NOTHING new — in-flight tasks
-    // finish (drain observes them) but queued work stays queued and dies with the
-    // process. Never cleared; a stopping queue is on its way out.
+    // Graceful-shutdown latch: once set, #pump starts NOTHING new — in-flight
+    // batches finish (drain observes them) but queued work stays queued and dies
+    // with the process. Never cleared; a stopping queue is on its way out.
     this.stopped = false;
   }
 
-  /** Stop starting new tasks (graceful shutdown). In-flight tasks are unaffected. */
+  /** Stop starting new batches (graceful shutdown). In-flight batches are unaffected. */
   stop() {
     this.stopped = true;
   }
 
   /**
-   * Enqueue a wake task under a key. Returns immediately. The task is a thunk
-   * returning a promise (the actual wake). Same key → serialized; different
-   * keys → concurrent up to maxConcurrency.
+   * Enqueue an opaque data item under a key. Returns immediately. Items on the
+   * same key coalesce: while a key's batch runs, later items pile up and are
+   * drained together as ONE batch when the slot frees. Different keys run
+   * concurrently up to maxConcurrency.
    * @param {string} key
-   * @param {() => Promise<void>} task
+   * @param {any} item  opaque data (e.g. `{ notification, attribution }`)
    */
-  enqueue(key, task) {
+  enqueue(key, item) {
     if (!this.pending.has(key)) this.pending.set(key, []);
-    this.pending.get(key).push(task);
+    this.pending.get(key).push(item);
     // A key becomes "ready" to claim a global slot only when it's not already
-    // running (serial-per-key) and not already queued for a slot.
+    // running (serial-per-key) and not already queued for a slot. While it IS
+    // running, later items simply accumulate in `pending` and are picked up by
+    // the next batch — this is where coalescing happens.
     if (!this.running.has(key) && !this.readyKeys.includes(key)) {
       this.readyKeys.push(key);
     }
@@ -65,7 +81,7 @@ export class WakeQueue {
   }
 
   /**
-   * Snapshot of the keys with a task currently running (observability read).
+   * Snapshot of the keys with a batch currently running (observability read).
    * Returns a fresh array so a caller can't mutate the internal Set.
    * @returns {string[]}
    */
@@ -74,7 +90,7 @@ export class WakeQueue {
   }
 
   /**
-   * Snapshot of the keys that have at least one task still waiting to run —
+   * Snapshot of the keys that have at least one item still waiting to run —
    * i.e. enqueued but not yet started (observability read). A key that is
    * currently running with no further queued work is NOT pending. Returns a
    * fresh array so a caller can't mutate internal state.
@@ -85,13 +101,13 @@ export class WakeQueue {
   }
 
   /**
-   * Wait (bounded) for every in-flight task to finish — the graceful-shutdown drain
+   * Wait (bounded) for every in-flight batch to finish — the graceful-shutdown drain
    * (fix-daemon-exit-orphan-running-turn). Resolves `true` when the queue went idle
-   * (no active task) within `timeoutMs`, `false` on timeout — the caller exits
+   * (no active batch) within `timeoutMs`, `false` on timeout — the caller exits
    * anyway and leaves the rest to the server-side reconcile backstop. Pending
-   * (not-yet-started) tasks are NOT waited for: a shutting-down daemon stops
+   * (not-yet-started) items are NOT waited for: a shutting-down daemon stops
    * starting new work, so only the in-flight subprocesses (and their exit reports)
-   * matter. Polling (50ms) keeps this zero-dep and independent of task internals.
+   * matter. Polling (50ms) keeps this zero-dep and independent of batch internals.
    * @param {number} timeoutMs
    * @returns {Promise<boolean>}
    */
@@ -112,33 +128,39 @@ export class WakeQueue {
       if (this.running.has(key)) continue; // already running under another slot
       const queue = this.pending.get(key);
       if (!queue || queue.length === 0) continue;
-      this.#runNext(key);
+      this.#startBatch(key);
     }
   }
 
-  /** Run the next task for a key, then chain to the following one. */
-  #runNext(key) {
+  /**
+   * Drain the ENTIRE pending array for a key into one batch and run it, then
+   * chain to the following batch. No batch-size cap (design.md §C1, Q7).
+   */
+  #startBatch(key) {
     const queue = this.pending.get(key);
     if (!queue || queue.length === 0) {
       this.running.delete(key);
       return;
     }
-    const task = queue.shift();
+    // Coalesce: take everything pending for this key right now as one batch.
+    // Items that arrive after this splice accumulate for the NEXT batch.
+    const items = queue.splice(0);
     this.running.add(key);
     this.activeCount++;
 
     Promise.resolve()
-      .then(task)
+      .then(() => this.runBatch(key, items))
       .catch((err) => {
-        // Poisoned wake: log, do NOT let it wedge the key's queue.
-        this.logger.warn(`[Chorus] wake task for ${key} failed: ${err}`);
+        // Poisoned batch: log, do NOT let it wedge the key's queue.
+        this.logger.warn(`[Chorus] wake batch for ${key} failed: ${err}`);
       })
       .finally(() => {
         this.activeCount--;
         const remaining = this.pending.get(key);
         if (remaining && remaining.length > 0) {
-          // Same key still has work → it must run serially. Re-mark ready;
-          // #pump will pick it up (respecting the global cap).
+          // Same key accumulated more work while this batch ran → it must run
+          // serially as the next batch. Re-mark ready; #pump will pick it up
+          // (respecting the global cap).
           if (!this.readyKeys.includes(key)) this.readyKeys.push(key);
           this.running.delete(key); // free the key so #pump can re-claim it
         } else {

package/cli/waker.mjs

@@ -12,11 +12,14 @@
 // the server-resolved root, NEVER re-derived from the (direct-idea) serialization
 // key.
 //
-// Module contract (design.md): Waker.wake(notification, key, attribution) →
-// Promise<void>. A failure is logged and swallowed — it must never crash the
-// daemon (no-silent-errors: visible log, no throw).
-
-import { buildPrompt } from "./prompts.mjs";
+// Module contract (design.md): Waker.wakeBatch(notifications, key, attribution) →
+// Promise<void> runs ONE coalesced turn for a batch of same-session notifications
+// (add-daemon-wake-coalescing); Waker.wake(n, key, attribution) is a thin wrapper =
+// wakeBatch([n], ...) so a batch of one is byte-identical to the pre-coalescing single
+// wake. A failure is logged and swallowed — it must never crash the daemon
+// (no-silent-errors: visible log, no throw).
+
+import { buildBatchPrompt } from "./prompts.mjs";
 import { writeMcpConfig } from "./mcp-config.mjs";
 import { isNewSession } from "./claude-spawner.mjs";
 import { killProcessTree, DEFAULT_SIGINT_TIMEOUT_MS } from "./process-killer.mjs";
@@ -320,49 +323,122 @@ export class Waker {
   }
 
   /**
-   * Run one wake. Never throws.
+   * Run one wake. Never throws. Thin wrapper over {@link wakeBatch} with a batch of one,
+   * so a single wake is byte-identical to the pre-coalescing behavior (prompt, execution
+   * row, turn accounting, coalescedCount = 1).
    * @param {import("./prompts.mjs").NotificationDetail} notification
    * @param {string} key  The serialization key (from keyFor) — anchored on the direct idea.
    * @param {{ rootIdeaUuid?: string|null, directIdeaUuid?: string|null }} [attribution]
-   *   Server-resolved ids from keyFor. `rootIdeaUuid` → execution snapshot;
-   *   `directIdeaUuid` → the deterministic Claude session id (when the entity has
-   *   an idea ancestor). When there is no direct idea, the session is anchored on
-   *   the entity's own uuid instead (see below).
    */
   async wake(notification, key, attribution) {
+    return this.wakeBatch([notification], key, attribution);
+  }
+
+  /**
+   * Run ONE coalesced turn for a batch of same-session notifications
+   * (add-daemon-wake-coalescing, Tech Design §C3). The WakeQueue drains all same-key
+   * pending wakes and hands them here as one batch; this composes their single combined
+   * prompt (buildBatchPrompt), spawns ONE subprocess (one `claude --resume <anchor>`), and
+   * accounts for the whole thing as ONE running turn. Never throws.
+   *
+   * A batch of ONE is byte-identical to the pre-coalescing single wake: `buildBatchPrompt`
+   * delegates to `buildPrompt`, the execution row + turn-advance carry the item's OWN
+   * entity, and `coalescedCount = 1` (so the wire is unchanged).
+   *
+   * Execution snapshot (Q6): a coalesced batch (> 1) is anchored on the SESSION, so it emits
+   * ONE running row synthesized from `attribution` — `idea:<directIdeaUuid>` (NOT necessarily
+   * one of the merged items — a batch of mentions on child tasks A+B under idea D has no
+   * `idea:D` item, yet the anchor IS `idea:D`), else the ad-hoc entity. Every drained/merged
+   * resource is removed from the executions map so the server reconcile ends its queued row.
+   *
+   * @param {import("./prompts.mjs").NotificationDetail[]} notifications  Arrival-ordered batch.
+   * @param {string} key  The serialization key (from keyFor) — shared by every item.
+   * @param {{ rootIdeaUuid?: string|null, directIdeaUuid?: string|null }} [attribution]
+   *   Server-resolved ids (shared across the batch — the key IS `idea:<directIdeaUuid>`, so
+   *   all items carry the same ids). `rootIdeaUuid` → snapshot; `directIdeaUuid` → session anchor.
+   */
+  async wakeBatch(notifications, key, attribution) {
     let cfg;
-    const entity = this.#entityOf(notification);
-    const execKey = entity ? this.#execKey(entity.entityType, entity.entityUuid) : null;
+    const list = Array.isArray(notifications) ? notifications : [];
+    // Physical batch size — how many wakes were coalesced into this one turn. Drives the
+    // session-anchor synthesis (a coalesced batch shows ONE synthesized idea row) and the
+    // arrival log label. Independent of the wire count below.
+    const batchSize = list.length;
+    // The number of coalesced wakes reported to the server on the running-transition so it can
+    // settle the next (coalescedCount − 1) same-session pending turns. Counted as ONLY the
+    // TURN-BACKED items: each notification-backed wake created a server-side pending
+    // DaemonSessionTurn at the chokepoint, so those are the turns the server can settle.
+    //
+    // A synthetic `resource_resumed` (子3 control-channel resume) is EXCLUDED: it is NEVER a
+    // persisted notification and creates NO server pending turn (src/services/notification-turn.ts
+    // deliberately omits it from the trigger map), so counting it would inflate N. An inflated N
+    // lets the server's `take: coalescedCount-1` seq-window settlement over-reach and mark a
+    // genuinely-separate post-drain pending turn as `merged` — which getPendingTurnsForConnection
+    // then never re-dispatches, silently dropping a piled-up chat message (defeats Q3).
+    // `resource_resumed` is the ONLY synthetic, non-notification wake action; every other
+    // WAKE_ACTIONS entry (incl. human_instruction) is notification-backed and turn-creating. A
+    // batch that reduces to 0 or 1 turn-backed items reports ≤ 1, which the client omits from the
+    // wire (see #advanceTurn) so no settlement runs.
+    const coalescedCount = list.filter((n) => n?.action !== "resource_resumed").length;
+    const first = list[0];
     // Both ids come from the resolved `attribution` (supplied by keyFor via the
     // router) and are threaded SEPARATELY — NEVER sliced from `key`. The ROOT idea
     // is reported in the snapshot; the DIRECT idea is the preferred session anchor.
     const rootIdeaUuid = attribution?.rootIdeaUuid ?? null;
     const directIdeaUuid = attribution?.directIdeaUuid ?? null;
+    // The resources markQueued tracked for THIS batch — every item's own entity. They must
+    // all leave the executions map when the batch settles so the server reconcile ends the
+    // queued rows the batch coalesced away (a coalesced batch shows only ONE running row).
+    const drainedExecKeys = [];
+    for (const n of list) {
+      const e = this.#entityOf(n);
+      if (e) drainedExecKeys.push(this.#execKey(e.entityType, e.entityUuid));
+    }
+    // The session-anchor resource for the ONE running row:
+    //  - a coalesced batch (> 1) is anchored on the SESSION, synthesized from attribution:
+    //    idea:<directIdeaUuid> when idea-anchored (NOT necessarily one of the merged items),
+    //    else the ad-hoc entity (all ad-hoc items share one entity → the first item's entity).
+    //  - a single wake (batch of one) keeps the item's OWN entity — byte-identical to before.
+    const entity =
+      batchSize > 1 && directIdeaUuid
+        ? { entityType: "idea", entityUuid: directIdeaUuid }
+        : this.#entityOf(first);
+    const execKey = entity ? this.#execKey(entity.entityType, entity.entityUuid) : null;
     // Per-wake lifecycle logging: stamp the start so completion can report a
     // duration. `Date.now()` is fine here (runtime metric, not a resume seed).
     const startMs = Date.now();
     const target = entity ? `${entity.entityType}:${entity.entityUuid}` : key;
-    const sessionId = directIdeaUuid ?? notification.entityUuid ?? null;
+    const sessionId = directIdeaUuid ?? first?.entityUuid ?? null;
     const requestedRuntimeCwd =
-      typeof notification?.runtimeCwd === "string" && notification.runtimeCwd
-        ? notification.runtimeCwd
+      typeof first?.runtimeCwd === "string" && first.runtimeCwd
+        ? first.runtimeCwd
         : null;
+    // Arrival label: the single action for a batch of one, else a batch count (the physical
+    // number of merged events — includes any resource_resumed, which is a real wake even
+    // though it is not turn-backed for settlement).
+    const arrivalAction =
+      batchSize > 1 ? `coalesced batch of ${batchSize}` : first?.action;
     try {
-      const prompt = buildPrompt(notification);
+      const prompt = buildBatchPrompt(list);
       if (!prompt) {
-        this.logger.info(`[Chorus] no wake prompt for action "${notification.action}" — skipping`);
+        this.logger.info(`[Chorus] no wake prompt for ${arrivalAction} on ${key} — skipping`);
         return;
       }
 
-      // Lifecycle line 1 — arrival: which action targets which idea/task/entity.
-      this.logger.info(`[Chorus] ▶ wake: ${notification.action} → ${target}`);
+      // Lifecycle line 1 — arrival: which action(s) target which idea/task/entity.
+      this.logger.info(`[Chorus] ▶ wake: ${arrivalAction} → ${target}`);
 
-      // Transition this resource to RUNNING with a start timestamp and emit a
-      // fresh snapshot, so the server/UI sees it leave the queue and begin
-      // executing. Report the server-resolved ROOT idea (not the direct-idea key).
-      // `child` starts null and is filled in by the spawner's onChild the moment the
-      // subprocess spawns (子3) — so the control handler can target it for interrupt.
+      // Transition to RUNNING and emit a fresh snapshot. First REMOVE every merged/drained
+      // resource (so the server reconcile ends their queued rows), then set the ONE
+      // synthesized anchor running row with a start timestamp — so the server/UI sees the
+      // batch as a single running entry with no leftover queued entries. Report the
+      // server-resolved ROOT idea (not the direct-idea key). `child` starts null and is
+      // filled in by the spawner's onChild the moment the subprocess spawns (子3) — so the
+      // control handler can target it for interrupt.
       if (entity && execKey) {
+        for (const dk of drainedExecKeys) {
+          if (dk !== execKey) this.executions.delete(dk);
+        }
         this.executions.set(execKey, {
           entityType: entity.entityType,
           entityUuid: entity.entityUuid,
@@ -416,7 +492,7 @@ export class Waker {
         this.logger.info(`[Chorus] dispatching session ${sessionId ?? "(none)"}`);
       }
       if (this.verbose) {
-        this.logger.info(`[Chorus]   cwd=${cwd} action=${notification.action} root=${rootIdeaUuid ?? "(none)"}`);
+        this.logger.info(`[Chorus]   cwd=${cwd} action=${arrivalAction} root=${rootIdeaUuid ?? "(none)"}`);
       }
 
       cfg = this.writeMcpConfigFn(this.creds);
@@ -456,7 +532,10 @@ export class Waker {
             turnAdvancedToRunning = true;
             // Fire-and-forget; #advanceTurn swallows + logs its own failures so a
             // turn-report error never crashes the spawn callback (no-silent-errors).
-            this.#advanceTurn(sessionId, "running", entity).catch(() => {});
+            // The coalescedCount rides this → running edge so the server settles the
+            // (count − 1) same-session pending turns coalesced into this one (a single
+            // wake reports 1, which the client omits from the wire).
+            this.#advanceTurn(sessionId, "running", entity, null, null, null, null, coalescedCount).catch(() => {});
           }
         },
         onMessage: (message) => {
@@ -577,7 +656,7 @@ export class Waker {
       );
       if (this.verbose) {
         this.logger.info(
-          `[Chorus]   action=${notification.action} session=${result?.sessionId} key=${key}`
+          `[Chorus]   action=${arrivalAction} session=${result?.sessionId} key=${key}`
         );
       }
     } catch (err) {
@@ -593,17 +672,22 @@ export class Waker {
         );
       }
     } finally {
-      // Wake finished (cleanly or not): the resource leaves the active set. Drop
-      // it and emit a fresh snapshot so the server ends its running/queued row.
-      // The server reconcile is snapshot-authoritative, so absence == ended. Also
-      // clear the per-entity interrupting flag so it can never leak into a later
-      // wake of the same entity.
+      // Wake finished (cleanly or not): EVERY resource this batch touched leaves the active
+      // set — the running anchor AND any drained/merged resources that were never promoted to
+      // the running row (e.g. a null-prompt batch that returned before the running transition,
+      // so their queued rows still linger). Drop them all and emit ONE fresh snapshot so the
+      // server ends their running/queued rows. The server reconcile is snapshot-authoritative,
+      // so absence == ended. Also clear the anchor's interrupting flag so it can never leak
+      // into a later wake of the same entity.
+      let changed = false;
+      for (const dk of drainedExecKeys) {
+        if (this.executions.delete(dk)) changed = true;
+      }
       if (execKey) {
         this.interrupting.delete(execKey);
-        if (this.executions.delete(execKey)) {
-          this.#emitExecutionChange();
-        }
+        if (this.executions.delete(execKey)) changed = true;
       }
+      if (changed) this.#emitExecutionChange();
       try {
         cfg?.cleanup?.();
       } catch {
@@ -647,8 +731,12 @@ export class Waker {
    * @param {string|null} [transcriptRelayError]
    * @param {import("./upload-hooks.mjs").TokenUsage|null} [usage]  Per-turn token usage
    *   (daemon-token-usage); forwarded only on a terminal edge, mirroring transcriptRelayError.
+   * @param {string|null} [backendSessionId]
+   * @param {number} [coalescedCount]  Number of wakes coalesced into this turn
+   *   (add-daemon-wake-coalescing); forwarded only on the → running edge and only when > 1,
+   *   so a single wake (default 1) leaves the field absent — byte-identical to before.
    */
-  async #advanceTurn(sessionId, status, entity, interruptedReason = null, transcriptRelayError = null, usage = null, backendSessionId = null) {
+  async #advanceTurn(sessionId, status, entity, interruptedReason = null, transcriptRelayError = null, usage = null, backendSessionId = null, coalescedCount = 1) {
     try {
       await this.advanceTurn({
         sessionId,
@@ -659,6 +747,7 @@ export class Waker {
         ...(transcriptRelayError ? { transcriptRelayError } : {}),
         ...(usage ? { usage } : {}),
         ...(backendSessionId ? { backendSessionId } : {}),
+        ...(status === "running" && coalescedCount > 1 ? { coalescedCount } : {}),
       });
     } catch (err) {
       this.logger.warn(