@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/providers/universal-git/repo-url.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Universal-git repository URL builder.
+ *
+ * Implements the `RepoUrlBuilder` interface from `@kici-dev/engine`. Each
+ * universal-git source provides a `gitUrlTemplate` (e.g.
+ * `https://forgejo.example.com/{owner}/{name}.git` or
+ * `ssh://git@forgejo.example.com/{owner}/{name}.git`) plus a `repoIdentifier`
+ * that appears in the normalized webhook (typically `owner/name`). This class
+ * substitutes `{owner}`, `{name}`, and `{repo}` placeholders to build the
+ * concrete clone URL used by agents.
+ */
+import type { RepoUrlBuilder } from '@kici-dev/engine';
+/**
+ * Universal-git implementation of RepoUrlBuilder.
+ *
+ * Bound to a single source's URL template — the orchestrator constructs one
+ * per registered universal-git source.
+ */
+export declare class UniversalGitRepoUrlBuilder implements RepoUrlBuilder {
+    private readonly gitUrlTemplate;
+    readonly provider: "generic";
+    constructor(gitUrlTemplate: string);
+    /**
+     * Build the clone URL by substituting placeholders in the template with
+     * values from the repo identifier (expected as `owner/name`).
+     *
+     * Accepts identifiers with a single slash (`owner/name`) or with multiple
+     * segments (GitLab groups: `group/subgroup/project`); the trailing segment
+     * is always treated as the repo name and everything before it as the
+     * owner path.
+     */
+    buildCloneUrl(repoIdentifier: string): string;
+    /**
+     * Raw file URLs are not supported for universal-git sources — the agent
+     * always shallow-clones the repo to fetch files. Returning the clone URL
+     * keeps the interface contract honest; callers that need raw content must
+     * use the shallow-clone path instead.
+     */
+    buildRawFileUrl(repoIdentifier: string, _ref: string, _path: string): string;
+}
+/**
+ * Split `owner/name` or `group/subgroup/project` into the owner path plus
+ * the final repo name. Throws on malformed input so misconfigured sources
+ * fail loudly rather than producing broken clone URLs.
+ */
+export declare function splitRepoIdentifier(repoIdentifier: string): {
+    owner: string;
+    name: string;
+};
+//# sourceMappingURL=repo-url.d.ts.map

package/dist/providers/universal-git/ssh-auth.d.ts

