@kici-dev/orchestrator 0.0.0 → 0.1.1

package/dist/__test-helpers__/mock-db.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared mock Kysely database builder for orchestrator tests.
+ *
+ * Provides a configurable `createMockDb()` that constructs a chainable
+ * mock supporting the common query patterns used by the orchestrator:
+ *
+ * - selectFrom().selectAll().where()...execute() / executeTakeFirst()
+ * - selectFrom().select().where()...execute() / executeTakeFirst() / executeTakeFirstOrThrow()
+ * - insertInto().values().execute() / returning().executeTakeFirstOrThrow()
+ * - insertInto().values().onConflict(cb).execute()
+ * - insertInto().values().returningAll().executeTakeFirstOrThrow()
+ * - updateTable().set().where()...execute() / executeTakeFirst()
+ * - deleteFrom().where()...execute() / executeTakeFirst()
+ * - transaction().execute(async (trx) => { ... })
+ *
+ * Each test can configure return values via options and access the
+ * underlying vi.fn() mocks for assertions via the `mocks` property.
+ */
+import { vi } from 'vitest';
+export interface MockDbOptions {
+    /** Rows returned by selectAll/select chains ending in .execute(). Default: [] */
+    selectRows?: unknown[];
+    /** Row returned by select chains ending in .executeTakeFirst(). Default: undefined */
+    selectFirstRow?: unknown | undefined;
+    /** Row returned by insert chains ending in .returningAll().executeTakeFirstOrThrow(). Default: { id: 'mock-id' } */
+    insertedRow?: unknown;
+    /** Row returned by insert chains ending in .returning().executeTakeFirstOrThrow(). Default: { id: 'mock-id' } */
+    insertReturning?: unknown;
+    /** Row returned by update chains ending in .returningAll().executeTakeFirstOrThrow() or executeTakeFirst(). Default: undefined */
+    updatedRow?: unknown;
+    /** Result for update .execute() calls. Default: { numUpdatedRows: 0n } */
+    updateResult?: {
+        numUpdatedRows: bigint;
+    };
+    /** Result for delete .executeTakeFirst() calls. Default: { numDeletedRows: 0n } */
+    deleteResult?: {
+        numDeletedRows: bigint;
+    };
+    /** Result for count queries (fn.countAll). Default: { count: 0 } */
+    countResult?: {
+        count: number;
+    };
+    /** Result for insert chains ending in .executeTakeFirst(). Default: undefined */
+    insertResult?: {
+        numInsertedOrUpdatedRows: bigint;
+    };
+}
+export interface MockDb {
+    db: any;
+    mocks: MockDbMocks;
+}
+export interface MockDbMocks {
+    selectFrom: ReturnType<typeof vi.fn>;
+    selectAll: ReturnType<typeof vi.fn>;
+    select: ReturnType<typeof vi.fn>;
+    selectWhere: ReturnType<typeof vi.fn>;
+    selectOrderBy: ReturnType<typeof vi.fn>;
+    selectLimit: ReturnType<typeof vi.fn>;
+    selectExecute: ReturnType<typeof vi.fn>;
+    selectExecuteTakeFirst: ReturnType<typeof vi.fn>;
+    selectExecuteTakeFirstOrThrow: ReturnType<typeof vi.fn>;
+    selectForUpdate: ReturnType<typeof vi.fn>;
+    selectSkipLocked: ReturnType<typeof vi.fn>;
+    insertInto: ReturnType<typeof vi.fn>;
+    insertValues: ReturnType<typeof vi.fn>;
+    insertReturning: ReturnType<typeof vi.fn>;
+    insertReturningAll: ReturnType<typeof vi.fn>;
+    insertExecute: ReturnType<typeof vi.fn>;
+    insertExecuteTakeFirstOrThrow: ReturnType<typeof vi.fn>;
+    onConflict: ReturnType<typeof vi.fn>;
+    updateTable: ReturnType<typeof vi.fn>;
+    updateSet: ReturnType<typeof vi.fn>;
+    updateWhere: ReturnType<typeof vi.fn>;
+    updateReturningAll: ReturnType<typeof vi.fn>;
+    updateExecute: ReturnType<typeof vi.fn>;
+    updateExecuteTakeFirst: ReturnType<typeof vi.fn>;
+    updateExecuteTakeFirstOrThrow: ReturnType<typeof vi.fn>;
+    deleteFrom: ReturnType<typeof vi.fn>;
+    deleteWhere: ReturnType<typeof vi.fn>;
+    deleteExecute: ReturnType<typeof vi.fn>;
+    deleteExecuteTakeFirst: ReturnType<typeof vi.fn>;
+    transaction: ReturnType<typeof vi.fn>;
+    transactionExecute: ReturnType<typeof vi.fn>;
+    countAll: ReturnType<typeof vi.fn>;
+    countAs: ReturnType<typeof vi.fn>;
+    countExecuteTakeFirst: ReturnType<typeof vi.fn>;
+}
+/**
+ * Create a mock Kysely DB instance for orchestrator unit tests.
+ *
+ * All query chains are fully wired and return sensible defaults.
+ * Override specific return values via the `options` parameter.
+ *
+ * @example
+ * ```ts
+ * const { db, mocks } = createMockDb({ selectRows: [row1, row2] });
+ * const store = new SomeStore(db);
+ * await store.list();
+ * expect(mocks.selectFrom).toHaveBeenCalledWith('my_table');
+ * ```
+ */
+export declare function createMockDb(options?: MockDbOptions): MockDb;
+//# sourceMappingURL=mock-db.d.ts.map

