@kici-dev/agent 0.1.27 → 0.2.0

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

@@ -13,12 +13,15 @@
  * This file is compiled alongside the agent by rolldown (existing build), but
  * runs as a SEPARATE process spawned by the sandbox backend.
  */
+import { $ } from 'zx';
+import { type TempScope } from '@kici-dev/core/tmp';
 import { ExecutionJobStatus } from '@kici-dev/engine';
-import type { StepContext } from '@kici-dev/sdk';
-import type { NeedsContext, FanoutPosition } from '@kici-dev/sdk';
+import type { Step, StepInput, StepContext } from '@kici-dev/sdk';
+import type { NeedsContext, FanoutPosition, EventDefinition } from '@kici-dev/sdk';
 import type { OutputsMap, StepRefMap, TrackedStepSecrets } from '@kici-dev/sdk';
 import type { RunnerToAgentMessage, JobExecutionRequest } from './ipc-protocol.js';
 import { LogMasker } from './log-masker.js';
+import { type RuleEvaluationResult } from '../rule-evaluator.js';
 /**
  * Build `ctx.needs` for a job's steps from the dispatch envelope. Reconstructs
  * an {@link UpstreamSnapshot} from `upstreamJobOutputs` (flat per single job;
@@ -28,6 +31,62 @@ import { LogMasker } from './log-masker.js';
  * undefined when the job declares no needs.
  */
 export declare function buildStepNeedsContext(declaredNeeds: readonly unknown[] | undefined, upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined, upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined): NeedsContext | undefined;
+/**
+ * Build a fresh zx `$` shell bound to the sandbox working directory and the
+ * sanitized environment (process.env was set by the parent via env-sanitizer
+ * before spawning this process). This is the single shell-construction code
+ * path shared by step execution (`createSandboxStepContext`) and the per-job
+ * init phase (`runInitPhase`), so init commands run through the identical shell
+ * steps use — same cwd, same live sanitized env, same masked log streaming.
+ *
+ * The shell binds `process.env` by reference (not a copy), so a same-step
+ * ctx.setEnv / ctx.addPath mutation — which applyEnvDelta writes to live
+ * process.env — is visible to that step's own subprocesses, matching the
+ * "visible to this step" SDK contract.
+ *
+ * Intercept zx subprocess output via the log callback: zx does NOT write child
+ * stdout/stderr to process.stdout — it pipes to an internal VoidStream and only
+ * calls $.log() with { kind: 'stdout'|'stderr', verbose }. We override the log
+ * function (`makeStreamingZxLog`) to capture both kinds and send them as masked
+ * IPC log.line messages tagged with `stepIndex`.
+ *
+ * The shell is built with `verbose: true` so ordinary subprocess output is
+ * flagged `verbose: true` (captured) while a step that opts into
+ * `$({ quiet: true })` — e.g. a `sops -d` credential decrypt — is flagged
+ * `verbose: false` and dropped by `makeStreamingZxLog`. That gate is what keeps
+ * a decrypted secret out of the streamed run log; a `verbose: false` base would
+ * flag ordinary output `verbose: false` too and drop every line.
+ *
+ * IMPORTANT: The log function must be passed in the zx$() config, not set on the
+ * returned function. zx$() returns a plain function (not the proxy $), so setting
+ * step$.log would only set it on the function object and NOT propagate to the
+ * AsyncLocalStorage store that zx uses for ProcessPromise snapshots.
+ */
+export declare function buildSandboxShell(cwd: string, stepIndex: number, maskedSendFn: (msg: RunnerToAgentMessage) => void): typeof $;
+/**
+ * Resolve the on-the-wire event name for `ctx.emit`. Accepts either an ad-hoc
+ * event-name string or a `defineEvent()` definition object (passed by the typed
+ * emit overload); a definition resolves to its `.name`, a string passes through.
+ */
+export declare function resolveEmitEventName(nameOrDefinition: string | EventDefinition): string;
+/**
+ * Sanitize a raw identifier into a valid temp label: lowercase, every
+ * non-`[a-z0-9-]` char to `-`, falling back to `'step'` when the result is
+ * empty. Applied to both the caller-supplied `ctx.mktemp(label)` and the
+ * default step-id label so a friendly-but-irregular label never rejects at the
+ * scope. Mirrors the SDK test builder's `sanitizeTempLabel`.
+ */
+export declare function sanitizeTempLabel(raw: string): string;
+/**
+ * Drain the job-scoped temp allocator once at job end.
+ *
+ * Called after the step loop and cancel-path hooks, immediately before the
+ * terminal `job.complete` emit, so a single call reclaims every `ctx.mktemp` /
+ * `ctx.mktempFile` allocation on success, failure, and cancel/timeout alike. A
+ * cleanup failure must NEVER change the job's terminal status, so any error is
+ * swallowed into `warn` rather than thrown out of `main()`.
+ */
+export declare function drainJobTempScope(scope: TempScope, warn: (message: string) => void): Promise<void>;
 /**
  * Create a StepContext natively inside the workflow runner.
  *
@@ -35,7 +94,7 @@ export declare function buildStepNeedsContext(declaredNeeds: readonly unknown[]
  * NOT serialized across the process boundary. This means zx $ runs natively
  * inside this process with full shell access.
  */
