@kici-dev/orchestrator 0.9.0 → 0.10.0

package/dist/queue/terminalize-unroutable.d.ts

@@ -4,10 +4,17 @@ import type { Database } from '../db/types.js';
 import type { ExecutionTracker } from '../reporting/execution-tracker.js';
 import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
 import type { PendingGlobalEvalTracker } from '../cache/pending-global-evals.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import { type AgentFitJob, type ScalerAgentView } from '../scaler/agent-fit.js';
 import type { ExpiredJobInfo } from './job-queue.js';
 /**
  * Whether ANYTHING could ever run a job with these selectors — a registered
- * agent (regardless of capacity) or a scaler backend able to spawn one.
+ * agent (regardless of capacity) that can run it, or a scaler backend able to
+ * spawn one.
+ *
+ * `job`, when given, is what the agent must be able to do beyond its labels:
+ * above all start the job's container (`canAgentRunJob`). Absent, any
+ * label-matching agent counts.
  *
  * The predicate is allowed to answer "routable" conservatively: the scaler half
  * matches exact labels only, so a pattern-only `runsOn` reads routable on a
@@ -15,9 +22,20 @@ import type { ExpiredJobInfo } from './job-queue.js';
  * how quickly the job settles, never safety — a job that reads routable
  * falls through to the queue-timeout backstop.
  */
-export type CanRouteLabels = (requiredLabels: string[], requiredPatterns: LabelMatcher[], excludeLabels: string[], excludePatterns: LabelMatcher[]) => boolean;
+export type CanRouteLabels = (requiredLabels: string[], requiredPatterns: LabelMatcher[], excludeLabels: string[], excludePatterns: LabelMatcher[], job?: AgentFitJob) => boolean;
+/**
+ * The one routability predicate, built on the registry and the scaler: the
+ * unroutable probe and the queue-expiry sweep both ask it.
+ */
+export declare function makeCanRouteLabels(deps: {
+    registry: Pick<AgentRegistry, 'hasMatchingAgent'>;
+    scaler?: {
+        hasBackendForLabels(labels: string[], excludeLabels: string[]): boolean;
+        agentView(agentId: string): ScalerAgentView | undefined;
+    };
+}): CanRouteLabels;
 /** The routing facts a verdict is computed from. */
