@kici-dev/engine 0.4.0 → 0.6.0

package/dist/labels.d.ts

@@ -175,6 +175,38 @@ export declare function capabilityLabel(name: string): string;
  * the bootstrap SSH key.
  */
 export declare const SSH_TRANSPORT_CAPABILITY = "kici:capability:ssh-transport";
+/**
+ * Runtime-fact label prefix — `kici:runtime:<name>` states something the AGENT
+ * discovered about its own host.
+ *
+ * Deliberately NOT `kici:capability:`. That prefix grants a privilege
+ * (`ssh-transport` custodies the bootstrap SSH key), so it must stay
+ * token-bound and an agent must never be able to self-assert it. A runtime fact
+ * grants nothing: it reports what the host can do, the way `kici:os:` reports
+ * what the host is, and it is self-reported for the same reason — the scaler
+ * cannot predict it at token-mint time.
+ */
+export declare const RUNTIME_LABEL_PREFIX = "kici:runtime:";
+/** Build a `kici:runtime:<name>` label. */
+export declare function runtimeLabel(name: string): string;
+/**
+ * Runtime facts an agent reports about its own host at registration.
+ *
+ * - `docker` / `podman` — that container runtime's socket answered, so the
+ *   agent can nest a job container.
+ * - `container-build` — a `docker` / `podman` CLI is on PATH, so the agent can
+ *   build a job's image from a Dockerfile. Distinct from the two above: a host
+ *   reachable only through a mounted socket can RUN containers but not BUILD
+ *   one, because the build shells out to the CLI.
+ */
+export declare const RuntimeFact: z.ZodEnum<{
+    "container-build": "container-build";
+    docker: "docker";
+    podman: "podman";
+}>;
+export type RuntimeFact = z.infer<typeof RuntimeFact>;
+/** The label a job's `runsOn` names to require a host that can build an image. */
+export declare const CONTAINER_BUILD_RUNTIME_LABEL: string;
 /**
  * The `kici:init` lifecycle label carried by a temporary init-runner agent
  * brought up on a fresh box for bootstrap. Marks it as ephemeral + privileged;
@@ -194,6 +226,14 @@ export declare const ROLE_LABEL_PREFIX = "kici:role:";
  * Convert a role name to its corresponding label.
  */
 export declare function roleToLabel(role: AgentRole): string;
+/**
+ * The label every pre-run evaluation job routes to.
+ *
+ * Exported because three dispatch sites and the global eval round all target
+ * it, and each had spelled the string out. Derived from {@link roleToLabel} so
+ * it cannot drift from the prefix or from `KNOWN_ROLES`.
+ */
+export declare const INIT_RUNNER_ROLE_LABEL: string;
 /**
  * Resolve a roles configuration into role labels.
  *
@@ -205,22 +245,44 @@ export declare function roleToLabel(role: AgentRole): string;
 export declare function resolveRoleLabels(roles: readonly string[] | undefined): string[];
 /**
  * The full label set a scaler injects into an agent it spawns: the base label
- * set plus the scaler-assigned `kici:agent:`, `kici:scaler:`, and `kici:role:`
- * labels. This is exactly what the scaler writes into `KICI_LABELS`, and it is
- * the set an ephemeral agent token must be bound to — the agent then adds only
- * the self-reported platform facts (`kici:os:`, `kici:arch:`, `kici:host:`) at
- * registration, which the orchestrator's register-time scope gate exempts (see
- * `isSelfReportedLabel`). Keep this aligned with the agent's wire-label
- * construction in `orchestrator-client.ts#sendAgentRegister`.
+ * set plus the scaler-assigned `kici:agent:`, `kici:scaler:`, `kici:role:`, and
+ * platform-taint labels. This is exactly what the scaler writes into
+ * `KICI_LABELS`, and it is the set an ephemeral agent token must be bound to —
+ * the agent then adds only the self-reported platform facts (`kici:os:`,
+ * `kici:arch:`, `kici:host:`) at registration, which the orchestrator's
+ * register-time scope gate exempts (see `isSelfReportedLabel`). Keep this
+ * aligned with the agent's wire-label construction in
+ * `orchestrator-client.ts#sendAgentRegister`.
+ *
+ * `platformTaints` are the plain tokens (`windows`, `macos`, `arm64`) derived
+ * from the pool's resolved platform. A taint is a routing GRANT, not a host
+ * fact: it is what a job's `runsOn` names to reach this pool, and the matcher
+ * gates on it. So the orchestrator asserts it here — bound into the agent's
+ * ephemeral token — rather than letting the agent self-report it. Adding these
+ * prefixes to `SELF_REPORTED_LABEL_PREFIXES` instead would let any agent claim
+ * any platform unchallenged, which is the opposite of a gate. The caller must
+ * derive them from the same source the gate uses
+ * (`ScalerManager.resolveScalerPlatform`) — deriving them twice is exactly the
+ * defect this parameter closes.
+ *
+ * The result is de-duplicated in first-seen order: a warm pool measures its
+ * readiness with a label set that already carries the taints, so it passes them
+ * as `labelSet` AND as `platformTaints`, and a label repeated in the set an
+ * ephemeral token is bound to is never meaningful.
  */
