@kici-dev/compiler 0.5.0 → 0.6.0

package/dist/commands/report/upload.js

@@ -0,0 +1,64 @@
+import "../../rolldown-runtime-ClRpJifh.js";
+import { DashboardClient } from "../../remote/dashboard-client.js";
+import * as fs$1 from "node:fs";
+import { createHash } from "node:crypto";
+//#region src/commands/report/upload.ts
+/**
+* Upload a report bundle privately to KiCI.
+*
+* Three steps, and the split is the point: the Platform mints a presigned PUT,
+* the bytes go straight from this machine to object storage, and a confirm call
+* lets the Platform verify what actually landed. The bundle never transits the
+* control plane, and the Platform never takes the client's word for the size.
+*
+* Upload is always opt-in (`--upload`). A bundle contains diagnostic data from
+* the customer's own machine, so sending it is a separate, explicit act from
+* producing it.
+*/
+/** sha256 of the file, which the Platform records alongside the report. */
+function sha256Of(body) {
+	return createHash("sha256").update(body).digest("hex");
+}
+async function defaultPutBytes(url, body) {
+	const res = await fetch(url, {
+		method: "PUT",
+		body: new Uint8Array(body),
+		headers: { "Content-Length": String(body.byteLength) }
+	});
+	if (!res.ok) throw new Error(`Bundle upload failed (${res.status} ${res.statusText}).`);
+}
+async function defaultDeps() {
+	const client = await DashboardClient.load();
+	return {
+		createIssueReport: client.createIssueReport.bind(client),
+		confirmIssueReport: client.confirmIssueReport.bind(client),
+		putBytes: defaultPutBytes
+	};
+}
+/**
+* Upload one bundle and return the reference id to quote to support.
+*
+* Reads the file once and derives both the size and the digest from those same
+* bytes, so what is promised at presign time is necessarily what is uploaded —
+* a stat-then-read would race a file still being written.
+*/
+async function uploadReportBundle(zipPath, meta, deps) {
+	const resolved = deps ?? await defaultDeps();
+	const body = fs$1.readFileSync(zipPath);
+	const { ref, uploadUrl } = await resolved.createIssueReport({
+		bundleId: meta.bundleId,
+		byteSize: body.byteLength,
+		sha256: sha256Of(body),
+		message: meta.message,
+		email: meta.email
+	});
+	await resolved.putBytes(uploadUrl, body);
+	return {
+		ref,
+		status: (await resolved.confirmIssueReport(ref)).status
+	};
+}
+//#endregion
+export { sha256Of, uploadReportBundle };
+
+//# sourceMappingURL=upload.js.map

package/dist/commands/run-hold-watch.js