-export declare function createSandboxStepContext(workDir: string, stepIndex: number, stepName: string, request: JobExecutionRequest, maskedSendFn: (msg: RunnerToAgentMessage) => void, outputsMap: OutputsMap, refMap: StepRefMap, operatorSecretKeys: Set<string>, secretOutputs: Map<string, string>, jobOutputsMap: OutputsMap, secrets: TrackedStepSecrets, masker: LogMasker, signal: AbortSignal): StepContext;
+export declare function createSandboxStepContext(workDir: string, stepIndex: number, stepName: string, request: JobExecutionRequest, maskedSendFn: (msg: RunnerToAgentMessage) => void, outputsMap: OutputsMap, refMap: StepRefMap, operatorSecretKeys: Set<string>, secretOutputs: Map<string, string>, jobOutputsMap: OutputsMap, secrets: TrackedStepSecrets, masker: LogMasker, signal: AbortSignal, jobTempScope: TempScope): StepContext;
 /**
  * Derive the fan-out position (`ctx.fanout`) from a dispatch request. Returns
  * `undefined` for a non-fan-out job (no `fanoutTotal`), so `ctx.fanout` is only
@@ -44,12 +103,59 @@ export declare function createSandboxStepContext(workDir: string, stepIndex: num
 export declare function deriveFanout(request: JobExecutionRequest): FanoutPosition | undefined;
 /** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
 export declare function rawPayloadFromEvent(event: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+/**
+ * Mutable state threaded through {@link coerceStep} for one job normalization
+ * pass: the shared `step-N` counter, the bare-function → name ref map, and the
+ * set of step objects this pass has already auto-named.
+ */
+export interface CoerceState {
+    counter: number;
+    refMap: StepRefMap;
+    autoNamed: WeakSet<object>;
+}
+/**
+ * Coerce one raw entry (bare function or Step) into a normalized Step, naming
+ * anonymous steps `step-N` with a counter shared across the whole flattened
+ * sequence (parallel children inline) — matching the compiler's transformSteps
+ * enumeration so the flat-stepIndex invariant holds agent ↔ orchestrator.
+ *
+ * Unnamed steps are named by MUTATING the original object so the SDK's
+ * late-bound `.result` proxy (which reads `step.name` at access time) resolves.
+ * A step object reused twice in one pass gets a clone with a fresh name on the
+ * repeat encounter — mirroring the compiler's per-occurrence naming so lock
+ * parity holds; the original keeps its first binding.
+ */
+export declare function coerceStep(stepOrFn: StepInput, state: CoerceState): Step<any>;
+/**
+ * Resolve `event.changedFiles` for rule evaluation before job/step rules run.
+ * Ground truth is the agent's own clone (`computeChangedFiles`); the
+ * orchestrator's already-fetched list (status `'fetched'`) is a free fast-path.
+ * Only runs when a rule could read `ctx.changedFiles` — rule-less jobs skip the
+ * git cost. Diff-less events (schedule/tag/manual) resolve to `'unavailable'`.
+ */
+export declare function resolveChangedFilesForRules(request: JobExecutionRequest, workDir: string, hasRules: boolean): Promise<void>;
+/**
+ * Decide the terminal `job.complete` for job-level rule evaluation, or `null`
+ * when the job should proceed to step execution.
+ *
+ * - `allPassed` → `null` (run the steps).
+ * - a rule's `check()` **threw** (`evaluationError`) → FAIL: the gate could not
+ *   be evaluated, so treating "couldn't decide" as "don't run" would be a false
+ *   green. Report `status: failed` with the error surfaced.
+ * - a rule cleanly returned `false` → clean skip: `status: success` with every
+ *   step marked skipped (a gate that evaluated and said "don't run").
+ *
+ * Pure and exported so the decision is unit-testable without `process.exit`.
+ */
+export declare function buildJobRuleCompletion(ruleResult: RuleEvaluationResult, normalizedSteps: Step[]): (RunnerToAgentMessage & {
+    type: 'job.complete';
+}) | null;
 /**
  * Build the step loop's KICI_ENV/KICI_PATH callbacks with a per-step delta-file
  * pair (keyed by step index). `beforeStepEnvFiles(stepIndex)` lazily creates the
  * step's pair and points the runner's process.env at it (each step's zx $
- * snapshots process.env at context creation, which happens AFTER this
- * before-hook, so the shell sees them; the pre-fork env allowlist does not
+ * reads live process.env at spawn, which happens AFTER this before-hook, so
+ * the shell sees them; the pre-fork env allowlist does not
  * re-filter runtime-set vars). `afterStepApplyEnvFiles(stepIndex)` applies that
  * step's delta and releases the pair.
  *

package/dist/execution/streaming-zx-log.d.ts

@@ -1,3 +1,4 @@
+import { LogStream } from '@kici-dev/engine';
 /**
  * Shared factory for the zx `log` callback that streams a subprocess's
  * stdout/stderr into the captured/streamed run log, line by line, via `emit`.
@@ -23,8 +24,15 @@
  * `verbose: false` (suppressed). A `verbose: false` base would flag ordinary
  * output `verbose: false` too, and this gate would then drop every line.
  *
- * The returned callback owns a per-shell line buffer, so partial chunks are
- * coalesced into whole lines before `emit` is called.
+ * The returned callback owns one line buffer PER STREAM, so partial chunks are
+ * coalesced into whole lines before `emit` is called. The buffers are separate
+ * because the two streams are independent pipes: a stdout chunk ending mid-line
+ * and a stderr chunk arriving next would otherwise concatenate into a single
+ * spliced line attributed to whichever kind completed it.
+ *
+ * `emit` receives the originating stream alongside the line so a diagnostic
+ * written to stderr stays distinguishable from ordinary progress output all the
+ * way to the persisted run log.
  */
