@kici-dev/agent 0.4.0 → 0.6.0

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

@@ -1,5 +1,6 @@
-import type { Workflow } from '@kici-dev/sdk';
-import { type MatrixValues } from '@kici-dev/engine';
+import type { $ as Shell } from 'zx';
+import type { Workflow, RepoInfo } from '@kici-dev/sdk';
+import { type ChangedFilesStatus, type MatrixValues } from '@kici-dev/engine';
 /**
  * Result of evaluating dynamic fields on a job.
  * Only fields that were flagged as dynamic and successfully resolved are set.
@@ -14,7 +15,56 @@ export interface InitResult {
      * The orchestrator re-materializes these into N execution jobs at dispatch.
      */
     matrixValues?: MatrixValues[];
+    /**
+     * Verdict of the workflow-level `filter`, set only when the init job was asked
+     * to evaluate one (`flags.hasFilter`). `false` means the workflow does not
+     * apply and its job must not be dispatched.
+     *
+     * Optional on purpose: an agent that predates the filter never sets it, so the
+     * orchestrator reads absence as "no verdict was reported", never as "suppress".
+     */
+    filterPassed?: boolean;
+}
+/**
+ * Everything a workflow-level `filter` needs beyond the workflow module and the
+ * event. Supplied by the caller because none of it is derivable here: the source
+ * tree lives wherever the init job materialized it, and the diff is ground truth
+ * from that same clone.
+ */
+export interface FilterEvalInput {
+    /** The repo whose event triggered this evaluation. */
+    sourceRepo: RepoInfo;
+    /** The repo that registered the workflow — identical to `sourceRepo` here. */
+    workflowRepo: RepoInfo;
+    changedFiles: string[];
+    changedFilesStatus: ChangedFilesStatus;
+    env?: Record<string, string | undefined>;
+    /** zx shell handed to the filter. Defaults to the ambient `$`. */
+    $?: typeof Shell;
 }
+/**
+ * Run a workflow's `filter` and report whether the workflow applies.
+ *
+ * Shared by both agent-side evaluation sites for a same-repo workflow: the init
+ * job that gates each static job's dispatch, and the dynamic-eval job that gates
+ * whether a generator runs at all. Both must reach the same verdict from the same
+ * inputs, so neither builds the context itself.
+ *
+ * The context is built through `createFilterContext` rather than as an object
+ * literal: the factory installs `changedFiles` as a throwing getter, so a filter
+ * that reads the diff on an event that has none fails loudly instead of seeing an
+ * empty list. A `false` verdict dispatches none of the workflow's own jobs, so a
+ * silently-empty diff would suppress it on a mistake. On this same-repo path the
+ * verdict is at least recoverable — the run row exists, carrying the `__init__*`
+ * jobs, and this evaluation's own step log records the verdict; it is the
+ * organization-wide path, which runs elsewhere, that leaves nothing behind.
+ *
+ * A throwing filter propagates: the evaluating job fails, which surfaces as a
+ * failed run. "Could not decide" is never treated as "do not run" — that would
+ * be a false green, the same reasoning `buildJobRuleCompletion` applies to a rule
+ * whose `check()` threw.
+ */
+export declare function evaluateWorkflowFilter(workflow: Workflow, event: Record<string, unknown>, input: FilterEvalInput | undefined, timeoutMs: number): Promise<boolean>;
 /**
  * Evaluate dynamic fields (context, env, concurrencyGroup) on a job.
  *
@@ -26,16 +76,23 @@ export interface InitResult {
  * -: If a dynamic function returns undefined/null, the field is left undefined.
  * -: Each dynamic function call is wrapped in a timeout (default 60s).
  *
+ * A workflow-level `filter` is evaluated FIRST when `flags.hasFilter` is set. A
+ * `false` verdict returns immediately: no job of that workflow will be
+ * dispatched, so evaluating this one's dynamic fields would run customer code
+ * whose result nothing can consume.
+ *
  * @param workflow - The extracted Workflow object
  * @param jobName - Name of the job whose dynamic fields to evaluate
  * @param event - Normalized event envelope — same shape every dynamic-function call site receives.
  * @param flags - Which fields are dynamic and need evaluation
  * @param timeoutMs - Timeout per dynamic function call (default 60_000ms)
+ * @param filterInput - Source tree + diff the workflow's `filter` reads. Required when `flags.hasFilter`.
  */
 export declare function evaluateDynamicFields(workflow: Workflow, jobName: string, event: Record<string, unknown>, flags: {
     dynamicContext: boolean;
     dynamicEnv: boolean;
     dynamicConcurrencyGroup: boolean;
     dynamicMatrix?: boolean;
-}, timeoutMs?: number): Promise<InitResult>;
+    hasFilter?: boolean;
+}, timeoutMs?: number, filterInput?: FilterEvalInput): Promise<InitResult>;
 //# sourceMappingURL=init-runner.d.ts.map

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