@@ -0,0 +1,94 @@
+/**
+ * SSH auth helper for universal-git sources.
+ *
+ * When a universal-git source uses `credentialType: 'ssh'`, the agent needs
+ * three things to run `git clone`:
+ *   1. The PEM-encoded private key materialized to a tempfile with mode 0600.
+ *   2. A `GIT_SSH_COMMAND` that points `ssh -i` at that tempfile.
+ *   3. A `StrictHostKeyChecking` policy that matches the source config —
+ *      either `accept-new` (TOFU) or `yes` with a pinned `known_hosts` file.
+ *
+ * This module provides the orchestrator-side primitives for preparing those
+ * artefacts. It is used in two contexts:
+ *   - **Agent-side** (Phase 4+): the agent receives the PEM + host-key policy
+ *     in the dispatch message and materializes them before cloning.
+ *   - **Lock-file fetcher** (Phase 2, this module's immediate consumer):
+ *     the orchestrator shallow-clones the source repo itself at registration
+ *     time, using the same SSH materialization path.
+ *
+ * All materialized tempfiles are created under `os.tmpdir()` in a private
+ * per-call subdirectory (`fs.mkdtempSync(.../kici-ugit-ssh-`)`), so
+ * concurrent clones never clobber each other. The returned `cleanup()`
+ * closure removes the directory recursively — callers MUST call it in a
+ * `finally` block.
+ */
+import type { SshHostKeyPolicy } from './config.js';
+/** Material the caller has prepared (key file + optional known_hosts file). */
+export interface SshAuthArtefacts {
+    /** Absolute path to the private key file (mode 0600). */
+    privateKeyPath: string;
+    /** Absolute path to the known_hosts file, if `policy === 'pinned'`. */
+    knownHostsPath?: string;
+    /** Complete GIT_SSH_COMMAND string to export when running git. */
+    gitSshCommand: string;
+    /** Dispose of every tempfile + the parent directory. Must be called. */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Synchronous variant — used when the caller is already in synchronous
+ * lock-file fetching logic. The structure matches the async version so
+ * callers can swap freely.
+ */
+export interface SshAuthArtefactsSync {
+    privateKeyPath: string;
+    knownHostsPath?: string;
+    gitSshCommand: string;
+    cleanup: () => void;
+}
+/** Options common to both sync and async variants. */
+export interface PrepareSshAuthOptions {
+    /** PEM-encoded private key. */
+    privateKey: string;
+    /** Host-key verification policy. */
+    policy: SshHostKeyPolicy;
+    /**
+     * OpenSSH known_hosts content. Required when `policy === 'pinned'`, ignored
+     * otherwise.
+     */
+    knownHostsPem?: string;
+}
+/**
+ * Async: materialize the private key (and pinned known_hosts) into a private
+ * tempdir, returning paths + the `GIT_SSH_COMMAND` the agent should export.
+ *
+ * @throws If `policy === 'pinned'` and `knownHostsPem` is missing.
+ */
+export declare function prepareSshAuth(opts: PrepareSshAuthOptions): Promise<SshAuthArtefacts>;
+/**
+ * Sync variant of `prepareSshAuth`. Semantics are identical; the caller
+ * receives a synchronous `cleanup()` closure.
+ */
+export declare function prepareSshAuthSync(opts: PrepareSshAuthOptions): SshAuthArtefactsSync;
+/**
+ * Compose the GIT_SSH_COMMAND string. Honors the host-key policy:
+ *   - `accept-new`: `StrictHostKeyChecking=accept-new` (TOFU on the per-call
+ *     empty known_hosts file).
+ *   - `pinned`: `StrictHostKeyChecking=yes` (rejects any unknown host key).
+ *
+ * Both policies pin `UserKnownHostsFile` to the per-call tempfile so the
+ * orchestrator never reads or writes the runtime user's
+ * `~/.ssh/known_hosts`. Without this, a stale entry there for a host:port
+ * we're cloning from blocks the connection (accept-new still rejects
+ * mismatches against cached keys). The per-call file is wiped by `cleanup()`.
+ *
+ * IdentitiesOnly=yes ensures ssh ignores any agent-forwarded keys and only
+ * uses the one we provided; this is critical in staging where the runner
+ * user may have a populated ssh-agent.
+ */
+export declare function composeGitSshCommand(privateKeyPath: string, policy: SshHostKeyPolicy, knownHostsPath: string): string;
+/**
+ * Shell-quote a path for embedding in `GIT_SSH_COMMAND`. Single-quotes the
+ * string and escapes embedded single quotes — matches POSIX shell parsing.
+ */
+export declare function quoteShell(path: string): string;
+//# sourceMappingURL=ssh-auth.d.ts.map

package/dist/queue/bootstrap.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Orchestrator scheduled-jobs bootstrap helper.
+ *
+ * Composes `registerOrchestratorScheduledJob()` calls for all the
+ * orchestrator's periodic work. Returns an array of handles so the
+ * caller (orchestrator-core.ts) can thread them into
+ * `setupGracefulShutdown`.
+ *
+ * Commit 5 ships the infrastructure; Commit 6 migrates the three
+ * legacy setInterval schedulers (queue cleanup, secret cleanup,
+ * token cleanup) into this helper. Commit 7 adds the
+ * `cold-store-archive` entry.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import { type OrchestratorScheduledJobHandle } from './scheduled-job.js';
+export interface OrchestratorScheduledJobsDeps {
+    db: Kysely<Database>;
+    instanceId: string;
+    routingKey?: string;
+}
+/**
+ * Overrides for the per-job handler + cadence. Callers pass the
+ * actual tick functions here — the bootstrap helper only composes
+ * registrations.
+ */
+export interface OrchestratorScheduledJobRegistrations {
+    cleanup?: {
+        intervalMs: number;
+        handler: () => Promise<void>;
+    };
+    orphanSecretCleanup?: {
+        intervalMs: number;
+        handler: () => Promise<void>;
+    };
+    tokenCleanup?: {
+        intervalMs: number;
+        handler: () => Promise<void>;
+    };
+    coldStoreArchive?: {
+        intervalMs: number;
+        handler: () => Promise<void>;
+    };
+    coldStorePurge?: {
+        intervalMs: number;
+        handler: () => Promise<void>;
+    };
+}
+export declare function bootstrapOrchestratorScheduledJobs(deps: OrchestratorScheduledJobsDeps, registrations: OrchestratorScheduledJobRegistrations): OrchestratorScheduledJobHandle[];
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/queue/cleanup.d.ts

@@ -0,0 +1,41 @@
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+import { JobQueue } from './job-queue.js';
+/**
+ * Run a single cleanup pass: remove expired dedup_cache entries and
+ * mark expired dispatch_queue entries.
+ *
+ * When `extras` is provided, expired jobs are also forwarded to Platform
+ * as terminal status updates so the Platform execution_jobs projection
+ * stays in sync.
+ *
+ * Event-log row + payload retention used to live here too, but Phase E
+ * replaced the 30-day hard-delete with cold-store archive-then-delete
+ * (see `packages/orchestrator/src/cold-store/tables/event-log.ts`).
+ *
+ * @returns Counts of cleaned entries.
+ */
+export declare function runCleanup(dedup: {
+    cleanup(): Promise<number>;
+}, queue: JobQueue, extras?: {
+    db: Kysely<Database>;
+    executionTracker: ExecutionTracker;
+}): Promise<{
+    dedupDeleted: number;
+    queueExpired: number;
+}>;
+/**
+ * Build a per-tick handler for the queue-cleanup scheduled job.
+ *
+ * The cadence (`intervalMs`) and the periodic wrapper itself live in
+ * `packages/orchestrator/src/queue/scheduled-job.ts` — this factory
+ * just produces the tick function. `runCleanup` is unchanged.
+ */
+export declare function createCleanupHandler(dedup: {
+    cleanup(): Promise<number>;
+}, queue: JobQueue, extras?: {
+    db: Kysely<Database>;
+    executionTracker: ExecutionTracker;
+}): () => Promise<void>;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/queue/depth-refresher.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Periodic refresher for the dispatch-queue depth breakdown.
+ *
+ * Runs on a fixed interval (default 5s) — short enough that the
+ * Prometheus observable-gauge callback (which reads the JobQueue's
+ * synchronous cache) never serves data older than one refresh tick,
+ * long enough that a single orchestrator does not hammer the DB.
+ *
+ * Two responsibilities:
+ *
+ *   1. Call {@link JobQueue.getDepthBreakdown} to refresh the internal
+ *      cache and feed {@link setDispatchQueueDepthBreakdown} so
+ *      `kici_orch_dispatch_queue_depth` / `..._by_label` are always
+ *      recent when Prometheus scrapes.
+ *   2. Watch for sustained backpressure: when the pending depth stays
+ *      at or above {@link RefresherOptions.thresholdGetter | threshold}
+ *      for two consecutive refreshes, emit a `logger.warn` that points
+ *      operators at the per-label Grafana panel. The two-in-a-row
+ *      guard suppresses transient spikes without needing a cooldown.
+ *
+ * Threshold is resolved lazily on every tick via `thresholdGetter` so
+ * live config reloads (SIGHUP / cluster propagation) take effect
+ * immediately without restarting the refresher.
+ *
+ * A threshold of `0` disables the warning entirely — the refresher
+ * still runs so metrics keep flowing.
+ */
+import type { Logger } from '@kici-dev/shared';
+import { type JobQueue } from './job-queue.js';
+export interface DepthRefresherOptions {
+    queue: JobQueue;
+    logger: Logger;
+    /**
+     * How often to refresh the cache / evaluate the warning threshold.
+     * Defaults to 5 seconds — short enough that Prometheus's default 15s
+     * scrape interval never sees data older than one tick.
+     */
+    intervalMs?: number;
+    /**
+     * Called on every tick to get the current backpressure warn
+     * threshold. `0` disables warnings.
+     */
+    thresholdGetter: () => number;
+    /**
+     * Optional hook invoked after each successful tick, for tests.
+     */
+    onTick?: (pendingDepth: number) => void;
+}
+export interface DepthRefresher {
+    /** Start the periodic timer. Idempotent. */
+    start(): void;
+    /** Stop the periodic timer. Idempotent. */
+    stop(): void;
+    /** Run one refresh synchronously (used at startup and in tests). */
+    refreshNow(): Promise<void>;
+}
+/**
+ * Create a dispatch-queue depth refresher.
+ *
+ * The returned object is NOT started automatically — call `start()`
+ * after the orchestrator is otherwise ready. `stop()` must be called
+ * during shutdown to avoid leaking the interval handle.
+ */
+export declare function createDepthRefresher(options: DepthRefresherOptions): DepthRefresher;
+//# sourceMappingURL=depth-refresher.d.ts.map

package/dist/queue/job-queue.d.ts

@@ -0,0 +1,343 @@
+import { type Kysely } from 'kysely';
+import type { ResourceRequest } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+/** Info about an expired dispatch_queue entry, returned by markExpired(). */
+export interface ExpiredJobInfo {
+    /** dispatch_queue row ID */
+    id: string;
+    runId: string;
+    jobName: string;
+}
+/**
+ * Point-in-time breakdown of dispatch_queue depth used for Prometheus gauges
+ * and operator-facing depth warnings.
+ *
+ * `byStatus` carries the raw COUNT(*) for each {@link DispatchQueueStatus.Pending}
+ * and {@link DispatchQueueStatus.Dispatched} bucket (other statuses are
+ * terminal and not surfaced here).
+ *
+ * `byLabel` is a flat rollup of pending-only jobs keyed by each distinct label
+ * in `runs_on_labels`. Multi-label jobs fan out: a job with `runs_on_labels =
+ * ['linux', 'x64']` contributes 1 to both `linux` and `x64`. This matches the
+ * "label pool" mental model operators use in Grafana (agents advertise their
+ * labels; the gauge answers "how many pending jobs want this label").
+ */
+export interface DispatchQueueDepthBreakdown {
+    byStatus: Partial<Record<DispatchQueueStatus, number>>;
+    byLabel: Record<string, number>;
+}
+/**
+ * Status values for dispatch_queue entries.
+ *
+ * Lifecycle: pending → dispatched → completed | failed
+ *                    ↘ recovering → failed | dispatched (reclaimed)
+ *            pending → expired (timeout)
+ */
+export declare enum DispatchQueueStatus {
+    Pending = "pending",
+    Dispatched = "dispatched",
+    Completed = "completed",
+    Failed = "failed",
+    Expired = "expired",
+    Recovering = "recovering"
+}
+/**
+ * Input for enqueuing a job. Callers provide these fields;
+ * the queue generates id, status, created_at, and expires_at.
+ */
+export interface QueuedJobInput {
+    /**
+     * Optional pre-allocated job identifier. When set, the queue uses this
+     * exact id instead of generating one — required for the cluster reroute
+     * path so the sending coord can register execution_runs/execution_jobs
+     * rows under the same id the receiving worker dispatches against.
+     */
+    jobId?: string;
+    runId: string;
+    workflowName: string;
+    jobName: string;
+    runsOnLabels: string[];
+    jobConfig: Record<string, unknown>;
+    repoUrl: string;
+    ref: string;
+    sha: string;
+    deliveryId: string;
+    /** Provider type (e.g., "github", "gitlab") */
+    provider: string;
+    /** Provider-specific context (e.g., { installationId: 42 } for GitHub) */
+    providerContext: Record<string, unknown>;
+    /** Routing key (e.g. "github:12345") for selecting the per-app provider
+     *  bundle when dispatching. Required for multi-app safety. */
+    routingKey: string;
+    /** Override default timeout. 0 = indefinite (no expiry). */
+    timeoutMs?: number;
+    /** URL to pre-compiled bundle (from cache). Passed through to job.dispatch. */
+    sourceTarUrl?: string;
+    /** Content hash of the pre-compiled bundle for verification. */
+    sourceTarHash?: string;
+    /** URL to pre-built dependency tarball (from dep cache). Passed through to job.dispatch. */
+    depsUrl?: string;
+    /** SHA-256 hash of the dependency tarball for integrity verification. */
+    depsHash?: string;
+    /** Request trace ID for cross-tier correlation. Passed through to job.dispatch. */
+    requestId?: string;
+    /** Labels that the dispatched agent must NOT have. */
+    excludeLabels?: string[];
+    /**
+     * Per-job resource request and limit (K8s-style). Drives scaler cap accounting
+     * (`requests`) and kernel-side enforcement on the spawned agent (`limits`).
+     * Stored inside `jobConfig` JSON; this typed field is a convenience for callers.
+     */
+    resources?: ResourceRequest;
+}
+/**
+ * Full queued job as stored in the database.
+ */
+export interface QueuedJob {
+    id: string;
+    runId: string;
+    workflowName: string;
+    jobName: string;
+    runsOnLabels: string[];
+    jobConfig: Record<string, unknown>;
+    repoUrl: string;
+    ref: string;
+    sha: string;
+    status: DispatchQueueStatus;
+    createdAt: string;
+    expiresAt: string | null;
+    deliveryId: string;
+    /** Provider type (e.g., "github", "gitlab") */
+    provider: string;
+    /** Provider-specific context */
+    providerContext: Record<string, unknown>;
+    /** Routing key (e.g. "github:12345") used to look up the per-app provider
+     *  bundle on dispatch. Required for multi-app safety. */
+    routingKey: string;
+    /** URL to pre-compiled bundle (from cache). Passed through to job.dispatch. */
+    sourceTarUrl?: string;
+    /** Content hash of the pre-compiled bundle for verification. */
+    sourceTarHash?: string;
+    /** URL to pre-built dependency tarball (from dep cache). Passed through to job.dispatch. */
+    depsUrl?: string;
+    /** SHA-256 hash of the dependency tarball for integrity verification. */
+    depsHash?: string;
+    /** Request trace ID for cross-tier correlation. Passed through to job.dispatch. */
+    requestId?: string;
+    /** Labels that the dispatched agent must NOT have. */
+    excludeLabels: string[];
+    /**
+     * Per-job resource request and limit (K8s-style). Materialized from `jobConfig.resources`
+     * by `rowToQueuedJob` so callers can read it without re-parsing the JSON column.
+     */
+    resources?: ResourceRequest;
+}
+/**
+ * DB-backed FIFO job dispatch queue using Kysely (PostgreSQL only).
+ * Uses SQL-based JSONB containment queries (@> operator) for label matching.
+ */
+export declare class JobQueue {
+    private readonly db;
+    private readonly maxDepth;
+    private readonly defaultTimeoutMs;
+    /** 1-second TTL cache for pending depth count to avoid extra SELECT COUNT per enqueue. */
+    private depthCache;
+    /**
+     * 1-second TTL cache for the dispatch-queue depth breakdown (per-status + per-label).
+     * Fed by {@link JobQueue.getDepthBreakdown} and read synchronously by
+     * {@link JobQueue.readCachedDepthBreakdown} so the Prometheus observable
+     * gauge callback never issues an extra COUNT per scrape.
+     */
+    private breakdownCache;
+    constructor(db: Kysely<Database>, options: {
+        maxDepth: number;
+        defaultTimeoutMs: number;
+    });
+    /**
+     * Enqueue a job. Checks depth first, rejects with 'queue full' if >= maxDepth.
+     * @returns The generated job ID.
+     */
+    enqueue(job: QueuedJobInput): Promise<string>;
+    /**
+     * Dequeue the oldest pending job whose runsOnLabels are a subset of the
+     * provided agent labels. Uses SQL JSONB containment (@> operator) with
+     * GIN index for O(1) lookups instead of fetching all rows and filtering in JS.
+     *
+     * Semantics: agentLabels @> runs_on_labels (agent provides all labels the job requires).
+     * FOR UPDATE SKIP LOCKED prevents concurrent dequeue races between agents.
+     *
+     * When `agentMandatoryLabels` is non-empty, an additional containment check
+     * (`runs_on_labels @> agentMandatoryLabels`) enforces the
+     * Kubernetes-taint-style gate inherited from the spawning scaler: a gated
+     * agent only accepts jobs whose `runsOn` lists every gate label. The
+     * default (`[]`) is a no-op for static / non-scaler agents — every JSONB
+     * array trivially contains the empty array, so the predicate is vacuously
+     * true.
+     *
+     * @param agentLabels Labels the agent provides.
+     * @param agentMandatoryLabels Mandatory labels the spawning scaler declared
+     *   (empty for static / non-scaler agents).
+     * @returns The matching job, or null if none found.
+     */
+    dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[]): Promise<QueuedJob | null>;
+    /**
+     * Atomically claim a specific pending job by ID, validating it still
+     * matches the agent's labels and isn't expired.
+     *
+     * Used by the eager-dispatch path: when the scaler spawned an agent for a
+     * specific queued job, the orchestrator claims that exact job on agent
+     * registration instead of racing the generic dequeueForLabels drain.
+     *
+     * Applies the same `agentMandatoryLabels` gate as `dequeueForLabels` so
+     * the eager-dispatch path can never claim a job that the scaler-side gate
+     * would have rejected (e.g. when the bound jobId outlived the scaler that
+     * spawned the agent and was reassigned to a different queued job).
+     *
+     * Returns null if the job is gone, no longer pending, expired, its label
+     * requirements are no longer satisfied by the agent, or the agent's gate
+     * is not satisfied by the job's `runsOn`.
+     */
+    dequeueById(jobId: string, agentLabels: string[], agentMandatoryLabels?: string[]): Promise<QueuedJob | null>;
+    /**
+     * Insert a job directly with status='dispatched' (bypasses the queue).
+     * Used when an agent is immediately available and the job doesn't need to wait.
+     * @returns The generated job ID.
+     */
+    insertDispatched(job: QueuedJobInput): Promise<string>;
+    /**
+     * Mark a job as dispatched.
+     *
+     * Note: agentId is not persisted in the dispatch_queue table.
+     * The dispatcher tracks agent-to-job mappings in memory (agentJobs Map).
+     * The dispatch_queue is a transient routing table, not the execution record.
+     */
+    markDispatched(jobId: string, _agentId: string): Promise<void>;
+    /**
+     * Mark a job as failed.
+     *
+     * Note: reason is not persisted in the dispatch_queue table.
+     * Failure details are tracked in execution_jobs via the reporting pipeline.
+     * The dispatch_queue only tracks routing status transitions.
+     */
+    markFailed(jobId: string, _reason: string): Promise<void>;
+    /**
+     * Mark a dispatched job as completed (terminal success).
+     *
+     * Only transitions rows from `Dispatched` or `Recovering`. A row that has
+     * already reached a terminal state (`Failed`, `Expired`, `Completed`,
+     * `Cancelled`) is left untouched — if the orchestrator already declared
+     * the job failed (e.g. build-coordinator timeout cascading through
+     * {@link failByRunId}), a late `job.complete` from the agent that was
+     * still working must NOT silently flip the row back to `Completed`.
+     */
+    markCompleted(jobId: string): Promise<void>;
+    /**
+     * Expire timed-out pending jobs.
+     * SELECT-then-UPDATE so callers get the expired job details for forwarding.
+     * @returns Array of expired job info (id, runId, jobName).
+     */
+    markExpired(): Promise<ExpiredJobInfo[]>;
+    /**
+     * Bulk-fail every still-non-terminal dispatch_queue entry for a run.
+     *
+     * Called from the run-level failure cascades in `ExecutionTracker`
+     * (`onBuildFailed`, `failRun`). At that point the run itself is being
+     * declared failed, so any dispatch_queue row still in `Pending`,
+     * `Recovering`, or `Dispatched` is by definition orphaned and must
+     * also be moved to `Failed` — leaving a `Dispatched` row in place
+     * keeps the row in a non-terminal state forever, which the build-timeout
+     * E2E (and any operator query for "is this run actually done") relies
+     * on never happening. The complementary {@link markCompleted} status
+     * guard ensures a late `job.complete` from the agent that was still
+     * working when the run was declared failed cannot flip the row back
+     * to `Completed`.
+     *
+     * @returns Number of affected rows.
+     */
+    failByRunId(runId: string): Promise<number>;
+    /**
+     * Bulk-cancel all pending dispatch_queue entries for a run.
+     * Called when a run is cancelled via API.
+     * @returns Number of affected rows.
+     */
+    cancelByRunId(runId: string): Promise<number>;
+    /**
+     * Get the current number of pending jobs.
+     * Uses a 1-second TTL cache to avoid extra SELECT COUNT per enqueue.
+     */
+    getDepth(): Promise<number>;
+    /**
+     * Compute the current dispatch-queue depth breakdown (pending + dispatched),
+     * aggregated per status and, for pending rows, per label.
+     *
+     * Uses the same 1-second TTL cache pattern as {@link JobQueue.getDepth}: if
+     * the cached breakdown is still fresh (or was refreshed within the last
+     * second), the cached value is returned without issuing a query. This keeps
+     * the Prometheus gauge callback cheap on high-frequency scrapes and avoids
+     * any extra DB load during enqueue bursts.
+     *
+     * Multi-label jobs fan out: a pending row with `runs_on_labels = ['linux',
+     * 'x64']` contributes `1` to both the `linux` and `x64` entries in
+     * `byLabel`. The `byStatus` buckets always contain raw counts.
+     */
+    getDepthBreakdown(): Promise<DispatchQueueDepthBreakdown>;
+    /**
+     * Return the most recently cached breakdown without issuing a DB query.
+     *
+     * Intended for synchronous contexts such as the OpenTelemetry observable
+     * gauge callback, which MUST NOT perform I/O. Callers are responsible for
+     * refreshing the cache periodically via {@link JobQueue.getDepthBreakdown}.
+     */
+    readCachedDepthBreakdown(): DispatchQueueDepthBreakdown | null;
+    /**
+     * Get job IDs for a run that are currently dispatched or recovering.
+     * Used by the cancel-run API to send job.cancel to the right agents.
+     * Includes recovering jobs since they may still be reclaimed by a reconnecting agent.
+     */
+    getDispatchedJobIdsByRunId(runId: string): Promise<string[]>;
+    /**
+     * Mark a job as recovering (agent disconnected, within grace period).
+     * Only transitions from 'dispatched' state for safety.
+     */
+    markRecovering(jobId: string): Promise<void>;
+    /**
+     * Mark a job as failed only if it is still in 'recovering' state.
+     * Uses optimistic concurrency to avoid failing jobs that were reclaimed.
+     * @returns true if the update affected a row (job was still recovering).
+     */
+    markFailedIfRecovering(jobId: string, _reason: string): Promise<boolean>;
+    /**
+     * Mark a job as dispatched only if it is still in 'recovering' state.
+     * Used when an agent reconnects and claims a recovering job.
+     * @returns true if the update affected a row (job was still recovering).
+     */
+    markDispatchedIfRecovering(jobId: string): Promise<boolean>;
+    /**
+     * Get a single job by ID.
+     * Used to look up runId during recovery timer setup.
+     */
+    getJobById(jobId: string): Promise<{
+        id: string;
+        runId: string;
+        status: DispatchQueueStatus;
+    } | null>;
+    /**
+     * Get all jobs matching a given status.
+     * Used on startup to find 'dispatched' jobs from a previous instance for recovery.
+     */
+    getJobsByStatus(status: DispatchQueueStatus): Promise<Array<{
+        id: string;
+        runId: string;
+        status: DispatchQueueStatus;
+    }>>;
+    /**
+     * Get all pending jobs in FIFO order (for queue drain on agent connect).
+     */
+    getPendingJobs(): Promise<QueuedJob[]>;
+    /**
+     * Convert a DB row to a QueuedJob object.
+     * Handles both auto-parsed JSONB arrays (from pg driver) and JSON strings (from tests).
+     */
+    private rowToQueuedJob;
+}
+//# sourceMappingURL=job-queue.d.ts.map