-export declare function makeStreamingZxLog(emit: (line: string) => void): (entry: unknown) => void;
+export declare function makeStreamingZxLog(emit: (line: string, stream: LogStream) => void): (entry: unknown) => void;
 //# sourceMappingURL=streaming-zx-log.d.ts.map

package/dist/execution/tmp-gc.d.ts

@@ -1,17 +1,32 @@
 /**
  * Startup garbage collection for this agent's own temp-directory families.
  *
- * Job workdirs (`kici-<6 random chars>`, see job-runner.ts) and isolated
- * pnpm stores (`kici-pnpm-store-*`, see dep-installer.ts) clean themselves
- * up in `finally` blocks — but a hard process death (SIGKILL, OOM kill)
- * skips those, and on a long-lived bare-metal agent the leftovers then
- * accumulate forever. Collecting anything older than a day at startup is
- * safe on shared hosts: no job lives remotely that long (job timeouts are
- * minutes), so a concurrent agent's in-flight dirs are never eligible.
+ * Bare job workdirs (`kici-<6 random chars>`, see job-runner.ts), labeled
+ * allocator dirs (`kici-<label>-<6 random chars>`, minted by the global temp
+ * allocator `@kici-dev/core/tmp`, which guarantees every allocation carries
+ * the `kici-` prefix), and isolated pnpm stores (`kici-pnpm-store-*`, see
+ * dep-installer.ts) clean themselves up in `finally` blocks — but a hard
+ * process death (SIGKILL, OOM kill) skips those, and on a long-lived
+ * bare-metal agent the leftovers then accumulate forever. Collecting anything
+ * older than a day at startup is safe on shared hosts: no job lives remotely
+ * that long (job timeouts are minutes), so a concurrent agent's in-flight
+ * dirs are never eligible.
+ *
+ * The deterministic persistent caches (`kici-agent-payloads`, `kici-data`,
+ * `kici-scaler-ledger`) also live directly under the temp root and can be far
+ * older than a day, so they are explicitly excluded — `kici-scaler-ledger`
+ * even structurally matches the allocator pattern (`ledger` is a 6-char label
+ * suffix), which a regex alone cannot distinguish.
  */
 /**
  * Collect this agent's stale temp dirs. `base` is overridable for tests;
  * production callers use the default temp root. Never throws.
+ *
+ * The default base is `kiciTmpBase()`, not the OS temp root, so it scans the
+ * exact directory the agent now writes payloads/clones/pnpm stores into: the
+ * global temp allocator and the payload cache both honor `KICI_TMPDIR` via the
+ * same helper. If the GC scanned a different root, stale-temp reaping would
+ * silently stop working whenever `KICI_TMPDIR` is set.
  */
 export declare function gcStaleAgentTmpDirs(base?: string): Promise<string[]>;
 //# sourceMappingURL=tmp-gc.d.ts.map

