@kici-dev/compiler 0.1.26 → 0.1.27

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

@@ -0,0 +1,97 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { randomUUID } from "node:crypto";
+import { AdminApiClient } from "@kici-dev/orchestrator";
+//#region src/local-plane/plane-trigger.ts
+/**
+* Trigger an offline routed run against the local plane and discover its runId.
+*
+* A local repo has no forge to send a webhook, so this posts a GitHub-shaped
+* synthetic push to the plane's provider-agnostic generic webhook route (the
+* same wire shape the `kici-admin source trigger-local` path builds). The
+* webhook is unauthenticated (the edge accepts it and returns 202); the run is
+* created asynchronously, so this then polls the admin runs list — authenticated
+* with the plane's bootstrap admin token — to resolve the created runId.
+*
+* The source's bundle hot-reload is debounced, so a first trigger can land
+* before the plane has registered the (re-pointed) local source. This resends
+* the webhook after a grace window until a run appears or the timeout elapses.
+*/
+/**
+* Build the GitHub-shaped webhook request the plane's local provider normalizer
+* expects. Mirrors `buildLocalTriggerRequest` in the orchestrator's
+* `cli/commands/local-trigger.ts` (kept local to honour the compiler-only scope
+* of this phase — no orchestrator export is added).
+*/
+function buildLocalTriggerRequest(input) {
+	const body = JSON.stringify({
+		ref: input.ref,
+		after: input.sha,
+		repository: {
+			full_name: input.repoFullName,
+			default_branch: input.defaultBranch
+		},
+		...input.event === "dispatch" && {
+			action: input.action,
+			client_payload: input.clientPayload ?? {}
+		}
+	});
+	return {
+		path: `/webhook/${input.orgId}/generic/${input.sourceId}`,
+		headers: {
+			"content-type": "application/json",
+			"x-event-type": input.event,
+			"x-delivery-id": randomUUID()
+		},
+		body
+	};
+}
+/** POST the trigger request to the plane. Returns the HTTP status. */
+async function sendLocalTrigger(planeUrl, req) {
+	return (await fetch(`${planeUrl.replace(/\/$/, "")}${req.path}`, {
+		method: "POST",
+		headers: req.headers,
+		body: req.body
+	})).status;
+}
+/**
+* Trigger the run and resolve its runId. Sends the synthetic push, then polls
+* the admin runs list (`created_at > since`) for the newest run, resending the
+* webhook past a grace window to absorb source hot-reload latency.
+*/
+async function triggerRun(planeUrl, adminToken, input, opts = {}) {
+	const client = opts.client ?? new AdminApiClient(planeUrl, adminToken);
+	const pollIntervalMs = opts.pollIntervalMs ?? 750;
+	const resendAfterMs = opts.resendAfterMs ?? 8e3;
+	const timeoutMs = opts.timeoutMs ?? 6e4;
+	const since = /* @__PURE__ */ new Date(Date.now() - 3e3);
+	const req = buildLocalTriggerRequest(input);
+	await sendLocalTrigger(planeUrl, req);
+	let lastSend = Date.now();
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const runId = await findLatestRunSince(client, since);
+		if (runId) return runId;
+		if (Date.now() - lastSend > resendAfterMs) {
+			await sendLocalTrigger(planeUrl, req);
+			lastSend = Date.now();
+		}
+		await sleep(pollIntervalMs);
+	}
+	throw new Error("offline run: no run appeared after triggering the local plane");
+}
+/** Return the newest run created after `since`, or null when none yet. */
+async function findLatestRunSince(client, since) {
+	const qs = new URLSearchParams({
+		since: since.toISOString(),
+		limit: "5"
+	});
+	const { runs } = await client.get(`/api/v1/admin/runs?${qs}`);
+	return runs[0]?.runId ?? null;
+}
+function sleep(ms) {
+	return new Promise((r) => setTimeout(r, ms));
+}
+//#endregion
+export { buildLocalTriggerRequest, sendLocalTrigger, triggerRun };
+
+//# sourceMappingURL=plane-trigger.js.map