-export type JobRoutingFacts = Pick<ExpiredJobInfo, 'lastProvisioningError' | 'runsOnLabels' | 'runsOnPatterns' | 'excludeLabels' | 'excludePatterns'>;
+export type JobRoutingFacts = Pick<ExpiredJobInfo, 'lastProvisioningError' | 'runsOnLabels' | 'runsOnPatterns' | 'excludeLabels' | 'excludePatterns'> & Partial<Pick<ExpiredJobInfo, 'id' | 'container'>>;
 /** Everything {@link terminalizeUnroutableJob} needs to settle a job. */
 export interface TerminalizeDeps {
     db: Kysely<Database>;
@@ -37,7 +55,22 @@ export interface TerminalizeDeps {
      */
     pendingGlobalEvals?: Pick<PendingGlobalEvalTracker, 'reject'>;
 }
-export declare function unroutableMessage(job: JobRoutingFacts): string;
+/** Why nothing can run a job. */
+export declare enum UnroutableCause {
+    /** No agent or scaler backend matches its labels. */
+    NoMatch = "no-match",
+    /**
+     * Agents match its labels, but it is a container job and none of them can
+     * start a container.
+     */
+    NoContainerRuntime = "no-container-runtime",
+    /**
+     * Agents match its labels, but each was started inside another job's image
+     * and runs only that job.
+     */
+    OnlyOtherJobImageAgents = "only-other-job-image-agents"
+}
+export declare function unroutableMessage(job: JobRoutingFacts, cause?: UnroutableCause): string;
 /**
  * Split the two reasons a queued job never ran: nothing in the fleet matched
  * its `runsOn` (`unroutable` — a label/fleet problem an operator has to fix)

package/dist/registration/registration-index.d.ts

@@ -1,9 +1,16 @@
 import type { LockWorkflow } from '@kici-dev/engine';
+import type { DepCacheKey } from '@kici-dev/shared';
 import type { RegistrationStore } from './registration-store.js';
 /**
  * A registered workflow entry with typed fields for fast in-memory lookup.
+ *
+ * Its `lockfileHash` / `siblingsDigest` are the dependency-cache key of the
+ * lock file that registered it, so a run dispatched from the registration uses
+ * the dependency cache the way a run dispatched from a fetched lock file does.
+ * Both are null unless the key was written for the registration's current
+ * commit, so a run never restores an older lock file's dependencies.
  */
-export interface RegisteredWorkflow {
+export interface RegisteredWorkflow extends DepCacheKey {
     id: string;
     repoIdentifier: string;
     workflowName: string;
@@ -136,6 +143,11 @@ export declare class RegistrationIndex {
      * Disabled rows are filtered out, mirroring the other typed lookups.
      */
     getByOrgAndRepo(customerId: string, repoIdentifier: string): RegisteredWorkflow[];
+    /**
+     * {@link getByOrgAndRepo} with disabled entries included, for a caller that
+     * must tell a disabled workflow from one that is no longer registered.
+     */
+    getAllByOrgAndRepo(customerId: string, repoIdentifier: string): RegisteredWorkflow[];
     /**
      * Get global workflows matching a trigger type within a routing key.
      * Used by the webhook processor for dual-query (per-repo + global).

package/dist/registration/registration-store.d.ts

@@ -1,12 +1,13 @@
 import type { Kysely } from 'kysely';
 import type { LockWorkflow } from '@kici-dev/engine';
+import { type DepCacheKey } from '@kici-dev/shared';
 import type { Database } from '../db/types.js';
 /**
  * Parsed registration row with typed fields.
  * DB stores lock_entry as JSON string and trigger_types as TEXT[],
  * but this interface exposes them as typed objects.
  */
-export interface RegistrationRow {
+export interface RegistrationRow extends DepCacheKey {
     id: string;
     repo_identifier: string;
     workflow_name: string;
@@ -63,6 +64,14 @@ interface ReplaceAllOptions {
      */
     defaultBranch?: string | null;
     sourceFile?: string;
+    /**
+     * The dependency-cache key of the lock file the workflows come from. Written
+     * on every row, like the lock entry it belongs to: an omitted key, or a lock
+     * file that records none, stores no key, so a row never keeps the key of a
+     * lock file it no longer carries the entry of. `commitSha` is written next to
+     * it as the commit the key describes.
+     */
+    depCacheKey?: DepCacheKey;
     /** Set of workflow names that should be marked as global */
     globalWorkflowNames?: Set<string>;
 }

package/dist/reporting/execution-tracker.d.ts

@@ -17,7 +17,27 @@ import { JobKind } from '../db/types.js';
 import { ExecutionRunStatus, type InitFailure, RunFailureClass, ScalerEventType, OrchLogPhase } from '@kici-dev/engine';
 import type { ObserverRegistry } from '../ws/observer-registry.js';
 import type { LogStorage } from './log-storage.js';
-import type { JobQueue } from '../queue/job-queue.js';
+import { type JobQueue } from '../queue/job-queue.js';
+/**
+ * The repository that defines a run's workflow, with the commit the run
+ * dispatched from it and that repository's registered branch.
+ */
+export interface WorkflowRepoProvenance {
+    identifier: string;
+    sha: string | null;
+    branch: string | null;
+}
+/**
+ * The run a re-run re-executes and the root of its re-run chain. Stamped by the
+ * pre-dispatch writers too, so a re-run that is held or fails before its first
+ * job still records what it re-ran.
+ */
+export interface RerunLineage {
+    parentRunId: string;
+    originalRunId: string;
+}
+/** The `trigger_decision` key a held evaluation round records its covered workflows under. */
+export declare const HELD_ROUND_WORKFLOWS_KEY = "heldRoundWorkflows";
 /** Context passed to onExecutionComplete for commit status updates. */
 export interface ExecutionContext {
     workflowName: string;
@@ -39,8 +59,7 @@ export interface ExecutionContext {
     workflowRepoIdentifier?: string;
     /**
      * True when this run records a global evaluation round rather than a
-     * workflow. Forwarded to the Platform so its own re-run refusal can admit the
-     * round's re-evaluation.
+     * workflow. Forwarded to the Platform, which mirrors it on the run row.
      */
     isGlobalEvalRound?: boolean;
     /** Git branch or tag (e.g. "main", "feature/foo"). */
@@ -71,6 +90,13 @@ export interface ExecutionContext {
      * subscriptions can match on it. Null/undefined for success or non-terminal.
      */
     failureClass?: RunFailureClass | null;
+    /**
+     * The run's status generation (`execution_runs.status_epoch`), forwarded on
+     * `execution.status` as `statusEpoch`. Absent reads as 0. It rises only when
+     * a run leaves a terminal status to continue, so the Platform can keep a
+     * finished run finished against a non-terminal frame that arrives late.
+     */
+    statusEpoch?: number;
     /**
      * Resolved trust tier of the run's ref, and which branch's lock file it was
      * evaluated against. Mirror the `execution_runs.trust_tier` /
@@ -396,12 +422,13 @@ export declare class ExecutionTracker {
     /** Pull-request number for PR-triggered runs; null/omitted for non-PR runs. */
     prNumber?: number | null, 
     /**
-     * The repository that DEFINES the workflow, when that is not
-     * `repoIdentifier` — an organization-wide workflow authored in one
-     * repository and dispatched against another. Omitted/null for every
-     * per-repository run, where the two are the same repository.
+     * The repository that DEFINES the workflow, with the commit dispatched from
+     * it and its registered branch, when that is not `repoIdentifier` — an
+     * organization-wide workflow authored in one repository and dispatched
+     * against another. Omitted/null for every per-repository run, where the two
+     * are the same repository.
      */
-    workflowRepoIdentifier?: string | null, 
+    workflowRepo?: WorkflowRepoProvenance | null, 
     /**
      * Pull-request head context, resolved from the normalized event.
      *
@@ -436,6 +463,16 @@ export declare class ExecutionTracker {
      * partitions by it without joining execution_runs.
      */
     private insertTrackedJobRows;
+    /**
+     * Cancel job rows just registered under a run that has already stopped.
+     *
+     * A job registers after its dispatch, so a cancel landing in between leaves
+     * the run terminal while the job's row is written `pending`. The queue
+     * refuses that job's dispatch (`JobQueue.insertDispatched`), so no agent
+     * will ever report on it: its row is cancelled here, as the cancel cancels
+     * the queued jobs it can see.
+     */
+    private cancelJobsOfStoppedRun;
     /**
      * Find the synthetic needs-pending job ID for a given job name in a run.
      * Used by dispatchReadyJob to locate the placeholder entry before replacing it.
@@ -580,6 +617,29 @@ export declare class ExecutionTracker {
      * (in which case the caller skips this status update entirely).
      */
     private recoverRunFromDb;
+    /**
+     * Reopen a run rehydrated from a prematurely `failed` row (e.g. "No agents
+     * available to dispatch jobs", but a queued job is now running): reset the
+     * row to `running`, clear the failure it recorded, and raise its status
+     * generation. The run completion logic then sets the correct final status.
+     *
+     * Called only once the job report that rehydrated the run has been applied to
+     * its job row. A replay of a frame the row already records must not reopen a
+     * finished run: it would roll the run up a second time. A run that failed on
+     * a build failure is never reopened — that failure is intentionally terminal.
+     */
+    private reopenRecoveredRun;
+    /**
+     * Read the run row's status generation into the in-memory run after this
+     * coordinator's reopen matched nothing.
+     *
+     * The reopen loses when another coordinator already reopened the run, or when
+     * this view is a generation behind the row. Either way the row's generation
+     * is the current one: a coordinator that kept its own older value would send
+     * every later frame of the run at a generation the Platform keeps as older, so
+     * none of them would apply.
+     */
+    private adoptStoredStatusEpoch;
     /**
      * Phase 1b: recover job state from the dispatch_queue and add it to the
      * run's in-memory map. Returns the freshly-inserted job entry.
@@ -746,6 +806,7 @@ export declare class ExecutionTracker {
     provenance?: {
         chainDepth?: number;
         dispatchedByFailureLifecycle?: boolean;
+        rerunLineage?: RerunLineage;
     }): Promise<void>;
     /**
      * Write a `failed` execution_runs row directly for an init failure, and drop
@@ -813,6 +874,8 @@ export declare class ExecutionTracker {
          * loop.
          */
         dispatchedByFailureLifecycle?: boolean;
+        /** Re-run lineage, when this run re-runs another. */
+        rerunLineage?: RerunLineage;
     }): Promise<void>;
     /**
      * Write one `failed` execution_runs row for a global eval round that never
@@ -903,6 +966,16 @@ export declare class ExecutionTracker {
          * whole time it sits in the queue and for the run it resumes into.
          */
         workflowRepoIdentifier: string;
+        /**
+         * Commit of the workflow repository the held run dispatches, recorded only
+         * when the workflow is defined in another repository.
+         */
+        workflowSha?: string | null;
+        /**
+         * The workflow repository's registered branch, recorded only when the
+         * workflow is defined in another repository.
+         */
+        workflowBranch?: string | null;
         /**
          * Inherited invoke-chain depth for a run summoned by an invoke gate.
          * REQUIRED to be threaded by any caller that has one: a hold is resumable,
@@ -917,6 +990,60 @@ export declare class ExecutionTracker {
          * excluded from batch accumulation (`EventRouter.isFailureLifecycleRun`).
          */
         dispatchedByFailureLifecycle?: boolean;
+        /** Re-run lineage, when this run re-runs another. */
+        rerunLineage?: RerunLineage;
+        /**
+         * True when the held run is a pre-run global evaluation round rather than a
+         * workflow: the structural marker the release and re-run paths branch on,
+         * written here because a held round is recorded through this method.
+         */
+        isGlobalEvalRound?: boolean;
+        /**
+         * For a held evaluation round: the workflows the round covers, recorded so
+         * its release can refuse when one of them lost its registration while the
+         * round waited. Stored in the row's `trigger_decision` blob.
+         */
+        heldRoundWorkflows?: readonly string[];
+        /**
+         * The source `providerContext` was taken from, when it is not
+         * `routingKey`. Recorded for a held evaluation round, whose release re-drives
+         * the organization-wide pass with that same pair — see
+         * {@link ExecutionTracker.recordGlobalEvalRoundFailureRun}.
+         */
+        dispatchRoutingKey?: string;
+    }): Promise<void>;
+    /**
+     * Claim a held global evaluation round for its release: move it from `held`
+     * to `pending`. Returns false when the row is not a held round — another
+     * release already claimed it — so a re-fired release signal dispatches the
+     * round at most once.
+     *
+     * `pending`, as a resumed per-repository run (`resumeHeldRun`), and not
+     * `running`: orphan recovery fails a `running` row older than its stale
+     * threshold that has no job rows, and a round row keeps the `started_at` of
+     * its hold and never has job rows. No sweeper selects a `pending` row with no
+     * job rows and no workflow timeout.
+     */
+    claimHeldGlobalEvalRound(runId: string): Promise<boolean>;
+    /**
+     * Terminalize a held global evaluation round whose hold was released.
+     *
+     * The released round runs as a job of its own and creates no run row when it
+     * decides, so nothing else ever moves this row out of `held`. `success`
+     * records that the round reached a verdict for its workflow repository;
+     * `failed` that it did not, with the reason. Guarded on `pending`, the
+     * state {@link ExecutionTracker.claimHeldGlobalEvalRound} moved the row to,
+     * so only the release that claimed it settles it.
+     *
+     * A settled round is not an execution: no `executions_total` sample is
+     * counted for a success, and the forwarded frame carries `isGlobalEvalRound`
+     * so the Platform raises no run notification or outbound webhook for it.
+     */
+    completeReleasedGlobalEvalRound(runId: string, outcome: {
+        status: typeof ExecutionRunStatus.enum.success;
+    } | {
+        status: typeof ExecutionRunStatus.enum.failed;
+        reason: string;
     }): Promise<void>;
     /**
      * Flip a `held` run back to `pending` so the resumed dispatch can proceed
@@ -928,6 +1055,19 @@ export declare class ExecutionTracker {
      * to `cancelled` and fires the status-change forward so Platform projects it.
      */
     cancelHeldRun(runId: string, reason: string): Promise<void>;
+    /**
+     * Cancel a run that has no job rows: a run cancelled before it dispatched
+     * any job, a pre-run evaluation round, or a `pending` row a crash left
+     * behind. No job will ever report a terminal status for it, so the cancel
+     * itself writes the terminal row and forwards it, as `cancelHeldRun` does.
+     *
+     * Guarded on the row being non-terminal, not `held`, and having no job rows,
+     * so a run a job registered on in the meantime is left to the job-driven
+     * completion and a held run to the hold-rejection path.
+     * The cancellation reason already stamped on the row wins over `reason`.
+     * Returns whether a row was cancelled.
+     */
+    cancelJoblessRun(runId: string, reason: string): Promise<boolean>;
     /**
      * Mark a run as failed immediately with a reason message.
      *
@@ -1159,6 +1299,7 @@ export declare class ExecutionTracker {
         startedAt: number;
         completedAt?: number;
         durationMs?: number;
+        statusEpoch?: number;
         jobs: Array<{
             jobId: string;
             jobName: string;

package/dist/reporting/log-chunk-sink.d.ts

@@ -46,5 +46,5 @@ export interface LogChunkSinkDeps {
      */
     forwardToPlatform?: (chunk: NormalizedLogChunk) => void;
 }
-export declare function createLogChunkSink(deps: LogChunkSinkDeps): (chunk: NormalizedLogChunk) => void;
+export declare function createLogChunkSink(deps: LogChunkSinkDeps): (chunk: NormalizedLogChunk) => Promise<void>;
 //# sourceMappingURL=log-chunk-sink.d.ts.map

package/dist/reporting/log-writer.d.ts

@@ -74,6 +74,20 @@ export declare class LogWriter {
      *   the agent did not report one, which is recorded as `stdout`.
      */
     appendChunk(runId: string, jobName: string, stepIndex: number, lines: string[], timestamp: number, jobId?: string, stepName?: string, stream?: LogStream): Promise<void>;
+    /**
+     * Make {@link drain} for `runId` wait for `pending` as it waits for an
+     * append.
+     *
+     * For a caller that still has work to do before it can call
+     * {@link appendChunk} — resolving the job name that names the storage key.
+     * Registering only inside `appendChunk` leaves that work outside the
+     * snapshot: a run that completes while the name is being resolved is drained
+     * first, the chunk's append lands afterwards, and on object storage its
+     * segment is never sealed, so the chunk is never readable. A job whose setup
+     * fails sends its last setup lines immediately before its terminal status,
+     * which is exactly that window.
+     */
+    trackPending(runId: string, pending: Promise<unknown>): void;
 }
 export {};
 //# sourceMappingURL=log-writer.d.ts.map

package/dist/reporting/step-log-path.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The storage key of one step's log. The log writer, the `execution_steps`
+ * row's `log_path`, and the step-log readers all build it here, so they agree
+ * on the layout. A job's workflow-level log is step `-1`, stored as
+ * `step--1.log`.
+ */
+export declare function stepLogPath(runId: string, jobName: string, stepIndex: number): string;
+//# sourceMappingURL=step-log-path.d.ts.map

package/dist/reporting/step-log-reader.d.ts

@@ -3,8 +3,11 @@
  *
  * Resolves a step's stored log file via the same `execution_steps.log_path` +
  * `LogStorage` access the dashboard step.logs path uses, then returns the lines
- * with line-based cursor pagination. `toAgentStepLogs` wraps every line in an
- * untrusted envelope (log content is process/user output — never trusted).
+ * with line-based cursor pagination. A job's workflow-level log (step `-1`:
+ * setup narration such as the clone and the dependency install) has no step
+ * row, so its key is derived from the job name the writer used.
+ * `toAgentStepLogs` wraps every line in an untrusted envelope (log content is
+ * process/user output — never trusted).
  */
 import type { Kysely } from 'kysely';
 import { type AgentStepLogs } from '@kici-dev/engine';
@@ -18,6 +21,11 @@ export interface RawStepLogs {
     lines: string[];
     totalLines: number;
     nextCursor: string | null;
+    /**
+     * Whether a log is stored for the step. `false` means none was ever written;
+     * `true` with no lines means the stored log is empty.
+     */
+    recorded: boolean;
 }
 export interface ReadStepLogArgs {
     runId: string;
@@ -31,9 +39,19 @@ export interface ReadStepLogArgs {
 /**
  * Read a page of a step's log lines. Returns an empty page (not an error) when
  * the step row or its log file is absent, so a never-emitted-logs step reads as
- * `{ lines: [], totalLines: 0, nextCursor: null }`.
+ * `{ lines: [], totalLines: 0, nextCursor: null, recorded: false }`.
  */
 export declare function readStepLogLines(deps: StepLogReaderDeps, args: ReadStepLogArgs): Promise<RawStepLogs>;
+/**
+ * The stored log key of the requested step, or `null` when it has none.
+ *
+ * A step's row names its log. The workflow-level log is written under a
+ * negative index that no `step.status` carries (the wire schema is
+ * non-negative), so no row ever names it: its key is built from the job name
+ * (see {@link resolveJobName}, which reads the job's row where the log writer
+ * reads its in-memory name) and used only when the file exists.
+ */
+export declare function resolveStepLogPath(deps: StepLogReaderDeps, args: Pick<ReadStepLogArgs, 'runId' | 'jobId' | 'stepIndex'>): Promise<string | null>;
 /** Wrap raw step logs into the untrusted-tagged `AgentStepLogs` shape. */
 export declare function toAgentStepLogs(runId: string, jobId: string, stepIndex: number, raw: RawStepLogs): AgentStepLogs;
 //# sourceMappingURL=step-log-reader.d.ts.map

package/dist/routes/admin-signing-keys.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Admin API route for reading the orchestrator's provenance signing keys.
+ *
+ *   GET /api/v1/admin/signing-keys — the trusted keys (every status except
+ *                                    `revoked`), oldest first.
+ *
+ * Returns `{ keys: [...] }` carrying only `SIGNING_KEY_METADATA_COLUMNS`: never
+ * the public JWK (served by `/.well-known/jwks.json`) and never the wrapped
+ * private key. Backs `kici-admin signing-key list` when the CLI reads over the
+ * admin API instead of the database.
+ *
+ * The keys belong to the whole orchestrator, not to one tenant, so the route
+ * requires an unscoped token, and `secret.read`, the permission the other
+ * read-only admin inspection routes use.
+ */
+import { Hono } from 'hono';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+export interface AdminSigningKeyRoutesDeps {
+    db: Kysely<Database>;
+    rbac: RbacEnforcer;
+}
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createAdminSigningKeyRoutes(deps: AdminSigningKeyRoutesDeps): Hono<AdminEnv>;
+export {};
+//# sourceMappingURL=admin-signing-keys.d.ts.map

package/dist/scaler/agent-fit.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Which agents may run a job, beyond what its labels say — above all, which
+ * agents may run a job that declares `container:`.
+ *
+ * A container job runs in one of two places. Either the scaler starts an agent
+ * inside the job's image (the agent then runs the steps directly), or an
+ * ordinary agent nests the job's container through a container runtime on its
+ * host. So an agent not started for the job can run it only when the agent can
+ * start containers, and an agent started inside one job's image can run nothing
+ * else: any other job would run in an image it never declared.
+ *
+ * {@link canAgentRunJob} is the one predicate; every dispatch path that hands a
+ * queued job to an agent asks it.
+ */
+import { ScalerBackendType } from '@kici-dev/engine';
+import type { ResourceRequest } from '@kici-dev/engine';
+import type { LabelSetConfig } from './types.js';
+/** What a job asks of the container runtime on the agent that runs it. */
+export declare enum JobContainerNeed {
+    /** The job declares no `container:`, so any agent can run it. */
+    None = "none",
+    /** The job names an image: the agent pulls it and runs the job inside it. */
+    Image = "image",
+    /** The job names a Dockerfile: the agent builds the image, then runs it. */
+    Dockerfile = "dockerfile"
+}
+/**
+ * Classify a job's `container:` declaration.
+ *
+ * Mirrors the agent, which runs a job in container mode whenever its
+ * `container` field is set at all. So any non-empty declaration counts, not
+ * only a well-formed `image`: routing a job to an agent that would then nest
+ * a container it cannot start is the failure this classification prevents.
+ */
+export declare function jobContainerNeed(container: unknown): JobContainerNeed;
+/** The self-reported labels that prove an agent's host can start a container. */
+export declare const CONTAINER_RUNTIME_LABELS: readonly string[];
+/**
+ * Whether an agent's registered labels prove it can start a container.
+ *
+ * The agent reports `kici:runtime:docker` / `kici:runtime:podman` when it finds
+ * that runtime's socket at startup. `kici:runtime:container-build` does not
+ * count: it says a build CLI is on PATH, and a host can have the CLI and no
+ * daemon to run the result on.
+ */
+export declare function hasContainerRuntime(labels: Iterable<string>): boolean;
+/**
+ * Whether a spawn this backend makes for a job that names its own image
+ * starts the agent INSIDE that image.
+ *
+ * - The container backend always does: a spawn carrying the job's image runs
+ *   that image with the KiCI runtime injected.
+ * - The bare-metal backend does only for a label set that declares an `image`
+ *   and no `binaryPath`. Such a set has no local binary to start, so it can
+ *   only mean job-image mode; every other bare-metal set starts a local agent
+ *   that nests the job's container. The backend decides its launch with this
+ *   same function, so the two cannot disagree.
+ * - Every other backend starts an ordinary agent.
+ */
+export declare function spawnsInJobImage(backendType: ScalerBackendType, labelSet: Pick<LabelSetConfig, 'image' | 'binaryPath'>): boolean;
+/** The facts about one job that decide which scaler agents may run it. */
+export interface AgentFitJob {
+    /**
+     * The queued job's id. An agent the scaler started for a job recognizes
+     * that job by it. Absent for a job not yet in the queue, which no agent can
+     * have been started for.
+     */
+    jobId?: string;
+    /** The cpu / memory shape the job declares, if any. */
+    resources?: ResourceRequest;
+    /** What the job's `container:` asks of the agent's host. */
+    container: JobContainerNeed;
+}
+/**
+ * The first agent release whose `kici:runtime:docker` / `kici:runtime:podman`
+ * labels describe the runtime its job containers actually start on. From it
+ * on, an agent with neither label has told the orchestrator it cannot start a
+ * container.
+ *
+ * Earlier releases (0.6.0 to 0.9.x) report runtime labels too, but read
+ * `DOCKER_HOST` only as a socket file path, while their container client
+ * honours any `DOCKER_HOST`. An agent pointed at `tcp://…` — a Docker-in-Docker
+ * sidecar, say — reports no Docker label and runs container jobs fine, so its
+ * missing label proves nothing.
+ */
+export declare const MIN_RUNTIME_FACTS_AGENT_VERSION = "0.10.0";
+/**
+ * Whether an agent's runtime labels are proof, so that a missing
+ * `kici:runtime:docker` / `kici:runtime:podman` label means no runtime: its
+ * version is at least {@link MIN_RUNTIME_FACTS_AGENT_VERSION}, or it reports
+ * `kici:runtime:job-image`, which only such a release sends.
+ *
+ * Any other runtime label is not proof: `kici:runtime:container-build` says a
+ * build CLI is on PATH, and an older agent reports it beside a remote
+ * `DOCKER_HOST` it does not report.
+ */
+export declare function reportsRuntimeFacts(agent: {
+    labels: Iterable<string>;
+    version: string | null | undefined;
+}): boolean;
+/** What the scaler knows about an agent it started. */
+export interface ScalerAgentView {
+    /** The job the scaler started the agent for, and whether it runs in that job's image. */
+    binding?: {
+        jobId: string;
+        jobImage: boolean;
+    };
+    /** The scaler pre-spawned the agent for its warm pool. */
+    prespawned: boolean;
+    /**
+     * Whether the agent's fixed shape leaves a job's declared shape unchanged.
+     * Always true for an agent the scaler did not pre-spawn.
+     */
+    shapeFits(resources: ResourceRequest | undefined): boolean;
+}
+/** The facts about one registered agent that {@link canAgentRunJob} reads. */
+export interface FitAgent {
+    /** The labels the agent registered with, its self-reported facts included. */
+    labels: ReadonlySet<string>;
+    /** The agent's self-reported version, or null when it reported none. */
+    version: string | null;
+    /** The registry records the agent as scaler-started. */
+    scalerManaged: boolean;
+    /** Present when this coordinator's scaler started the agent. */
+    scaler?: ScalerAgentView | undefined;
+}
+/**
+ * The facts `canAgentRunJob` judges a registered agent on: what it reported at
+ * registration, and what the scaler that started it (if one did) recorded.
+ */
+export declare function fitAgentFor(agent: {
+    agentId: string;
+    labels: ReadonlySet<string>;
+    version: string | null;
+    scalerManaged: boolean;
+}, scalerAgentView?: (agentId: string) => ScalerAgentView | undefined): FitAgent;
+/**
+ * Whether this agent may run this job. Every dispatch path that hands a
+ * queued job to an agent asks this one predicate; labels have already matched.
+ *
+ * In order:
+ *
+ * - **The agent started for this job** always runs it: the scaler chose that
+ *   spawn for this job, image and shape included.
+ * - **An agent inside another job's image** runs nothing else. The scaler's
+ *   record says so, or the agent itself does (`kici:runtime:job-image`).
+ * - **A job that declares `container:`** needs an agent that reports
+ *   `kici:runtime:docker` or `kici:runtime:podman`, whenever the missing label
+ *   is proof ({@link runtimeLabelIsProof}).
+ * - **A pre-spawned (warm) agent** must also match any shape the job declares.
+ */
+export declare function canAgentRunJob(agent: FitAgent, job: AgentFitJob): boolean;
+/**
+ * Whether {@link canAgentRunJob} can ever answer false for this agent. The
+ * queue drain carries the predicate into its claim only when it can: for an
+ * agent that runs any job, the drain keeps its single-statement fast path.
+ */
+export declare function agentMayRefuse(agent: FitAgent): boolean;
+//# sourceMappingURL=agent-fit.d.ts.map