@@ -66,7 +66,7 @@ async function handleNewHolds(args) {
 		printHold(action.hold, out);
 		ctx = ctx ?? await resolveCtx();
 		if (!ctx) {
-			out(pc.dim(`Run held; approve via \`kici approve ${action.hold.runId}\`.`));
+			out(pc.dim(`Run held; approve via \`kici approve ${action.hold.runId} --hold ${action.hold.id}\`.`));
 			continue;
 		}
 		if (args.approveAll) {
@@ -74,7 +74,7 @@ async function handleNewHolds(args) {
 			continue;
 		}
 		if (action.kind === "notify") {
-			out(pc.dim(`Run held; approve via the dashboard or \`kici approve ${action.hold.runId}\`.`));
+			out(pc.dim(`Run held; approve via the dashboard or \`kici approve ${action.hold.runId} --hold ${action.hold.id}\`.`));
 			continue;
 		}
 		const approved = await args.confirm("Approve this gate?");

package/dist/commands/run.js

@@ -303,8 +303,10 @@ async function renderResults(results, options) {
 		const junitXml = formatJunitResult(runResults);
 		await writeFile(options.junit, junitXml);
 		if (!options.quiet) logger.info(pc.green(`JUnit XML written to ${options.junit}`));
-	} else if (!options.quiet || results.some((r) => r.status !== "success" && r.status !== "accepted")) if (runResults.length > 1) logger.info(formatMultiFixtureSummary(runResults));
-	else displayRemoteResults(results);
+	} else if (!options.quiet || results.some((r) => r.status !== "success" && r.status !== "accepted")) {
+		if (runResults.length > 1) logger.info(formatMultiFixtureSummary(runResults));
+		else displayRemoteResults(results);
+	}
 	return results.every((r) => r.status === "accepted" || r.status === "success");
 }
 /**
@@ -537,10 +539,11 @@ async function watchRunHolds(runId, seenHolds, getCtx, setCtx, options) {
 		const holds = await listHeldRunsForRun(ctx, runId);
 		if (holds.length === 0) return;
 		const quiet = Boolean(options.quiet);
+		const isTty = quiet ? false : Boolean(process.stdin.isTTY && process.stdout.isTTY);
 		await handleNewHolds({
 			holds,
 			seen: seenHolds,
-			isTty: quiet ? false : Boolean(process.stdin.isTTY && process.stdout.isTTY),
+			isTty,
 			output: quiet ? (line) => void process.stderr.write(line + "\n") : (line) => logger.info(line),
 			approveAll: Boolean(options.approveAll),
 			confirm: (message) => confirm({

package/dist/commands/runs/show.js

@@ -2,6 +2,7 @@ import "../../rolldown-runtime-ClRpJifh.js";
 import { DashboardClient, DashboardClientError } from "../../remote/dashboard-client.js";
 import { RunHistory } from "../../remote/history.js";
 import { colorStatus, formatDuration as formatDuration$1, relativeTime } from "../../remote/render.js";
+import { HeldRunRequestError, listHeldRunsForRun, resolveHeldRunContext } from "../held-run-client.js";
 import pc from "picocolors";
 import { logger, toErrorMessage } from "@kici-dev/core";
 //#region src/commands/runs/show.ts
@@ -17,33 +18,111 @@ async function runsShowCommand(runId, options = {}) {
 			throw err;
 		}
 		const detail = await client.getRunDetail(runId);
+		const holds = await loadHolds(runId);
 		if (options.json) {
 			console.log(JSON.stringify({
 				run,
-				detail
+				detail,
+				heldRuns: holds.holds,
+				...holds.unavailable && { heldRunsUnavailable: holds.unavailable }
 			}, null, 2));
 			return true;
 		}
 		printHeader(run);
+		printInitFailure(detail.initFailure);
 		printJobs(detail.jobs);
+		printHolds(holds);
 		return true;
 	} catch (err) {
 		logger.error(pc.red(err instanceof DashboardClientError ? err.message : toErrorMessage(err)));
 		return false;
 	}
 }
+/**
+* Read the approval holds recorded for a run.
+*
+* The holds are extra detail on a run this command can already display, so a
+* failure here degrades to a note rather than failing the command: an operator
+* asking why a job did not run still gets the run, its jobs and its init
+* failure. The auth context is resolved quietly for the same reason — a config
+* that cannot reach the held-runs API is not an error for `runs show`.
+*/
+async function loadHolds(runId) {
+	try {
+		const ctx = await resolveHeldRunContext({ quiet: true });
+		if (!ctx) return {
+			holds: [],
+			unavailable: "not authenticated for held-run lookup",
+			unavailableSilently: true
+		};
+		return { holds: await listHeldRunsForRun(ctx, runId) };
+	} catch (err) {
+		const denied = err instanceof HeldRunRequestError && err.isPermissionDenied;
+		return {
+			holds: [],
+			unavailable: toErrorMessage(err),
+			...denied && { unavailableSilently: true }
+		};
+	}
+}
 function printHeader(run) {
 	const f = (v) => v == null ? "—" : v;
 	console.log(pc.bold(`\nRun ${run.runId}`) + `  ${colorStatus(run.status)}`);
 	console.log(pc.gray(`  workflow=${f(run.workflowName)} repo=${f(run.repoIdentifier)} branch=${f(run.ref)} sha=${f(run.sha)} trigger=${f(run.triggerEvent)} by=${f(run.triggeredBy)}`));
 	console.log(pc.gray(`  started=${relativeTime(run.startedAt ?? void 0)}`));
 }
+/**
+* The run-scoped init failure — why the run never started a step (an
+* unresolvable lock file, a secret it could not read, a gate it never passed).
+* Nothing is printed when the run started normally.
+*/
+function printInitFailure(initFailure) {
+	if (!initFailure) return;
+	console.log(`\n  ${pc.yellow("Init failure")} ${pc.gray(`(${initFailure.category})`)}`);
+	console.log(`    ${initFailure.message}`);
+}
 function printJobs(jobs) {
 	for (const j of jobs) {
 		console.log(`\n  ${pc.bold(j.jobName)} ${colorStatus(j.status)} ` + pc.gray(j.durationMs ? formatDuration$1(j.durationMs) : ""));
+		printJobFailure(j);
 		for (const s of j.steps ?? []) console.log(pc.gray("    └─ ") + `${s.stepName} ${colorStatus(s.status)} ` + pc.gray(`${s.durationMs ? formatDuration$1(s.durationMs) : ""}${s.exitCode != null ? ` exit=${s.exitCode}` : ""}`));
 	}
 }