package/dist/local-plane/platform-attach.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Platform attach helpers for the local dev plane. Pure HTTP/URL helpers with no
+ * plane side-effects: derive the orchestrator WS relay URL from the CLI's HTTPS
+ * API base, mint/revoke an org-scoped orchestrator key via the Platform API
+ * using the logged-in personal access token, and probe Platform reachability.
+ *
+ * The minted key (prefix `kici_ok_`) is what the plane presents on WS auth when
+ * it boots hybrid. It is org-scoped and created under the calling user's own
+ * `api_keys:write` permission — attach never mints anything the user could not
+ * mint from the dashboard.
+ */
+/**
+ * Derive the orchestrator WS relay URL from the CLI's HTTPS Platform API base.
+ * `https://…` → `wss://…`, `http://…` → `ws://…`, then ensure a single trailing
+ * `/ws` path segment (idempotent when the base already ends in `/ws`).
+ */
+export declare function derivePlatformWsUrl(apiBase: string): string;
+export interface MintedOrchestratorKey {
+    /** Raw orchestrator key (kici_ok_…) — present once. NEVER log this. */
+    key: string;
+    /** Platform api_keys id (for later revoke). */
+    keyId: string;
+    keyPrefix: string;
+}
+/**
+ * Mint an org-scoped orchestrator key via the Platform HTTP API using the PAT.
+ * `POST ${apiBase}/api/v1/orgs/${orgId}/orchestrator-keys`.
+ */
+export declare function mintOrchestratorKey(args: {
+    apiBase: string;
+    pat: string;
+    orgId: string;
+    name?: string;
+}): Promise<MintedOrchestratorKey>;
+/**
+ * Best-effort revoke of a previously-minted orchestrator key on detach.
+ * `DELETE ${apiBase}/api/v1/orgs/${orgId}/orchestrator-keys/${keyId}`. Never
+ * throws — a failed revoke (offline, expired PAT) is non-fatal; the key is
+ * org-scoped and the local plane stops presenting it regardless.
+ */
+export declare function revokeOrchestratorKey(args: {
+    apiBase: string;
+    pat: string;
+    orgId: string;
+    keyId: string;
+}): Promise<boolean>;
+/**
+ * Bounded reachability probe against the Platform API base. Returns true when
+ * the base responds (any HTTP status — a reachable Platform, even a 401/404 on
+ * `/health`, proves the network path). A timeout / network error is false.
+ */
+export declare function probePlatformReachable(apiBase: string, timeoutMs?: number): Promise<boolean>;
+//# sourceMappingURL=platform-attach.d.ts.map

package/dist/local-plane/platform-attach.js

