@chorus-aidlc/chorus 0.13.0 → 0.13.2

package/cli/daemon.mjs

@@ -46,6 +46,15 @@ import {
   isRunning,
   readLog,
 } from "./daemon-lifecycle.mjs";
+import {
+  detectSupervisor,
+  installService,
+  uninstallService,
+  systemctlUser,
+  journalctlUser,
+  resolveServicePaths,
+  SERVICE_NAME,
+} from "./daemon-service.mjs";
 import { readFileSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -254,7 +263,20 @@ export function buildDaemon(creds, deps = {}) {
     // transcript (new-vs-resume) and to spawn, so they never diverge (Module Contract
     // 1 — resolveCwd is the single source). `cwd` is `undefined` for the single-path /
     // old-daemon default, which the Waker degrades to process.cwd() (HARD-1).
-    waker = new Waker({ creds, lineage, spawner, cwd, hooks, logger, reportInterrupt, advanceTurn, verbose });
+    waker = new Waker({
+      creds,
+      lineage,
+      spawner,
+      cwd,
+      hooks,
+      logger,
+      reportInterrupt,
+      advanceTurn,
+      verbose,
+      // Graceful-shutdown kill escalation (fix-daemon-exit-orphan-running-turn):
+      // interruptAll() reuses the SAME window the interrupt control handler uses.
+      sigintTimeoutMs,
+    });
     // The router reads THIS connection's own uuid lazily (same source the control handler
     // uses) to suppress a DIRECTED (pinned) wake stamped for a different connection
     // (fix-pinned-wake-directed-delivery, T2). Null until the SSE handshake assigns it — a
@@ -274,8 +296,8 @@ export function buildDaemon(creds, deps = {}) {
     // all scoped to THIS connection's uuid/router/backfill (see the original wiring
     // comments retained on the shared helpers). The control handler verifies a control
     // event against this connection's own connectionUuid before acting.
-    const redispatchResume = (entityType, entityUuid) => {
-      router.dispatchResume?.({ entityType, entityUuid });
+    const redispatchResume = (entityType, entityUuid, resumeReason) => {
+      router.dispatchResume?.({ entityType, entityUuid, resumeReason });
     };
     const deliverTurn = (turnUuid) => backfill?.pendingTurnsOnly?.(turnUuid);
     const onControl = createControlHandler({
@@ -399,10 +421,30 @@ export function buildDaemon(creds, deps = {}) {
       }
     },
     async stop() {
+      // Graceful shutdown ordering (fix-daemon-exit-orphan-running-turn):
+      // 1. Stop taking new work: disconnect the SSE listeners (no new notifications)
+      //    and latch the queue (queued-but-unstarted wakes never spawn).
       for (const c of connections) {
         c.sseListener.disconnect?.();
       }
-      // The MCP client is process-wide (shared) — disconnect it once.
+      queue.stop();
+      // 2. Interrupt every in-flight wake subprocess via the shared kill escalation.
+      //    Each wake's exit path — seeing shuttingDown — reports its turn
+      //    interrupted(shutdown) and suppresses the execution crash report.
+      for (const c of connections) {
+        c.waker?.interruptAll?.();
+      }
+      // 3. Await the in-flight wakes so those turn-advance reports flush, BOUNDED:
+      //    the kill escalation window plus a hard 5s cap for the exit path's REST
+      //    reports. A wake that outlives this does NOT hang the shutdown — its
+      //    orphaned turn is the server-side offline reconcile's job (the backstop).
+      const drained = await queue.drain(sigintTimeoutMs + 5_000);
+      if (!drained) {
+        logger.warn(
+          "[Chorus] shutdown: in-flight wake(s) did not finish within the bound — exiting anyway (server reconcile will finalize their turns)",
+        );
+      }
+      // 4. The MCP client is process-wide (shared) — disconnect it once.
       await mcpClient.disconnect?.();
     },
   };
@@ -456,7 +498,25 @@ export async function runDaemon(flags = {}, deps = {}) {
   // Lifecycle subcommands (stop/status/restart/logs) operate on the pidfile/logfile
   // managed by the `-d` path — they never start the long-lived foreground daemon.
   // `run` falls through to the normal startup below. Injectable lifecycle for tests.
-  const lifecycle = deps.lifecycle ?? { startBackground, stopDaemon, isRunning, readLog };
+  // stopDaemon's real signature is (io, opts); the bundle exposes (opts) with the
+  // default io so handleLifecycleAction can pass { force } directly.
+  const lifecycle = deps.lifecycle ?? {
+    startBackground,
+    stopDaemon: (opts) => stopDaemon(undefined, opts),
+    isRunning,
+    readLog,
+  };
+  // Supervisor (systemd --user) seam — install/uninstall the boot service and
+  // detect/delegate to it from the lifecycle subcommands. Injectable for tests
+  // (no real systemctl / disk). Defaults to the real daemon-service module.
+  const service = deps.service ?? {
+    detectSupervisor,
+    installService,
+    uninstallService,
+    systemctlUser,
+    journalctlUser,
+    resolveServicePaths: () => resolveServicePaths(env),
+  };
   // The preflight dep bundle — built from the same seams runDaemon resolved, so
   // the detach/restart paths run the SAME (injectable) preflight, not the real
   // implementations. Threaded into startDetached so tests can drive it offline.
@@ -464,7 +524,7 @@ export async function runDaemon(flags = {}, deps = {}) {
 
   const action = flags.action ?? "run";
   if (action !== "run") {
-    return handleLifecycleAction(action, { log, errLog, lifecycle, pfDeps });
+    return handleLifecycleAction(action, { log, errLog, lifecycle, service, pfDeps });
   }
 
   // `-d` / --detach: complete any interactive preflight in THIS foreground process
@@ -665,13 +725,87 @@ export async function preflight(ctx) {
 }
 
 /**
- * Dispatch a daemon lifecycle subcommand (stop/status/restart/logs) against the
- * pidfile/logfile-managed background daemon. Each reports clearly when nothing
- * is running (no silent failure). `restart` performs stop-then-detached-start.
+ * Dispatch a daemon lifecycle subcommand. Two families:
+ *   - install / uninstall — manage the boot-autostart supervisor service
+ *     (systemd --user on Linux; a printed template on macOS/Windows).
+ *   - status / stop / restart / logs — when a supervisor unit is installed and
+ *     active, DELEGATE to it (systemctl / journalctl) so a supervised daemon is
+ *     never misreported as "not running"; otherwise operate on the
+ *     pidfile/logfile-managed `-d` background daemon exactly as before.
+ * Each reports clearly (no silent failure). `restart` performs
+ * stop-then-detached-start on the pidfile path.
  * @returns {Promise<number>} exit code
  */
-export async function handleLifecycleAction(action, { log, errLog, lifecycle, pfDeps }) {
+export async function handleLifecycleAction(action, { log, errLog, lifecycle, service, pfDeps }) {
+  // The supervisor seam is optional (older test bundles inject only lifecycle);
+  // a no-op fallback keeps those callers on the pure pidfile path.
+  const svc = service ?? { detectSupervisor: () => ({ kind: "none" }) };
+
+  if (action === "install") {
+    const spec = {
+      ...svc.resolveServicePaths(),
+      cwds: pfDeps?.flags?.cwd ?? [],
+      agent: pfDeps?.flags?.agent,
+      chorusOnly: pfDeps?.flags?.chorusOnly === true,
+      workingDir: process.cwd(),
+    };
+    const r = svc.installService(spec);
+    if (r.installed) {
+      log(`[Chorus] installed and started the daemon service:`);
+      for (const s of r.steps) log(`[Chorus]   ${s}`);
+      log(`[Chorus] it will now start automatically at login. Manage it with:`);
+      log(`[Chorus]   chorus daemon status | stop | restart | logs`);
+      // A --user service only survives logout with lingering enabled; and a
+      // separately-started `chorus daemon -d` would hold the same paths and make
+      // this service exit-and-retry. Surface both so neither is a silent gotcha.
+      log(`[Chorus] to keep it running after you log out: loginctl enable-linger "$USER"`);
+      log(`[Chorus] if you previously ran 'chorus daemon -d', stop it first ('chorus daemon stop') so it doesn't hold the same paths.`);
+      return 0;
+    }
+    if (r.platform === "linux") {
+      // Linux install actually failed (write / systemctl error) — surface it.
+      errLog(`[Chorus] service install failed: ${r.error}`);
+      for (const s of r.steps) errLog(`[Chorus]   (did: ${s})`);
+      return 1;
+    }
+    // macOS / Windows: not auto-installed by design — print the template + steps.
+    log(`[Chorus] automatic install is Linux-only. To run the daemon as a service on this platform:`);
+    for (const s of r.steps) log(`[Chorus]   ${s}`);
+    log("");
+    log(r.unitText);
+    return 0;
+  }
+  if (action === "uninstall") {
+    const r = svc.uninstallService();
+    if (r.platform === "linux") {
+      if (r.error) {
+        errLog(`[Chorus] service uninstall failed: ${r.error}`);
+        return 1;
+      }
+      if (r.removed) {
+        log(`[Chorus] removed the daemon service:`);
+        for (const s of r.steps) log(`[Chorus]   ${s}`);
+      } else {
+        log(`[Chorus] no installed daemon service found (nothing to remove).`);
+      }
+      return 0;
+    }
+    log(`[Chorus] automatic uninstall is Linux-only. To remove the service on this platform:`);
+    for (const s of r.steps) log(`[Chorus]   ${s}`);
+    return 0;
+  }
+
+  // For the control verbs, prefer a live supervisor unit over the pidfile.
+  const sup = svc.detectSupervisor();
+  const supervised = sup.kind === "systemd" && sup.installed;
+
   if (action === "status") {
+    if (supervised) {
+      log(`[Chorus] daemon is managed by systemd (${SERVICE_NAME}.service) — ${sup.active ? "active" : "installed but NOT active"}.`);
+      const r = svc.systemctlUser(["status", "--no-pager", `${SERVICE_NAME}.service`]);
+      if (r.stdout) log(r.stdout.trimEnd());
+      return sup.active ? 0 : 1;
+    }
     const s = lifecycle.isRunning();
     if (s.running) log(`[Chorus] daemon is running (pid ${s.pid}).`);
     else if (s.stale) log(`[Chorus] daemon is NOT running (stale pidfile for pid ${s.pid}).`);
@@ -679,6 +813,15 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, pf
     return 0;
   }
   if (action === "logs") {
+    if (supervised) {
+      const r = svc.journalctlUser(["-u", `${SERVICE_NAME}.service`, "--no-pager", "-n", "200"]);
+      if (r.status !== 0 && !r.stdout) {
+        errLog(`[Chorus] could not read the service journal: ${r.stderr.trim() || `exit ${r.status}`}`);
+        return 1;
+      }
+      log(r.stdout.trimEnd());
+      return 0;
+    }
     const r = lifecycle.readLog();
     if (!r.ok) {
       errLog(`[Chorus] ${r.message}`);
@@ -688,11 +831,36 @@ export async function handleLifecycleAction(action, { log, errLog, lifecycle, pf
     return 0;
   }
   if (action === "stop") {
-    const r = lifecycle.stopDaemon();
-    (r.stopped ? log : errLog)(`[Chorus] ${r.message}`);
-    return r.stopped ? 0 : 1;
+    if (supervised) {
+      const r = svc.systemctlUser(["stop", `${SERVICE_NAME}.service`]);
+      if (r.status === 0) {
+        log(`[Chorus] stopped the daemon service (systemctl --user stop ${SERVICE_NAME}.service).`);
+        log(`[Chorus] note: it is still enabled and will start again at next login. To disable: chorus daemon uninstall`);
+        return 0;
+      }
+      errLog(`[Chorus] failed to stop the service: ${r.stderr.trim() || `exit ${r.status}`}`);
+      return 1;
+    }
+    // --force: unconditional pidfile cleanup for stuck states the identity
+    // probe cannot resolve. Threaded from the parsed client flags.
+    const r = lifecycle.stopDaemon({ force: pfDeps?.flags?.force === true });
+    // Exit 0 whenever the end state is "no daemon, no pidfile" (stopped /
+    // stale-cleared / forced) so `chorus daemon stop && …` chains survive a
+    // self-heal; 1 for not-running and signal errors.
+    const ok = r.reason === "stopped" || r.reason === "stale-cleared" || r.reason === "forced";
+    (ok ? log : errLog)(`[Chorus] ${r.message}`);
+    return ok ? 0 : 1;
   }
   if (action === "restart") {
+    if (supervised) {
+      const r = svc.systemctlUser(["restart", `${SERVICE_NAME}.service`]);
+      if (r.status === 0) {
+        log(`[Chorus] restarted the daemon service (systemctl --user restart ${SERVICE_NAME}.service).`);
+        return 0;
+      }
+      errLog(`[Chorus] failed to restart the service: ${r.stderr.trim() || `exit ${r.status}`}`);
+      return 1;
+    }
     const r = lifecycle.stopDaemon();
     log(`[Chorus] ${r.message}`);
     // Start a fresh detached instance regardless of whether one was running.

package/cli/event-router.mjs

@@ -14,12 +14,14 @@ const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 // MIRROR of the server's NOTIFICATION_ACTION_TO_TURN_TRIGGER (src/services/notification-turn.ts).
 // Used ONLY to match a re-read wake notification back to a DIRECTED autonomous pending turn
 // (the deliver_turn re-dispatch rebuilds the prompt from the notification, T2). Kept narrow
-// to the three triggers a `deliver_turn` ping can carry for an autonomous wake; every other
-// action collapses to the `task_assigned` trigger exactly as the server does, so a
+// to the dedicated triggers a `deliver_turn` ping can carry for an autonomous wake; every
+// other action collapses to the `task_assigned` trigger exactly as the server does, so a
 // task_assigned turn matches its task_reopened/task_verified/idea_claimed/proposal_* origins.
 const ACTION_TO_TURN_TRIGGER = {
   mentioned: "mentioned",
   elaboration_verified: "elaboration_verified",
+  start_development: "start_development",
+  yolo_requested: "yolo_requested",
   elaboration_requested: "elaboration",
   elaboration_answered: "elaboration",
   human_instruction: "human_instruction",
@@ -219,7 +221,12 @@ export class EventRouter {
    * per-direct-idea serialization holds and the spawner's on-disk transcript probe
    * naturally selects `claude --resume <directIdeaUuid>` (the session already
    * exists). Synchronous + non-throwing, mirroring `dispatch`.
-   * @param {{ entityType?: string, entityUuid?: string }} target
+   *
+   * `resumeReason` (add-crash-execution-resume) is the interrupted row's prior
+   * 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
    */
   dispatchResume(target) {
     const entityType = target?.entityType;
@@ -228,7 +235,16 @@ export class EventRouter {
       this.logger.warn("[Chorus] resume dispatch missing entityType/entityUuid, skipping");
       return;
     }
-    const n = { action: "resource_resumed", entityType, entityUuid };
+    const resumedFrom =
+      target?.resumeReason === "user" || target?.resumeReason === "crash"
+        ? target.resumeReason
+        : undefined;
+    const n = {
+      action: "resource_resumed",
+      entityType,
+      entityUuid,
+      ...(resumedFrom ? { resumedFrom } : {}),
+    };
     this.#resolveAndEnqueue(n, `resume:${entityType}:${entityUuid}`).catch((err) => {
       this.logger.error(`[Chorus] failed to dispatch resume for ${entityType}:${entityUuid}: ${err}`);
     });
@@ -278,15 +294,18 @@ export class EventRouter {
       this.logger.warn(`[Chorus] pending-turn ${turnUuid} missing sessionId, skipping`);
       return;
     }
-    // A DIRECTED autonomous turn (mentioned / task_assigned / elaboration_verified) is
-    // delivered by the deliver_turn ping too (T2). Its prompt must be rebuilt from the
-    // notification (promptText is null), so it takes a separate async path. resume /
-    // elaboration are not delivered by deliver_turn (resume is synthetic; elaboration
-    // request/answer rides the notification broadcast), so they are not re-dispatched here.
+    // A DIRECTED autonomous turn (mentioned / task_assigned / elaboration_verified /
+    // start_development / yolo_requested) is delivered by the deliver_turn ping too (T2).
+    // Its prompt must be rebuilt from the notification (promptText is null), so it takes a
+    // separate async path. resume / elaboration are not delivered by deliver_turn (resume
+    // is synthetic; elaboration request/answer rides the notification broadcast), so they
+    // are not re-dispatched here.
     if (
       pending.trigger === "mentioned" ||
       pending.trigger === "task_assigned" ||
-      pending.trigger === "elaboration_verified"
+      pending.trigger === "elaboration_verified" ||
+      pending.trigger === "start_development" ||
+      pending.trigger === "yolo_requested"
     ) {
       // Shared dedup, marked BEFORE async work (mirrors the human_instruction path and
       // `dispatch`) so concurrent deliveries collapse to one wake.

package/cli/prompts.mjs

@@ -138,6 +138,42 @@ function buildPromptBody(n) {
         `chorus_get_elaboration, then author the proposal via the existing proposal flow ` +
         `(chorus_pm_create_proposal / the proposal skill).\n${mentionGuidance(n, "idea")}`
       );
+    case "start_development":
+      // A human clicked "Start Development" (add-stage-advance-start-development). The
+      // idea's proposal is approved and unfinished tasks remain. The agent's job on this
+      // wake is the WHOLE remaining execute stage — loop over every claimable task until
+      // none remain (elaboration decision Q1), never stopping after a single task.
+      return (
+        `[Chorus] A human started DEVELOPMENT for idea '${n.entityTitle}' ` +
+        `(ideaUuid: ${n.entityUuid}, projectUuid: ${n.projectUuid}). The idea's proposal is approved and ` +
+        `unfinished tasks remain. Claim and execute ALL remaining tasks of that proposal in dependency ` +
+        `order, following the develop workflow: repeatedly find claimable tasks (chorus_get_unblocked_tasks ` +
+        `with projectUuid: "${n.projectUuid}"), claim one (chorus_claim_task), implement it, self-check its ` +
+        `acceptance criteria (chorus_report_criteria_self_check), and submit it (chorus_submit_for_verify) — ` +
+        `then loop until NO claimable task remains. Do NOT stop after one task. Leave tasks already in ` +
+        `to_verify (awaiting human verification) and tasks claimed by other sessions untouched. If nothing ` +
+        `is claimable, post a brief status comment on the idea and end the turn.\n${mentionGuidance(n, "idea")}`
+      );
+    case "yolo_requested":
+      // A human clicked "Yolo" (add-stage-advance-yolo). Unlike start_development
+      // (always the execute stage), this wake can land at ANY incomplete stage, so the
+      // prompt must NOT hard-code a stage — it points the agent at the yolo skill and lets
+      // it self-select the entry phase from the idea's current state (no proposal yet →
+      // elaborate + write proposal; approved proposal with open tasks → execute; etc.).
+      // Honors the "yolo never merges" rule: drive through done + completion report, but
+      // never merge or push a PR without explicit human approval.
+      return (
+        `[Chorus] A human requested a YOLO run for idea '${n.entityTitle}' ` +
+        `(ideaUuid: ${n.entityUuid}, projectUuid: ${n.projectUuid}). Drive this idea all the ` +
+        `way to done following the yolo skill (the full-auto AI-DLC pipeline: Idea → ` +
+        `Elaboration → Proposal → Execute → Verify). First read the idea's current state with ` +
+        `chorus_get_idea (plus chorus_get_elaboration / chorus_get_proposals as needed) and ` +
+        `RESUME from whatever phase it is already in — do NOT assume a fixed stage: if ` +
+        `elaboration isn't resolved, self-elaborate then write the proposal; if a proposal is ` +
+        `approved with open tasks, execute them; and so on. Complete the pipeline through the ` +
+        `final done state and completion report, but do NOT merge or push a pull request ` +
+        `without explicit human approval.\n${mentionGuidance(n, "idea")}`
+      );
     case "proposal_rejected":
       return (
         `[Chorus] Proposal '${n.entityTitle}' was REJECTED (proposalUuid: ${n.entityUuid}, ` +
@@ -172,6 +208,21 @@ function buildPromptBody(n) {
       // 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).
+      //
+      // `resumedFrom` (add-crash-execution-resume) distinguishes the resume kind:
+      // "crash" gets an explicit exited-abnormally instruction — the previous run may
+      // have died mid-edit, so the agent must verify state before continuing.
+      // "user" / absent / unknown (older server) keeps the original text unchanged.
+      if (n.resumedFrom === "crash") {
+        return (
+          `[Chorus] The previous run on this ${n.entityType} EXITED ABNORMALLY (crashed) ` +
+          `(${n.entityType}Uuid: ${n.entityUuid}), and a user asked to resume it. The crash may ` +
+          `have left work half-finished — first re-check the current state with the appropriate ` +
+          `chorus_get_* tool (e.g. chorus_get_task / chorus_get_idea) plus chorus_get_comments, ` +
+          `and inspect any partial local work (working tree, uncommitted changes, half-written ` +
+          `files). Then continue the unfinished work from where the crashed run left off.`
+        );
+      }
       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 ` +
@@ -253,6 +304,16 @@ export const WAKE_ACTIONS = new Set([
   // 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",
+  // add-stage-advance-start-development: a human clicked "Start Development" — the idea's
+  // proposal is approved and unfinished tasks remain. Wakes the assigned daemon agent to
+  // CLAIM AND EXECUTE ALL remaining tasks (dedicated trigger, session-origin-pinned like
+  // elaboration_verified). See buildPrompt's `start_development` case.
+  "start_development",
+  // add-stage-advance-yolo: a human clicked "Yolo" — wakes the assigned daemon agent to
+  // drive the WHOLE idea to done via the yolo skill (dedicated trigger, session-origin-
+  // pinned like start_development). Unlike start_development it is stage-adaptive — see
+  // buildPrompt's `yolo_requested` case.
+  "yolo_requested",
   "proposal_rejected",
   "proposal_approved",
   "idea_claimed",

package/cli/turn-reporter.mjs

@@ -4,7 +4,7 @@
 // persistent conversation; the server creates that turn (status `pending`) at the
 // notification chokepoint, and the daemon advances it:
 //   • on spawn      → pending → running
-//   • on subprocess exit → running → ended
+//   • on subprocess exit → running → ended (clean) | interrupted (user/crash/shutdown)
 //
 // The daemon does NOT know the server-side turn uuid. It identifies the turn the SAME
 // way the transcript ingest does — by the session BUSINESS KEY (`sessionId` = the
@@ -27,7 +27,10 @@ import { createDaemonRestClient } from "./daemon-rest-client.mjs";
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 
 /** Turn lifecycle states the server's turn-advance endpoint accepts. */
-export const TURN_STATUSES = new Set(["pending", "running", "ended"]);
+export const TURN_STATUSES = new Set(["pending", "running", "ended", "interrupted"]);
+
+/** Interrupt reasons a DAEMON may report (`offline` is server-reconcile-only). */
+export const TURN_INTERRUPT_REASONS = new Set(["user", "crash", "shutdown"]);
 
 /**
  * Build an `advanceTurn(params)` function the waker invokes on a wake's spawn (→
@@ -43,7 +46,7 @@ export const TURN_STATUSES = new Set(["pending", "running", "ended"]);
  *   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", entityType?: string|null, entityUuid?: string|null }) => Promise<void>}
+ * @returns {(params: { sessionId: string, status: "running"|"ended"|"interrupted", entityType?: string|null, entityUuid?: string|null, interruptedReason?: "user"|"crash"|"shutdown"|null }) => Promise<void>}
  */
 export function createTurnReporter(opts) {
   const logger = opts.logger ?? NOOP_LOGGER;
@@ -58,18 +61,36 @@ export function createTurnReporter(opts) {
     logger,
   });
 
-  return async function advanceTurn({ sessionId, status, entityType, entityUuid }) {
+  return async function advanceTurn({
+    sessionId,
+    status,
+    entityType,
+    entityUuid,
+    interruptedReason,
+  }) {
     if (typeof sessionId !== "string" || !sessionId || !TURN_STATUSES.has(status)) {
       logger.warn(
         `[Chorus] refusing to advance turn: bad sessionId/status (${sessionId}, ${status})`,
       );
       return;
     }
+    // Domain guard mirroring the server's: a reason travels only with `interrupted`
+    // and only from the daemon-reportable vocabulary (`offline` is the server's own
+    // reconcile verdict). Refusing here keeps a bad caller visible in daemon logs
+    // instead of as a server 400.
+    if (interruptedReason != null) {
+      if (status !== "interrupted" || !TURN_INTERRUPT_REASONS.has(interruptedReason)) {
+        logger.warn(
+          `[Chorus] refusing to advance turn: bad interruptedReason (${interruptedReason}) for status ${status}`,
+        );
+        return;
+      }
+    }
     // The client resolves the connectionUuid lazily, validates it (logging
     // "no connection uuid yet" when absent), POSTs the exact server payload — sending
     // entityType/entityUuid only when both are present — and logs the failure cause on a
     // network error / non-2xx. We swallow the structured result so a failed report can
     // never crash the wake path.
-    await client.turnAdvance({ sessionId, status, entityType, entityUuid });
+    await client.turnAdvance({ sessionId, status, entityType, entityUuid, interruptedReason });
   };
 }

package/cli/wake-queue.mjs

@@ -30,6 +30,15 @@ export class WakeQueue {
     /** @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.
+    this.stopped = false;
+  }
+
+  /** Stop starting new tasks (graceful shutdown). In-flight tasks are unaffected. */
+  stop() {
+    this.stopped = true;
   }
 
   /**
@@ -75,8 +84,29 @@ export class WakeQueue {
     return [...this.pending.entries()].filter(([, q]) => q.length > 0).map(([k]) => k);
   }
 
+  /**
+   * Wait (bounded) for every in-flight task 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
+   * 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
+   * 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.
+   * @param {number} timeoutMs
+   * @returns {Promise<boolean>}
+   */
+  async drain(timeoutMs) {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    while (this.activeCount > 0) {
+      if (Date.now() >= deadline) return false;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    return true;
+  }
+
   /** Try to start as many ready keys as the concurrency cap allows. */
   #pump() {
+    if (this.stopped) return; // shutting down — start nothing new
     while (this.activeCount < this.maxConcurrency && this.readyKeys.length > 0) {
       const key = this.readyKeys.shift();
       if (this.running.has(key)) continue; // already running under another slot