@kici-dev/engine 0.1.26 → 0.2.0

package/dist/labels.d.ts

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 /**
  * Structured auto-labels with category prefixes.
  *
@@ -30,6 +31,85 @@
  * Derive kici:os: and kici:arch: labels from platform and architecture strings.
  */
 export declare function deriveOsArchLabels(platform: string, arch: string): string[];
+/**
+ * Plain OS/arch labels that gate a bare-metal scaler as a mandatory taint.
+ * A pool whose declared labels include one of these only accepts jobs that
+ * explicitly request that platform. Linux and x64/amd64 are the defaults and
+ * are absent on purpose — an unqualified `runsOn: 'bare-metal'` job must still
+ * land on a Linux-x64 scaler.
+ */
+export declare const PLATFORM_TAINT_LABELS: Set<string>;
+/**
+ * Intersect a pool's declared labels with {@link PLATFORM_TAINT_LABELS},
+ * returning the de-duplicated plain platform-taint labels (lowercased) in
+ * input order.
+ */
+export declare function derivePlatformTaints(declaredLabels: string[]): string[];
+/**
+ * Operating systems a scaler pool can declare via the structured `platform`
+ * field. `linux` is the default and carries no taint; `macos` / `windows` are
+ * non-default and taint the pool.
+ */
+export declare const ScalerOs: z.ZodEnum<{
+    linux: "linux";
+    macos: "macos";
+    windows: "windows";
+}>;
+export type ScalerOs = z.infer<typeof ScalerOs>;
+/**
+ * CPU architectures a scaler pool can declare via the structured `platform`
+ * field. `x64` is the default and carries no taint; `arm64` taints the pool.
+ */
+export declare const ScalerArch: z.ZodEnum<{
+    arm64: "arm64";
+    x64: "x64";
+}>;
+export type ScalerArch = z.infer<typeof ScalerArch>;
+/**
+ * Structured platform of a scaler pool: the single source of truth for both the
+ * auto-injected `kici:os:*` / `kici:arch:*` labels and the mandatory platform
+ * taint. Declaring it once removes the ambiguity of matching plain string
+ * labels against a denylist.
+ */
+export declare const scalerPlatformSchema: z.ZodObject<{
+    os: z.ZodEnum<{
+        linux: "linux";
+        macos: "macos";
+        windows: "windows";
+    }>;
+    arch: z.ZodEnum<{
+        arm64: "arm64";
+        x64: "x64";
+    }>;
+}, z.core.$strict>;
+export type ScalerPlatform = z.infer<typeof scalerPlatformSchema>;
+/**
+ * Derive the `kici:os:*` / `kici:arch:*` labels for a declared structured
+ * platform. Reuses {@link deriveOsArchLabels} so the label shape is identical to
+ * the host-reported form (e.g. `windows` yields both `kici:os:windows` and
+ * `kici:os:win32`).
+ */
+export declare function platformToOsArchLabels(platform: ScalerPlatform): string[];
+/**
+ * Derive the plain platform-taint labels for a declared structured platform.
+ * Returns the canonical tokens (`macos`, `windows`, `arm64`) that a job's
+ * `runsOn` must include to allocate on the pool. The linux/x64 default carries
+ * no taint. Unlike {@link derivePlatformTaints} (which intersects declared
+ * labels against a denylist), this derives from the structured field, so a pool
+ * labeled `windows-2022` still taints correctly.
+ */
+export declare function platformToTaints(platform: ScalerPlatform): string[];
+/** Map an `os.platform()` string to a `ScalerOs`, or null when unrecognised. */
+export declare function nodePlatformToScalerOs(nodePlatform: string): ScalerOs | null;
+/** Map an `os.arch()` string to a `ScalerArch`, or null when unrecognised. */
+export declare function nodeArchToScalerArch(nodeArch: string): ScalerArch | null;
+/**
+ * Build a structured platform from the host's `os.platform()` / `os.arch()`.
+ * Returns null when either component is not one of the supported enum values,
+ * so a caller can fall back to the legacy host-label derivation for exotic
+ * hosts.
+ */
+export declare function hostToScalerPlatform(nodePlatform: string, nodeArch: string): ScalerPlatform | null;
 /** Prefix for the agent self-reported hostname label. */
 export declare const HOST_LABEL_PREFIX = "kici:host:";
 /**
@@ -74,7 +154,7 @@ export declare function normalizeRunsOn(runsOn: string | string[] | {
  * - builder: can run __build__ jobs (dependency cache compilation)
  * - init-runner: can run __init__ jobs (workspace initialization)
  */
