@chorus-aidlc/chorus 0.10.0 → 0.11.1

package/cli/mcp-config.mjs

@@ -0,0 +1,58 @@
+// cli/mcp-config.mjs
+// Writes the --mcp-config JSON that wires the spawned headless Claude to THIS
+// daemon's Chorus server (url + cho_ key), into the OS temp dir (never a
+// hardcoded /tmp), and cleans it up. Plain ESM, zero deps.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Build the MCP config object that exposes the Chorus server to the spawned
+ * Claude as a `chorus` MCP server over Streamable HTTP (mirrors the entry the
+ * OpenClaw plugin writes — see mcp-registration.ts).
+ * @param {{ url: string, apiKey: string }} creds
+ */
+export function buildMcpConfig({ url, apiKey }) {
+  return {
+    mcpServers: {
+      chorus: {
+        type: "http",
+        url: `${url.replace(/\/$/, "")}/api/mcp`,
+        headers: { Authorization: `Bearer ${apiKey}` },
+      },
+    },
+  };
+}
+
+/**
+ * Write the MCP config to a fresh temp file under os.tmpdir() and return its
+ * path plus a cleanup function. The caller MUST call cleanup() when the wake
+ * completes (or register it for process exit).
+ *
+ * @param {{ url: string, apiKey: string }} creds
+ * @param {{ tmp?: string, mkdtemp?: typeof mkdtempSync, write?: typeof writeFileSync, rm?: typeof rmSync }} [deps]
+ * @returns {{ path: string, cleanup: () => void }}
+ */
+export function writeMcpConfig(creds, deps = {}) {
+  const tmp = deps.tmp ?? tmpdir();
+  const mkdtemp = deps.mkdtemp ?? mkdtempSync;
+  const write = deps.write ?? writeFileSync;
+  const rm = deps.rm ?? rmSync;
+
+  const dir = mkdtemp(join(tmp, "chorus-mcp-"));
+  const path = join(dir, "mcp.json");
+  write(path, JSON.stringify(buildMcpConfig(creds), null, 2), { mode: 0o600 });
+
+  let cleaned = false;
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    try {
+      rm(dir, { recursive: true, force: true });
+    } catch {
+      // best-effort; temp dir is reclaimed by the OS regardless
+    }
+  };
+  return { path, cleanup };
+}

package/cli/process-killer.mjs

