@kici-dev/compiler 0.1.26 → 0.2.0

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

@@ -0,0 +1,193 @@
+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';
+/**
+ * Attachment record for a hybrid plane: the Platform relay it dials, the org it
+ * is scoped to, and the Platform api_keys id of its minted orchestrator key (for
+ * later revoke). The orchestrator token itself is NEVER stored here — it lives
+ * in a sibling 0600 file so it can't land in a world-readable stamp.
+ */
+export interface PlaneAttachment {
+    /** Orchestrator KICI_PLATFORM_URL — a ws(s)://…/ws relay URL. */
+    platformWsUrl: string;
+    /** HTTPS Platform API base (provenance/verify context, key revoke). */
+    platformApiBase: string;
+    orgId: string;
+    /** Platform api_keys id of the minted orchestrator key. */
+    keyId: string;
+}
+/** On-disk record of the running plane, written on boot, read on status/down. */
+export interface PlaneStamp {
+    orchestratorPid: number;
+    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';
+    stampVersion?: number;
+    url?: string;
+    /** Bootstrap admin token the CLI presents to the plane's admin API. */
+    adminToken?: string;
+    /** Offline (independent) vs attached (hybrid). */
+    mode: PlaneMode;
+    /** Present iff mode === 'hybrid'. */
+    attachment?: PlaneAttachment;
+}
+/**
+ * Read the plane's persisted Platform orchestrator token (mode 0600), or null
+ * when the plane is independent/offline. Kept out of the stamp so the token
+ * never lands in a world-readable file.
+ */
+export declare function readPlatformToken(): string | null;
+/** Persist the Platform orchestrator token (mode 0600). */
+export declare function writePlatformToken(token: string): void;
+/** Remove the persisted Platform orchestrator token (on detach). */
+export declare function clearPlatformToken(): void;
+/**
+ * Read the durable attachment record (survives `kici local down`), or null when
+ * the plane is not attached. This — not the running stamp — is the source of
+ * truth for "is this plane attached to the Platform".
+ */
+export declare function readAttachment(): PlaneAttachment | null;
+/** Persist the durable attachment record (never the token). */
+export declare function writeAttachment(attachment: PlaneAttachment): void;
+/** Remove the durable attachment record (on detach). */
+export declare function clearAttachment(): void;
+/**
+ * Read the plane's persisted bootstrap admin token, generating + persisting one
+ * (mode 0600) on first boot. A warm plane reuses the same token across CLI
+ * invocations so a running orchestrator keeps accepting the CLI's admin calls.
+ */
+export declare function readOrCreateAdminToken(): string;
+/** Read the plane's admin token without generating one (null when absent). */
+export declare function planeAdminToken(): string | null;
+/**
+ * Read the plane's local master secret key, generating + persisting a fresh 64
+ * hex-char key (mode 0600) on first boot. Stable across boots so DB-encrypted
+ * material stays decryptable. Freshly generated — never derived from any sops
+ * secret. Enables the orchestrator's secrets subsystem, which gates its admin
+ * API surface.
+ */
+export declare function readOrCreateSecretKey(): string;
+/** Absolute path of the dev-signed identity's private JWK key file. */
+export declare function devIdentityKeyFile(): string;
+/** Absolute path of the dev-signed identity's public JWK (written by the plane orchestrator). */
+export declare function devIdentityPublicJwkFile(): string;
+/**
+ * Read the plane's dev-signed identity keypair, generating + persisting a fresh
+ * EC P-256 private JWK (mode 0600) on first boot. Stable across boots so a
+ * `kici local trust-root` export stays valid for previously-minted tokens.
+ * Freshly generated — NEVER derived from any sops secret or real key. Only the
+ * private key is written here; the plane orchestrator derives + writes the
+ * public JWK next to it. Returns the private-key file path passed to the
+ * 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 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 {
+    platformWsUrl: string;
+    platformToken: string;
+    platformApiBase: string;
+    orgId: string;
+    keyId: string;
+}
+export interface PlaneUpOptions {
+    /** Boot the plane hybrid (attached to the Platform) instead of independent. */
+    attach?: PlaneUpAttach;
+}
+/**
+ * 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. 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 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 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
+ * against the Platform relay. Registration with the Platform is implicit — the
+ * hybrid orchestrator's PlatformClient sends `source.register` on WS auth.
+ */
+export declare function attachPlane(args: {
+    apiBase: string;
+    pat: string;
+    orgId: string;
+}): Promise<PlaneStatus>;
+/**
+ * Detach the local dev plane: best-effort revoke the minted orchestrator key on
+ * the Platform, clear the durable attachment + token, then reboot the plane
+ * independent (offline). The revoke is non-fatal — a detach must succeed even
+ * offline or with an expired PAT.
+ */
+export declare function detachPlane(opts?: {
+    pat?: string;
+}): Promise<PlaneStatus>;
+//# sourceMappingURL=plane-manager.d.ts.map

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