-export declare const KNOWN_ROLES: readonly ["builder", "init-runner"];
+export declare const KNOWN_ROLES: readonly ['builder', 'init-runner'];
 /** Agent role type derived from KNOWN_ROLES. */
 export type AgentRole = (typeof KNOWN_ROLES)[number];
 /** Reserved label prefix — labels starting with this are system-managed. */
@@ -140,7 +220,7 @@ export declare function scalerAgentLabels(labelSet: string[], backendType: strin
  * platform facts, not authorization grants, so the orchestrator's register-time
  * label-scope gate does not require an ephemeral token to be bound to them.
  */
-export declare const SELF_REPORTED_LABEL_PREFIXES: readonly ["kici:os:", "kici:arch:", "kici:host:"];
+export declare const SELF_REPORTED_LABEL_PREFIXES: readonly ['kici:os:', 'kici:arch:', 'kici:host:'];
 /**
  * True if a label is a self-reported platform fact (os/arch/host) rather than a
  * scaler-assigned, authorization-bearing label. Used by the agent register-time

package/dist/labels.js

@@ -1,4 +1,5 @@
 import "./rolldown-runtime-ClRpJifh.js";
+import { z } from "zod";
 //#region src/labels.ts
 /**
 * Structured auto-labels with category prefixes.
@@ -56,6 +57,123 @@ function deriveOsArchLabels(platform, arch) {
 	}
 	return labels;
 }
+/**
+* Plain OS/arch labels that gate a bare-metal scaler as a mandatory taint.
+* A pool whose declared labels include one of these only accepts jobs that
+* explicitly request that platform. Linux and x64/amd64 are the defaults and
+* are absent on purpose — an unqualified `runsOn: 'bare-metal'` job must still
+* land on a Linux-x64 scaler.
+*/
+const PLATFORM_TAINT_LABELS = /* @__PURE__ */ new Set([
+	"windows",
+	"win32",
+	"macos",
+	"darwin",
+	"arm64",
+	"aarch64",
+	"arm"
+]);
+/**
+* Intersect a pool's declared labels with {@link PLATFORM_TAINT_LABELS},
+* returning the de-duplicated plain platform-taint labels (lowercased) in
+* input order.
+*/
+function derivePlatformTaints(declaredLabels) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const raw of declaredLabels) {
+		const label = raw.toLowerCase();
+		if (PLATFORM_TAINT_LABELS.has(label)) seen.add(label);
+	}
+	return [...seen];
+}
+/**
+* Operating systems a scaler pool can declare via the structured `platform`
+* field. `linux` is the default and carries no taint; `macos` / `windows` are
+* non-default and taint the pool.
+*/
+const ScalerOs = z.enum([
+	"linux",
+	"macos",
+	"windows"
+]);
+/**
+* CPU architectures a scaler pool can declare via the structured `platform`
+* field. `x64` is the default and carries no taint; `arm64` taints the pool.
+*/
+const ScalerArch = z.enum(["x64", "arm64"]);
+/**
+* Structured platform of a scaler pool: the single source of truth for both the
+* auto-injected `kici:os:*` / `kici:arch:*` labels and the mandatory platform
+* taint. Declaring it once removes the ambiguity of matching plain string
+* labels against a denylist.
+*/
+const scalerPlatformSchema = z.object({
+	os: ScalerOs,
+	arch: ScalerArch
+}).strict();
+/** Map a structured `ScalerOs` back to the `os.platform()` string it represents. */
+function scalerOsToNodePlatform(os) {
+	switch (os) {
+		case "linux": return "linux";
+		case "macos": return "darwin";
+		case "windows": return "win32";
+	}
+}
+/**
+* Derive the `kici:os:*` / `kici:arch:*` labels for a declared structured
+* platform. Reuses {@link deriveOsArchLabels} so the label shape is identical to
+* the host-reported form (e.g. `windows` yields both `kici:os:windows` and
+* `kici:os:win32`).
+*/
+function platformToOsArchLabels(platform) {
+	return deriveOsArchLabels(scalerOsToNodePlatform(platform.os), platform.arch);
+}
+/**
+* Derive the plain platform-taint labels for a declared structured platform.
+* Returns the canonical tokens (`macos`, `windows`, `arm64`) that a job's
+* `runsOn` must include to allocate on the pool. The linux/x64 default carries
+* no taint. Unlike {@link derivePlatformTaints} (which intersects declared
+* labels against a denylist), this derives from the structured field, so a pool
+* labeled `windows-2022` still taints correctly.
+*/
+function platformToTaints(platform) {
+	const taints = [];
+	if (platform.os === "macos") taints.push("macos");
+	else if (platform.os === "windows") taints.push("windows");
+	if (platform.arch === "arm64") taints.push("arm64");
+	return taints;
+}
+/** Map an `os.platform()` string to a `ScalerOs`, or null when unrecognised. */
+function nodePlatformToScalerOs(nodePlatform) {
+	switch (nodePlatform) {
+		case "linux": return "linux";
+		case "darwin": return "macos";
+		case "win32": return "windows";
+		default: return null;
+	}
+}
+/** Map an `os.arch()` string to a `ScalerArch`, or null when unrecognised. */
+function nodeArchToScalerArch(nodeArch) {
+	switch (nodeArch) {
+		case "x64": return "x64";
+		case "arm64": return "arm64";
+		default: return null;
+	}
+}
+/**
+* Build a structured platform from the host's `os.platform()` / `os.arch()`.
+* Returns null when either component is not one of the supported enum values,
+* so a caller can fall back to the legacy host-label derivation for exotic
+* hosts.
+*/
+function hostToScalerPlatform(nodePlatform, nodeArch) {
+	const os = nodePlatformToScalerOs(nodePlatform);
+	const arch = nodeArchToScalerArch(nodeArch);
+	return os && arch ? {
+		os,
+		arch
+	} : null;
+}
 /** Prefix for the agent self-reported hostname label. */
 const HOST_LABEL_PREFIX = "kici:host:";
 /**
@@ -234,6 +352,6 @@ function separateLabels(labels) {
 	};
 }
 //#endregion
-export { CAPABILITY_LABEL_PREFIX, HOST_LABEL_PREFIX, INIT_LABEL, KNOWN_ROLES, PRIVILEGED_ROOT_LABEL, RESERVED_LABEL_PREFIX, ROLE_LABEL_PREFIX, SELF_REPORTED_LABEL_PREFIXES, SSH_TRANSPORT_CAPABILITY, agentTypeLabel, capabilityLabel, deriveOsArchLabels, hostLabel, isAutoLabel, isSelfReportedLabel, mergeAutoLabels, normalizeRunsOn, parseHostLabel, resolveRoleLabels, roleToLabel, scalerAgentLabels, scalerLabel, separateLabels, validateNoReservedLabels };
+export { CAPABILITY_LABEL_PREFIX, HOST_LABEL_PREFIX, INIT_LABEL, KNOWN_ROLES, PLATFORM_TAINT_LABELS, PRIVILEGED_ROOT_LABEL, RESERVED_LABEL_PREFIX, ROLE_LABEL_PREFIX, SELF_REPORTED_LABEL_PREFIXES, SSH_TRANSPORT_CAPABILITY, ScalerArch, ScalerOs, agentTypeLabel, capabilityLabel, deriveOsArchLabels, derivePlatformTaints, hostLabel, hostToScalerPlatform, isAutoLabel, isSelfReportedLabel, mergeAutoLabels, nodeArchToScalerArch, nodePlatformToScalerOs, normalizeRunsOn, parseHostLabel, platformToOsArchLabels, platformToTaints, resolveRoleLabels, roleToLabel, scalerAgentLabels, scalerLabel, scalerPlatformSchema, separateLabels, validateNoReservedLabels };
 
 //# sourceMappingURL=labels.js.map

package/dist/matrix/expand.d.ts

@@ -17,6 +17,31 @@ export interface MatrixValues {
     /** Multi-dimensional: named properties */
     [dimension: string]: string | undefined;
 }