@@ -0,0 +1,205 @@
+// cli/process-killer.mjs
+// Two-stage, cross-platform process-tree killer for the daemon's reverse control
+// channel (子3 — daemon-interrupt-resume, Tech Design "Killer contract"). When an
+// authorized interrupt is verified, the daemon must STOP a running headless-Claude
+// subprocess — first gracefully (SIGINT, so the model can flush in-progress work),
+// then forcefully if it does not exit within a configurable window. Plain ESM, ZERO
+// new npm deps (CLAUDE.md pitfall #9) and Bash-3.2-safe (no shell touched).
+//
+// Why a process TREE, not just the direct child:
+//   • POSIX: Claude may itself spawn children. Linux does NOT cascade a signal to a
+//     parent's children (Node docs: "On Linux, child processes of child processes
+//     will not be terminated when attempting to kill their parent"). So the daemon
+//     spawns the child `detached: true` — which makes it a PROCESS GROUP LEADER
+//     (its pgid === its pid) — and we signal the whole GROUP via the negative-pid
+//     form `process.kill(-pid, sig)`. That reaches every descendant in the group.
+//   • Windows: there is no per-tree signal. We escalate with the platform
+//     `taskkill /PID <pid> /T /F` command — `/T` ends the process AND its child
+//     processes (the tree), `/F` forces termination. Verified against Microsoft
+//     Learn's taskkill reference. The graceful stage is best-effort `child.kill()`
+//     on the direct process only (Node delivers SIGINT to the child on Windows; the
+//     signal cannot reach a tree there). The Windows path is NOT runtime-verifiable
+//     in this (POSIX) environment — re-verify on a real Windows host before claiming
+//     Windows support.
+//
+// Contract (Tech Design): killProcessTree(child, { sigintTimeoutMs, platform,
+// logger, spawnImpl, nowKill }) → Promise<{ killed, escalated, signaled }>. It is
+// pure-ish (platform + spawn injectable for tests), NEVER throws into the wake path
+// (every signal/spawn is try/caught), and LOGS visibly (memory: no-silent-errors).
+
+import { spawn as nodeSpawn } from "node:child_process";
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+
+/** Default escalation window before a forceful kill (Tech Design / spec: 10s). */
+export const DEFAULT_SIGINT_TIMEOUT_MS = 10_000;
+
+/**
+ * Send SIGINT to a POSIX child's PROCESS GROUP (negative pid). The child must have
+ * been spawned `detached: true` so it leads its own group and the group kill reaches
+ * grandchildren. Returns true iff the signal was delivered without throwing.
+ * @param {number} pid
+ * @param {string} signal  "SIGINT" | "SIGKILL"
+ * @param {(pid: number, signal: string) => void} killImpl  injectable process.kill
+ * @param {{warn(m:string):void}} logger
+ * @returns {boolean}
+ */
+function signalGroup(pid, signal, killImpl, logger) {
+  try {
+    // Negative pid → signal the entire process group led by `pid`. This is the
+    // POSIX semantics process.kill(2) implements; Node forwards it verbatim.
+    killImpl(-pid, signal);
+    return true;
+  } catch (err) {
+    // ESRCH (already gone) is the common, benign case after a graceful exit; any
+    // other error (e.g. EPERM) is logged but never thrown — the wake path must not
+    // crash because a stop signal failed.
+    logger.warn(`[Chorus] kill(-${pid}, ${signal}) failed: ${err}`);
+    return false;
+  }
+}
+
+/**
+ * Two-stage stop of a running subprocess TREE. Never throws.
+ *
+ * Stage 1 (graceful): SIGINT.
+ *   • POSIX: `process.kill(-pid, "SIGINT")` — the whole group.
+ *   • Windows: best-effort `child.kill("SIGINT")` on the direct process (no tree
+ *     signal exists; taskkill below is the tree-reaching escalation).
+ * Then wait up to `sigintTimeoutMs` for the child to exit (resolved via the child's
+ * own 'exit'/'close' — the caller observes that and aborts our timer by resolving
+ * early through `child.exitObserved`). If the child has not exited when the timer
+ * fires:
+ * Stage 2 (forceful):
+ *   • POSIX: `process.kill(-pid, "SIGKILL")` — the whole group.
+ *   • Windows: spawn `taskkill /PID <pid> /T /F`.
+ *
+ * @param {{ pid?: number, killed?: boolean, kill?: Function, once?: Function, on?: Function }} child
+ *   The live ChildProcess (or a test double). `pid` MUST be present to target a tree.
+ * @param {{
+ *   sigintTimeoutMs?: number,
+ *   platform?: NodeJS.Platform,
+ *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
+ *   killImpl?: (pid: number, signal: string) => void,  Injectable process.kill (POSIX group signal).
+ *   spawnImpl?: typeof nodeSpawn,                       Injectable spawn (Windows taskkill).
+ *   hasExited?: () => boolean,                          Probe: has the child already exited?
+ *   waitForExit?: (ms: number) => Promise<boolean>,     Resolve true if child exits within ms, else false.
+ * }} [opts]
+ * @returns {Promise<{ signaled: boolean, killed: boolean, escalated: boolean }>}
+ *   signaled: the graceful SIGINT was delivered.
+ *   escalated: a forceful kill was issued (child did not exit within the window).
+ *   killed: a stop action (graceful or forceful) was issued at all.
+ */
+export async function killProcessTree(child, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const logger = opts.logger ?? NOOP_LOGGER;
+  const killImpl = opts.killImpl ?? ((pid, signal) => process.kill(pid, signal));
+  const spawnImpl = opts.spawnImpl ?? nodeSpawn;
+  const sigintTimeoutMs = opts.sigintTimeoutMs ?? DEFAULT_SIGINT_TIMEOUT_MS;
+  const isWin = platform === "win32";
+
+  if (!child || typeof child.pid !== "number") {
+    // No live process to target — log and no-op (never throw into the wake path).
+    logger.warn("[Chorus] killProcessTree: no child pid to target; ignoring");
+    return { signaled: false, killed: false, escalated: false };
+  }
+  const pid = child.pid;
+
+  // --- Stage 1: graceful SIGINT ---
+  let signaled;
+  if (isWin) {
+    // Windows: deliver SIGINT to the direct child only (best-effort). Node maps
+    // SIGINT to a console-stop on Windows; it cannot reach a tree there.
+    try {
+      signaled = child.kill?.("SIGINT") ?? false;
+    } catch (err) {
+      logger.warn(`[Chorus] child.kill("SIGINT") failed: ${err}`);
+      signaled = false;
+    }
+    logger.info(`[Chorus] interrupt: sent SIGINT to pid ${pid} (windows, direct child)`);
+  } else {
+    signaled = signalGroup(pid, "SIGINT", killImpl, logger);
+    logger.info(`[Chorus] interrupt: sent SIGINT to process group -${pid} (posix)`);
+  }
+
+  // --- Wait for graceful exit within the window ---
+  const exitedGracefully = await waitForChildExit(child, sigintTimeoutMs, opts, logger);
+  if (exitedGracefully) {
+    logger.info(`[Chorus] interrupt: pid ${pid} exited gracefully within ${sigintTimeoutMs}ms`);
+    return { signaled, killed: true, escalated: false };
+  }
+
+  // --- Stage 2: forceful tree kill ---
+  if (isWin) {
+    // taskkill /PID <pid> /T /F — /T ends the tree (child processes), /F forces it.
+    try {
+      const tk = spawnImpl("taskkill", ["/PID", String(pid), "/T", "/F"], {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      // taskkill failures are logged, never thrown.
+      tk?.on?.("error", (err) => logger.warn(`[Chorus] taskkill spawn error: ${err}`));
+      logger.info(`[Chorus] interrupt: escalated — taskkill /PID ${pid} /T /F (windows)`);
+    } catch (err) {
+      logger.warn(`[Chorus] taskkill escalation failed for pid ${pid}: ${err}`);
+    }
+  } else {
+    signalGroup(pid, "SIGKILL", killImpl, logger);
+    logger.info(`[Chorus] interrupt: escalated — SIGKILL to process group -${pid} (posix)`);
+  }
+  return { signaled, killed: true, escalated: true };
+}
+
+/**
+ * Resolve true if the child exits within `ms`, else false (timeout). Prefers an
+ * injected `waitForExit` (tests); otherwise races the child's own 'exit' event
+ * against a timer, with an immediate short-circuit if it has already exited.
+ * Never throws.
+ */
+async function waitForChildExit(child, ms, opts, logger) {
+  if (typeof opts.waitForExit === "function") {
+    try {
+      return await opts.waitForExit(ms);
+    } catch (err) {
+      logger.warn(`[Chorus] waitForExit probe failed: ${err}`);
+      return false;
+    }
+  }
+  // Already exited? (Node sets child.killed after a delivered signal, but exitCode/
+  // signalCode is the authoritative "has terminated" probe.)
+  const hasExited =
+    typeof opts.hasExited === "function"
+      ? safeBool(opts.hasExited, logger)
+      : child.exitCode !== null && child.exitCode !== undefined;
+  if (hasExited) return true;
+
+  return await new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(false), ms);
+    // unref so a pending timer never keeps the daemon process alive on shutdown.
+    timer?.unref?.();
+    try {
+      child.once?.("exit", () => finish(true));
+      child.once?.("close", () => finish(true));
+    } catch (err) {
+      logger.warn(`[Chorus] failed to attach exit listener: ${err}`);
+      finish(false);
+    }
+  });
+}
+
+/** Run a boolean probe, treating a throw as false (never propagate). */
+function safeBool(fn, logger) {
+  try {
+    return Boolean(fn());
+  } catch (err) {
+    logger.warn(`[Chorus] hasExited probe threw: ${err}`);
+    return false;
+  }
+}

