@kici-dev/compiler 0.1.20 → 0.1.22

package/dist/cli.d.ts

@@ -8,4 +8,18 @@ import { Command } from 'commander';
 export declare function buildProgram(): Command;
 /** Build the program and parse argv — the bin-shim entry point. */
 export declare function runCli(argv?: string[]): void;
+/**
+ * Decide whether this module is the process entry point, tolerating a
+ * symlinked `argv[1]`. A `node_modules/.bin/kici` entry is a symlink, and when
+ * it points at this compiled `cli.js` (the compiler package declares a `kici`
+ * bin), `process.argv[1]` is the symlink path while `import.meta.url` is the
+ * real file. A plain `resolve()` comparison sees two different paths and never
+ * matches, silently skipping `runCli()` — so `kici compile` (and every other
+ * subcommand) becomes a no-op when invoked through the bin symlink.
+ * Dereference both sides with `realpathSync` so a symlinked invocation is
+ * correctly recognised as the entry point. Falls back to a plain `resolve()`
+ * comparison when `argv[1]` doesn't resolve to a real file (e.g. a virtual
+ * entry point), preserving the previous behaviour for that edge case.
+ */
+export declare function isMainEntryPoint(argv1: string | undefined, importMetaUrl: string): boolean;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -3,10 +3,11 @@ import "./chunk-BTugEXQM.js";
 import { shouldSuppressBanner } from "./cli-banner.js";
 import { fileURLToPath } from "node:url";
 import { resolve } from "node:path";
+import { realpathSync } from "node:fs";
 import { Argument, Command, Option } from "commander";
 import pc from "picocolors";
 //#region src/cli.ts