+/**
+ * Thrown when a matrix value does not match the documented contract — a
+ * `string[]` or a `Record<string, string[]>`. A static matrix is guaranteed by
+ * the lock-file schema, but a dynamic matrix returns arbitrary runtime data, so
+ * the contract has to be enforced here rather than by the type system.
+ */
+export declare class MatrixShapeError extends Error {
+    readonly name = "MatrixShapeError";
+    constructor(message: string);
+}
+/** A validated matrix input: dimensions sorted, elements coerced to strings. */
+export type NormalizedMatrix = {
+    kind: 'array';
+    values: string[];
+} | {
+    kind: 'object';
+    dimensions: Array<[name: string, values: string[]]>;
+};
+/**
+ * Validate and normalize a matrix value. Accepts the two documented shapes,
+ * coercing numeric and boolean elements to strings (they already reach job
+ * names as strings), and rejects everything else with the contract in the
+ * message. Dimensions are sorted here so expansion stays deterministic.
+ */
+export declare function normalizeMatrixInput(input: unknown): NormalizedMatrix;
 /**
  * Compute the cartesian product of the given value sets in row-major order.
  * An empty set list yields a single empty tuple; any empty set yields no tuples.
@@ -34,9 +59,31 @@ export declare function expandSingleDimension(matrix: StaticMatrixArray): Matrix
  */
 export declare function expandMultiDimension(matrix: StaticMatrixObject): MatrixValues[];
 /**
- * Unified expand function that dispatches to single or multi-dimensional expansion.
+ * Validated entry point: normalizes an untrusted matrix value, then dispatches
+ * to single- or multi-dimensional expansion. {@link expandSingleDimension} and
+ * {@link expandMultiDimension} remain available for a caller that already holds
+ * a typed value; this is the one to use for anything crossing a runtime
+ * boundary, such as the return value of a dynamic matrix function.
+ */
+export declare function expandMatrix(input: unknown): MatrixValues[];
+/**
+ * How many combinations a matrix would expand to, computed WITHOUT building
+ * them. Callers use this to refuse an oversized matrix before allocating it —
+ * the product is checked, never materialized.
+ */
+export declare function matrixCombinationCount(input: unknown): number;
+/**
+ * The first combination whose key collides with an earlier one, or `null` when
+ * every combination is distinct.
+ *
+ * `keyOf` decides what "the same combination" means. Callers that own a job name
+ * pass a renderer for the expanded name, because the collision that actually
+ * hurts is two children sharing a name — they are indistinguishable to an
+ * operator and ambiguous as a needs-edge target. Two structurally different
+ * combinations can still render the same name, so name-keying is strictly
+ * stronger than the structural default.
  */
