@kici-dev/compiler 0.1.27 → 0.2.0

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

@@ -1,6 +1,8 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { planePaths, planePorts } from "./paths.js";
-import { orchestratorReady, spawnOrchestrator } from "./orchestrator-process.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";
@@ -8,7 +10,19 @@ import path from "node:path";
 import fs from "node:fs";
 import { generateKeyPairSync, randomBytes } from "node:crypto";
 //#region src/local-plane/plane-manager.ts
-const kiciVersion = "0.1.27";
+/**
+* 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
@@ -139,6 +153,28 @@ function writeStamp(stamp) {
 	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}`;
 }
@@ -146,57 +182,135 @@ function orchestratorUrl(port) {
 function planeLogPath() {
 	return planePaths().logFile;
 }
-/** 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.
+*/
 async function planeStatus() {
 	const stamp = readStamp();
 	const port = stamp?.port ?? planePorts().orchestrator;
-	if (!await orchestratorReady(port)) return {
+	const classification = await classifyPlane(port, stamp);
+	const mode = stamp?.mode ?? "independent";
+	const attachment = readAttachment() ?? void 0;
+	if (classification.kind === "free") return {
 		running: false,
-		mode: stamp?.mode ?? "independent",
-		attachment: readAttachment() ?? void 0
+		state: "stopped",
+		mode,
+		attachment
 	};
-	return {
+	if (classification.kind === "ours-ready") return {
 		running: true,
-		pid: stamp?.orchestratorPid,
+		state: "ready",
+		pid: classification.pid,
 		port,
 		pgKind: stamp?.pgKind,
 		stampVersion: stamp?.stampVersion,
 		url: orchestratorUrl(port),
 		adminToken: planeAdminToken() ?? void 0,
-		mode: stamp?.mode ?? "independent",
-		attachment: readAttachment() ?? 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
 	};
 }
 /**
-* 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
+* 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.
+* 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 planeDown();
+		await tearDownForBoot();
 		fs.rmSync(planePaths().pgData, {
 			recursive: true,
 			force: true
 		});
-	} else if ((existing?.mode ?? "independent") !== requestedMode && await orchestratorReady(port)) await planeDown();
-	else if (await orchestratorReady(port)) return {
-		running: true,
-		pid: existing?.orchestratorPid,
-		port,
-		pgKind: existing?.pgKind,
-		stampVersion: existing?.stampVersion,
-		url: orchestratorUrl(port),
-		adminToken: planeAdminToken() ?? void 0,
-		mode: existing?.mode ?? "independent",
-		attachment: readAttachment() ?? void 0
-	};
+	} else {
+		const reusable = await prepareForBoot(port, existing, requestedMode);
+		if (reusable) return reusable;
+	}
 	const adminToken = readOrCreateAdminToken();
 	const secretKey = readOrCreateSecretKey();
 	const scalerConfigFile = writeScalerConfig(port);
@@ -210,7 +324,7 @@ async function planeUp(opts = {}) {
 			orgId: opts.attach.orgId,
 			keyId: opts.attach.keyId
 		});
-		orch = await spawnOrchestrator(pg.url, {
+		orch = spawnOrchestratorProcess(pg.url, {
 			adminToken,
 			secretKey,
 			scalerConfigFile,
@@ -221,23 +335,33 @@ async function planeUp(opts = {}) {
 		});
 	} else {
 		const devIdentityKey = readOrCreateDevIdentity();
-		orch = await spawnOrchestrator(pg.url, {
+		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,
+		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,
@@ -249,49 +373,65 @@ async function planeUp(opts = {}) {
 	};
 }
 /**
-* 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.
+* 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 planeDown() {
-	const stamp = readStamp();
-	const { pidfile, stampFile } = planePaths();
-	if (stamp) {
-		try {
-			process.kill(stamp.orchestratorPid, "SIGTERM");
-		} catch {}
-		await waitForProcessExit(stamp.orchestratorPid);
-		await stopPlanePostgres(stamp.pgKind);
-	}
-	fs.rmSync(pidfile, { force: true });
-	fs.rmSync(stampFile, { force: true });
+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;
 }
 /**
-* 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.
 */
-async function waitForProcessExit(pid, graceMs = 1e4) {
-	const deadline = Date.now() + graceMs;
-	let killed = false;
-	for (;;) {
-		try {
-			process.kill(pid, 0);
-		} catch {
-			return;
-		}
-		if (!killed && Date.now() > deadline) {
-			try {
-				process.kill(pid, "SIGKILL");
-			} catch {
-				return;
-			}
-			killed = true;
-		}
-		await new Promise((r) => setTimeout(r, 100));
+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
@@ -335,6 +475,6 @@ async function detachPlane(opts = {}) {
 	return planeUp();
 }
 //#endregion
-export { attachPlane, clearAttachment, clearPlatformToken, detachPlane, devIdentityKeyFile, devIdentityPublicJwkFile, planeAdminToken, planeDown, planeLogPath, planeStatus, planeUp, readAttachment, readOrCreateAdminToken, readOrCreateDevIdentity, readOrCreateSecretKey, readPlatformToken, waitForProcessExit, writeAttachment, writePlatformToken };
+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

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

@@ -45,8 +45,14 @@ export interface LocalTriggerRequest {
  * of this phase — no orchestrator export is added).
  */
 export declare function buildLocalTriggerRequest(input: LocalTriggerInput): LocalTriggerRequest;
-/** POST the trigger request to the plane. Returns the HTTP status. */
-export declare function sendLocalTrigger(planeUrl: string, req: LocalTriggerRequest): Promise<number>;
+/** Structured result of posting a local trigger to the plane. */
+export interface LocalTriggerResponse {
+    status: number;
+    /** Routing-key-scoped delivery id echoed by the plane, or null if absent. */
+    deliveryId: string | null;
+}
+/** POST the trigger request to the plane. Returns the status + delivery id. */
+export declare function sendLocalTrigger(planeUrl: string, req: LocalTriggerRequest): Promise<LocalTriggerResponse>;
 export interface TriggerRunOptions {
     client?: RunDiscoveryClient;
     pollIntervalMs?: number;
@@ -55,8 +61,11 @@ export interface TriggerRunOptions {
 }
 /**
  * Trigger the run and resolve its runId. Sends the synthetic push, then polls
- * the admin runs list (`created_at > since`) for the newest run, resending the
- * webhook past a grace window to absorb source hot-reload latency.
+ * the admin runs list filtered by this webhook's routing-key-scoped delivery id
+ * (`?deliveryId=`), resending the webhook past a grace window to absorb source
+ * hot-reload latency. Correlating on the exact delivery id — rather than the
+ * newest run in a time window — guarantees the follower attaches to the run
+ * THIS invocation created, even when another local run lands concurrently.
  */
 export declare function triggerRun(planeUrl: string, adminToken: string, input: LocalTriggerInput, opts?: TriggerRunOptions): Promise<string>;
 //# sourceMappingURL=plane-trigger.d.ts.map

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

@@ -45,45 +45,58 @@ function buildLocalTriggerRequest(input) {
 		body
 	};
 }
-/** POST the trigger request to the plane. Returns the HTTP status. */
+/** POST the trigger request to the plane. Returns the status + delivery id. */
 async function sendLocalTrigger(planeUrl, req) {
-	return (await fetch(`${planeUrl.replace(/\/$/, "")}${req.path}`, {
+	const res = await fetch(`${planeUrl.replace(/\/$/, "")}${req.path}`, {
 		method: "POST",
 		headers: req.headers,
 		body: req.body
-	})).status;
+	});
+	let deliveryId = null;
+	try {
+		const parsed = await res.json();
+		if (typeof parsed.deliveryId === "string") deliveryId = parsed.deliveryId;
+	} catch {}
+	return {
+		status: res.status,
+		deliveryId
+	};
 }
 /**
 * Trigger the run and resolve its runId. Sends the synthetic push, then polls
-* the admin runs list (`created_at > since`) for the newest run, resending the
-* webhook past a grace window to absorb source hot-reload latency.
+* the admin runs list filtered by this webhook's routing-key-scoped delivery id
+* (`?deliveryId=`), resending the webhook past a grace window to absorb source
+* hot-reload latency. Correlating on the exact delivery id — rather than the
+* newest run in a time window — guarantees the follower attaches to the run
+* THIS invocation created, even when another local run lands concurrently.
 */
 async function triggerRun(planeUrl, adminToken, input, opts = {}) {
 	const client = opts.client ?? new AdminApiClient(planeUrl, adminToken);
 	const pollIntervalMs = opts.pollIntervalMs ?? 750;
 	const resendAfterMs = opts.resendAfterMs ?? 8e3;
 	const timeoutMs = opts.timeoutMs ?? 6e4;
-	const since = /* @__PURE__ */ new Date(Date.now() - 3e3);
 	const req = buildLocalTriggerRequest(input);
-	await sendLocalTrigger(planeUrl, req);
+	let deliveryId = (await sendLocalTrigger(planeUrl, req)).deliveryId;
 	let lastSend = Date.now();
 	const deadline = Date.now() + timeoutMs;
 	while (Date.now() < deadline) {
-		const runId = await findLatestRunSince(client, since);
-		if (runId) return runId;
+		if (deliveryId) {
+			const runId = await findRunByDelivery(client, deliveryId);
+			if (runId) return runId;
+		}
 		if (Date.now() - lastSend > resendAfterMs) {
-			await sendLocalTrigger(planeUrl, req);
+			deliveryId ??= (await sendLocalTrigger(planeUrl, req)).deliveryId;
 			lastSend = Date.now();
 		}
 		await sleep(pollIntervalMs);
 	}
 	throw new Error("offline run: no run appeared after triggering the local plane");
 }
-/** Return the newest run created after `since`, or null when none yet. */
-async function findLatestRunSince(client, since) {
+/** Return the run created by this webhook delivery, or null when none yet. */
+async function findRunByDelivery(client, deliveryId) {
 	const qs = new URLSearchParams({
-		since: since.toISOString(),
-		limit: "5"
+		deliveryId,
+		limit: "1"
 	});
 	const { runs } = await client.get(`/api/v1/admin/runs?${qs}`);
 	return runs[0]?.runId ?? null;

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

@@ -99,11 +99,7 @@ async function probePlatformReachable(apiBase, timeoutMs = 4e3) {
 }
 /** A short, non-sensitive label for the minted key name (the machine host). */
 function orgHostLabel() {
-	try {
-		return process.env.HOSTNAME || "kici-local";
-	} catch {
-		return "kici-local";
-	}
+	return process.env.HOSTNAME || "kici-local";
 }
 //#endregion
 export { derivePlatformWsUrl, mintOrchestratorKey, probePlatformReachable, revokeOrchestratorKey };

package/dist/local-plane/port-holder.d.ts

@@ -0,0 +1,78 @@
+/** Command runner, injectable so each platform branch is unit-testable anywhere. */
+export type ExecFn = (cmd: string, args: string[]) => Promise<{
+    stdout: string;
+    exitCode: number;
+}>;
+/**
+ * Command line of process `pid`, or null when it cannot be determined.
+ *
+ * Linux exposes it as a NUL-separated `/proc` file; every other platform is
+ * asked through the same injectable `ExecFn` the port discovery above uses.
+ *
+ * **A null means "cannot tell", never "not that process."** Callers must treat
+ * it as an absence of evidence — the only safe reading when the answer decides
+ * whether to signal a pid.
+ */
+export declare function processCommandLine(pid: number, opts?: {
+    exec?: ExecFn;
+    platform?: NodeJS.Platform;
+    readProc?: (path: string) => string;
+}): Promise<string | null>;
+/**
+ * Whether the port can be bound on loopback. Probes `127.0.0.1` because that is
+ * the address the CLI talks to; a listener bound to `0.0.0.0` still makes this
+ * bind fail with EADDRINUSE, so there is no false "free".
+ */
+export declare function isPortFree(port: number): Promise<boolean>;
+/**
+ * Parse `ss -lptnH` rows. The process name is deliberately NOT matched — a Node
+ * listener reports as `MainThread` — so only `pid=N` is extracted. A row for a
+ * socket this user does not own carries no `users:(…)` field at all and yields
+ * null, which is what sends the caller to the lsof fallback.
+ */
+export declare function parseSsOutput(stdout: string, port: number): number | null;
+/**
+ * Parse `lsof -Fpn` field output, which is a stateful stream: each `p<pid>` line
+ * precedes the `n<address>` lines belonging to that pid.
+ */
+export declare function parseLsofOutput(stdout: string, port: number): number | null;
+/** Parse `netstat -ano -p tcp`: LISTENING rows only, pid in the last column. */
+export declare function parseNetstatOutput(stdout: string, port: number): number | null;
+/**
+ * Pid of the process listening on `port`, or null when it cannot be determined.
+ * Each platform runs the UNFILTERED listing and matches the port here rather
+ * than passing a filter expression to the tool, whose syntax is the fragile
+ * part. On Linux a null parse falls through to lsof as well as a non-zero exit,
+ * because ss omits the owning-process field for sockets this user does not own.
+ */
+export declare function findPortHolderPid(port: number, opts?: {
+    exec?: ExecFn;
+    platform?: NodeJS.Platform;
+}): Promise<number | null>;
+/** Signal sender, injectable so the escalation windows are unit-testable. */
+export type KillFn = (pid: number, signal: NodeJS.Signals | 0) => void;
+/**
+ * Poll until process `pid` has exited, sending SIGTERM first and escalating to
+ * SIGKILL past the grace window. `process.kill(pid, 0)` throws ESRCH once the
+ * process is gone. On Windows every signal terminates unconditionally, so the
+ * escalation collapses into a single hard kill there.
+ *
+ * Resolving does NOT prove the process died: a pid that survives SIGKILL (a
+ * zombie awaiting reaping, or a task wedged in uninterruptible I/O) is given
+ * `hardKillWaitMs` and then abandoned, because a teardown command that hangs
+ * forever is worse than one that reports the port is still held. Callers decide
+ * the outcome from the port itself — `waitForPortFree` — never from this
+ * resolving.
+ */
+export declare function terminatePid(pid: number, graceMs?: number, opts?: {
+    hardKillWaitMs?: number;
+    kill?: KillFn;
+}): Promise<void>;
+/**
+ * Poll until the port is bindable. This, not `terminatePid` resolving, is what
+ * decides a teardown: `terminatePid` abandons a pid that survives SIGKILL, and
+ * even a process that did exit can leave its listening socket lingering a moment
+ * longer on some platforms.
+ */
+export declare function waitForPortFree(port: number, timeoutMs?: number): Promise<boolean>;
+//# sourceMappingURL=port-holder.d.ts.map