package/dist/__test-helpers__/mock-ws.d.ts

@@ -0,0 +1,13 @@
+import type { WsLike } from '../agent/registry.js';
+import type { ObserverWsLike } from '../ws/observer-registry.js';
+/**
+ * Create a mock WsLike with vi.fn() spies on send/close.
+ * Used across agent registry, dispatcher, heartbeat, and WS handler tests.
+ */
+export declare function mockWs(): WsLike;
+/**
+ * Create a mock ObserverWsLike with vi.fn() spies on send/close.
+ * Used by observer-registry tests.
+ */
+export declare function mockObserverWs(): ObserverWsLike;
+//# sourceMappingURL=mock-ws.d.ts.map

package/dist/agent/dispatcher.d.ts

@@ -0,0 +1,231 @@
+import type { AgentRegistry } from './registry.js';
+import { type JobQueue, type QueuedJob, type QueuedJobInput } from '../queue/job-queue.js';
+import type { ScaleResult } from '../scaler/types.js';
+import type { ResourceRequest } from '@kici-dev/engine';
+/**
+ * Metrics interface for dispatch operations.
+ * Allows the dispatcher to update Prometheus counters without
+ * directly importing the metrics module (dependency injection).
+ */
+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;
+}
+/**
+ * Result of a dispatch attempt.
+ */
+type DispatchResult = {
+    status: 'dispatched';
+    agentId: string;
+    jobId: string;
+} | {
+    status: 'queued';
+    jobId: string;
+} | {
+    status: 'queued-no-backend';
+    jobId: string;
+} | {
+    status: 'rejected';
+    reason: string;
+};
+/**
+ * Dispatch coordinator connecting the agent registry and job queue.
+ *
+ * Routes incoming jobs to matching agents based on label requirements,
+ * falling back to the persistent queue when no agent is available.
+ * Handles agent lifecycle events (connect, disconnect, job completion).
+ *
+ * The dispatcher does NOT directly access WebSocket connections --
+ * it uses the onDispatch callback provided at construction. The caller
+ * (app.ts or server.ts) provides an onDispatch that looks up the agent's
+ * WS from the registry and sends the job.dispatch message.
+ */
+export declare class Dispatcher {
+    private readonly registry;
+    private readonly queue;
+    private readonly metrics;
+    private readonly onDispatch;
+    private readonly onNoMatchingAgent?;
+    /**
+     * Tracks which jobs are dispatched to which agents.
+     * Used for marking jobs as failed on agent disconnect.
+     */
+    private readonly agentJobs;
+    /** Reverse map: jobId -> agentId, for cancel-run lookups. */
+    private readonly jobToAgent;
+    /**
+     * 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.
+     */
+    private readonly completedJobs;
+    /** Cap on completedJobs map to prevent unbounded 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. */
+    private readonly maxReconnectDelayMs;
+    /** Callback when a recovery timer expires and the job is permanently failed. */
+    private readonly onRecoveryTimeout?;
+    /** Callback when a job enters recovery (starts timer). */
+    private readonly onRecoveryStarted?;
+    /**
+     * 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.
+     */
+    private readonly recoveringJobs;
+    /** Grace period = 2x max reconnection delay. */
+    private get gracePeriodMs();
+    constructor(deps: {
+        registry: AgentRegistry;
+        queue: JobQueue;
+        metrics: DispatchMetrics;
+        onDispatch: (agentId: string, job: QueuedJob) => void | Promise<void>;
+        /** 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. */
+        onNoMatchingAgent?: (labels: string[], jobId: string, excludeLabels: string[], resources?: ResourceRequest) => Promise<ScaleResult>;
+        /** Max reconnection delay from agent config (default 60s). Used to derive grace period. */
+        maxReconnectDelayMs?: number;
+        /** Callback when a recovery timer expires and the job is permanently failed. */
+        onRecoveryTimeout?: (agentId: string, jobId: string, runId: string) => void;
+        /** Callback when a job enters recovery (starts timer). */
+        onRecoveryStarted?: (agentId: string, jobId: string) => 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(job: QueuedJobInput): Promise<DispatchResult>;
+    /**
+     * Eagerly dispatch a specific bound job to a freshly-registered
+     * scaler-managed agent.
+     *
+     * 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 if dispatched, false if the bound job was already claimed
+     * elsewhere, expired, or the agent isn't registered. The caller falls
+     * back to the generic onAgentAvailable() drain in either case.
+     */
+    dispatchBoundJob(agentId: string, jobId: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    onAgentAvailable(agentId: string): Promise<void>;
+    /**
+     * Handle agent disconnect. Starts per-job recovery timers instead of
+     * 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).
+     */
+    onAgentDisconnect(agentId: string): Promise<string[]>;
+    /**
+     * 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.
+     */
+    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).
+     */
+    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).
+     */
+    getAgentIdForJob(jobId: string): string | null;
+    /**
+     * Start periodic cleanup of expired grace window entries.
+     * Should be called during server startup.
+     */
+    startGraceCleanup(): void;
+    /**
+     * Stop periodic grace cleanup.
+     * Should be called during 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.
+     */
+    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.
+     */
+    reconcileRecovery(jobId: string, agentId: string): Promise<boolean>;
+    /**
+     * Get recovery info for a job (for structured logging).
+     */
+    getRecoveryInfo(jobId: string): {
+        disconnectedAt: number;
+        agentId: string;
+    } | null;
+    /**
+     * Get all recovering job IDs for a specific agent.
+     * Used during 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.
+     */
+    restoreJobForAgent(agentId: string, jobId: 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.
+     */
+    startRecoveryTimer(jobId: string, agentId: string, runId: string): Promise<void>;
+    /**
+     * Stop all recovery timers. 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.
+     */
+    private handleRecoveryExpiry;
+    /** Remove expired entries from the completedJobs grace window map. */
+    private cleanupExpiredGraceEntries;
+    private trackJobForAgent;
+    /**
+     * 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.
+     */
+    cancelQueuedJob(jobId: string, reason: string): Promise<void>;
+    private updateQueueDepthMetric;
+}
+export {};
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/agent/ownership-tracker.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Job ownership tracker for agent message validation.
+ *
+ * Validates that agents only send messages (job.status, log.chunk, step.status,
+ * job.heartbeat, cache.upload.request, cache.upload.complete) for jobs that were
+ * actually dispatched to them.
+ *
+ * Includes:
+ * - Ownership check via dispatcher's isJobOwnedByAgent
+ * - Violation counting with sliding window (default: 5 violations in 60s)
+ * - Escalation: disconnect agent after threshold violations
+ */
+interface OwnershipTrackerOpts {
+    /** Check if a job is owned by the given agent (active or in grace window). */
+    isJobOwnedByAgent: (agentId: string, jobId: string) => boolean;
+    /** Callback to disconnect an agent after escalation. */
+    onDisconnect: (agentId: string, reason: string) => void;
+    /** Number of violations before escalation (default: 5). */
+    violationThreshold?: number;
+    /** Window in ms for counting violations (default: 60_000). */
+    violationWindowMs?: number;
+}
+export declare class OwnershipTracker {
+    private readonly isJobOwnedByAgent;
+    private readonly onDisconnect;
+    private readonly violationThreshold;
+    private readonly violationWindowMs;
+    private readonly violations;
+    constructor(opts: OwnershipTrackerOpts);
+    /**
+     * Check if an agent owns a job. Returns true if ownership is valid.
+     * On violation: logs warning, records violation, may escalate to disconnect.
+     */
+    checkOwnership(agentId: string, jobId: string, messageType: string): boolean;
+    /**
+     * Record a violation for an agent. If threshold is exceeded within the
+     * violation window, triggers disconnect escalation.
+     */
+    private recordViolation;
+    /**
+     * Clean up violation tracking for a disconnected agent.
+     */
+    cleanup(agentId: string): void;
+}
+export {};
+//# sourceMappingURL=ownership-tracker.d.ts.map

package/dist/agent/registry.d.ts

@@ -0,0 +1,255 @@
+/**
+ * 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.
+ */
+import type { WsLike } from '@kici-dev/engine';
+export type { WsLike } from '@kici-dev/engine';
+/**
+ * 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"). */
+    labels: Set<string>;
+    /**
+     * 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).
+     *
+     * 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).
+     */
+    mandatoryLabels: Set<string>;
+    /** Number of jobs currently executing on this agent. */
+    activeJobs: number;
+    /** Maximum concurrent jobs this agent can handle (default 1). */
+    maxConcurrency: number;
+    /** Unix epoch ms of the last heartbeat received. */
+    lastHeartbeatAt: number;
+    /** Agent platform (os.platform(), e.g. 'linux', 'darwin', 'win32'). */
+    platform: string;
+    /** Agent architecture (os.arch(), e.g. 'x64', 'arm64'). */
+    arch: string;
+    /** Unix epoch ms when the agent registered. */
+    registeredAt: number;
+    /** Self-reported agent version (e.g. "0.0.1"). 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. in the pentest catalog.
+     */
+    tokenId: string | null;
+    hostname: string | null;
+    osRelease: string | null;
+    osVersion: string | null;
+    totalMemoryMb: number | null;
+    cpuCount: number | null;
+    nodeVersion: string | null;
+    runningAsUser: string | null;
+    runningAsUid: number | null;
+    memoryUsedMb: number | null;
+    memoryAvailableMb: number | null;
+    uptimeSeconds: number | null;
+}
+/** Optional static metadata from the agent.register message. */
+interface AgentMetadata {
+    hostname?: string;
+    osRelease?: string;
+    osVersion?: string;
+    totalMemoryMb?: number;
+    cpuCount?: number;
+    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.
+     */
+    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.
+     */
+    mandatoryLabels?: string[];
+}
+export declare class AgentRegistry {
+    /** Primary: agentId -> AgentEntry */
+    private readonly agents;
+    /** Secondary: label -> Set<agentId> (reverse index for label-based queries) */
+    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.
+     */
+    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. Closes the sister gap
+     * to the revocation finding (`agent-token-revocation-stale-ws`,
+     * fixed in `993bc3d9d`) where natural TTL expiration had no
+     * propagation path to in-flight WS connections.
+     */
+    private readonly tokenExpiryTimers;
+    /**
+     * Register an agent. If the agentId already exists, updates the existing
+     * entry (agent reconnection scenario).
+     */
+    register(agentId: string, ws: WsLike, labels: string[], platform?: string, arch?: string, version?: string, maxConcurrency?: number, metadata?: AgentMetadata): void;
+    /**
+     * Unregister an agent by ID. Removes from all indexes.
+     * @returns The removed AgentEntry, 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.
+     */
+    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.
+     *
+     * 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.
+     *
+     * 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.
+     */
+    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`.
+     *
+     * 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.
+     *
+     * 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). Closes the sister gap to the revocation
+     * finding (`agent-token-revocation-stale-ws`, fixed in `993bc3d9d`)
+     * where natural TTL expiration had no propagation path to
+     * in-flight WS connections.
+     */
+    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.
+     *
+     * @param requiredLabels - All labels the agent must have (intersection semantics).
+     * @returns Array of matching available AgentEntry objects.
+     */
+    findAvailable(requiredLabels: string[], excludeLabels?: string[]): AgentEntry[];
+    /**
+     * 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).
+     *
+     * 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.
+     */
+    hasMatchingAgent(requiredLabels: string[], excludeLabels?: string[]): 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.
+     */
+    private intersectLabelCandidates;
+    /**
+     * Increment activeJobs for an agent.
+     * @returns false if agent not found.
+     */
+    incrementActiveJobs(agentId: string): boolean;
+    /**
+     * Decrement activeJobs for an agent (min 0).
+     * @returns false if agent not found.
+     */
+    decrementActiveJobs(agentId: string): boolean;
+    /**
+     * Update the last heartbeat timestamp for an agent.
+     */
+    updateHeartbeat(agentId: string): boolean;
+    /**
+     * Get a single agent entry by ID.
+     */
+    get(agentId: string): AgentEntry | undefined;
+    /**
+     * Get an agent entry by its WebSocket reference.
+     */
+    getByWs(ws: WsLike): AgentEntry | undefined;
+    /**
+     * Total number of registered agents.
+     */
+    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.
+     */
+    private removeFromIndexes;
+}
+//# sourceMappingURL=registry.d.ts.map