-export declare function expandMatrix(matrix: StaticMatrixArray | StaticMatrixObject): MatrixValues[];
+export declare function findDuplicateCombination(combos: readonly MatrixValues[], keyOf?: (combo: MatrixValues) => string): MatrixValues | null;
 /**
  * Apply include/exclude modifications to expanded matrix combinations.
  * Exclude first (remove matching), then include (add new).

package/dist/matrix/expand.js

@@ -1,10 +1,65 @@
 import "../rolldown-runtime-ClRpJifh.js";
 //#region src/matrix/expand.ts
 /**
+* Thrown when a matrix value does not match the documented contract — a
+* `string[]` or a `Record<string, string[]>`. A static matrix is guaranteed by
+* the lock-file schema, but a dynamic matrix returns arbitrary runtime data, so
+* the contract has to be enforced here rather than by the type system.
+*/
+var MatrixShapeError = class MatrixShapeError extends Error {
+	name = "MatrixShapeError";
+	constructor(message) {
+		super(message);
+		Object.setPrototypeOf(this, MatrixShapeError.prototype);
+	}
+};
+/** Describe a rejected value for an error message, without dumping it wholesale. */
+function describeValue(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "string") return `a string (${JSON.stringify(value)})`;
+	if (typeof value === "object") return "an object";
+	return `a ${typeof value}`;
+}
+/** Coerce one matrix element, rejecting anything that has no sensible string form. */
+function coerceElement(value, where) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	throw new MatrixShapeError(`matrix ${where} must contain strings, got ${describeValue(value)}`);
+}
+/**
+* Validate and normalize a matrix value. Accepts the two documented shapes,
+* coercing numeric and boolean elements to strings (they already reach job
+* names as strings), and rejects everything else with the contract in the
+* message. Dimensions are sorted here so expansion stays deterministic.
+*/
+function normalizeMatrixInput(input) {
+	if (Array.isArray(input)) return {
+		kind: "array",
+		values: Array.from(input, (v, i) => coerceElement(v, `values[${i}]`))
+	};
+	if (input === null || typeof input !== "object") {
+		const suffix = typeof input === "string" ? " — a bare string is read as one dimension per character; split it into an array" : "";
+		throw new MatrixShapeError(`matrix must be a string array or an object of string arrays, got ${describeValue(input)}${suffix}`);
+	}
+	const dimensions = [];
+	for (const [name, values] of Object.entries(input)) {
+		if (!Array.isArray(values)) throw new MatrixShapeError(`matrix dimension "${name}" must be an array, got ${describeValue(values)}`);
+		dimensions.push([name, Array.from(values, (v, i) => coerceElement(v, `dimension "${name}"[${i}]`))]);
+	}
+	dimensions.sort((a, b) => a[0].localeCompare(b[0]));
+	return {
+		kind: "object",
+		dimensions
+	};
+}
+/**
 * Compute the cartesian product of the given value sets in row-major order.
 * An empty set list yields a single empty tuple; any empty set yields no tuples.
 */
 function cartesianProduct(sets) {
+	if (sets.some((set) => set.length === 0)) return [];
 	return sets.reduce((acc, set) => acc.flatMap((tuple) => set.map((value) => [...tuple, value])), [[]]);
 }
 /**
@@ -24,20 +79,54 @@ function expandMultiDimension(matrix) {
 	if (dimensions.length === 0) return [];
 	dimensions.sort((a, b) => a[0].localeCompare(b[0]));
 	const names = dimensions.map(([name]) => name);
-	return cartesianProduct(dimensions.map(([, values]) => values)).map((combo) => {
-		const result = {};
-		names.forEach((name, idx) => {
-			result[name] = combo[idx];
-		});
-		return result;
-	});
+	return cartesianProduct(dimensions.map(([, values]) => values)).map((combo) => Object.fromEntries(names.map((name, idx) => [name, combo[idx]])));
+}
+/**
+* Validated entry point: normalizes an untrusted matrix value, then dispatches
+* to single- or multi-dimensional expansion. {@link expandSingleDimension} and
+* {@link expandMultiDimension} remain available for a caller that already holds
+* a typed value; this is the one to use for anything crossing a runtime
+* boundary, such as the return value of a dynamic matrix function.
+*/
+function expandMatrix(input) {
+	const normalized = normalizeMatrixInput(input);
+	if (normalized.kind === "array") return expandSingleDimension(normalized.values);
+	return expandMultiDimension(Object.fromEntries(normalized.dimensions));
 }
 /**
-* Unified expand function that dispatches to single or multi-dimensional expansion.
+* How many combinations a matrix would expand to, computed WITHOUT building
+* them. Callers use this to refuse an oversized matrix before allocating it —
+* the product is checked, never materialized.
 */
