@kici-dev/compiler 0.1.26 → 0.2.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
+- [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) (190 KB) — Authoring API: workflow/job/step factories, triggers, rules, matrix, runtime, caching
-- [cli](https://docs.kici.dev/llms-cli.txt) (136 KB) — Running the CLI: compile, test, run local/remote, auth, hooks, lock-file drift
-- [features](https://docs.kici.dev/llms-features.txt) (126 KB) — Workflow features: concurrency, environments, secrets, approvals, provenance, events
-- [providers](https://docs.kici.dev/llms-providers.txt) (36 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
+- [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) (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,40 +35,50 @@ 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
 
 - [Account and sign-in](https://docs.kici.dev/user/account-and-login/): How your KiCI account relates to sign-in methods, and how to change the way you sign in.
 - [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with approval
 - [Concurrency groups](https://docs.kici.dev/user/concurrency/): Control parallel execution with auto-cancel and queue modes
+- [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
-- [Environments](https://docs.kici.dev/user/environments/): Configure deployment environments with variables, secrets, and protection rules
+- [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

@@ -0,0 +1,70 @@
+/**
+ * Resolve a host address the plane's co-located bare-metal agent can reach for
+ * cache-blob fetches. The orchestrator refuses to hand a scaler a loopback
+ * storage URL (it assumes remote agents), so the plane advertises its first
+ * non-internal IPv4 (still this machine — the agent is co-located). Falls back
+ * to the hostname when no external interface is present.
+ */
+export declare function resolveAgentReachableHost(): string;
+/**
+ * Resolve the built `@kici-dev/orchestrator/standalone` entry the local plane
+ * launches in independent (offline) mode.
+ */
+export declare function resolveStandaloneEntry(): string;
+/**
+ * Resolve the built `@kici-dev/orchestrator/server` entry the local plane
+ * launches in hybrid (Platform-attached) mode.
+ */
+export declare function resolveServerEntry(): string;
+/** Single `/ready` probe against the local orchestrator. */
+export declare function orchestratorReady(port: number): Promise<boolean>;
+/** Options threading the plane's admin token + bare-metal scaler into the boot. */
+export interface SpawnOrchestratorOptions {
+    /** Bootstrap admin token the CLI presents to the plane's admin API. */
+    adminToken: string;
+    /**
+     * Local master secret key (64 hex chars). Enables the orchestrator's secrets
+     * subsystem, which is what gates the admin API routes the CLI drives.
+     */
+    secretKey: string;
+    /** Path to the bare-metal scaler YAML (KICI_SCALER_CONFIG_PATH). */
+    scalerConfigFile: string;
+    /**
+     * Path to the dev-signed identity's EC P-256 private JWK (mode 0600), freshly
+     * generated by the plane. Enables the orchestrator's local OIDC mint +
+     * dev-signed provenance (issuer `kici-local`) in independent mode. Present in
+     * the independent boot; omitted (with `attach`) in the hybrid boot, which
+     * mints via the Platform relay instead.
+     */
+    devIdentityKeyFile?: string;
+    /**
+     * When present, boot the orchestrator in HYBRID mode attached to the Platform
+     * relay instead of independent mode. OIDC + attestation then mint via the
+     * Platform (the local dev signer is never consulted — the orchestrator's
+     * `selectOidcMintRegistration` prefers the relay whenever a Platform
+     * connection exists).
+     */
+    attach?: {
+        /** Orchestrator KICI_PLATFORM_URL — a ws(s)://…/ws relay URL. */
+        platformWsUrl: string;
+        /** Org-scoped orchestrator key (kici_ok_…) presented on WS auth. */
+        platformToken: string;
+    };
+}
+/**
+ * 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 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

@@ -0,0 +1,129 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { planePaths, planePorts } from "./paths.js";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+import os from "node:os";
+//#region src/local-plane/orchestrator-process.ts
+/**
+* Resolve a host address the plane's co-located bare-metal agent can reach for
+* cache-blob fetches. The orchestrator refuses to hand a scaler a loopback
+* storage URL (it assumes remote agents), so the plane advertises its first
+* non-internal IPv4 (still this machine — the agent is co-located). Falls back
+* to the hostname when no external interface is present.
+*/
+function resolveAgentReachableHost() {
+	for (const addrs of Object.values(os.networkInterfaces())) for (const a of addrs ?? []) if (a.family === "IPv4" && !a.internal) return a.address;
+	return os.hostname();
+}
+/**
+* Resolve the built `@kici-dev/orchestrator/standalone` entry the local plane
+* launches in independent (offline) mode.
+*/
+function resolveStandaloneEntry() {
+	return createRequire(import.meta.url).resolve("@kici-dev/orchestrator/standalone");
+}
+/**
+* Resolve the built `@kici-dev/orchestrator/server` entry the local plane
+* launches in hybrid (Platform-attached) mode.
+*/
+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`, { signal: AbortSignal.timeout(READY_PROBE_TIMEOUT_MS) })).status === 200;
+	} catch {
+		return false;
+	}
+}
+/**
+* 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.
+*/
+function spawnOrchestratorProcess(databaseUrl, opts) {
+	const { orchestrator: port } = planePorts();
+	const { logFile, root, cacheDir } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	fs.mkdirSync(cacheDir, { recursive: true });
+	const out = fs.openSync(logFile, "a");
+	const baseEnv = {};
+	for (const [key, value] of Object.entries(process.env)) if (!key.startsWith("KICI_")) baseEnv[key] = value;
+	const commonEnv = {
+		...baseEnv,
+		KICI_PORT: String(port),
+		KICI_DATABASE_URL: databaseUrl,
+		KICI_AGENT_AUTH: "none",
+		KICI_AUTO_MIGRATE: "true",
+		KICI_DATA_DIR: root,
+		KICI_BOOTSTRAP_ADMIN_TOKEN: opts.adminToken,
+		KICI_SECRET_KEY: opts.secretKey,
+		KICI_SCALER_CONFIG_PATH: opts.scalerConfigFile,
+		KICI_WEBHOOK_PUBLIC_URL: `http://127.0.0.1:${port}`,
+		KICI_STORAGE_TYPE: "filesystem",
+		KICI_STORAGE_FS_PATH: cacheDir,
+		KICI_STORAGE_FS_BASE_URL: `http://${resolveAgentReachableHost()}:${port}`
+	};
+	let entry;
+	let modeEnv;
+	if (opts.attach) {
+		entry = resolveServerEntry();
+		modeEnv = {
+			KICI_MODE: "hybrid",
+			KICI_PLATFORM_URL: opts.attach.platformWsUrl,
+			KICI_PLATFORM_TOKEN: opts.attach.platformToken
+		};
+	} else {
+		entry = resolveStandaloneEntry();
+		modeEnv = {
+			KICI_MODE: "independent",
+			KICI_INDEPENDENT_SECRETS: "true",
+			KICI_INDEPENDENT_IDENTITY: "true",
+			KICI_DEV_IDENTITY_KEY_FILE: opts.devIdentityKeyFile,
+			KICI_PROVENANCE_ISSUER: "kici-local"
+		};
+	}
+	const child = spawn(process.execPath, [entry], {
+		detached: true,
+		stdio: [
+			"ignore",
+			out,
+			out
+		],
+		env: {
+			...commonEnv,
+			...modeEnv
+		}
+	});
+	child.unref();
+	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 { 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/paths.d.ts

@@ -0,0 +1,39 @@
+/**
+ * On-disk layout version of the local dev plane. Bumped when the state-dir
+ * structure changes incompatibly, so a stamped plane from an older layout is
+ * recreated rather than reused.
+ */
+export declare const PLANE_STAMP_VERSION = 3;
+/**
+ * Root directory of the local dev plane's state, following the same
+ * `KICI_CONFIG_DIR` → `~/.kici` convention the rest of the CLI uses.
+ */
+export declare function planeRoot(): string;
+/**
+ * Absolute paths for every artefact the plane persists under its state root.
+ */
+export declare function planePaths(): {
+    root: string;
+    pgData: string;
+    pidfile: string;
+    stampFile: string;
+    logFile: string;
+    socketDir: string;
+    adminTokenFile: string;
+    platformTokenFile: string;
+    attachmentFile: string;
+    secretKeyFile: string;
+    scalerConfigFile: string;
+    agentWrapperFile: string;
+    devIdentityDir: string;
+    cacheDir: string;
+};
+/**
+ * Fixed localhost ports for the plane's orchestrator (HTTP+WS) and Postgres.
+ * Overridable via `KICI_LOCAL_ORCH_PORT` / `KICI_LOCAL_PG_PORT`.
+ */
+export declare function planePorts(): {
+    orchestrator: number;
+    postgres: number;
+};
+//# sourceMappingURL=paths.d.ts.map

package/dist/local-plane/paths.js

@@ -0,0 +1,54 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import path from "node:path";
+import os from "node:os";
+//#region src/local-plane/paths.ts
+/**
+* On-disk layout version of the local dev plane. Bumped when the state-dir
+* structure changes incompatibly, so a stamped plane from an older layout is
+* recreated rather than reused.
+*/
+const PLANE_STAMP_VERSION = 3;
+/**
+* Root directory of the local dev plane's state, following the same
+* `KICI_CONFIG_DIR` → `~/.kici` convention the rest of the CLI uses.
+*/
+function planeRoot() {
+	const base = process.env.KICI_CONFIG_DIR ?? path.join(os.homedir(), ".kici");
+	return path.join(base, "local");
+}
+/**
+* Absolute paths for every artefact the plane persists under its state root.
+*/
+function planePaths() {
+	const root = planeRoot();
+	return {
+		root,
+		pgData: path.join(root, "pgdata"),
+		pidfile: path.join(root, "plane.pid"),
+		stampFile: path.join(root, "stamp.json"),
+		logFile: path.join(root, "orchestrator.log"),
+		socketDir: path.join(root, "sock"),
+		adminTokenFile: path.join(root, "admin-token"),
+		platformTokenFile: path.join(root, "platform-token"),
+		attachmentFile: path.join(root, "attachment.json"),
+		secretKeyFile: path.join(root, "secret-key"),
+		scalerConfigFile: path.join(root, "scaler.yaml"),
+		agentWrapperFile: path.join(root, "agent-wrapper.sh"),
+		devIdentityDir: path.join(root, "dev-identity"),
+		cacheDir: path.join(root, "cache")
+	};
+}
+/**
+* Fixed localhost ports for the plane's orchestrator (HTTP+WS) and Postgres.
+* Overridable via `KICI_LOCAL_ORCH_PORT` / `KICI_LOCAL_PG_PORT`.
+*/
+function planePorts() {
+	return {
+		orchestrator: Number(process.env.KICI_LOCAL_ORCH_PORT ?? 4319),
+		postgres: Number(process.env.KICI_LOCAL_PG_PORT ?? 45432)
+	};
+}
+//#endregion
+export { PLANE_STAMP_VERSION, planePaths, planePorts, planeRoot };
+
+//# sourceMappingURL=paths.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