package/cli/prompts.mjs

@@ -0,0 +1,273 @@
+// cli/prompts.mjs
+// Per-notification-action prompt builders. Ported from the OpenClaw plugin's
+// event-router wake messages. The spawned Claude is headless and acts only
+// through the chorus_* MCP tools — these prompts tell it what happened and
+// which tools to use.
+//
+// HEADLESS GUARD (add-daemon-headless-interaction-guard): a daemon-woken session
+// has NO human at the terminal, so it must never call AskUserQuestion or any
+// blocking terminal prompt — that would hang or be silently dropped. buildPrompt
+// prepends HEADLESS_PREAMBLE (below) to EVERY non-null wake body so the rule rides
+// every turn, new or --resume (the daemon rebuilds the prompt on each wake, so a
+// per-turn prefix persists across resumes without touching the spawn argv — there
+// is deliberately no --append-system-prompt; see claude-spawner.mjs). The preamble
+// also names the CHORUS_DAEMON_HEADLESS=1 env signal the spawner sets.
+
+/**
+ * @typedef {Object} NotificationDetail
+ * @property {string} uuid
+ * @property {string} projectUuid
+ * @property {string} entityType
+ * @property {string} entityUuid
+ * @property {string} entityTitle
+ * @property {string} action
+ * @property {string} message
+ * @property {string} actorType
+ * @property {string} actorUuid
+ * @property {string} actorName
+ * @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
+ *   `chorus_get_notifications` call it already makes (zero extra fetch); the
+ *   event-router threads it here. Present only for the `human_instruction` action.
+ */
+
+/** @param {NotificationDetail} n @param {string} entityType */
+function mentionGuidance(n, entityType) {
+  return (
+    `After completing your work, post a comment on this ${entityType} using ` +
+    `chorus_add_comment with @mention: @[${n.actorName}](${n.actorType}:${n.actorUuid})`
+  );
+}
+
+/**
+ * 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
+ * human at the terminal, so AskUserQuestion (and any blocking terminal prompt) reaches
+ * no one — it hangs or is dropped, stalling the agent or forcing a unilateral decision.
+ * This block tells the agent that fact and routes every human-decision point through
+ * Chorus's async channels instead.
+ *
+ * Wording note: the re-routing guidance names `chorus_add_comment` and describes the
+ * elaboration panel in prose ON PURPOSE — it must NOT embed the literal
+ * `chorus_pm_start_elaboration` / `chorus_pm_validate_elaboration` tool names, because
+ * this preamble rides EVERY wake including `elaboration_verified` (write-the-proposal),
+ * whose contract is that it never mentions the answer-questions tools. Keep it that way.
+ *
+ * Kept compact: it is paid on every wake, so each line costs tokens per wake.
+ */
+export const HEADLESS_PREAMBLE = [
+  "[Headless daemon session] You are a headless `claude -p` session woken by the Chorus",
+  "daemon. There is NO human at the terminal, and the environment variable",
+  "CHORUS_DAEMON_HEADLESS=1 is set.",
+  "",
+  "Do NOT call AskUserQuestion or any interactive / blocking terminal prompt — it reaches",
+  "no one and will hang or be silently dropped. Whenever you would ask the human something,",
+  "route it through Chorus instead: post a comment with chorus_add_comment and @mention the",
+  "requester, and/or open an elaboration round the human answers in the Chorus UI panel.",
+  "",
+  "A few examples (not exhaustive): when a skill says to present elaboration questions via",
+  "AskUserQuestion, open an elaboration round and @mention the requester in a comment so they",
+  "answer in the UI; when a skill says to ask permission before skipping a step, do not skip",
+  "silently — record the reason in a Chorus comment; when a skill offers to write a report,",
+  "create it directly or skip it, never prompt for it.",
+  "",
+  "After you post something that needs a human decision, END THE TURN and leave the work",
+  "pending — do not poll or wait for a synchronous reply. The human's later comment or",
+  "elaboration answer wakes a fresh turn that continues the work.",
+].join("\n");
+
+/**
+ * Build the wake prompt for a notification, or null if the action has no
+ * wake (caller ignores those). Prepends HEADLESS_PREAMBLE to every non-null body
+ * (a null body — unknown action / empty human_instruction — stays null so the router
+ * still skips it and no contentless subprocess is spawned). The per-action body is
+ * produced by buildPromptBody below.
+ * @param {NotificationDetail} n
+ * @returns {string | null}
+ */
+export function buildPrompt(n) {
+  const body = buildPromptBody(n);
+  if (body == null) return null;
+  return `${HEADLESS_PREAMBLE}\n\n${body}`;
+}
+
+/**
+ * The per-action wake body (without the headless preamble). Mirrors the OpenClaw
+ * event-router handlers; returns null for actions that have no wake.
+ * @param {NotificationDetail} n
+ * @returns {string | null}
+ */
+function buildPromptBody(n) {
+  switch (n.action) {
+    case "task_assigned":
+      return (
+        `[Chorus] Task assigned: ${n.entityTitle}. Task UUID: ${n.entityUuid}, ` +
+        `Project UUID: ${n.projectUuid}. Use chorus_get_task to review the task, ` +
+        `then chorus_claim_task to start work.\n${mentionGuidance(n, "task")}`
+      );
+    case "mentioned":
+      return (
+        `[Chorus] You were @mentioned in ${n.entityType} '${n.entityTitle}' ` +
+        `(entityType: ${n.entityType}, entityUuid: ${n.entityUuid}, projectUuid: ${n.projectUuid}): ${n.message}\n` +
+        `Review the ${n.entityType} and use chorus_get_comments (targetType: "${n.entityType}", ` +
+        `targetUuid: "${n.entityUuid}") to see the conversation, then respond.\n${mentionGuidance(n, n.entityType)}`
+      );
+    case "elaboration_requested":
+      return (
+        `[Chorus] Elaboration requested for idea '${n.entityTitle}' ` +
+        `(ideaUuid: ${n.entityUuid}, projectUuid: ${n.projectUuid}). ` +
+        `Use chorus_get_elaboration to review the questions.`
+      );
+    case "elaboration_answered":
+      return (
+        `[Chorus] Elaboration answers were submitted for idea '${n.entityTitle}' ` +
+        `(ideaUuid: ${n.entityUuid}, projectUuid: ${n.projectUuid}). Use chorus_get_elaboration to review the ` +
+        `answers, then either resolve the elaboration (chorus_pm_validate_elaboration) and proceed to a proposal, ` +
+        `or open another round (chorus_pm_start_elaboration) if gaps remain.\n${mentionGuidance(n, "idea")}`
+      );
+    case "elaboration_verified":
+      // A human clicked "Verify Elaborate" (add-elaboration-verify-wake). This is NOT a
+      // request to answer questions — the elaboration is DONE and the idea is now
+      // `elaborated`. The agent's job on this wake is to WRITE THE PROPOSAL via the
+      // existing proposal flow, anchored to the idea's same session that ran elaboration.
+      return (
+        `[Chorus] Elaboration for idea '${n.entityTitle}' was VERIFIED by a human ` +
+        `(ideaUuid: ${n.entityUuid}, projectUuid: ${n.projectUuid}). The idea is now elaborated — do NOT ` +
+        `answer elaboration questions. Proceed to WRITE THE PROPOSAL: gather context with chorus_get_idea and ` +
+        `chorus_get_elaboration, then author the proposal via the existing proposal flow ` +
+        `(chorus_pm_create_proposal / the proposal skill).\n${mentionGuidance(n, "idea")}`
+      );
+    case "proposal_rejected":
+      return (
+        `[Chorus] Proposal '${n.entityTitle}' was REJECTED (proposalUuid: ${n.entityUuid}, ` +
+        `projectUuid: ${n.projectUuid}). Review note: "${n.message}". Use chorus_get_proposal to review, ` +
+        `fix issues with chorus_pm_update_task_draft / chorus_pm_update_document_draft, then ` +
+        `chorus_pm_validate_proposal and chorus_pm_submit_proposal to resubmit.\n${mentionGuidance(n, "proposal")}`
+      );
+    case "proposal_approved":
+      return (
+        `[Chorus] Proposal '${n.entityTitle}' was APPROVED (proposalUuid: ${n.entityUuid}, ` +
+        `projectUuid: ${n.projectUuid}). Its documents and tasks have been created. Use ` +
+        `chorus_get_unblocked_tasks (projectUuid: "${n.projectUuid}") to find tasks ready to start.\n${mentionGuidance(n, "proposal")}`
+      );
+    case "idea_claimed":
+      return (
+        `[Chorus] Idea '${n.entityTitle}' was assigned to you (ideaUuid: ${n.entityUuid}, ` +
+        `projectUuid: ${n.projectUuid}). Use chorus_get_idea to review it, then claim it ` +
+        `(chorus_claim_idea) to begin elaboration.\n${mentionGuidance(n, "idea")}`
+      );
+    case "task_reopened":
+      return (
+        `[Chorus] Task '${n.entityTitle}' was reopened and needs rework (taskUuid: ${n.entityUuid}, ` +
+        `projectUuid: ${n.projectUuid}). Use chorus_get_task and chorus_get_comments to see the ` +
+        `verification feedback, then fix the issues.\n${mentionGuidance(n, "task")}`
+      );
+    case "resource_resumed":
+      // A user resumed a previously-interrupted wake (子3 — daemon-interrupt-resume).
+      // Resume is entity-generic (task / idea / proposal / document) and arrives as a
+      // synthetic dispatch off the reverse CONTROL channel — NOT a persisted
+      // notification — so it carries only entityType + entityUuid (no actor / title /
+      // project). Because the direct-idea transcript already exists on disk, the
+      // daemon's isNewSession probe selects `claude --resume <directIdeaUuid>`
+      // automatically, so the woken Claude continues the SAME session where it left
+      // off. It intentionally has no @mention (a self-resume has no actor to address).
+      return (
+        `[Chorus] Your work on this ${n.entityType} was RESUMED after an interrupt ` +
+        `(${n.entityType}Uuid: ${n.entityUuid}). Continue where you left off — re-check the ` +
+        `current state with the appropriate chorus_get_* tool (e.g. chorus_get_task / ` +
+        `chorus_get_idea) plus chorus_get_comments for any new feedback, then resume the work ` +
+        `you had started.`
+      );
+    case "task_verified":
+      return (
+        `[Chorus] Task '${n.entityTitle}' was verified and is now done (taskUuid: ${n.entityUuid}, ` +
+        `projectUuid: ${n.projectUuid}). Use chorus_get_unblocked_tasks (projectUuid: "${n.projectUuid}") ` +
+        `to see whether this unblocked any tasks that are now ready to start.`
+      );
+    case "human_instruction": {
+      // A human typed a free-text instruction for this daemon's session (子1 — the 子2
+      // UI send box, or a backfilled pending instruction). The canonical text lives on
+      // the server-side turn's promptText and is denormalized onto the wake
+      // notification as `instructionText`, so the daemon reads it WITHOUT an extra
+      // fetch and the event-router threads it here. The instruction is delivered on the
+      // session the daemon is already running (idea-anchored or the entity itself), so
+      // continuation is naturally `claude --resume` of that session. If the body is
+      // empty/missing there is nothing to act on — skip (no prompt) rather than spawn a
+      // contentless wake.
+      const instruction =
+        typeof n.instructionText === "string" ? n.instructionText.trim() : "";
+      if (!instruction) return null;
+      // Optional entity context: a human_instruction may be attached to an entity
+      // (task/idea/proposal/document) or be a bare session instruction. Include the
+      // entity hint only when present so the agent knows what it relates to.
+      const entityHint =
+        n.entityType && n.entityUuid
+          ? ` (regarding ${n.entityType} ${n.entityUuid}` +
+            (n.projectUuid ? `, projectUuid: ${n.projectUuid}` : "") +
+            `)`
+          : "";
+      const actorHint =
+        n.actorName && n.actorType && n.actorUuid
+          ? `\nWhen you have addressed it, reply with a comment @mentioning the requester: ` +
+            `@[${n.actorName}](${n.actorType}:${n.actorUuid})`
+          : "";
+      return (
+        `[Chorus] New instruction from a human${entityHint}:\n\n` +
+        `${instruction}\n\n` +
+        `Continue this session and act on the instruction above using the appropriate ` +
+        `chorus_* tools. Re-check the current state first (e.g. chorus_get_task / ` +
+        `chorus_get_idea / chorus_get_comments) if you need context.${actorHint}`
+      );
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Actions that produce a wake. Used by the router to decide whether to enqueue.
+ *
+ * Covers the notifications that imply the agent should act — an explicit
+ * @mention, assignment, lifecycle transitions it owns, and unblock signals.
+ * Deliberately NOT woken:
+ *   - comment_added             (fires for EVERY comment to the task's
+ *                                assignee+creator, not just ones directed at the
+ *                                agent — too noisy; an @mention is the real
+ *                                "I need you" signal and arrives as `mentioned`)
+ *   - task_status_changed       (high-frequency, usually a side effect of own work)
+ *   - task_submitted_for_verify (reviewer/owner channel; verification is its own flow)
+ *   - report_created            (informational summary)
+ * The switch in buildPrompt is the source of truth — keep them in sync (a test
+ * asserts every WAKE_ACTIONS entry yields a non-null prompt).
+ */
+export const WAKE_ACTIONS = new Set([
+  "task_assigned",
+  "mentioned",
+  "elaboration_requested",
+  "elaboration_answered",
+  // add-elaboration-verify-wake: a human clicked "Verify Elaborate" — the elaboration is
+  // resolved and the idea is `elaborated`. This wakes the assigned daemon PM agent to WRITE
+  // THE PROPOSAL (distinct from elaboration_requested/answered, which mean "answer
+  // questions"). Arrives as a persisted notification (recipient = the idea's assigned agent),
+  // idea-rooted like the other elaboration wakes, so the session anchor/resume contract is
+  // unchanged. See buildPrompt's `elaboration_verified` case for the write-proposal prompt.
+  "elaboration_verified",
+  "proposal_rejected",
+  "proposal_approved",
+  "idea_claimed",
+  "task_reopened",
+  "task_verified",
+  // 子3 — daemon-interrupt-resume: a user-resumed wake re-dispatches through the
+  // wake path so the daemon continues the session via `--resume`. Entity-generic
+  // (task / idea / proposal / document); arrives via the reverse CONTROL channel as
+  // a synthetic dispatch, NOT a persisted notification.
+  "resource_resumed",
+  // 子1 — daemon-session-conversation: a human-typed instruction for the daemon's
+  // session. Arrives as a persisted notification (recipient = the daemon agent)
+  // carrying the free-text body in `instructionText`; the event-router threads that
+  // body into buildPrompt. NOTE: buildPrompt's human_instruction branch returns null
+  // when the body is empty/missing (nothing to act on) — so this action is a wake
+  // action only when it actually carries instruction text.
+  "human_instruction",
+]);