-const version = "0.1.20";
+const version = "0.1.22";
 /**
 * Build the kici Commander program with every command registered. Exported so
 * the surface registry can walk the real command tree without parsing argv (no
@@ -43,7 +44,7 @@ function buildProgram() {
 		await fixtureCommand(event, options);
 	});
 	const runCommand = program.command("run").description("Execute workflows locally or remotely");
-	runCommand.command("local").argument("[event]", "Event type (e.g., push, pr:open, schedule) — optional with --pick").description("Execute workflows locally without orchestrator infrastructure").option("-p, --pick", "Interactively pick a workflow and trigger to simulate", false).option("--workflow <name>", "Run only the specified workflow").option("--job <name>", "Run only the specified job (and its dependencies)").option("--branch <name>", "Override detected git branch").option("--sha <hash>", "Override detected git SHA").option("--payload <path>", "Path to explicit event payload JSON file").option("--concurrency <n>", "Max parallel jobs (default: CPU cores)", parseInt).option("--keep-going", "Continue after job failure", false).option("--container", "Use Podman container isolation", false).option("--env <KEY=VALUE>", "Environment variable override (repeatable)", (val, prev) => [...prev, val], []).option("--quiet", "Suppress streaming output", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--files <path>", "Override changed file paths (repeatable, default: git diff)", (val, prev) => [...prev, val], []).option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--in-place", "Run against the real working directory instead of an isolated tmp checkout", false).option("--keep", "Always retain the isolated tmp checkout (default: keep only on failure)", false).action(async (event, options) => {
+	runCommand.command("local").argument("[event]", "Event type (e.g., push, pr:open, schedule) — optional with --pick").description("Execute workflows locally without orchestrator infrastructure").option("-p, --pick", "Interactively pick a workflow and trigger to simulate", false).option("--workflow <name>", "Run only the specified workflow").option("--job <name>", "Run only the specified job (and its dependencies)").option("--branch <name>", "Override detected git branch").option("--sha <hash>", "Override detected git SHA").option("--payload <path>", "Path to explicit event payload JSON file").option("--concurrency <n>", "Max parallel jobs (default: CPU cores)", parseInt).option("--keep-going", "Continue after job failure", false).option("--container", "Use Podman container isolation", false).option("--env <KEY=VALUE>", "Environment variable override (repeatable)", (val, prev) => [...prev, val], []).option("--quiet", "Suppress streaming output", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--files <path>", "Override changed file paths (repeatable, default: git diff)", (val, prev) => [...prev, val], []).option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--in-place", "Run against the real working directory instead of an isolated tmp checkout", false).option("--keep", "Always retain the isolated tmp checkout (default: keep only on failure)", false).option("--check", "Run in check mode: report drift, change nothing", false).option("--fail-on-drift", "In check mode, exit non-zero if any step reports drift", false).action(async (event, options) => {
 		if (options.pick && options.workflow) {
 			console.error("Error: --pick is mutually exclusive with --workflow.");
 			process.exit(2);
@@ -53,8 +54,20 @@ function buildProgram() {
 			process.exit(2);
 		}
 		const { runLocalCommand } = await import("./commands/index.js");
+		const { resolveCheckMode } = await import("./commands/check-mode.js");
+		let checkMode;
+		try {
+			checkMode = resolveCheckMode({
+				check: options.check,
+				failOnDrift: options.failOnDrift
+			});
+		} catch (err) {
+			console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+			process.exit(2);
+		}
 		const success = await runLocalCommand({
 			event,
+			checkMode,
 			pick: options.pick,
 			workflow: options.workflow,
 			job: options.job,
@@ -76,11 +89,26 @@ function buildProgram() {
 		});
 		process.exit(success ? 0 : 1);
 	});
-	runCommand.command("remote").argument("[fixture]", "Fixture name or glob pattern (omit to list available)").description("Execute fixtures remotely via orchestrator").option("--workflow <name>", "Run a specific workflow directly (bypass triggers)").option("--all", "Run all available fixtures", false).option("--parallel", "Run matching fixtures concurrently", false).option("--no-wait", "Fire and forget (print runIds, don't stream)").option("--quiet", "Suppress output except final result", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--history", "Show recent run history", false).option("--routing-key <key>", "Override routing key for this run").option("--org <id>", "Target organization (overrides the active org)").option("--orchestrator <name>", "Target orchestrator cluster (overrides the per-org default)").option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--context <ctx.key=value>", "Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)", (val, prev) => [...prev, val], []).option("--env <KEY=VALUE>", "Provide a per-run secret (repeatable); uploaded encrypted to the orchestrator", (val, prev) => [...prev, val], []).action(async (fixture, options) => {
+	runCommand.command("remote").argument("[fixture]", "Fixture name or glob pattern (omit to list available)").description("Execute fixtures remotely via orchestrator").option("--workflow <name>", "Run a specific workflow directly (bypass triggers)").option("--all", "Run all available fixtures", false).option("--parallel", "Run matching fixtures concurrently", false).option("--no-wait", "Fire and forget (print runIds, don't stream)").option("--quiet", "Suppress output except final result", false).option("--json", "Output structured JSON result", false).option("--junit <path>", "Output JUnit XML result").option("--history", "Show recent run history", false).option("--routing-key <key>", "Override routing key for this run").option("--org <id>", "Target organization (overrides the active org)").option("--orchestrator <name>", "Target orchestrator cluster (overrides the per-org default)").option("--debug", "Verbose internals", false).option("--kici-dir <path>", "Path to .kici directory", ".kici").option("--context <ctx.key=value>", "Inject a namespaced context secret, uploaded encrypted to the orchestrator (repeatable)", (val, prev) => [...prev, val], []).option("--env <KEY=VALUE>", "Provide a per-run secret (repeatable); uploaded encrypted to the orchestrator", (val, prev) => [...prev, val], []).option("--check", "Run in check mode: report drift, change nothing", false).option("--fail-on-drift", "In check mode, exit non-zero if any step reports drift", false).option("--target <selector>", "Narrow runsOnAll jobs to hosts matching this label selector (repeatable, AND-combined)", (val, prev) => [...prev, val], []).option("--target-allow-empty", "A --target that narrows a runsOnAll job to zero hosts skips it instead of failing", false).option("--approve-all, --yes", "Auto-approve every approval gate this run holds on (run-scoped; eligibility still enforced)", false).action(async (fixture, options) => {
 		const { runRemoteCommand } = await import("./commands/index.js");
+		const { resolveCheckMode } = await import("./commands/check-mode.js");
+		let checkMode;
+		try {
+			checkMode = resolveCheckMode({
+				check: options.check,
+				failOnDrift: options.failOnDrift
+			});
+		} catch (err) {
+			console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+			process.exit(2);
+		}
 		const success = await runRemoteCommand(fixture, {
 			...options,
-			envFlags: options.env
+			checkMode,
+			envFlags: options.env,
+			targets: options.target,
+			targetAllowEmpty: options.targetAllowEmpty,
+			approveAll: options.approveAll
 		});
 		process.exit(success ? 0 : 1);
 	});
@@ -102,7 +130,7 @@ function buildProgram() {
 		const success = await hookInstallCommand({ git: options.git });
 		process.exit(success ? 0 : 1);
 	});
-	program.command("login").description("Authenticate with KiCI via browser OAuth (default) or API key (--token)").option("--token <key>", "API key for direct authentication (legacy)").option("--device", "Force device authorization flow (for headless/SSH environments)").option("--platform-endpoint <url>", "Platform relay URL").option("--routing-key <key>", "Routing key for webhook source identification").addHelpText("after", `
+	program.command("login").description("Authenticate with KiCI via browser OAuth (default) or API key (--token)").option("--token <key>", "API key for direct authentication (legacy)").option("--device", "Force device authorization flow (for headless/SSH environments)").option("--platform-endpoint <url>", "Platform relay URL").option("--oidc-issuer <url>", "OIDC issuer URL (defaults to the hosted KiCI IdP unless a flag/env selects another)").option("--routing-key <key>", "Routing key for webhook source identification").addHelpText("after", `
 Environment variables:
   KICI_BROWSER_CMD     Custom browser command (use {url} placeholder, or 'none' to suppress)
   KICI_CALLBACK_PORT   Fixed port for OAuth PKCE callback server (default: random)
@@ -115,6 +143,7 @@ Environment variables:
 			token: options.token,
 			device: options.device,
 			platformEndpoint: options.platformEndpoint,
+			oidcIssuer: options.oidcIssuer,
 			routingKey: options.routingKey
 		});
 		process.exit(success ? 0 : 1);
@@ -263,8 +292,30 @@ Environment variables:
 function runCli(argv = process.argv) {
 	buildProgram().parse(argv);
 }
-if (resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) runCli();
+/**
+* Decide whether this module is the process entry point, tolerating a
+* symlinked `argv[1]`. A `node_modules/.bin/kici` entry is a symlink, and when
+* it points at this compiled `cli.js` (the compiler package declares a `kici`
+* bin), `process.argv[1]` is the symlink path while `import.meta.url` is the
+* real file. A plain `resolve()` comparison sees two different paths and never
+* matches, silently skipping `runCli()` — so `kici compile` (and every other
+* subcommand) becomes a no-op when invoked through the bin symlink.
+* Dereference both sides with `realpathSync` so a symlinked invocation is
+* correctly recognised as the entry point. Falls back to a plain `resolve()`
+* comparison when `argv[1]` doesn't resolve to a real file (e.g. a virtual
+* entry point), preserving the previous behaviour for that edge case.
+*/
+function isMainEntryPoint(argv1, importMetaUrl) {
+	if (!argv1) return false;
+	const modulePath = fileURLToPath(importMetaUrl);
+	try {
+		return realpathSync(argv1) === realpathSync(modulePath);
+	} catch {
+		return resolve(argv1) === resolve(modulePath);
+	}
+}
+if (isMainEntryPoint(process.argv[1], import.meta.url)) runCli();
 //#endregion