@@ -0,0 +1,111 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { toErrorMessage } from "@kici-dev/core";
+//#region src/local-plane/platform-attach.ts
+/**
+* Platform attach helpers for the local dev plane. Pure HTTP/URL helpers with no
+* plane side-effects: derive the orchestrator WS relay URL from the CLI's HTTPS
+* API base, mint/revoke an org-scoped orchestrator key via the Platform API
+* using the logged-in personal access token, and probe Platform reachability.
+*
+* The minted key (prefix `kici_ok_`) is what the plane presents on WS auth when
+* it boots hybrid. It is org-scoped and created under the calling user's own
+* `api_keys:write` permission — attach never mints anything the user could not
+* mint from the dashboard.
+*/
+/**
+* Derive the orchestrator WS relay URL from the CLI's HTTPS Platform API base.
+* `https://…` → `wss://…`, `http://…` → `ws://…`, then ensure a single trailing
+* `/ws` path segment (idempotent when the base already ends in `/ws`).
+*/
+function derivePlatformWsUrl(apiBase) {
+	let url;
+	try {
+		url = new URL(apiBase);
+	} catch {
+		throw new Error(`Invalid Platform API base URL: ${apiBase}`);
+	}
+	if (url.protocol === "https:") url.protocol = "wss:";
+	else if (url.protocol === "http:") url.protocol = "ws:";
+	else throw new Error(`Platform API base must be http(s): ${apiBase}`);
+	const trimmed = url.pathname.replace(/\/+$/, "");
+	url.pathname = trimmed.endsWith("/ws") ? trimmed : `${trimmed}/ws`;
+	url.search = "";
+	url.hash = "";
+	return url.toString();
+}
+/**
+* Mint an org-scoped orchestrator key via the Platform HTTP API using the PAT.
+* `POST ${apiBase}/api/v1/orgs/${orgId}/orchestrator-keys`.
+*/
+async function mintOrchestratorKey(args) {
+	const url = `${args.apiBase.replace(/\/+$/, "")}/api/v1/orgs/${encodeURIComponent(args.orgId)}/orchestrator-keys`;
+	let res;
+	try {
+		res = await fetch(url, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${args.pat}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({ name: args.name ?? `local dev plane (${orgHostLabel()})` })
+		});
+	} catch (err) {
+		throw new Error(`Could not reach the Platform to mint an orchestrator key: ${toErrorMessage(err)}`);
+	}
+	if (res.status === 401) throw new Error("Platform rejected the credentials (401). Run `kici login` to re-authenticate.");
+	if (res.status === 403) throw new Error(`Your account lacks permission to create orchestrator keys in org ${args.orgId} (needs the api_keys:write permission — an Owner can grant it).`);
+	if (!res.ok) throw new Error(`Platform returned ${res.status} minting the orchestrator key.`);
+	const body = await res.json();
+	if (!body.key || !body.id) throw new Error("Platform orchestrator-key response was missing the key or id.");
+	return {
+		key: body.key,
+		keyId: body.id,
+		keyPrefix: body.keyPrefix ?? "kici_ok_"
+	};
+}
+/**
+* Best-effort revoke of a previously-minted orchestrator key on detach.
+* `DELETE ${apiBase}/api/v1/orgs/${orgId}/orchestrator-keys/${keyId}`. Never
+* throws — a failed revoke (offline, expired PAT) is non-fatal; the key is
+* org-scoped and the local plane stops presenting it regardless.
+*/
+async function revokeOrchestratorKey(args) {
+	const url = `${args.apiBase.replace(/\/+$/, "")}/api/v1/orgs/${encodeURIComponent(args.orgId)}/orchestrator-keys/${encodeURIComponent(args.keyId)}`;
+	try {
+		return (await fetch(url, {
+			method: "DELETE",
+			headers: { Authorization: `Bearer ${args.pat}` }
+		})).ok;
+	} catch {
+		return false;
+	}
+}
+/**
+* Bounded reachability probe against the Platform API base. Returns true when
+* the base responds (any HTTP status — a reachable Platform, even a 401/404 on
+* `/health`, proves the network path). A timeout / network error is false.
+*/
+async function probePlatformReachable(apiBase, timeoutMs = 4e3) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const url = `${apiBase.replace(/\/+$/, "")}/health`;
+		return (await fetch(url, { signal: controller.signal })).status > 0;
+	} catch {
+		return false;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** A short, non-sensitive label for the minted key name (the machine host). */
+function orgHostLabel() {
+	try {
+		return process.env.HOSTNAME || "kici-local";
+	} catch {
+		return "kici-local";
+	}
+}
+//#endregion
+export { derivePlatformWsUrl, mintOrchestratorKey, probePlatformReachable, revokeOrchestratorKey };
+
+//# sourceMappingURL=platform-attach.js.map

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

@@ -0,0 +1,44 @@
+/**
+ * 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 a podman binary is available on PATH. */
+export declare function isPodmanAvailable(): 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).
+ */
+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,165 @@
+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 { spawn } from "node:child_process";
+import os from "node:os";
+import { $ } from "zx";
+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;
+}
+/** 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
+* 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();
+}
+/**
+* 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).
+*/
+async function defaultEmbeddedDaemon(port) {
+	const { pgData, logFile } = planePaths();
+	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, isPodmanAvailable, 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,41 @@
+/**
+ * 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.
+ */
+/** 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;
+}
+/** 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