@kici-dev/compiler 0.1.27 → 0.3.0

package/dist/llm-context/llms.txt

@@ -8,19 +8,23 @@ The full markdown bundle of every page indexed here is available at https://docs
 
 Each bundle below is a self-contained markdown file for one authoring task. Fetch only the one your task needs instead of the full bundle:
 
-- [getting-started](https://docs.kici.dev/llms-getting-started.txt) (25 KB) — Install the SDK, write your first workflow, compile and test locally
-- [patterns](https://docs.kici.dev/llms-patterns.txt) (48 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
-- [sdk](https://docs.kici.dev/llms-sdk.txt) (190 KB) — Authoring API: workflow/job/step factories, triggers, rules, matrix, runtime, caching
-- [cli](https://docs.kici.dev/llms-cli.txt) (135 KB) — Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift
-- [features](https://docs.kici.dev/llms-features.txt) (125 KB) — Workflow features: concurrency, contexts, secrets, approvals, provenance, events
+- [getting-started](https://docs.kici.dev/llms-getting-started.txt) (51 KB) — Adopt KiCI: why it exists, how workflows execute, migrating from GitHub Actions, installing the SDK, and writing/compiling/testing your first workflow
+- [patterns](https://docs.kici.dev/llms-patterns.txt) (49 KB) — Copy-paste workflow recipes: triggers, conditionals, matrix, scheduling, integrations
+- [sdk](https://docs.kici.dev/llms-sdk.txt) (110 KB) — Core authoring API: workflow/job/step factories, triggers, rules, matrix, dynamic jobs, cross-job outputs
+- [sdk-runtime](https://docs.kici.dev/llms-sdk-runtime.txt) (112 KB) — Runtime and advanced authoring: step runtime context, event payloads, host fan-out, idempotent steps, caching, artifacts, waiting
+- [cli](https://docs.kici.dev/llms-cli.txt) (185 KB) — Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift
+- [features](https://docs.kici.dev/llms-features.txt) (135 KB) — Workflow features: concurrency, contexts, secrets, approvals, provenance, events
 - [providers](https://docs.kici.dev/llms-providers.txt) (37 KB) — Connecting sources: GitHub App, universal-git (Forgejo/Gitea/GitLab), local file://
-- [architecture](https://docs.kici.dev/llms-architecture.txt) (87 KB) — How the runtime works: three-tier relay model, data flows, configuration
+- [architecture](https://docs.kici.dev/llms-architecture.txt) (92 KB) — How the runtime works: three-tier relay model, data flows, configuration
 
 ## Getting started
 
-- [User guide](https://docs.kici.dev/user/): Writing and testing CI/CD workflows in TypeScript
+- [User guide](https://docs.kici.dev/user/): Writing and testing CI/CD workflows in TypeScript, running on infrastructure you control
+- [How your workflow code executes](https://docs.kici.dev/user/execution-model/): When and where your workflow TypeScript runs — compile time, orchestrator time, and agent time
 - [Getting started with workflows](https://docs.kici.dev/user/getting-started/): Install the SDK, write your first workflow, compile and test locally
+- [Migrating from GitHub Actions](https://docs.kici.dev/user/migrating-from-github-actions/): Map GitHub Actions concepts to KiCI, translate a real workflow side-by-side, and see what has no equivalent yet
 - [5-minute quickstart](https://docs.kici.dev/user/quickstart/): Stand up a KiCI orchestrator + agent and run your first workflow
+- [Why KiCI](https://docs.kici.dev/user/why-kici/): The case for running CI on infrastructure you control, with typed TypeScript workflows you test locally
 
 ## Workflow patterns
 
@@ -31,30 +35,40 @@ Each bundle below is a self-contained markdown file for one authoring task. Fetc
 - [Pattern reference](https://docs.kici.dev/user/patterns/reference/): Step context, examples repository, GitHub check run output — cross-cutting reference for all patterns
 - [Scheduling & event patterns](https://docs.kici.dev/user/patterns/scheduling-and-events/): Nightly cron, workflow-complete-triggered deploys, custom event chaining
 
-## SDK reference
+## SDK reference: core
 
-- [Caching](https://docs.kici.dev/user/sdk/caching/): Cache files and directories across runs with declarative job/step cache or the imperative ctx.cache API
 - [SDK reference: core](https://docs.kici.dev/user/sdk/core/): Factory functions (workflow, job, step) and authoring patterns: needs, output chaining, dynamic groups
-- [Event payload reference](https://docs.kici.dev/user/sdk/event-payloads/): Generated schema of the normalized event envelope passed to rules and dynamic functions.
-- [SDK reference: idempotent](https://docs.kici.dev/user/sdk/idempotent/): Idempotent helpers for declarative check / apply patterns inside workflow steps
 - [SDK reference: parallel](https://docs.kici.dev/user/sdk/parallel/): Run independent steps concurrently within a single job, each as its own observable step
 - [SDK reference: rules, matrix, dynamic jobs](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/): rule(), skip(), matrix builds (static + dynamic), and dynamicJob / dynamicGroup
+- [SDK reference: triggers](https://docs.kici.dev/user/sdk/triggers/): GitHub event triggers, kiciEvent, workflowComplete, workflowsFailedBatch, jobComplete, genericWebhook, schedule, lifecycle
+- [SDK reference: validation & events](https://docs.kici.dev/user/sdk/validation-events/): validateDag(), event definitions, and event emission
+- [SDK reference](https://docs.kici.dev/user/sdk-reference/): Complete API reference for @kici-dev/sdk -- workflows, jobs, steps, triggers, rules, matrix, validation, runtime
+
+## SDK reference: runtime and advanced
+
+- [Artifacts](https://docs.kici.dev/user/sdk/artifacts/): Share named, durable build outputs between jobs of a run and download them from the run page with ctx.artifacts
+- [Caching](https://docs.kici.dev/user/sdk/caching/): Cache files and directories across runs with declarative job/step cache or the imperative ctx.cache API
+- [Event payload reference](https://docs.kici.dev/user/sdk/event-payloads/): Generated schema of the normalized event envelope passed to rules and dynamic functions.
+- [SDK reference: idempotent](https://docs.kici.dev/user/sdk/idempotent/): Idempotent helpers for declarative check / apply patterns inside workflow steps
 - [SDK reference: runsOnAll host fan-out](https://docs.kici.dev/user/sdk/runs-on-all/): Fan one job out to every matching connected host, one pinned execution per host
 - [SDK reference: runtime](https://docs.kici.dev/user/sdk/runtime/): Types index, StepContext, secrets, fixtures
-- [SDK reference: triggers](https://docs.kici.dev/user/sdk/triggers/): GitHub event triggers, kiciEvent, workflowComplete, jobComplete, genericWebhook, schedule, lifecycle
-- [SDK reference: validation & events](https://docs.kici.dev/user/sdk/validation-events/): validateDag(), event definitions, and event emission
+- [SDK reference: temp directories](https://docs.kici.dev/user/sdk/temp-directories/): Allocate job-scoped scratch dirs and files with ctx.mktemp() / ctx.mktempFile()
 - [SDK reference: waitFor](https://docs.kici.dev/user/sdk/wait-for/): Polling helpers for steps that pause until an external condition becomes true
-- [SDK reference](https://docs.kici.dev/user/sdk-reference/): Complete API reference for @kici-dev/sdk -- workflows, jobs, steps, triggers, rules, matrix, validation, runtime
 
 ## CLI and authoring
 
 - [Drive KiCI from your coding agent](https://docs.kici.dev/user/ai-agents/): Point a coding agent at KiCI's MCP server and let it trigger, read, and re-run your CI under your own identity.
 - [CLI authentication](https://docs.kici.dev/user/cli-auth/): Authenticate the KiCI CLI with browser OAuth, device flow, or API key paste
-- [CLI reference](https://docs.kici.dev/user/cli-reference/): All CLI commands: compile, run (local/remote), orchestrators, preview, login, logout, org, diagnostics, runs (list/show/logs/rerun/cancel), secrets, types, fixture, init, hook, endpoints, workflows, docs, admin
+- [CLI reference](https://docs.kici.dev/user/cli-reference/): All CLI commands: compile, preview, local, fixture, types, workflows, hook, docs, run, runs, approve, reject, login, logout, init, org, pat, secrets, admin, orchestrators, endpoints, notifications, verify-attestation, diagnostics, doctor
+- [Common failures](https://docs.kici.dev/user/common-failures/): Symptom-to-fix reference for the failures workflow authors hit most — no jobs dispatched, lock-file drift, missing webhooks, and agents that won't connect
 - [Lifecycle hooks](https://docs.kici.dev/user/hooks/): SDK hook API for cancel, cleanup, success, failure, and step-level callbacks
 - [Lock file and workflow drift](https://docs.kici.dev/user/lock-file-and-drift/): Keep the lock file in sync with your workflow source and avoid drift
 - [Testing guide](https://docs.kici.dev/user/testing-guide/): Running remote test fixtures with kici run remote
 - [Workflow patterns](https://docs.kici.dev/user/workflow-patterns/): Common patterns: monorepo builds, conditional jobs, dynamic matrices, generic webhooks, scheduling
+- [kici: account & org](https://docs.kici.dev/user/cli/account-and-org/): Login, org selection, personal access tokens, secrets, and admin
+- [kici: authoring & local dev](https://docs.kici.dev/user/cli/authoring-and-local/): Compile, preview, local execution, fixtures, types, workflows, hooks, and docs
+- [kici: notifications & diagnostics](https://docs.kici.dev/user/cli/notifications-and-diagnostics/): Notification channels, attestation verification, and diagnostics
+- [kici: runs & approvals](https://docs.kici.dev/user/cli/runs-and-approvals/): Run push and inspection plus approval / rejection of held runs
 
 ## Workflow features
 
@@ -64,7 +78,7 @@ Each bundle below is a self-contained markdown file for one authoring task. Fetc
 - [Contexts](https://docs.kici.dev/user/contexts/): Configure deployment contexts with variables, secrets, and protection rules
 - [Dashboard](https://docs.kici.dev/user/dashboard/): Web UI for monitoring workflow runs, managing sources, secrets, and organization settings.
 - [Dynamic values](https://docs.kici.dev/user/dynamic-values/)
-- [Environment variables](https://docs.kici.dev/user/env-vars/): KICI_* environment variable reference for the CLI
+- [Environment variables](https://docs.kici.dev/user/env-vars/): Environment variable reference for the CLI
 - [Event system](https://docs.kici.dev/user/events/): How KiCI's event model works -- event types, the registration model, event matching, and circuit breaker protection
 - [Global workflows](https://docs.kici.dev/user/global-workflows/): Cross-repo workflows that run on events from any repo in the same org
 - [Idempotent steps and check mode](https://docs.kici.dev/user/idempotent-steps/): Declare desired state with a step check facet, then run in apply or --check preview mode

package/dist/local-plane/orchestrator-process.d.ts

@@ -52,14 +52,19 @@ export interface SpawnOrchestratorOptions {
     };
 }
 /**
- * Spawn the orchestrator's standalone entry in independent mode against the
- * local Postgres, detached, with stdout/stderr redirected to the plane log.
- * Boots with a bootstrap admin token (so the CLI can drive the admin API) and a
- * bare-metal scaler (so a dispatched job auto-spawns an ephemeral agent). Waits
- * for `GET /ready` to report warm, then returns the child pid + port.
+ * Spawn the orchestrator entry against the local Postgres, detached, with
+ * stdout/stderr redirected to the plane log, and return immediately. Boots with
+ * a bootstrap admin token (so the CLI can drive the admin API) and a bare-metal
+ * scaler (so a dispatched job auto-spawns an ephemeral agent).
+ *
+ * Returning before the process is ready is deliberate: it lets the caller record
+ * the pid on disk BEFORE the readiness wait, so a wait that fails or a CLI that
+ * dies mid-boot cannot leave a running orchestrator that nothing can identify.
  */
-export declare function spawnOrchestrator(databaseUrl: string, opts: SpawnOrchestratorOptions): Promise<{
+export declare function spawnOrchestratorProcess(databaseUrl: string, opts: SpawnOrchestratorOptions): {
     pid: number;
     port: number;
-}>;
+};
+/** Poll `/ready` until the orchestrator serves, or throw once the attempts run out. */
+export declare function awaitOrchestratorReady(port: number, attempts?: number, intervalMs?: number): Promise<void>;
 //# sourceMappingURL=orchestrator-process.d.ts.map

package/dist/local-plane/orchestrator-process.js

@@ -30,22 +30,32 @@ function resolveStandaloneEntry() {
 function resolveServerEntry() {
 	return createRequire(import.meta.url).resolve("@kici-dev/orchestrator/server");
 }
+/**
+* Cap on one readiness probe. Generous enough for a server still warming up,
+* bounded so a socket that accepts and then goes silent cannot stall the poll
+* for the HTTP client's own multi-minute default — which would make
+* `awaitOrchestratorReady`'s attempt budget meaningless.
+*/
+const READY_PROBE_TIMEOUT_MS = 5e3;
 /** Single `/ready` probe against the local orchestrator. */
 async function orchestratorReady(port) {
 	try {
-		return (await fetch(`http://127.0.0.1:${port}/ready`)).status === 200;
+		return (await fetch(`http://127.0.0.1:${port}/ready`, { signal: AbortSignal.timeout(READY_PROBE_TIMEOUT_MS) })).status === 200;
 	} catch {
 		return false;
 	}
 }
 /**
-* Spawn the orchestrator's standalone entry in independent mode against the
-* local Postgres, detached, with stdout/stderr redirected to the plane log.
-* Boots with a bootstrap admin token (so the CLI can drive the admin API) and a
-* bare-metal scaler (so a dispatched job auto-spawns an ephemeral agent). Waits
-* for `GET /ready` to report warm, then returns the child pid + port.
+* Spawn the orchestrator entry against the local Postgres, detached, with
+* stdout/stderr redirected to the plane log, and return immediately. Boots with
+* a bootstrap admin token (so the CLI can drive the admin API) and a bare-metal
+* scaler (so a dispatched job auto-spawns an ephemeral agent).
+*
+* Returning before the process is ready is deliberate: it lets the caller record
+* the pid on disk BEFORE the readiness wait, so a wait that fails or a CLI that
+* dies mid-boot cannot leave a running orchestrator that nothing can identify.
 */
-async function spawnOrchestrator(databaseUrl, opts) {
+function spawnOrchestratorProcess(databaseUrl, opts) {
 	const { orchestrator: port } = planePorts();
 	const { logFile, root, cacheDir } = planePaths();
 	fs.mkdirSync(root, { recursive: true });
@@ -100,16 +110,20 @@ async function spawnOrchestrator(databaseUrl, opts) {
 		}
 	});
 	child.unref();
-	for (let i = 0; i < 120; i++) {
-		if (await orchestratorReady(port)) return {
-			pid: child.pid,
-			port
-		};
-		await new Promise((r) => setTimeout(r, 500));
+	return {
+		pid: child.pid,
+		port
+	};
+}
+/** Poll `/ready` until the orchestrator serves, or throw once the attempts run out. */
+async function awaitOrchestratorReady(port, attempts = 120, intervalMs = 500) {
+	for (let i = 0; i < attempts; i++) {
+		if (await orchestratorReady(port)) return;
+		await new Promise((r) => setTimeout(r, intervalMs));
 	}
 	throw new Error("local orchestrator did not become ready");
 }
 //#endregion
-export { orchestratorReady, resolveAgentReachableHost, resolveServerEntry, resolveStandaloneEntry, spawnOrchestrator };
+export { awaitOrchestratorReady, orchestratorReady, resolveAgentReachableHost, resolveServerEntry, resolveStandaloneEntry, spawnOrchestratorProcess };
 
 //# sourceMappingURL=orchestrator-process.js.map

package/dist/local-plane/os-mismatch-hint.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Detect when a routed local run cannot match the host OS.
+ *
+ * The local dev plane satisfies the host's own `kici:os:*` label (the scaler
+ * injects the host's derived OS labels into its bare-metal label sets). A job
+ * that requests a DIFFERENT OS than the host — e.g. a workflow authored on Linux
+ * run on a Mac — matches no local backend and dispatches nothing. This surfaces
+ * that as an honest hint instead of a silent "nothing happened".
+ */
+/**
+ * One hint per job whose `runsOn` requires a `kici:os:*` label the host does not
+ * provide. Empty when every job either omits an OS selector or requests the
+ * host's own OS.
+ */
+export declare function detectOsMismatchHints(lock: unknown, platform: string, arch: string): string[];
+//# sourceMappingURL=os-mismatch-hint.d.ts.map

package/dist/local-plane/os-mismatch-hint.js

@@ -0,0 +1,34 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { deriveOsArchLabels } from "@kici-dev/engine";
+//#region src/local-plane/os-mismatch-hint.ts
+/**
+* Detect when a routed local run cannot match the host OS.
+*
+* The local dev plane satisfies the host's own `kici:os:*` label (the scaler
+* injects the host's derived OS labels into its bare-metal label sets). A job
+* that requests a DIFFERENT OS than the host — e.g. a workflow authored on Linux
+* run on a Mac — matches no local backend and dispatches nothing. This surfaces
+* that as an honest hint instead of a silent "nothing happened".
+*/
+const OS_LABEL_PREFIX = "kici:os:";
+/**
+* One hint per job whose `runsOn` requires a `kici:os:*` label the host does not
+* provide. Empty when every job either omits an OS selector or requests the
+* host's own OS.
+*/
+function detectOsMismatchHints(lock, platform, arch) {
+	const hostOsLabels = new Set(deriveOsArchLabels(platform, arch).filter((l) => l.startsWith(OS_LABEL_PREFIX)));
+	const hostPrimary = [...hostOsLabels][0] ?? `${OS_LABEL_PREFIX}${platform}`;
+	const hints = [];
+	for (const workflow of lock.workflows ?? []) for (const job of workflow.jobs ?? []) {
+		const requestedOs = (job.runsOn ?? []).filter((m) => m.kind === "exact" && m.value?.startsWith(OS_LABEL_PREFIX)).map((m) => m.value);
+		if (requestedOs.length === 0) continue;
+		if (requestedOs.some((l) => hostOsLabels.has(l))) continue;
+		hints.push(`Job '${job.name ?? "job"}' wants ${requestedOs.join(", ")} but this host is ${platform} — nothing will dispatch locally. Retry with ${hostPrimary} or edit the job's runsOn in .kici/workflows/.`);
+	}
+	return hints;
+}
+//#endregion
+export { detectOsMismatchHints };
+
+//# sourceMappingURL=os-mismatch-hint.js.map

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

@@ -0,0 +1,68 @@
+/** The stamp fields classification needs. Structural, to avoid an import cycle with plane-manager. */
+export interface StampIdentity {
+    orchestratorPid: number;
+    port: number;
+}
+/** The `/health` fields that identify a KiCI orchestrator. */
+export interface KiciHealth {
+    uptime: number;
+    version?: string;
+    buildCommit?: string;
+}
+export type PlaneState = 'stopped' | 'ready' | 'unready' | 'foreign-kici' | 'foreign-unknown';
+export type PlaneClassification = {
+    kind: 'free';
+} | {
+    kind: 'ours-ready';
+    pid: number;
+} | {
+    kind: 'ours-unready';
+    pid: number;
+    checks: Record<string, boolean>;
+} | {
+    kind: 'foreign-kici';
+    pid: number | null;
+    health: KiciHealth;
+} | {
+    kind: 'foreign-unknown';
+    pid: number | null;
+};
+export interface PlaneProbes {
+    isPortFree(port: number): Promise<boolean>;
+    findPortHolderPid(port: number): Promise<number | null>;
+    /** The parsed `/health` body, or null when it did not answer in time. */
+    fetchHealth(port: number): Promise<unknown>;
+    fetchReady(port: number): Promise<{
+        ok: boolean;
+        checks: Record<string, boolean>;
+    }>;
+    isPidAlive(pid: number): boolean;
+}
+export interface ReclaimResult {
+    freed: boolean;
+    killedPid?: number;
+    error?: string;
+}
+/**
+ * Whether a `/health` body came from a KiCI orchestrator. The build-fingerprint
+ * fields are the discriminator: an `ok` status alone is far too common to
+ * justify signalling the process that produced it.
+ */
+export declare function isKiciOrchestratorHealth(body: unknown): body is KiciHealth;
+/** The state label a classification reports to the operator. */
+export declare function planeStateOf(c: PlaneClassification): PlaneState;
+/** The holder pid a classification carries, when it has one. */
+export declare function classificationPid(c: PlaneClassification): number | null;
+/**
+ * Decide what, if anything, is holding the plane port and whether it is ours.
+ *
+ * `stamp` is the on-disk record of the plane this config dir booted; a null
+ * stamp means nothing here booted the holder, so any live holder is foreign.
+ */
+export declare function classifyPlane(port: number, stamp: StampIdentity | null, probes?: Partial<PlaneProbes>): Promise<PlaneClassification>;
+/**
+ * Free the plane port, if it is ours or another KiCI plane orchestrator. A
+ * holder that does not identify as one is reported and left strictly alone.
+ */
+export declare function reclaimPlanePort(port: number, c: PlaneClassification): Promise<ReclaimResult>;
+//# sourceMappingURL=plane-liveness.d.ts.map

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

@@ -0,0 +1,145 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { findPortHolderPid, isPortFree, terminatePid, waitForPortFree } from "./port-holder.js";
+//#region src/local-plane/plane-liveness.ts
+/**
+* One answer to "is a local dev plane running", shared by up, down, and status.
+*
+* Ownership is decided by pid identity — the process actually holding the port
+* versus the pid the stamp names — not by whether a stamp file exists. That is
+* what keeps the three commands consistent: a plane nobody stamped is foreign to
+* all of them, rather than invisible to two and adoptable by the third.
+*
+* Every external effect arrives through `PlaneProbes`, so the policy here is
+* exercised without a subprocess or a socket.
+*/
+/**
+* Cap on each loopback probe. The holder these probes exist to diagnose is
+* frequently wedged, and a socket that accepts a connection but never answers
+* would otherwise hang the CLI for the HTTP client's own multi-minute default —
+* turning `kici local status` into the hang it is meant to explain. A holder
+* that cannot answer loopback within this window is treated as not answering.
+*/
+const PROBE_TIMEOUT_MS = 2e3;
+const defaultProbes = {
+	isPortFree,
+	findPortHolderPid,
+	async fetchHealth(port) {
+		try {
+			const r = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+			if (!r.ok) return null;
+			return await r.json();
+		} catch {
+			return null;
+		}
+	},
+	async fetchReady(port) {
+		try {
+			const r = await fetch(`http://127.0.0.1:${port}/ready`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+			const body = await r.json().catch(() => ({}));
+			return {
+				ok: r.status === 200,
+				checks: body.checks ?? {}
+			};
+		} catch {
+			return {
+				ok: false,
+				checks: {}
+			};
+		}
+	},
+	isPidAlive(pid) {
+		try {
+			process.kill(pid, 0);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+};
+/**
+* Whether a `/health` body came from a KiCI orchestrator. The build-fingerprint
+* fields are the discriminator: an `ok` status alone is far too common to
+* justify signalling the process that produced it.
+*/
+function isKiciOrchestratorHealth(body) {
+	if (typeof body !== "object" || body === null) return false;
+	const b = body;
+	return b.status === "ok" && typeof b.uptime === "number" && "sdkBundleHash" in b && "engineBundleHash" in b;
+}
+/** The state label a classification reports to the operator. */
+function planeStateOf(c) {
+	switch (c.kind) {
+		case "free": return "stopped";
+		case "ours-ready": return "ready";
+		case "ours-unready": return "unready";
+		case "foreign-kici": return "foreign-kici";
+		case "foreign-unknown": return "foreign-unknown";
+	}
+}
+/** The holder pid a classification carries, when it has one. */
+function classificationPid(c) {
+	return "pid" in c ? c.pid : null;
+}
+/**
+* Decide what, if anything, is holding the plane port and whether it is ours.
+*
+* `stamp` is the on-disk record of the plane this config dir booted; a null
+* stamp means nothing here booted the holder, so any live holder is foreign.
+*/
+async function classifyPlane(port, stamp, probes = {}) {
+	const p = {
+		...defaultProbes,
+		...probes
+	};
+	if (await p.isPortFree(port)) return { kind: "free" };
+	const holderPid = await p.findPortHolderPid(port);
+	if ((holderPid !== null ? stamp !== null && holderPid === stamp.orchestratorPid : stamp !== null && p.isPidAlive(stamp.orchestratorPid)) && stamp !== null) {
+		const ready = await p.fetchReady(port);
+		return ready.ok ? {
+			kind: "ours-ready",
+			pid: stamp.orchestratorPid
+		} : {
+			kind: "ours-unready",
+			pid: stamp.orchestratorPid,
+			checks: ready.checks
+		};
+	}
+	const health = await p.fetchHealth(port);
+	return isKiciOrchestratorHealth(health) ? {
+		kind: "foreign-kici",
+		pid: holderPid,
+		health
+	} : {
+		kind: "foreign-unknown",
+		pid: holderPid
+	};
+}
+/**
+* Free the plane port, if it is ours or another KiCI plane orchestrator. A
+* holder that does not identify as one is reported and left strictly alone.
+*/
+async function reclaimPlanePort(port, c) {
+	if (c.kind === "free") return { freed: true };
+	if (c.kind === "foreign-unknown") return {
+		freed: false,
+		error: `port ${port} is held by a process that is not a KiCI plane orchestrator${c.pid === null ? "" : ` (pid ${c.pid})`} — refusing to stop it`
+	};
+	const pid = classificationPid(c);
+	if (pid === null) return {
+		freed: false,
+		error: `port ${port} is held by a KiCI plane orchestrator whose pid could not be determined`
+	};
+	await terminatePid(pid);
+	return await waitForPortFree(port) ? {
+		freed: true,
+		killedPid: pid
+	} : {
+		freed: false,
+		killedPid: pid,
+		error: `port ${port} is still held after stopping pid ${pid}`
+	};
+}
+//#endregion
+export { classificationPid, classifyPlane, isKiciOrchestratorHealth, planeStateOf, reclaimPlanePort };
+
+//# sourceMappingURL=plane-liveness.js.map

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

@@ -1,3 +1,15 @@
+import { type PlaneState } from './plane-liveness.js';
+/**
+ * The current CLI build's identity — semver plus git build commit — read at
+ * call time from the Rolldown-injected build constants (`scripts/build-ts.mjs`).
+ * Read on each call rather than captured in a module const so unit tests can
+ * inject the constants via `globalThis`. Falls back to `0.0.0` / `unknown` when
+ * running from source (unbuilt tree / vitest), where the defines are absent.
+ */
+export declare function currentBuildIdentity(): {
+    version: string;
+    buildCommit: string;
+};
 /** Whether the plane runs offline (independent) or attached to the Platform (hybrid). */
 export type PlaneMode = 'independent' | 'hybrid';
 /**
@@ -21,12 +33,19 @@ export interface PlaneStamp {
     port: number;
     pgKind: 'embedded' | 'podman';
     kiciVersion: string;
+    /** Git build commit of the CLI that booted this plane (see planeBuildIsStale). */
+    buildCommit: string;
     stampVersion: number;
     /** Offline (independent) vs attached (hybrid). Absent (legacy) reads as independent. */
     mode?: PlaneMode;
 }
 export interface PlaneStatus {
+    /** True only when the plane is serving — a live-but-unready plane is false. */
     running: boolean;
+    /** Liveness of the plane port: stopped, serving, live-but-not-serving, or held by someone else. */
+    state: PlaneState;
+    /** Failing `/ready` checks, when the plane is live but not serving. */
+    checks?: Record<string, boolean>;
     pid?: number;
     port?: number;
     pgKind?: 'embedded' | 'podman';
@@ -89,9 +108,29 @@ export declare function devIdentityPublicJwkFile(): string;
  * orchestrator via KICI_DEV_IDENTITY_KEY_FILE.
  */
 export declare function readOrCreateDevIdentity(): string;
+/** Remove the plane's on-disk record (pidfile + stamp). */
+export declare function clearStamp(): void;
+/**
+ * Whether a running plane described by `existing` was booted from a different
+ * CLI build than the current one — a semver bump OR a git-commit change (the
+ * latter covers intermediate staging/E2E commits that share a semver). Returns
+ * false when there is no stamp, or when the current build has no concrete
+ * identity (`buildCommit === 'unknown'`, i.e. running from source / a test),
+ * so a source-context `planeUp` never reboots a healthy plane spuriously. An
+ * old stamp with no `buildCommit` field reads as `undefined` and therefore
+ * triggers a one-time reboot on the first upgrade past this feature.
+ */
+export declare function planeBuildIsStale(existing: PlaneStamp | null): boolean;
 /** Absolute path of the plane orchestrator's log file. */
 export declare function planeLogPath(): string;
-/** Read the plane's current status by probing `/ready` against the stamped port. */
+/**
+ * Read the plane's current status from whatever holds the plane port.
+ *
+ * `running` means "serving": a live orchestrator whose `/ready` fails is
+ * reported as `unready`, with the failing checks, rather than as stopped —
+ * inferring "not running" from an unready probe hides a process that still owns
+ * the port.
+ */
 export declare function planeStatus(): Promise<PlaneStatus>;
 /** Attach parameters for a hybrid plane boot (see attachPlane). */
 export interface PlaneUpAttach {
@@ -106,28 +145,31 @@ export interface PlaneUpOptions {
     attach?: PlaneUpAttach;
 }
 /**
- * Start (or reuse) the local dev plane. Idempotent: a healthy running plane
- * **whose stamped mode matches the requested mode** is returned as-is; a mode
- * change (independent↔hybrid) forces a teardown + reboot. Otherwise Postgres +
- * the orchestrator are booted and a fresh stamp + pidfile are written. When
+ * Start (or reuse) the local dev plane. Idempotent: a healthy running plane this
+ * config dir stamped, **whose stamped mode matches the requested mode**, is
+ * returned as-is. Otherwise the port is reclaimed if it is another KiCI plane,
+ * and Postgres + the orchestrator are booted with a fresh stamp + pidfile. When
  * `attach` is present the orchestrator boots hybrid against the Platform relay;
- * otherwise it boots independent with the dev-signed identity.
+ * otherwise it boots independent with the dev-signed identity. Throws when the
+ * port is held by a process that is not a KiCI plane orchestrator.
  */
 export declare function planeUp(opts?: PlaneUpOptions): Promise<PlaneStatus>;
+/** Outcome of a teardown attempt. `stopped` is true only when the port is verified free. */
+export interface PlaneDownResult {
+    stopped: boolean;
+    port: number;
+    holderPid?: number;
+    reason?: string;
+}
 /**
- * Stop the local dev plane. Teardown is reconstructed from the stamp (the
- * start-time Postgres handle does not survive a separate CLI invocation):
- * SIGTERM the orchestrator, stop Postgres by backend kind, then clear the
- * pidfile + stamp.
- */
-export declare function planeDown(): Promise<void>;
-/**
- * Poll until process `pid` has exited (SIGTERM already sent), escalating to
- * SIGKILL if it outlives the grace period, so the caller can rely on the
- * listening socket being released once this resolves. `process.kill(pid, 0)`
- * throws `ESRCH` once the process is gone.
+ * Stop the local dev plane and confirm the port was released.
+ *
+ * Teardown is reconstructed from whatever holds the port, not only from the
+ * stamp: a plane this config dir never stamped still occupies the port and is
+ * still ours to stop. The pidfile and stamp are cleared only once the port is
+ * verified free, so a survivor never loses the pid that identifies it.
  */
-export declare function waitForProcessExit(pid: number, graceMs?: number): Promise<void>;
+export declare function planeDown(): Promise<PlaneDownResult>;
 /**
  * Attach the local dev plane to the hosted Platform: mint an org-scoped
  * orchestrator key with the logged-in PAT, then (re)boot the plane hybrid