@kici-dev/agent 0.4.0 → 0.6.0

package/dist/execution/between-jobs-controller.d.ts

@@ -0,0 +1,50 @@
+import type { ExecutionMode, BetweenJobsRunOn } from '../config.js';
+import { runBetweenJobsReset, type ResetStatus } from './between-jobs-reset.js';
+import { runDeclaredCleanupOutOfBand, type CleanupRerunStatus } from './cleanup-rerun.js';
+interface ControllerConfig {
+    betweenJobsResetCommand?: string;
+    betweenJobsResetTimeoutMs: number;
+    betweenJobsResetRunOn: BetweenJobsRunOn;
+    orphanCleanup: boolean;
+    drainOnResetFailure: boolean;
+}
+export interface AfterJobContext {
+    completionHooksRan: boolean;
+    jobFailed: boolean;
+    backend: ExecutionMode;
+    declaresCleanup: boolean;
+    workDir: string;
+    reap: () => Promise<number>;
+    deleteWorkdir: () => Promise<void>;
+    cleanupSpawn?: (workDir: string, signal: AbortSignal) => Promise<void>;
+}
+export interface BetweenJobsOutcome {
+    rerun: CleanupRerunStatus;
+    reaped: number;
+    reset: ResetStatus;
+    consecutiveResetFailures: number;
+}
+/**
+ * Supervisor-owned between-jobs phase for a reused (bare-metal / in-place) agent.
+ * After every job it sequences: (1) out-of-band declared-cleanup re-run when the
+ * runner died before its completion hooks ran, (2) process-group reap of the
+ * job's descendant tree, (3) workdir deletion, (4) the operator reset command.
+ * Each phase is delegated so the class stays unit-testable, and a persistently
+ * failing reset can drain the agent via the consecutive-failure counter.
+ */
+export declare class BetweenJobsController {
+    private deps;
+    private _consecutiveResetFailures;
+    /** Consecutive between-jobs reset failures, for the supervisor's drain gate. */
+    get consecutiveResetFailures(): number;
+    constructor(deps: {
+        config: ControllerConfig;
+        rerun?: typeof runDeclaredCleanupOutOfBand;
+        reset?: typeof runBetweenJobsReset;
+    });
+    private runRerunPhase;
+    private runResetPhase;
+    afterJob(ctx: AfterJobContext): Promise<BetweenJobsOutcome>;
+}
+export {};
+//# sourceMappingURL=between-jobs-controller.d.ts.map

package/dist/execution/between-jobs-reset.d.ts

@@ -0,0 +1,25 @@
+import type { BetweenJobsRunOn } from '../config.js';
+export type ResetStatus = 'success' | 'failed' | 'timeout' | 'skipped';
+export interface ExecResult {
+    code: number | null;
+    timedOut?: boolean;
+}
+export type ExecFn = (command: string, timeoutMs: number) => Promise<ExecResult>;
+export interface ResetInput {
+    command?: string;
+    timeoutMs: number;
+    runOn: BetweenJobsRunOn;
+    jobFailed: boolean;
+    exec?: ExecFn;
+}
+export interface ResetResult {
+    status: ResetStatus;
+    durationMs: number;
+}
+/**
+ * Run the operator between-jobs reset command. Fail-open: never throws, always
+ * resolves to a status. Skips when unconfigured, or when runOn=on-failure and
+ * the job succeeded.
+ */
+export declare function runBetweenJobsReset(input: ResetInput): Promise<ResetResult>;
+//# sourceMappingURL=between-jobs-reset.d.ts.map

package/dist/execution/cleanup-rerun.d.ts

@@ -0,0 +1,21 @@
+import type { ExecutionMode } from '../config.js';
+export type CleanupRerunStatus = 'success' | 'failed' | 'timeout' | 'skipped';
+export interface CleanupRerunInput {
+    workDir: string;
+    backend: ExecutionMode;
+    declaresCleanup: boolean;
+    timeoutMs: number;
+    spawn: (workDir: string, signal: AbortSignal) => Promise<void>;
+}
+export interface CleanupRerunResult {
+    status: CleanupRerunStatus;
+    durationMs: number;
+}
+/**
+ * Re-run a hard-killed job's declared cleanup/onFailure hooks out-of-band,
+ * against its preserved workdir, in a fresh bounded child. Returns 'skipped'
+ * when there is nothing to do (no declared cleanup, wrong backend, or a
+ * non-positive timeout). Never throws — a failure is reported as a status.
+ */
+export declare function runDeclaredCleanupOutOfBand(input: CleanupRerunInput): Promise<CleanupRerunResult>;
+//# sourceMappingURL=cleanup-rerun.d.ts.map