@@ -1,7 +1,70 @@
 import type { AgentToOrchestratorMessage, JobDispatch } from '@kici-dev/engine';
+import type { LogStream } from '@kici-dev/engine';
 import type { AppConfig } from '../config.js';
+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`.
+ *
+ * An init or dynamic-eval job normally restores only `.kici/` from the cached
+ * source tarball — enough to import the workflow module, but a directory with no
+ * repo in it. A filter that reads a file or shells out against that path would
+ * get a confidently wrong answer, and `changedFiles` could not be computed at
+ * all, so a filter-bearing job clones the source repo into a sibling directory.
+ *
+ * When no tarball was attached the job already cloned the whole repo into
+ * `workDir`, and that clone is reused rather than duplicated — including the
+ * local working-tree case, where there is no repo url and `workDir` IS the tree.
+ *
+ * A tarball with no repo url is the one combination that cannot be honoured:
+ * `workDir` holds `.kici/` alone and there is nothing to clone from. Returning it
+ * would hand the filter a directory in which every path test answers "absent" —
+ * the exact silent lie this function exists to prevent — so it throws instead.
+ */
+export declare function ensureFilterSourceDir(dispatch: JobDispatch, workDir: string): Promise<string>;
+/**
+ * Build the context a non-global workflow's `filter` is evaluated against.
+ *
+ * `sourceRepo` and `workflowRepo` are the same repo — that is what "non-global"
+ * means — so both carry the same identifier, path, ref, and sha. The zx shell is
+ * rooted at the source tree and streams into the evaluating step's log, matching
+ * what the global eval round hands its own filters.
+ *
+ * They are two distinct objects all the same. Being the same repo is a fact
+ * about their VALUES, not a licence to hand the author one object under two
+ * names: a filter that mutated `ctx.sourceRepo` would silently see
+ * `ctx.workflowRepo` change with it, which happens on no other path.
+ */
+export declare function buildInitFilterInput(dispatch: JobDispatch, event: Record<string, unknown>, workDir: string, emit: (line: string, stream: LogStream) => void): Promise<FilterEvalInput>;
+/**
+ * Build the per-invocation zx `$` a global eval round hands to filters and
+ * generators, so a `await $\`…\`` inside one is visible in the eval step's log.
+ *
+ * **`env` is the LIVE `process.env` reference, never a spread.** A spread is a
+ * snapshot taken when the shell is built, which is before the round applies the
+ * seven `KICI_*` keys — so a filter that shells out (`$\`printenv
+ * KICI_SOURCE_REPO_PATH\``, or any subprocess inheriting env) would see nothing
+ * here while the sandbox re-evaluation's ambient `$` resolves `process.env`
+ * after `setupGlobalWorkflowEnv` has run and does see them. That is the same
+ * two-worlds determinism failure the cwd choice below exists to prevent, one
+ * layer down. Passing the live reference reproduces the ambient `$`'s own
+ * behaviour, which is what the sandbox uses.
+ *
+ * `verbose: true` + `makeStreamingZxLog` honors a per-call `quiet: true`, so a
+ * decrypted secret never leaks into the log.
+ *
+ * `emit` is a callback rather than the `LogStreamer` itself so the caller can
+ * route it through its own closed-guard: `LogStreamer.destroy()` sets no closed
+ * flag and `addLine` buffers unconditionally, so a subprocess line arriving
+ * after the step was reported would otherwise emit a `log.chunk` for a terminal
+ * step. That is the likeliest path for it — an orphaned candidate is usually
+ * orphaned *because* it is waiting on a subprocess.
+ */
+export declare function buildEvalShell(cwd: string, emit: (line: string, stream: LogStream) => void): Promise<typeof Shell>;
 /**
  * Dependencies injected into JobRunner.
  */
