@kici-dev/compiler 0.1.27 → 0.2.0

package/dist/local-plane/port-holder.js

@@ -0,0 +1,227 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import fs from "node:fs";
+import { execFile } from "node:child_process";
+import net from "node:net";
+//#region src/local-plane/port-holder.ts
+/**
+* OS-level ownership of the local dev plane's port.
+*
+* Answers two questions the plane's on-disk stamp cannot: is the port occupied
+* at all, and which process occupies it. Every external command is reached
+* through an injectable `ExecFn` so each platform branch has a real unit test on
+* any host, and every failure degrades to `null` rather than throwing — a
+* discovery failure must never break the command that asked.
+*/
+const defaultExec = (cmd, args) => new Promise((resolve) => {
+	execFile(cmd, args, {
+		timeout: 5e3,
+		maxBuffer: 8 * 1024 * 1024
+	}, (err, stdout) => {
+		const raw = err?.code;
+		resolve({
+			stdout: stdout ?? "",
+			exitCode: typeof raw === "number" ? raw : err ? 1 : 0
+		});
+	});
+});
+/**
+* Command line of process `pid`, or null when it cannot be determined.
+*
+* Linux exposes it as a NUL-separated `/proc` file; every other platform is
+* asked through the same injectable `ExecFn` the port discovery above uses.
+*
+* **A null means "cannot tell", never "not that process."** Callers must treat
+* it as an absence of evidence — the only safe reading when the answer decides
+* whether to signal a pid.
+*/
+async function processCommandLine(pid, opts = {}) {
+	const platform = opts.platform ?? process.platform;
+	try {
+		if (platform === "linux") {
+			const joined = (opts.readProc ?? ((p) => fs.readFileSync(p, "utf-8")))(`/proc/${pid}/cmdline`).split("\0").filter(Boolean).join(" ").trim();
+			return joined === "" ? null : joined;
+		}
+		if (platform === "win32") return null;
+		const r = await (opts.exec ?? defaultExec)("ps", [
+			"-o",
+			"args=",
+			"-p",
+			String(pid)
+		]);
+		if (r.exitCode !== 0) return null;
+		const line = r.stdout.trim();
+		return line === "" ? null : line;
+	} catch {
+		return null;
+	}
+}
+/**
+* Whether the port can be bound on loopback. Probes `127.0.0.1` because that is
+* the address the CLI talks to; a listener bound to `0.0.0.0` still makes this
+* bind fail with EADDRINUSE, so there is no false "free".
+*/
+function isPortFree(port) {
+	return new Promise((resolve) => {
+		const probe = net.createServer();
+		probe.once("error", () => resolve(false));
+		probe.listen({
+			port,
+			host: "127.0.0.1",
+			exclusive: true
+		}, () => {
+			probe.close(() => resolve(true));
+		});
+	});
+}
+/**
+* Port of a socket address column. The port is the segment after the LAST
+* colon, because an IPv6 address is written `[::]:5355`.
+*/
+function addressPort(addr) {
+	const i = addr.lastIndexOf(":");
+	if (i < 0) return null;
+	const n = Number(addr.slice(i + 1));
+	return Number.isInteger(n) ? n : null;
+}
+/**
+* Parse `ss -lptnH` rows. The process name is deliberately NOT matched — a Node
+* listener reports as `MainThread` — so only `pid=N` is extracted. A row for a
+* socket this user does not own carries no `users:(…)` field at all and yields
+* null, which is what sends the caller to the lsof fallback.
+*/
+function parseSsOutput(stdout, port) {
+	for (const line of stdout.split("\n")) {
+		const cols = line.trim().split(/\s+/);
+		if (cols.length < 4) continue;
+		if (addressPort(cols[3]) !== port) continue;
+		const m = /pid=(\d+)/.exec(line);
+		return m ? Number(m[1]) : null;
+	}
+	return null;
+}
+/**
+* Parse `lsof -Fpn` field output, which is a stateful stream: each `p<pid>` line
+* precedes the `n<address>` lines belonging to that pid.
+*/
+function parseLsofOutput(stdout, port) {
+	let current = null;
+	for (const line of stdout.split("\n")) if (line.startsWith("p")) {
+		const n = Number(line.slice(1));
+		current = Number.isInteger(n) ? n : null;
+	} else if (line.startsWith("n") && current !== null) {
+		if (addressPort(line.slice(1)) === port) return current;
+	}
+	return null;
+}
+/** Parse `netstat -ano -p tcp`: LISTENING rows only, pid in the last column. */
+function parseNetstatOutput(stdout, port) {
+	for (const line of stdout.split("\n")) {
+		const cols = line.trim().split(/\s+/);
+		if (cols.length < 5) continue;
+		if (!/^LISTENING$/i.test(cols[3])) continue;
+		if (addressPort(cols[1]) !== port) continue;
+		const pid = Number(cols[cols.length - 1]);
+		return Number.isInteger(pid) ? pid : null;
+	}
+	return null;
+}
+/**
+* Pid of the process listening on `port`, or null when it cannot be determined.
+* Each platform runs the UNFILTERED listing and matches the port here rather
+* than passing a filter expression to the tool, whose syntax is the fragile
+* part. On Linux a null parse falls through to lsof as well as a non-zero exit,
+* because ss omits the owning-process field for sockets this user does not own.
+*/
+async function findPortHolderPid(port, opts = {}) {
+	const exec = opts.exec ?? defaultExec;
+	const platform = opts.platform ?? process.platform;
+	const viaLsof = async () => {
+		const r = await exec("lsof", [
+			"-nP",
+			"-iTCP",
+			"-sTCP:LISTEN",
+			"-Fpn"
+		]);
+		return r.exitCode === 0 ? parseLsofOutput(r.stdout, port) : null;
+	};
+	try {
+		if (platform === "win32") {
+			const r = await exec("netstat", [
+				"-ano",
+				"-p",
+				"tcp"
+			]);
+			return r.exitCode === 0 ? parseNetstatOutput(r.stdout, port) : null;
+		}
+		if (platform === "linux") {
+			const r = await exec("ss", ["-lptnH"]);
+			return (r.exitCode === 0 ? parseSsOutput(r.stdout, port) : null) ?? await viaLsof();
+		}
+		return await viaLsof();
+	} catch {
+		return null;
+	}
+}
+const defaultKill = (pid, signal) => process.kill(pid, signal);
+/** How long to keep watching for the process to disappear after SIGKILL. */
+const HARD_KILL_WAIT_MS = 5e3;
+/**
+* Poll until process `pid` has exited, sending SIGTERM first and escalating to
+* SIGKILL past the grace window. `process.kill(pid, 0)` throws ESRCH once the
+* process is gone. On Windows every signal terminates unconditionally, so the
+* escalation collapses into a single hard kill there.
+*
+* Resolving does NOT prove the process died: a pid that survives SIGKILL (a
+* zombie awaiting reaping, or a task wedged in uninterruptible I/O) is given
+* `hardKillWaitMs` and then abandoned, because a teardown command that hangs
+* forever is worse than one that reports the port is still held. Callers decide
+* the outcome from the port itself — `waitForPortFree` — never from this
+* resolving.
+*/
+async function terminatePid(pid, graceMs = 1e4, opts = {}) {
+	const kill = opts.kill ?? defaultKill;
+	const hardKillWaitMs = opts.hardKillWaitMs ?? HARD_KILL_WAIT_MS;
+	try {
+		kill(pid, "SIGTERM");
+	} catch {
+		return;
+	}
+	let deadline = Date.now() + graceMs;
+	let killed = false;
+	for (;;) {
+		try {
+			kill(pid, 0);
+		} catch {
+			return;
+		}
+		if (Date.now() > deadline) {
+			if (killed) return;
+			try {
+				kill(pid, "SIGKILL");
+			} catch {
+				return;
+			}
+			killed = true;
+			deadline = Date.now() + hardKillWaitMs;
+		}
+		await new Promise((r) => setTimeout(r, 100));
+	}
+}
+/**
+* Poll until the port is bindable. This, not `terminatePid` resolving, is what
+* decides a teardown: `terminatePid` abandons a pid that survives SIGKILL, and
+* even a process that did exit can leave its listening socket lingering a moment
+* longer on some platforms.
+*/
+async function waitForPortFree(port, timeoutMs = 5e3) {
+	const deadline = Date.now() + timeoutMs;
+	for (;;) {
+		if (await isPortFree(port)) return true;
+		if (Date.now() >= deadline) return false;
+		await new Promise((r) => setTimeout(r, 100));
+	}
+}
+//#endregion
+export { findPortHolderPid, isPortFree, parseLsofOutput, parseNetstatOutput, parseSsOutput, processCommandLine, terminatePid, waitForPortFree };
+
+//# sourceMappingURL=port-holder.js.map

