reviewzy 0.1.0

package/src/notify.ts

@@ -0,0 +1,142 @@
+import type { Config } from "./config.ts";
+
+/** The debounce window: filings for one project inside it merge into a single ping per transport. */
+const DEFAULT_WINDOW_MS = 1000;
+
+/** Every ping's deadline; a hung transport can hold nothing, since the ping itself is fire-and-forget. */
+const PING_TIMEOUT_MS = 5_000;
+
+/**
+ * Everything a notification run needs, all injectable for tests: `config` arms the transports,
+ * `baseUrl` builds the dashboard link, and `fetch`/`windowMs` let a test point pings at real local
+ * servers and collapse bursts quickly.
+ */
+export type NotifierOptions = {
+  config: Config;
+  baseUrl: string;
+  fetch?: typeof fetch;
+  windowMs?: number;
+};
+
+/** One project's merged filings waiting out the debounce window. */
+type Pending = {
+  count: number;
+  batchId: string;
+  timer: Timer;
+};
+
+/**
+ * Fires filing notifications for `file_entries`. Debounce is trailing, keyed per project slug:
+ * each `notifyBatch` inside the window replaces the timer and merges into the pending ping (count
+ * sums, batch id goes latest), so an agent loop re-filing a burst lands as one ping at window end.
+ *
+ * Delivery is fire-and-forget: `notifyBatch` returns immediately, and a failing transport logs to
+ * stderr naming itself — it can never touch the filing result. The timer is unref'd, so a pending
+ * ping never holds the daemon open at shutdown; `dispose()` cancels it outright. All timing lives
+ * here: nothing upstream waits on or measures a window.
+ */
+export class Notifier {
+  readonly #config: Config;
+  readonly #baseUrl: string;
+  readonly #fetch: typeof fetch;
+  readonly #windowMs: number;
+  readonly #pending = new Map<string, Pending>();
+
+  constructor(options: NotifierOptions) {
+    this.#config = options.config;
+    this.#baseUrl = options.baseUrl;
+    this.#fetch = options.fetch ?? fetch;
+    this.#windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+  }
+
+  /**
+   * Called after a filing that changed the store: the caller (file_entries) computes `count` from
+   * its results and only calls here for a batch that created or updated at least one entry, so a
+   * zero count never arrives. Silent when every transport is unarmed.
+   */
+  notifyBatch(project: string, batchId: string, count: number): void {
+    // Guard on the real arming conditions, not just the urls: a topic-less ntfy url arms nothing,
+    // and a timer armed for a transport that can never ping is dead work per filing. The config is
+    // fixed for the daemon's life, so this never flips mid-debounce.
+    const ntfyArmed = this.#config.NTFY_URL !== undefined && this.#config.NTFY_TOPIC !== undefined;
+    if (!ntfyArmed && this.#config.WEBHOOK_URL === undefined) return;
+
+    const existing = this.#pending.get(project);
+    if (existing !== undefined) {
+      existing.count += count;
+      existing.batchId = batchId;
+      // The callback captures its values at arm time, and clearing the stale timer guarantees it
+      // never fires, so the one live timer always carries the merged count and batch id.
+      clearTimeout(existing.timer);
+      existing.timer = this.#arm(project, existing.count, existing.batchId);
+      return;
+    }
+    this.#pending.set(project, { count, batchId, timer: this.#arm(project, count, batchId) });
+  }
+
+  /** Cancels every pending debounce. The stop path calls this before closing the store. */
+  dispose(): void {
+    for (const pending of this.#pending.values()) clearTimeout(pending.timer);
+    this.#pending.clear();
+  }
+
+  #arm(project: string, count: number, batchId: string): Timer {
+    const timer = setTimeout(() => {
+      this.#pending.delete(project);
+      this.#ping(project, batchId, count);
+    }, this.#windowMs);
+    // A pending ping dropped at exit is acceptable, so the timer must never hold the process open.
+    timer.unref();
+    return timer;
+  }
+
+  #ping(project: string, batchId: string, count: number): void {
+    const dashboardUrl = `${this.#baseUrl}/?project=${encodeURIComponent(project)}`;
+    void this.#pingNtfy(project, count, dashboardUrl);
+    void this.#pingWebhook(project, batchId, count, dashboardUrl);
+  }
+
+  async #pingNtfy(project: string, count: number, dashboardUrl: string): Promise<void> {
+    const url = this.#config.NTFY_URL;
+    const topic = this.#config.NTFY_TOPIC;
+    // ntfy is armed only when both are set; a url alone posts to a topic named nothing.
+    if (url === undefined || topic === undefined) return;
+    const noun = count === 1 ? "entry" : "entries";
+    try {
+      const response = await this.#fetch(url, {
+        method: "POST",
+        headers: {
+          Topic: topic,
+          Title: `reviewzy: ${project}`,
+          Priority: String(this.#config.NTFY_PRIORITY),
+          Click: dashboardUrl,
+        },
+        body: `${count} new ${noun} from ${project} await review`,
+        signal: AbortSignal.timeout(PING_TIMEOUT_MS),
+      });
+      if (!response.ok) {
+        console.error(`reviewzy: ntfy notification failed: server answered ${response.status}`);
+      }
+    } catch (error) {
+      console.error(`reviewzy: ntfy notification failed: ${(error as Error).message}`);
+    }
+  }
+
+  async #pingWebhook(project: string, batchId: string, count: number, dashboardUrl: string): Promise<void> {
+    const url = this.#config.WEBHOOK_URL;
+    if (url === undefined) return;
+    try {
+      const response = await this.#fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ project, batch_id: batchId, count, dashboard_url: dashboardUrl }),
+        signal: AbortSignal.timeout(PING_TIMEOUT_MS),
+      });
+      if (!response.ok) {
+        console.error(`reviewzy: webhook notification failed: server answered ${response.status}`);
+      }
+    } catch (error) {
+      console.error(`reviewzy: webhook notification failed: ${(error as Error).message}`);
+    }
+  }
+}