@@ -10,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>;
@@ -182,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?;
@@ -190,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.
@@ -198,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.
@@ -276,6 +374,18 @@ export declare class JobRunner {
      * uncommitted changes).
      */
     private cloneAndApplyOverlay;
+    /**
+     * Materialize the init job's workflow source into `workDir`. A test run ships
+     * its full working tree as an encrypted overlay tarball (`fullRepo`) rather
+     * than a git repo, so skip the clone and let the overlay populate the
+     * workspace — the same handling the normal execution-job path uses. Otherwise
+     * restore from the cached tarball if present, else clone. In every case, apply
+     * an attached overlay tarball afterward (test runs with uncommitted changes;
+     * for a fullRepo run this is what actually populates the workspace, so the
+     * init job resolves a dynamic context against the real source tree instead of
+     * an empty directory).
+     */
+    private materializeInitJobSource;
     /**
      * Phase 2 of build: install dependencies locally if needed for the build,
      * and (when the orchestrator has flagged the dep cache as stale) pack
@@ -288,6 +398,30 @@ export declare class JobRunner {
      * it to the source cache.
      */
     private packAndUploadSource;
+    /**
+     * Clone both repos for a global eval round and materialize the workflow
+     * repo's dependencies, mirroring the sandbox's own dual-clone: the workflow
+     * repo under `<workDir>/workflow`, the source repo under `<workDir>/source`.
+     *
+     * `.kici/` lives in the WORKFLOW repo for a global workflow, so deps and the
+     * scratch-dir git exclude both apply to that checkout, never the source one.
+     */
+    private checkoutForGlobalEvalRound;
+    /**
+     * Handle a pre-run global eval round.
+     *
+     * The round runs once per (event × workflow repo) BEFORE any run row exists:
+     * it checks out the workflow repo and the source repo, then runs each
+     * candidate global workflow's `filter` and — for a survivor — its
+     * `DynamicJobFn`s, so the orchestrator learns which workflows apply to this
+     * source repo and which jobs each one generates.
+     *
+     * A candidate that fails is reported indeterminate inside the result, not as
+     * a job failure: the round carries several unrelated org-wide workflows, and
+     * one broken filter must not suppress the rest. The job itself fails only
+     * when the checkout or the round machinery breaks.
+     */
+    private handleGlobalEvalRound;
     /**
      * Handle an init-only job.
      *
@@ -309,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.

package/dist/execution/sandbox/fork-runner.d.ts

@@ -9,6 +9,21 @@ import { type ChildProcess } from 'node:child_process';
 import type { JobDispatch } from '@kici-dev/engine';
 import type { JobExecutionOptions, JobExecutionResult } from './types.js';
 import type { JobExecutionRequest } from './ipc-protocol.js';
+/**
+ * Best-effort SIGKILL/SIGTERM of an entire process group led by `pid`.
+ * `process.kill(-pid, signal)` targets the group whose leader is `pid` (the
+ * child was spawned `detached`, so its pid is its group id). Returns 1 when the
+ * group was signalled, 0 when it was already gone (ESRCH) or the pid is invalid.
+ * We cannot cheaply count members, so the caller treats a non-zero return as
+ * "reap attempted".
+ */
+export declare function killProcessGroup(pid: number | undefined, signal: NodeJS.Signals): number;
+/**
+ * SIGTERM the job's process group, wait a short grace, then SIGKILL. No-op
+ * (returns 0) when the child was not spawned detached or has no pid. Returns the
+ * count of reap attempts that signalled a live group (0, 1, or 2).
+ */
+export declare function reapGroup(pid: number | undefined, detached: boolean, killFn?: (p: number | undefined, s: NodeJS.Signals) => number, sleepMs?: number): Promise<number>;
 /** Options for creating a fork-based runner. */
 interface ForkRunnerOptions {
     /** Absolute path to the compiled workflow-runner.js. */
@@ -39,6 +54,18 @@ interface ForkRunnerOptions {
      * Defaults to 30_000 (30 seconds).
      */
     maxGracePeriodMs?: number;
+    /**
+     * Spawn the runner child `detached` so it leads its own process group. Set by
+     * the bare-metal backend when orphan cleanup is on and bwrap is off, so the
+     * between-jobs phase can reap a backgrounded daemon that reparented to init.
+     * Ignored under bwrap (its PID namespace already contains the tree).
+     */
+    detachProcessGroup?: boolean;
+    /**
+     * Between-jobs out-of-band cleanup re-run: the runner reuses the preserved
+     * workdir and runs only the job's declared cleanup / onFailure hooks.
+     */
+    cleanupOnly?: boolean;
 }
 /** State of a running fork-based child process. */
 export interface ForkRunnerHandle {
@@ -59,13 +86,40 @@ export interface ForkRunnerHandle {
      *                      Capped by the agent's maxGracePeriodMs.
      */
     cancel: (force: boolean, gracePeriodMs?: number) => void;
+    /**
+     * Whether this runner leads its own detached process group (bare-metal,
+     * non-bwrap, orphan cleanup on). Drives whether `reap()` does anything.
+     */
+    detached: boolean;
+    /**
+     * True once the runner emitted `completion-hooks-done` (its onSuccess /
+     * onFailure / cleanup hooks ran). Stays false when the child exits before
+     * signalling, which is the between-jobs phase's cue to re-run declared
+     * cleanup out-of-band.
+     */
+    completionHooksRan: boolean;
+    /**
+     * True once the runner reported (via `hooks-declared`) that the job declares
+     * an `onFailure` / `cleanup` hook. Recorded early so it survives a later hard
+     * kill; gates whether the out-of-band cleanup re-run is attempted.
+     */
+    declaresCleanup: boolean;
+    /**
+     * SIGTERM → grace → SIGKILL the runner's process group, reaping any daemon it
+     * backgrounded. No-op (resolves 0) when the runner is not detached; returns
+     * the number of reap attempts that signalled a live group.
+     */
+    reap: () => Promise<number>;
 }
 /**
  * Build a JobExecutionRequest from a JobDispatch.
  *
  * Maps orchestrator dispatch fields to the subset needed by the workflow runner.
  */
-export declare function buildRequest(dispatch: JobDispatch, workDir: string): JobExecutionRequest;
+export declare function buildRequest(dispatch: JobDispatch, workDir: string, extra?: {
+    cleanupOnly?: boolean;
+    credentialHelperPath?: string;
+}): JobExecutionRequest;
 /**
  * Build bubblewrap (bwrap) arguments for namespace isolation.
  *

package/dist/execution/sandbox/image-preflight.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fail a container job on an unusable image BEFORE the job starts.
+ *
+ * KiCI injects its own runtime (a pinned official glibc-2.17 Node) into the
+ * customer's image, so the image needs only a glibc and a shell. When it has
+ * neither, the container runtime's own error is close to useless — a musl image
+ * reports
+ *
+ *   exec container process (missing dynamic library?) `/opt/kici/node/bin/node`:
+ *   No such file or directory
+ *
+ * which names a file that plainly exists and says nothing about musl. The
+ * preflight turns that into a sentence an author can act on, and it fires
+ * before any step runs rather than partway through a job.
+ *
+ * glibc-only is the deliberate scope of this version; a musl runtime variant is
+ * a documented follow-up.
+ */
+import type Docker from 'dockerode';
+/** What an image's rootfs says about whether we can run our runtime in it. */
+export type ImageLibc = 'glibc' | 'musl' | 'static' | 'no-shell';
+/** Every path the preflight stats in the image. */
+export declare const PROBE_PATHS: readonly string[];
+/**
+ * Classify an image from the subset of {@link PROBE_PATHS} that exist in it.
+ *
+ * Pure, so the decision table is testable without a container runtime.
+ */
+export declare function classifyImageLibc(presentPaths: readonly string[]): ImageLibc;
+/**
+ * Throw unless `image` can host the injected runtime.
+ *
+ * Stats the probe paths through a created-but-never-started container, so a
+ * shell-less or musl image is diagnosed without executing anything in it —
+ * running a probe command would fail for the very reason we are testing for.
+ */
+export declare function assertImageRunnable(docker: Docker, image: string): Promise<void>;
+//# sourceMappingURL=image-preflight.d.ts.map