@kici-dev/compiler 0.1.26 → 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

@@ -0,0 +1,56 @@
+/**
+ * Podman fallback Postgres image for the local dev plane. Pinned via
+ * `TS_CONST_PINS` in hack/containers-lock.ts (identity
+ * docker.io/library/postgres+alpine), so a lock bump rewrites it in place.
+ */
+export declare const PLANE_PG_IMAGE = "docker.io/library/postgres:18.4-alpine";
+/** Name of the fallback podman Postgres container. */
+export declare const PLANE_PG_CONTAINER = "kici-local-postgres";
+export type PlanePgHandle = {
+    url: string;
+    kind: 'embedded' | 'podman';
+    stop(): Promise<void>;
+};
+declare let readyPoller: typeof defaultReadyPoller;
+/** Test seam: override the podman readiness poller. */
+export declare function __setReadyPollerForTest(fn: typeof readyPoller): void;
+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 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). A cluster already serving this
+ * plane's port is reused as-is.
+ */
+declare function defaultEmbeddedDaemon(port: number): Promise<void>;
+/**
+ * Stop the plane's Postgres by backend kind. Handle-independent so a separate
+ * CLI invocation (`kici local down`) can tear down what `up` started.
+ */
+export declare function stopPlanePostgres(kind: 'embedded' | 'podman'): Promise<void>;
+/**
+ * Provision the local dev plane's Postgres. Prefers the zero-dependency
+ * `embedded-postgres` binary (daemonized via pg_ctl so it stays warm); falls
+ * back to a podman Postgres container when the embedded binary is unavailable
+ * (or when forced via `forcePodman` / `KICI_LOCAL_PG_MODE=podman`).
+ */
+export declare function startPlanePostgres(opts?: {
+    forcePodman?: boolean;
+}): Promise<PlanePgHandle>;
+export {};
+//# sourceMappingURL=postgres.d.ts.map

package/dist/local-plane/postgres.js

