omp-conductor 0.19.6 → 0.20.0

package/src/commands/extend.ts

@@ -6,22 +6,30 @@
  * same run-control target `worker` uses, so a live systemd-run daemon
  * stays reachable when its pidfile is missing (#811) and the refusal
  * answers cannot drift between the two verbs.
+ *
+ * The turn-limit endpoint is mutating, so it now carries the daemon's bearer
+ * token (Phase 4). The token is read, never minted: the daemon mints it at
+ * start, so an absent file means no daemon has run here — the honest refusal
+ * is that message, not an unauthenticated request that comes back a bare 401.
  */
 
 import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { requireDaemonControl } from "../lifecycle.ts";
+import { httpAuthHeader, missingHttpTokenMessage } from "../http-token.ts";
 
 export async function extendCommand(ctx: CommandContext): Promise<void> {
 const issue = ctx.issueArg("extend", ctx.argv[1]);
 const maxTurns = ctx.turnsFlag();
 const project = findProject(loadConfig(), ctx.projectFlag);
 const daemon = await requireDaemonControl(project.name);
+const auth = httpAuthHeader();
+if (auth === undefined) throw new Error(missingHttpTokenMessage());
 const response = await fetch(
   `http://127.0.0.1:${daemon.port}/runs/${issue}/turn-limit`,
   {
     method: "PUT",
-    headers: { "content-type": "application/json" },
+    headers: { "content-type": "application/json", ...auth },
     body: JSON.stringify({ project: project.name, maxTurns }),
   },
 );

package/src/commands/intake.ts

@@ -12,9 +12,15 @@ import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { dbPath, openStore } from "../store.ts";
 
-/** Flags the intake surface understands. `--project` is consumed by
- *  {@link CommandContext.projectFlag}; the value token stays in argv. */
-const INTAKE_FLAGS: Record<string, true> = { "--project": true, "--issue": true };
+/** Flags the intake surface understands, and whether each takes a value.
+ *  `--project` is consumed by {@link CommandContext.projectFlag}; the value
+ *  token stays in argv, so the arg scan has to step over it. `--json` is a
+ *  toggle and must NOT swallow the token after it. */
+const INTAKE_FLAGS: Record<string, "value" | "toggle"> = {
+  "--project": "value",
+  "--issue": "value",
+  "--json": "toggle",
+};
 
 /** Every remaining token after the subverb must be one of the known flags
  *  (or its value), otherwise the operator typo'd something that would be
@@ -23,10 +29,12 @@ function assertKnownArgs(ctx: CommandContext, from: number): void {
   for (let i = from; i < ctx.argv.length; i++) {
     const token = ctx.argv[i];
     if (token === undefined) continue;
-    if (INTAKE_FLAGS[token] === true) {
+    const kind = INTAKE_FLAGS[token];
+    if (kind === "value") {
       i += 1;
       continue;
     }
+    if (kind === "toggle") continue;
     if (token.startsWith("--project=")) continue;
     process.stderr.write(`omp-conductor: intake: unexpected argument "${token}"\n`);
     process.exit(2);
@@ -45,17 +53,36 @@ export async function intakeCommand(ctx: CommandContext): Promise<void> {
     if (sub === "list") {
       assertKnownArgs(ctx, 2);
       const pending = store.pendingIntake(project.name);
-      if (pending.length === 0) {
+      const now = Date.now();
+      // Age at capture granularity: minutes for a fresh idea, hours once it
+      // has been waiting a while — the unit the operator actually cares about.
+      const items = pending.map((item) => {
+        const minutes = Math.max(0, Math.round((now - item.createdAt) / 60_000));
+        return {
+          id: item.id,
+          age: minutes < 60 ? `${minutes}m` : `${Math.floor(minutes / 60)}h`,
+          // null, not omitted, so a consumer can tell "operator's own idea"
+          // from "this build predates provenance" — the key is always there.
+          source: item.source ?? null,
+          text: item.text,
+        };
+      });
+      if (ctx.argv.includes("--json")) {
+        process.stdout.write(`${JSON.stringify({ project: project.name, items }, null, 2)}\n`);
+        return;
+      }
+      if (items.length === 0) {
         process.stdout.write("no pending ideas\n");
         return;
       }
-      const now = Date.now();
-      for (const item of pending) {
-        // Age at capture granularity: minutes for a fresh idea, hours once it
-        // has been waiting a while — the unit the operator actually cares about.
-        const minutes = Math.max(0, Math.round((now - item.createdAt) / 60_000));
-        const age = minutes < 60 ? `${minutes}m` : `${Math.floor(minutes / 60)}h`;
-        process.stdout.write(`${item.id}  ${age.padStart(5)}  ${item.text}\n`);
+      for (const item of items) {
+        // The source column exists so an operator reading this list can tell a
+        // machine-filed signal from something they thought of themselves —
+        // they are answerable for one and merely informed of the other. A dash
+        // marks their own idea; anything else names the signal that filed it.
+        process.stdout.write(
+          `${item.id}  ${item.age.padStart(5)}  ${item.source ?? "-"}  ${item.text}\n`,
+        );
       }
       return;
     }
@@ -95,7 +122,7 @@ export async function intakeCommand(ctx: CommandContext): Promise<void> {
       return;
     }
 
-    if (sub !== undefined && sub.startsWith("--") && INTAKE_FLAGS[sub] !== true) {
+    if (sub !== undefined && sub.startsWith("--") && INTAKE_FLAGS[sub] === undefined) {
       process.stderr.write(`omp-conductor: intake: unexpected argument "${sub}"\n`);
       process.exit(2);
     }
@@ -106,7 +133,10 @@ export async function intakeCommand(ctx: CommandContext): Promise<void> {
     for (let i = 1; i < ctx.argv.length; i++) {
       const token = ctx.argv[i];
       if (token === undefined) continue;
-      if (INTAKE_FLAGS[token] === true) {
+      // Only value flags step over their value here. `--json` is a list-only
+      // toggle, so on the capture path it falls through to the rejection below
+      // rather than being silently ignored on a verb that cannot honour it.
+      if (INTAKE_FLAGS[token] === "value") {
         i += 1;
         continue;
       }

package/src/commands/stats.ts

@@ -32,21 +32,35 @@ merge settlement), attempts per merged issue, metered spend per merged issue,
 the failure-class breakdown of everything that did not merge, and the tracked
 GitHub API calls consumed over the window's days.
 
+It then attributes that spend: worker runs grouped by the model actually
+billed (runs, merges, metered spend, $/merge — runs that never observed a
+resolved model group under "(unresolved)" rather than being guessed into a
+bucket), and the daemon's own sessions per role (to-spec grooming and review
+adjudication, with turns and metered spend). The orchestrator's tick session is
+listed as unmetered: no usage events are observable for it, so its cost is
+unknown and no figure includes it.
+
 Continuation chains collapse into one journey: an issue that took six attempts
 is one merged outcome with six runs and one lead time. Runs whose spend reads
 $0.00 — harness telemetry absent (README Limitations) — are counted separately
-as unmetered and never averaged into cost as if they were free.
+as unmetered and never averaged into cost as if they were free. A daemon
+session whose provider reported no cost is counted the same way, and never
+printed as $0.00.
 
 flags:
   --since 7d | 30d | YYYY-MM-DD   window start (default 7d)
   --json                          print the stable report shape {project,
-                                  window, ghCalls, empty, total, repos} — keys
-                                  never move, so a consumer can rely on it
+                                  window, ghCalls, empty, total, repos,
+                                  models, sessions, groomSpendUsd,
+                                  groomUnmeteredSessions, unmeteredRoles} —
+                                  keys never move, so a consumer can rely on it
   --project NAME                  the project to report (required only when
                                   the config has more than one)
 
 When nothing settled in the window the report says so explicitly ("empty:
-true" in --json) rather than printing zeros that could read as measurements.`;
+true" in --json) rather than printing zeros that could read as measurements.
+Daemon session spend is still reported there: a dry queue is exactly when
+grooming runs, and that spend bought no outcome.`;
 
 export async function statsCommand(ctx: CommandContext): Promise<void> {
   // Help first: parsing stops before any config read or store open.
@@ -101,6 +115,7 @@ export async function statsCommand(ctx: CommandContext): Promise<void> {
       window,
       ghCalls: store.ghCallsBetween(window.sinceDay, window.untilDay),
       runs: store.statsRuns(project.name, window.sinceEpochMs),
+      sessions: store.sessionSpendSince(project.name, window.sinceEpochMs),
     });
     if (ctx.argv.includes("--json")) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
     else {

package/src/commands/worker.ts

@@ -4,11 +4,17 @@
  * Moved out of cli.ts's switch by the per-verb module split (#462);
  * the daemon discovery resolves through {@link requireDaemonControl} so a
  * live systemd-run daemon stays reachable when its pidfile is missing (#811).
+ *
+ * Run control is the most consequential mutating route on the daemon port — it
+ * can terminally settle a live run — so it carries the daemon's bearer token
+ * (Phase 4). The token is read, never minted: an absent file means no daemon
+ * has run under this home, and saying so is more useful than a bare 401.
  */
 
 import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { requireDaemonControl } from "../lifecycle.ts";
+import { httpAuthHeader, missingHttpTokenMessage } from "../http-token.ts";
 
 export async function workerCommand(ctx: CommandContext): Promise<void> {
 const sub = ctx.argv[1];
@@ -34,11 +40,13 @@ const project = findProject(loadConfig(), ctx.projectFlag);
 // because the runtime directory was wiped (#811). The refusal chain is
 // shared with `extend` through requireDaemonControl.
 const daemon = await requireDaemonControl(project.name);
+const auth = httpAuthHeader();
+if (auth === undefined) throw new Error(missingHttpTokenMessage());
 const response = await fetch(
   `http://127.0.0.1:${daemon.port}/runs/${issue}/${sub}`,
   {
     method: "PUT",
-    headers: { "content-type": "application/json" },
+    headers: { "content-type": "application/json", ...auth },
     body: JSON.stringify({
       project: project.name,
       source: "cli",

package/src/config-schema.ts

@@ -404,6 +404,19 @@ const projectSchema = z
     // authored line instead of silently degrading the fleet's grooming duty
     // to the default.
     groomBelow: z.union([z.number().int().min(1), z.literal("always")]).optional(),
+    // The daemon's own grooming-scout role (#1041). Validated with exactly the
+    // regex and message the review adjudicator is: one role-name grammar for
+    // every role token conductor stores, so an operator who mistypes a
+    // provider/model here hears the same authored line either place. Optional
+    // rather than `.default()`ed — a config that never answered stays
+    // unwritten and reads as DEFAULT_GROOM_ROLE, exactly like `groomBelow`.
+    groomRole: z
+      .string()
+      .regex(
+        REVIEW_ADJUDICATOR_RE,
+        "must name one OMP model role — a single role token like \"task\" (never a provider/model, which omp owns)",
+      )
+      .optional(),
     stateLabels: stateLabelsSchema.optional(),
     routing: routingSchema.optional(),
     caps: capsSchema.optional(),

package/src/config.ts

@@ -25,6 +25,7 @@ import {
   DEFAULT_ARM_PROOF,
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
+  DEFAULT_GROOM_ROLE,
   DEFAULT_PROJECT_POLICY,
   DEFAULT_REPORT_POLICY,
   DEFAULT_REPORT_SCOPE,
@@ -387,6 +388,24 @@ export function resolveReview(p: ProjectConfig): ReviewPolicy {
   };
 }
 
+/**
+ * The OMP model role this project's daemon-owned grooming scouts run under
+ * (#1041).
+ *
+ * One reader for the same reason {@link resolveReview} is one: the daemon
+ * launches these sessions unattended, so "which role did it spend under" must
+ * have exactly one answer, and a project that never chose gets
+ * {@link DEFAULT_GROOM_ROLE} — `task`, the general session role every install
+ * can launch without pinning a provider. Deliberately not folded into
+ * `review.adjudicator`: grooming judgement and review adjudication are
+ * separate operator choices, and sharing the key would silently move one when
+ * the other is retuned.
+ */
+export function resolveGroomRole(p: ProjectConfig): string {
+  const configured = p.groomRole;
+  return configured !== undefined && configured.trim() !== "" ? configured.trim() : DEFAULT_GROOM_ROLE;
+}
+
 /**
  * A policy with no array shared with its source.
  *
@@ -1263,6 +1282,13 @@ function finalizeProject(
   const workerModel =
     typeof rawWorkerModel === "string" && rawWorkerModel.trim() !== "" ? rawWorkerModel : undefined;
 
+  // The daemon's grooming-scout role (#1041), a hint like `workerModel`: zod
+  // already enforced the role-token grammar, so this only narrows the type and
+  // drops a blank. Absent stays absent — the daemon reads it as
+  // DEFAULT_GROOM_ROLE — so no config gains a key its operator never chose.
+  const rawGroomRole = p["groomRole"];
+  const groomRole = typeof rawGroomRole === "string" && rawGroomRole !== "" ? rawGroomRole : undefined;
+
   // The failover chain is a hint like workerModel, not a ceiling: an unusable
   // entry or a malformed threshold is dropped rather than failing the load,
   // and absent/empty `modelFallbacks` keeps today's dispatch byte for byte.
@@ -1367,6 +1393,7 @@ function finalizeProject(
     tracker: { kind: "github", repo: trackerRepo },
     queueLabel: p["queueLabel"] as string,
     ...(groomBelow === undefined ? {} : { groomBelow }),
+    ...(groomRole === undefined ? {} : { groomRole }),
     stateLabels: {
       inProgress: pickString(stateLabels?.["inProgress"], DEFAULT_STATE_LABELS.inProgress),
       blocked: pickString(stateLabels?.["blocked"], DEFAULT_STATE_LABELS.blocked),

package/src/daemon/ack.ts

@@ -0,0 +1,159 @@
+/**
+ * The admission acknowledgement fence: proof that a *running* daemon, not just
+ * a daemon-shaped process, has seen the current install and admitted work under
+ * it.
+ *
+ * Setup and upgrade both need that proof and neither can get it from the store,
+ * because a daemon that never reached its first tick would leave the last
+ * daemon's rows sitting there looking like an answer. So the record is written
+ * by the tick itself, stamped with the generation of the process that wrote it,
+ * and `wakeDaemon` is here beside it as the one nudge that shortens the wait for
+ * it to appear.
+ *
+ * Kept out of `admission.ts` (the top-level gate module) and out of
+ * `admission-pass.ts` (the tick's use of it) on purpose: this is neither a gate
+ * nor a pass, it is the handshake either side of a restart reads.
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stateDir } from "../config.ts";
+import { httpAuthHeader } from "../http-token.ts";
+import { SYSTEMD_UNIT, livingDaemon, probeUnit } from "../lifecycle.ts";
+import { pauseInstance } from "../pause.ts";
+
+// acknowledgement (#651, review #3)
+//
+// The setup-fence's "acknowledgement" must come from the daemon itself, not a
+// second synchronous worker count: a tick that passed its pause gate before
+// the fence landed can sit in awaited tracker/routing/admission work and claim
+// after the count and before setup mutates. Two places make that impossible
+// and record it durably:
+//
+//  - the tick's pause gate re-acknowledges every held pass (the daemon has
+//    reached its admission boundary and claims nothing);
+//  - the claim itself re-checks the pause immediately before creating the run
+//    row, so a tick already past its gate when the fence landed refuses at
+//    the claim — and writes the acknowledgement — instead of admitting.
+//
+// The acknowledgement file names the exact pause instance observed and the
+// daemon generation that observed it, so the setup barrier can prove the
+// acknowledged fence is the fence it froze and the acknowledgement belongs to
+// the daemon it began with.
+
+/** The durable admission acknowledgement a daemon writes when it observes a
+ *  pause fence at an admission boundary. */
+export interface AdmissionAckRecord {
+  /** The pause instance observed (source token, reason, creation instant). */
+  pause: { source: string; reason?: string; since: number };
+  /** The daemon generation that observed it — {@link daemonGeneration}. */
+  daemon: string;
+  /** When the daemon observed the fence. */
+  observedAt: number;
+}
+
+/** The acknowledgement file path. One per host: the fence is host-global. */
+export function admissionAckPath(): string {
+  return join(stateDir(), "admission-ack.json");
+}
+
+/**
+ * The generation identity of the running daemon, or `undefined` when nothing
+ * provably runs. The live pidfile record wins (its pid and boot instant
+ * identify the exact instance, #377); a record-less ACTIVE unit is still a
+ * running daemon and its MainPID is the generation that lets a fence spot a
+ * supervisor restart (#651 review #2). Shared by the ack writer and the setup
+ * barrier's identity so both sides of the acknowledgement name the same
+ * instance by the same rule.
+ */
+export function daemonGeneration(): string | undefined {
+  const daemon = livingDaemon();
+  if (daemon !== undefined) return `${daemon.pid}@${daemon.startedAt}`;
+  const ownership = probeUnit(SYSTEMD_UNIT);
+  return ownership.kind === "active" ? `systemd:${ownership.pid}` : undefined;
+}
+
+/** Reads the current admission acknowledgement, if one is readable. A corrupt
+ *  or unreadable file is absence — the barrier fails closed on the absence. */
+export function readAdmissionAck(): AdmissionAckRecord | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(admissionAckPath(), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object") return undefined;
+  const r = parsed as Record<string, unknown>;
+  const pause = r["pause"];
+  const daemon = r["daemon"];
+  const observedAt = r["observedAt"];
+  if (pause === null || typeof pause !== "object") return undefined;
+  const p = pause as Record<string, unknown>;
+  const source = p["source"];
+  const since = p["since"];
+  const reason = p["reason"];
+  if (typeof source !== "string" || source.length === 0) return undefined;
+  if (typeof since !== "number" || !Number.isFinite(since)) return undefined;
+  if (reason !== undefined && typeof reason !== "string") return undefined;
+  if (typeof daemon !== "string" || daemon.length === 0) return undefined;
+  if (typeof observedAt !== "number" || !Number.isFinite(observedAt)) return undefined;
+  return { pause: { source, since, ...(reason === undefined ? {} : { reason }) }, daemon, observedAt };
+}
+
+/**
+ * Writes the admission acknowledgement for the pause the daemon just observed.
+ * The observed instance is the most restrictive fence in force: a host-global
+ * sentinel gates every project and is the pause a host-wide transaction (setup,
+ * an all-projects hold) froze, so it wins over a project-scoped sentinel;
+ * otherwise the project's own sentinel is the effective one for the daemon's
+ * claims, matching {@link pauseInstance}. Recording the project sentinel while
+ * a global fence is also in force would name a narrower, older hold instead of
+ * the fence that actually gates the host — and a barrier that froze the global
+ * sentinel could then never match its own acknowledgement (#651 review #4). A
+ * no-op when no pause is readable: there is nothing to acknowledge. The
+ * generation is the writing daemon's own (the record it owns, or its
+ * supervised MainPID).
+ */
+export function writeAdmissionAck(project: string): void {
+  // `pauseInstance()` reads only the global sentinel; while it is in force it
+  // is the fence that gates every project, and the durable record must name it
+  // rather than a per-project hold that predates it.
+  const pause = pauseInstance() ?? pauseInstance(project);
+  if (pause === undefined) return;
+  const generation = daemonGeneration();
+  if (generation === undefined) return;
+  const path = admissionAckPath();
+  mkdirSync(dirname(path), { recursive: true });
+  const record: AdmissionAckRecord = { pause, daemon: generation, observedAt: Date.now() };
+  const tmp = `${path}.${process.pid.toString(36)}.${Date.now().toString(36)}.tmp`;
+  try {
+    writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+/** Wake the daemon's dispatch loop to prompt a pass (best-effort; used by the
+ *  setup barrier so a live daemon acknowledges the fence without waiting for
+ *  its next five-minute tick). A refused/failed wake just lengthens the wait;
+ *  the barrier's deadline is what bounds it.
+ *
+ *  `POST /wake` is authenticated (Phase 4), so this reads the token the daemon
+ *  minted at start. An absent token means no daemon has ever started under this
+ *  `$OMP_CONDUCTOR_HOME`, so there is nothing to wake: skip the request rather
+ *  than spend a round trip earning a 401. Still void, still best-effort — the
+ *  contract is unchanged, only the reason a wake can be a no-op is wider. */
+export async function wakeDaemon(port: number): Promise<void> {
+  const auth = httpAuthHeader();
+  if (auth === undefined) return;
+  try {
+    await fetch(`http://127.0.0.1:${port}/wake`, {
+      method: "POST",
+      headers: auth,
+      signal: AbortSignal.timeout(1_500),
+    });
+  } catch {
+    // Best-effort by contract: the caller's bounded wait is the backstop.
+  }
+}

package/src/daemon/admission-pass.ts

@@ -0,0 +1,135 @@
+/**
+ * The dispatcher's side of admission: how many slots there are, what to do with
+ * the candidates that got one, and how to describe the ones that did not.
+ *
+ * The gates themselves are `admission.ts` at the top level — pure, storeless,
+ * and shared with everything that needs to ask "would this be admitted". This
+ * module is deliberately the other half: it holds no rule, only the concurrency
+ * primitive every pass launches through (`WorkerPool`) and the two summaries the
+ * tick logs and the digest read. Hence the name — it is the *pass*, not the
+ * policy, and the two must not be one file or the policy becomes untestable
+ * without a pool.
+ */
+import type { Admission, AdmissionHold } from "../admission.ts";
+import type { AdmissionHoldReason, DispatchSummary } from "../types.ts";
+
+export const HOLD_SAMPLE_SIZE = 5;
+export const DEGRADED_HOLDS: ReadonlySet<AdmissionHoldReason> = new Set([
+  "parent-lookup-error",
+  "open-pr-lookup-error",
+  "issue-state-lookup-error",
+  "critical-base-verify-error",
+]);
+
+/** Groups transient decisions into the bounded record exposed by status. */
+export function summarizeDispatch(
+  ready: number,
+  routed: number,
+  claimed: number,
+  admitted: number,
+  holds: readonly AdmissionHold[],
+  completedAt = Date.now(),
+  settled = 0,
+  parked = 0,
+): DispatchSummary {
+  const groups = new Map<AdmissionHoldReason, { count: number; issues: number[]; details: string[] }>();
+  for (const hold of holds) {
+    const group = groups.get(hold.reason) ?? { count: 0, issues: [], details: [] };
+    group.count += 1;
+    if (group.issues.length < HOLD_SAMPLE_SIZE) {
+      // `issues` and `details` share the sample: the detail is only kept when
+      // the issue it explains is, so the arrays stay index-aligned.
+      group.issues.push(hold.issue);
+      if (hold.detail !== undefined) group.details.push(hold.detail);
+    }
+    groups.set(hold.reason, group);
+  }
+  return {
+    completedAt,
+    ready,
+    routed,
+    claimed,
+    admitted,
+    degraded: holds.some((hold) => DEGRADED_HOLDS.has(hold.reason)),
+    holds: [...groups]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([reason, group]) => ({
+        reason,
+        count: group.count,
+        issues: group.issues,
+        ...(group.details.length === 0 ? {} : { details: group.details }),
+      })),
+    settled,
+    // Omitted at zero so a pass with nothing parked keeps the pre-#507 record
+    // shape byte for byte — old persisted rows lack the key and readers use
+    // `?? 0` either way.
+    ...(parked === 0 ? {} : { parked }),
+  };
+}
+
+/**
+ * The record of a held pass (#497): the loop ran — settling and reconciling
+ * above the pause gate — but routing never happened and nothing was admitted.
+ * `ready`/`routed`/`claimed` stay 0 because they were never computed; the
+ * `paused` flag is what keeps a reader from reading them as an empty queue.
+ */
+export function summarizeHeldPass(settled: number, completedAt = Date.now()): DispatchSummary {
+  return {
+    completedAt,
+    ready: 0,
+    routed: 0,
+    claimed: 0,
+    admitted: 0,
+    degraded: false,
+    holds: [],
+    settled,
+    paused: true,
+  };
+}
+
+export interface WorkerPool {
+  launch(work: Promise<void>): void;
+  activeCount(): number;
+  drain(): Promise<void>;
+}
+
+/**
+ * Keeps background workers alive without making the five-minute tick await them.
+ *
+ * `onSettled` fires as each worker leaves the pool, whichever way it ended
+ * (#878): that is the instant a slot frees, and without it queued work waited
+ * for the next scheduled pass — up to five minutes of idle capacity that reads,
+ * from outside, exactly like a stalled queue. It only *prompts* a pass; every
+ * hold, drain, lane, budget and routing gate is re-evaluated by that pass as
+ * usual.
+ */
+export function createWorkerPool(onSettled?: () => void): WorkerPool {
+  const active = new Set<Promise<void>>();
+  return {
+    launch(work) {
+      active.add(work);
+      const settled = (): void => {
+        active.delete(work);
+        onSettled?.();
+      };
+      void work.then(settled, settled);
+    },
+    activeCount: () => active.size,
+    async drain() {
+      await Promise.allSettled(active);
+    },
+  };
+}
+
+/** `--once` awaits workers; the resident daemon registers them for shutdown. */
+export async function dispatchAdmissions(
+  admitted: readonly Admission[],
+  run: (admission: Admission) => Promise<void>,
+  pool?: WorkerPool,
+): Promise<void> {
+  if (pool !== undefined) {
+    for (const admission of admitted) pool.launch(run(admission));
+    return;
+  }
+  await Promise.allSettled(admitted.map(run));
+}