@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/agent/dispatcher.d.ts

@@ -5,12 +5,9 @@ import type { ResolvedContainerSpawn } from '../scaler/types.js';
 import { type ScalerAgentView } from '../scaler/agent-fit.js';
 import type { ResourceRequest } from '@kici-dev/engine';
 /**
- * Why a freed agent's queue drain claimed nothing.
- *
- * Named rather than inlined because the value travels: it is the `reason`
- * field of the drain-declined log line and the assertion subject of the tests
- * that pin each exit. The five members are the five ways
- * `Dispatcher.drainForAgent` can return without a dispatch.
+ * Why a freed agent's queue drain claimed nothing: one member per way
+ * `Dispatcher.drainForAgent` returns without a dispatch. Named because the value
+ * travels: it is the drain-declined log line's `reason` and the tests' subject.
  */
 export declare enum AgentDrainDecline {
     /** The agent id is not in the in-memory registry (already disconnected). */
@@ -25,30 +22,22 @@ export declare enum AgentDrainDecline {
     NoMatchingJob = "no-matching-job"
 }
 /**
- * Default per-pass cap on how many pending jobs a capacity-freed re-drive
- * re-offers to the scaler. Bounds the burst so a single free event cannot storm
- * the scaler; the per-backend spawn semaphore bounds actual provisioning, and a
- * job that gets `at-capacity` again stays pending for the next tick.
+ * Default per-pass cap on pending jobs a capacity-freed re-drive re-offers, so
+ * one free event cannot storm the scaler. The per-backend spawn semaphore bounds
+ * provisioning; a job that gets `at-capacity` again stays pending for the next tick.
  */
 export declare const DEFAULT_REDRIVE_BATCH = 10;
-/**
- * Metrics interface for dispatch operations.
- * Allows the dispatcher to update Prometheus counters without
- * directly importing the metrics module (dependency injection).
- */
+/** Dispatch metrics, injected so the dispatcher does not import the metrics module. */
 export interface DispatchMetrics {
-    /** Increment the jobs dispatched counter by status. */
     incJobsDispatched(status: 'dispatched' | 'queued' | 'rejected'): void;
-    /** Set the queue depth gauge. */
     setQueueDepth(depth: number): void;
     /** Record `count` pending jobs re-driven through the scaler by `trigger`. */
     incScalerRedispatch(trigger: ScalerRedispatchTrigger, count: number): void;
 }
 /**
- * Narrow slice of `HostRosterStore` the dispatcher needs for the host-restart
- * flow. Kept as an interface so the dispatcher doesn't import the full store
- * (which pulls in engine label matchers) and to make the reboot logic testable
- * with a tiny in-memory stub.
+ * Slice of `HostRosterStore` for the host-restart flow: an interface so the
+ * dispatcher avoids importing the full store (it pulls in engine label matchers)
+ * and the reboot logic is testable with an in-memory stub.
  */
 export interface HostRosterRebootStore {
     /** True when the host's reboot-pending deadline is still in the future. */
@@ -57,13 +46,10 @@ export interface HostRosterRebootStore {
     clearRebootPending(agentId: string): Promise<void>;
 }
 /**
- * Result of a dispatch attempt.
- *
- * `duplicate` = the dispatch_queue row for a preassigned (rerouted) jobId
- * already existed, so nothing was dispatched here (the claimed agent slot is
- * released and onDispatch is NOT called). The reroute caller should treat the
- * job as already handled. Only reachable on a reroute re-dispatch — first-
- * dispatch paths use a fresh UUID that can never collide.
+ * `duplicate`: the dispatch_queue row for a preassigned (rerouted) jobId already
+ * existed, so the claimed slot is released, onDispatch is NOT called, and the
+ * reroute caller treats the job as handled. Only a reroute re-dispatch reaches
+ * it; first dispatch uses a fresh UUID that cannot collide.
  *
  * `queued` also answers a direct dispatch refused because the job's run has
  * stopped: the queue row is recorded `expired` and the job cancelled, the
@@ -86,6 +72,17 @@ type DispatchResult = {
     status: 'rejected';
     reason: string;
 };
+/**
+ * The job's container spawn, from what dispatch already resolved on `jobConfig`:
+ * `container` from the lock, `containerRegistryAuth` orchestrator-side. Nothing
+ * is re-resolved — a second resolution is a second chance to disagree.
+ *
+ * A job that BUILDS its image (`container.dockerfile`) carries no `image`, so this
+ * returns `undefined` and no per-job-image spawn happens. Load bearing: the image
+ * does not exist until an agent clones and builds it, so an ordinary agent must
+ * run the job and nest the container. Exported so `dispatcher.test.ts` pins this
+ * routing decision.
+ */
 export declare function containerSpawnFor(jobConfig: Record<string, unknown> | undefined): {
     image: string;
     authconfig?: {
@@ -104,6 +101,14 @@ export interface DispatchRefusal {
 }
 /** The callback that sends a dispatched job to its agent. */
 export type OnDispatch = (agentId: string, job: QueuedJob) => void | DispatchRefusal | Promise<void | DispatchRefusal>;
+/**
+ * Dispatch coordinator: routes jobs to label-matching agents, falling back to the
+ * persistent queue, and handles agent connect, disconnect and job completion.
+ *
+ * It never touches WebSocket connections: the caller (orchestrator-core.ts or worker-core.ts)
+ * provides an onDispatch that looks up the agent's WS in the registry and sends
+ * the job.dispatch message.
+ */
 export declare class Dispatcher {
     private readonly registry;
     private readonly queue;
@@ -113,142 +118,120 @@ export declare class Dispatcher {
     /** See the constructor dep of the same name. */
     private readonly scalerAgentView?;
     /**
-     * Single-flight guard for `retryPendingScaleRequests`. The capacity-freed
-     * hook and the leader-gated sweep can both fire concurrently; this prevents
-     * two re-drives from double-offering the same pending jobs to the scaler in
-     * the same tick.
+     * Single-flight guard for `retryPendingScaleRequests`: the capacity-freed hook
+     * and the leader-gated sweep can fire concurrently and must not double-offer
+     * the same pending jobs to the scaler in one tick.
      */
     private redriveInFlight;
     /**
-     * Single-flight guard for `redrivePendingToConnectedAgents`. The per-coord
-     * safety-net tick must not overlap itself, so a slow re-drive can't be
-     * re-entered by the next interval fire and double-scan the same pending rows.
+     * Single-flight guard for `redrivePendingToConnectedAgents`: the next interval
+     * fire must not re-enter a slow re-drive and double-scan the same pending rows.
      */
     private pendingRedriveInFlight;
-    /**
-     * Tracks which jobs are dispatched to which agents.
-     * Used for marking jobs as failed on agent disconnect.
-     */
+    /** agentId -> dispatched jobIds, for failing jobs on agent disconnect. */
     private readonly agentJobs;
     /** Reverse map: jobId -> agentId, for cancel-run lookups. */
     private readonly jobToAgent;
     /**
-     * jobId -> runId for currently-tracked jobs. Populated alongside
-     * `jobToAgent`/`agentJobs` at dispatch time and cleared with them, so the
-     * provenance token relay can resolve a job's runId from the dispatcher's own
-     * state (`resolveOwnedJob`) rather than trusting an agent-asserted value.
+     * jobId -> runId, kept and cleared with `jobToAgent`/`agentJobs`, so the
+     * provenance token relay resolves a job's runId from dispatcher state
+     * (`resolveOwnedJob`) rather than trusting an agent-asserted value.
      */
     private readonly jobRunIds;
     /**
-     * Grace window for recently completed jobs.
-     * Allows late messages (log.chunk, step.status) to be accepted for a short
-     * period after job completion, preventing false ownership violations.
+     * Grace window for recently completed jobs: late messages (log.chunk,
+     * step.status) are accepted briefly after completion, not flagged as
+     * ownership violations.
      */
     private readonly completedJobs;
-    /** Cap on completedJobs map to prevent unbounded growth. */
+    /** Bounds completedJobs growth. */
     private static readonly COMPLETED_JOBS_CAP;
-    /** Grace window duration in milliseconds (30 seconds). */
     private static readonly GRACE_WINDOW_MS;
-    /** Interval for cleaning up expired grace window entries (10 seconds). */
     private static readonly GRACE_CLEANUP_INTERVAL_MS;
-    /** Timer for periodic grace cleanup. */
     private graceCleanupTimer;
-    /** Max reconnection delay from agent config, used to derive grace period. */
+    /** From agent config; derives the recovery grace period. */
     private readonly maxReconnectDelayMs;
     /**
-     * Callback fired when a job reaches a permanent dispatch-side failure:
-     * recovery window expired, re-dispatch attempts exhausted, or a
-     * scaler-managed agent was destroyed mid-execution. The receiver marks
-     * the execution-tracker job failed with the given reason.
+     * Fired on a permanent dispatch-side failure (recovery window expired,
+     * re-dispatch attempts exhausted, or a scaler-managed agent destroyed
+     * mid-execution); the receiver marks the execution-tracker job failed.
      */
     private readonly onJobFailedPermanently?;
-    /** Callback when a job enters recovery (starts timer). */
     private readonly onRecoveryStarted?;
     /** Fallback ack deadline when no getAckTimeoutMs dep is wired (tests). */
     private static readonly DEFAULT_ACK_TIMEOUT_MS;
     /**
-     * Pending dispatch acknowledgments: armed when a job.dispatch is sent,
-     * resolved by job.ack / job.reject / job.status running / disconnect
-     * triage. On expiry the dispatch is treated as lost: requeue + disconnect.
+     * Pending dispatch acks: armed when a job.dispatch is sent, resolved by
+     * job.ack / job.reject / job.status running / disconnect triage. On expiry the
+     * dispatch is lost: requeue + disconnect.
      */
     private readonly pendingAcks;
     /**
-     * Acks that arrived before their pending-ack entry was armed (the agent
-     * answered faster than the orchestrator could resolve the timeout + stamp
-     * the deadline). Keyed by jobId -> the agent that acked. Consumed by
-     * `armAckDeadline`, which then skips arming.
+     * jobId -> acking agent, for acks that beat their pending-ack entry (the agent
+     * answered before the timeout was resolved and the deadline stamped).
+     * `armAckDeadline` consumes it and skips arming.
      */
     private readonly earlyAcks;
-    /** Resolve the per-job ack deadline (per-org override / cluster default). */
+    /** Per-job ack deadline (per-org override / cluster default). */
     private readonly getAckTimeoutMs;
     /** Cancel + disconnect an agent whose dispatch ack deadline expired. */
     private readonly onAckTimeout?;
     /**
-     * Jobs that have reached agent-side execution (a `job.status: running`
-     * arrived). Disconnect triage treats never-started jobs as safely
-     * re-dispatchable; started jobs on destroyed agents fail fast.
+     * Jobs whose `job.status: running` arrived. Disconnect triage re-dispatches
+     * never-started jobs; started jobs on destroyed agents fail fast.
      */
     private readonly startedJobs;
     /**
-     * Per-job recovery timers for jobs in 'recovering' state.
-     * When an agent disconnects with in-flight jobs, each job gets a timer.
-     * If the agent reconnects before the timer fires, the timer is cancelled.
+     * Recovery timers for 'recovering' jobs: each in-flight job of a disconnected
+     * agent gets one, cancelled if the agent reconnects before it fires.
      */
     private readonly recoveringJobs;
-    /** Grace period = 2x max reconnection delay. */
     private get gracePeriodMs();
-    /** Host roster store for the reboot-pending gate; undefined ⇒ flow inert. */
+    /** For the reboot-pending gate; undefined ⇒ flow inert. */
     private readonly rosterStore?;
-    /** Coordinator drain predicate; when true, new jobs queue Pending instead of
-     *  dispatching. Defaults to never-draining. */
+    /** When true, new jobs queue Pending instead of dispatching. Defaults to never. */
     private readonly isDraining;
-    /** Whether another coordinator is live. Defaults to none (a single node). */
+    /** Defaults to none (a single node). */
     private readonly hasPeerCoordinators;
     constructor(deps: {
         registry: AgentRegistry;
         queue: JobQueue;
         metrics: DispatchMetrics;
         onDispatch: OnDispatch;
-        /** Optional hook called when no agent matches the job's labels.
-         *  When set, receives the per-job `resources` so the scaler can apply
-         *  per-scaler / per-orchestrator / per-machine caps before spawning. */
+        /** Called when no agent matches; gets the per-job `resources` so the scaler
+         *  applies per-scaler / per-orchestrator / per-machine caps before spawning. */
         onNoMatchingAgent?: (labels: string[], jobId: string, runId: string, excludeLabels: string[], resources?: ResourceRequest, orgId?: string, 
         /**
-         * The job's own container image plus registry credentials, already
-         * resolved at dispatch. Present means the backend spawns THAT image with
-         * the KiCI runtime injected instead of the pool's fixed agent image.
+         * The job's own image plus registry credentials, resolved at dispatch.
+         * Present: the backend spawns THAT image with the KiCI runtime injected
+         * instead of the pool's fixed agent image.
          */
         containerSpawn?: ResolvedContainerSpawn) => Promise<ScaleResult>;
         /**
-         * What the scaler knows about an agent it started
-         * (`ScalerManager.agentView`), or undefined for one it did not. It feeds
-         * `canAgentRunJob`: the job the agent was started for, whether it runs in
-         * that job's image, and a warm agent's fixed shape. Absent when no scaler
-         * is configured; the predicate then judges every agent on its own
-         * registration.
+         * What the scaler knows about an agent it started (`ScalerManager.agentView`),
+         * undefined for others. Feeds `canAgentRunJob`: the job the agent was started
+         * for, whether it runs in that job's image, a warm agent's fixed shape. Absent
+         * with no scaler; every agent is then judged on its own registration.
          */
         scalerAgentView?: (agentId: string) => ScalerAgentView | undefined;
-        /** Max reconnection delay from agent config (default 60s). Used to derive grace period. */
+        /** From agent config (default 60s); derives the grace period. */
         maxReconnectDelayMs?: number;
-        /** Callback fired when a job is permanently failed before/outside agent execution. */
+        /** Fired when a job is permanently failed before/outside agent execution. */
         onJobFailedPermanently?: (agentId: string, jobId: string, runId: string, reason: string) => void;
-        /** Callback when a job enters recovery (starts timer). */
+        /** Fired when a job enters recovery (its timer starts). */
         onRecoveryStarted?: (agentId: string, jobId: string) => void;
-        /** Resolve the per-job dispatch-ack deadline (ms). Defaults to 10s. */
+        /** Per-job dispatch-ack deadline (ms). Defaults to 10s. */
         getAckTimeoutMs?: (job: QueuedJob) => Promise<number>;
         /** Cancel + disconnect an agent whose dispatch ack deadline expired. */
         onAckTimeout?: (agentId: string, jobId: string, runId: string) => void;
         /**
-         * Host roster store, used for the workflow-level host-restart flow: gate the
-         * pinned-drain off for a reboot-pending agent, and treat a reboot-pending
-         * agent's disconnect as the expected reboot (complete its in-flight job
-         * success rather than starting the recovery-fail timer). Omitted ⇒ the
-         * reboot-pending behavior is inert (every host reads not-pending).
+         * For the host-restart flow: no pinned drain to a reboot-pending agent, and
+         * its disconnect is the expected reboot (in-flight job completes success, no
+         * recovery-fail timer). Omitted ⇒ inert (every host reads not-pending).
          */
         rosterStore?: HostRosterRebootStore;
-        /** Coordinator drain predicate. When true, dispatch() enqueues new jobs as
-         *  Pending and onAgentAvailable() claims nothing — jobs already on agents
-         *  finish. Defaults to never-draining. */
+        /** When true, dispatch() enqueues new jobs Pending and onAgentAvailable()
+         *  claims nothing; jobs already on agents finish. Defaults to never. */
         isDraining?: () => boolean;
         /**
          * Whether another coordinator is live: connected, or disconnected for less
@@ -261,365 +244,272 @@ export declare class Dispatcher {
     /** Runs with the ids of the jobs each disconnect triage failed; see {@link setDisconnectCleanup}. */
     private disconnectCleanup?;
     /**
-     * Install what runs with the ids of the jobs a disconnect triage failed. The
-     * agent WebSocket handler installs the release of their in-memory waiters
-     * (pending builds, inits, dynamic evaluations, global eval rounds). It runs
-     * inside {@link onAgentDisconnect}, so a path that drops an agent without
-     * waiting for its socket (heartbeat timeout, ack timeout, token revocation)
-     * reaches it too.
+     * The agent WS handler installs the release of the failed jobs' in-memory
+     * waiters (pending builds, inits, dynamic evaluations, global eval rounds). It
+     * runs inside {@link onAgentDisconnect}, so paths that drop an agent without
+     * its socket closing (heartbeat timeout, ack timeout, token revocation) reach it.
      */
     setDisconnectCleanup(cleanup: (failedJobIds: string[]) => void): void;
-    /**
-     * Dispatch a job to a matching agent, or queue it if none available.
-     *
-     * Flow:
-     * 1. Find available agents matching job's runsOnLabels.
-     * 2. If agent found: increment activeJobs, call onDispatch, return 'dispatched'.
-     * 3. If no agent: enqueue in queue, return 'queued'.
-     * 4. If queue full: return 'rejected'.
-     */
+    /** Dispatch a job to a matching agent, or queue it; 'rejected' when the queue is full. */
     dispatch(job: QueuedJobInput): Promise<DispatchResult>;
     /**
-     * Re-drive the scaler for jobs still pending after an `at-capacity` verdict.
-     *
-     * Called by the capacity-freed hook (`ScalerManager.onCapacityFreed`) and the
-     * leader-gated `PendingScaleSweeper`. Lists the oldest pending jobs (FIFO
-     * fairness — the longest-waiting burst victim gets the freed slot first) and
-     * re-runs the SAME `onNoMatchingAgent` → `requestScale` path used at dispatch
-     * time, so the re-drive inherits the per-backend spawn semaphore and cap
-     * accounting. A job that returns `at-capacity` again just stays pending for
-     * the next free/sweep tick — no retry state, no backoff bookkeeping.
+     * Re-drive the scaler for jobs still pending after `at-capacity`, from the
+     * capacity-freed hook (`ScalerManager.onCapacityFreed`) and the leader-gated
+     * `PendingScaleSweeper`. Oldest first (FIFO: the longest-waiting burst victim
+     * gets the freed slot), through the SAME `onNoMatchingAgent` → `requestScale`
+     * path as dispatch, so it inherits the spawn semaphore and cap accounting. A
+     * job that gets `at-capacity` again stays pending for the next tick — no retry
+     * state, no backoff.
      *
-     * Single-flight: a second call while one is in flight returns 0, so an
-     * overlapping hook+sweep cannot double-offer the same jobs. Bounded by
-     * `maxJobs` so one free event cannot storm the scaler.
-     *
-     * A job whose sealed secrets this coordinator cannot open is never scaled
-     * for: it is settled instead ({@link settleUnopenablePending}).
+     * Single-flight (an overlapping call returns 0, so hook+sweep never double-offer)
+     * and bounded by `maxJobs`. A job whose sealed secrets this coordinator cannot
+     * open is settled instead ({@link settleUnopenablePending}).
      *
      * @returns the number of jobs that entered `spawning`.
      */
     retryPendingScaleRequests(maxJobs?: number, trigger?: ScalerRedispatchTrigger): Promise<number>;
     /**
-     * Re-offer ONE pending job to the scaler: a worker's spawn-retry backoff ending.
-     *
-     * Outside the batch's single-flight on purpose: a wake-up that lands during a
-     * batch pass would otherwise be dropped, and a worker runs no pending-scale
-     * sweep to pick it up. The worker's per-job attempt gate is what keeps this
-     * from starting a second spawn for the same job.
+     * Re-offer ONE pending job to the scaler when a worker's spawn-retry backoff
+     * ends. Outside the batch single-flight on purpose: a wake-up during a batch
+     * pass would be dropped, and a worker runs no pending-scale sweep. The worker's
+     * per-job attempt gate prevents a second spawn for the same job.
      *
      * @returns true when a spawn started.
      */
     redrivePendingJob(jobId: string): Promise<boolean>;
     /**
-     * Offer one pending job to the scaler through the same `onNoMatchingAgent` →
-     * `requestScale` path a dispatch uses, or settle it when its sealed secrets
-     * cannot be opened here.
+     * Offer one pending job via the dispatch scale path, or settle it when its
+     * sealed secrets cannot be opened here.
      */
     private offerPendingToScaler;
     /**
-     * Release the slot claimed for a direct dispatch the queue refused because
-     * the job's run has stopped. Nothing is sent to the agent. The queue already
-     * recorded the row `expired` and cancelled the job, so the job reads as a
-     * queued job of the run that the cancel expired, and the caller tracks it
-     * under `queued` exactly as it would that one.
+     * Release the slot of a direct dispatch the queue refused because the run has
+     * stopped; nothing is sent. The queue already recorded the row `expired` and
+     * cancelled the job, so it reads as a queued job the cancel expired, and the
+     * caller tracks it under `queued` the same way.
      */
     private refuseStoppedRunDispatch;
     /**
-     * Dispatch a host-fanout pinned child. The job targets exactly
-     * `job.pinnedAgentId`: if that agent is locally connected, satisfies the
-     * runsOn/exclude/mandatory gate, and has capacity, dispatch immediately;
-     * otherwise queue it WITH the pin so the pin-aware drain delivers it when the
-     * agent frees up or (re)connects. A pinned job never falls through to a
-     * different agent.
+     * Dispatch a host-fanout pinned child to exactly `job.pinnedAgentId` when it is
+     * locally connected, passes the runsOn/exclude/mandatory gate and has capacity;
+     * otherwise queue it WITH the pin for the pin-aware drain when the agent frees
+     * up or (re)connects. Never falls through to a different agent.
      */
     private dispatchPinned;
     /**
-     * Eagerly dispatch a specific bound job to a freshly-registered
-     * scaler-managed agent.
+     * Eagerly dispatch the job the scaler bound at spawn time to a freshly
+     * registered scaler-managed agent (the agent-handler calls it right after
+     * registration). Atomically claims it (still pending, labels still satisfied),
+     * marks it dispatched and sends it.
      *
-     * Called by the agent-handler immediately after a scaler-managed agent
-     * registers, when the scaler had bound a queued jobId to that agent at
-     * spawn time. Atomically claims the job from the queue (validating it's
-     * still pending and the agent's labels still satisfy it), marks it
-     * dispatched, and sends it to the agent.
-     *
-     * Returns true only when the job was sent to the agent. False when nothing
-     * was claimed (the bound job was already claimed elsewhere, expired, or the
-     * agent isn't registered, is full or the coordinator is draining), and also
-     * when the claimed job was not sent: its dispatch was refused and it failed,
-     * or this coordinator could not open its sealed secrets. The caller falls
-     * back to the generic onAgentAvailable() drain in every false case.
+     * True only when sent. False when nothing was claimed (claimed elsewhere,
+     * expired, agent unregistered or full, coordinator draining) or the claimed
+     * job was not sent (refused and failed, or sealed secrets this coordinator
+     * cannot open). On false the caller falls back to the onAgentAvailable() drain.
      */
     dispatchBoundJob(agentId: string, jobId: string): Promise<boolean>;
     /** {@link dispatchBoundJob}, reporting whether the job was claimed apart from whether it was sent. */
     private claimBoundJob;
     /**
-     * Try draining the queue for a specific agent.
-     * Called when an agent registers or completes a job.
-     *
-     * Dequeues matching jobs from the queue while the agent has capacity,
-     * calling onDispatch for each.
-     */
-    /**
-     * Drop agents whose reboot-pending flag is set from a candidate list. Used by
-     * the label-routed dispatch path so a post-restart job is never sent to a host
-     * that is about to reboot. No-op when no roster store is wired.
+     * Drop reboot-pending agents, so label-routed dispatch never sends a
+     * post-restart job to a host about to reboot. No-op with no roster store.
      */
     private filterRebootPending;
     /**
-     * Drop the agents that cannot run this job (`canAgentRunJob`). Sibling of
-     * {@link filterRebootPending}: both remove candidates `findAvailable` matched
-     * on labels but that are unusable for a reason labels cannot express.
-     *
-     * The reasons: an agent started inside another job's image, a container job
-     * on an agent that reports no container runtime, a warm agent of another
-     * shape. Dropping the candidate here is what sends the job down the ordinary
-     * `onNoMatchingAgent` scale path.
-     *
-     * `jobId` is the job's queue id when it has one: it is how the agent started
-     * for the job recognizes it.
+     * Drop the agents that cannot run this job (`canAgentRunJob`): like
+     * {@link filterRebootPending}, a reason labels cannot express (started inside
+     * another job's image, no container runtime for a container job, a warm agent
+     * of another shape). Dropping them sends the job down the `onNoMatchingAgent`
+     * scale path. `jobId` (the queue id, when any) is how the agent started for
+     * the job recognizes it.
      */
     private filterUnservableAgents;
     /** The registration facts, and the scaler's record, `canAgentRunJob` judges an agent on. */
     private fitAgentFor;
     /**
-     * The fit question for one job: its queue id, the shape it declares, and
-     * what its `container:` asks of the agent's host.
+     * The fit question for one job: queue id, declared shape, and what its
+     * `container:` asks of the host.
      *
-     * The shape comes from `jobConfig.resources` when the typed `resources`
-     * mirror is absent, because the mirror is optional and several dispatch paths
-     * never fill it — a job reaching {@link dispatch} straight off the webhook
-     * pipeline or off a worker's reroute handler carries its declaration in
-     * `jobConfig` alone. Reading only the mirror there reports a job that
-     * declares nothing, which admits it onto a pre-spawned agent of some other
-     * size — the exact mismatch this gate exists to refuse.
+     * The shape falls back to `jobConfig.resources` because the typed `resources`
+     * mirror is optional and several paths never fill it: a job reaching {@link dispatch}
+     * off the webhook pipeline or a worker's reroute handler declares in
+     * `jobConfig` alone. Reading only the mirror admits it onto a pre-spawned agent
+     * of another size — the mismatch this gate exists to refuse.
      */
     private agentFitFor;
     /**
-     * The queue-drain half of {@link filterUnservableAgents}: a per-job
-     * predicate for one agent, or undefined when this agent needs no check.
-     *
-     * Undefined is the common answer for an agent that runs any job: the
-     * predicate could only ever say yes, and returning one would cost the drain
-     * its single-statement fast path for nothing.
+     * The queue-drain half of {@link filterUnservableAgents}: a per-job predicate
+     * for one agent, or undefined for an agent that runs any job — a predicate
+     * that only says yes would cost the drain its single-statement fast path.
      */
     private agentFitFilterFor;
     /**
-     * Release a reboot-pending host on its real reconnect (down-then-up). Clears
-     * the persisted flag so the very next `onAgentAvailable` drain dispatches the
-     * held post-restart job. Call this ONLY from the (re-)register path — a fresh
-     * connection after the box rebooted — never from a still-connected drain
-     * trigger (job completion / agent.status), which must keep the gate closed.
+     * Clear a reboot-pending host's flag on its real (down-then-up) reconnect, so
+     * the next `onAgentAvailable` drain dispatches the held post-restart job. Call
+     * ONLY from the (re-)register path, never from a still-connected drain trigger
+     * (job completion / agent.status), which must keep the gate closed.
      */
     releaseRebootPending(agentId: string): Promise<void>;
-    onAgentAvailable(agentId: string): Promise<void>;
     /**
-     * Claim at most one queued job for a freed agent.
-     *
-     * Returns the reason nothing was dispatched, or null when a job was.
+     * Try draining the queue for a specific agent. Called when an agent registers,
+     * completes a job or reports `agent.status`; claims at most one queued job per
+     * call ({@link drainForAgent}).
      */
+    onAgentAvailable(agentId: string): Promise<void>;
+    /** Claim at most one queued job for a freed agent; null when one was dispatched. */
     private drainForAgent;
     /** {@link deliver} inside the job's own request context, restored for a queue-drained job. */
     private deliverInRequestContext;
     /**
-     * Hand a tracked job to `onDispatch`. Returns false when the job was not sent:
-     * either the callback refused it, and the job is failed permanently since the
-     * refusal is a fact about the job and another agent would refuse it too; or
-     * this coordinator cannot open its sealed secrets, and the job is put back so
-     * a coordinator holding the key can take it, or failed when none can
-     * ({@link releaseUnopenableDispatch}).
+     * Hand a tracked job to `onDispatch`. False when not sent: the callback
+     * refused it (failed permanently — the refusal is a fact about the job, so
+     * another agent would refuse it too), or this coordinator cannot open its
+     * sealed secrets (put back for a key holder, or failed when none can:
+     * {@link releaseUnopenableDispatch}).
      */
     private deliver;
     /**
-     * Handle a claimed job whose sealed secrets this coordinator cannot open: it
-     * was sealed with a master key this coordinator does not hold.
+     * Handle a claimed job sealed with a master key this coordinator does not hold.
      *
-     * With another coordinator live this is not a permanent refusal: during a
-     * rolling master-key rotation that peer may already hold the new key, and if
-     * it does, its own drains can take the job. The row returns to pending,
-     * spending one dispatch attempt and recording the reason as the job's
+     * With a peer live it is not permanent: mid rolling master-key rotation the
+     * peer may hold the new key and its drains can take the job. The row returns
+     * to pending, spending one dispatch attempt and recording the reason as the
      * provisioning error (what an expiry reports), and this coordinator stops
-     * offering the job for the sealed-secrets back-off. Once the back-off lapses
-     * its drains and periodic re-drives offer the job again like any other, so a
-     * job no coordinator can open is claimed again and fails with the reason once
-     * {@link MAX_DISPATCH_ATTEMPTS} is reached. With no other coordinator live
-     * nobody can open it, so it fails at once.
+     * offering it for the sealed-secrets back-off. After that, drains and re-drives
+     * offer it again, so a job no coordinator opens fails with the reason at
+     * {@link MAX_DISPATCH_ATTEMPTS}. With no peer live it fails at once.
      *
-     * `agentId` is the agent the job was claimed for, or undefined when a re-drive
-     * claimed it for no agent ({@link settleUnopenablePending}).
+     * `agentId` is undefined when a re-drive claimed it for no agent
+     * ({@link settleUnopenablePending}).
      */
     private releaseUnopenableDispatch;
     /**
-     * Settle a pending job whose sealed secrets this coordinator cannot open,
-     * found by a re-drive that would otherwise scale for it.
-     *
-     * Scaling for the job is wrong twice over. The registry credentials of a
-     * private image are sealed with the job's other secrets, so a spawn of that
-     * image pulls without them and fails before any agent registers: the job is
-     * never claimed, never spends an attempt, and every re-drive spawns again.
-     * And any agent a spawn does start is one this coordinator would hand the job
-     * back from. So the job is claimed by id for no agent and gets the decision a
-     * drain that claimed it would give it ({@link releaseUnopenableDispatch}). A
-     * claim lost to another coordinator, or refused inside the back-off, leaves
-     * the job alone.
+     * Settle a pending job with unopenable sealed secrets that a re-drive would
+     * otherwise scale for. Scaling is wrong twice: a private image's registry
+     * credentials are sealed with the other secrets, so its spawn pulls without
+     * them and fails before any agent registers (never claimed, no attempt spent,
+     * every re-drive spawns again); and any agent a spawn starts would get the job
+     * handed back. So it is claimed by id for no agent and decided as a drain
+     * would ({@link releaseUnopenableDispatch}). A claim lost to another
+     * coordinator, or refused inside the back-off, leaves the job alone.
      */
     private settleUnopenablePending;
-    /**
-     * Undo the dispatch accounting of a refused job and fail it with the refusal
-     * reason. `agentId` is undefined for a job claimed for no agent.
-     */
+    /** Undo a refused job's accounting and fail it; `agentId` undefined = claimed for no agent. */
     private failRefusedDispatch;
     /** Free the slot and tracking a claim took on its agent; a claim for no agent took none. */
     private releaseClaimAccounting;
     /**
-     * Release the slot and tracking `jobId` holds on `agentId`, if the job is
-     * still tracked there. Returns false when another path (a refusal, a
-     * put-back, a disconnect) already took it.
+     * Release the slot and tracking `jobId` holds on `agentId`; false when another
+     * path (a refusal, a put-back, a disconnect) already took it.
      */
     private releaseTrackedClaim;
     /**
-     * Hand a job this coordinator just claimed from the queue to `agentId`,
-     * whose slot the claim took. A query that fails before the job is sent
-     * returns the claim ({@link returnUndeliveredClaim}) and rethrows, so the
-     * agent is not left holding a slot for a job it never received.
+     * Hand a just-claimed job to `agentId`, whose slot the claim took. A query
+     * failing before the send returns the claim ({@link returnUndeliveredClaim})
+     * and rethrows, so the agent holds no slot for a job it never received.
      *
      * @returns whether the job was sent.
      */
     private sendClaimedJob;
     /**
-     * Put back a job a queue claim took but did not send: a query failed between
-     * the claim and the send. The agent's slot (and the job's tracking, once
-     * taken) is released so the agent takes work again, and the row returns to
-     * pending without spending a dispatch attempt, since no agent saw it. The
-     * next drain or the pending re-drive offers it again. A job a refusal or a
-     * disconnect already took is left to that path. If the put-back fails too,
-     * the row stays dispatched with no ack deadline and the stale-dispatch scan
-     * reaps it.
+     * Put back a claimed job a query failure kept from being sent. The slot (and
+     * tracking, once taken) is released, and the row returns to pending without
+     * spending an attempt, since no agent saw it; the next drain or pending
+     * re-drive offers it again. A job a refusal or disconnect already took is left
+     * to that path. If the put-back fails too, the row stays dispatched with no ack
+     * deadline and the stale-dispatch scan reaps it.
      */
     private returnUndeliveredClaim;
-    /** Record that a job began executing on its agent. */
     markJobStarted(jobId: string): void;
     /**
-     * The agent accepted `jobId` (a `job.ack`, or the `running` status that stands
-     * in for a lost one). Drop a busy hold that already ran out: a job accepted
-     * while it sits on the entry was dispatched after it expired, into a free
-     * slot, so the agent's job count is not stuck and its next teardown-window
-     * rejection must not spend an attempt. A hold still in force is kept — see
-     * {@link AgentRegistry.clearExpiredBusyHold}.
+     * The agent accepted `jobId` (`job.ack`, or `running` standing in for a lost
+     * one). An expired busy hold is dropped: the job was dispatched after it ran
+     * out, into a free slot, so the job count is not stuck and the next
+     * teardown-window rejection must not spend an attempt. A hold still in force
+     * is kept — see {@link AgentRegistry.clearExpiredBusyHold}.
      */
     private noteJobAccepted;
     /**
      * Arm the ack deadline for a just-sent dispatch (timer + persisted row).
-     *
-     * Resolving the timeout and persisting the deadline both touch the DB, so
-     * a fast agent's job.ack can arrive before this method registers its
-     * in-memory entry. `earlyAcks` records such an ack so this method skips
-     * arming entirely instead of starting a timer that has nothing to resolve
-     * it (which would expire a dispatch the agent actually accepted).
+     * Resolving the timeout and persisting both touch the DB, so a fast job.ack can
+     * beat the in-memory entry; `earlyAcks` records it and arming is skipped, since
+     * a timer with nothing to resolve it would expire an accepted dispatch.
      */
     private armAckDeadline;
-    /**
-     * Consume a recorded early ack for `jobId` from `agentId`. Returns true if
-     * one was pending (and removes it).
-     */
+    /** Consume a recorded early ack for `jobId` from `agentId`; true if one was pending. */
     private consumeEarlyAck;
     /** Clear a pending ack (answered or otherwise settled). Idempotent. */
     private resolvePendingAck;
-    /** Handle an explicit dispatch acknowledgment (`job.ack`) from an agent. */
+    /** Handle a `job.ack` from an agent. */
     onJobAcked(agentId: string, jobId: string): void;
     /**
-     * The ack deadline expired: the dispatch is lost. Untrack the job, then
-     * remove the unresponsive agent from the registry BEFORE requeueing, so the
-     * redispatch cannot land the job back on the very agent we are tearing down.
-     * The job is already untracked when the WS close fires, so the disconnect
-     * triage finds nothing to double-handle.
+     * The ack deadline expired: the dispatch is lost. The job is untracked and the
+     * agent removed from the registry BEFORE the requeue, so the redispatch cannot
+     * land it back on the agent being torn down, and the later WS-close triage
+     * finds nothing to double-handle.
      */
     private handleAckExpiry;
     /**
-     * Drop an agent that did not acknowledge a dispatch. Its other in-flight jobs
-     * (a multi-slot agent may run more than the one that timed out) go through
-     * {@link onAgentDisconnect}, which reads the registration before its first
-     * await to tell a scaler-managed agent from a static one, so the triage
-     * starts first. The unregister right after removes the agent from routing at
-     * once, so a redispatch cannot re-select it while the triage awaits.
+     * Drop an agent that did not ack a dispatch. Its other in-flight jobs (a
+     * multi-slot agent) go through {@link onAgentDisconnect}, which reads the
+     * registration before its first await to tell scaler-managed from static, so
+     * the triage starts first; the unregister right after removes the agent from
+     * routing so a redispatch cannot re-select it while the triage awaits.
      */
     private dropUnacknowledgingAgent;
-    /**
-     * Handle an explicit dispatch rejection (`job.reject`) from an agent.
-     * Undoes the dispatch accounting and requeues the job for another agent.
-     */
+    /** Handle a `job.reject`: undo the dispatch accounting and requeue for another agent. */
     onJobRejected(agentId: string, jobId: string, reason: string): Promise<void>;
-    /** Remove a job from all per-agent in-memory tracking. */
     private untrackJob;
     /**
-     * Requeue a dispatched job for re-delivery, or fail it permanently when
-     * its attempt budget is exhausted. Returns the outcome so disconnect
-     * triage can surface failed job IDs to the caller. `countAttempt: false`
-     * requeues without spending the budget (a busy rejection).
+     * Requeue a dispatched job, or fail it once its attempt budget is exhausted;
+     * the outcome lets disconnect triage surface failed job IDs. `countAttempt:
+     * false` spends no budget (a busy rejection).
      */
     private requeueOrFail;
     /**
-     * The half of {@link requeueOrFail} that runs once the row has been flipped:
-     * fail the job when its attempt budget is exhausted, otherwise re-dispatch.
-     *
-     * Split out so the ack-expiry paths can drive it from the attempt count their
-     * own guarded requeue (`requeueIfAwaitingAck`) returned, instead of flipping
-     * the row a second time.
+     * The post-flip half of {@link requeueOrFail}: fail on an exhausted budget,
+     * else re-dispatch. Split out so ack expiry drives it from its guarded
+     * requeue's (`requeueIfAwaitingAck`) attempt count without flipping the row twice.
      */
     private finishRequeue;
     /**
-     * Try to deliver a requeued pending job: prefer an idle matching agent
-     * (atomic claim via dispatchBoundJob), otherwise consult the scaler so a
-     * fresh agent is spawned bound to this job.
+     * Deliver a requeued pending job: an idle matching agent (atomic claim via
+     * dispatchBoundJob), else the scaler spawns a fresh agent bound to it.
      */
     private redispatch;
     /**
-     * Safety-net re-drive: deliver every pending job that a currently-connected,
-     * idle, matching agent could take, through the same atomic claim the drain
-     * uses (`dispatchBoundJob` → `dequeueById`).
-     *
-     * Runs per-coordinator and is NOT leader-gated: each coordinator drains the
-     * shared queue onto its OWN connected agents, and the atomic claim guarantees
-     * at most one agent (on any coordinator) wins each job, so concurrent ticks
-     * cannot double-dispatch.
+     * Safety-net re-drive: deliver each pending job a connected, idle, matching
+     * agent could take, through the drain's atomic claim (`dispatchBoundJob` →
+     * `dequeueById`).
      *
-     * It closes the requeue re-drive gap. A job requeued by `handleAckExpiry` /
-     * `onJobRejected` / the leader ack sweep gets exactly one delivery attempt —
-     * `redispatch`'s single `findAvailable` + `dispatchBoundJob`. An idle matching
-     * agent whose own drain trigger (registration / completion / status) already
-     * fired before the requeue has no further trigger, so if that one attempt
-     * transiently misses the agent — the agent is momentarily at capacity while an
-     * in-flight drain holds its eagerly-claimed slot, or the agent is connected to
-     * a different coordinator than the one that ran the expiry — the requeued
-     * pending job would otherwise sit undelivered until it expired. This tick
-     * re-attempts delivery onto connected agents so the miss recovers on the next
-     * sweep.
+     * Per-coordinator, NOT leader-gated: each coordinator drains the shared queue
+     * onto its OWN agents, and the atomic claim lets at most one agent (on any
+     * coordinator) win each job, so concurrent ticks cannot double-dispatch.
      *
-     * It never consults the scaler (that is `retryPendingScaleRequests`) and never
-     * spawns: it only places jobs onto agents already connected here.
+     * It closes the requeue gap: a job requeued by `handleAckExpiry` /
+     * `onJobRejected` / the leader ack sweep gets one delivery attempt
+     * (`redispatch`'s `findAvailable` + `dispatchBoundJob`), and an idle agent whose
+     * drain trigger fired before the requeue gets no other. If that attempt misses
+     * (the agent momentarily at capacity while a drain holds its eagerly claimed
+     * slot, or connected to another coordinator than the one that ran the expiry),
+     * the job would sit until it expired; this tick recovers it on the next sweep.
      *
-     * Returns the number of jobs sent. A job it claims but does not send (its
-     * dispatch refused, or its sealed secrets unopenable here) is not counted.
+     * Never consults the scaler (that is `retryPendingScaleRequests`) or spawns.
      *
-     * A failure propagates to the caller rather than being swallowed here — the
-     * per-coord interval wrapper is the single error-log site, matching the
-     * sibling recovery/ack sweeps that share its cadence. The `finally` only
-     * releases the single-flight guard.
+     * Returns the jobs sent; a claimed job not sent (refused, or sealed secrets
+     * unopenable here) is not counted. Failures propagate: the per-coord interval
+     * wrapper is the single error-log site, like the sibling recovery/ack sweeps
+     * on its cadence. The `finally` only releases the single-flight guard.
      */
     redrivePendingToConnectedAgents(maxJobs?: number): Promise<number>;
     /**
-     * Pick a connected agent that may take a pending job, or null. A pinned
-     * host-fanout child may run ONLY on its pinned agent — and `dequeueById`
-     * ignores the pin — so a pinned job is routed to its own agent and never
-     * offered to `findAvailable`, which would mis-deliver it to any label match.
+     * Pick a connected agent for a pending job, or null. A pinned host-fanout child
+     * runs ONLY on its pinned agent and `dequeueById` ignores the pin, so it never
+     * goes to `findAvailable`, which would mis-deliver it to any label match.
      *
-     * Reboot-pending gate: a host whose `restart` job just completed is still
-     * connected but about to reboot, so its held post-restart job must NOT be
-     * re-driven into the about-to-die box. This is the safety-net re-drive's
-     * counterpart of the same gate in `dispatch()` / `dispatchPinned` /
-     * `drainForAgent`; without it this path re-drives the held job onto the
-     * reboot-pending host and defeats the hold.
+     * Reboot-pending gate: the safety-net counterpart of the gate in `dispatch()` /
+     * `dispatchPinned` / `drainForAgent`; without it this path re-drives the held
+     * post-restart job onto the about-to-reboot host and defeats the hold.
      */
     private selectConnectedTargetForPending;
     /**
@@ -627,160 +517,116 @@ export declare class Dispatcher {
      * immediately failing jobs, giving the agent a grace period to reconnect.
      * If no in-flight jobs, performs a clean disconnect.
      *
-     * Returns empty array (no immediately failed jobs -- failures happen
-     * asynchronously when recovery timers expire).
+     * Returns the started jobs a scaler-managed agent's disconnect failed outright;
+     * otherwise empty (failures happen asynchronously when recovery timers expire).
      */
     onAgentDisconnect(agentId: string): Promise<string[]>;
     /**
-     * Reboot-pending agent disconnected: complete its in-flight started job(s) as
-     * success (the restart job, which already reported success, may already be
-     * terminal — `markCompleted` is a no-op / guarded in that case). Never starts
-     * a recovery timer. Untracks the jobs so the reconnect does not reconcile a
-     * phantom in-flight set.
+     * Complete a reboot-pending agent's in-flight started jobs as success (the
+     * restart job may already be terminal; `markCompleted` is guarded then). No
+     * recovery timer. Untracked so the reconnect reconciles no phantom in-flight set.
      */
     private completeInFlightForReboot;
-    /** Drop grace-window entries owned by an agent. */
     private cleanupGraceEntriesForAgent;
-    /**
-     * Scaler-managed agent disconnected: requeue never-started jobs, fail
-     * started ones. Returns the permanently failed job IDs.
-     */
+    /** Scaler-managed disconnect: requeue never-started jobs, fail started ones (returned). */
     private triageScalerManagedDisconnect;
     /**
-     * Static agent disconnected: start per-job recovery timers (the agent
-     * may reconnect and reclaim). Always returns [] — failures happen
-     * asynchronously when recovery timers expire.
+     * Static disconnect: per-job recovery timers (the agent may reconnect and
+     * reclaim). Always returns []; failures happen when the timers expire.
      */
     private startRecoveryForDisconnect;
     /**
-     * Called when an agent completes a job (success or failure).
-     * Decrements active jobs and moves the job to the grace window
-     * (instead of immediately removing it) so that late messages
-     * (e.g. final log chunks) are still accepted.
+     * An agent finished a job (success or failure). The job moves to the grace
+     * window rather than being removed, so late messages (final log chunks) are
+     * still accepted.
      */
     onJobComplete(agentId: string, jobId: string): void;
     /**
-     * Check if a job is owned by the given agent.
-     * Returns true if the job is actively dispatched to the agent,
-     * in recovery (agent disconnected but within grace period),
-     * or in the grace window (completed within the last 30 seconds).
+     * True if the job is dispatched to the agent, recovering (disconnected within
+     * the grace period), or in the grace window (completed in the last 30 seconds).
      */
     isJobOwnedByAgent(agentId: string, jobId: string): boolean;
-    /**
-     * Resolve which agent a dispatched job was sent to.
-     * Used by the cancel-run API. Returns null if the job is not tracked (e.g. already completed).
-     */
+    /** For the cancel-run API; null once the job is untracked (e.g. completed). */
     getAgentIdForJob(jobId: string): string | null;
     /** The jobs of `runId` this dispatcher currently tracks to an agent. */
     getTrackedJobIdsForRun(runId: string): string[];
-    /**
-     * Start periodic cleanup of expired grace window entries.
-     * Should be called during server startup.
-     */
+    /** Start periodic cleanup of expired grace window entries; call at server startup. */
     startGraceCleanup(): void;
-    /**
-     * Stop periodic grace cleanup.
-     * Should be called during server shutdown.
-     */
+    /** Call at server shutdown. */
     stopGraceCleanup(): void;
     /**
-     * Claim a recovering job back for a reconnected agent.
-     * Cancels the recovery timer and returns true if the job was in recovery
-     * for this agent. Returns false if the job is not recovering or belongs
-     * to a different agent.
+     * Claim a recovering job back for a reconnected agent, cancelling its timer;
+     * false if it is not recovering or belongs to a different agent.
      */
     claimRecovery(jobId: string, agentId: string): boolean;
     /**
-     * Full reconciliation of a recovering job for a reconnected agent.
-     * Claims the recovery timer, transitions DB status back to dispatched,
-     * and restores in-memory tracking. Returns true if reconciled.
+     * Reconcile a recovering job for a reconnected agent: claim the timer, move
+     * the DB row back to dispatched, restore in-memory tracking.
      */
     reconcileRecovery(jobId: string, agentId: string): Promise<boolean>;
-    /**
-     * Get recovery info for a job (for structured logging).
-     */
+    /** For structured logging. */
     getRecoveryInfo(jobId: string): {
         disconnectedAt: number;
         agentId: string;
     } | null;
-    /**
-     * Get all recovering job IDs for a specific agent.
-     * Used during reconnection reconciliation.
-     */
+    /** For reconnection reconciliation. */
     getRecoveringJobsForAgent(agentId: string): string[];
     /**
-     * Restore a reconciled job into the dispatcher's in-memory tracking.
-     * Called when an agent reconnects and claims a recovering job. A
-     * reconnecting agent reporting the job in-flight means it had started,
-     * so mark it started for disconnect triage.
+     * Restore a job a reconnected agent claimed from recovery. The agent reports
+     * it in-flight, so it had started: marked started for disconnect triage.
      */
     restoreJobForAgent(agentId: string, jobId: string, runId?: string): void;
     /**
-     * Start a recovery timer for a job found in 'dispatched' state on startup.
-     * Called by server.ts/standalone.ts to create recovery timers for jobs
-     * from a previous orchestrator instance.
+     * Start a recovery timer for a job found 'dispatched' at startup. Called by
+     * orchestrator-core.ts for jobs from a previous orchestrator instance.
      */
     startRecoveryTimer(jobId: string, agentId: string, runId: string): Promise<void>;
     /**
-     * Rebuild the in-memory `recoveringJobs` Map from persisted
-     * `dispatch_queue` rows after a coord boot / Raft leader switch.
-     *
-     * For each `status='recovering'` row:
-     *   - if `recovery_deadline` is in the future, recreate a setTimeout
-     *     with the remaining window so the local sweep still fires.
-     *   - if the deadline is already in the past, leave the row alone —
-     *     the leader-gated `sweepExpiredRecoveries()` will pick it up on
-     *     its next tick (which avoids two coords racing to mark the same
-     *     job failed during recovery).
-     *   - rows with NULL deadline (pre-migration recovering jobs) are
-     *     fast-failed by the sweep on its first run.
+     * Rebuild `recoveringJobs` from `dispatch_queue` after a coord boot / Raft
+     * leader switch. Per `status='recovering'` row:
+     *   - future `recovery_deadline`: re-arm a timer for the remaining window.
+     *   - past deadline: left to the leader-gated `sweepExpiredRecoveries()`, so
+     *     two coords never race to mark the same job failed.
+     *   - NULL deadline (pre-migration recovering jobs): the sweep fast-fails it
+     *     on its first run.
      */
     recoverState(): Promise<void>;
     /**
-     * Leader-gated sweep: requeue every `dispatched` row whose ack deadline
-     * passed while no coord was watching (owning coord crashed before its
-     * in-memory timer fired). Requeue is atomic (WHERE status='dispatched'),
-     * so racing coords cannot double-requeue.
+     * Leader-gated sweep: requeue `dispatched` rows whose ack deadline passed
+     * unwatched (the owning coord crashed before its timer fired). The requeue is
+     * atomic (WHERE status='dispatched'), so racing coords cannot double-requeue.
      */
     sweepExpiredAckDeadlines(): Promise<number>;
     /**
-     * Leader-gated sweep: mark every `recovering` row whose
-     * `recovery_deadline < now` as `failed` and fire the per-job
-     * `onJobFailedPermanently` hook. Intended to run on the Raft leader at a
-     * fixed interval so jobs whose owning coord crashed mid-recovery
-     * still reach a terminal state.
-     *
-     * Safe to call on non-leaders (idempotent due to the WHERE clause)
-     * but skipping the call on followers avoids redundant DB updates.
+     * Leader-gated sweep: fail `recovering` rows with `recovery_deadline < now`
+     * and fire `onJobFailedPermanently`, so jobs whose owning coord crashed
+     * mid-recovery still reach a terminal state. Runs on the Raft leader at a
+     * fixed interval; idempotent on followers (WHERE clause), skipped there to
+     * avoid redundant DB updates.
      */
     sweepExpiredRecoveries(): Promise<number>;
-    /**
-     * Stop all recovery timers. Called during graceful shutdown.
-     */
+    /** Called during graceful shutdown. */
     stopRecoveryTimers(): void;
     /**
-     * Handle recovery timer expiry for a single job.
-     * Extracted so that both onAgentDisconnect and startRecoveryTimer share the same logic,
-     * and the caller can `.catch()` to prevent unhandled rejections in setTimeout.
+     * Recovery timer expiry for one job, shared by onAgentDisconnect and
+     * startRecoveryTimer; callers `.catch()` it to avoid unhandled rejections in
+     * setTimeout.
      */
     private handleRecoveryExpiry;
-    /** Remove expired entries from the completedJobs grace window map. */
     private cleanupExpiredGraceEntries;
     private trackJobForAgent;
     /**
-     * Verify `agentId` currently owns `jobId`; if so, return the job's runId from
-     * the dispatcher's own tracking. Used by the provenance token relay so the
-     * orchestrator binds a minted token to a job the agent actually owns — the
-     * agent never asserts a runId. Returns `undefined` when the agent does not
-     * own the job (or the runId is no longer tracked).
+     * The runId of `jobId` from dispatcher tracking, if `agentId` currently owns
+     * it; else `undefined` (also when the runId is no longer tracked). The
+     * provenance token relay binds a minted token to a job the agent actually
+     * owns — the agent never asserts a runId.
      */
     resolveOwnedJob(agentId: string, jobId: string): {
         runId: string;
     } | undefined;
     /**
-     * Cancel a queued job (mark as failed in the dispatch queue).
-     * Used by the coordinator to clean up local fallback entries when a peer
-     * accepts the rerouted job.
+     * Mark a queued job failed: the coordinator cleans up its local fallback
+     * entry once a peer accepts the rerouted job.
      */
     cancelQueuedJob(jobId: string, reason: string): Promise<void>;
     private updateQueueDepthMetric;