-export { buildProgram, runCli };
+export { buildProgram, isMainEntryPoint, runCli };
 
 //# sourceMappingURL=cli.js.map

package/dist/commands/check-mode.d.ts

@@ -0,0 +1,19 @@
+import { CheckMode } from '@kici-dev/engine';
+/** The two run-mode flags shared by `kici run local` and `kici run remote`. */
+export interface CheckModeFlags {
+    /** --check: report drift, change nothing. */
+    check?: boolean;
+    /** --fail-on-drift: in check mode, exit non-zero if any step reports drift. */
+    failOnDrift?: boolean;
+}
+/**
+ * Resolve the run {@link CheckMode} from the `--check` / `--fail-on-drift` flags.
+ *
+ * - no flags -> `apply` (the unchanged default: converge).
+ * - `--check` -> `check` (report-only, changes nothing).
+ * - `--check --fail-on-drift` -> `check-fail-on-drift` (fails the run on drift).
+ *
+ * `--fail-on-drift` without `--check` is an error — it only modifies check mode.
+ */
+export declare function resolveCheckMode(flags: CheckModeFlags): CheckMode;
+//# sourceMappingURL=check-mode.d.ts.map

package/dist/commands/check-mode.js

@@ -0,0 +1,21 @@
+import "../chunk-BTugEXQM.js";
+import { CheckMode } from "@kici-dev/engine";
+//#region src/commands/check-mode.ts
+/**
+* Resolve the run {@link CheckMode} from the `--check` / `--fail-on-drift` flags.
+*
+* - no flags -> `apply` (the unchanged default: converge).
+* - `--check` -> `check` (report-only, changes nothing).
+* - `--check --fail-on-drift` -> `check-fail-on-drift` (fails the run on drift).
+*
+* `--fail-on-drift` without `--check` is an error — it only modifies check mode.
+*/
+function resolveCheckMode(flags) {
+	if (flags.failOnDrift && !flags.check) throw new Error("--fail-on-drift requires --check");
+	if (flags.check) return flags.failOnDrift ? CheckMode.enum["check-fail-on-drift"] : CheckMode.enum.check;
+	return CheckMode.enum.apply;
+}
+//#endregion
+export { resolveCheckMode };
+
+//# sourceMappingURL=check-mode.js.map

