@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/agent/registry.d.ts

@@ -1,12 +1,7 @@
 /**
- * In-memory agent registry with label-based lookup and capacity tracking.
- *
- * Follows the Platform ConnectionRegistry dual-map pattern:
- * - Primary map: agentId -> AgentEntry (direct agent lookup)
- * - Secondary map: label -> Set<agentId> (reverse index for label-based dispatch queries)
- * - WS reverse map: ws -> agentId (fast lookup on WS events)
- *
- * No persistence needed -- agents re-register on reconnect.
+ * In-memory agent registry with label-based lookup and capacity tracking, following the
+ * Platform ConnectionRegistry dual-map pattern. No persistence needed: agents re-register
+ * on reconnect.
  */
 import { type CanonicalLabel, type LabelMatcher } from '@kici-dev/engine';
 import type { WsLike } from '@kici-dev/engine';
@@ -32,87 +27,81 @@ export declare enum BusyHoldOutcome {
  */
 export declare function agentHasFreeSlot(entry: AgentEntry, now?: number): boolean;
 export type { WsLike } from '@kici-dev/engine';
-/**
- * A single tracked agent connection.
- */
+/** A single tracked agent connection. */
 export interface AgentEntry {
-    /** Unique agent identifier. */
     agentId: string;
-    /** The underlying WebSocket (or mock). */
     ws: WsLike;
     /**
-     * Set of labels this agent provides (e.g., "linux", "gpu", "docker"), folded
-     * to canonical form by `register()`. The label reverse index is keyed the
+     * Folded to canonical form by `register()`. The label reverse index is keyed the
      * same way, so a lookup must fold its query before it reaches either.
      */
     labels: Set<CanonicalLabel>;
     /**
-     * Kubernetes-taint-style mandatory labels inherited from the scaler that
-     * spawned this agent. A job is only dispatched to this agent when every
-     * label in `mandatoryLabels` appears in `runsOnLabels` (in addition to the
-     * existing subset/exclusion checks).
+     * Kubernetes-taint-style gate copied from the spawning scaler's `mandatoryLabels`
+     * block: a job is dispatched here only when every one of these appears in its
+     * `runsOnLabels`, on top of the subset/exclusion checks. Empty for static agents and
+     * warm-pool replenishment spawns (no gate).
      *
-     * Empty for static agents and warm-pool replenishment spawns — those have
-     * no opt-in gate and behave exactly as before. Populated only when the
-     * spawning scaler declared a `mandatoryLabels` block; the value is a copy
-     * of the scaler's gate (the scaler-side gate in `findBackendForLabels` is
-     * not enough — once the agent registers, the queue-drain path
-     * (`onAgentAvailable` → `dequeueForLabels`) sees only the agent's labels
-     * and would otherwise pull a queued job whose `runsOn` is a subset of the
-     * agent's labels but does not satisfy the gate).
+     * The scaler-side gate in `findBackendForLabels` is not enough: once the agent
+     * registers, the queue-drain path (`onAgentAvailable` → `dequeueForLabels`) sees only
+     * the agent's labels and would pull a queued job whose `runsOn` is a subset of them
+     * but does not satisfy the gate.
      *
-     * Folded to canonical form by `register()`, so a scaler that declared `GPU`
-     * gates the same jobs a scaler that declared `gpu` does.
+     * Folded to canonical form by `register()`, so a scaler that declared `GPU` gates the
+     * same jobs one that declared `gpu` does.
      */
     mandatoryLabels: Set<CanonicalLabel>;
     /**
-     * True when this agent was spawned by a scaler backend. Scaler-managed
-     * agents are single-use: the scaler destroys them on disconnect, so they
-     * can never reconnect to reclaim recovering jobs. The dispatcher uses
-     * this to triage disconnects (requeue / fail-fast) instead of starting a
-     * recovery window that cannot succeed.
+     * Scaler-spawned agents are single-use: the scaler destroys them on disconnect, so
+     * they never reconnect to reclaim recovering jobs. The dispatcher triages their
+     * disconnects (requeue / fail-fast) instead of starting a recovery window that
+     * cannot succeed.
      */
     scalerManaged: boolean;
     /**
      * True while this agent is being torn down and must receive no new work.
      *
-     * The warm pool decides an agent is idle, marks it, then awaits a destroy
-     * that takes seconds — a container `stop({ t: 5 })`, or a Firecracker
-     * `SendCtrlAltDel` plus its grace. The registry entry survives until the
-     * agent's WebSocket actually closes, so without this flag `findAvailable`
-     * kept returning the agent throughout: a job arriving in that window was
-     * dispatched onto a container that was already exiting, and failed as a
-     * spurious infrastructure error on a healthy system.
+     * A warm-pool destroy takes seconds (a container `stop({ t: 5 })`, or a Firecracker
+     * `SendCtrlAltDel` plus its grace), and the entry survives until the WebSocket closes.
+     * Without this flag `findAvailable` keeps returning the agent, and a job arriving in
+     * that window lands on an exiting container and fails as a spurious infrastructure
+     * error.
+     *
+     * In memory rather than DB-backed, unlike reboot-pending: the destroy is issued by
+     * this process, lasts seconds, and ends with the WebSocket close that removes the
+     * entry — there is nothing to outlive.
      *
-     * In memory rather than DB-backed, unlike reboot-pending: a warm-pool
-     * destroy is issued by this process, lasts seconds, and ends with the
-     * WebSocket close that removes the entry — there is nothing to outlive.
+     * Also set when the agent itself reports `draining` on `agent.status` (a SIGUSR1
+     * drain, or a single-job agent that accepted its job); see {@link drainReported}.
      */
     draining: boolean;
+    /**
+     * The agent reported `draining` itself. Its drain is terminal for this connection,
+     * so {@link AgentRegistry.clearDraining} (the warm-pool undo) leaves it draining.
+     */
+    drainReported?: boolean;
     /**
      * Epoch ms until which the agent is held out of routing after it rejected a
      * dispatch as busy. Unset when no hold is in force. See {@link AgentRegistry.markBusyHeld}.
      */
     busyHeldUntil?: number;
-    /** Number of jobs currently executing on this agent. */
     activeJobs: number;
-    /** Maximum concurrent jobs this agent can handle (default 1). */
+    /** Default 1. */
     maxConcurrency: number;
-    /** Unix epoch ms of the last heartbeat received. */
+    /** Unix epoch ms. */
     lastHeartbeatAt: number;
-    /** Agent platform (os.platform(), e.g. 'linux', 'darwin', 'win32'). */
+    /** `os.platform()`, e.g. 'linux', 'darwin', 'win32'. */
     platform: string;
-    /** Agent architecture (os.arch(), e.g. 'x64', 'arm64'). */
+    /** `os.arch()`, e.g. 'x64', 'arm64'. */
     arch: string;
-    /** Unix epoch ms when the agent registered. */
+    /** Unix epoch ms. */
     registeredAt: number;
-    /** Self-reported agent version (e.g. "0.0.1"). Null if not reported. */
+    /** Self-reported; null if not reported. */
     version: string | null;
     /**
-     * The `agent_tokens.id` row used to authenticate this connection, or
-     * `null` when auth mode is `none`. Indexed by `tokenIdIndex` so a
-     * synchronous revocation kick can enumerate every WS authenticated by
-     * a given token.
+     * The `agent_tokens.id` that authenticated this connection, `null` when auth mode is
+     * `none`. Indexed by `tokenIdIndex` so a synchronous revocation kick can enumerate
+     * every WS authenticated by a token.
      */
     tokenId: string | null;
     hostname: string | null;
@@ -127,10 +116,9 @@ export interface AgentEntry {
     memoryAvailableMb: number | null;
     uptimeSeconds: number | null;
     /**
-     * The auth token's `agent_type` (`'static'` | `'ephemeral'`) snapshot, or
-     * `null` when auth mode is `none`. Drives the host roster's
-     * `lifecycle_class` — `static` rows persist + alarm on absence, `ephemeral`
-     * rows are GC'd past their ttl.
+     * The auth token's `agent_type` snapshot, `null` when auth mode is `none`. Drives the
+     * host roster's `lifecycle_class`: `static` rows persist and alarm on absence,
+     * `ephemeral` rows are GC'd past their ttl.
      */
     tokenAgentType: 'static' | 'ephemeral' | null;
 }
@@ -144,42 +132,30 @@ interface AgentMetadata {
     nodeVersion?: string;
     runningAsUser?: string;
     runningAsUid?: number;
-    /**
-     * The `agent_tokens.id` row used to authenticate this connection.
-     * `null` when auth mode is `none` (no token-based auth applied).
-     * Indexed for `disconnectByTokenId(...)` revocation kicks.
-     */
+    /** `null` when auth mode is `none`. Indexed for `disconnectByTokenId(...)` revocation kicks. */
     tokenId?: string | null;
     /**
-     * Kubernetes-taint-style mandatory labels inherited from the scaler that
-     * spawned this agent. Empty / undefined for static agents (no opt-in
-     * gate). Populated by `agent-handler.ts` from the scaler manager's
-     * `onAgentRegistered(...)` return value.
+     * Set by `agent-handler.ts` from the scaler manager's `onAgentRegistered(...)` return
+     * value. Empty / undefined for static agents (no gate).
      */
     mandatoryLabels?: string[];
-    /**
-     * True when a scaler backend spawned this agent (single-use; destroyed
-     * on disconnect). Set by `agent-handler.ts` from the presence of the
-     * scaler registration metadata.
-     */
+    /** Set by `agent-handler.ts` from the presence of the scaler registration metadata. */
     scalerManaged?: boolean;
     /**
-     * The auth token's `agent_type` (`'static'` | `'ephemeral'`), threaded from
-     * `agent-handler.ts` so the host roster can snapshot it as the row's
+     * Threaded from `agent-handler.ts` so the host roster can snapshot it as the row's
      * `lifecycle_class`. `null` / undefined when auth mode is `none`.
      */
     tokenAgentType?: 'static' | 'ephemeral' | null;
     /**
-     * Agent-reported typed host-vars (the `KICI_PROPERTIES` bag), threaded from
-     * the `agent.register` message into the roster upsert (shallow-merged with
-     * any operator-declared properties). Undefined ⇒ the agent reported none.
+     * Agent-reported typed host-vars (the `KICI_PROPERTIES` bag), passed into the roster
+     * upsert (shallow-merged with any operator-declared properties). Undefined ⇒ the
+     * agent reported none.
      */
     properties?: Record<string, string | number | boolean>;
 }
 /**
- * Subset of `HostRosterStore` the registry reconciles into. Optional — when no
- * store is injected (e.g. workers, which have no DB), the reconcile hooks are
- * a no-op and the in-memory registry behaves exactly as before.
+ * Subset of `HostRosterStore` the registry reconciles into. Optional: with no store
+ * injected (e.g. workers, which have no DB), the reconcile hooks are a no-op.
  */
 export interface RosterReconciler {
     upsert(input: {
@@ -204,57 +180,34 @@ export interface AgentRegistryDeps {
     instanceId?: string;
 }
 export declare class AgentRegistry {
-    /** Primary: agentId -> AgentEntry */
     private readonly agents;
-    /** Secondary: label -> Set<agentId> (reverse index for label-based queries) */
+    /** label -> agentIds, keyed on the canonical label. */
     private readonly labelIndex;
-    /** Reverse: ws -> agentId (for fast lookup on WS events) */
     private readonly wsToAgentId;
     /**
-     * Reverse: tokenId -> Set<agentId> (for synchronous revocation kicks).
-     *
-     * Populated when `register()` is called with a non-null `tokenId`,
-     * cleaned up by `removeFromIndexes()` on `unregister()` /
-     * re-registration. `disconnectByTokenId(tokenId)` walks the matching
-     * set, closes each WS, and unregisters the entry — closing the
-     * gap where a revoked token's in-flight WS retained data-plane
-     * authority until the agent itself disconnected.
+     * tokenId -> agentIds, for synchronous revocation kicks: `disconnectByTokenId` closes
+     * each WS so a revoked token's in-flight connection loses data-plane authority at
+     * once instead of when the agent disconnects.
      */
     private readonly tokenIdIndex;
     /**
-     * Per-tokenId TTL kick timer, keyed by `tokenId`. Scheduled by
-     * `scheduleExpiryKick(tokenId, expiresAt)` at agent register-time
-     * when the auth token has a non-null `expires_at`. Fires
-     * `disconnectByTokenId(tokenId)` when the token's TTL elapses, and
-     * is cleared when (a) the timer fires, (b) `disconnectByTokenId` is
-     * called explicitly via revocation (no double-kick when revoke
-     * races TTL), or (c) the last agent under the tokenId unregisters
-     * naturally (avoid timer leaks on long-lived registries).
-     *
-     * Idempotent: re-scheduling the same tokenId is a no-op as long as
-     * a timer is still queued — a token's `expires_at` doesn't shift
-     * across reconnects of the same agent. Revocation kicks a token's
-     * in-flight WS connections at once; these timers do the same when
-     * the token reaches its natural TTL.
+     * Per-tokenId TTL kick timer, armed by `scheduleExpiryKick` for a token with a
+     * non-null `expires_at`. Cleared when it fires, when a revocation calls
+     * `disconnectByTokenId` (no double kick when revoke races TTL), or when the last agent
+     * under the token unregisters (no timer leak on long-lived registries).
      */
     private readonly tokenExpiryTimers;
     /**
-     * Per-agent last roster `last_seen` stamp time (epoch ms). Throttles the
-     * coarse heartbeat write so we don't issue a DB write per agent per
-     * heartbeat — `grace`/`ttl` are minute-scale, so a throttled stamp is
-     * sufficient. Cleaned up alongside the agent in `removeFromIndexes`.
+     * Per-agent last roster `last_seen` stamp (epoch ms). Throttles the heartbeat write
+     * to one per agent per window: `grace`/`ttl` are minute-scale, so a throttled stamp
+     * is sufficient.
      */
     private readonly lastRosterStampAt;
     /** Minimum interval between coarse roster `last_seen` stamps per agent. */
     private readonly ROSTER_STAMP_THROTTLE_MS;
-    /** Optional host-roster reconciler + this instance's id (see AgentRegistryDeps). */
     private readonly rosterStore?;
     private readonly instanceId?;
-    /**
-     * The roster reconcile seam is optional: when no store is injected (workers
-     * with no DB, unit tests), every reconcile hook is a no-op and the in-memory
-     * registry behaves exactly as before.
-     */
+    /** With no roster store (workers with no DB, unit tests), every reconcile hook is a no-op. */
     constructor(deps?: AgentRegistryDeps);
     /**
      * Triages the in-flight jobs of an agent this registry drops on its own (a
@@ -266,12 +219,11 @@ export declare class AgentRegistry {
     /** Install the job triage {@link disconnectByTokenId} runs for each agent it drops. */
     setDisconnectTriage(triage: (agentId: string) => Promise<unknown>): void;
     /**
-     * Sockets whose `agent.register` is in flight (awaiting the scaler lookup),
-     * per agent id, with the id of the agent token each authenticated with
-     * (`null` without token auth). Kept here rather than in the WebSocket
-     * handler because the coordinator builds one handler per connection: a
-     * socket's close, and the check a registration makes against another agent
-     * token, must see a registration in flight on another connection.
+     * Sockets whose `agent.register` is in flight (awaiting the scaler lookup), per agent
+     * id, with the agent token id each authenticated with (`null` without token auth).
+     * Kept here rather than in the WebSocket handler because the coordinator builds one
+     * handler per connection: a socket's close, and a registration's check against
+     * another agent token, must see a registration in flight on another connection.
      */
     private readonly registeringSockets;
     /** Record that `ws`, authenticated with `tokenId`, has started registering `agentId`. */
@@ -288,8 +240,7 @@ export declare class AgentRegistry {
      */
     isAgentIdHeldByOtherToken(agentId: string, tokenId: string, ws: WsLike): boolean;
     /**
-     * Register an agent. If the agentId already exists, updates the existing
-     * entry (agent reconnection scenario).
+     * Register an agent, replacing an existing entry for the same id (reconnect).
      *
      * @returns the socket the previous entry was bound to, when this register
      *   replaced one bound to a *different* socket. The caller owns that socket's
@@ -300,123 +251,84 @@ export declare class AgentRegistry {
      *   same socket.
      */
     register(agentId: string, ws: WsLike, labels: string[], platform?: string, arch?: string, version?: string, maxConcurrency?: number, metadata?: AgentMetadata): WsLike | undefined;
-    /**
-     * Unregister an agent by ID. Removes from all indexes.
-     * @returns The removed AgentEntry, or undefined if not found.
-     */
+    /** @returns the removed entry, or undefined if not found. */
     unregister(agentId: string): AgentEntry | undefined;
-    /**
-     * Unregister an agent by its WebSocket reference (for disconnect handling).
-     * @returns The removed AgentEntry, or undefined if not found.
-     */
+    /** For disconnect handling. @returns the removed entry, or undefined if not found. */
     unregisterByWs(ws: WsLike): AgentEntry | undefined;
     /**
-     * Close every WS authenticated under `tokenId`, send a final
-     * `auth.failure` message, then unregister the entry. Returns the
-     * count of kicked agents.
+     * Send a final `auth.failure` to every WS authenticated under `tokenId`, close it,
+     * and unregister the entry. Returns the count of kicked agents.
      *
-     * Closes the gap on the agent->orchestrator leg: when an admin
-     * revokes a token via `DELETE /api/v1/agent-tokens/:id`, the route
-     * calls this synchronously after `tokenStore.revoke(id)` so the
-     * in-flight WS loses data-plane authority before the handler
-     * returns.
+     * `DELETE /api/v1/agent-tokens/:id` calls this synchronously after
+     * `tokenStore.revoke(id)`, so the in-flight WS loses data-plane authority before the
+     * handler returns.
      *
-     * The WS close code is `WS_CLOSE_AGENT_AUTH_FAILED` (4010); the
-     * agent's reconnect loop treats both the `auth.failure` message and
-     * this close code as permanent and stops retrying.
+     * The close code is `WS_CLOSE_AGENT_AUTH_FAILED` (4010); the agent's reconnect loop
+     * treats both it and the `auth.failure` message as permanent and stops retrying.
      */
     disconnectByTokenId(tokenId: string): number;
     /**
-     * Schedule a one-shot TTL kick for `tokenId` at `expiresAt`. When
-     * the timer fires (or if `expiresAt` is already past), every
-     * in-flight WS authenticated under the token is closed via
-     * `disconnectByTokenId`.
+     * Schedule a one-shot `disconnectByTokenId` kick for `tokenId` at `expiresAt`, or at
+     * once when it is already past.
      *
-     * Idempotent per `tokenId`: if a timer is already scheduled for
-     * this token, the call is a no-op. A token's `expires_at` doesn't
-     * change across reconnects, so re-scheduling would just re-arm the
-     * same trigger.
+     * Idempotent per `tokenId`: a token's `expires_at` doesn't change across reconnects,
+     * so re-scheduling would re-arm the same trigger.
      *
-     * Caller is the agent WS handler at register-time, when the token's
-     * `agent_tokens.expires_at` column is non-null. Static tokens have
-     * `expires_at = null` and are skipped at the call site (they have
-     * no TTL by design). Revocation kicks a token's in-flight WS
-     * connections at once; this timer does the same at the token's
-     * natural TTL.
+     * Called by the agent WS handler at register time when `agent_tokens.expires_at` is
+     * non-null. Static tokens have `expires_at = null` (no TTL by design) and are skipped
+     * at the call site.
      */
     scheduleExpiryKick(tokenId: string, expiresAt: Date): void;
     /**
-     * Find available agents that match ALL required labels.
-     * An agent is available when it has capacity (activeJobs < maxConcurrency).
-     *
-     * In addition to the subset + exclusion filters, every label declared in
-     * the agent's `mandatoryLabels` must appear in `requiredLabels`. This is
-     * the agent-side mirror of the scaler-side mandatory-labels gate
-     * (`findBackendForLabels`). Without it, a queued job whose `runsOn` is a
-     * subset of a gated agent's labels but does not list the gate label
-     * would be drained onto that agent the next time `onAgentAvailable`
-     * fires — sidestepping the opt-in semantics the gate is meant to enforce.
+     * Find available agents that have ALL required labels.
+     * An agent is available when it is not draining and has a free slot
+     * ({@link agentHasFreeSlot}: activeJobs < maxConcurrency and no busy hold).
      *
-     * @param requiredLabels - All labels the agent must have (intersection semantics).
-     * @returns Array of matching available AgentEntry objects.
+     * Every label in the agent's `mandatoryLabels` must also appear in `requiredLabels`:
+     * the agent-side mirror of the scaler-side gate (`findBackendForLabels`). Without it,
+     * a queued job whose `runsOn` is a subset of a gated agent's labels but omits the
+     * gate label would be drained onto that agent the next time `onAgentAvailable` fires.
      */
     findAvailable(requiredLabels: string[], requiredPatterns?: LabelMatcher[], excludeLabels?: string[], excludePatterns?: LabelMatcher[]): AgentEntry[];
     /**
-     * Whether a specific agent satisfies the same label / exclude / mandatory
-     * gate `findAvailable` applies per-agent, ignoring capacity. Used by the
-     * host-fanout pin to verify the resolved agent still matches before pinning
-     * (guards against roster label drift between resolution and dispatch).
+     * The per-agent label / exclude / mandatory gate of `findAvailable`, ignoring
+     * capacity. The host-fanout pin uses it to guard against roster label drift between
+     * resolution and dispatch.
      */
     agentSatisfies(agent: AgentEntry, requiredLabels: string[], requiredPatterns?: LabelMatcher[], excludeLabels?: string[], excludePatterns?: LabelMatcher[]): boolean;
     /**
-     * Check if ANY registered agent matches the required labels, regardless of capacity.
-     * Used to decide whether to queue (agent exists but busy) vs reject (no agent at all).
+     * Whether ANY registered agent matches, regardless of capacity: decides queue (agent
+     * exists but busy) vs reject (no agent at all).
      *
-     * Applies the same `mandatoryLabels` gate as `findAvailable` — a gated
-     * agent only counts as "matching" when every label in its
-     * `mandatoryLabels` is present in `requiredLabels`. Without this, the
-     * dispatcher's `queued-no-backend` decision in `dispatch()` would treat
-     * an off-gate gated agent as "matching but busy" and skip the peer
-     * reroute path even though the local agent can never accept the job.
+     * Applies the `mandatoryLabels` gate of `findAvailable`. Without it, the
+     * `queued-no-backend` decision in `dispatch()` would treat an off-gate agent as
+     * "matching but busy" and skip the peer reroute path, though that agent can never
+     * accept the job.
      */
     hasMatchingAgent(requiredLabels: string[], requiredPatterns?: LabelMatcher[], excludeLabels?: string[], excludePatterns?: LabelMatcher[], 
     /**
-     * An extra test a label-matching agent must pass: whether it can run the
-     * job at all, which its labels cannot express. An agent that matches but
-     * never could is not a reason to keep the job here rather than reroute it.
+     * Whether a label-matching agent can run the job at all, which its labels cannot
+     * express. An agent that never could is no reason to keep the job here rather
+     * than reroute it.
      */
     canRun?: (entry: AgentEntry) => boolean): boolean;
     /**
-     * Internal helper: intersect the per-label candidate sets to find agentIds
-     * that satisfy `requiredLabels`. Returns `null` when any required label
-     * matches zero agents (so callers can short-circuit). Returns an empty
-     * Set on `requiredLabels.length === 0` since the caller decides the
-     * walk strategy in that case.
+     * Agent ids that have every required label, or `null` when any label matches zero
+     * agents (so callers can short-circuit). An empty Set for no labels: the caller picks
+     * the walk strategy then.
      *
-     * Takes canonical labels: the index it reads is keyed on the canonical form,
-     * so a caller folds before it gets here.
+     * Takes canonical labels, since the index is keyed on the canonical form.
      */
     private intersectLabelCandidates;
-    /**
-     * Increment activeJobs for an agent.
-     * @returns false if agent not found.
-     */
+    /** @returns false if agent not found. */
     incrementActiveJobs(agentId: string): boolean;
-    /**
-     * Decrement activeJobs for an agent (min 0).
-     * @returns false if agent not found.
-     */
+    /** Floors at 0. @returns false if agent not found. */
     decrementActiveJobs(agentId: string): boolean;
-    /**
-     * Update the last heartbeat timestamp for an agent.
-     */
     updateHeartbeat(agentId: string): boolean;
     /**
-     * Compact, allocation-cheap snapshot of every registered agent's routing
-     * facts. Used by the dispatcher to log WHY a job found no backend (required
-     * labels vs each agent's labels / capacity), which is otherwise invisible —
-     * a `queued-no-backend` outcome alone doesn't say whether the label set
-     * mismatched, the agent was at capacity, or no agent was connected at all.
+     * Cheap snapshot of every agent's routing facts, so the dispatcher can log WHY a job
+     * found no backend: `queued-no-backend` alone doesn't say whether the labels
+     * mismatched, the agent was at capacity, or no agent was connected.
      */
     agentSummaries(): Array<{
         agentId: string;
@@ -427,25 +339,20 @@ export declare class AgentRegistry {
         maxConcurrency: number;
     }>;
     /**
-     * Get a single agent entry by ID.
-     */
-    /**
-     * Whether one agent id is currently registered.
-     *
-     * Distinct from `findAvailable`, which answers "which agents could take this
-     * job" — the container orphan sweep needs to know only whether a running
-     * container's agent is present at all, including one that is busy or gated.
+     * Distinct from `findAvailable` ("which agents could take this job"): the container
+     * orphan sweep needs only whether a running container's agent is present at all,
+     * busy or gated included.
      */
     isRegistered(agentId: string): boolean;
     /**
      * Condemn an agent: it stays registered and keeps finishing its current work,
      * but takes no new dispatches.
      *
-     * Called before a warm-pool destroy is issued. Returns the agent's current
-     * `activeJobs` so the caller can see a job that was claimed between its idle
-     * check and this mark, and back out.
+     * Called before a warm-pool destroy is issued. An agent that reports its own
+     * drain goes through {@link markDrainReported} instead.
      *
-     * @returns the agent's active-job count, or `undefined` when it is not registered
+     * @returns the agent's `activeJobs`, so the caller can see a job claimed between its
+     *   idle check and this mark and back out; `undefined` when not registered
      */
     markDraining(agentId: string): number | undefined;
     /**
@@ -486,24 +393,24 @@ export declare class AgentRegistry {
      * free slot now.
      */
     clearExpiredBusyHold(agentId: string, now?: number): void;
-    /** Undo {@link markDraining} — a destroy that was rejected leaves the agent alive. */
-    clearDraining(agentId: string): void;
-    get(agentId: string): AgentEntry | undefined;
     /**
-     * Get an agent entry by its WebSocket reference.
+     * The agent reported on `agent.status` that it takes no new job: a drain, or a
+     * single-job agent that has accepted its job. Terminal for this connection.
      */
-    getByWs(ws: WsLike): AgentEntry | undefined;
+    markDrainReported(agentId: string): void;
     /**
-     * Total number of registered agents.
+     * Undo {@link markDraining} — a destroy that was rejected leaves the agent alive.
+     * An agent that reported its own drain stays draining.
      */
+    clearDraining(agentId: string): void;
+    get(agentId: string): AgentEntry | undefined;
+    getByWs(ws: WsLike): AgentEntry | undefined;
     getActiveCount(): number;
-    /**
-     * Iterator over all agent entries (for heartbeat checks, etc).
-     */
     getAllEntries(): IterableIterator<AgentEntry>;
     /**
-     * Remove an agent from the WS reverse map and label index.
-     * Does NOT remove from the primary agents map.
+     * Remove an agent from the WS reverse map, the label index, the roster-stamp
+     * map and the token index (cancelling the token's TTL timer when no agent is
+     * left on it). Does NOT remove from the primary agents map.
      */
     private removeFromIndexes;
 }