package/dist/execution/download.d.ts

@@ -4,6 +4,12 @@
  * Extracted from workflow-loader.ts to avoid duplication across
  * dep-restore.ts and workflow-loader.ts.
  */
+/**
+ * Retries a pre-signed upload makes after its first attempt, matching the
+ * dep-tarball download's ceiling (`MAX_RETRIES` in `dep-restore.ts`) so both
+ * halves of the agent's object-storage traffic give up at the same point.
+ */
+export declare const UPLOAD_MAX_RETRIES = 2;
 /**
  * Download content from an HTTP/HTTPS URL.
  *
@@ -15,15 +21,34 @@
  */
 export declare function downloadUrl(url: string): Promise<Buffer>;
 /**
- * Upload a buffer to a pre-signed S3 URL via HTTP PUT.
+ * Upload a buffer to a pre-signed S3 URL via HTTP PUT, retrying a transient
+ * failure.
  *
  * Used for direct-to-S3 uploads of bundles and dep tarballs. Localhost /
  * 127.0.0.1 URLs are rewritten via `resolveOrchestratorUrl` so the
  * filesystem cache backend's signed URLs work from container agents that
  * can't reach the orchestrator's host loopback directly.
  *
+ * **Why retrying is safe here.** A pre-signed PUT writes one whole object at a
+ * single key: there is no multipart session, no append, and no
+ * server-generated identity, so a repeat attempt writes the same bytes to the
+ * same key and the last write wins. S3 also only makes an object visible once
+ * the body has been received in full, so an attempt that died mid-body left
+ * nothing behind. A retry therefore cannot double-write or produce a torn
+ * object — which is why every AWS SDK retries PUTs by default.
+ *
+ * Only a failure that can plausibly differ next time is repeated — see
+ * {@link isRetryableUploadFailure}.
+ *
  * @param url - The pre-signed URL to upload to
  * @param data - The buffer to upload
+ * @param opts.baseDelayMs - Backoff before the first retry (doubles thereafter)
+ * @param opts.timeoutMs - Per-attempt socket-inactivity timeout (see
+ *   {@link UPLOAD_TIMEOUT_MS}); an override exists so a test can drive the
+ *   stall path without waiting out the production budget.
  */
-export declare function uploadToPresignedUrl(url: string, data: Buffer): Promise<void>;
+export declare function uploadToPresignedUrl(url: string, data: Buffer, opts?: {
+    baseDelayMs?: number;
+    timeoutMs?: number;
+}): Promise<void>;
 //# sourceMappingURL=download.d.ts.map

package/dist/execution/dynamic-job-serializer.d.ts

@@ -13,7 +13,8 @@
  *
  * Constraints:
  * - Generated jobs are limited to MAX_DYNAMIC_JOBS per DynamicJobFn invocation
- * - Generated job names must be unique within the same DynamicJobFn output
+ * - Generated job names must be unique within the same DynamicJobFn output, and
+ *   across a whole eval round when the caller threads a shared `seenNames` set
  */
 import type { $ as Shell } from 'zx';
 import type { Job, Logger } from '@kici-dev/sdk';
