@kici-dev/agent 0.5.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/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/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

package/dist/execution/job-runner.d.ts

@@ -5,6 +5,7 @@ import { type FilterEvalInput } from './init-runner.js';
 import { buildNeedsContext } from '@kici-dev/sdk';
 import type { $ as Shell } from 'zx';
 import type { CacheRequestIpc, CacheResponseIpc, ProvenanceRequestIpc, ProvenanceResponseIpc, ArtifactRequestIpc, ArtifactResponseIpc, StepApprovalRequestIpc, StepApprovalResolvedIpc } from './sandbox/index.js';
+import { BetweenJobsController } from './between-jobs-controller.js';
 /**
  * Materialize the source tree a non-global workflow's `filter` reads through
  * `ctx.sourceRepo.path`.
@@ -72,10 +73,17 @@ export interface JobRunnerDeps {
     send: (msg: AgentToOrchestratorMessage) => void;
     /** Agent config */
     config: AppConfig;
+    /**
+     * Supervisor-owned between-jobs phase, run after every job to reap the
+     * process tree, re-run declared cleanup out-of-band, delete the workdir, and
+     * run the operator reset command. Optional so unit harnesses can omit it.
+     */
+    betweenJobsController?: BetweenJobsController;
     /** Request a pre-signed S3 upload URL from the orchestrator via WS request-response. */
     requestUploadUrl: (jobId: string, cacheType: 'source' | 'deps', key: {
         contentHash?: string;
         lockfileHash?: string;
+        depsHash?: string;
         platform: string;
         arch: string;
     }) => Promise<string>;