-export declare function scalerAgentLabels(labelSet: string[], backendType: string, backendName: string, roles: readonly string[] | undefined): string[];
+export declare function scalerAgentLabels(labelSet: string[], backendType: string, backendName: string, roles: readonly string[] | undefined, platformTaints?: readonly string[]): string[];
 /**
  * Label-category prefixes the agent self-reports at registration from its own
- * host (operating system, CPU architecture, hostname). They are immutable
- * 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.
+ * host: operating system, CPU architecture, hostname, and runtime facts. They
+ * are 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.
+ *
+ * Adding a prefix here lets any agent assert it unchallenged. That is correct
+ * for a fact about the host and WRONG for anything that grants a privilege —
+ * `kici:capability:` is absent from this list for exactly that reason.
  */
-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:', "kici:runtime:"];
 /**
  * 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

@@ -253,6 +253,39 @@ function capabilityLabel(name) {
 */
 const SSH_TRANSPORT_CAPABILITY = "kici:capability:ssh-transport";
 /**
+* Runtime-fact label prefix — `kici:runtime:<name>` states something the AGENT
+* discovered about its own host.
+*
+* Deliberately NOT `kici:capability:`. That prefix grants a privilege
+* (`ssh-transport` custodies the bootstrap SSH key), so it must stay
+* token-bound and an agent must never be able to self-assert it. A runtime fact
+* grants nothing: it reports what the host can do, the way `kici:os:` reports
+* what the host is, and it is self-reported for the same reason — the scaler
+* cannot predict it at token-mint time.
+*/
+const RUNTIME_LABEL_PREFIX = "kici:runtime:";
+/** Build a `kici:runtime:<name>` label. */
+function runtimeLabel(name) {
+	return `${RUNTIME_LABEL_PREFIX}${name}`;
+}
+/**
+* Runtime facts an agent reports about its own host at registration.
+*
+* - `docker` / `podman` — that container runtime's socket answered, so the
+*   agent can nest a job container.
+* - `container-build` — a `docker` / `podman` CLI is on PATH, so the agent can
+*   build a job's image from a Dockerfile. Distinct from the two above: a host
+*   reachable only through a mounted socket can RUN containers but not BUILD
+*   one, because the build shells out to the CLI.
+*/
+const RuntimeFact = z.enum([
+	"docker",
+	"podman",
+	"container-build"
+]);
+/** The label a job's `runsOn` names to require a host that can build an image. */
+const CONTAINER_BUILD_RUNTIME_LABEL = runtimeLabel(RuntimeFact.enum["container-build"]);
+/**
 * The `kici:init` lifecycle label carried by a temporary init-runner agent
 * brought up on a fresh box for bootstrap. Marks it as ephemeral + privileged;
 * it dies on reboot and is reaped. Distinct from `kici:role:init-runner`
@@ -274,6 +307,14 @@ function roleToLabel(role) {
 	return `${ROLE_LABEL_PREFIX}${role}`;
 }
 /**
+* The label every pre-run evaluation job routes to.
+*
+* Exported because three dispatch sites and the global eval round all target
+* it, and each had spelled the string out. Derived from {@link roleToLabel} so
+* it cannot drift from the prefix or from `KNOWN_ROLES`.
+*/
+const INIT_RUNNER_ROLE_LABEL = roleToLabel("init-runner");
+/**
 * Resolve a roles configuration into role labels.
 *
 * - undefined → all roles (backward compat: existing agents get all capabilities)
@@ -289,32 +330,56 @@ function resolveRoleLabels(roles) {
 }
 /**
 * The full label set a scaler injects into an agent it spawns: the base label
-* set plus the scaler-assigned `kici:agent:`, `kici:scaler:`, and `kici:role:`
-* labels. This is exactly what the scaler writes into `KICI_LABELS`, and it is
-* the set an ephemeral agent token must be bound to — the agent then adds only
-* the self-reported platform facts (`kici:os:`, `kici:arch:`, `kici:host:`) at
-* registration, which the orchestrator's register-time scope gate exempts (see
-* `isSelfReportedLabel`). Keep this aligned with the agent's wire-label
-* construction in `orchestrator-client.ts#sendAgentRegister`.
-*/
-function scalerAgentLabels(labelSet, backendType, backendName, roles) {
-	return [
+* set plus the scaler-assigned `kici:agent:`, `kici:scaler:`, `kici:role:`, and
+* platform-taint labels. This is exactly what the scaler writes into
+* `KICI_LABELS`, and it is the set an ephemeral agent token must be bound to —
+* the agent then adds only the self-reported platform facts (`kici:os:`,
+* `kici:arch:`, `kici:host:`) at registration, which the orchestrator's
+* register-time scope gate exempts (see `isSelfReportedLabel`). Keep this
+* aligned with the agent's wire-label construction in
+* `orchestrator-client.ts#sendAgentRegister`.
+*
+* `platformTaints` are the plain tokens (`windows`, `macos`, `arm64`) derived
+* from the pool's resolved platform. A taint is a routing GRANT, not a host
+* fact: it is what a job's `runsOn` names to reach this pool, and the matcher
+* gates on it. So the orchestrator asserts it here — bound into the agent's
+* ephemeral token — rather than letting the agent self-report it. Adding these
+* prefixes to `SELF_REPORTED_LABEL_PREFIXES` instead would let any agent claim
+* any platform unchallenged, which is the opposite of a gate. The caller must
+* derive them from the same source the gate uses
+* (`ScalerManager.resolveScalerPlatform`) — deriving them twice is exactly the
+* defect this parameter closes.
+*
+* The result is de-duplicated in first-seen order: a warm pool measures its
+* readiness with a label set that already carries the taints, so it passes them
+* as `labelSet` AND as `platformTaints`, and a label repeated in the set an
+* ephemeral token is bound to is never meaningful.
+*/
+function scalerAgentLabels(labelSet, backendType, backendName, roles, platformTaints = []) {
+	return [.../* @__PURE__ */ new Set([
 		...labelSet,
 		agentTypeLabel(backendType),
 		scalerLabel(backendName),
-		...resolveRoleLabels(roles)
-	];
+		...resolveRoleLabels(roles),
+		...platformTaints
+	])];
 }
 /**
 * Label-category prefixes the agent self-reports at registration from its own
-* host (operating system, CPU architecture, hostname). They are immutable
-* 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.
+* host: operating system, CPU architecture, hostname, and runtime facts. They
+* are 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.
+*
+* Adding a prefix here lets any agent assert it unchallenged. That is correct
+* for a fact about the host and WRONG for anything that grants a privilege —
+* `kici:capability:` is absent from this list for exactly that reason.
 */
 const SELF_REPORTED_LABEL_PREFIXES = [
 	"kici:os:",
 	"kici:arch:",
-	"kici:host:"
+	"kici:host:",
+	RUNTIME_LABEL_PREFIX
 ];
 /**
 * True if a label is a self-reported platform fact (os/arch/host) rather than a
@@ -352,6 +417,6 @@ function separateLabels(labels) {
 	};
 }
 //#endregion
-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 };
+export { CAPABILITY_LABEL_PREFIX, CONTAINER_BUILD_RUNTIME_LABEL, HOST_LABEL_PREFIX, INIT_LABEL, INIT_RUNNER_ROLE_LABEL, KNOWN_ROLES, PLATFORM_TAINT_LABELS, PRIVILEGED_ROOT_LABEL, RESERVED_LABEL_PREFIX, ROLE_LABEL_PREFIX, RUNTIME_LABEL_PREFIX, RuntimeFact, 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, runtimeLabel, scalerAgentLabels, scalerLabel, scalerPlatformSchema, separateLabels, validateNoReservedLabels };
 
 //# sourceMappingURL=labels.js.map

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

@@ -15,6 +15,17 @@ export interface HeldRunSummary {
      * orchestrator's response.
      */
     holdType?: string;
+    /**
+     * Bound context that requested the hold, when the row carries one. Null once
+     * the context is deleted, and absent from an older orchestrator's response.
+     */
+    contextName?: string | null;
+    /** Persisted `held_runs.queue_type` (`context` / `security`), when present. */
+    queueType?: string;
+    /** Why the hold was requested, when the row carries a reason. */
+    reason?: string | null;
+    /** When the hold expires, as an ISO timestamp; null when it never does. */
+    expiresAt?: string | null;
     /** Computed drift payload for a `when: 'drift'` step hold; absent otherwise. */
     payload?: {
         summaryMarkdown: string;
@@ -27,6 +38,26 @@ export interface HeldRunFilter {
     job?: string;
     /** Match a step-scoped hold by its step index (compared as a string). */
     step?: string;
+    /**
+     * Match one hold by its own id, ignoring every other filter.
+     *
+     * The escape hatch for an ambiguity nothing else can resolve. A job can carry
+     * more than one pending hold — an SDK `requireApproval` and a security-typed
+     * context gate produce two job-scoped rows under one job name — and while
+     * {@link holdType} separates that pair, nothing guarantees a future pair
+     * differs in type. An id always does, and the candidate list prints the ids
+     * whenever two holds are otherwise indistinguishable.
+     */
+    holdId?: string;
+    /**
+     * Narrow to holds of one type (`reviewer` / `timer` / `concurrency` /
+     * `security`), normalized through `normalizePersistedHoldType` on both sides
+     * so a legacy `approval` row answers to `reviewer`.
+     *
+     * Composes with {@link job} / {@link step} rather than replacing them: a
+     * matrix whose children each carry two holds needs both halves.
+     */
+    holdType?: string;
 }
 /** Resolution result: either a held-run id or a user-facing error message. */
 export type ResolveResult = {
@@ -40,10 +71,19 @@ export type ResolveResult = {
 /**
  * Resolve the held-run id matching the filter from a list of pending holds.
  *
+ * - `holdId` names one hold outright and ignores every other filter.
  * - `step` requires `job` and matches a `step`-scoped hold whose step index
  *   equals the given value.
  * - `job` alone matches a `job`/`workflow`-scoped hold for that job.
+ * - `holdType` narrows whichever set the above produced, and may be used on its
+ *   own.
  * - With no filter, the sole pending hold is used; ambiguity is an error.
+ *
+ * One job can carry more than one pending hold: an SDK `requireApproval` paired
+ * with a security-typed context gate writes two job-scoped rows under one job
+ * name, because two independent requirements gate the job and both must be
+ * answered. `job` alone cannot separate those, which is what `holdType` and
+ * `holdId` are for.
  */
 export declare function resolveHeldRunId(holds: readonly HeldRunSummary[], filter: HeldRunFilter): ResolveResult;
 //# sourceMappingURL=held-run-resolve.d.ts.map

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

@@ -1,38 +1,86 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { HeldRunStatus } from "../context/held-run-status.js";
+import { normalizePersistedHoldType } from "../context/hold-type.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.
+* Both surfaces first list the pending holds for a run, then resolve the one the
+* caller named via `job` / `step` / `holdType` / `holdId` (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.
+*
+* A job name is not a unique key: two independent requirements can gate one job,
+* and each writes its own pending row under that name. So every ambiguity path
+* here has to end at a filter that can actually separate them, and the candidate
+* list has to print enough for the caller to pick one.
 */
 /**
 * 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.
+* the step index prefixed for a step-scoped hold, and the hold type appended.
+*
+* The type is what makes the candidate list actionable when one job carries two
+* holds — without it both rows rendered as the bare job name, so the list
+* collapsed to a single entry and named a `--job` filter that could not tell
+* them apart. It is omitted when the orchestrator's list response carried none
+* (an older build), which renders exactly as it did before.
 */
 function describeHold(hold) {
 	const job = hold.jobId || "(unnamed hold)";
-	if (hold.holdScope === "step" && hold.stepIndex != null) return `step ${hold.stepIndex} of ${job}`;
-	return job;
+	const base = hold.holdScope === "step" && hold.stepIndex != null ? `step ${hold.stepIndex} of ${job}` : job;
+	return hold.holdType ? `${base} (${normalizePersistedHoldType(hold.holdType)})` : base;
 }
-/** The distinct hold descriptions, in listing order, for an error message. */
+/**
+* The hold descriptions, in listing order, for an error message.
+*
+* A description that occurs once is listed once. One that occurs more than once
+* is listed per hold WITH its id, because at that point the description alone
+* cannot name which hold the caller means and `--hold <id>` is the only filter
+* left that can. Silently de-duplicating those is what made the old message
+* offer a disambiguator it had already discarded the information for.
+*/
 function listCandidates(holds) {
-	return [...new Set(holds.map(describeHold))].join(", ");
+	const counts = /* @__PURE__ */ new Map();
+	for (const hold of holds) {
+		const text = describeHold(hold);
+		counts.set(text, (counts.get(text) ?? 0) + 1);
+	}
+	const emitted = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const hold of holds) {
+		const text = describeHold(hold);
+		if ((counts.get(text) ?? 0) > 1) {
+			out.push(`${text} [${hold.id}]`);
+			continue;
+		}
+		if (emitted.has(text)) continue;
+		emitted.add(text);
+		out.push(text);
+	}
+	return out.join(", ");
 }
+/** The disambiguators a caller can reach for, named the way the CLI spells them. */
+const DISAMBIGUATORS = "--job <name>, --step <index>, --hold-type <type> or --hold <id>";
 /**
 * Resolve the held-run id matching the filter from a list of pending holds.
 *
+* - `holdId` names one hold outright and ignores every other filter.
 * - `step` requires `job` and matches a `step`-scoped hold whose step index
 *   equals the given value.
 * - `job` alone matches a `job`/`workflow`-scoped hold for that job.
+* - `holdType` narrows whichever set the above produced, and may be used on its
+*   own.
 * - With no filter, the sole pending hold is used; ambiguity is an error.
+*
+* One job can carry more than one pending hold: an SDK `requireApproval` paired
+* with a security-typed context gate writes two job-scoped rows under one job
+* name, because two independent requirements gate the job and both must be
+* answered. `job` alone cannot separate those, which is what `holdType` and
+* `holdId` are for.
 */
 function resolveHeldRunId(holds, filter) {
 	const pending = holds.filter((h) => h.status === HeldRunStatus.enum.pending);
@@ -40,17 +88,22 @@ function resolveHeldRunId(holds, filter) {
 		ok: false,
 		error: "No pending approval holds found for this run."
 	};
+	if (filter.holdId !== void 0) return pickSingle(pending.filter((h) => h.id === filter.holdId), `hold '${filter.holdId}'`, pending);
+	const wanted = filter.holdType && normalizePersistedHoldType(filter.holdType);
+	const byType = (candidates) => wanted === void 0 ? candidates : candidates.filter((h) => h.holdType && normalizePersistedHoldType(h.holdType) === wanted);
+	const typeLabel = wanted ? ` of type '${wanted}'` : "";
 	if (filter.step !== void 0) {
 		if (!filter.job) return {
 			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}'`, pending);
+		return pickSingle(byType(pending.filter((h) => h.holdScope === "step" && h.jobId === filter.job && String(h.stepIndex ?? "") === filter.step)), `step ${filter.step} of job '${filter.job}'${typeLabel}`, pending);
 	}
-	if (filter.job !== void 0) return pickSingle(pending.filter((h) => h.jobId === filter.job && h.holdScope !== "step"), `job '${filter.job}'`, pending);
+	if (filter.job !== void 0) return pickSingle(byType(pending.filter((h) => h.jobId === filter.job && h.holdScope !== "step")), `job '${filter.job}'${typeLabel}`, pending);
+	if (wanted !== void 0) return pickSingle(byType(pending), `hold type '${wanted}'`, pending);
 	if (pending.length > 1) return {
 		ok: false,
-		error: `Multiple pending holds for this run. Use --job <name> (and --step <index>) to choose one. Candidates: ${listCandidates(pending)}.`
+		error: `Multiple pending holds for this run. Use ${DISAMBIGUATORS} to choose one. Candidates: ${listCandidates(pending)}.`
 	};
 	return {
 		ok: true,
@@ -65,7 +118,7 @@ function pickSingle(matches, label, pending) {
 	};
 	if (matches.length > 1) return {
 		ok: false,
-		error: `Multiple pending holds match ${label}; cannot disambiguate. Candidates: ${listCandidates(matches)}.`
+		error: `Multiple pending holds match ${label}. Narrow it with ${DISAMBIGUATORS}. Candidates: ${listCandidates(matches)}.`
 	};
 	return {
 		ok: true,

package/dist/mcp/tool-schemas.d.ts

@@ -59,12 +59,16 @@ export declare const approveRunToolSchema: {
     runId: z.ZodString;
     job: z.ZodOptional<z.ZodString>;
     step: z.ZodOptional<z.ZodString>;
+    holdType: z.ZodOptional<z.ZodString>;
+    holdId: z.ZodOptional<z.ZodString>;
 };
 export declare const rejectRunToolSchema: {
     orgId: z.ZodOptional<z.ZodString>;
     runId: z.ZodString;
     job: z.ZodOptional<z.ZodString>;
     step: z.ZodOptional<z.ZodString>;
+    holdType: z.ZodOptional<z.ZodString>;
+    holdId: z.ZodOptional<z.ZodString>;
     reason: z.ZodString;
 };
 export declare const cancelRunsByBranchToolSchema: {

package/dist/mcp/tool-schemas.js

@@ -55,17 +55,29 @@ const triggerRunToolSchema = {
 	orgId: orgIdArg,
 	registrationId: z.string().min(1).describe("The workflow registration id to trigger.")
 };
+/**
+* The two filters that separate holds a job name cannot. One job can carry more
+* than one pending hold — an SDK `requireApproval` paired with a security-typed
+* context gate writes two job-scoped rows under one job name — so `job` alone is
+* ambiguous for that shape, and the error listing names these instead.
+*/
+const holdTypeArg = z.string().optional().describe("Hold type (reviewer, timer, concurrency, security), when one job carries more than one hold.");
+const holdIdArg = z.string().optional().describe("A specific hold id, as printed in the candidate list when nothing else separates them.");
 const approveRunToolSchema = {
 	orgId: orgIdArg,
 	runId: z.string().min(1).describe("The run whose held approval gate to approve."),
 	job: z.string().optional().describe("Job name, to disambiguate when the run has multiple holds."),
-	step: z.string().optional().describe("Zero-based step index (requires job) for a step-scoped hold.")
+	step: z.string().optional().describe("Zero-based step index (requires job) for a step-scoped hold."),
+	holdType: holdTypeArg,
+	holdId: holdIdArg
 };
 const rejectRunToolSchema = {
 	orgId: orgIdArg,
 	runId: z.string().min(1).describe("The run whose held approval gate to reject."),
 	job: z.string().optional().describe("Job name, to disambiguate when the run has multiple holds."),
 	step: z.string().optional().describe("Zero-based step index (requires job) for a step-scoped hold."),
+	holdType: holdTypeArg,
+	holdId: holdIdArg,
 	reason: z.string().min(1).describe("Why the gate is rejected (required).")
 };
 const cancelRunsByBranchToolSchema = {

package/dist/metrics/catalog-policy.d.ts

@@ -55,10 +55,24 @@ export declare const ORCH_PUSHED_METRIC_NAMES: ReadonlySet<MetricName>;
 /**
  * Closed enum of scaler-backend TYPE values the orchestrator's own
  * resource-usage gauges carry on their `scalerType` rollup label.
- * `__global__` is the orchestrator-wide rollup row; the other four match
- * `AGENT_SCALER_VALUES`. Exported so the policy tests can assert against it.
+ * `__global__` is the orchestrator-wide rollup row; every other value comes
+ * from `ScalerManager`'s own `backends` map, so the enum is `ScalerBackendType`
+ * itself — NOT `AGENT_SCALER_VALUES`, which additionally carries the
+ * agent-only `stateful` and predates the `event` backend. Exported so the
+ * policy tests can assert against it.
  */
-export declare const ORCH_SCALER_VALUES: readonly ["__global__", "stateful", "container", "firecracker", "bare-metal"];
+export declare const ORCH_SCALER_VALUES: readonly ["__global__", ...("bare-metal" | "container" | "event" | "firecracker" | "kubernetes")[]];
+/**
+ * Closed enum of the scheduled jobs the orchestrator runs. MUST mirror
+ * `OrchestratorScheduledJobName` (`packages/orchestrator/src/queue/scheduled-job.ts`)
+ * exactly — a job missing here has its whole `kici_orch_job_*` series
+ * dropped by the Platform filter with `reason="bad_label_value"`, so the
+ * job silently loses every health metric. The engine cannot import the
+ * orchestrator (dependency runs the other way), so the parity assertion
+ * lives on the orchestrator side in `scheduled-job.test.ts`. Exported so
+ * that test can assert against it.
+ */
+export declare const ORCH_JOB_VALUES: readonly ['cleanup', 'orphan-secret-cleanup', 'token-cleanup', 'cold-store-archive', 'cold-store-purge', 'unroutable-probe'];
 /**
  * Per-metric, per-label value policy. Missing entries (or missing label
  * keys within an entry) mean "no value-level constraint" — the label key

package/dist/metrics/catalog-policy.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { ExecutionRunStatus } from "../protocol/messages/execution-status.js";
+import { ScalerBackendType } from "../scaler/scaler-backend-type.js";
 import { MetricNames, MetricService } from "./metric-catalog.generated.js";
 //#region src/metrics/catalog-policy.ts
 /**
@@ -41,27 +42,43 @@ const OVERFLOW_LABEL_VALUE = "__overflow__";
 * so they are valid push payloads alongside `kici_orch_*`.
 */
 const ORCH_PUSHED_METRIC_NAMES = new Set(Object.entries(MetricService).filter(([, svc]) => svc === "orchestrator" || svc === "agent" || svc === "runtime").map(([key]) => MetricNames[key]));
-/** Closed enum of the four scaler-backend label values an agent can carry. */
-const AGENT_SCALER_VALUES = [
-	"stateful",
-	"container",
-	"firecracker",
-	"bare-metal"
-];
+/**
+* Closed enum of the `scaler` label values an agent can carry: every scaler
+* backend type the orchestrator can resolve for a managed agent, plus
+* `stateful` for a static agent no scaler manages (the fallback
+* `AgentMetricsAggregator.resolveScalerLabel` stamps when the lookup returns
+* null). Derived from `ScalerBackendType` rather than restated, so adding a
+* backend cannot silently drop every `kici_agent_*` series that backend's
+* agents emit as `bad_label_value`.
+*/
+const AGENT_SCALER_VALUES = ["stateful", ...ScalerBackendType.options];
 /**
 * Closed enum of scaler-backend TYPE values the orchestrator's own
 * resource-usage gauges carry on their `scalerType` rollup label.
-* `__global__` is the orchestrator-wide rollup row; the other four match
-* `AGENT_SCALER_VALUES`. Exported so the policy tests can assert against it.
+* `__global__` is the orchestrator-wide rollup row; every other value comes
+* from `ScalerManager`'s own `backends` map, so the enum is `ScalerBackendType`
+* itself — NOT `AGENT_SCALER_VALUES`, which additionally carries the
+* agent-only `stateful` and predates the `event` backend. Exported so the
+* policy tests can assert against it.
+*/
+const ORCH_SCALER_VALUES = ["__global__", ...ScalerBackendType.options];
+/**
+* Closed enum of the scheduled jobs the orchestrator runs. MUST mirror
+* `OrchestratorScheduledJobName` (`packages/orchestrator/src/queue/scheduled-job.ts`)
+* exactly — a job missing here has its whole `kici_orch_job_*` series
+* dropped by the Platform filter with `reason="bad_label_value"`, so the
+* job silently loses every health metric. The engine cannot import the
+* orchestrator (dependency runs the other way), so the parity assertion
+* lives on the orchestrator side in `scheduled-job.test.ts`. Exported so
+* that test can assert against it.
 */
-const ORCH_SCALER_VALUES = ["__global__", ...AGENT_SCALER_VALUES];
-/** Closed enum of the five scheduled jobs the orchestrator runs (mirrors `OrchestratorScheduledJobName`). */
 const ORCH_JOB_VALUES = [
 	"cleanup",
 	"orphan-secret-cleanup",
 	"token-cleanup",
 	"cold-store-archive",
-	"cold-store-purge"
+	"cold-store-purge",
+	"unroutable-probe"
 ];
 /**
 * Per-metric, per-label value policy. Missing entries (or missing label
@@ -136,6 +153,20 @@ const METRIC_LABEL_POLICY = {
 		scalerType: { values: ORCH_SCALER_VALUES },
 		machinePool: { maxUniqueValues: 50 }
 	},
+	kici_orch_scaler_warm_pool_target: {
+		scaler: { maxUniqueValues: 50 },
+		labelSet: { maxUniqueValues: 100 }
+	},
+	kici_orch_scaler_warm_pool_ready: {
+		scaler: { maxUniqueValues: 50 },
+		labelSet: { maxUniqueValues: 100 }
+	},
+	kici_orch_scaler_warm_pool_in_flight: {
+		scaler: { maxUniqueValues: 50 },
+		labelSet: { maxUniqueValues: 100 }
+	},
+	kici_orch_scaler_warm_pool_spawns_total: { scaler: { maxUniqueValues: 50 } },
+	kici_orch_scaler_warm_pool_reaped_total: { scaler: { maxUniqueValues: 50 } },
 	kici_orch_install_secrets_decisions_total: {
 		decision: { values: [
 			"pass",
@@ -277,6 +308,6 @@ const METRIC_LABEL_POLICY = {
 	}
 };
 //#endregion
-export { METRIC_LABEL_POLICY, ORCH_PUSHED_METRIC_NAMES, ORCH_SCALER_VALUES, OVERFLOW_LABEL_VALUE };
+export { METRIC_LABEL_POLICY, ORCH_JOB_VALUES, ORCH_PUSHED_METRIC_NAMES, ORCH_SCALER_VALUES, OVERFLOW_LABEL_VALUE };
 
 //# sourceMappingURL=catalog-policy.js.map