@@ -0,0 +1,187 @@
+import "../rolldown-runtime-ClRpJifh.js";
+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 EmbeddedPostgres from "embedded-postgres";
+//#region src/local-plane/postgres.ts
+/**
+* Podman fallback Postgres image for the local dev plane. Pinned via
+* `TS_CONST_PINS` in hack/containers-lock.ts (identity
+* docker.io/library/postgres+alpine), so a lock bump rewrites it in place.
+*/
+const PLANE_PG_IMAGE = "docker.io/library/postgres:18.4-alpine";
+/** Name of the fallback podman Postgres container. */
+const PLANE_PG_CONTAINER = "kici-local-postgres";
+let readyPoller = defaultReadyPoller;
+/** Test seam: override the podman readiness poller. */
+function __setReadyPollerForTest(fn) {
+	readyPoller = fn;
+}
+let embeddedDaemon = defaultEmbeddedDaemon;
+/** Test seam: override the embedded postmaster daemonizer. */
+function __setEmbeddedDaemonForTest(fn) {
+	embeddedDaemon = fn;
+}
+async function defaultReadyPoller(_port) {
+	for (let i = 0; i < 60; i++) try {
+		await $`podman exec ${PLANE_PG_CONTAINER} pg_isready -U kici`.quiet();
+		return true;
+	} catch {
+		await new Promise((r) => setTimeout(r, 500));
+	}
+	return false;
+}
+/**
+* Resolve the platform-specific `pg_ctl` binary bundled with embedded-postgres.
+* Mirrors the package's own platform → binary-package mapping, resolving the
+* binary package through embedded-postgres's module context (pnpm isolates it
+* as a transitive dependency, so it is not directly resolvable here) and
+* computing the `native/bin/pg_ctl` path from the resolved package directory.
+*/
+function resolvePgCtl() {
+	const platform = os.platform();
+	const arch = os.arch();
+	const pkg = {
+		"darwin:arm64": "@embedded-postgres/darwin-arm64",
+		"darwin:x64": "@embedded-postgres/darwin-x64",
+		"linux:arm64": "@embedded-postgres/linux-arm64",
+		"linux:arm": "@embedded-postgres/linux-arm",
+		"linux:ia32": "@embedded-postgres/linux-ia32",
+		"linux:ppc64": "@embedded-postgres/linux-ppc64",
+		"linux:x64": "@embedded-postgres/linux-x64",
+		"win32:x64": "@embedded-postgres/windows-x64"
+	}[`${platform}:${arch}`];
+	if (!pkg) throw new Error(`unsupported platform for embedded Postgres: ${platform}/${arch}`);
+	const entry = createRequire(createRequire(import.meta.url).resolve("embedded-postgres")).resolve(pkg);
+	const binName = platform === "win32" ? "pg_ctl.exe" : "pg_ctl";
+	return path.resolve(path.dirname(entry), "..", "native", "bin", binName);
+}
+/**
+* Initialise the embedded Postgres cluster + the `kici_local` database once. A
+* short-lived in-process server is used only for the one-time bootstrap; the
+* persistent postmaster is started separately (daemonized) so it outlives this
+* CLI invocation.
+*/
+async function ensureEmbeddedCluster(port) {
+	const { pgData } = planePaths();
+	if (fs.existsSync(path.join(pgData, "PG_VERSION"))) return;
+	const pg = new EmbeddedPostgres({
+		databaseDir: pgData,
+		port,
+		user: "kici",
+		password: "kici",
+		persistent: true
+	});
+	await pg.initialise();
+	await pg.start();
+	await pg.createDatabase("kici_local").catch(() => {});
+	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). 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). */
+async function stopEmbeddedDaemon() {
+	const { pgData } = planePaths();
+	if (!fs.existsSync(path.join(pgData, "postmaster.pid"))) return;
+	await $`${resolvePgCtl()} -D ${pgData} stop -m fast`.quiet().catch(() => {});
+}
+/**
+* Stop the plane's Postgres by backend kind. Handle-independent so a separate
+* CLI invocation (`kici local down`) can tear down what `up` started.
+*/
+async function stopPlanePostgres(kind) {
+	if (kind === "podman") await $`podman rm -f ${PLANE_PG_CONTAINER}`.quiet().catch(() => {});
+	else await stopEmbeddedDaemon();
+}
+/**
+* Provision the local dev plane's Postgres. Prefers the zero-dependency
+* `embedded-postgres` binary (daemonized via pg_ctl so it stays warm); falls
+* back to a podman Postgres container when the embedded binary is unavailable
+* (or when forced via `forcePodman` / `KICI_LOCAL_PG_MODE=podman`).
+*/
+async function startPlanePostgres(opts = {}) {
+	const { postgres: port } = planePorts();
+	const url = `postgres://kici:kici@127.0.0.1:${port}/kici_local`;
+	if (!(opts.forcePodman || process.env.KICI_LOCAL_PG_MODE === "podman")) try {
+		await ensureEmbeddedCluster(port);
+		await embeddedDaemon(port);
+		return {
+			url,
+			kind: "embedded",
+			stop: () => stopEmbeddedDaemon()
+		};
+	} catch {}
+	spawn("podman", [
+		"run",
+		"-d",
+		"--replace",
+		"--name",
+		PLANE_PG_CONTAINER,
+		"-p",
+		`127.0.0.1:${port}:5432`,
+		"-e",
+		"POSTGRES_USER=kici",
+		"-e",
+		"POSTGRES_PASSWORD=kici",
+		"-e",
+		"POSTGRES_DB=kici_local",
+		PLANE_PG_IMAGE
+	], {
+		stdio: "ignore",
+		detached: true
+	}).unref();
+	if (!await readyPoller(port)) throw new Error("local Postgres (podman) did not become ready");
+	return {
+		url,
+		kind: "podman",
+		stop: async () => {
+			await $`podman rm -f ${PLANE_PG_CONTAINER}`.quiet().catch(() => {});
+		}
+	};
+}
+//#endregion
+export { PLANE_PG_CONTAINER, PLANE_PG_IMAGE, __setEmbeddedDaemonForTest, __setReadyPollerForTest, embeddedClusterIsServing, startPlanePostgres, stopPlanePostgres };
+
+//# sourceMappingURL=postgres.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * Plane auto-selection for `kici run --local` (design §5).
+ *
+ * Rules:
+ * - `--offline`   → force the independent (offline) plane.
+ * - `--connected` → require an attached plane; hard-error if not attached, and
+ *   hard-error if the Platform is unreachable (the user explicitly demanded it).
+ * - neither flag  → attached + Platform reachable → hybrid; attached but the
+ *   Platform is unreachable → fall back to the independent plane with a loud
+ *   banner; not attached → offline.
+ *
+ * The fallback is the "mid-session Platform-unreachable" guarantee: a `--local`
+ * run never fails just because the Platform is unreachable (unless `--connected`).
+ * It re-boots/keeps the independent plane and continues on local secrets +
+ * dev-signed identity.
+ */
+import { type PlaneStatus } from './plane-manager.js';
+export interface ResolvePlaneFlags {
+    offline?: boolean;
+    connected?: boolean;
+}
+export type ResolvedPlane = {
+    kind: 'offline';
+    plane: PlaneStatus;
+} | {
+    kind: 'attached';
+    plane: PlaneStatus;
+    orgId: string;
+} | {
+    kind: 'fallback';
+    plane: PlaneStatus;
+    reason: string;
+} | {
+    error: string;
+};
+export declare function resolvePlaneForRun(flags: ResolvePlaneFlags): Promise<ResolvedPlane>;
+//# sourceMappingURL=resolve-plane.d.ts.map

