@chorus-aidlc/chorus 0.12.1 → 0.13.1

package/cli/embedded-db.mjs

@@ -0,0 +1,234 @@
+// cli/embedded-db.mjs
+// Embedded PGlite launch logic, extracted out of chorus.mjs (GitHub #379).
+//
+// Why this module exists — the bug:
+//   chorus.mjs used to fork the PGlite child with { stdio: "ignore" }, attach only
+//   .on("error") (which fires ONLY on spawn failure), then trust waitForTcp — which
+//   answers "is *someone* listening on this port?", NOT "is it *our* PGlite?". When a
+//   real Postgres already occupied the port (default 5433), the forked PGlite child
+//   died of EADDRINUSE — but it catches that and exits with code 0 (a clean shutdown),
+//   so .on("error") never fired and its output was swallowed by stdio:"ignore". The
+//   launcher then connected to the FOREIGN Postgres, printed a false "PGlite ready",
+//   and `prisma migrate deploy` failed authentication with a bare Prisma P1000.
+//
+// The fix is defense-in-depth, both layers pure + dependency-injected so they unit-test
+// with fakes (server-signal-handlers.mjs precedent — no real process spawning, no
+// import-time side effects):
+//   1. Pre-flight port-occupancy probe — before forking, check whether the port is
+//      already held. If so, FAIL FAST with an actionable message (no fork, no false
+//      "ready", no silent mis-connect).
+//   2. Exit-latch — after forking, race the child's "exit"/"error" against port-ready.
+//      If the child exits before readiness is confirmed, for ANY exit code (including
+//      the reproduced EADDRINUSE -> exit 0), the launch is FATAL. "someone is listening"
+//      is no longer sufficient evidence that our embedded PGlite is up.
+//
+// No automatic port bumping (out of scope for #379 — elaboration chose fail-fast).
+
+/**
+ * Format the fail-fast message shown when the embedded PGlite port is occupied.
+ * @param {number} port
+ * @returns {string}
+ */
+export function formatPortConflictMessage(port) {
+  return (
+    `ERROR: Embedded PostgreSQL (PGlite) could not start — port ${port} is already in use.\n` +
+    `Another process (often a real PostgreSQL) is occupying it. Free the port, or run\n` +
+    `Chorus on a different embedded port:  chorus --pglite-port <port>`
+  );
+}
+
+/** True when a child process has already terminated (exit code recorded). */
+function childHasExited(child) {
+  return child.exitCode !== null && child.exitCode !== undefined;
+}
+
+/**
+ * Classify migrate output as a Prisma authentication failure (P1000).
+ *
+ * Matches the stable error CODE token first, then the human phrase as a fallback,
+ * so it survives message drift across Prisma versions. Deliberately narrow: it must
+ * NOT fire on other migration errors (P3009 failed migration, P1001 can't-reach, etc.)
+ * — those keep chorus.mjs's existing generic "Database migration failed" path.
+ * Verified against the installed Prisma 7.3.0 surface text (GitHub #379).
+ *
+ * @param {string|undefined|null} output  combined stdout+stderr of `prisma migrate deploy`
+ * @returns {boolean}
+ */
+export function isPrismaAuthFailure(output) {
+  if (!output) return false;
+  const text = String(output);
+  // P1000 is Prisma's dedicated auth-failure code — the most stable signal.
+  if (/\bP1000\b/.test(text)) return true;
+  // Fallback phrase (covers adapter-surfaced errors that omit the bare code token).
+  if (/Authentication failed against (the )?database server/i.test(text)) return true;
+  return false;
+}
+
+/**
+ * Mask credentials in a Postgres connection URL, preserving host:port (+db) for
+ * diagnostics. Falls back to a naive user:pass@ strip if URL parsing fails, and to a
+ * placeholder for empty input.
+ *
+ * @param {string|undefined|null} url
+ * @returns {string}
+ */
+export function maskDbUrl(url) {
+  if (!url) return "(unknown database)";
+  const raw = String(url);
+  try {
+    const u = new URL(raw);
+    const auth = u.username ? `${u.username}:***@` : "";
+    const db = u.pathname && u.pathname !== "/" ? u.pathname : "";
+    return `${u.protocol}//${auth}${u.host}${db}`;
+  } catch {
+    // Best-effort: strip a user:pass@ segment if present.
+    return raw.replace(/\/\/[^@/]*@/, "//***@");
+  }
+}
+
+/** Extract just host:port from a connection URL for terse messages. */
+function hostPortOf(url) {
+  if (!url) return "the database";
+  try {
+    return new URL(String(url)).host || "the database";
+  } catch {
+    const m = String(url).match(/@([^/?]+)/);
+    return m ? m[1] : "the database";
+  }
+}
+
+/**
+ * Build the Chorus-friendly diagnostic shown (as the FINAL output) when
+ * `prisma migrate deploy` fails authentication. The remedy depends on WHY we're
+ * pointed at that database:
+ *   - embedded path (no external DATABASE_URL): the port is likely occupied by another
+ *     PostgreSQL — suggest `chorus --pglite-port <port>`.
+ *   - external path (DATABASE_URL set): name the external host:port and suggest
+ *     `unset DATABASE_URL` if it was unintended.
+ * Credentials are always masked.
+ *
+ * @param {object} params
+ * @param {string}  params.effectiveUrl    the DATABASE_URL actually used for migration
+ * @param {boolean} params.startedEmbedded  true if we launched embedded PGlite ourselves
+ * @param {number}  params.pglitePort       the embedded port (for the --pglite-port hint)
+ * @returns {string}
+ */
+export function formatMigrationAuthDiagnostic({ effectiveUrl, startedEmbedded, pglitePort }) {
+  const masked = maskDbUrl(effectiveUrl);
+  const hostPort = hostPortOf(effectiveUrl);
+  const lines = [
+    "",
+    "ERROR: Database migration failed — the database server rejected the credentials.",
+    `Connected to ${masked}, but authentication failed (Prisma P1000).`,
+    "",
+  ];
+  if (startedEmbedded) {
+    lines.push(
+      `This usually means port ${pglitePort} is occupied by another PostgreSQL, so Chorus`,
+      `connected to it instead of its own embedded database. Free the port, or run on a`,
+      `different one:  chorus --pglite-port <port>`
+    );
+  } else {
+    lines.push(
+      `Chorus used the DATABASE_URL from your environment (${hostPort}) instead of its`,
+      `embedded database. If that was not intended, clear it and re-run:  unset DATABASE_URL`
+    );
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Launch the embedded PGlite child and confirm it is genuinely OUR process that is
+ * ready — not a foreign listener on the same port.
+ *
+ * Pure w.r.t. its injected dependencies: `fork`, `waitForTcp`, `preflightCheck`,
+ * `logger`. No process global is touched here; the caller (chorus.mjs) wires the real
+ * implementations and decides how to exit on failure.
+ *
+ * @param {object} params
+ * @param {string}   params.host            host to probe for readiness (e.g. "localhost")
+ * @param {number}   params.port            embedded PGlite port
+ * @param {() => { on: Function, kill?: Function, exitCode: number|null, killed?: boolean }} params.fork
+ *   forks the PGlite server child and returns a ChildProcess-like object
+ * @param {(host: string, port: number) => Promise<void>} params.waitForTcp
+ *   resolves when the port accepts a TCP connection, rejects on timeout
+ * @param {(host: string, port: number) => Promise<boolean>} params.preflightCheck
+ *   resolves true if the port is ALREADY occupied before we fork (foreign listener)
+ * @param {{ log: Function, error: Function }} params.logger
+ * @returns {Promise<
+ *   | { ok: true, child: object }
+ *   | { ok: false, reason: "port-occupied", port: number }
+ *   | { ok: false, reason: "child-exited", exitInfo: { code: number|null, signal: string|null } }
+ *   | { ok: false, reason: "child-error", error: Error }
+ *   | { ok: false, reason: "not-ready", error: Error }
+ * >}
+ */
+export async function launchEmbeddedPglite({ host, port, fork, waitForTcp, preflightCheck, logger }) {
+  // Layer 1 — pre-flight: never fork onto an already-occupied port.
+  const occupied = await preflightCheck(host, port);
+  if (occupied) {
+    logger.error(formatPortConflictMessage(port));
+    return { ok: false, reason: "port-occupied", port };
+  }
+
+  const child = fork();
+
+  // The child may have died synchronously during/just after fork (its exit code is
+  // then already recorded even if our "exit" listener attaches a tick too late).
+  if (childHasExited(child)) {
+    return {
+      ok: false,
+      reason: "child-exited",
+      exitInfo: { code: child.exitCode, signal: null },
+    };
+  }
+
+  // Layer 2 — latch the child's terminal events, then race them against readiness.
+  // A dead child ALWAYS beats a "someone is listening" probe: that is the #379 guard.
+  let exitInfo = null; // { code, signal } once the child exits
+  let spawnError = null;
+  let readyError = null;
+
+  const childDied = new Promise((resolve) => {
+    child.on("exit", (code, signal) => {
+      exitInfo = { code, signal };
+      resolve("exit");
+    });
+    child.on("error", (err) => {
+      spawnError = err;
+      resolve("error");
+    });
+  });
+
+  const readied = waitForTcp(host, port).then(
+    () => "ready",
+    (err) => {
+      readyError = err;
+      return "not-ready";
+    }
+  );
+
+  const outcome = await Promise.race([childDied, readied]);
+
+  // Re-check the latches regardless of who won the race — the child dying is fatal
+  // even if the port-ready probe also resolved (e.g. against a foreign listener).
+  if (exitInfo || childHasExited(child)) {
+    return {
+      ok: false,
+      reason: "child-exited",
+      exitInfo: exitInfo || { code: child.exitCode ?? null, signal: null },
+    };
+  }
+  if (spawnError) {
+    return { ok: false, reason: "child-error", error: spawnError };
+  }
+  if (outcome === "not-ready") {
+    // Readiness timed out but the child is (as far as we know) still alive — don't leak it.
+    if (child.kill && !child.killed) child.kill("SIGTERM");
+    return { ok: false, reason: "not-ready", error: readyError };
+  }
+
+  // outcome === "ready" AND the child has not exited → genuinely our PGlite.
+  logger.log(`PGlite ready on port ${port}.`);
+  return { ok: true, child };
+}

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