package/src/shim/daemon.ts

@@ -0,0 +1,318 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, openSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { NAME } from "../version.ts";
+import {
+  acquireClaim,
+  claimHolderIsDead,
+  isPidAlive,
+  isReviewzyProcess,
+  readLockfile,
+  releaseClaim,
+  writeLockfileAtomic,
+  type Lockfile,
+} from "./lockfile.ts";
+import { compareSemver } from "./semver.ts";
+
+export type Health = { name: string; version: string; pid: number; nonce: string; startedAt: string };
+export type DaemonHandle = { pid: number; port: number; version: string };
+
+/** A lifecycle failure a caller can tell apart from a bug: bad state on disk, not broken code. */
+export class ShimError extends Error {
+  override readonly name = "ShimError";
+}
+
+const HEALTH_POLL_MS = 50;
+const HEALTH_BOOT_TIMEOUT_MS = 10_000;
+const CLAIM_POLL_MS = 50;
+const CLAIM_WAIT_MS = 15_000;
+const DRAIN_EXIT_TIMEOUT_MS = 10_000;
+const ATTEMPTS = 4;
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const daemonEntry = fileURLToPath(new URL("../daemon/main.ts", import.meta.url));
+
+/**
+ * The daemon's `/health`, or null when nothing reviewzy-shaped answers on that port. This is the
+ * authoritative liveness check: the pid and name in its body are what tie a lockfile entry to a
+ * process that is really ours and really serving.
+ */
+export async function fetchHealth(port: number, timeoutMs = 1_500): Promise<Health | null> {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok) return null;
+
+    const body = (await response.json()) as Partial<Health>;
+    if (
+      typeof body.name !== "string" ||
+      typeof body.version !== "string" ||
+      !Number.isInteger(body.pid) ||
+      typeof body.nonce !== "string" ||
+      typeof body.startedAt !== "string"
+    ) {
+      return null;
+    }
+    return body as Health;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Spawns the daemon detached: the shim exits on stdin EOF while the daemon keeps serving, so the
+ * child must never share the shim's life. stderr lands in `daemon.log` beside the lockfile — never
+ * the shim's own stderr, which a stdio client may pipe and which must stay free of daemon noise.
+ */
+export function spawnDetachedDaemon(
+  env: Record<string, string | undefined>,
+  lockPath: string,
+): number {
+  const dataDir = dirname(lockPath);
+  mkdirSync(dataDir, { recursive: true });
+  const logFd = openSync(join(dataDir, "daemon.log"), "a");
+  const child = spawn(process.execPath, ["run", daemonEntry], {
+    env,
+    detached: true,
+    stdio: ["ignore", "ignore", logFd],
+  });
+  child.unref();
+  if (child.pid === undefined) throw new ShimError("reviewzy: spawning the daemon produced no pid");
+  console.error(`reviewzy: spawned daemon (pid ${child.pid})`);
+  return child.pid;
+}
+
+/**
+ * Waits until the process `childPid` spawned is the one answering /health on the port. Anything
+ * else answering /health with our name (a spoof, or an incumbent daemon that beat the child to the
+ * bind) ends the wait early with null, so the caller's fallback can decide instead of a spoof
+ * riding a dead spawn into the lockfile.
+ */
+async function waitHealthy(port: number, timeoutMs: number, childPid: number): Promise<Health | null> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const health = await fetchHealth(port);
+    if (health !== null && health.name === NAME) {
+      if (health.pid === childPid) return health;
+      return null;
+    }
+    if (Date.now() > deadline) return null;
+    await sleep(HEALTH_POLL_MS);
+  }
+}
+
+/** The daemon a valid lockfile names, when it is alive, ours, and actually serving its port. */
+async function liveDaemon(lockPath: string): Promise<{ lock: Lockfile; health: Health } | null> {
+  const lock = readLockfile(lockPath);
+  if (lock === null) return null;
+  if (!isPidAlive(lock.pid)) return null;
+  if (!isReviewzyProcess(lock.pid)) return null;
+
+  const health = await fetchHealth(lock.port);
+  if (health === null || health.name !== NAME || health.pid !== lock.pid) return null;
+  // The boot nonce ties this lockfile to the one boot it recorded: a port answered by another
+  // process (or another boot's daemon) fails here, and a cross-user spoof cannot read the
+  // lockfile to echo the value.
+  if (health.nonce !== lock.nonce) return null;
+  return { lock, health };
+}
+
+/**
+ * Asks a running daemon to drain and waits out its exit. The daemon's exit frees the port, so a new
+ * daemon cannot be started before this returns without stealing the old one's port out from under
+ * in-flight requests.
+ */
+async function drainAndAwaitExit(lock: Lockfile, token: string | undefined): Promise<void> {
+  const headers: Record<string, string> = {};
+  if (token !== undefined) headers.authorization = `Bearer ${token}`;
+
+  let response: Response;
+  try {
+    response = await fetch(`http://127.0.0.1:${lock.port}/drain`, {
+      method: "POST",
+      headers,
+      signal: AbortSignal.timeout(2_000),
+    });
+  } catch (error) {
+    throw new ShimError(
+      `reviewzy: could not ask daemon pid ${lock.pid} to drain: ${(error as Error).message}`,
+    );
+  }
+  if (response.status !== 200) {
+    throw new ShimError(`reviewzy: daemon pid ${lock.pid} refused /drain with http ${response.status}`);
+  }
+
+  const deadline = Date.now() + DRAIN_EXIT_TIMEOUT_MS;
+  while (isPidAlive(lock.pid)) {
+    if (Date.now() > deadline) {
+      throw new ShimError(
+        `reviewzy: daemon pid ${lock.pid} did not exit within ${DRAIN_EXIT_TIMEOUT_MS}ms of draining`,
+      );
+    }
+    await sleep(HEALTH_POLL_MS);
+  }
+}
+
+/**
+ * Waits for the claim to clear, sweeping it when its holder died mid-spawn (a shim killed between
+ * acquiring and releasing would otherwise lock every future session out).
+ */
+async function waitForClaimRelease(lockPath: string): Promise<boolean> {
+  const claim = `${lockPath}.claim`;
+  const deadline = Date.now() + CLAIM_WAIT_MS;
+  while (Date.now() < deadline) {
+    if (!existsSync(claim)) return true;
+    if (claimHolderIsDead(lockPath)) {
+      try {
+        rmSync(claim);
+      } catch {
+        // Another waiter swept it first; the existsSync above re-decides.
+      }
+      if (!existsSync(claim)) return true;
+    }
+    await sleep(CLAIM_POLL_MS);
+  }
+  return false;
+}
+
+export type EnsureDaemonOptions = {
+  lockfile: string;
+  /** The configured `REVIEWZY_PORT`: the port the daemon is spawned on and health-checked against. */
+  port: number;
+  /** The shim's own package version, compared semantically against the daemon's `/health` version. */
+  shimVersion: string;
+  /** The bearer token for `/drain` and `/mcp` when `REVIEWZY_TOKEN` is set. */
+  token?: string | undefined;
+  /** The environment the spawned daemon inherits. */
+  env: Record<string, string | undefined>;
+  /** Overridable spawner, so tests can count spawns. Defaults to the real detached spawn. */
+  spawnDaemon?: ((env: Record<string, string | undefined>, lockPath: string) => number) | undefined;
+};
+
+/**
+ * Returns a live daemon handle, spawning or handshaking a handoff as needed:
+ *
+ * 1. A live, reviewzy-owned daemon named by a valid lockfile is adopted (and drained first, when
+ *    the shim's version semantically outranks the daemon's).
+ * 2. Otherwise, under an exclusive claim, the shim re-checks for a live daemon (another shim may
+ *    have finished while this one waited), spawns the daemon detached, waits for `/health`, and
+ *    writes the lockfile from the health body — so the recorded pid is always the process that is
+ *    actually serving, even when a racing spawn lost the port bind and its child died.
+ */
+export async function ensureDaemon(options: EnsureDaemonOptions): Promise<DaemonHandle> {
+  const spawnDaemon = options.spawnDaemon ?? spawnDetachedDaemon;
+
+  for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+    const live = await liveDaemon(options.lockfile);
+    if (live !== null) {
+      const rank = compareSemver(options.shimVersion, live.health.version);
+      if (rank !== null && rank > 0) {
+        console.error(
+          `reviewzy: shim ${options.shimVersion} outranks daemon ${live.health.version}; draining pid ${live.health.pid}`,
+        );
+        await drainAndAwaitExit(live.lock, options.token);
+        // Falls through to the spawn phase; the drained daemon is gone and cannot be adopted.
+      } else {
+        return { pid: live.health.pid, port: live.lock.port, version: live.health.version };
+      }
+    }
+
+    if (!acquireClaim(options.lockfile)) {
+      const cleared = await waitForClaimRelease(options.lockfile);
+      if (!cleared) continue;
+      // The winner may have finished while we waited; the next loop adopts its daemon, or retries.
+      continue;
+    }
+
+    try {
+      // Re-check under the claim: another shim can have completed between our first read and here.
+      const raced = await liveDaemon(options.lockfile);
+      if (raced !== null) {
+        // The same version rung the adopt path applies: a raced daemon was fully booted before the
+        // winning shim released the claim (release follows the health wait), so draining it here
+        // cannot interrupt a boot.
+        const rank = compareSemver(options.shimVersion, raced.health.version);
+        if (rank !== null && rank > 0) {
+          console.error(
+            `reviewzy: shim ${options.shimVersion} outranks raced daemon ${raced.health.version}; draining pid ${raced.health.pid}`,
+          );
+          await drainAndAwaitExit(raced.lock, options.token);
+          // Falls through to the spawn phase; the claim is already ours.
+        } else {
+          return { pid: raced.health.pid, port: raced.lock.port, version: raced.health.version };
+        }
+      }
+
+      const spawnAndVerify = async (): Promise<DaemonHandle> => {
+        const childPid = spawnDaemon(options.env, options.lockfile);
+        const health = await waitHealthy(options.port, HEALTH_BOOT_TIMEOUT_MS, childPid);
+        if (health !== null) {
+          writeLockfileAtomic(options.lockfile, {
+            pid: health.pid,
+            port: options.port,
+            version: health.version,
+            nonce: health.nonce,
+          });
+          console.error(`reviewzy: daemon ${health.version} ready (pid ${health.pid}, port ${options.port})`);
+          return { pid: health.pid, port: options.port, version: health.version };
+        }
+
+        // The child is not the process answering the port, and it is ours. Kill it HERE, before any
+        // branch can leave it behind: left booting, it binds the port the moment the blocker leaves
+        // it and orphans itself — on the adoption branch nobody ever reclaims it, and on the drain
+        // branch it becomes the thief the drain then has to drain.
+        if (isPidAlive(childPid)) {
+          try {
+            process.kill(childPid, "SIGKILL");
+          } catch {
+            // Already gone between the check and the kill.
+          }
+        }
+
+        // Either the bind was lost to an incumbent daemon the (missing or corrupt) lockfile never
+        // named, or the child died on its own and a spoof or foreign process is answering. Only a
+        // real reviewzy daemon gets the incumbent treatment — the same version rung the adopt path
+        // applies, so a newer shim still drains it instead of bridging to an old daemon all session.
+        const incumbent = await fetchHealth(options.port);
+        if (
+          incumbent !== null &&
+          incumbent.name === NAME &&
+          isReviewzyProcess(incumbent.pid) &&
+          incumbent.pid !== childPid
+        ) {
+          const incumbentLock = {
+            pid: incumbent.pid,
+            port: options.port,
+            version: incumbent.version,
+            nonce: incumbent.nonce,
+          };
+          const rank = compareSemver(options.shimVersion, incumbent.version);
+          if (rank !== null && rank > 0) {
+            console.error(
+              `reviewzy: shim ${options.shimVersion} outranks incumbent daemon ${incumbent.version}; draining pid ${incumbent.pid}`,
+            );
+            await drainAndAwaitExit(incumbentLock, options.token);
+            return spawnAndVerify();
+          }
+          writeLockfileAtomic(options.lockfile, incumbentLock);
+          console.error(`reviewzy: adopted daemon ${incumbent.version} (pid ${incumbent.pid}, port ${options.port})`);
+          return { pid: incumbent.pid, port: options.port, version: incumbent.version };
+        }
+
+        throw new ShimError(
+          `reviewzy: the spawned daemon never answered /health on port ${options.port} within ${HEALTH_BOOT_TIMEOUT_MS}ms (see daemon.log beside the lockfile)`,
+        );
+      };
+      return await spawnAndVerify();
+    } finally {
+      releaseClaim(options.lockfile);
+    }
+  }
+
+  throw new ShimError(
+    `reviewzy: could not establish a daemon on port ${options.port} after ${ATTEMPTS} attempts`,
+  );
+}