-function expandMatrix(matrix) {
-	if (Array.isArray(matrix)) return expandSingleDimension(matrix);
-	return expandMultiDimension(matrix);
+function matrixCombinationCount(input) {
+	const normalized = normalizeMatrixInput(input);
+	if (normalized.kind === "array") return normalized.values.length;
+	if (normalized.dimensions.length === 0) return 0;
+	return normalized.dimensions.reduce((acc, [, values]) => acc * values.length, 1);
+}
+/** Stable identity for a combination: its key/value pairs, key-sorted. */
+function combinationKey(combo) {
+	return JSON.stringify(Object.entries(combo).filter(([, value]) => value !== void 0).sort((a, b) => a[0].localeCompare(b[0])));
+}
+/**
+* The first combination whose key collides with an earlier one, or `null` when
+* every combination is distinct.
+*
+* `keyOf` decides what "the same combination" means. Callers that own a job name
+* pass a renderer for the expanded name, because the collision that actually
+* hurts is two children sharing a name — they are indistinguishable to an
+* operator and ambiguous as a needs-edge target. Two structurally different
+* combinations can still render the same name, so name-keying is strictly
+* stronger than the structural default.
+*/
+function findDuplicateCombination(combos, keyOf = combinationKey) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const combo of combos) {
+		const key = keyOf(combo);
+		if (seen.has(key)) return combo;
+		seen.add(key);
+	}
+	return null;
 }
 /**
 * Apply include/exclude modifications to expanded matrix combinations.
@@ -62,11 +151,11 @@ function applyIncludeExclude(expanded, include, exclude) {
 			const comboKeys = Object.keys(combo);
 			if (inclKeys.length !== comboKeys.length) return false;
 			return inclKeys.every((key) => combo[key] === incl[key]);
-		})) result.push(incl);
+		})) result.push(Object.fromEntries([...inclKeys].sort((a, b) => a.localeCompare(b)).map((key) => [key, incl[key]])));
 	}
 	return result;
 }
 //#endregion
-export { applyIncludeExclude, cartesianProduct, expandMatrix, expandMultiDimension, expandSingleDimension };
+export { MatrixShapeError, applyIncludeExclude, cartesianProduct, expandMatrix, expandMultiDimension, expandSingleDimension, findDuplicateCombination, matrixCombinationCount, normalizeMatrixInput };
 
 //# sourceMappingURL=expand.js.map

package/dist/matrix/format.d.ts

@@ -5,6 +5,11 @@ import type { MatrixValues } from './expand.js';
  * Multi-dimensional: "linux, 18"
  */
 export declare function formatMatrixSuffix(matrixValues: MatrixValues): string;