package/dist/local-plane/postgres.d.ts

@@ -18,12 +18,24 @@ declare let embeddedDaemon: typeof defaultEmbeddedDaemon;
 /** Test seam: override the embedded postmaster daemonizer. */
 export declare function __setEmbeddedDaemonForTest(fn: typeof embeddedDaemon): void;
 declare function defaultReadyPoller(_port: number): Promise<boolean>;
-/** Whether a podman binary is available on PATH. */
-export declare function isPodmanAvailable(): Promise<boolean>;
+/**
+ * Whether this plane's embedded postmaster is already serving `port`.
+ *
+ * `pg_ctl start` fails outright against a running cluster, so a boot that
+ * reclaims the plane port while leaving PostgreSQL up — reclaiming another
+ * plane's orchestrator does exactly that, since only the port holder is
+ * signalled — would otherwise fall through to the Podman path and fail there.
+ *
+ * The port comes from the cluster's own `postmaster.pid` (line 4) rather than
+ * being assumed, so a postmaster left on a different port is not mistaken for
+ * one this plane can reuse.
+ */
+export declare function embeddedClusterIsServing(port: number): Promise<boolean>;
 /**
  * Start a detached embedded postmaster via `pg_ctl` so it survives the exit of
  * this CLI process (embedded-postgres's in-process server is killed by its own
- * exit hook, so it cannot back a warm plane).
+ * exit hook, so it cannot back a warm plane). A cluster already serving this
+ * plane's port is reused as-is.
  */
 declare function defaultEmbeddedDaemon(port: number): Promise<void>;
 /**

package/dist/local-plane/postgres.js

@@ -3,9 +3,9 @@ import { planePaths, planePorts } from "./paths.js";
 import { createRequire } from "node:module";
 import path from "node:path";
 import fs from "node:fs";
+import { $ } from "zx";
 import { spawn } from "node:child_process";
 import os from "node:os";
-import { $ } from "zx";
 import EmbeddedPostgres from "embedded-postgres";
 //#region src/local-plane/postgres.ts
 /**
@@ -35,15 +35,6 @@ async function defaultReadyPoller(_port) {
 	}
 	return false;
 }
-/** Whether a podman binary is available on PATH. */
-async function isPodmanAvailable() {
-	try {
-		await $`podman --version`.quiet();
-		return true;
-	} catch {
-		return false;
-	}
-}
 /**
 * Resolve the platform-specific `pg_ctl` binary bundled with embedded-postgres.
 * Mirrors the package's own platform → binary-package mapping, resolving the
@@ -91,12 +82,43 @@ async function ensureEmbeddedCluster(port) {
 	await pg.stop();
 }
 /**
+* Whether this plane's embedded postmaster is already serving `port`.
+*
+* `pg_ctl start` fails outright against a running cluster, so a boot that
+* reclaims the plane port while leaving PostgreSQL up — reclaiming another
+* plane's orchestrator does exactly that, since only the port holder is
+* signalled — would otherwise fall through to the Podman path and fail there.
+*
+* The port comes from the cluster's own `postmaster.pid` (line 4) rather than
+* being assumed, so a postmaster left on a different port is not mistaken for
+* one this plane can reuse.
+*/
+async function embeddedClusterIsServing(port) {
+	const { pgData } = planePaths();
+	const pidFile = path.join(pgData, "postmaster.pid");
+	let runningPort;
+	try {
+		runningPort = Number(fs.readFileSync(pidFile, "utf-8").split("\n")[3]);
+	} catch {
+		return false;
+	}
+	if (runningPort !== port) return false;
+	try {
+		await $`${resolvePgCtl()} -D ${pgData} status`.quiet();
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
 * Start a detached embedded postmaster via `pg_ctl` so it survives the exit of
 * this CLI process (embedded-postgres's in-process server is killed by its own
-* exit hook, so it cannot back a warm plane).
+* exit hook, so it cannot back a warm plane). A cluster already serving this
+* plane's port is reused as-is.
 */
 async function defaultEmbeddedDaemon(port) {
 	const { pgData, logFile } = planePaths();
+	if (await embeddedClusterIsServing(port)) return;
 	await $`${resolvePgCtl()} -D ${pgData} -o ${`-p ${port}`} -l ${`${logFile}.pg`} -w start`.quiet();
 }
 /** Stop the detached embedded postmaster (handle-independent, reads the data dir). */
@@ -160,6 +182,6 @@ async function startPlanePostgres(opts = {}) {
 	};
 }
 //#endregion
