@os-eco/overstory-cli 0.9.3 → 0.10.3

package/src/utils/pid.ts

@@ -1,7 +1,9 @@
 /**
  * PID file management for daemon processes.
  */
-import { unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { link, mkdir, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 
 /**
  * Read the PID from a PID file.
@@ -43,3 +45,86 @@ export async function removePidFile(pidFilePath: string): Promise<void> {
 		// File may already be gone — not an error
 	}
 }
+
+/**
+ * Result of acquirePidLock.
+ *
+ * `acquired: true` — caller owns the lock and is responsible for removing the
+ * PID file on shutdown.
+ *
+ * `acquired: false` — a live foreign process already owns the lock; caller
+ * must not start. `existingPid` is the live owner. `existingPid === -1` means
+ * the lock file existed but was unreadable and could not be reclaimed.
+ */
+export type AcquirePidLockResult = { acquired: true } | { acquired: false; existingPid: number };
+
+/**
+ * Atomically acquire a PID-file lock.
+ *
+ * Uses the write-temp-then-link pattern so the lock file appears at its final
+ * path with PID contents already present (no empty-file window): a competing
+ * reader can never observe an in-flight write. Behavior:
+ *
+ * - Lock file does not exist → atomic create via link(). Caller owns the lock.
+ * - Lock file exists, contains the caller's own PID → idempotent acquire
+ *   (caller already owns it; e.g. background-mode parent wrote child.pid
+ *   before spawn).
+ * - Lock file exists with a live foreign PID → refuse; return existingPid.
+ * - Lock file exists with a dead PID (or unreadable) → reclaim by unlinking
+ *   and retrying once. If the retry races and loses to a live foreign
+ *   watchdog, the call returns acquired=false with that foreign PID.
+ *
+ * Parent directory is created if missing (matches the implicit Bun.write
+ * behavior the legacy writePidFile relied on).
+ */
+export async function acquirePidLock(
+	pidFilePath: string,
+	pid: number,
+	isAlive: (pid: number) => boolean,
+): Promise<AcquirePidLockResult> {
+	await mkdir(dirname(pidFilePath), { recursive: true });
+
+	// Stage the PID content at a unique temp path. After link() succeeds, the
+	// lock path appears with full content already present.
+	const tempPath = `${pidFilePath}.tmp.${pid}.${randomUUID()}`;
+	await writeFile(tempPath, `${pid}\n`);
+
+	try {
+		// Two attempts: first try, then one stale-lock reclaim retry. A second
+		// EEXIST after reclaim means a live foreign process raced in.
+		for (let attempt = 0; attempt < 2; attempt++) {
+			try {
+				await link(tempPath, pidFilePath);
+				return { acquired: true };
+			} catch (err: unknown) {
+				const code = (err as NodeJS.ErrnoException | undefined)?.code;
+				if (code !== "EEXIST") {
+					throw err;
+				}
+				const existing = await readPidFile(pidFilePath);
+				if (existing === null) {
+					// Unreadable/corrupted lock file — treat as stale.
+					await removePidFile(pidFilePath);
+					continue;
+				}
+				if (existing === pid) {
+					// Idempotent: caller already owns it (parent pre-wrote child PID).
+					return { acquired: true };
+				}
+				if (isAlive(existing)) {
+					return { acquired: false, existingPid: existing };
+				}
+				// Stale: reclaim and retry once.
+				await removePidFile(pidFilePath);
+			}
+		}
+
+		// Two stale-then-retry attempts both failed. Another writer raced in
+		// between our reclaim and our retry — they own the lock now.
+		const existing = await readPidFile(pidFilePath);
+		return { acquired: false, existingPid: existing ?? -1 };
+	} finally {
+		// Drop the temp inode link (lock path retains the data via the second link).
+		await unlink(tempPath).catch(() => {});
+	}
+}

package/src/utils/process-scan.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { findRunningWatchdogProcesses } from "./process-scan.ts";
+
+describe("findRunningWatchdogProcesses", () => {
+	test("returns an array (does not throw)", async () => {
+		const results = await findRunningWatchdogProcesses();
+		expect(Array.isArray(results)).toBe(true);
+		// We can't assert specifics — depends on what's running on the host —
+		// but each entry should have a numeric pid and string command.
+		for (const proc of results) {
+			expect(typeof proc.pid).toBe("number");
+			expect(proc.pid).toBeGreaterThan(0);
+			expect(typeof proc.command).toBe("string");
+		}
+	});
+
+	test("excludes own process even if command matches", async () => {
+		// The test process itself runs `bun test ...` not `ov watch`, so it
+		// would not match anyway. But we still verify own-pid is filtered out
+		// by checking no result has our PID.
+		const results = await findRunningWatchdogProcesses();
+		const ownPid = process.pid;
+		for (const proc of results) {
+			expect(proc.pid).not.toBe(ownPid);
+		}
+	});
+
+	test("matches `ov watch` and `bun run ov watch` invocations", async () => {
+		// Spawn a sleeper whose command line contains the `ov watch` substring,
+		// then verify the scanner finds it. We use `sh -c` so the argv string
+		// passed to ps contains our marker tokens.
+		const sleeper = Bun.spawn(["sh", "-c", "exec -a 'bun run ov watch' sleep 30"], {
+			stdout: "ignore",
+			stderr: "ignore",
+		});
+		try {
+			// Give ps a moment to see the new process.
+			await Bun.sleep(150);
+			const results = await findRunningWatchdogProcesses();
+			const found = results.find((p) => p.pid === sleeper.pid);
+			// On macOS BSD ps, `exec -a` may or may not change the displayed
+			// argv depending on shell version. We accept either: if the
+			// command is detected, it must look right; if not, we don't fail
+			// the test (env-dependent).
+			if (found) {
+				expect(found.command).toMatch(/\b(ov|overstory)\b.*\bwatch\b/);
+			}
+		} finally {
+			sleeper.kill("SIGTERM");
+			await sleeper.exited.catch(() => {});
+		}
+	});
+});

package/src/utils/process-scan.ts

@@ -0,0 +1,76 @@
+/**
+ * Process-table scanning helpers.
+ *
+ * Used to detect runaway daemon processes that are not tracked by a PID file —
+ * for example, the multi-`ov watch` situation observed on 2026-04-30 where
+ * three concurrent watchdogs were running because earlier releases had no
+ * PID-file exclusion lock.
+ *
+ * Implementation note: `ps` is used directly because we only need to find
+ * processes by command-line substring, and Bun has no built-in process-table
+ * API. The `ps -o pid=,command=` form is portable across macOS (BSD) and
+ * Linux (procps) for the columns we read.
+ */
+
+export interface WatchdogProcess {
+	pid: number;
+	/** The full command line as reported by `ps`. */
+	command: string;
+}
+
+/**
+ * Find running processes that look like an `ov watch` daemon.
+ *
+ * Matches on the command-line substring `ov watch` (the daemon spawn form)
+ * and excludes the current process so callers do not accidentally treat
+ * themselves as a foreign daemon.
+ *
+ * Returns an empty list if `ps` is unavailable or fails — callers must not
+ * rely on this for correctness, only for diagnostics and `--kill-others`.
+ */
+export async function findRunningWatchdogProcesses(): Promise<WatchdogProcess[]> {
+	const proc = Bun.spawn(["ps", "-A", "-o", "pid=,command="], {
+		stdout: "pipe",
+		stderr: "ignore",
+	});
+	const exitCode = await proc.exited;
+	if (exitCode !== 0) {
+		return [];
+	}
+	const text = await new Response(proc.stdout).text();
+	const ownPid = process.pid;
+	const out: WatchdogProcess[] = [];
+
+	for (const rawLine of text.split("\n")) {
+		const line = rawLine.trim();
+		if (line === "") continue;
+
+		// `ps -o pid=,command=` outputs: `   1234 /path/to/binary args...`
+		// (leading whitespace is allowed, then PID, then a single space, then
+		// the rest of the command).
+		const match = line.match(/^(\d+)\s+(.+)$/);
+		if (!match) continue;
+		const pidStr = match[1];
+		const command = match[2];
+		if (pidStr === undefined || command === undefined) continue;
+		const pid = Number.parseInt(pidStr, 10);
+		if (!Number.isFinite(pid) || pid <= 0) continue;
+		if (pid === ownPid) continue;
+
+		// Match the spawn form: `bun run /path/to/ov watch`. We also tolerate
+		// direct invocation `overstory watch` and `ov watch`.
+		if (!isWatchdogCommand(command)) continue;
+
+		out.push({ pid, command });
+	}
+
+	return out;
+}
+
+function isWatchdogCommand(command: string): boolean {
+	// Anchor on a `watch` token preceded by an `ov` or `overstory` token.
+	// Avoids false positives like "watch ov.log" or unrelated `watch` commands.
+	if (!/\bwatch\b/.test(command)) return false;
+	if (/\b(ov|overstory)\b[^\n]*\bwatch\b/.test(command)) return true;
+	return false;
+}