-/** Expanded child job name: `${baseName} (${suffix})`. MUST match the local executor. */
+/**
+ * Expanded child job name: `${baseName} (${suffix})`. The `(...)` wrapper is
+ * load-bearing, not decoration: `variantLabelOf` (fanout/materialize.ts) and
+ * `buildMatrixOutputsEnvelope` (the orchestrator's `byMatrix` key) both recover
+ * the suffix by slicing it back out of the name.
+ */
 export declare function formatExpandedJobName(baseName: string, matrixValues: MatrixValues): string;
 //# sourceMappingURL=format.d.ts.map

package/dist/matrix/format.js

@@ -10,7 +10,12 @@ function formatMatrixSuffix(matrixValues) {
 	if (defined.length === 1 && defined[0][0] === "value") return defined[0][1];
 	return defined.map(([, v]) => v).join(", ");
 }
-/** Expanded child job name: `${baseName} (${suffix})`. MUST match the local executor. */
+/**
+* Expanded child job name: `${baseName} (${suffix})`. The `(...)` wrapper is
+* load-bearing, not decoration: `variantLabelOf` (fanout/materialize.ts) and
+* `buildMatrixOutputsEnvelope` (the orchestrator's `byMatrix` key) both recover
+* the suffix by slicing it back out of the name.
+*/
 function formatExpandedJobName(baseName, matrixValues) {
 	return `${baseName} (${formatMatrixSuffix(matrixValues)})`;
 }

package/dist/mcp/held-run-resolve.d.ts

@@ -1,13 +1,3 @@
-/**
- * Shared held-run resolution for the `kici approve` / `kici reject` commands and
- * the developer MCP `approve_run` / `reject_run` tools.
- *
- * Both surfaces first list the pending holds for a run, then resolve the one
- * the caller named via `job` / `step` (or the sole pending hold when there is
- * exactly one and no filter is given). The resolution is a pure function so it
- * can be unit-tested without HTTP, and it stays import-free so it is safe to
- * re-export from the browser-facing engine barrel.
- */
 /** Hold scope, mirroring the engine `HoldScope` enum. */
 export type HeldRunScope = 'workflow' | 'job' | 'step';
 /** A pending-hold row as returned by the held-runs list. */