-export { PLANE_PG_CONTAINER, PLANE_PG_IMAGE, __setEmbeddedDaemonForTest, __setReadyPollerForTest, isPodmanAvailable, startPlanePostgres, stopPlanePostgres };
+export { PLANE_PG_CONTAINER, PLANE_PG_IMAGE, __setEmbeddedDaemonForTest, __setReadyPollerForTest, embeddedClusterIsServing, startPlanePostgres, stopPlanePostgres };
 
 //# sourceMappingURL=postgres.js.map

package/dist/local-plane/run-follow.d.ts

@@ -3,6 +3,16 @@
  * orchestrator admin API (no SSE in independent mode). Streams step log lines as
  * they arrive and resolves when the run reaches a terminal state.
  */
+/**
+ * Resolve the acceptance window, falling back to the default for any value that
+ * is not a positive number of milliseconds.
+ *
+ * A malformed override must never reach the deadline arithmetic: `Number('')`
+ * is `0` (every run fails instantly) and `Number('2 min')` is `NaN`, which makes
+ * `now > deadline` permanently false and silently restores the 900 s hang this
+ * window exists to prevent. Both failure modes are worse than ignoring a typo.
+ */
+export declare function resolveAcceptanceTimeoutMs(explicitMs: number | undefined, raw: string | undefined): number;
 /** A minimal admin-read client (AdminApiClient.get) — injectable for tests. */
 export interface RunFollowClient {
     get<T>(path: string): Promise<T>;
@@ -35,6 +45,16 @@ export interface FollowRunOptions {
     timeoutMs?: number;
     /** Absolute cap regardless of progress (safety net against a runaway follow). Default 2 h. */
     maxTotalMs?: number;
+    /**
+     * Max time for the FIRST job to leave `pending`/`queued` — that is, for some
+     * agent to claim the run. A plane whose scaler matches no label set, or whose
+     * agent cannot start, never gets past this, so it fails in seconds instead of
+     * consuming the whole idle window. Default 2 min; override with
+     * `KICI_LOCAL_ACCEPTANCE_TIMEOUT_MS`.
+     */
+    acceptanceTimeoutMs?: number;
+    /** Plane log path named in the acceptance-failure message. */
+    hintLogPath?: string;
 }
 /** Poll a run to completion, streaming step logs. */
 export declare function followRun(planeUrl: string, adminToken: string, runId: string, opts?: FollowRunOptions): Promise<RunOutcome>;

package/dist/local-plane/run-follow.js

@@ -1,5 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { ExecutionJobStatus, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES } from "@kici-dev/engine";
+import { ExecutionJobStatus, ExecutionRunStatus, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES } from "@kici-dev/engine";
 import { AdminApiClient } from "@kici-dev/orchestrator";
 //#region src/local-plane/run-follow.ts
 /**
@@ -7,29 +7,76 @@ import { AdminApiClient } from "@kici-dev/orchestrator";
 * orchestrator admin API (no SSE in independent mode). Streams step log lines as
 * they arrive and resolves when the run reaches a terminal state.
 */
-/** Job states that mean the job did NOT succeed (failed / stale / cancelled / dropped). */
+/**
+* Job states that mean the job did NOT succeed (failed / stale / cancelled /
+* dropped / unroutable). Read only by the anti-false-green guard below, so a
+* missing member lets a lagging `success` run header be reported verbatim even
+* though a job settled badly.
+*/
 const FAILED_JOB_STATES = /* @__PURE__ */ new Set([
 	ExecutionJobStatus.enum.failed,
 	ExecutionJobStatus.enum.timed_out_stale,
 	ExecutionJobStatus.enum.cancelled,
-	ExecutionJobStatus.enum.drift_dropped
+	ExecutionJobStatus.enum.drift_dropped,
+	ExecutionJobStatus.enum.unroutable
 ]);
+/** Job states in which no agent has claimed the job yet. */
+const UNCLAIMED_JOB_STATES = /* @__PURE__ */ new Set([ExecutionJobStatus.enum.pending, ExecutionJobStatus.enum.queued]);
+/**
+* How often the acceptance check re-fetches jobs. Deliberately far coarser than
+* the poll interval: at 750 ms a two-minute window would cost ~160 extra admin
+* requests to answer a question that changes once.
+*/
+const ACCEPTANCE_CHECK_INTERVAL_MS = 5e3;
+/** Default window for an agent to claim the run before the follow gives up. */
+const DEFAULT_ACCEPTANCE_TIMEOUT_MS = 12e4;
+/**
+* Resolve the acceptance window, falling back to the default for any value that
+* is not a positive number of milliseconds.
+*
+* A malformed override must never reach the deadline arithmetic: `Number('')`
+* is `0` (every run fails instantly) and `Number('2 min')` is `NaN`, which makes
+* `now > deadline` permanently false and silently restores the 900 s hang this
+* window exists to prevent. Both failure modes are worse than ignoring a typo.
+*/
+function resolveAcceptanceTimeoutMs(explicitMs, raw) {
+	if (explicitMs !== void 0) return explicitMs;
+	if (raw === void 0) return DEFAULT_ACCEPTANCE_TIMEOUT_MS;
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_ACCEPTANCE_TIMEOUT_MS;
+}
 /** Poll a run to completion, streaming step logs. */
 async function followRun(planeUrl, adminToken, runId, opts = {}) {
 	const client = opts.client ?? new AdminApiClient(planeUrl, adminToken);
 	const pollIntervalMs = opts.pollIntervalMs ?? 750;
 	const idleTimeoutMs = opts.idleTimeoutMs ?? opts.timeoutMs ?? 9e5;
 	const maxTotalMs = opts.maxTotalMs ?? 72e5;
+	const acceptanceTimeoutMs = resolveAcceptanceTimeoutMs(opts.acceptanceTimeoutMs, process.env.KICI_LOCAL_ACCEPTANCE_TIMEOUT_MS);
 	const cursors = /* @__PURE__ */ new Map();
 	const stream = !opts.quiet && opts.onLine ? opts.onLine : void 0;
 	const startedAt = Date.now();
 	let lastProgressAt = startedAt;
 	let lastStatus = "";
+	let accepted = false;
+	let acceptanceDeadline = startedAt + acceptanceTimeoutMs;
+	let lastAcceptanceCheck = 0;
 	for (;;) {
 		const now = Date.now();
 		if (now - lastProgressAt > idleTimeoutMs) throw new Error(`offline run: follow timed out (no progress for ${idleTimeoutMs}ms) for run ${runId}`);
 		if (now - startedAt > maxTotalMs) throw new Error(`offline run: follow exceeded its max window (${maxTotalMs}ms) for run ${runId}`);
 		const { run } = await client.get(`/api/v1/admin/runs/${runId}`);
+		if (!accepted && !TERMINAL_RUN_STATES.has(run.status)) {
+			if (run.status === ExecutionRunStatus.enum.held) acceptanceDeadline = now + acceptanceTimeoutMs;
+			else if (now - lastAcceptanceCheck >= ACCEPTANCE_CHECK_INTERVAL_MS) {
+				lastAcceptanceCheck = now;
+				const claimedJobs = await fetchJobs(client, runId);
+				accepted = claimedJobs.length > 0 && claimedJobs.some((j) => !UNCLAIMED_JOB_STATES.has(j.status));
+			}
+			if (!accepted && now > acceptanceDeadline) {
+				const seconds = Math.round(acceptanceTimeoutMs / 1e3);
+				throw new Error(`offline run: no agent picked up this run within ${seconds}s — no scaler label set matched the job's runsOn, or the agent failed to start.` + (opts.hintLogPath ? ` Plane log: ${opts.hintLogPath}` : ""));
+			}
+		}
 		let progressed = false;
 		if (run.status !== lastStatus) {
 			lastStatus = run.status;
@@ -99,6 +146,6 @@ function sleep(ms) {
 	return new Promise((r) => setTimeout(r, ms));
 }
 //#endregion
-export { followRun };
+export { followRun, resolveAcceptanceTimeoutMs };
 
 //# sourceMappingURL=run-follow.js.map

package/dist/local-plane/scaler-config.d.ts

@@ -34,21 +34,35 @@ export declare const TRUSTED_ROUTING_LABEL = "self-hosted";
  */
 export declare const IN_PLACE_ROUTING_LABEL = "in-place";
 /**
- * Write the plane's bare-metal scaler YAML and return its path. One scaler with
- * two coexisting label sets spawning the agent wrapper against the plane
- * orchestrator's localhost WS endpoint:
+ * Write the plane's bare-metal scaler YAML and return its path. TWO coexisting
+ * bare-metal scalers spawn the agent wrapper against the plane orchestrator's
+ * localhost WS endpoint — a **sandboxed** pool and a `self-hosted`-**tainted**
+ * TRUSTED pool:
  *
- * - `default` — the sandboxed / credential-isolated profile a normal
- *   `kici run --local` dispatch (jobs with `runsOn: ['default']` or none) lands
- *   on. Smallest-set-wins routing keeps default runs here.
- * - `default` + `self-hosted` — the TRUSTED fleet profile (`KICI_TRUSTED_ENV=true`,
- *   bwrap off) a `kici run --local --trusted` run (or a `runsOn: self-hosted`
- *   workflow) lands on: steps run with the ambient host env passed through,
- *   minus the agent's own KiCI identity secrets.
- * - `default` + `self-hosted` + `in-place` — the TRUSTED **in-place** profile
- *   (adds `KICI_IN_PLACE=true`) a `kici run --local --trusted --in-place` run
- *   lands on: same trusted env, but the agent uses the operator's real working
- *   tree directly (no clone) — the profile KiCI's own routed `deploy:stg` uses.
+ * - `kici-local-bare-metal` (sandboxed) — one `default` label set, no taint. The
+ *   credential-isolated profile a normal `kici run --local` dispatch (jobs with
+ *   `runsOn: ['default']` or none) lands on. Its agents inherit no
+ *   `mandatoryLabels`, so a bare `default` job routes here.
+ * - `kici-local-bare-metal-trusted` (TRUSTED) — carries `mandatoryLabels:
+ *   ['self-hosted']`, so ONLY a job that explicitly requests `self-hosted`
+ *   (i.e. a `kici run --local --trusted` run, whose lock patch appends the
+ *   `self-hosted` routing label, or a `runsOn: self-hosted` workflow) is ever
+ *   routed to it — at BOTH the scaler spawn matcher AND the orchestrator's
+ *   agent-registry dispatch gate. Two label sets:
+ *     - `default` + `self-hosted` — the trusted fleet profile
+ *       (`KICI_TRUSTED_ENV=true`, bwrap off): steps run with the ambient host
+ *       env passed through, minus the agent's own KiCI identity secrets.
+ *     - `default` + `self-hosted` + `in-place` — the trusted **in-place**
+ *       profile (adds `KICI_IN_PLACE=true`) a `kici run --local --trusted
+ *       --in-place` run lands on: same trusted env, but the agent uses the
+ *       operator's real working tree directly (no clone) — the profile KiCI's
+ *       own routed `deploy:stg` uses.
+ *
+ * The `self-hosted` taint is the isolation guarantee: without it, an idle
+ * trusted agent (spawned for an earlier `--trusted` run and lingering for
+ * follow-up jobs) would satisfy the agent-registry's subset match for a plain
+ * `default` job and leak the ambient host env into a sandboxed run. The taint
+ * closes that at the dispatch layer, not just the spawn heuristic.
  */
 export declare function writeScalerConfig(orchestratorPort: number): string;
 //# sourceMappingURL=scaler-config.d.ts.map

package/dist/local-plane/scaler-config.js

@@ -49,60 +49,78 @@ const TRUSTED_ROUTING_LABEL = "self-hosted";
 */
 const IN_PLACE_ROUTING_LABEL = "in-place";
 /**
-* Write the plane's bare-metal scaler YAML and return its path. One scaler with
-* two coexisting label sets spawning the agent wrapper against the plane
-* orchestrator's localhost WS endpoint:
+* Write the plane's bare-metal scaler YAML and return its path. TWO coexisting
+* bare-metal scalers spawn the agent wrapper against the plane orchestrator's
+* localhost WS endpoint — a **sandboxed** pool and a `self-hosted`-**tainted**
+* TRUSTED pool:
 *
-* - `default` — the sandboxed / credential-isolated profile a normal
-*   `kici run --local` dispatch (jobs with `runsOn: ['default']` or none) lands
-*   on. Smallest-set-wins routing keeps default runs here.
-* - `default` + `self-hosted` — the TRUSTED fleet profile (`KICI_TRUSTED_ENV=true`,
-*   bwrap off) a `kici run --local --trusted` run (or a `runsOn: self-hosted`
-*   workflow) lands on: steps run with the ambient host env passed through,
-*   minus the agent's own KiCI identity secrets.
-* - `default` + `self-hosted` + `in-place` — the TRUSTED **in-place** profile
-*   (adds `KICI_IN_PLACE=true`) a `kici run --local --trusted --in-place` run
-*   lands on: same trusted env, but the agent uses the operator's real working
-*   tree directly (no clone) — the profile KiCI's own routed `deploy:stg` uses.
+* - `kici-local-bare-metal` (sandboxed) — one `default` label set, no taint. The
+*   credential-isolated profile a normal `kici run --local` dispatch (jobs with
+*   `runsOn: ['default']` or none) lands on. Its agents inherit no
+*   `mandatoryLabels`, so a bare `default` job routes here.
+* - `kici-local-bare-metal-trusted` (TRUSTED) — carries `mandatoryLabels:
+*   ['self-hosted']`, so ONLY a job that explicitly requests `self-hosted`
+*   (i.e. a `kici run --local --trusted` run, whose lock patch appends the
+*   `self-hosted` routing label, or a `runsOn: self-hosted` workflow) is ever
+*   routed to it — at BOTH the scaler spawn matcher AND the orchestrator's
+*   agent-registry dispatch gate. Two label sets:
+*     - `default` + `self-hosted` — the trusted fleet profile
+*       (`KICI_TRUSTED_ENV=true`, bwrap off): steps run with the ambient host
+*       env passed through, minus the agent's own KiCI identity secrets.
+*     - `default` + `self-hosted` + `in-place` — the trusted **in-place**
+*       profile (adds `KICI_IN_PLACE=true`) a `kici run --local --trusted
+*       --in-place` run lands on: same trusted env, but the agent uses the
+*       operator's real working tree directly (no clone) — the profile KiCI's
+*       own routed `deploy:stg` uses.
+*
+* The `self-hosted` taint is the isolation guarantee: without it, an idle
+* trusted agent (spawned for an earlier `--trusted` run and lingering for
+* follow-up jobs) would satisfy the agent-registry's subset match for a plain
+* `default` job and leak the ambient host env into a sandboxed run. The taint
+* closes that at the dispatch layer, not just the spawn heuristic.
 */
 function writeScalerConfig(orchestratorPort) {
 	const { scalerConfigFile, root } = planePaths();
 	fs.mkdirSync(root, { recursive: true });
 	const binaryPath = writeAgentWrapper();
+	const orchestratorUrl = `ws://127.0.0.1:${orchestratorPort}/ws`;
 	const yaml = stringify({
 		version: 1,
 		scalers: [{
 			name: "kici-local-bare-metal",
 			type: "bare-metal",
 			maxAgents: 10,
-			orchestratorUrl: `ws://127.0.0.1:${orchestratorPort}/ws`,
-			labelSets: [
-				{
-					labels: ["default"],
-					binaryPath
-				},
-				{
-					labels: ["default", TRUSTED_ROUTING_LABEL],
-					binaryPath,
-					env: {
-						KICI_TRUSTED_ENV: "true",
-						KICI_SANDBOX: "false"
-					}
-				},
-				{
-					labels: [
-						"default",
-						TRUSTED_ROUTING_LABEL,
-						IN_PLACE_ROUTING_LABEL
-					],
-					binaryPath,
-					env: {
-						KICI_TRUSTED_ENV: "true",
-						KICI_SANDBOX: "false",
-						KICI_IN_PLACE: "true"
-					}
+			orchestratorUrl,
+			labelSets: [{
+				labels: ["default"],
+				binaryPath
+			}]
+		}, {
+			name: "kici-local-bare-metal-trusted",
+			type: "bare-metal",
+			maxAgents: 10,
+			orchestratorUrl,
+			mandatoryLabels: [TRUSTED_ROUTING_LABEL],
+			labelSets: [{
+				labels: ["default", TRUSTED_ROUTING_LABEL],
+				binaryPath,
+				env: {
+					KICI_TRUSTED_ENV: "true",
+					KICI_SANDBOX: "false"
+				}
+			}, {
+				labels: [
+					"default",
+					TRUSTED_ROUTING_LABEL,
+					IN_PLACE_ROUTING_LABEL
+				],
+				binaryPath,
+				env: {
+					KICI_TRUSTED_ENV: "true",
+					KICI_SANDBOX: "false",
+					KICI_IN_PLACE: "true"
 				}
-			]
+			}]
 		}]
 	});
 	fs.writeFileSync(scalerConfigFile, yaml);