+/**
+* Why a single job failed: its job-scoped init failure (a job the context rules
+* rejected carries `context_rules` plus the context and rule that rejected it),
+* or its plain error message. The init failure wins when both are present —
+* the two carry the same text on a rejected job, and the category is the part
+* that tells the reader whether a gate or a step failed.
+*/
+function printJobFailure(job) {
+	if (job.initFailure) {
+		console.log(`    ${pc.yellow("init failure")} ${pc.gray(`(${job.initFailure.category})`)}: ` + job.initFailure.message);
+		return;
+	}
+	if (job.errorMessage) console.log(`    ${pc.red("error")}: ${job.errorMessage}`);
+}
+/** The approval holds recorded against the run, or a note when unreadable. */
+function printHolds(result) {
+	if (result.unavailable) {
+		if (!result.unavailableSilently) console.log(pc.gray(`\n  Approval-hold detail unavailable: ${result.unavailable}`));
+		return;
+	}
+	if (result.holds.length === 0) return;
+	console.log(`\n  ${pc.bold(`Approval holds (${result.holds.length})`)}`);
+	for (const h of result.holds) {
+		const parts = [
+			h.jobId || "(workflow)",
+			h.holdType ?? "—",
+			h.contextName ? `context=${h.contextName}` : void 0,
+			h.queueType ? `queue=${h.queueType}` : void 0,
+			colorStatus(h.status)
+		].filter((p) => p != null);
+		console.log(`    ${parts.join("  ")}`);
+		if (h.reason) console.log(pc.gray(`      reason: ${h.reason}`));
+		if (h.expiresAt) console.log(pc.gray(`      expires: ${relativeTime(h.expiresAt)}`));
+	}
+}
 async function showLocalFallback(runId, json) {
 	const history = new RunHistory();
 	await history.load();

package/dist/commands/types.js

@@ -8,6 +8,32 @@ import fs from "node:fs/promises";
 import { toErrorMessage } from "@kici-dev/core";
 //#region src/commands/types.ts
 /**
+* Error kinds meaning the Platform is genuinely unreachable or the CLI is not
+* configured to reach it — not authenticated, no active org, network down, or
+* orchestrator offline. For these, `kici types` writes a valid empty stub so
+* the declaration file always exists (typecheck degrades to "no known keys"
+* rather than "module has no exported member") instead of failing.
+*
+* An authenticated-but-rejected response (`unauthorized`, `forbidden`, …) is
+* deliberately excluded: that is a real credential/permission problem the user
+* must see, and writing a stub would mask it.
+*/
+const UNREACHABLE_ERROR_KINDS = [
+	"not_logged_in",
+	"no_active_org",
+	"orchestrator_offline",
+	"http"
+];
+/** True if `p` exists (any type). Used to avoid clobbering a real snapshot. */
+async function fileExists(p) {
+	try {
+		await fs.access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
 * Generate TypeScript declarations for context secrets.
 *
 * Fetches context metadata (with secret key names) through the Platform
@@ -18,23 +44,40 @@ import { toErrorMessage } from "@kici-dev/core";
 * @returns true on success, false on error
 */
 async function typesCommand(options = {}) {
+	const kiciDir = options.kiciDir ?? ".kici";
+	const typesDir = path.join(kiciDir, "types");
+	const outputPath = path.join(typesDir, "secrets.d.ts");
 	try {
 		const config = await loadGlobalConfig();
+		const metadata = (await DashboardClient.fromConfig(config).listContexts(true)).map((e) => ({
+			name: e.name,
+			keys: e.secretKeys ?? []
+		}));
+		const source = config.platformEndpoint ?? config.endpoint ?? "kici Platform";
 		const dtsContent = generateSecretsDts({
-			contexts: (await DashboardClient.fromConfig(config).listContexts(true)).map((e) => ({
-				name: e.name,
-				keys: e.secretKeys ?? []
-			})),
-			endpoint: (config.platformEndpoint ?? config.endpoint ?? "kici Platform").replace(/\/+$/, "")
+			contexts: metadata,
+			endpoint: source.replace(/\/+$/, "")
 		});
-		const kiciDir = options.kiciDir ?? ".kici";
-		const typesDir = path.join(kiciDir, "types");
 		await fs.mkdir(typesDir, { recursive: true });
-		const outputPath = path.join(typesDir, "secrets.d.ts");
 		await fs.writeFile(outputPath, dtsContent, "utf-8");
 		if (!options.quiet) console.log(pc.green("Types generated") + pc.dim(` ${outputPath}`));
 		return true;
 	} catch (err) {
+		if (err instanceof DashboardClientError && UNREACHABLE_ERROR_KINDS.includes(err.kind)) {
+			if (await fileExists(outputPath)) {
+				console.error(pc.yellow(`${err.message} Keeping the existing ${outputPath}; run \`kici types\` when authenticated to refresh it.`));
+				return true;
+			}
+			const stub = generateSecretsDts({
+				contexts: [],
+				endpoint: "",
+				offline: true
+			});
+			await fs.mkdir(typesDir, { recursive: true });
+			await fs.writeFile(outputPath, stub, "utf-8");
+			console.error(pc.yellow(`${err.message} Wrote an offline type stub to ${outputPath}; run \`kici types\` when authenticated to populate it.`));
+			return true;
+		}
 		if (err instanceof DashboardClientError) {
 			console.error(pc.red(err.message));
 			return false;

package/dist/execution/sdk-alias.js

@@ -19,7 +19,8 @@ import { readFile } from "node:fs/promises";
 */
 async function getSdkPathFromPackageJson() {
 	try {
-		const content = await readFile(path.resolve(process.cwd(), ".kici", "package.json"), "utf-8");
+		const pkgPath = path.resolve(process.cwd(), ".kici", "package.json");
+		const content = await readFile(pkgPath, "utf-8");
 		const sdkPath = JSON.parse(content).kici?.sdkPath;
 		if (!sdkPath) return null;
 		return path.resolve(sdkPath);
@@ -36,7 +37,8 @@ async function getSdkPathFromPackageJson() {
 */
 async function isInKiciRepo() {
 	try {
-		const content = await readFile(path.resolve(process.cwd(), "package.json"), "utf-8");
+		const rootPkgPath = path.resolve(process.cwd(), "package.json");
+		const content = await readFile(rootPkgPath, "utf-8");
 		return JSON.parse(content).kici?.development === true;
 	} catch {
 		return false;

package/dist/fixtures/compiler.js

@@ -119,7 +119,8 @@ async function ensureRuntimeSymlinks(filePath) {
 			continue;
 		} catch {}
 		try {
-			const pkgDir = await findPackageRoot(fileURLToPath(import.meta.resolve(pkg)));
+			const entry = import.meta.resolve(pkg);
+			const pkgDir = await findPackageRoot(fileURLToPath(entry));
 			const linkParent = path.dirname(linkPath);
 			if (linkParent !== nodeModulesDir) await fs.mkdir(linkParent, { recursive: true });
 			await fs.symlink(pkgDir, linkPath);

package/dist/format.js

@@ -6,12 +6,12 @@ import "./rolldown-runtime-ClRpJifh.js";
 function formatRelativeTime(isoDate) {
 	const ms = Date.now() - new Date(isoDate).getTime();
 	if (ms < 0) return "just now";
-	const minutes = Math.floor(ms / (60 * 1e3));
+	const minutes = Math.floor(ms / 6e4);
 	if (minutes < 1) return "just now";
 	if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
-	const hours = Math.floor(ms / (3600 * 1e3));
+	const hours = Math.floor(ms / 36e5);
 	if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
-	const days = Math.floor(ms / (1440 * 60 * 1e3));
+	const days = Math.floor(ms / 864e5);
 	return `${days} day${days === 1 ? "" : "s"} ago`;
 }
 //#endregion

package/dist/generators/secrets-dts.d.ts

@@ -10,9 +10,16 @@ export interface ContextMetadata {
     name: string;
     keys: string[];
 }
-interface GenerateSecretsDtsOptions {
+export interface GenerateSecretsDtsOptions {
     contexts: ContextMetadata[];
     endpoint: string;
+    /**
+     * Mark the output as an offline stub written when the Platform could not be
+     * reached (unauthenticated, offline, or no active org). The header names it a
+     * stub instead of a source URL so a reader can tell it from a real snapshot,
+     * and the caller passes `contexts: []` so it augments no known keys.
+     */
+    offline?: boolean;
 }
 /**
  * Generate a .d.ts string from context metadata.
@@ -24,5 +31,4 @@ interface GenerateSecretsDtsOptions {
  * @returns The .d.ts file content as a string
  */
 export declare function generateSecretsDts(options: GenerateSecretsDtsOptions): string;
-export {};
 //# sourceMappingURL=secrets-dts.d.ts.map

package/dist/generators/secrets-dts.js

@@ -34,10 +34,11 @@ function buildKeySourceMap(contexts) {
 * @returns The .d.ts file content as a string
 */
 function generateSecretsDts(options) {
-	const { contexts, endpoint } = options;
+	const { contexts, endpoint, offline } = options;
 	const lines = [];
 	lines.push("// @generated by kici types -- DO NOT EDIT");
-	lines.push(`// Source: ${endpoint}`);
+	if (offline) lines.push("// Source: offline stub -- Platform unreachable, no known secret keys");
+	else lines.push(`// Source: ${endpoint}`);
 	lines.push("// Run `kici types` to refresh");
 	lines.push("");
 	lines.push("declare module '@kici-dev/sdk' {");

package/dist/hooks/installer.js

@@ -252,7 +252,8 @@ repos:
 */
 async function resolveCommonGitDir(gitDir) {
 	try {
-		const commondir = (await readFile(path.join(gitDir, "commondir"), "utf-8")).trim();
+		const commondirPath = path.join(gitDir, "commondir");
+		const commondir = (await readFile(commondirPath, "utf-8")).trim();
 		return path.resolve(gitDir, commondir);
 	} catch {
 		return gitDir;

package/dist/llm-context/llms-architecture.txt

@@ -316,10 +316,13 @@ The `ProviderRegistry` maps routing keys to provider bundles. Each routing key (
 - `FileContentsFetcher` -- reads arbitrary repository files at a ref, for the declarative content-requirements (`requires`) filter
 - `CloneTokenProvider` -- generates clone tokens for agents
 - `RepoUrlBuilder` -- builds clone URLs and raw file URLs
-- `ContributorResolver` -- resolves contributor permissions for trust-tier gating
 - `CheckStatusPoster` -- posts check statuses (approval/hold) to the git provider
 
-A GitHub App source populates all eight -- though the file-contents capability arrives as a per-delivery factory rather than a prebuilt instance, because a GitHub client is scoped to one installation and the installation id is only known once the delivery's credentials are resolved. A plain generic webhook source carries only the normalizer -- it has no repository API to fetch a lock file, resolve a contributor, or post a check against -- so the pipeline skips the stages whose interface is absent rather than failing the delivery.
+A bundle also carries a `hasForkModel` flag, set for a provider whose head ref can live outside the base repository. It is what admits a pull-request event to the org fork switch. GitHub sets it; a generic source (whose trust boundary is its verification secret) and a local source (whose trust boundary is on-disk ownership) do not.
+
+A GitHub App source populates all seven. The file-contents capability arrives as a per-delivery factory rather than a prebuilt instance: a GitHub client is scoped to one installation, and the installation id is known only once the delivery's credentials are resolved.
+
+A plain generic webhook source carries only the normalizer, because it has no repository API to fetch a lock file or post a check against. The pipeline skips the stages whose interface is absent rather than failing the delivery.
 
 Provider registrations are managed via the `sources` database table, not via `SharedConfig`. When the orchestrator connects to the Platform relay, it reads source records from the DB and sends `source.register` messages. Changes to sources (add/remove) are detected via PostgreSQL LISTEN/NOTIFY on the `sources_change` channel and pushed to the Platform via `source.secrets` and `source.register`/`source.deregister`.
 
@@ -439,7 +442,18 @@ Orchestrator                         Agent                    Sandbox (child pro
 
 ### Agent pipeline
 
-The agent delegates job execution to an `ExecutionSandbox` (container, bare-metal, or firecracker). The sandbox runs customer code in an isolated child process -- never in the agent's V8 isolate. Four job types are handled: execution jobs (sandbox), build-only jobs (in-process, cache population), init-only jobs (in-process, dynamic field resolution), and DynamicJobFn evaluation jobs (in-process, runtime job generation). See [Job execution lifecycle](https://docs.kici.dev/architecture/execution/job-execution/) for details.
+The agent delegates job execution to an `ExecutionSandbox` (container, bare-metal, or firecracker). The sandbox runs customer code in an isolated child process -- never in the agent's V8 isolate.
+
+Six job types are handled. Only the first uses a sandbox; the other five run in-process, because they never execute customer workflow steps:
+
+- **Execution jobs** -- the standard sandbox path.
+- **Init-only jobs** -- dynamic field resolution.
+- **Global-eval-round jobs** -- filters and generators for the candidate global workflows of one workflow repo.
+- **DynamicJobFn evaluation jobs** -- runtime job generation.
+- **Bring-up jobs** -- init-runner SSH bring-up. No clone, no sandbox.
+- **Build-only jobs** -- cache population.
+
+See [Job execution lifecycle](https://docs.kici.dev/architecture/execution/job-execution/) for details.
 
 1. **Report running** -- Send `job.status: running` immediately upon accepting the dispatch
 2. **Sandbox selection** -- Determine execution mode (container, bare-metal, firecracker) from job config and environment
@@ -512,7 +526,7 @@ Build Job Dispatch --> Build Agent (kici:role:builder + matching kici:os:/kici:a
   |                      |-- Pack .kici/ source (portable tar.gz, excludes node_modules)
   |                      |-- Pack .kici/node_modules (portable tar.gz)
   |                      |-- Upload source tarball to cache (source/{contentHash}.tar.gz)
-  |                      |-- Upload deps tarball to cache (deps/{plat}-{arch}/{lockfileHash}.tar.gz)
+  |                      |-- Upload deps tarball to cache (deps/{plat}-{arch}/{depsHash}.tar.gz)
   |                      |-- Upload deps companion .hash file
   |                      |-- Report success (cache.upload.complete × 2)
   |                      |
@@ -586,7 +600,7 @@ Dep cache misses alone do **not** trigger a build job. Deps are platform-specifi
 
 ### Cross-source / no-contentHash workflows
 
-- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 34.
+- **Lock files without `contentHash`** (schema v1) skip the source cache entirely; agents compile from source. Regenerate lock files with `kici compile` to enable caching. The current lock file schema version is 39.
 - **Cross-source / global-workflow dispatch** (a workflow registered against source A fired by a webhook on source B) bypasses both caches. The registration's lock file entry still carries `contentHash`, but the cross-source path always clone-and-installs — the eval temp dir doesn't ship `@kici-dev/sdk`. The execution agent still verifies `contentHash` against the cloned source for drift detection.
 
 ### Build deduplication
@@ -626,7 +640,10 @@ Both source and dep caches use `S3CacheStorage` as the sole backend. The `CacheS
 Cache keys reflect that source tarballs and deps have different platform characteristics:
 
 - **Source:** `source/{contentHash}.tar.gz` — platform-agnostic. Raw TypeScript source is identical regardless of CPU architecture, so one entry is shared across all platforms. `contentHash` is the per-workflow hash from the lock file (`SHA-256(COMPILE_SCHEMA_VERSION + ":" + rawSource [+ "\0" + assetDigest])`, where `COMPILE_SCHEMA_VERSION = 5` and line endings are normalized to LF so the hash agrees across platforms).
-- **Deps:** `deps/{platform}-{arch}/{lockfileHash}.tar.gz` (e.g., `deps/linux-arm64/def456.tar.gz`) — platform-specific. Native dependencies in `node_modules` differ across architectures, so each platform/arch combination gets its own cache entry.
+- **Deps:** `deps/{platform}-{arch}/{depsHash}.tar.gz`, with a
+  `deps/{platform}-{arch}/{lockfileHash}.hash` pointer holding that hash — the
+  tarball is addressed by its own content, so two builds sharing a lock file
+  cannot leave a tarball and an integrity hash that disagree. Platform-specific. Native dependencies in `node_modules` differ across architectures, so each platform/arch combination gets its own cache entry.
 
 The orchestrator derives the target platform/arch for dep cache lookups by probing `AgentRegistry.findAvailable()` with the workflow's first job's `runsOn` labels to find a representative matching agent, then using that agent's platform and arch. Falls back to `linux/x64` if no matching agents are registered.
 
@@ -1304,7 +1321,7 @@ The orchestrator is the execution brain. It decides what to run and dispatches w
 - **Job queue** -- PostgreSQL-backed FIFO queue for reliable dispatch.
 - **Webhook pipeline** -- Dedup, event mapping, lock file fetch, trigger matching, and job dispatch in a single pipeline.
 - **Multi-orchestrator clustering** -- Optional peer-to-peer coordination via direct WebSocket connections. Enables cross-architecture job routing (e.g., x64 coordinator reroutes arm64 jobs to a peer), high availability, and dedicated coordinator topologies. Uses Raft consensus for leader election (orphan recovery). See [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/).
-- **Auto-scaler** -- Optional pluggable module for ephemeral agent provisioning. Supports containers (Docker/Podman), bare-metal processes, and Firecracker microVMs as backends. Spawns agents on demand when no matching agent is connected, with label-based routing, two-level capacity limits (global + per-backend), warm pools, YAML configuration (`scalers.d/` directory support), and SIGHUP reload. Disabled by default -- orchestrator works without it.
+- **Auto-scaler** -- Optional pluggable module for ephemeral agent provisioning. Four backends are configurable: containers (Docker/Podman), bare-metal processes, Firecracker microVMs, and the event backend, which performs no local compute -- it emits reserved scale-up / scale-down events that a customer-authored provisioning workflow consumes to boot and tear down a cloud instance. Spawns agents on demand when no matching agent is connected, with label-based routing, two-level capacity limits (global + per-backend), warm pools, YAML configuration (`scalers.d/` directory support), and SIGHUP reload. Disabled by default -- orchestrator works without it.
 - **Independent database** -- Has its own PostgreSQL database separate from the Platform. Stores execution runs/jobs/steps, dispatch queue, webhook secrets, dedup cache, and scaler state. The orchestrator's `execution_runs` and `execution_jobs` are the authoritative source of truth. The Platform receives execution status updates via WebSocket messages (`execution.status`, `job.status.forward`).
 
 > Source: `packages/orchestrator/src/pipeline/processor.ts` (webhook pipeline), `packages/orchestrator/src/cluster/` (P2P coordination), `packages/orchestrator/src/scaler/` (auto-scaler module), `packages/orchestrator/src/server.ts` (Platform/hybrid entry point)
@@ -1314,6 +1331,7 @@ The orchestrator is the execution brain. It decides what to run and dispatches w
 The agent is the execution worker. It runs on customer infrastructure and has full access to customer code.
 
 - **Repository cloning** -- Clones the target repo with token-based auth (token in HTTP headers, not URLs, to prevent leakage).
+- **Git credential helper** -- Registers a credential helper for the job's git operations. Every network operation asks the orchestrator's broker for a credential, so a token is minted seconds before use rather than held for the life of the job. Write access is opt-in and time-boxed: `ctx.repo.withWrite(...)` adds a repository-scoped grant for the duration of its callback and revokes it afterwards, with a TTL backstop.
 - **Step execution** -- Runs steps in declaration order with full `StepContext` (zx shell, logger, environment, workflow/job metadata). Steps wrapped in a `parallel()` group run concurrently behind a `maxParallel` window, and each child reports as its own observable step with its own logs, status, timing, and retry.
 - **Execution sandboxes** -- Runs the workflow runner as a separate child process with a sanitized environment, in one of three sandboxes: bare metal (process fork, with optional bubblewrap namespace isolation), a container runtime (the whole job lifecycle runs inside a disposable container), or inside a Firecracker microVM. Agent-internal credentials never reach customer workflow code.
 - **Log streaming** -- Chunked log streaming back to the orchestrator with configurable size limits.
@@ -1329,11 +1347,14 @@ The agent is the execution worker. It runs on customer infrastructure and has fu
 Shared business logic used by all three tiers. Single source of truth for cross-tier concerns. Has no internal `@kici-dev/*` dependencies -- only a handful of third-party libraries.
 
 - Protocol message schemas (Zod-based, direction-specific unions including dashboard REST-over-WS, browser live streaming, the test-relay control plane, log pull, run events, peer-to-peer, cluster join, and source registration)
-- Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, FileContentsFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster)
+- Provider interfaces (WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, FileContentsFetcher, CloneTokenProvider, RepoUrlBuilder, CheckStatusPoster), plus the deprecated `ContributorResolver` the pipeline no longer calls
+- Git credential vocabulary (forge names plus the credential reference, grant, request, and result shapes the SDK declares and the orchestrator's broker resolves) and the agent→orchestrator relay protocol its credential helper calls. See [Git credentials](https://docs.kici.dev/user/patterns/git-credentials/)
 - Trigger matching engine (branch, path, event evaluation)
+- Content-requirement matcher (the declarative `requires` filter -- pure data describing a query over the bytes of one source file at the event's ref, interpreted by the orchestrator via the `FileContentsFetcher` so no author code runs there) and the shared text-match vocabulary (`contains` / `notContains` / `matches` / `notMatches`) it shares with the commit-message trigger filter
 - Dispatch inputs (input descriptors, extraction from the trigger event, and coercion to typed values)
 - Matrix expansion and fanout (combination expansion with include/exclude, job-name suffix formatting, and materialization of one matrix or multi-host job into N dispatchable children)
-- Execution status vocabulary (run/job/step status enums + terminal-state sets; lifecycle owned by the orchestrator's execution tracker)
+- Execution status vocabulary (run/job/step status enums + terminal-state sets; lifecycle owned by the orchestrator's execution tracker) and its presentation layer (the total precedence order that decides which status wins a roll-up, legacy-spelling resolution, and the per-status failure classification every consumer asks about)
+- Job-kind discriminator, alongside the status enums. It separates a `standard` job running steps from an invoke `gate` and from the `proxy` job that mirrors a summoned run
 - Check mode (the idempotent run modes `apply` / `check` / `check-fail-on-drift` and the per-step outcome vocabulary)
 - Webhook signature verification (HMAC-SHA256, timing-safe)
 - WebSocket close codes (unified across all tiers)
@@ -1344,12 +1365,13 @@ Shared business logic used by all three tiers. Single source of truth for cross-
 - Approval requirements (normalized approver clauses shared by the orchestrator gate, the resolver, the held-run store, and the agent step round-trip)
 - Build provenance (in-toto statement schema, DSSE envelope, attestation bundle, verification)
 - Artifact name contract (the shared filesystem/URL-safe name schema the orchestrator, agent, and SDK all validate against)
-- Developer MCP tool schemas (argument schemas for the AI-agent tool surface)
+- Developer MCP tool schemas (argument schemas for the AI-agent tool surface) and the untrusted-content fence that wraps every repository- or contributor-supplied value an agent reads in a per-response random nonce, so log lines and error text cannot be read as instructions
 - Developer-operations contract (one row per workflow-developer operation declaring which entrypoints expose it -- the shared REST API behind the web UI and the `kici` CLI, the AI-agent tool surface, and a curated UI flag -- asserted against each real surface by congruence tests)
 - Label utilities (platform label derivation, runsOn normalization, `kici:*` set-only reserved namespace, role labels)
 - Host inventory (the canonical queryable host-roster schema shared by the orchestrator's roster store, the agent-facing inventory API, and the SDK's `ctx.kici.inventory`)
 - Audit policy and retention (per-action access-log sampling, warm-retention windows for cold-store eligibility, federated activity row schema)
-- Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`)
+- Scaler backend type enum (`container`, `bare-metal`, `firecracker`, `kubernetes`, `event`) and the reserved `kici.` event-name prefix that keeps a user step from forging a system event
+- Job resource vocabulary (the requests/limits shape the SDK accepts, the compiler validates and emits, the orchestrator uses for capacity math and kernel-side enforcement, and the dashboard displays)
 - Registration trigger type enum (registerable trigger discriminator)
 - Sandbox capability set (the Linux capability names a container sandbox may add or drop, shared by the SDK validator, the compiler, and the dispatch resolver)
 - Plan tier vocabulary (the hosted plan tiers and the purchasable subset, shared by the Platform and the browser dashboard)
@@ -1375,7 +1397,7 @@ It also runs the **local dev plane** -- an on-demand, fully local execution stac
 
 ### `@kici-dev/core`
 
-Light shared utilities with no server-side dependencies — JSON-structured logging, error helpers, human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`), cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret`), zx initialization (`initZx()`), and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
+Light shared utilities with no server-side dependencies. It provides JSON-structured logging, error helpers, async-local-storage request context, and human-readable formatting (`formatBytes`/`formatDuration`/`formatUptime`). It also provides cryptographic helpers (`sha256`/`sha256File`/`deriveSharedSecret` plus symmetric encrypt/decrypt), retry-backoff computation, and the shared diagnostics-result contract. The rest of its surface ships as subpath entry points: the temp-directory allocator and its garbage collector, package-manager detection, CI-environment detection, and the idempotent-step runner (the check / confirm / apply primitive behind idempotent steps). Finally it supplies zx initialization (`initZx()`) and the TypeScript loader hook that transforms TypeScript on import. It is the dependency-light core that the SDK, compiler, and `kici` CLI consume directly so they stay free of heavier server-only dependencies. `@kici-dev/shared` re-exports it, so existing `@kici-dev/shared` import paths keep working.
 
 > Source: `packages/core/src/`
 
@@ -1463,7 +1485,7 @@ The orchestrator connects outbound to the Platform WebSocket endpoint. After aut
 
 When multiple orchestrators are deployed, they establish direct WebSocket connections to each other on the `/ws/peer` endpoint. Peers are discovered via the Platform matchmaker (Platform/hybrid modes) or static configuration (`KICI_CLUSTER_PEERS` env var, independent mode). Connections are authenticated with a mutual pre-shared key (PSK). Traffic includes agent inventory heartbeats, job rerouting, progress reporting, cancel propagation, and Raft leader election. These messages never transit the Platform tier.
 
-> See [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/) for clustering details and [Protocol Messages](https://docs.kici.dev/architecture/protocol/dashboard/#orchestrator-orchestrator-messages-peer-to-peer) for message schemas.
+> See [Multi-Orchestrator Architecture](https://docs.kici.dev/architecture/clustering/multi-orchestrator/) for clustering details and [Protocol Messages](https://docs.kici.dev/architecture/protocol/dashboard/#orchestrator---orchestrator-messages-peer-to-peer) for message schemas.
 
 ### Orchestrator ↔ Agent