package/dist/commands/compile.js

@@ -8,8 +8,8 @@ import "../validation/index.js";
 import { computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile } from "../lockfile/generator.js";
 import "../lockfile/index.js";
 import path from "node:path";
-import pc from "picocolors";
 import { existsSync } from "node:fs";
+import pc from "picocolors";
 import fs from "node:fs/promises";
 import { logger, toErrorMessage } from "@kici-dev/core";
 import { PackageManager, detectPackageManagerSync } from "@kici-dev/core/package-manager";

package/dist/commands/held-run-client.d.ts

@@ -19,8 +19,13 @@ export interface HeldRunContext {
 export declare function resolveHeldRunContext(): Promise<HeldRunContext | null>;
 /** List the held runs for a single run id. */
 export declare function listHeldRunsForRun(ctx: HeldRunContext, runId: string): Promise<HeldRunSummary[]>;
-/** POST an approve decision for a held run. Returns true on success. */
-export declare function postApprove(ctx: HeldRunContext, heldRunId: string): Promise<boolean>;
+/**
+ * POST an approve decision for a held run. Returns true on success. When
+ * `autoApprove` is set, marks the approval as a `kici run --approve-all`
+ * breakglass so the orchestrator audits it as `held_run.auto_approve`
+ * (eligibility is still enforced server-side — never a bypass).
+ */
+export declare function postApprove(ctx: HeldRunContext, heldRunId: string, autoApprove?: boolean): Promise<boolean>;
 /** POST a reject decision (with reason) for a held run. Returns true on success. */
 export declare function postReject(ctx: HeldRunContext, heldRunId: string, reason: string): Promise<boolean>;
 //# sourceMappingURL=held-run-client.d.ts.map

package/dist/commands/held-run-client.js

@@ -52,9 +52,15 @@ async function listHeldRunsForRun(ctx, runId) {
 	if (!response.ok) throw new Error(await describeError(response));
 	return (await response.json()).heldRuns ?? [];
 }
-/** POST an approve decision for a held run. Returns true on success. */
-async function postApprove(ctx, heldRunId) {
-	const url = `${ctx.endpoint}/api/v1/orgs/${ctx.orgId}/held-runs/${heldRunId}/approve`;
+/**
+* POST an approve decision for a held run. Returns true on success. When
+* `autoApprove` is set, marks the approval as a `kici run --approve-all`
+* breakglass so the orchestrator audits it as `held_run.auto_approve`
+* (eligibility is still enforced server-side — never a bypass).
+*/
+async function postApprove(ctx, heldRunId, autoApprove = false) {
+	const query = autoApprove ? "?auto=1" : "";
+	const url = `${ctx.endpoint}/api/v1/orgs/${ctx.orgId}/held-runs/${heldRunId}/approve${query}`;
 	const response = await fetch(url, {
 		method: "POST",
 		headers: authHeaders(ctx.token)

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

@@ -16,6 +16,11 @@ export interface HeldRunSummary {
     holdScope?: HeldRunScope;
     stepIndex?: number | null;
     status: string;
+    /** Computed drift payload for a `when: 'drift'` step hold; absent otherwise. */
+    payload?: {
+        summaryMarkdown: string;
+        drift?: unknown;
+    } | null;
 }
 /** Filters supplied on the command line. */
 export interface HeldRunFilter {

package/dist/commands/login.d.ts

@@ -3,6 +3,8 @@ export interface LoginOptions {
     token?: string;
     /** Platform relay URL */
     platformEndpoint?: string;
+    /** OIDC issuer URL override */
+    oidcIssuer?: string;
     /** Routing key for webhook source identification */
     routingKey?: string;
     /** Force device authorization flow regardless of environment */

package/dist/commands/login.js

@@ -1,5 +1,5 @@
 import "../chunk-BTugEXQM.js";
-import { getConfigPath, mergeGlobalConfig } from "../remote/config.js";
+import { getConfigPath, loadGlobalConfig, mergeGlobalConfig, saveGlobalConfig } from "../remote/config.js";
 import { deviceFlow, exchangeTokenForPat, pkceFlow } from "../remote/oauth.js";
 import "../remote/prod-defaults.js";
 import { isHeadless } from "../auth/headless-detect.js";
@@ -46,8 +46,9 @@ function checkPatExpiry(expiresAt) {
 * 4. Save PAT to global config
 */
 async function oauthLogin(options) {
+	const existing = await loadGlobalConfig();
 	const platformUrl = options.platformEndpoint || process.env.KICI_PLATFORM_URL || "https://api.kici.dev";
-	const issuer = process.env.KICI_OIDC_ISSUER || "https://auth.kici.dev/realms/kici-internal";
+	const issuer = options.oidcIssuer || process.env.KICI_OIDC_ISSUER || "https://auth.kici.dev/realms/kici-internal";
 	const clientId = process.env.KICI_OIDC_CLIENT_ID || "kici-cli";
 	console.log(pc.cyan("\n  Step 1/4: Detecting environment..."));
 	const browserCmdSet = !!process.env.KICI_BROWSER_CMD;
@@ -70,14 +71,21 @@ async function oauthLogin(options) {
 		machineName
 	});
 	console.log(pc.cyan("\n  Step 4/4: Saving credentials..."));
-	const configUpdate = {
+	const endpointChanged = existing.platformEndpoint !== platformUrl;
+	const next = {
+		...existing,
 		pat: patResult.token,
 		patId: patResult.id,
-		patExpiresAt: patResult.expiresAt
+		patExpiresAt: patResult.expiresAt,
+		platformEndpoint: platformUrl,
+		oidcIssuer: issuer
 	};
-	if (options.platformEndpoint) configUpdate.platformEndpoint = options.platformEndpoint;
-	if (options.routingKey) configUpdate.routingKey = options.routingKey;
-	await mergeGlobalConfig(configUpdate);
+	if (options.routingKey) next.routingKey = options.routingKey;
+	if (endpointChanged) {
+		delete next.activeOrgId;
+		delete next.defaultClusters;
+	}
+	await saveGlobalConfig(next);
 	const configPath = getConfigPath();
 	const expiryDate = new Date(patResult.expiresAt).toLocaleDateString();
 	console.log(pc.green(`\n  Authenticated successfully!`));

package/dist/commands/run-hold-watch.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Hold-visibility + inline approve/reject for `kici run remote`.
+ *
+ * While a run is being watched, the orchestrator may pause it on an approval
+ * gate (a `when: 'always'` step/job/workflow gate, or a `when: 'drift'` step
+ * gate that carries a computed-drift payload). The poll loop calls
+ * `handleNewHolds` each tick with the run's pending holds. For each hold not
+ * seen before it prints the payload (if any) and, in a TTY, prompts the
+ * operator to approve/reject inline — reusing the same Platform held-run HTTP
+ * path as `kici approve` / `kici reject`. In a non-TTY it prints guidance and
+ * keeps polling (the run stays held until resolved out-of-band).
+ */
+import type { HeldRunSummary } from './held-run-resolve.js';
+import { type HeldRunContext } from './held-run-client.js';
+/** A yes/no prompt; injected so the poll branch is unit-testable. */
+export type ConfirmPrompt = (message: string) => Promise<boolean>;
+/** What to do with a newly-observed hold. Pure — no IO. */
+export type HoldAction = {
+    kind: 'prompt';
+    hold: HeldRunSummary;
+} | {
+    kind: 'notify';
+    hold: HeldRunSummary;
+};
+/**
+ * Classify the holds observed this tick against the set already seen. Returns
+ * one action per genuinely-new pending hold (TTY ⇒ prompt, non-TTY ⇒ notify),
+ * and the updated seen-set. Pure: the caller performs the IO.
+ */
+export declare function classifyNewHolds(holds: readonly HeldRunSummary[], seen: Set<string>, isTty: boolean): {
+    actions: HoldAction[];
+    seen: Set<string>;
+};
+/**
+ * Process the new holds observed this tick: print each, and in a TTY prompt the
+ * operator to approve/reject inline (posting the decision via the shared
+ * held-run HTTP path). Returns the updated seen-set. A resolved context is
+ * resolved lazily on first need and cached for the run.
+ */
+export declare function handleNewHolds(args: {
+    holds: readonly HeldRunSummary[];
+    seen: Set<string>;
+    isTty: boolean;
+    confirm: ConfirmPrompt;
+    /**
+     * `--approve-all` breakglass: auto-approve each hold (run-scoped) instead of
+     * prompting, marking the approval as `auto_approve` so the orchestrator
+     * audits it distinctly. Eligibility is still enforced server-side.
+     */
+    approveAll?: boolean;
+    /** Override for tests; defaults to the shared Platform held-run context. */
+    resolveContext?: () => Promise<HeldRunContext | null>;
+    /** Override for tests. */
+    approve?: (ctx: HeldRunContext, heldRunId: string, autoApprove?: boolean) => Promise<boolean>;
+    reject?: (ctx: HeldRunContext, heldRunId: string, reason: string) => Promise<boolean>;
+}): Promise<Set<string>>;
+//# sourceMappingURL=run-hold-watch.d.ts.map

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

@@ -0,0 +1,87 @@
+import "../chunk-BTugEXQM.js";
+import { postApprove, postReject, resolveHeldRunContext } from "./held-run-client.js";
+import pc from "picocolors";
+import { logger } from "@kici-dev/core";
+//#region src/commands/run-hold-watch.ts
+/**
+* Hold-visibility + inline approve/reject for `kici run remote`.
+*
+* While a run is being watched, the orchestrator may pause it on an approval
+* gate (a `when: 'always'` step/job/workflow gate, or a `when: 'drift'` step
+* gate that carries a computed-drift payload). The poll loop calls
+* `handleNewHolds` each tick with the run's pending holds. For each hold not
+* seen before it prints the payload (if any) and, in a TTY, prompts the
+* operator to approve/reject inline — reusing the same Platform held-run HTTP
+* path as `kici approve` / `kici reject`. In a non-TTY it prints guidance and
+* keeps polling (the run stays held until resolved out-of-band).
+*/
+/**
+* Classify the holds observed this tick against the set already seen. Returns
+* one action per genuinely-new pending hold (TTY ⇒ prompt, non-TTY ⇒ notify),
+* and the updated seen-set. Pure: the caller performs the IO.
+*/
+function classifyNewHolds(holds, seen, isTty) {
+	const next = new Set(seen);
+	const actions = [];
+	for (const hold of holds) {
+		if (hold.status !== "pending") continue;
+		if (next.has(hold.id)) continue;
+		next.add(hold.id);
+		actions.push({
+			kind: isTty ? "prompt" : "notify",
+			hold
+		});
+	}
+	return {
+		actions,
+		seen: next
+	};
+}
+/** Print a hold's identity + its drift payload (when present) to stdout. */
+function printHold(hold) {
+	const scope = hold.holdScope ?? "job";
+	const where = scope === "step" && hold.stepIndex != null ? `step #${hold.stepIndex}${hold.jobId ? ` of job '${hold.jobId}'` : ""}` : hold.jobId ? `job '${hold.jobId}'` : scope;
+	logger.info(pc.yellow(`\n[kici] Run held for approval (${where}).`));
+	if (hold.payload?.summaryMarkdown) {
+		logger.info(pc.dim("Computed drift — review before approving:"));
+		for (const line of hold.payload.summaryMarkdown.split("\n")) logger.info(pc.dim(`    ${line}`));
+	}
+}
+/**
+* Process the new holds observed this tick: print each, and in a TTY prompt the
+* operator to approve/reject inline (posting the decision via the shared
+* held-run HTTP path). Returns the updated seen-set. A resolved context is
+* resolved lazily on first need and cached for the run.
+*/
+async function handleNewHolds(args) {
+	const { actions, seen } = classifyNewHolds(args.holds, args.seen, args.isTty);
+	if (actions.length === 0) return seen;
+	const resolveCtx = args.resolveContext ?? resolveHeldRunContext;
+	const doApprove = args.approve ?? postApprove;
+	const doReject = args.reject ?? postReject;
+	let ctx = null;
+	if (args.approveAll) logger.info(pc.yellow("[kici] --approve-all: auto-approving every gate for this run (eligibility enforced)."));
+	for (const action of actions) {
+		printHold(action.hold);
+		ctx = ctx ?? await resolveCtx();
+		if (!ctx) {
+			logger.info(pc.dim(`Run held; approve via \`kici approve ${action.hold.runId}\`.`));
+			continue;
+		}
+		if (args.approveAll) {
+			if (await doApprove(ctx, action.hold.id, true)) logger.info(pc.green("[kici] Auto-approved."));
+			continue;
+		}
+		if (action.kind === "notify") {
+			logger.info(pc.dim(`Run held; approve via the dashboard or \`kici approve ${action.hold.runId}\`.`));
+			continue;
+		}
+		const approved = await args.confirm("Approve this gate?");
+		if (approved ? await doApprove(ctx, action.hold.id) : await doReject(ctx, action.hold.id, "rejected via kici run")) logger.info(approved ? pc.green("[kici] Approved.") : pc.red("[kici] Rejected."));
+	}
+	return seen;
+}
+//#endregion
+export { classifyNewHolds, handleNewHolds };
+
+//# sourceMappingURL=run-hold-watch.js.map

package/dist/commands/run.d.ts

@@ -1,5 +1,13 @@
+import type { HostTargetSelector } from '@kici-dev/engine';
 import type { RunLocalOptions } from '../local-executor/types.js';
 import type { RemoteRunOptions } from './test.js';
+/**
+ * Compile `--target` selector strings into a {@link HostTargetSelector}. Each
+ * string becomes one AND value (its own include set); repeated values
+ * AND-combine. Returns undefined when no `--target` is given. Throws when
+ * `--target-allow-empty` is set without at least one `--target`.
+ */
+export declare function buildTargetSelector(targets: string[] | undefined, allowEmpty: boolean): HostTargetSelector | undefined;
 /**
  * Run a workflow locally using the local executor.
  * Thin wrapper that delegates to executeLocal from local-executor.

package/dist/commands/run.js

@@ -10,10 +10,14 @@ import { formatJsonResult } from "../remote/output/json.js";
 import { formatJunitResult } from "../remote/output/junit.js";
 import { formatErrorHighlight, formatMultiFixtureSummary, formatSummary } from "../remote/output/summary.js";
 import { compileFixtures, filterFixtures } from "../fixtures/compiler.js";
+import { listHeldRunsForRun, resolveHeldRunContext } from "./held-run-client.js";
+import { handleNewHolds } from "./run-hold-watch.js";
 import path from "node:path";
 import pc from "picocolors";
 import { readFile, writeFile } from "node:fs/promises";
 import { formatBytes, logger, toErrorMessage } from "@kici-dev/core";
+import { normalizeRunsOnToMatchers } from "@kici-dev/engine/labels/compile";
+import { confirm } from "@inquirer/prompts";
 //#region src/commands/run.ts
 /** Terminal run statuses returned by the Platform run-status snapshot. */
 const TERMINAL_STATUSES = new Set([
@@ -22,6 +26,22 @@ const TERMINAL_STATUSES = new Set([
 	"cancelled",
 	"error"
 ]);
+/**
+* Compile `--target` selector strings into a {@link HostTargetSelector}. Each
+* string becomes one AND value (its own include set); repeated values
+* AND-combine. Returns undefined when no `--target` is given. Throws when
+* `--target-allow-empty` is set without at least one `--target`.
+*/
+function buildTargetSelector(targets, allowEmpty) {
+	if (!targets || targets.length === 0) {
+		if (allowEmpty) throw new Error("--target-allow-empty requires at least one --target selector");
+		return;
+	}
+	return {
+		values: targets.map((t) => normalizeRunsOnToMatchers(t, "kici run --target")),
+		allowEmpty
+	};
+}
 /** Interval between status/log polls while a run is active. */
 const POLL_INTERVAL_MS = 750;
 /**
@@ -58,6 +78,7 @@ async function runRemoteCommand(fixture, options) {
 		if (!options.quiet) logger.info(pc.gray("Debug mode enabled"));
 	}
 	try {
+		buildTargetSelector(options.targets, options.targetAllowEmpty ?? false);
 		if (options.workflow && !fixture && !options.all) return await runDirectWorkflow(options.workflow, options);
 		const kiciDir = resolveKiciDir(options.kiciDir);
 		if (options.history) {
@@ -294,7 +315,12 @@ async function runSingleFixture(fixture, ctx, options, config, history) {
 			},
 			workflowName: opts.workflowName,
 			inlineLockFile: overlay.inlineLockFile,
-			fullRepo: true
+			fullRepo: true,
+			...options.checkMode && { checkMode: options.checkMode },
+			...(() => {
+				const target = buildTargetSelector(options.targets, options.targetAllowEmpty ?? false);
+				return target ? { target } : {};
+			})()
 		});
 		if (triggerResult.status === "rejected") {
 			if (!options.quiet) logger.info(pc.red(`Rejected: ${triggerResult.reason ?? "unknown reason"}`));
@@ -371,6 +397,8 @@ async function pollRunToCompletion(ctx, runId, fixtureId, options) {
 	process.on("SIGINT", cancelHandler);
 	try {
 		let lastStatus = null;
+		const seenHolds = /* @__PURE__ */ new Set();
+		let heldCtx;
 		while (!cancelled) {
 			const logs = await ctx.client.runLogs(ctx.orgId, runId, cursor, ctx.target);
 			for (const line of logs.lines) {
@@ -380,7 +408,9 @@ async function pollRunToCompletion(ctx, runId, fixtureId, options) {
 			}
 			cursor = logs.nextCursor;
 			lastStatus = await ctx.client.runStatus(ctx.orgId, runId, ctx.target);
-			if ((lastStatus.done || TERMINAL_STATUSES.has(lastStatus.status)) && logs.done) return finishRun(fixtureId, runId, lastStatus, startTime, tailLines, options);
+			const terminal = lastStatus.done || TERMINAL_STATUSES.has(lastStatus.status);
+			if (terminal && logs.done) return finishRun(fixtureId, runId, lastStatus, startTime, tailLines, options);
+			if (!terminal && !options.quiet) await watchRunHolds(runId, seenHolds, () => heldCtx, (c) => heldCtx = c, options);
 			await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
 		}
 		return {
@@ -394,6 +424,34 @@ async function pollRunToCompletion(ctx, runId, fixtureId, options) {
 		process.removeListener("SIGINT", cancelHandler);
 	}
 }
+/**
+* Fetch this run's pending holds and surface them to the operator. The held-run
+* context is resolved lazily (cached across ticks via the getter/setter). A
+* resolution / fetch failure is swallowed — hold-visibility is best-effort and
+* must never abort the run watch.
+*/
+async function watchRunHolds(runId, seenHolds, getCtx, setCtx, options) {
+	try {
+		let ctx = getCtx();
+		if (ctx === void 0) {
+			ctx = await resolveHeldRunContext();
+			setCtx(ctx);
+		}
+		if (!ctx) return;
+		const holds = await listHeldRunsForRun(ctx, runId);
+		if (holds.length === 0) return;
+		await handleNewHolds({
+			holds,
+			seen: seenHolds,
+			isTty: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+			approveAll: Boolean(options.approveAll),
+			confirm: (message) => confirm({
+				message,
+				default: false
+			})
+		});
+	} catch {}
+}
 /** Build the final result + render the summary table for a completed run. */
 function finishRun(fixtureId, runId, status, startTime, tailLines, options) {
 	const durationMs = Date.now() - startTime;
@@ -481,7 +539,12 @@ async function runDirectWorkflow(workflowName, options) {
 			},
 			workflowName,
 			inlineLockFile: overlay.inlineLockFile,
-			fullRepo: true
+			fullRepo: true,
+			...options.checkMode && { checkMode: options.checkMode },
+			...(() => {
+				const target = buildTargetSelector(options.targets, options.targetAllowEmpty ?? false);
+				return target ? { target } : {};
+			})()
 		});
 		if (!options.quiet) logger.info(pc.green(`Run started: ${triggerResult.runId}`));
 		if (options.wait === false) return triggerResult.status === "accepted";
@@ -509,6 +572,6 @@ function displayRemoteResults(results) {
 	logger.info("");
 }
 //#endregion
-export { runLocalCommand, runRemoteCommand };
+export { buildTargetSelector, runLocalCommand, runRemoteCommand };
 
 //# sourceMappingURL=run.js.map

package/dist/commands/test.d.ts

@@ -1,4 +1,5 @@
 import { type PayloadOptions } from '../test-runner/payload-builder.js';
+import { type CheckMode } from '@kici-dev/engine';
 /** Options for the kici test command (dry-run trigger preview) */
 export interface TestOptions extends PayloadOptions {
     /** Filter to specific workflow */
@@ -38,6 +39,22 @@ export interface RemoteRunOptions extends TestOptions {
     org?: string;
     /** Target orchestrator cluster name (overrides the per-org default). */
     orchestrator?: string;
+    /**
+     * Run mode resolved from --check / --fail-on-drift, threaded onto the dispatch
+     * payload so the orchestrator runs the agent step loop in the requested mode.
+     * Defaults to `apply`.
+     */
+    checkMode?: CheckMode;
+    /** `--target <selector>` values (repeatable), AND-combined into host narrowing. */
+    targets?: string[];
+    /** `--target-allow-empty`: a target that zeroes a runsOnAll job skips it instead of failing. */
+    targetAllowEmpty?: boolean;
+    /**
+     * `--approve-all` (alias `--yes`): auto-approve every approval gate this run
+     * holds on (run-scoped only — the run id this invocation dispatched). The
+     * operator must still be clause-eligible per hold; an ineligible hold blocks.
+     */
+    approveAll?: boolean;
 }
 /** Result of a single remote fixture run */
 export interface RemoteRunResult {