home-hosted 0.7.19 → 0.7.20

package/AGENTS.md

@@ -121,6 +121,12 @@ nobody reads is worse than a long file.
   never recreated.
 - **A port is only ever freed by re-listing its listeners.** `free-port` never trusts a pid quoted in
   a message, and refuses any listener in `supervisedPids()` instead of killing it.
+- **A live pid is not the running panel.** Pids are recycled and a zombie still answers signal 0, so
+  `up`/`status`/`down` decide with `runtimeIsAlive`/`runtimeLiveness` (pid **plus** `run.json`'s own
+  `startedAt`), never `isProcessAlive` alone — otherwise `up` refuses against a dead panel, `status`
+  reports "running, but not answering", and `down` signals an unrelated process. Only `'gone'`
+  (nothing behind the pid) deletes a record; `'recycled'` blocks a **signal** but still allows the
+  token-authenticated `/_hh/shutdown`, because the birth time is wall-clock-derived.
 - **Only `kill` ever touches a process the panel could not identify** — which is why it logs the pids
   it stopped. `follow` adopts this entry's own successor, `reclaim` replaces it. Ownership is the
   entry's whole **tree**, and the panel's own tree is excluded. Full matching rules:

package/README.md

@@ -341,7 +341,7 @@ restarts itself), and how hand-edits are validated: [SERVERS.md](./docs/SERVERS.
 | `home-hosted up` | start the panel detached, and keep it alive in the background |
 | `home-hosted down` | stop it cleanly — supervised processes included, persistent entries left running |
 | `home-hosted restart` | `down`, then `up` — or `restart <id>` to restart one server, leaving the panel up |
-| `home-hosted status` | pid, URL, health, uptime, state and log paths — the panel's console *and* the per-server directory, naming the `<id>.log` convention once logs exist (`--json` for scripts; stopped answers `{ running: false, initialised }`, where `initialised: false` means nothing was ever set up here) |
+| `home-hosted status` | pid, URL, health, uptime, state and log paths — the panel's console *and* the per-server directory, naming the `<id>.log` convention once logs exist (`--json` for scripts; stopped answers `{ running: false, initialised }`, where `initialised: false` means nothing was ever set up here, plus `liveness` — `gone`, or `recycled` when the OS has handed the recorded pid to another process and the record is stale) |
 | `home-hosted start <id>` | start one server in the default workspace — and anything it `dependsOn` (`--workspace <id>`) |
 | `home-hosted stop <id>` | stop one server, nothing else (`--workspace <id>`) |
 | `home-hosted restart <id>` | restart one server, nothing else (`--workspace <id>`) — the same as the panel's per-server Restart |

package/dist/cli.js

@@ -7301,6 +7301,125 @@ function isProcessAlive(pid) {
 		return error.code === "EPERM";
 	}
 }