package/dist/execution/workflow-loader.d.ts

@@ -6,7 +6,37 @@
  * no Rolldown step at runtime. `@kici-dev/sdk` and host-repo deps resolve via
  * Node's normal ESM lookup against `.kici/node_modules/`.
  */
-import type { Workflow, StepInput, DynamicJobFn } from '@kici-dev/sdk';
+import type { Workflow, StepInput, DynamicJobFn, OutputsMap, StepRefMap } from '@kici-dev/sdk';
+/**
+ * SDK output-map setters resolved from a specific `@kici-dev/sdk` instance.
+ * The agent uses these to wire the workflow module's OWN SDK copy (a different
+ * physical module than the agent's bundled SDK) to the same output maps the
+ * step loop mutates, so within-job `.result` proxies — which read that copy's
+ * module-global `_stepOutputsMap` — resolve at access time.
+ */
+export interface SdkOutputSetters {
+    setStepOutputsMap: (map: OutputsMap) => void;
+    setStepRefMap: (map: StepRefMap) => void;
+    setJobOutputsMap: (map: OutputsMap) => void;
+}
+/**
+ * Resolve the `@kici-dev/sdk` instance the workflow module itself imports.
+ *
+ * The workflow's `.result` proxies read the module-global step-outputs map of
+ * whichever SDK copy the workflow file resolves — which is generally a
+ * different physical module than the agent's bundled SDK (the workflow is
+ * imported from the cloned source tree and resolves its deps against that
+ * tree's `node_modules`). Resolving via `createRequire(workflowFilePath)` walks
+ * `node_modules` from the workflow file exactly the way the workflow's own
+ * `import '@kici-dev/sdk'` does — including any hoisted copy — so the returned
+ * setters mutate the SAME module-global map object the proxies read. Node caches
+ * ESM modules by resolved URL, so importing that path yields the workflow's live
+ * singleton, not a fresh copy.
+ *
+ * Falls back to the agent's bundled setters when resolution fails (mirrors
+ * `resolveSdkSetters` in the compiler's test runner).
+ */
+export declare function resolveWorkflowSdkSetters(workflowFilePath: string): Promise<SdkOutputSetters>;
 /**
  * Compile schema version — must match `@kici-dev/compiler` lockfile/hasher.ts.
  * Mixed into the content hash so compilation-approach changes produce different
@@ -33,6 +63,7 @@ export declare function ensureLoaderHookRegistered(): void;
  */
 export declare function loadWorkflowSource(workDir: string, sourceFile: string, expectedContentHash?: string, resolvedHashFiles?: string[]): Promise<{
     module: Record<string, unknown>;
+    sdkSetters: SdkOutputSetters;
 }>;
 /**
  * Extract a workflow by name from a module's exports.

package/dist/index.js

@@ -5,7 +5,8 @@ import { z } from "zod";
 import { LOGGER_ENV_VARS, defineEnv, validateUnknownKiciVars } from "@kici-dev/shared/env";
 import { KNOWN_ROLES, parseHostPropertyAssignments, validateNoReservedLabels } from "@kici-dev/engine";
 import { execFile } from "node:child_process";
-import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { access, cp, lstat, mkdir, readFile, readdir, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { makeTempDir } from "@kici-dev/core/tmp";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { createLogger, sha256, toErrorMessage } from "@kici-dev/shared";
@@ -15,6 +16,7 @@ import { parse, stringify } from "yaml";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
+import { HOME_ANCHOR, REPO_ANCHOR } from "@kici-dev/core";
 import { c, x } from "tar";
 import https from "node:https";
 import http from "node:http";
@@ -85,10 +87,18 @@ const envDef = defineEnv({
 		dockerKeepFailed: z.string().default("false").transform((s) => s === "true"),
 		jobHeartbeatIntervalMs: z.coerce.number().default(6e4),
 		backpressureMode: z.enum(["pause", "drop"]).default("pause"),
+		agentPayloadDir: z.string().optional(),
+		agentCommand: z.string().optional(),
 		sandbox: z.string().default("false").transform((s) => s === "true"),
 		trustedEnv: z.string().default("false").transform((s) => s === "true"),
 		inPlace: z.string().default("false").transform((s) => s === "true"),
 		sandboxNetwork: z.enum(["isolated", "host"]).default("isolated"),
+		sandboxHardened: z.string().default("true").transform((s) => s !== "false"),
+		sandboxReadonlyRootfs: z.string().default("false").transform((s) => s === "true"),
+		sandboxUser: z.string().optional(),
+		sandboxPidsLimit: z.coerce.number().int().positive().default(512),
+		sandboxMemoryBytes: z.coerce.number().int().positive().default(2 * 1024 * 1024 * 1024),
+		sandboxNanoCpus: z.coerce.number().int().positive().default(2 * 1e9),
 		scalerManaged: z.string().optional().transform((s) => s === "1"),
 		scalerIdleTimeoutMs: z.coerce.number().default(5e3),
 		scalerPendingDispatchTimeoutMs: z.coerce.number().default(6e4),
@@ -113,10 +123,18 @@ const envDef = defineEnv({
 		dockerKeepFailed: "KICI_DOCKER_KEEP_FAILED",
 		jobHeartbeatIntervalMs: "KICI_JOB_HEARTBEAT_INTERVAL_MS",
 		backpressureMode: "KICI_BACKPRESSURE_MODE",
+		agentPayloadDir: "KICI_AGENT_PAYLOAD_DIR",
+		agentCommand: "KICI_AGENT_COMMAND",
 		sandbox: "KICI_SANDBOX",
 		trustedEnv: "KICI_TRUSTED_ENV",
 		inPlace: "KICI_IN_PLACE",
 		sandboxNetwork: "KICI_SANDBOX_NETWORK",
+		sandboxHardened: "KICI_SANDBOX_HARDENED",
+		sandboxReadonlyRootfs: "KICI_SANDBOX_READONLY_ROOTFS",
+		sandboxUser: "KICI_SANDBOX_USER",
+		sandboxPidsLimit: "KICI_SANDBOX_PIDS_LIMIT",
+		sandboxMemoryBytes: "KICI_SANDBOX_MEMORY_BYTES",
+		sandboxNanoCpus: "KICI_SANDBOX_NANO_CPUS",
 		scalerManaged: "KICI_SCALER_MANAGED",
 		scalerIdleTimeoutMs: "KICI_SCALER_IDLE_TIMEOUT",
 		scalerPendingDispatchTimeoutMs: "KICI_SCALER_PENDING_DISPATCH_TIMEOUT",
@@ -146,7 +164,13 @@ const envDef = defineEnv({
 * - KICI_SANDBOX (default: false) — enable bubblewrap (bwrap) namespace isolation for bare-metal execution
 * - KICI_TRUSTED_ENV (default: false) — trusted fleet-agent profile: pass the ambient host env (minus the agent's own KiCI identity secrets) through to steps
 * - KICI_IN_PLACE (default: false) — in-place no-clone profile: for a file:// source, use the real repo path as workDir and skip the clone (the routed deploy:stg profile)
-* - KICI_SANDBOX_NETWORK (default: isolated, options: isolated | host) — when sandbox=true, controls bwrap network namespace
+* - KICI_SANDBOX_NETWORK (default: isolated, options: isolated | host) — sandbox network posture for BOTH backends: the bwrap network namespace (when sandbox=true) and the container job network. `host` shares the host network (container backend also binds host /etc/hosts read-only for name resolution); applies to the container backend under the default hardened posture (KICI_SANDBOX_HARDENED=true)
+* - KICI_SANDBOX_HARDENED (default: true) — hardened-by-default job containers (CapDrop ALL, no-new-privileges, cgroup caps, tmpfs /tmp); set false to roll back to the legacy unhardened posture
+* - KICI_SANDBOX_READONLY_ROOTFS (default: false) — opt-in read-only container rootfs (/tmp stays a writable tmpfs)
+* - KICI_SANDBOX_USER (optional) — container user override (uid, uid:gid, or name); honors the image user when unset
+* - KICI_SANDBOX_PIDS_LIMIT (default: 512) — max PIDs in the job container cgroup
+* - KICI_SANDBOX_MEMORY_BYTES (default: 2 GiB) — memory cap in bytes for the job container cgroup
+* - KICI_SANDBOX_NANO_CPUS (default: 2 CPUs) — CPU cap in nano-CPUs for the job container cgroup
 * - KICI_SCALER_MANAGED (set to "1" by the orchestrator's auto-scaler — agent self-shuts down on idle)
 * - KICI_SCALER_IDLE_TIMEOUT (ms, default 5000) — how long a scaler-managed agent waits before shutdown after going idle
 * - KICI_SCALER_PENDING_DISPATCH_TIMEOUT (ms, default 60000) — extended idle window when register.ack signals a queued bound job
@@ -155,7 +179,7 @@ const envDef = defineEnv({
 */
 function loadConfig() {
 	const data = envDef.parse();
-	if (!data.scalerManaged) validateNoReservedLabels(data.labels, "KICI_LABELS");
+	if (!data.scalerManaged && !data.agentToken) validateNoReservedLabels(data.labels, "KICI_LABELS");
 	validateUnknownKiciVars([...envDef.listKnownEnvVars(), ...LOGGER_ENV_VARS]);
 	return {
 		...data,
@@ -364,7 +388,7 @@ async function applyYarnrcBerryConfig(args) {
 	const hasPrivateRegistry = registries.length > 0 || Object.keys(installEnvSecrets).length > 0;
 	const yarnrcPath = join(args.kiciDir, ".yarnrc.yml");
 	const { raw: original, doc } = await readOriginalYarnrc(yarnrcPath);
-	const cacheFolder = await mkdtemp(join(tmpdir(), "kici-yarn-berry-cache-"));
+	const { path: cacheFolder, cleanup: cleanupCache } = await makeTempDir("yarn-berry-cache");
 	const merged = {
 		...doc,
 		nodeLinker: "node-modules",
@@ -401,10 +425,7 @@ async function applyYarnrcBerryConfig(args) {
 			if (original === null) await unlink(yarnrcPath).catch(() => {});
 			else await writeFile(yarnrcPath, original, { encoding: "utf8" });
 		} catch {}
-		await rm(cacheFolder, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanupCache().catch(() => {});
 	};
 	return {
 		extraEnv: {
@@ -756,9 +777,9 @@ async function detectKiciYarnFlavor(repoRoot, kiciDir) {
 * Install `.kici/` dependencies inline with the repo's package manager.
 *
 * Falls back to this when the dep cache is unavailable or a download fails.
-* The install runs with an isolated cache/store directory (created in
-* `os.tmpdir()`) to prevent cache poisoning between build jobs; the directory
-* is removed after installation.
+* The install runs with an isolated cache/store directory (allocated under the
+* global temp base, which honors `KICI_TMPDIR`) to prevent cache poisoning
+* 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`,
@@ -847,7 +868,7 @@ function envWithNodeOnPath(extraEnv, nodeDir) {
 /** Run `npm install` in `.kici/` with an isolated cache directory. */
 async function runNpmInstall(args) {
 	const { npmCliPath, nodeExe, nodeDir } = resolveNpm();
-	const cacheDir = await mkdtemp(join(tmpdir(), "kici-npm-cache-"));
+	const { path: cacheDir, cleanup } = await makeTempDir("npm-cache");
 	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
 	const buildArgs = (...prefix) => {
 		const a = [
@@ -872,10 +893,7 @@ async function runNpmInstall(args) {
 			maxBuffer: INSTALL_MAX_BUFFER
 		});
 	} finally {
-		await rm(cacheDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanup().catch(() => {});
 	}
 }
 /**
@@ -889,7 +907,7 @@ async function runNpmInstall(args) {
 async function runPnpmInstall(args) {
 	await assertPnpmAvailable();
 	const { nodeDir } = resolveNpm();
-	const storeDir = await mkdtemp(join(tmpdir(), "kici-pnpm-store-"));
+	const { path: storeDir, cleanup } = await makeTempDir("pnpm-store");
 	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
 	const argv = [
 		"install",
@@ -909,10 +927,7 @@ async function runPnpmInstall(args) {
 			maxBuffer: INSTALL_MAX_BUFFER
 		});
 	} finally {
-		await rm(storeDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanup().catch(() => {});
 	}
 }
 /** Pure: argv for `yarn install` with an isolated cache folder. */
@@ -938,7 +953,7 @@ function buildYarnInstallArgs(cacheDir, hasPrivateRegistry) {
 async function runYarnInstall(args) {
 	await assertYarnAvailable();
 	const { nodeDir } = resolveNpm();
-	const cacheDir = await mkdtemp(join(tmpdir(), "kici-yarn-cache-"));
+	const { path: cacheDir, cleanup } = await makeTempDir("yarn-cache");
 	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
 	const argv = buildYarnInstallArgs(cacheDir, args.hasPrivateRegistry);
 	try {
@@ -950,10 +965,7 @@ async function runYarnInstall(args) {
 			maxBuffer: INSTALL_MAX_BUFFER
 		});
 	} finally {
-		await rm(cacheDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
+		await cleanup().catch(() => {});
 	}
 }
 /** Pure: argv for a berry `yarn install`. Cache + linker live in .yarnrc.yml. */
@@ -1224,10 +1236,6 @@ var init_download = __esmMin((() => {
 const logger = createLogger({ prefix: "cache-engine" });
 /** Download timeout for a presigned cache GET: 5 minutes. */
 const DOWNLOAD_TIMEOUT_MS = 300 * 1e3;
-/** Anchor prefix for repo-root-relative cache entries inside the tar. */
-const REPO_ANCHOR = "__repo__";
-/** Anchor prefix for home-relative (`~`) cache entries inside the tar. */
-const HOME_ANCHOR = "__home__";
 /**
 * Resolve a cache path. `~`-prefixed -> home root; otherwise repo-root-relative.
 * Rejects absolute paths and `..` escapes so a workflow cannot read or clobber
@@ -1268,7 +1276,7 @@ function anchorEntries(workDir, paths, roots) {
 */
 async function packCachePaths(workDir, paths, roots) {
 	const entries = anchorEntries(workDir, paths, roots);
-	const staging = await mkdtemp(join(tmpdir(), "kici-cache-pack-"));
+	const { path: staging, cleanup } = await makeTempDir("cache-pack");
 	try {
 		const topLevel = /* @__PURE__ */ new Set();
 		for (const e of entries) {
@@ -1299,10 +1307,7 @@ async function packCachePaths(workDir, paths, roots) {
 			hash
 		};
 	} finally {
-		await rm(staging, {
-			recursive: true,
-			force: true
-		});
+		await cleanup();
 	}
 }
 /** Move the extracted `__repo__` / `__home__` groups from a scratch dir into place. */
@@ -1333,7 +1338,7 @@ async function extractCacheTarball(tarball, workDir, expectedHash, roots) {
 	if (actual !== expectedHash) throw new Error(`Cache tarball checksum mismatch: expected ${expectedHash}, got ${actual}`);
 	const home = roots?.home ?? homedir();
 	await mkdir(workDir, { recursive: true });
-	const scratch = await mkdtemp(join(tmpdir(), "kici-cache-extract-"));
+	const { path: scratch, cleanup } = await makeTempDir("cache-extract");
 	try {
 		await new Promise((res, rej) => {
 			Readable.from(tarball).pipe(x({
@@ -1343,10 +1348,7 @@ async function extractCacheTarball(tarball, workDir, expectedHash, roots) {
 		});
 		await moveAnchoredGroups(scratch, workDir, home);
 	} finally {
-		await rm(scratch, {
-			recursive: true,
-			force: true
-		});
+		await cleanup();
 	}
 }
 /**
@@ -1365,17 +1367,14 @@ async function downloadAndExtractCache(url, workDir, expectedHash, roots) {
 		cb(null, chunk);
 	} });
 	await mkdir(workDir, { recursive: true });
-	const scratch = await mkdtemp(join(tmpdir(), "kici-cache-extract-"));
+	const { path: scratch, cleanup } = await makeTempDir("cache-extract");
 	try {
 		await pipeline(Readable.fromWeb(response.body), hashTransform, createGunzip(), x({ cwd: scratch }));
 		const digest = hash.digest("hex");
 		if (digest !== expectedHash) throw new Error(`Cache tarball checksum mismatch on download: expected ${expectedHash}, got ${digest}`);
 		await moveAnchoredGroups(scratch, workDir, home);
 	} finally {
-		await rm(scratch, {
-			recursive: true,
-			force: true
-		});
+		await cleanup();
 	}
 }
 /** Build the imperative `ctx.cache` API bound to a workDir + transport. */

package/dist/provenance/statement-builder.d.ts

@@ -1,12 +1,13 @@
 /**
  * Build a SLSA v1.0 in-toto provenance statement from the server-truth identity
  * token claims plus the caller-supplied subject. The build context comes
- * entirely from the JWT claims (Platform-minted, unforgeable), so the
+ * entirely from the JWT claims (minted server-side by the orchestrator,
+ * unforgeable), so the
  * statement's identity equals the token's identity by construction.
  */
 import { type KiciProvenanceStatement } from '@kici-dev/engine/provenance/schema';
 import type { SourceOrigin } from '@kici-dev/engine';
-/** The KiCI identity-token claims the builder reads (Platform server-truth). */
+/** The KiCI identity-token claims the builder reads (minter server-truth). */
 export interface ProvenanceTokenClaims {
     iss: string;
     repository?: string | null;

package/dist/server.d.ts

@@ -4,7 +4,7 @@
  * Startup sequence:
  * 1. Load config
  * 2. Create logger
- * 3. Create JobRunner with send/sendDirect callbacks
+ * 3. Create JobRunner with send callbacks
  * 4. Create OrchestratorClient with dispatch and cancel handlers
  * 5. Add WS log transport (if not scaler-managed)
  * 6. Connect OrchestratorClient