package/src/shim/lockfile.ts

@@ -0,0 +1,153 @@
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, writeSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export type Lockfile = { pid: number; port: number; version: string; nonce: string };
+
+/**
+ * The lockfile lives in the directory the db DEFAULTS to (`docs/design.md` lifecycle row), not
+ * wherever `REVIEWZY_DB` points: the daemon's discovery point must stay fixed even when an operator
+ * relocates the store, or two shims with different dbs would hunt two different lockfiles and both
+ * spawn. Mirrors `defaultDbPath` in `src/config.ts`.
+ */
+export function lockfilePath(env: Record<string, string | undefined>): string {
+  const dataRoot = env.XDG_DATA_HOME ?? join(env.HOME ?? homedir(), ".local", "share");
+  return join(dataRoot, "reviewzy", "daemon.lock");
+}
+
+/**
+ * Reads and validates the lockfile. Anything wrong reads as null (stale): a missing file, a
+ * corrupt body, or a shape missing `pid`/`port`/`version`. Staleness of a WELL-FORMED lockfile is
+ * decided by the caller from pid liveness, process identity, and `/health`.
+ */
+export function readLockfile(path: string): Lockfile | null {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+
+  const { pid, port, version, nonce } = parsed as Record<string, unknown>;
+  if (!Number.isInteger(pid) || (pid as number) <= 0) return null;
+  if (!Number.isInteger(port) || (port as number) < 1 || (port as number) > 65535) return null;
+  if (typeof version !== "string") return null;
+  // The nonce ties the lockfile to one daemon boot: adoption requires /health to carry it.
+  if (typeof nonce !== "string") return null;
+  return { pid: pid as number, port: port as number, version: version as string, nonce: nonce as string };
+}
+
+/**
+ * Writes via `rename(2)` from a per-pid temp file in the same directory, so a reader never sees a
+ * half-written lockfile and two racing writers each atomically land a complete document. Both
+ * writers derive their content from the daemon's own `/health`, so whichever rename lands last,
+ * the file names a daemon that is really serving.
+ */
+export function writeLockfileAtomic(path: string, lock: Lockfile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(lock)}\n`);
+  renameSync(temp, path);
+}
+
+/**
+ * `kill(pid, 0)` probes without signalling. `EPERM` means the process exists but belongs to
+ * another user: alive, which is the only question here.
+ */
+export function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** The real uid `/proc/<pid>/status` reports, or null when the file is unreadable. */
+export function processUid(pid: number): number | null {
+  try {
+    const match = /^Uid:\s*(\d+)/m.exec(readFileSync(`/proc/${pid}/status`, "utf8"));
+    return match === null ? null : Number(match[1]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Answers "could this pid be OUR daemon". The daemon's argv always embeds its entry path, and this
+ * matches the entry path's tail `/src/daemon/main.ts`, never the checkout dir's name: a renamed
+ * checkout and the npm layout (`node_modules/reviewzy/src/daemon/main.ts`) both match, while a
+ * process that merely mentions "reviewzy" in its argv (an editor with this repo open) is still
+ * foreign. An unreadable cmdline (no `/proc`, or the process vanished mid-read) reads as "could be
+ * ours": the caller's `/health` check is the authoritative decision, and refusing here would drain
+ * a healthy daemon on a probe hiccup.
+ */
+export function isReviewzyProcess(pid: number): boolean {
+  let cmdline: string;
+  try {
+    cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
+  } catch {
+    return true;
+  }
+  if (!cmdline.includes("/src/daemon/main.ts")) return false;
+
+  // Cross-user defence: another local user can bind 127.0.0.1 and craft argv embedding the entry
+  // path, and a spoof adopted on the lockfile-less incumbent path would receive the shim's bearer
+  // token on /mcp. The daemon always runs as the shim's user, so a different uid is never ours.
+  // An unreadable status keeps the cmdline verdict.
+  const uid = processUid(pid);
+  const ownUid = process.getuid?.();
+  if (uid !== null && ownUid !== undefined && uid !== ownUid) return false;
+  return true;
+}
+
+/**
+ * One shim may spawn the daemon at a time, enforced by an exclusively-created claim file beside the
+ * lockfile. `O_EXCL` is the whole mutex: no advisory locks to leak, and a crashed claimer is
+ * detected by the pid it wrote into the claim.
+ */
+export function acquireClaim(lockPath: string): boolean {
+  const claim = `${lockPath}.claim`;
+  // The claim is the FIRST thing a fresh install ever writes here: no lockfile has created the
+  // directory yet, so the claim creates it.
+  mkdirSync(dirname(lockPath), { recursive: true });
+  try {
+    const fd = openSync(claim, "wx");
+    try {
+      writeSync(fd, String(process.pid));
+    } finally {
+      closeSync(fd);
+    }
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+    throw error;
+  }
+}
+
+export function releaseClaim(lockPath: string): void {
+  rmSync(`${lockPath}.claim`, { force: true });
+}
+
+/**
+ * True when the claim is safe to sweep: the shim that created it is gone, OR its content is
+ * unparseable. A holder killed between `openSync(claim, "wx")` and `writeSync` leaves an empty or
+ * partial file, and reading that as "still held" would wedge every future shim permanently.
+ */
+export function claimHolderIsDead(lockPath: string): boolean {
+  try {
+    const pid = Number.parseInt(readFileSync(`${lockPath}.claim`, "utf8").trim(), 10);
+    if (Number.isNaN(pid)) return true;
+    return !isPidAlive(pid);
+  } catch {
+    return false;
+  }
+}