+/**
+* `/proc/<pid>/stat` field 22 is the start time in clock ticks since boot, which only
+* becomes an epoch by adding `btime` from `/proc/stat`. Field 3 is the state.
+*
+* The comm field is parenthesised and may itself hold spaces and parentheses, so the
+* fields are counted from after the **last** `)`. Counting from the first would shift
+* every offset for a process whose name contains a `)`, and this value decides whether a
+* live-looking pid is really the daemon.
+*/
+function parseProcBirth(content, btimeSeconds, hz = LINUX_HZ) {
+	const close = content.lastIndexOf(")");
+	if (close < 0) return null;
+	const fields = content.slice(close + 2).split(" ");
+	const ticks = Number.parseInt(fields[19] ?? "", 10);
+	if (!Number.isFinite(ticks) || ticks < 0) return null;
+	return {
+		startMs: btimeSeconds * 1e3 + ticks / hz * 1e3,
+		zombie: fields[0] === "Z"
+	};
+}
+/**
+* One `ps -o state=,lstart=` row, e.g. `S Wed Oct  7 19:43:26 2026` (macOS, other POSIX).
+* The leading weekday is stripped before parsing: `Date.parse` is not obliged to accept it
+* and it says nothing the date does not.
+*/
+function parsePsBirth(output) {
+	const line = output.trim().split("\n")[0]?.trim() ?? "";
+	if (line.length === 0) return null;
+	const [state = "", ...rest] = line.split(/\s+/);
+	const startMs = Date.parse(rest.join(" ").replace(/^[A-Z]{3,9}\s+/i, ""));
+	if (!Number.isFinite(startMs)) return null;
+	return {
+		startMs,
+		zombie: state.startsWith("Z")
+	};
+}
+/**
+* FILETIME ticks (100ns since **1601**, UTC) to a Unix epoch in ms — the shape
+* `DateTime.ToFileTimeUtc()` returns.
+*
+* The epoch matters: `DateTime.Ticks` counts from **0001**, not 1601, and the two differ by
+* 1600 years. Reading the wrong one put every Windows panel ~1600 years in the future, which
+* `processLiveness` then called `recycled` — a live panel that could never signal-stop itself.
+* The PowerShell call below therefore asks for `ToFileTimeUtc()` explicitly, and this is exported
+* so the conversion is pinned by a test.
+*/
+function parseFiletime(ticks) {
+	if (!Number.isFinite(ticks) || ticks <= 0) return null;
+	return ticks / 1e4 - FILETIME_UNIX_OFFSET_MS;
+}
+/**
+* When the pid started, from the platform's own process table. `null` when the platform
+* cannot say — an unreadable `/proc`, no `ps`, or no PowerShell — which the caller must
+* read as "unknown", never as "gone".
+*/
+async function processBirth(pid) {
+	if (!Number.isInteger(pid) || pid <= 0) return null;
+	if (process.platform === "linux") try {
+		const [stat, system] = await Promise.all([fs.promises.readFile(`/proc/${pid}/stat`, "utf8"), fs.promises.readFile("/proc/stat", "utf8")]);
+		const btime = /^btime (\d+)$/m.exec(system)?.[1];
+		if (btime === void 0) return null;
+		return parseProcBirth(stat, Number.parseInt(btime, 10));
+	} catch {
+		return null;
+	}
+	if (process.platform === "win32") try {
+		const script = `$p = Get-CimInstance Win32_Process -Filter "ProcessId=${pid}"; if ($p) { $p.CreationDate.ToFileTimeUtc() }`;
+		const { stdout } = await execFileAsync$2("powershell", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			script
+		], {
+			timeout: 2e4,
+			windowsHide: true
+		});
+		const startMs = parseFiletime(Number.parseFloat(stdout.trim()));
+		return startMs === null ? null : {
+			startMs,
+			zombie: false
+		};
+	} catch {
+		return null;
+	}
+	try {
+		const { stdout } = await execFileAsync$2("ps", [
+			"-p",
+			String(pid),
+			"-o",
+			"state=,lstart="
+		], { timeout: 3e3 });
+		return parsePsBirth(stdout);
+	} catch {
+		return null;
+	}
+}
+/**
+* A pid is **not** an identity. The OS hands a dead process's pid to an unrelated one later, and a
+* zombie — exited but not yet reaped by its parent — still answers signal 0. So `isProcessAlive`
+* alone can report a long-dead daemon as live, which is what let `up` say "already running" and
+* `status` say "running, but not answering" against a stale `run.json`, and what let `down` signal
+* whatever stranger had inherited the pid.
+*
+* `startedAt` settles it in one direction, with no threshold to guess at: the daemon writes its
+* record *during its own boot*, so its process is necessarily born **before** that stamp. A pid born
+* after it is not that process, whoever else it now is. The comparison is deliberately one-sided —
+* the other direction would have to tell a recycled pid from a wall clock that merely moved, and it
+* cannot, so a record is never called stale for being *older* than its process.
+*
+* `'unknown'` is not `'gone'`: a platform that cannot report a birth time must not have its live pid
+* dismissed, or a running panel's record would be cleared out from under it.
+*/
+async function processLiveness(pid, startedAt, options = {}) {
+	if (!isProcessAlive(pid)) return "gone";
+	const birth = await (options.readBirth ?? processBirth)(pid);
+	if (birth === null) return "unknown";
+	if (birth.zombie) return "gone";
+	return birth.startMs > startedAt + (options.toleranceMs ?? 2e3) ? "recycled" : "live";
+}
 function signalPid$1(pid, name) {
 	try {
 		process.kill(pid, name);
@@ -7384,9 +7503,11 @@ async function listPortHolders(port) {
 function parsePids(stdout) {
 	return [...new Set(stdout.split(/\s+/).map((entry) => Number.parseInt(entry, 10)).filter((pid) => Number.isInteger(pid) && pid > 0 && pid !== process.pid))];
 }
-var execFileAsync$2;
+var execFileAsync$2, LINUX_HZ, FILETIME_UNIX_OFFSET_MS;
 var init_port = __esmMin((() => {
 	execFileAsync$2 = promisify(execFile);
+	LINUX_HZ = 100;
+	FILETIME_UNIX_OFFSET_MS = 0xa9730b66800;
 }));
 //#endregion
 //#region src/providers/nanny.ts
@@ -11126,12 +11247,16 @@ var init_layout = __esmMin((() => {
 //#region src/helpers/daemon.ts
 var daemon_exports = /* @__PURE__ */ __exportAll({
 	clearRuntime: () => clearRuntime,
+	isLiveLiveness: () => isLiveLiveness,
 	isProcessAlive: () => isProcessAlive,
 	newToken: () => newToken,
 	probeRuntime: () => probeRuntime,
 	readRuntime: () => readRuntime,
 	requestControl: () => requestControl,
 	requestShutdown: () => requestShutdown,
+	runtimeIsAlive: () => runtimeIsAlive,
+	runtimeIsGone: () => runtimeIsGone,
+	runtimeLiveness: () => runtimeLiveness,
 	runtimeSchema: () => runtimeSchema,
 	writeRuntime: () => writeRuntime
 });
@@ -11152,6 +11277,51 @@ function clearRuntime() {
 function newToken() {
 	return randomBytes(32).toString("base64url");
 }
+/**
+* What became of the daemon this record describes: the verdict `run.json`'s pid cannot give on
+* its own. See `processLiveness` in `providers/port.ts` for why the pid is not an identity.
+*/
+async function runtimeLiveness(runtime) {
+	return await processLiveness(runtime.pid, runtime.startedAt);
+}
+/**
+* Is the daemon this record describes still the one running?
+*
+* `readRuntime()` answers "does a record exist", never "is the panel behind it alive" — and a pid
+* alone cannot answer that either. The OS reuses pids, and a zombie still answers signal 0, so a
+* bare `isProcessAlive(runtime.pid)` reported a stale `run.json` as a live panel: `up` refused with
+* "already running", `status` said "running, but not answering", and `down` signalled whatever
+* unrelated process had since inherited the pid.
+*
+* Every caller must read this one predicate, because a caller that re-derives it slightly differently
+* is how a `down` comes to signal a stranger.
+*/
+async function runtimeIsAlive(runtime) {
+	return isLiveLiveness(await runtimeLiveness(runtime));
+}
+/**
+* Only `'live'` and `'unknown'` count as alive. `'unknown'` means the platform could not read a start
+* time, so the live pid is all there is — dismissing it would clear a record the running panel still
+* owns. `'recycled'` is emphatically **not** alive: the pid belongs to somebody else now.
+*/
+function isLiveLiveness(liveness) {
+	return liveness === "live" || liveness === "unknown";
+}
+/**
+* Is the record positively pointing at nothing at all — no process behind the pid?
+*
+* This is the **only** condition under which deleting `run.json` is safe, so it is deliberately
+* narrower than `!runtimeIsAlive`. The start-time check can be wrong in one direction: Linux derives
+* a process's birth epoch from `btime`, which the kernel computes from the wall clock
+* (`getboottime64`: "calls to settimeofday will affect the value returned"), so a forward clock step
+* — common when a laptop or a WSL host wakes from sleep — makes a *live* panel look recycled. Deleting
+* its record over that would orphan a running panel: still supervising servers, no longer stoppable by
+* `down`. A record that some process may still own is left alone and simply overwritten when a new
+* panel finishes booting.
+*/
+async function runtimeIsGone(runtime) {
+	return await runtimeLiveness(runtime) === "gone";
+}
 /** A degraded panel is still answering: a 503 must not read as "not running". */
 async function probeRuntime(runtime, timeoutMs = 2500) {
 	const answer = await localCall(runtime, "/healthz", "GET", void 0, timeoutMs);
@@ -16906,11 +17076,11 @@ function probeHostFor(bindHost) {
 async function runControlPlane(options) {
 	ensureLayout();
 	const existing = readRuntime();
-	if (existing !== null && existing.pid !== process.pid && isProcessAlive(existing.pid)) {
+	if (existing !== null && existing.pid !== process.pid && await runtimeIsAlive(existing)) {
 		logger.error(`already running (pid ${existing.pid}) at ${existing.url} — run \`home-hosted down\` first`);
 		process.exit(1);
 	}
-	if (existing !== null) clearRuntime();
+	if (existing !== null && await runtimeIsGone(existing)) clearRuntime();
 	const settings = new GlobalSettingsStore();
 	settings.load();
 	settings.writeJsonSchema();
@@ -17265,17 +17435,17 @@ async function runUp(flags, entry) {
 		});
 		return;
 	}
-	const { clearRuntime, isProcessAlive, readRuntime } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
+	const { clearRuntime, readRuntime, runtimeIsAlive, runtimeIsGone } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
 	const { daemonLogPath, dataRoot, projectDir } = await Promise.resolve().then(() => (init_paths(), paths_exports));
 	const existing = readRuntime();
-	if (existing !== null && isProcessAlive(existing.pid)) {
+	if (existing !== null && await runtimeIsAlive(existing)) {
 		process.stdout.write(`${green("already running")} home-hosted ${existing.version} (pid ${existing.pid}) at ${existing.url}\n`);
 		const note = versionMismatchNote(existing.version);
 		if (note !== null) process.stdout.write(`${dim(note)}\n`);
 		process.stdout.write(`${dim("stop it with `home-hosted down`")}\n`);
 		return;
 	}
-	if (existing !== null) clearRuntime();
+	if (existing !== null && await runtimeIsGone(existing)) clearRuntime();
 	fs.mkdirSync(path.dirname(daemonLogPath), { recursive: true });
 	rotateLog(daemonLogPath);
 	const log = fs.openSync(daemonLogPath, "a");
@@ -17383,13 +17553,14 @@ var down_exports = /* @__PURE__ */ __exportAll({
 });
 /** `down` stops the panel and everything it supervises. */
 async function runDown() {
-	const { clearRuntime, isProcessAlive, readRuntime, requestShutdown } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
+	const { clearRuntime, isLiveLiveness, readRuntime, requestShutdown, runtimeLiveness } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
 	const runtime = readRuntime();
 	if (runtime === null) {
 		process.stdout.write("home-hosted is not running\n");
 		return;
 	}
-	if (!isProcessAlive(runtime.pid)) {
+	const liveness = await runtimeLiveness(runtime);
+	if (liveness === "gone") {
 		clearRuntime();
 		process.stdout.write(`home-hosted is not running (removed a stale run.json from home-hosted ${runtime.version})\n`);
 		return;
@@ -17400,8 +17571,21 @@ async function runDown() {
 		const note = versionMismatchNote(runtime.version);
 		if (note !== null) process.stdout.write(`${dim(note)}\n`);
 	};
-	process.stdout.write(`stopping pid ${runtime.pid}…\n`);
-	if (!await requestShutdown(runtime)) signal(runtime.pid, "SIGTERM");
+	let answered = false;
+	if (isLiveLiveness(liveness)) {
+		process.stdout.write(`stopping pid ${runtime.pid}…\n`);
+		answered = await requestShutdown(runtime);
+		if (!answered) signal(runtime.pid, "SIGTERM");
+	} else {
+		if (!await requestShutdown(runtime)) {
+			process.stdout.write(`home-hosted is not running (the pid in run.json, ${runtime.pid}, belongs to another process — it was not signalled)\n`);
+			return;
+		}
+		process.stdout.write(`stopped the panel on ${runtime.url} (its pid in run.json, ${runtime.pid}, was another process and was left alone)\n`);
+		clearRuntime();
+		await reportPersistent();
+		return;
+	}
 	if (await waitForExit(runtime.pid, 2e4)) {
 		clearRuntime();
 		reportStopped(false);
@@ -17490,10 +17674,10 @@ var server_exports = /* @__PURE__ */ __exportAll({
 	stopCommand: () => stopCommand
 });
 async function runServerAction(action, id, workspace) {
-	const { clearRuntime, isProcessAlive, readRuntime, requestControl } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
+	const { clearRuntime, readRuntime, requestControl, runtimeIsAlive, runtimeIsGone } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
 	const runtime = readRuntime();
-	if (runtime === null || !isProcessAlive(runtime.pid)) {
-		if (runtime !== null) clearRuntime();
+	if (runtime === null || !await runtimeIsAlive(runtime)) {
+		if (runtime !== null && await runtimeIsGone(runtime)) clearRuntime();
 		fail("home-hosted is not running — start it with `home-hosted up`");
 	}
 	const query = workspace === void 0 || workspace.length === 0 ? "" : `?workspace=${encodeURIComponent(workspace)}`;
@@ -17590,7 +17774,7 @@ var status_exports = /* @__PURE__ */ __exportAll({
 	statusCommand: () => statusCommand
 });
 async function runStatus(json) {
-	const { isProcessAlive, probeRuntime, readRuntime } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
+	const { isLiveLiveness, probeRuntime, readRuntime, runtimeLiveness } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
 	const { UiService } = await Promise.resolve().then(() => (init_ui(), ui_exports));
 	const { hhDir: dataRoot, workspaceDir, DEFAULT_WORKSPACE_ID, workspacesPath } = await Promise.resolve().then(() => (init_paths(), paths_exports));
 	const runtime = readRuntime();
@@ -17605,7 +17789,8 @@ async function runStatus(json) {
 		process.exitCode = 1;
 		return;
 	}
-	const running = isProcessAlive(runtime.pid);
+	const liveness = await runtimeLiveness(runtime);
+	const running = isLiveLiveness(liveness);
 	const probe = running ? await probeRuntime(runtime) : {
 		reachable: false,
 		degraded: false
@@ -17617,6 +17802,7 @@ async function runStatus(json) {
 		const { token: _token, ...safe } = runtime;
 		process.stdout.write(`${JSON.stringify({
 			running,
+			liveness,
 			answering: probe.reachable,
 			degraded: probe.degraded,
 			...safe,
@@ -17632,7 +17818,7 @@ async function runStatus(json) {
 	}
 	const uptime = formatDuration(Date.now() - runtime.startedAt);
 	const rows = [
-		["status", !running ? paint("31", "stale (the process is gone)") : probe.degraded ? paint("33", "running — a server needs attention") : probe.reachable ? green("running") : paint("33", "running, but not answering")],
+		["status", !running ? liveness === "recycled" ? paint("31", "stale (the pid belongs to another process now)") : paint("31", "stale (the process is gone)") : probe.degraded ? paint("33", "running — a server needs attention") : probe.reachable ? green("running") : paint("33", "running, but not answering")],
 		["pid", running ? `${runtime.pid} · up ${uptime}` : String(runtime.pid)],
 		["url", `${runtime.url} ${dim(`(${runtime.protocol})`)}`],
 		["version", runtime.version],