@@ -18,6 +8,13 @@ export interface HeldRunSummary {
     holdScope?: HeldRunScope;
     stepIndex?: number | null;
     status: string;
+    /**
+     * Persisted `held_runs.hold_type`, when the orchestrator's list response
+     * carried one. Optional and un-normalized: callers pass it through
+     * `normalizePersistedHoldType` before branching. Absent from an older
+     * orchestrator's response.
+     */
+    holdType?: string;
     /** Computed drift payload for a `when: 'drift'` step hold; absent otherwise. */
     payload?: {
         summaryMarkdown: string;

package/dist/mcp/held-run-resolve.js

@@ -1,6 +1,32 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { HeldRunStatus } from "../context/held-run-status.js";
 //#region src/mcp/held-run-resolve.ts
 /**
+* Shared held-run resolution for the `kici approve` / `kici reject` commands and
+* the developer MCP `approve_run` / `reject_run` tools.
+*
+* Both surfaces first list the pending holds for a run, then resolve the one
+* the caller named via `job` / `step` (or the sole pending hold when there is
+* exactly one and no filter is given). The resolution is a pure function so it
+* can be unit-tested without HTTP, and it imports nothing beyond the shared
+* held-run vocabulary, so it is safe to re-export from the browser-facing
+* engine barrel.
+*/
+/**
+* Name a hold the way the caller would type it: the literal `jobId` (so an
+* `__install__…` sentinel or an opaque legacy id is reproduced verbatim), with
+* the step index prefixed for a step-scoped hold.
+*/
+function describeHold(hold) {
+	const job = hold.jobId || "(unnamed hold)";
+	if (hold.holdScope === "step" && hold.stepIndex != null) return `step ${hold.stepIndex} of ${job}`;
+	return job;
+}
+/** The distinct hold descriptions, in listing order, for an error message. */
+function listCandidates(holds) {
+	return [...new Set(holds.map(describeHold))].join(", ");
+}
+/**
 * Resolve the held-run id matching the filter from a list of pending holds.
 *
 * - `step` requires `job` and matches a `step`-scoped hold whose step index
@@ -9,7 +35,7 @@ import "../rolldown-runtime-ClRpJifh.js";
 * - With no filter, the sole pending hold is used; ambiguity is an error.
 */
 function resolveHeldRunId(holds, filter) {
-	const pending = holds.filter((h) => h.status === "pending");
+	const pending = holds.filter((h) => h.status === HeldRunStatus.enum.pending);
 	if (pending.length === 0) return {
 		ok: false,
 		error: "No pending approval holds found for this run."
@@ -19,12 +45,12 @@ function resolveHeldRunId(holds, filter) {
 			ok: false,
 			error: "--step requires --job to identify the held step."
 		};
-		return pickSingle(pending.filter((h) => h.holdScope === "step" && h.jobId === filter.job && String(h.stepIndex ?? "") === filter.step), `step ${filter.step} of job '${filter.job}'`);
+		return pickSingle(pending.filter((h) => h.holdScope === "step" && h.jobId === filter.job && String(h.stepIndex ?? "") === filter.step), `step ${filter.step} of job '${filter.job}'`, pending);
 	}
-	if (filter.job !== void 0) return pickSingle(pending.filter((h) => h.jobId === filter.job && h.holdScope !== "step"), `job '${filter.job}'`);
+	if (filter.job !== void 0) return pickSingle(pending.filter((h) => h.jobId === filter.job && h.holdScope !== "step"), `job '${filter.job}'`, pending);
 	if (pending.length > 1) return {
 		ok: false,
-		error: "Multiple pending holds for this run. Use --job <name> (and --step <index>) to choose one."
+		error: `Multiple pending holds for this run. Use --job <name> (and --step <index>) to choose one. Candidates: ${listCandidates(pending)}.`
 	};
 	return {
 		ok: true,
@@ -32,14 +58,14 @@ function resolveHeldRunId(holds, filter) {
 		hold: pending[0]
 	};
 }
-function pickSingle(matches, label) {
+function pickSingle(matches, label, pending) {
 	if (matches.length === 0) return {
 		ok: false,
-		error: `No pending hold found for ${label}.`
+		error: `No pending hold found for ${label}. Pending holds: ${listCandidates(pending)}.`
 	};
 	if (matches.length > 1) return {
 		ok: false,
-		error: `Multiple pending holds match ${label}; cannot disambiguate.`
+		error: `Multiple pending holds match ${label}; cannot disambiguate. Candidates: ${listCandidates(matches)}.`
 	};
 	return {
 		ok: true,

package/dist/metrics/catalog-policy.js

@@ -259,10 +259,6 @@ const METRIC_LABEL_POLICY = {
 		"v8js.gc.type": { maxUniqueValues: 6 },
 		scaler: { values: AGENT_SCALER_VALUES }
 	},
-	"v8js.memory.heap.limit": {
-		"v8js.heap.space.name": { maxUniqueValues: 20 },
-		scaler: { values: AGENT_SCALER_VALUES }
-	},
 	"v8js.memory.heap.used": {
 		"v8js.heap.space.name": { maxUniqueValues: 20 },
 		scaler: { values: AGENT_SCALER_VALUES }
@@ -274,6 +270,10 @@ const METRIC_LABEL_POLICY = {
 	"v8js.memory.heap.space.physical_size": {
 		"v8js.heap.space.name": { maxUniqueValues: 20 },
 		scaler: { values: AGENT_SCALER_VALUES }
+	},
+	"v8js.resource.active": {
+		"v8js.resource.type": { maxUniqueValues: 20 },
+		scaler: { values: AGENT_SCALER_VALUES }
 	}
 };
 //#endregion