@@ -244,6 +252,8 @@ export declare class JobRunner {
     private readonly _sendRunEvent;
     private readonly _sendConcurrencyReport;
     private readonly _sendApiRequest?;
+    /** Live git credentials per job, so the sandbox can reach the grant table. */
+    private readonly jobGitCredentials;
     private readonly _requestUserCache?;
     private readonly _relayProvenance?;
     private readonly _requestUserArtifact?;
@@ -252,6 +262,15 @@ export declare class JobRunner {
     readonly activeJobs: Map<string, ActiveJob>;
     /** Active sandbox for the current job (used for abort). */
     private activeSandbox;
+    /** Supervisor-owned between-jobs phase (reap / cleanup re-run / reset). */
+    private readonly betweenJobsController?;
+    /**
+     * Facts about the just-finished standard job, captured before sandbox
+     * teardown so the between-jobs controller (run in `execute`'s `.finally`) can
+     * reach them. Null for special job types (init / build / dynamic), which run
+     * no sandbox — the controller then only deletes the workdir and resets.
+     */
+    private betweenJobsFacts;
     constructor(deps: JobRunnerDeps);
     /**
      * Execute a dispatched job through its full lifecycle.
@@ -260,6 +279,23 @@ export declare class JobRunner {
      * reports status, and cleans up.
      */
     execute(dispatch: JobDispatch): Promise<void>;
+    /**
+     * Stand up per-job git credentials, or `undefined` when the agent has no
+     * orchestrator relay (unit harnesses, offline local runs).
+     *
+     * A failure here must not fail the job: without a helper, git falls back to
+     * its own mechanisms exactly as it did before this existed. The job simply
+     * cannot push.
+     */
+    private startGitCredentials;
+    /**
+     * Run the supervisor-owned between-jobs phase after a job finishes. Delegates
+     * to the injected `BetweenJobsController` (out-of-band cleanup → reap →
+     * workdir delete → operator reset) with facts captured before sandbox
+     * teardown. When no controller is wired (unit harnesses) it just deletes the
+     * workdir, preserving the historical behavior. Never throws.
+     */
+    private runBetweenJobsPhase;
     /**
      * Cancel a running job by signaling its abort controller
      * and aborting the active sandbox.
@@ -407,6 +443,18 @@ export declare class JobRunner {
      * and sends the result back to the orchestrator.
      */
     private handleDynamicJobFn;
+    /**
+     * Build the job's container image when it declared a Dockerfile, and return
+     * the tag the sandbox must run.
+     *
+     * Returns `undefined` for every other job — one with no container, or one
+     * naming a finalized image — which is the common case and costs nothing.
+     *
+     * Extracted from `setupSandboxForExecution` so that function stays inside the
+     * 200-line ceiling, and so the build's streamer lifecycle is visibly bounded
+     * by one `finally`.
+     */
+    private buildJobImageIfDeclared;
     /**
      * Create the appropriate sandbox backend based on execution mode.
      */

package/dist/execution/sandbox/bare-metal-sandbox.d.ts

@@ -31,6 +31,11 @@ interface BareMetalSandboxOptions {
     sandboxNetwork?: 'isolated' | 'host';
     /** Pre-sanitized environment variables (system allowlist + user env). */
     env: Record<string, string>;
+    /**
+     * When true (and bwrap is off), spawn the runner in its own process group so
+     * the between-jobs phase can reap a backgrounded daemon. Default true.
+     */
+    orphanCleanup?: boolean;
 }
 /**
  * Bare-metal execution sandbox implementation.
@@ -43,8 +48,10 @@ export declare class BareMetalSandbox implements ExecutionSandbox {
     private readonly useBwrap;
     private readonly sandboxNetwork;
     private readonly env;
+    private readonly orphanCleanup;
     private runner;
     private workDir;
+    private lastOptions;
     constructor(options: BareMetalSandboxOptions);
     /**
      * Validate that the runner path exists and bwrap is available (if needed).
@@ -61,9 +68,26 @@ export declare class BareMetalSandbox implements ExecutionSandbox {
      */
     abort(): Promise<void>;
     /**
-     * Clean up the child process if still running.
+     * Clean up the child process if still running. The handle reference is kept
+     * (not nulled) so the between-jobs phase can still read `completionHooksRan` /
+     * `declaresCleanup` and reap the process group after teardown — the group
+     * survives the single child's death. The next `executeJob` overwrites it.
      */
     teardown(): Promise<void>;
+    /** Whether the runner signalled its completion hooks ran. */
+    get completionHooksRan(): boolean;
+    /** Whether the job declared an onFailure / cleanup hook. */
+    get declaresCleanup(): boolean;
+    /** Reap the finished job's process group. */
+    reap(): Promise<number>;
+    /**
+     * Re-run the finished job's declared cleanup / onFailure hooks against the
+     * preserved workdir, in a fresh cleanup-only child. Reuses the last job's
+     * dispatch + orchestrator relays but suppresses step/log callbacks (the
+     * original job already reported and its log streamers are gone). Rejects when
+     * the cleanup-only child fails so the caller can time it out.
+     */
+    runCleanupOnly(workDir: string, signal: AbortSignal): Promise<void>;
 }
 export {};
 //# sourceMappingURL=bare-metal-sandbox.d.ts.map

package/dist/execution/sandbox/container-sandbox.d.ts

@@ -12,8 +12,11 @@
  * - Agent-internal credentials (KICI_*, KICI_DATABASE_URL, etc.) NEVER enter the container
  * - IPC uses demuxed Docker stream with JSON-line parsing on stdout
  *
- * The container image MUST have Node.js installed (a kici/runner base image
- * is deferred -- for now this is a documented requirement).
+ * The container image does NOT need Node.js or git. KiCI provisions its own
+ * runtime — a pinned, official glibc-2.17 Node plus the runner bundle, mounted
+ * read-only at /opt/kici — and launches the runner with THAT node. The image
+ * needs only a glibc and a shell, which the preflight asserts before the
+ * container is created.
  */
 import Docker from 'dockerode';
 import type { ExecutionSandbox, SandboxSetupOptions, JobExecutionOptions, JobExecutionResult } from './types.js';
@@ -27,6 +30,51 @@ interface ContainerSandboxOptions {
     runnerPath: string;
     /** Mount target inside container (default: /opt/kici/workflow-runner.js). */
     runnerMountPath?: string;
+    /**
+     * Pre-provisioned KiCI Node tree (the directory whose `bin/node` is the
+     * injected runtime), bind-mounted read-only at `/opt/kici/node`. A HOST
+     * path, or the name of a volume already holding the tree.
+     *
+     * When supplied, the runner launches on THAT node and the image needs no
+     * Node of its own. Wins over `runtimeImage` — a caller that already has the
+     * tree should not pay a materialization to get the same one.
+     */
+    runtimeNodePath?: string;
+    /**
+     * KiCI agent image carrying `/opt/kici`, from which the Node tree is
+     * materialized into a named volume during setup.
+     *
+     * This is how an agent nesting a job container gets a runtime: a bind mount
+     * needs a HOST path, and the agent may itself be containerized, so it cannot
+     * assume `/opt/kici` exists on the host filesystem. Copying the tree out of
+     * the image into a volume once, then mounting that volume, works either way.
+     *
+     * Absent (and no `runtimeNodePath`) means no injection: the runner falls
+     * back to the image's own `node`, which is the historical contract and still
+     * correct for an image that ships one. Both modes are correct; the fallback
+     * is not a workaround for a missing mount but the mode a caller that has no
+     * runtime to inject is in.
+     */
+    runtimeImage?: string;
+    /**
+     * Tag this sandbox's image was BUILT under, when the job declared a
+     * Dockerfile rather than naming an image.
+     *
+     * Present only for a built image, and removed at teardown — a tag per run
+     * would otherwise accumulate on the host forever. Removing the tag leaves the
+     * layer cache untouched, which is what makes the next build fast, so this
+     * costs nothing but the name.
+     */
+    buildTag?: string;
+    /**
+     * Registry credentials for pulling `image`, already resolved by the
+     * orchestrator. Absent means an anonymous pull.
+     */
+    registryAuth?: {
+        username: string;
+        password: string;
+        serveraddress: string;
+    };
     /**
      * Path to the pure-JS container loader-hook bundle on the HOST (bind-mounted
      * read-only). Defaults to `container-ts-loader-hook.js` next to `runnerPath`.
@@ -51,6 +99,17 @@ export declare class ContainerSandbox implements ExecutionSandbox {
     private readonly docker;
     private readonly image;
     private readonly runnerPath;
+    private readonly runtimeNodePath;
+    private readonly runtimeImage;
+    private readonly buildTag;
+    /**
+     * The runtime actually injected into this job's container — the configured
+     * path, or the volume materialized during setup. Resolved once in setup()
+     * because materialization needs the container runtime, and read by both the
+     * bind list and the runner launch.
+     */
+    private resolvedRuntimeNode;
+    private readonly registryAuth;
     private readonly runnerMountPath;
     /** Host path to the pure-JS container loader-hook bundle (bind-mounted :ro). */
     private readonly hookHostPath;
@@ -81,7 +140,35 @@ export declare class ContainerSandbox implements ExecutionSandbox {
      * private images pre-pulled with registry auth stay working) skip the pull.
      */
     private ensureImagePresent;
+    /**
+     * Resolve the Node tree to inject into the job container, materializing it
+     * when only an image was configured.
+     *
+     * A configured path wins: a caller that already provisioned the tree should
+     * not pay a copy to arrive at the same one. Returning `undefined` is a real
+     * outcome, not a failure — an agent with no runtime source runs the job on
+     * the image's own `node`, which is what a `node:*` image was always doing.
+     *
+     * A materialization that FAILS is not softened into that outcome. Continuing
+     * would start the job against an image the operator never claimed ships Node,
+     * and the resulting "node: not found" says nothing about the runtime that was
+     * supposed to be there.
+     */
+    private resolveRuntimeNode;
     setup(options: SandboxSetupOptions): Promise<void>;
+    /**
+     * Populate the container's `/workspace` volume from the host working tree.
+     *
+     * `/workspace` is a container-owned anonymous volume rather than a host bind,
+     * which is what dissolves the host-uid vs container-uid conflict once
+     * `CapDrop: ['ALL']` removes CAP_DAC_OVERRIDE — so the tree is streamed in as
+     * a tar rather than mounted.
+     *
+     * A failure here is fatal on purpose. Swallowing it would start the job
+     * against an EMPTY workspace, which surfaces as a baffling "file not found"
+     * in whichever step happens to touch the repo first.
+     */
+    private copyWorkspaceIn;
     /**
      * Build the container's read-only bind list.
      *
@@ -133,6 +220,14 @@ export declare class ContainerSandbox implements ExecutionSandbox {
      */
     private buildExecutionResult;
     abort(): Promise<void>;
+    /**
+     * Drop the tag a `container.dockerfile` build produced.
+     *
+     * Best-effort: teardown must not fail a job that already finished. The LAYER
+     * cache — the thing that makes the next build fast — is not a tag and is
+     * untouched by this.
+     */
+    private reclaimBuiltImage;
     teardown(): Promise<void>;
     /**
      * Send the execute request to the workflow runner via the exec's stdin.