package/dist/local-plane/resolve-plane.js

@@ -0,0 +1,76 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { probePlatformReachable } from "./platform-attach.js";
+import { planeUp, readAttachment, readPlatformToken } from "./plane-manager.js";
+//#region src/local-plane/resolve-plane.ts
+/**
+* Plane auto-selection for `kici run --local` (design §5).
+*
+* Rules:
+* - `--offline`   → force the independent (offline) plane.
+* - `--connected` → require an attached plane; hard-error if not attached, and
+*   hard-error if the Platform is unreachable (the user explicitly demanded it).
+* - neither flag  → attached + Platform reachable → hybrid; attached but the
+*   Platform is unreachable → fall back to the independent plane with a loud
+*   banner; not attached → offline.
+*
+* The fallback is the "mid-session Platform-unreachable" guarantee: a `--local`
+* run never fails just because the Platform is unreachable (unless `--connected`).
+* It re-boots/keeps the independent plane and continues on local secrets +
+* dev-signed identity.
+*/
+/** Boot the hybrid plane from the durable attachment record + persisted token. */
+async function bootAttached(attachment) {
+	const token = readPlatformToken();
+	if (!token) return { error: "The plane is attached but its Platform token is missing — run `kici local attach` to re-attach." };
+	return planeUp({ attach: {
+		platformWsUrl: attachment.platformWsUrl,
+		platformToken: token,
+		platformApiBase: attachment.platformApiBase,
+		orgId: attachment.orgId,
+		keyId: attachment.keyId
+	} });
+}
+async function resolvePlaneForRun(flags) {
+	const attachment = readAttachment();
+	if (flags.offline) return {
+		kind: "offline",
+		plane: await planeUp()
+	};
+	if (flags.connected) {
+		if (!attachment) return { error: "Not attached to the Platform. Run `kici local attach` first (or drop --connected)." };
+		if (!await probePlatformReachable(attachment.platformApiBase)) return { error: `Platform ${attachment.platformApiBase} is unreachable — cannot honor --connected.` };
+		const booted = await bootAttached(attachment);
+		if ("error" in booted) return booted;
+		return {
+			kind: "attached",
+			plane: booted,
+			orgId: attachment.orgId
+		};
+	}
+	if (!attachment) return {
+		kind: "offline",
+		plane: await planeUp()
+	};
+	if (await probePlatformReachable(attachment.platformApiBase)) {
+		const booted = await bootAttached(attachment);
+		if ("error" in booted) return {
+			kind: "fallback",
+			plane: await planeUp(),
+			reason: booted.error
+		};
+		return {
+			kind: "attached",
+			plane: booted,
+			orgId: attachment.orgId
+		};
+	}
+	return {
+		kind: "fallback",
+		plane: await planeUp(),
+		reason: "Platform unreachable"
+	};
+}
+//#endregion
+export { resolvePlaneForRun };
+
+//# sourceMappingURL=resolve-plane.js.map

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

@@ -0,0 +1,61 @@
+/**
+ * Follow an offline routed run against the local plane by polling the
+ * 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>;
+}
+/** Terminal outcome of a followed run. */
+export interface RunOutcome {
+    runId: string;
+    status: string;
+    jobs: Array<{
+        name: string;
+        status: string;
+        durationMs?: number;
+    }>;
+}
+export interface FollowRunOptions {
+    onLine?: (line: string) => void;
+    quiet?: boolean;
+    client?: RunFollowClient;
+    pollIntervalMs?: number;
+    /**
+     * Idle window: the max time with NO observed progress (no new log line, no run
+     * status change) before the follow gives up. Resets on every progress tick, so
+     * a legitimately long run (e.g. a full `deploy:stg`, tens of minutes of image
+     * builds + host mutation) never times out while it is actively advancing —
+     * only a genuinely stalled run does. Default 15 min. `timeoutMs` is a
+     * back-compat alias.
+     */
+    idleTimeoutMs?: number;
+    /** @deprecated Back-compat alias for `idleTimeoutMs`. */
+    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>;
+//# sourceMappingURL=run-follow.d.ts.map