@@ -0,0 +1,480 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { planePaths, planePorts } from "./paths.js";
+import { awaitOrchestratorReady, resolveServerEntry, resolveStandaloneEntry, spawnOrchestratorProcess } from "./orchestrator-process.js";
+import { isPortFree, processCommandLine, terminatePid } from "./port-holder.js";
+import { classificationPid, classifyPlane, planeStateOf, reclaimPlanePort } from "./plane-liveness.js";
+import { startPlanePostgres, stopPlanePostgres } from "./postgres.js";
+import { writeScalerConfig } from "./scaler-config.js";
+import { derivePlatformWsUrl, mintOrchestratorKey, revokeOrchestratorKey } from "./platform-attach.js";
+import path from "node:path";
+import fs from "node:fs";
+import { generateKeyPairSync, randomBytes } from "node:crypto";
+//#region src/local-plane/plane-manager.ts
+/**
+* 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.
+*/
+function currentBuildIdentity() {
+	return {
+		version: "0.2.0",
+		buildCommit: "15d5e4447"
+	};
+}
+/**
+* Read the plane's persisted Platform orchestrator token (mode 0600), or null
+* when the plane is independent/offline. Kept out of the stamp so the token
+* never lands in a world-readable file.
+*/
+function readPlatformToken() {
+	try {
+		return fs.readFileSync(planePaths().platformTokenFile, "utf-8").trim() || null;
+	} catch {
+		return null;
+	}
+}
+/** Persist the Platform orchestrator token (mode 0600). */
+function writePlatformToken(token) {
+	const { platformTokenFile, root } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	fs.writeFileSync(platformTokenFile, token, { mode: 384 });
+}
+/** Remove the persisted Platform orchestrator token (on detach). */
+function clearPlatformToken() {
+	fs.rmSync(planePaths().platformTokenFile, { force: true });
+}
+/**
+* Read the durable attachment record (survives `kici local down`), or null when
+* the plane is not attached. This — not the running stamp — is the source of
+* truth for "is this plane attached to the Platform".
+*/
+function readAttachment() {
+	try {
+		return JSON.parse(fs.readFileSync(planePaths().attachmentFile, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+/** Persist the durable attachment record (never the token). */
+function writeAttachment(attachment) {
+	const { attachmentFile, root } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	fs.writeFileSync(attachmentFile, JSON.stringify(attachment, null, 2));
+}
+/** Remove the durable attachment record (on detach). */
+function clearAttachment() {
+	fs.rmSync(planePaths().attachmentFile, { force: true });
+}
+/**
+* Read the plane's persisted bootstrap admin token, generating + persisting one
+* (mode 0600) on first boot. A warm plane reuses the same token across CLI
+* invocations so a running orchestrator keeps accepting the CLI's admin calls.
+*/
+function readOrCreateAdminToken() {
+	const { adminTokenFile, root } = planePaths();
+	try {
+		const existing = fs.readFileSync(adminTokenFile, "utf-8").trim();
+		if (existing) return existing;
+	} catch {}
+	fs.mkdirSync(root, { recursive: true });
+	const token = `kici-local-${randomBytes(24).toString("hex")}`;
+	fs.writeFileSync(adminTokenFile, token, { mode: 384 });
+	return token;
+}
+/** Read the plane's admin token without generating one (null when absent). */
+function planeAdminToken() {
+	try {
+		return fs.readFileSync(planePaths().adminTokenFile, "utf-8").trim() || null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Read the plane's local master secret key, generating + persisting a fresh 64
+* hex-char key (mode 0600) on first boot. Stable across boots so DB-encrypted
+* material stays decryptable. Freshly generated — never derived from any sops
+* secret. Enables the orchestrator's secrets subsystem, which gates its admin
+* API surface.
+*/
+function readOrCreateSecretKey() {
+	const { secretKeyFile, root } = planePaths();
+	try {
+		const existing = fs.readFileSync(secretKeyFile, "utf-8").trim();
+		if (existing) return existing;
+	} catch {}
+	fs.mkdirSync(root, { recursive: true });
+	const key = randomBytes(32).toString("hex");
+	fs.writeFileSync(secretKeyFile, key, { mode: 384 });
+	return key;
+}
+/** Absolute path of the dev-signed identity's private JWK key file. */
+function devIdentityKeyFile() {
+	return path.join(planePaths().devIdentityDir, "identity.jwk");
+}
+/** Absolute path of the dev-signed identity's public JWK (written by the plane orchestrator). */
+function devIdentityPublicJwkFile() {
+	return path.join(planePaths().devIdentityDir, "identity.pub.jwk");
+}
+/**
+* Read the plane's dev-signed identity keypair, generating + persisting a fresh
+* EC P-256 private JWK (mode 0600) on first boot. Stable across boots so a
+* `kici local trust-root` export stays valid for previously-minted tokens.
+* Freshly generated — NEVER derived from any sops secret or real key. Only the
+* private key is written here; the plane orchestrator derives + writes the
+* public JWK next to it. Returns the private-key file path passed to the
+* orchestrator via KICI_DEV_IDENTITY_KEY_FILE.
+*/
+function readOrCreateDevIdentity() {
+	const keyFile = devIdentityKeyFile();
+	try {
+		if (fs.readFileSync(keyFile, "utf-8").trim()) return keyFile;
+	} catch {}
+	fs.mkdirSync(planePaths().devIdentityDir, {
+		recursive: true,
+		mode: 448
+	});
+	const { privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+	const jwk = privateKey.export({ format: "jwk" });
+	fs.writeFileSync(keyFile, JSON.stringify(jwk, null, 2), { mode: 384 });
+	return keyFile;
+}
+function readStamp() {
+	try {
+		return JSON.parse(fs.readFileSync(planePaths().stampFile, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+function writeStamp(stamp) {
+	const { root, stampFile, pidfile } = planePaths();
+	fs.mkdirSync(root, { recursive: true });
+	fs.writeFileSync(stampFile, JSON.stringify(stamp, null, 2));
+	fs.writeFileSync(pidfile, String(stamp.orchestratorPid));
+}
+/** Remove the plane's on-disk record (pidfile + stamp). */
+function clearStamp() {
+	const { pidfile, stampFile } = planePaths();
+	fs.rmSync(pidfile, { force: true });
+	fs.rmSync(stampFile, { force: true });
+}
+/**
+* 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.
+*/
+function planeBuildIsStale(existing) {
+	if (!existing) return false;
+	const { version, buildCommit } = currentBuildIdentity();
+	if (buildCommit === "unknown") return false;
+	return existing.kiciVersion !== version || existing.buildCommit !== buildCommit;
+}
+function orchestratorUrl(port) {
+	return `http://127.0.0.1:${port}`;
+}
+/** Absolute path of the plane orchestrator's log file. */
+function planeLogPath() {
+	return planePaths().logFile;
+}
+/**
+* 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.
+*/
+async function planeStatus() {
+	const stamp = readStamp();
+	const port = stamp?.port ?? planePorts().orchestrator;
+	const classification = await classifyPlane(port, stamp);
+	const mode = stamp?.mode ?? "independent";
+	const attachment = readAttachment() ?? void 0;
+	if (classification.kind === "free") return {
+		running: false,
+		state: "stopped",
+		mode,
+		attachment
+	};
+	if (classification.kind === "ours-ready") return {
+		running: true,
+		state: "ready",
+		pid: classification.pid,
+		port,
+		pgKind: stamp?.pgKind,
+		stampVersion: stamp?.stampVersion,
+		url: orchestratorUrl(port),
+		adminToken: planeAdminToken() ?? void 0,
+		mode,
+		attachment
+	};
+	return {
+		running: false,
+		state: planeStateOf(classification),
+		pid: classificationPid(classification) ?? void 0,
+		port,
+		pgKind: stamp?.pgKind,
+		url: orchestratorUrl(port),
+		checks: classification.kind === "ours-unready" ? classification.checks : void 0,
+		mode,
+		attachment
+	};
+}
+/**
+* Tear the plane down ahead of a fresh boot, refusing to continue when the port
+* was not released.
+*
+* Booting over a still-held port only re-fails later, as a readiness timeout
+* that names the log instead of the survivor — so the teardown's own reason (the
+* pid still holding the port) is raised here, while it is still the accurate
+* one.
+*/
+async function tearDownForBoot() {
+	const result = await planeDown();
+	if (result.stopped) return;
+	const holder = result.holderPid === void 0 ? "" : ` (pid ${result.holderPid})`;
+	throw new Error(result.reason ?? `port ${result.port} is still held after stopping the local dev plane${holder}`);
+}
+/**
+* Ensure the plane port is either reusable or vacant before a boot.
+*
+* Returns the running plane when it may be reused as-is, or null when the caller
+* must boot fresh. A plane no stamp accounts for is reclaimed rather than
+* adopted: reuse would serve `kici run --local` from an orchestrator of unknown
+* build, with an unknown scaler configuration, which is exactly the state a
+* stamped plane's staleness check exists to prevent.
+*/
+async function prepareForBoot(port, existing, requestedMode) {
+	const classification = await classifyPlane(port, existing);
+	switch (classification.kind) {
+		case "free": return null;
+		case "foreign-unknown": {
+			const reclaim = await reclaimPlanePort(port, classification);
+			throw new Error(reclaim.error ?? `port ${port} is held by an unrecognised process`);
+		}
+		case "foreign-kici": {
+			const reclaim = await reclaimPlanePort(port, classification);
+			if (!reclaim.freed) throw new Error(reclaim.error ?? `could not reclaim port ${port}`);
+			clearStamp();
+			return null;
+		}
+		case "ours-unready":
+			await tearDownForBoot();
+			return null;
+		case "ours-ready": {
+			const modeChanged = (existing?.mode ?? "independent") !== requestedMode;
+			if (planeBuildIsStale(existing) || modeChanged) {
+				await tearDownForBoot();
+				return null;
+			}
+			return {
+				running: true,
+				state: "ready",
+				pid: classification.pid,
+				port,
+				pgKind: existing?.pgKind,
+				stampVersion: existing?.stampVersion,
+				url: orchestratorUrl(port),
+				adminToken: planeAdminToken() ?? void 0,
+				mode: existing?.mode ?? "independent",
+				attachment: readAttachment() ?? void 0
+			};
+		}
+	}
+}
+/**
+* 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. Throws when the
+* port is held by a process that is not a KiCI plane orchestrator.
+*/
+async function planeUp(opts = {}) {
+	const { orchestrator: port } = planePorts();
+	const existing = readStamp();
+	const requestedMode = opts.attach ? "hybrid" : "independent";
+	if (existing && existing.stampVersion !== 3) {
+		await tearDownForBoot();
+		fs.rmSync(planePaths().pgData, {
+			recursive: true,
+			force: true
+		});
+	} else {
+		const reusable = await prepareForBoot(port, existing, requestedMode);
+		if (reusable) return reusable;
+	}
+	const adminToken = readOrCreateAdminToken();
+	const secretKey = readOrCreateSecretKey();
+	const scalerConfigFile = writeScalerConfig(port);
+	const pg = await startPlanePostgres();
+	let orch;
+	if (opts.attach) {
+		writePlatformToken(opts.attach.platformToken);
+		writeAttachment({
+			platformWsUrl: opts.attach.platformWsUrl,
+			platformApiBase: opts.attach.platformApiBase,
+			orgId: opts.attach.orgId,
+			keyId: opts.attach.keyId
+		});
+		orch = spawnOrchestratorProcess(pg.url, {
+			adminToken,
+			secretKey,
+			scalerConfigFile,
+			attach: {
+				platformWsUrl: opts.attach.platformWsUrl,
+				platformToken: opts.attach.platformToken
+			}
+		});
+	} else {
+		const devIdentityKey = readOrCreateDevIdentity();
+		orch = spawnOrchestratorProcess(pg.url, {
+			adminToken,
+			secretKey,
+			scalerConfigFile,
+			devIdentityKeyFile: devIdentityKey
+		});
+	}
+	const { version: stampVersionSemver, buildCommit: stampBuildCommit } = currentBuildIdentity();
+	writeStamp({
+		orchestratorPid: orch.pid,
+		port: orch.port,
+		pgKind: pg.kind,
+		kiciVersion: stampVersionSemver,
+		buildCommit: stampBuildCommit,
+		stampVersion: 3,
+		mode: requestedMode
+	});
+	try {
+		await awaitOrchestratorReady(orch.port);
+	} catch {
+		await terminatePid(orch.pid);
+		if (await isPortFree(orch.port)) clearStamp();
+		throw new Error(`local orchestrator did not become ready — see ${planeLogPath()}`);
+	}
+	return {
+		running: true,
+		state: "ready",
+		pid: orch.pid,
+		port: orch.port,
+		pgKind: pg.kind,
+		stampVersion: 3,
+		url: orchestratorUrl(orch.port),
+		adminToken,
+		mode: requestedMode,
+		attachment: readAttachment() ?? void 0
+	};
+}
+/**
+* Whether the stamped pid is still one of this build's plane orchestrators.
+*
+* The stamp outlives the process it names — a crash, a `kill -9`, or a reboot
+* all leave it behind — so once the operating system recycles that pid onto an
+* unrelated process, signalling it blind would stop a stranger's program. Every
+* other signal path in the plane is identity-verified (`reclaimPlanePort` only
+* ever signals a pid confirmed to hold the port or to answer `/health` as a KiCI
+* orchestrator); this keeps the stamp-driven path to the same standard by
+* matching the live command line against the entry this build would launch.
+*
+* Returns false whenever identity cannot be established — an unreadable command
+* line, an unresolvable entry, or a plane launched from a different install.
+* That is deliberate: not signalling leaves a process running, while signalling
+* the wrong pid kills one.
+*/
+async function stampedPidIsOurOrchestrator(pid) {
+	const cmdline = await processCommandLine(pid);
+	if (!cmdline) return false;
+	for (const resolveEntry of [resolveStandaloneEntry, resolveServerEntry]) try {
+		if (cmdline.includes(resolveEntry())) return true;
+	} catch {}
+	return false;
+}
+/**
+* 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.
+*/
+async function planeDown() {
+	const stamp = readStamp();
+	const port = stamp?.port ?? planePorts().orchestrator;
+	const classification = await classifyPlane(port, stamp);
+	const reclaim = await reclaimPlanePort(port, classification);
+	if (!reclaim.freed) return {
+		stopped: false,
+		port,
+		holderPid: reclaim.killedPid ?? classificationPid(classification) ?? void 0,
+		reason: reclaim.error
+	};
+	if (stamp && stamp.orchestratorPid !== reclaim.killedPid && await stampedPidIsOurOrchestrator(stamp.orchestratorPid)) {
+		await terminatePid(stamp.orchestratorPid);
+		if (!await isPortFree(port)) return {
+			stopped: false,
+			port,
+			holderPid: stamp.orchestratorPid,
+			reason: `port ${port} is still held after stopping pid ${stamp.orchestratorPid}`
+		};
+	}
+	if (stamp) await stopPlanePostgres(stamp.pgKind);
+	else if (classification.kind !== "free") await stopPlanePostgres("embedded");
+	clearStamp();
+	return {
+		stopped: true,
+		port,
+		holderPid: reclaim.killedPid
+	};
+}
+/**
+* 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
+* against the Platform relay. Registration with the Platform is implicit — the
+* hybrid orchestrator's PlatformClient sends `source.register` on WS auth.
+*/
+async function attachPlane(args) {
+	const platformWsUrl = derivePlatformWsUrl(args.apiBase);
+	const minted = await mintOrchestratorKey({
+		apiBase: args.apiBase,
+		pat: args.pat,
+		orgId: args.orgId,
+		name: "local dev plane"
+	});
+	return planeUp({ attach: {
+		platformWsUrl,
+		platformToken: minted.key,
+		platformApiBase: args.apiBase,
+		orgId: args.orgId,
+		keyId: minted.keyId
+	} });
+}
+/**
+* Detach the local dev plane: best-effort revoke the minted orchestrator key on
+* the Platform, clear the durable attachment + token, then reboot the plane
+* independent (offline). The revoke is non-fatal — a detach must succeed even
+* offline or with an expired PAT.
+*/
+async function detachPlane(opts = {}) {
+	const attachment = readAttachment();
+	if (attachment && opts.pat) await revokeOrchestratorKey({
+		apiBase: attachment.platformApiBase,
+		pat: opts.pat,
+		orgId: attachment.orgId,
+		keyId: attachment.keyId
+	}).catch(() => false);
+	clearAttachment();
+	clearPlatformToken();
+	await planeDown();
+	return planeUp();
+}
+//#endregion
+export { attachPlane, clearAttachment, clearPlatformToken, clearStamp, currentBuildIdentity, detachPlane, devIdentityKeyFile, devIdentityPublicJwkFile, planeAdminToken, planeBuildIsStale, planeDown, planeLogPath, planeStatus, planeUp, readAttachment, readOrCreateAdminToken, readOrCreateDevIdentity, readOrCreateSecretKey, readPlatformToken, writeAttachment, writePlatformToken };
+
+//# sourceMappingURL=plane-manager.js.map