@@ -54,9 +55,12 @@ export interface SerializerContext {
  *
  * @param jobs - Jobs returned by a DynamicJobFn
  * @param ctx - Eval-time context used to resolve dynamic fields on generated jobs
+ * @param seenNames - Optional accumulator of job names already emitted earlier
+ *   in the same eval round; when supplied, a name already present throws and
+ *   every generated name is added so later generators in the round see it
  * @returns Serialized LockJob array ready for orchestrator dispatch
  * @throws Error if validation fails (duplicates, limit exceeded) or if a user-supplied
  *   dynamic function throws / times out / returns an unsupported value
  */
-export declare function serializeJobsToLock(jobs: Job[], ctx: SerializerContext, staticNames?: Set<string>, allowedGroups?: Set<string>): Promise<LockJob[]>;
+export declare function serializeJobsToLock(jobs: Job[], ctx: SerializerContext, staticNames?: Set<string>, allowedGroups?: Set<string>, seenNames?: Set<string>): Promise<LockJob[]>;
 //# sourceMappingURL=dynamic-job-serializer.d.ts.map

package/dist/execution/generator-context.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The single builder for a `DynamicJobFn`'s context.
+ *
+ * A generator is evaluated twice — once pre-dispatch to produce the job list,
+ * and once inside the sandbox to recover the step closures a `LockJob` cannot
+ * carry. `extractStepsFromDynamicJob` throws when the target job is missing on
+ * re-evaluation, so a generator whose two calls see different contexts is
+ * unsound by construction. Every call site builds its context here so the two
+ * cannot drift apart.
+ */
+import type { DynamicJobContext, RepoInfo } from '@kici-dev/sdk';
+/**
+ * The source / workflow repo pair a global workflow's generator sees.
+ *
+ * `sourceRepo.path` is an absolute path into THIS evaluation's work directory:
+ * it is NOT stable across the two evaluations (a different `workDir`, possibly
+ * a different machine). Its *contents* are stable; the path is not. So read
+ * through the path — never embed it in a generated job name, a job output, or
+ * anything else the two evaluations are compared on.
+ *
+ * `RepoInfo.ref` and `.sha` are optional: an evaluation that has no checkout
+ * metadata still supplies the pair. Never assume either is present.
+ */
+export interface GeneratorRepoPair {
+    sourceRepo: RepoInfo;
+    workflowRepo: RepoInfo;
+}
+/** Input for {@link buildGeneratorContext}. */
+export interface GeneratorContextInput {
+    workflowName: string;
+    /**
+     * The raw wire event. Untyped JSON that, per the unified event protocol,
+     * always carries the normalized event envelope.
+     */
+    event: Record<string, unknown>;
+    env: Record<string, string | undefined>;
+    /** Present for a global workflow; omitted entirely otherwise. */
+    repos?: GeneratorRepoPair;
+    /** Frozen upstream outputs for a result-aware generator. */
+    needs?: NonNullable<DynamicJobContext['ctx']['needs']>;
+    $: DynamicJobContext['$'];
+    log: DynamicJobContext['log'];
+    kici: DynamicJobContext['kici'];
+}
+/**
+ * Build the context handed to a `DynamicJobFn`.
+ *
+ * Optional members are spread conditionally rather than assigned `undefined`,
+ * so an absent `needs` / repo pair leaves no key behind — a present-but-
+ * undefined key reads as "declared" to a generator and serializes differently
+ * between the two evaluations.
+ */
+export declare function buildGeneratorContext(input: GeneratorContextInput): DynamicJobContext;
+//# sourceMappingURL=generator-context.d.ts.map

package/dist/execution/global-eval-runner.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The pre-run global eval round.
+ *
+ * One round runs per (event × workflow repo), on an agent that already holds
+ * both trees on disk. For each candidate global workflow it runs the workflow's
+ * `filter` — deciding whether the workflow applies to the source repo at all —
+ * and, for a survivor, its `DynamicJobFn`s, so the orchestrator can dispatch
+ * generated jobs it could not otherwise see. The round precedes every run row:
+ * a `filter` returning `false` means no run is created.
+ *
+ * Shape is modelled on `init-runner.ts` — load the module, resolve the target,
+ * evaluate under `withTimeout`, return a structured result. As there, author
+ * code runs in the agent's ordinary module loader: no `vm`, no `new Function`,
+ * no dynamic `eval`.
+ *
+ * Two properties are load-bearing and easy to lose:
+ *
+ * - **One bad candidate never sinks the round.** A candidate whose filter or
+ *   generator throws, or that blows its budget, comes back
+ *   `{ run: false, indeterminate: true, reason }` while its siblings carry real
+ *   verdicts. Several unrelated org-wide workflows share a round; a single
+ *   broken filter suppressing all of them would be a silent outage.
+ * - **Candidates are STARTED sequentially.** They share one checkout and one
+ *   working directory, so a parallel `$` would race on cwd. This is a strict
+ *   guarantee on the happy path and **best-effort past a timeout**: `withTimeout`
+ *   races rather than cancels, so a candidate that blew its own budget is still
+ *   running when the next one starts. Nothing can preempt user code mid-`await`,
+ *   so the round bounds the damage rather than eliminating it — the loop stops
+ *   at the round deadline (and on the caller's abort signal), which caps the
+ *   overlap at one orphaned candidate instead of the whole remaining queue.
+ */
+import type { RepoInfo, DynamicJobContext, Logger } from '@kici-dev/sdk';
+import { type $ as Shell } from 'zx';
+import type { ChangedFilesStatus, GlobalEvalRoundResult } from '@kici-dev/engine';
+/** One workflow the round must decide on, as the lock file describes it. */
+export interface GlobalEvalCandidate {
+    workflowName: string;
+    /** Repo-relative path of the workflow module inside the workflow checkout. */
+    sourceFile: string;
+    /** From `LockWorkflow.hasFilter` — skip the filter call entirely when false. */
+    hasFilter: boolean;
+}
+/** Arguments for {@link runGlobalEvalRound}. */
+export interface GlobalEvalRoundArgs {
+    /** Absolute path of the workflow-repo checkout (modules are loaded from here). */
+    workflowDir: string;
+    /** Absolute path of the source-repo checkout. */
+    sourceDir: string;
+    repos: {
+        sourceRepo: RepoInfo;
+        workflowRepo: RepoInfo;
+    };
+    candidates: GlobalEvalCandidate[];
+    /** The raw wire event, carrying the normalized event envelope. */
+    event: Record<string, unknown>;
+    changedFiles: string[];
+    /**
+     * Availability of `changedFiles`. Required, not defaulted: it feeds the
+     * throwing accessor on `FilterContext`, and defaulting it to `'fetched'`
+     * would let a diff-less event read as an empty diff and silently suppress
+     * every path-gated workflow in the round.
+     */
+    changedFilesStatus: ChangedFilesStatus;
+    /** Wall-clock budget for the whole round. */
+    roundTimeoutMs: number;
+    /** Wall-clock budget for one candidate (its filter plus its generators). */
+    candidateTimeoutMs: number;
+    /**
+     * Caller's cancellation signal. The round stops starting new candidates once
+     * it fires; the one already in flight cannot be preempted (see the module
+     * doc comment) but its verdict is discarded.
+     */
+    signal?: AbortSignal;
+    /** zx shell handed to filters and generators. Defaults to the ambient `$`. */
+    $?: typeof Shell;
+    /** Logger handed to generators. Defaults to a no-op. */
+    log?: Logger;
+    /** KiCI API handed to generators. Defaults to one that rejects every call. */
+    kici?: DynamicJobContext['kici'];
+    /**
+     * Module loader seam. Defaults to `loadWorkflowSource` against `workflowDir`;
+     * a caller that already holds the modules (or a unit test) supplies its own.
+     */
+    loadModule?: (sourceFile: string) => Promise<Record<string, unknown>>;
+}
+/**
+ * Run one global eval round and return every candidate's verdict, in candidate
+ * order. Never throws: a round that exceeds `roundTimeoutMs` reports whatever
+ * it established and marks the rest indeterminate.
+ */
+export declare function runGlobalEvalRound(args: GlobalEvalRoundArgs): Promise<GlobalEvalRoundResult>;
+//# sourceMappingURL=global-eval-runner.d.ts.map

package/dist/execution/global-workflow-env.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The single writer of the seven `KICI_*` ambient env keys a global workflow's
+ * user code sees.
+ *
+ * It lives here rather than in `sandbox/workflow-runner.ts` because that module
+ * calls `main()` at import time — it is the sandbox process entry point — so the
+ * agent's own process cannot import it. The pre-dispatch global eval round runs
+ * in the agent process and must set exactly the same keys the sandbox does.
+ *
+ * Why exactly the same keys: `extractAndNormalizeSteps` hands a `DynamicJobFn`
+ * `process.env` as its `env`, and a generator is evaluated twice — once
+ * pre-dispatch, once inside the sandbox to recover the step closures a `LockJob`
+ * cannot carry. A generator that reads `process.env.KICI_SOURCE_REPO_PATH` and
+ * gets a value on one call and `undefined` on the other has seen two different
+ * worlds, which `extractStepsFromDynamicJob` turns into a hard determinism
+ * failure. `buildGeneratorContext` keeps the two contexts' *shape* identical; it
+ * cannot keep the ambient env identical, which is what this does.
+ */
+import type { RepoInfo } from '@kici-dev/sdk';
+/** The source / workflow repo pair a global-workflow evaluation runs against. */
+export interface GlobalWorkflowRepos {
+    sourceRepo: RepoInfo;
+    workflowRepo: RepoInfo;
+}
+/**
+ * Derive an `owner/repo` identifier from a clone URL, stripping the trailing
+ * `.git` and any `http(s)://host/` prefix.
+ */
+export declare function repoIdentifierFromUrl(repoUrl: string): string;
+/** Every env key {@link applyGlobalWorkflowEnv} writes, in one place. */
+export declare const GLOBAL_WORKFLOW_ENV_KEYS: readonly ['KICI_IS_GLOBAL_WORKFLOW', 'KICI_WORKFLOW_REPO_PATH', 'KICI_SOURCE_REPO_PATH', 'KICI_SOURCE_REPO', 'KICI_SOURCE_BRANCH', 'KICI_SOURCE_SHA', 'KICI_WORKFLOW_REPO'];
+/**
+ * Inject the seven global-workflow env keys and return a restorer that puts
+ * `process.env` back exactly as it was — each key reset to its prior value, or
+ * deleted if it had none.
+ *
+ * **The restorer is mandatory for any caller in a long-lived process.** The
+ * sandbox may ignore it: it runs one job per forked child, which exits. The
+ * pre-dispatch global eval round may NOT: it runs in the agent process, which
+ * serves many dispatches from one `JobRunner`. Leaving the keys set there is
+ * this module's own hazard running backwards — a later NON-global
+ * `DynamicJobFn` evaluation builds its generator context with
+ * `env: process.env` still carrying `KICI_IS_GLOBAL_WORKFLOW=true` and a
+ * `KICI_SOURCE_REPO_PATH` pointing at a deleted work directory, while that
+ * job's own sandbox re-evaluation sees neither (`buildSanitizedEnv` scrubs the
+ * whole `KICI_*` namespace on the trusted profile, and the default profile is
+ * allowlist-only). That is the same two-worlds determinism failure, injected
+ * into an unrelated job.
+ *
+ * `RepoInfo.ref` / `.sha` are optional, so an evaluation with no checkout
+ * metadata writes an empty string rather than leaving the key unset — matching
+ * how `KICI_WORKFLOW_REPO` already handles a missing identifier. Assigning
+ * `undefined` to a `process.env` key would stringify to `"undefined"`, which is
+ * worse than either.
+ */
+export declare function applyGlobalWorkflowEnv(repos: GlobalWorkflowRepos): () => void;
+//# sourceMappingURL=global-workflow-env.d.ts.map

package/dist/execution/image-build/build-engine.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Build a job's container image with the host's build CLI.
+ *
+ * The CLI is REQUIRED — there is deliberately no socket-API fallback. One build
+ * path means one set of Dockerfile semantics: `.dockerignore`, BuildKit and
+ * every directive behave as they do on the author's own machine, instead of
+ * depending on which agent happened to pick the job up. A host without a CLI
+ * cannot run a Dockerfile job, and says so in as many words.
+ */
+import { z } from 'zod';
+import type { JobImageBuildSpec } from './resolve-build-spec.js';
+/** The build CLIs an agent host may provide. */
+export declare const ContainerBuildCli: z.ZodEnum<{
+    docker: "docker";
+    podman: "podman";
+}>;
+export type ContainerBuildCli = z.infer<typeof ContainerBuildCli>;
+/** Is `bin` executable somewhere on `PATH`? */
+export declare function binaryOnPath(bin: string): boolean;
+/**
+ * The container socket the SANDBOX will use.
+ *
+ * Mirrors what dockerode's `new Docker()` resolves, and exists so build and run
+ * provably agree. A host with both runtimes whose sandbox socket points at
+ * podman would otherwise build with docker and then start the job container on
+ * a daemon that has never heard of that image — a failure that surfaces as
+ * "no such image" and names nothing.
+ */
+export declare function sandboxSocketPath(): string;
+export declare function resolveBuildCli(args: {
+    configured?: ContainerBuildCli | undefined;
+    onPath?: (bin: string) => boolean;
+}): ContainerBuildCli;
+export declare function buildArgv(args: {
+    cli: ContainerBuildCli;
+    spec: JobImageBuildSpec;
+    socketPath?: string | undefined;
+}): string[];
+/** Registry credentials in the shape a build CLI's config file expects. */
+export interface BuildAuthconfig {
+    username: string;
+    password: string;
+    serveraddress: string;
+}
+/**
+ * Split a chunk stream into whole lines, carrying the remainder between chunks.
+ *
+ * `flush` matters: a builder whose last line has no trailing newline — which is
+ * exactly the shape of an error written just before exit — would otherwise leave
+ * that line in the carry, and the one line the author most needs would be the
+ * one that never reaches the run log.
+ */
+export declare function makeLineSplitter(onLine: (line: string) => void): {
+    write: (chunk: Buffer) => void;
+    flush: () => void;
+};
+export interface BuildJobImageArgs {
+    spec: JobImageBuildSpec;
+    cli: ContainerBuildCli;
+    socketPath?: string | undefined;
+    authconfig?: BuildAuthconfig | undefined;
+    /** Every line of build output, in order, for the run log. */
+    onLog: (line: string) => void;
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Run the build. Resolves when the image is tagged; rejects with the builder's
+ * own last words otherwise.
+ *
+ * The rejection carries real output rather than an exit code because the author
+ * is the one who has to act on it, and "exit 1" tells them nothing about which
+ * `RUN` failed.
+ */
+export declare function buildJobImage(args: BuildJobImageArgs): Promise<void>;
+//# sourceMappingURL=build-engine.d.ts.map

package/dist/execution/image-build/build-step.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Run a job's image build and render it as a step in the run.
+ *
+ * The build happens on the AGENT, before the sandbox exists, so it cannot use
+ * the runner's IPC pseudo-step channel that the cache phase uses — that channel
+ * belongs to a process which has not started yet. It uses the agent-side seam
+ * the synthetic `build` / `init` / `global-eval` jobs already use: a step-status
+ * pair plus a log streamer bound to a step index.
+ */
+import { ExecutionStepStatus } from '@kici-dev/engine';
+import type { LockJob } from '@kici-dev/engine';
+import { type JobImageBuildSpec } from './resolve-build-spec.js';
+/** Step name the run timeline shows for a job's image build. */
+export declare const CONTAINER_BUILD_STEP_NAME = "container:build";
+/**
+ * Step index the image build reports under.
+ *
+ * A large positive constant, for two reasons that are easy to trip over:
+ *
+ * - `step.status` carries `z.number().int().nonnegative()`, so a negative index
+ *   is not available. An agent that sent one to an OLDER orchestrator would be
+ *   disconnected mid-job (an invalid message closes the socket), and two
+ *   consumers read a negative index as absent — the check-run reporter writes
+ *   `steps[stepIndex]`, and the dashboard gates log fetching on `stepIndex >= 0`.
+ * - It must clear every index the in-sandbox allocators reach. The cache phase
+ *   tops out around `stepCount * 3 + 100 + (stepCount + 1) * 1000`, so this
+ *   clears a job of several hundred steps with room to spare.
+ *
+ * DISPLAY ORDER does not come from this index. The step is tagged with the
+ * `container:build` {@link SetupStepType}, and readers sort setup pseudo-steps
+ * ahead of the real steps by type — so the build renders where it ran, first,
+ * without a negative index or a protocol change.
+ */
+export declare const CONTAINER_BUILD_STEP_INDEX = 1000000;
+export interface RunJobImageBuildArgs {
+    container: LockJob['container'];
+    workDir: string;
+    jobId: string;
+    jobName: string;
+    /** Perform the build. Injected so the step logic is testable without a host. */
+    build: (spec: JobImageBuildSpec, onLog: (line: string) => void) => Promise<void>;
+    /** Every line of build output, in order, for the run log. */
+    onLog: (line: string) => void;
+    sendStepStatus: (name: string, state: ExecutionStepStatus, data?: Record<string, unknown>) => void;
+    fileExists?: (p: string) => boolean;
+}
+/**
+ * Build the job's image when it declared a Dockerfile, and return the tag the
+ * sandbox should run.
+ *
+ * Returns `undefined` when there is nothing to build — a job with no container,
+ * or one that names a finalized image. That is the common case and emits no
+ * step at all: a run timeline should not grow an empty entry for work that did
+ * not happen.
+ */
+export declare function runJobImageBuild(args: RunJobImageBuildArgs): Promise<string | undefined>;
+//# sourceMappingURL=build-step.d.ts.map

package/dist/execution/image-build/resolve-build-spec.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Turn a job's `container.dockerfile` into an absolute, checked build spec.
+ *
+ * Pure on purpose. Every rule that decides what gets built — the anchoring, the
+ * escape refusal, the tag shape — is decided here and unit-tested without a
+ * container runtime anywhere near it. The half that needs a host lives in
+ * `build-engine.ts`.
+ */
+import type { LockJob } from '@kici-dev/engine';
+/** Everything the build CLI needs, resolved and checked. */
+export interface JobImageBuildSpec {
+    /** Absolute path to the Dockerfile. */
+    dockerfilePath: string;
+    /** Absolute build-context directory. */
+    contextDir: string;
+    /** Build stage to stop at, when the job named one. */
+    target?: string;
+    /** Build arguments. Plain strings — never secret material. */
+    args: Record<string, string>;
+    /** Tag the built image gets, and the sandbox then runs. */
+    tag: string;
+    /** Labels that put the image in reach of the leak sweep. */
+    labels: Record<string, string>;
+}
+export interface ResolveJobImageBuildSpecArgs {
+    container: LockJob['container'];
+    /** The cloned tree. Every path resolves against this and must stay inside it. */
+    workDir: string;
+    jobId: string;
+    jobName: string;
+    /** Injected for tests; defaults to a real filesystem check. */
+    fileExists?: (p: string) => boolean;
+}
+/**
+ * Resolve the build spec for a job, or `undefined` when the job builds nothing.
+ *
+ * `undefined` is the common case and is not a failure: a job with no container,
+ * or one that names a finalized image, has nothing to build.
+ */
+export declare function resolveJobImageBuildSpec(args: ResolveJobImageBuildSpecArgs): JobImageBuildSpec | undefined;
+//# sourceMappingURL=resolve-build-spec.d.ts.map

package/dist/execution/image-build/runtime-facts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What this agent's own host can do with containers, discovered at startup.
+ *
+ * The orchestrator cannot answer this. An agent runs on its own machine, and
+ * whether that machine has a container runtime is the agent's fact — probing
+ * the orchestrator's filesystem answers a different question, and doing so once
+ * stranded container jobs that had been running fine, because the probe and the
+ * job ran in different places.
+ *
+ * Reported as `kici:runtime:*` labels, which the register-time scope gate
+ * accepts unchallenged as self-reported facts. Deliberately NOT
+ * `kici:capability:*` — that prefix grants a privilege and stays token-bound.
+ */
+import { RuntimeFact } from '@kici-dev/engine';
+export interface DetectRuntimeFactsDeps {
+    /** Injected for tests; defaults to a real filesystem check. */
+    pathExists?: (p: string) => boolean;
+    binaryOnPath?: (bin: string) => boolean;
+}
+/**
+ * Discover this host's runtime facts.
+ *
+ * Presence of the socket FILE, not a handshake: registration must not block on
+ * a daemon that is slow or wedged, and a job that reaches a broken runtime
+ * still fails with the runtime's own error. The label answers "is there a
+ * runtime here at all", which is the routing question.
+ */
+export declare function detectRuntimeFacts(deps?: DetectRuntimeFactsDeps): RuntimeFact[];
+/** The `kici:runtime:*` labels this host should register with. */
+export declare function runtimeFactLabels(deps?: DetectRuntimeFactsDeps): string[];
+//# sourceMappingURL=runtime-facts.d.ts.map