@yoavsh/treekeeper 0.0.0-stage → 0.1.0

package/src/core/render.ts

@@ -0,0 +1,168 @@
+import type { ApplyResult } from "./apply.js";
+import type { Plan, RepoPlan, WorktreeCandidate } from "./plan.js";
+import { formatKb } from "../util/bytes.js";
+import { color, padEndVisible, visibleWidth } from "../util/color.js";
+import { shortenPath } from "../util/paths.js";
+
+export interface RenderOptions {
+  /** Show kept worktrees too (default: only when there are few). */
+  verbose?: boolean;
+  /** Only the summary line. */
+  quiet?: boolean;
+}
+
+/** The human-readable plan. */
+export function renderPlan(plan: Plan, opts: RenderOptions = {}): string {
+  const out: string[] = [];
+  if (opts.quiet) return summaryLine(plan);
+
+  for (const repo of plan.repos) {
+    const block = renderRepo(repo, opts);
+    if (block.length > 0) {
+      out.push(...block, "");
+    }
+  }
+
+  for (const warning of plan.warnings) {
+    out.push(color.yellow(`note  ${warning}`));
+  }
+  if (plan.warnings.length > 0) out.push("");
+
+  out.push(summaryLine(plan));
+  return out.join("\n");
+}
+
+function renderRepo(repo: RepoPlan, opts: RenderOptions): string[] {
+  if (repo.skipped) {
+    return opts.verbose ? [`${color.bold(repo.name)}  ${color.gray(`skipped — ${repo.skipped}`)}`] : [];
+  }
+
+  const reclaim = repo.worktrees.filter((w) => w.verdict.action === "reclaim");
+  const kept = repo.worktrees.filter(
+    (w) => w.verdict.action === "keep" && w.verdict.code !== "main-worktree",
+  );
+  const showKept = opts.verbose ? kept : [];
+
+  if (reclaim.length === 0 && showKept.length === 0 && repo.branches.length === 0) return [];
+
+  const rows: Array<[string, string, string, string, string]> = [];
+  for (const w of reclaim) rows.push(row(w, true));
+  for (const w of showKept) rows.push(row(w, false));
+
+  const widths = [0, 0, 0, 0];
+  for (const r of rows) {
+    for (let i = 0; i < 4; i += 1) {
+      widths[i] = Math.max(widths[i]!, visibleWidth(r[i]!));
+    }
+  }
+
+  const head = `${color.bold(repo.name)} ${color.gray(`(${repo.defaultBranch})`)}${
+    repo.forgeAvailable ? "" : color.gray(" [no PR data]")
+  }`;
+  const lines = [head];
+
+  for (const r of rows) {
+    const cells = [
+      padEndVisible(r[0]!, widths[0]!),
+      padEndVisible(r[1]!, widths[1]!),
+      padEndVisible(r[2]!, widths[2]!),
+      padEndVisible(r[3]!, widths[3]!),
+      r[4]!,
+    ];
+    lines.push(`  ${cells.join("  ").trimEnd()}`);
+  }
+
+  if (repo.branches.length > 0) {
+    const names = repo.branches.map((b) => b.name);
+    const shown = names.slice(0, 6).join(" ");
+    const more = names.length > 6 ? color.gray(` +${names.length - 6} more`) : "";
+    lines.push(
+      `  ${color.red("DELETE")}  ${names.length} merged branch${names.length === 1 ? "" : "es"}: ${color.gray(shown)}${more}`,
+    );
+  }
+
+  return lines;
+}
+
+function row(w: WorktreeCandidate, reclaim: boolean): [string, string, string, string, string] {
+  const action = reclaim ? color.red("RECLAIM") : color.gray("keep   ");
+  const path = reclaim ? shortenPath(w.path) : color.gray(shortenPath(w.path));
+  const branch = w.branch ? color.cyan(`[${w.branch}]`) : color.gray("[detached]");
+  const size = w.sizeKb === null ? "" : (reclaim ? color.yellow(formatKb(w.sizeKb)) : color.gray(formatKb(w.sizeKb)));
+  const risks = w.verdict.risks.length > 0 ? color.yellow(` (${w.verdict.risks.join(", ")})`) : "";
+  const reason = (reclaim ? color.gray(w.verdict.reason) : color.gray(w.verdict.reason)) + risks;
+  return [action, path, branch, size, reason];
+}
+
+export function summaryLine(plan: Plan): string {
+  const s = plan.summary;
+  if (s.worktreesReclaimable === 0 && s.branchesDeletable === 0) {
+    return color.green(
+      `nothing to clean — ${s.worktreesScanned} worktree${s.worktreesScanned === 1 ? "" : "s"} across ${s.repos} repo${s.repos === 1 ? "" : "s"} all still in play`,
+    );
+  }
+  return [
+    `would reclaim ${color.bold(String(s.worktreesReclaimable))} worktree${s.worktreesReclaimable === 1 ? "" : "s"}`,
+    `(${color.bold(formatKb(s.reclaimKb))})`,
+    `and delete ${color.bold(String(s.branchesDeletable))} branch${s.branchesDeletable === 1 ? "" : "es"}`,
+    color.gray(`· ${s.worktreesKept} kept`),
+  ].join(" ");
+}
+
+/** What actually happened, after `--apply`. */
+export function renderApply(result: ApplyResult, plan: Plan): string {
+  const out: string[] = [];
+
+  for (const r of result.removedWorktrees) {
+    const parts = [
+      color.green("reclaimed"),
+      shortenPath(r.path),
+      r.branch ? color.cyan(`[${r.branch}]`) : "",
+      color.yellow(formatKb(r.sizeKb)),
+      color.gray(`— ${r.reason}`),
+    ].filter((p) => p !== "");
+    out.push(parts.join("  "));
+  }
+
+  const branchOnly = result.deletedBranches.filter(
+    (b) => !result.removedWorktrees.some((w) => w.branch === b.name && w.repo === b.repo),
+  );
+  if (branchOnly.length > 0) {
+    out.push(
+      `${color.green("deleted")}  ${branchOnly.length} branch${branchOnly.length === 1 ? "" : "es"} ${color.gray(
+        branchOnly.slice(0, 8).map((b) => b.name).join(" "),
+      )}`,
+    );
+  }
+
+  const archived = result.archives.filter((a) => a.bundle || a.patch || a.untracked);
+  if (archived.length > 0) {
+    out.push("");
+    out.push(color.gray(`archived unique work from ${archived.length} of them:`));
+    for (const a of archived.slice(0, 10)) {
+      const bits = [
+        a.bundle ? `${a.bundle.commits} commit${a.bundle.commits === 1 ? "" : "s"}` : null,
+        a.patch ? "uncommitted diff" : null,
+        a.untracked ? `${a.untracked.count} untracked` : null,
+      ].filter(Boolean);
+      out.push(color.gray(`  ${shortenPath(a.dir)}  (${bits.join(", ")})`));
+    }
+  }
+
+  for (const f of result.failures) {
+    out.push(color.yellow(`kept  ${shortenPath(f.target)} — ${f.message}`));
+  }
+
+  if (out.length > 0) out.push("");
+
+  const nothing = result.removedWorktrees.length === 0 && result.deletedBranches.length === 0;
+  out.push(
+    nothing
+      ? color.green("nothing to clean")
+      : `${color.bold("reclaimed")} ${formatKb(result.reclaimedKb)} · ` +
+        `${result.removedWorktrees.length} worktree${result.removedWorktrees.length === 1 ? "" : "s"}, ` +
+        `${result.deletedBranches.length} branch${result.deletedBranches.length === 1 ? "" : "es"} · ` +
+        color.gray(`${plan.summary.worktreesKept} kept`),
+  );
+  return out.join("\n");
+}

package/src/core/scan.ts

@@ -0,0 +1,105 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { isGitRepo, mainRepoPath } from "./git.js";
+import { isInside, matchAnyGlob } from "../util/paths.js";
+import type { Logger } from "../util/log.js";
+
+/** Directories never worth descending into when hunting for repos. */
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", ".svn", ".hg", "vendor", "target", "dist", "build",
+  ".next", ".nuxt", ".venv", "venv", "__pycache__", ".cache", ".pnpm-store",
+  "Library", "Applications", ".Trash", ".cargo", ".rustup", ".gradle", ".m2",
+]);
+
+export interface ScanOptions {
+  roots: string[];
+  maxDepth: number;
+  protectPaths?: string[];
+  logger?: Logger;
+}
+
+/**
+ * Find the main worktree of every git repo under `roots`.
+ *
+ * A linked worktree found during the walk resolves to its parent clone, so a
+ * repo is discovered whether the root holds the clone, the worktrees, or both.
+ */
+export async function discoverRepos(opts: ScanOptions): Promise<string[]> {
+  const found = new Set<string>();
+  const seen = new Set<string>();
+
+  const walk = async (dir: string, depth: number): Promise<void> => {
+    if (seen.has(dir)) return;
+    seen.add(dir);
+    if (opts.protectPaths && matchAnyGlob(opts.protectPaths, dir)) return;
+
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "EACCES" && code !== "ENOTDIR" && code !== "EPERM") {
+        opts.logger?.debug(`scan: cannot read ${dir}: ${(err as Error).message}`);
+      }
+      return;
+    }
+
+    const hasGit = entries.some((e) => e.name === ".git");
+    if (hasGit) {
+      const main = await mainRepoPath(dir);
+      if (main) {
+        found.add(main);
+        // Stop here: `git worktree list` from the main repo enumerates the rest,
+        // and nested repos inside a checkout are not ours to garbage-collect.
+        return;
+      }
+    }
+
+    if (depth >= opts.maxDepth) return;
+    for (const entry of entries) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+      if (entry.name.startsWith(".") && entry.name !== ".worktrees") continue;
+      if (SKIP_DIRS.has(entry.name)) continue;
+      const child = join(dir, entry.name);
+      if (entry.isSymbolicLink()) {
+        // Follow a symlinked root one level, but never let a loop trap the walk.
+        try {
+          const st = await stat(child);
+          if (!st.isDirectory()) continue;
+        } catch {
+          continue;
+        }
+      }
+      await walk(child, depth + 1);
+    }
+  };
+
+  for (const root of opts.roots) {
+    await walk(root, 0);
+  }
+  return [...found].sort();
+}
+
+/**
+ * Resolve the repos implied by explicit CLI paths. A path inside a repo or
+ * worktree resolves to that repo; a plain directory is scanned shallowly.
+ */
+export async function reposFromPaths(paths: string[], opts: Omit<ScanOptions, "roots">): Promise<string[]> {
+  const out = new Set<string>();
+  for (const p of paths) {
+    if (await isGitRepo(p)) {
+      const main = await mainRepoPath(p);
+      if (main) {
+        out.add(main);
+        continue;
+      }
+    }
+    for (const repo of await discoverRepos({ ...opts, roots: [p] })) out.add(repo);
+  }
+  return [...out].sort();
+}
+
+/** True when any root contains the given path — used to sanity-check config. */
+export function underAnyRoot(roots: string[], path: string): boolean {
+  return roots.some((r) => isInside(r, path));
+}

package/src/core/sessions.ts

@@ -0,0 +1,339 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Config, SessionCommand } from "./config.js";
+import { run } from "../util/exec.js";
+import type { Logger } from "../util/log.js";
+import { expandPath, isInside } from "../util/paths.js";
+import { parseDuration } from "../util/time.js";
+
+export interface ActivityHit {
+  /** Which detector saw it: "claude-code", "process", "mtime", … */
+  detector: string;
+  /** Epoch ms of the most recent activity. */
+  lastActivity: number;
+  detail: string;
+}
+
+export interface ActivityContext {
+  now: number;
+  graceMs: number;
+  detectors: Set<string>;
+  extraPaths: string[];
+  commands: SessionCommand[];
+  logger?: Logger;
+  /** Absolute paths that are the cwd of some live process; null when unknown. */
+  processCwds: string[] | null;
+}
+
+/** Directories whose contents say nothing about whether an agent is working. */
+const MTIME_SKIP = new Set([
+  "node_modules", ".git", "dist", "build", "target", ".next", ".nuxt", ".venv",
+  "venv", "__pycache__", ".cache", "coverage", ".turbo", ".pytest_cache",
+  ".gradle", ".mypy_cache", ".ruff_cache", "vendor", ".terraform",
+]);
+
+const MTIME_MAX_ENTRIES = 4_000;
+const MTIME_MAX_DEPTH = 3;
+
+export async function createActivityContext(
+  cfg: Config,
+  logger?: Logger,
+  now = Date.now(),
+): Promise<ActivityContext> {
+  const detectors = new Set(cfg.sessions.detectors);
+  const ctx: ActivityContext = {
+    now,
+    graceMs: parseDuration(cfg.sessions.grace),
+    detectors,
+    extraPaths: cfg.sessions.extraPaths,
+    commands: cfg.sessions.commands,
+    logger,
+    processCwds: null,
+  };
+  if (detectors.has("process")) {
+    ctx.processCwds = await loadProcessCwds(logger);
+  }
+  return ctx;
+}
+
+/**
+ * Is an agent (or a human) still working in this worktree?
+ *
+ * Detectors are deliberately layered: the harness-specific ones give a precise
+ * answer with a timestamp, while `process` and `mtime` are the catch-all that
+ * makes this work with harnesses treekeeper has never heard of.
+ */
+export async function detectActivity(
+  ctx: ActivityContext,
+  worktreePath: string,
+): Promise<ActivityHit | null> {
+  const cutoff = ctx.now - ctx.graceMs;
+  const hits: ActivityHit[] = [];
+
+  if (ctx.detectors.has("process") && ctx.processCwds) {
+    const match = ctx.processCwds.find((p) => isInside(worktreePath, p));
+    if (match) {
+      hits.push({
+        detector: "process",
+        lastActivity: ctx.now,
+        detail: "a running process is sitting in this directory",
+      });
+    }
+  }
+
+  if (ctx.detectors.has("claude-code")) {
+    const hit = await claudeCodeActivity(worktreePath, cutoff);
+    if (hit) hits.push(hit);
+  }
+  if (ctx.detectors.has("codex")) {
+    const hit = await codexActivity(worktreePath, cutoff, ctx);
+    if (hit) hits.push(hit);
+  }
+  if (ctx.detectors.has("aider")) {
+    const hit = await newestFileIn(
+      worktreePath,
+      [".aider.chat.history.md", ".aider.input.history"],
+      "aider",
+      cutoff,
+    );
+    if (hit) hits.push(hit);
+  }
+  if (ctx.extraPaths.length > 0) {
+    const paths = ctx.extraPaths.map((p) =>
+      expandPath(p.replaceAll("{worktree}", worktreePath)),
+    );
+    const hit = await newestPath(paths, "extra-path", cutoff);
+    if (hit) hits.push(hit);
+  }
+  if (ctx.detectors.has("mtime")) {
+    const hit = await mtimeActivity(worktreePath, cutoff);
+    if (hit) hits.push(hit);
+  }
+
+  for (const cmd of ctx.commands) {
+    const r = await run("sh", ["-c", cmd.command], {
+      timeoutMs: 15_000,
+      env: { ...process.env, TREEKEEPER_WORKTREE: worktreePath },
+      cwd: undefined,
+    });
+    if (r.code === 0) {
+      hits.push({
+        detector: cmd.name,
+        lastActivity: ctx.now,
+        detail: `custom check "${cmd.name}" reported activity`,
+      });
+    }
+  }
+
+  if (hits.length === 0) return null;
+  hits.sort((a, b) => b.lastActivity - a.lastActivity);
+  return hits[0]!;
+}
+
+/** `true` when the hit falls inside the session grace window. */
+export function isActive(ctx: ActivityContext, hit: ActivityHit | null): boolean {
+  if (!hit) return false;
+  return hit.lastActivity >= ctx.now - ctx.graceMs;
+}
+
+// --- harness-specific detectors --------------------------------------------
+
+/**
+ * Claude Code stores one JSONL transcript per session under
+ * `~/.claude/projects/<slugified-cwd>/`, so the newest transcript mtime is the
+ * last time an agent did anything in that worktree.
+ */
+export function claudeProjectSlugs(worktreePath: string): string[] {
+  const all = worktreePath.replace(/[^a-zA-Z0-9]/g, "-");
+  const slashesOnly = worktreePath.replace(/\//g, "-");
+  return all === slashesOnly ? [all] : [all, slashesOnly];
+}
+
+async function claudeCodeActivity(worktreePath: string, cutoff: number): Promise<ActivityHit | null> {
+  const base = process.env.CLAUDE_CONFIG_DIR
+    ? expandPath(process.env.CLAUDE_CONFIG_DIR)
+    : join(homedir(), ".claude");
+  for (const slug of claudeProjectSlugs(worktreePath)) {
+    const dir = join(base, "projects", slug);
+    const hit = await newestInDir(dir, ".jsonl", "claude-code", cutoff);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+/**
+ * Codex CLI writes rollout transcripts under `~/.codex/sessions/<y>/<m>/<d>/`.
+ * Only recently-modified files are opened, and only their head is read, so the
+ * cwd match stays cheap even with thousands of archived sessions.
+ */
+async function codexActivity(
+  worktreePath: string,
+  cutoff: number,
+  ctx: ActivityContext,
+): Promise<ActivityHit | null> {
+  const root = join(homedir(), ".codex", "sessions");
+  const recent: Array<{ path: string; mtime: number }> = [];
+
+  const walk = async (dir: string, depth: number): Promise<void> => {
+    if (depth > 4 || recent.length >= 40) return;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) {
+        await walk(p, depth + 1);
+      } else if (e.isFile() && e.name.endsWith(".jsonl")) {
+        try {
+          const st = await stat(p);
+          if (st.mtimeMs >= cutoff) recent.push({ path: p, mtime: st.mtimeMs });
+        } catch {
+          /* vanished mid-walk */
+        }
+      }
+    }
+  };
+  await walk(root, 0);
+
+  recent.sort((a, b) => b.mtime - a.mtime);
+  for (const file of recent) {
+    try {
+      const handle = await readFile(file.path, "utf8");
+      const head = handle.slice(0, 8_000);
+      if (head.includes(`"cwd":"${worktreePath}"`) || head.includes(`"cwd": "${worktreePath}"`)) {
+        return {
+          detector: "codex",
+          lastActivity: file.mtime,
+          detail: "a Codex session transcript was updated",
+        };
+      }
+    } catch (err) {
+      ctx.logger?.debug(`codex detector: ${(err as Error).message}`);
+    }
+  }
+  return null;
+}
+
+// --- generic detectors ------------------------------------------------------
+
+/**
+ * Last-resort signal that covers every harness: did anything inside the
+ * worktree change recently? Bounded in depth and entry count so a sweep over
+ * dozens of worktrees stays fast.
+ */
+async function mtimeActivity(worktreePath: string, cutoff: number): Promise<ActivityHit | null> {
+  let visited = 0;
+  let newest = 0;
+  let newestPathSeen = "";
+
+  const walk = async (dir: string, depth: number): Promise<boolean> => {
+    if (visited >= MTIME_MAX_ENTRIES) return false;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return false;
+    }
+    for (const e of entries) {
+      if (visited >= MTIME_MAX_ENTRIES) return false;
+      visited += 1;
+      if (MTIME_SKIP.has(e.name)) continue;
+      const p = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (depth < MTIME_MAX_DEPTH && (await walk(p, depth + 1))) return true;
+        continue;
+      }
+      if (!e.isFile()) continue;
+      try {
+        const st = await stat(p);
+        if (st.mtimeMs > newest) {
+          newest = st.mtimeMs;
+          newestPathSeen = e.name;
+        }
+        if (st.mtimeMs >= cutoff) return true; // early exit: already "active"
+      } catch {
+        /* ignore */
+      }
+    }
+    return false;
+  };
+
+  const active = await walk(worktreePath, 0);
+  if (!active && newest < cutoff) return null;
+  return {
+    detector: "mtime",
+    lastActivity: newest,
+    detail: `files changed recently (${newestPathSeen})`,
+  };
+}
+
+async function loadProcessCwds(logger?: Logger): Promise<string[] | null> {
+  if (process.platform === "win32") return null;
+  const r = await run("lsof", ["-d", "cwd", "-Fn"], { timeoutMs: 30_000 });
+  if (r.code !== 0 && r.stdout.trim() === "") {
+    logger?.debug("process detector: lsof unavailable, skipping");
+    return null;
+  }
+  const out = new Set<string>();
+  for (const line of r.stdout.split("\n")) {
+    if (line.startsWith("n/")) out.add(line.slice(1));
+  }
+  return [...out];
+}
+
+async function newestInDir(
+  dir: string,
+  suffix: string,
+  detector: string,
+  cutoff: number,
+): Promise<ActivityHit | null> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  let newest = 0;
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith(suffix)) continue;
+    try {
+      const st = await stat(join(dir, e.name));
+      if (st.mtimeMs > newest) newest = st.mtimeMs;
+    } catch {
+      /* ignore */
+    }
+  }
+  if (newest === 0 || newest < cutoff) return null;
+  return { detector, lastActivity: newest, detail: "a session transcript was updated" };
+}
+
+async function newestFileIn(
+  base: string,
+  names: string[],
+  detector: string,
+  cutoff: number,
+): Promise<ActivityHit | null> {
+  return newestPath(names.map((n) => join(base, n)), detector, cutoff);
+}
+
+async function newestPath(paths: string[], detector: string, cutoff: number): Promise<ActivityHit | null> {
+  let newest = 0;
+  let which = "";
+  for (const p of paths) {
+    try {
+      const st = await stat(p);
+      if (st.mtimeMs > newest) {
+        newest = st.mtimeMs;
+        which = p;
+      }
+    } catch {
+      /* missing is fine */
+    }
+  }
+  if (newest === 0 || newest < cutoff) return null;
+  return { detector, lastActivity: newest, detail: `${which} was updated` };
+}

package/src/core/size.ts

@@ -0,0 +1,10 @@
+import { run } from "../util/exec.js";
+
+/** Disk usage in KB. Uses `du` (fast, counts real blocks); null when unavailable. */
+export async function dirSizeKb(path: string): Promise<number | null> {
+  const r = await run("du", ["-sk", path], { timeoutMs: 120_000 });
+  if (r.code !== 0 && r.stdout.trim() === "") return null;
+  const first = r.stdout.trim().split("\n")[0] ?? "";
+  const kb = Number(first.split(/\s+/)[0]);
+  return Number.isFinite(kb) ? kb : null;
+}

package/src/daemon/lock.ts

@@ -0,0 +1,65 @@
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { treekeeperHome } from "../util/paths.js";
+
+const LOCK = "sweep.lock";
+
+export interface Lock {
+  release(): Promise<void>;
+}
+
+function lockPath(): string {
+  return join(treekeeperHome(), LOCK);
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Take the machine-wide sweep lock, so a scheduled sweep and a manual
+ * `treekeeper gc --apply` can never remove the same worktree twice.
+ * Returns null when another sweep holds it.
+ */
+export async function acquireLock(): Promise<Lock | null> {
+  const path = lockPath();
+  await mkdir(treekeeperHome(), { recursive: true });
+
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      await writeFile(path, JSON.stringify({ pid: process.pid, at: Date.now() }), { flag: "wx" });
+      return {
+        release: async () => {
+          try {
+            await unlink(path);
+          } catch {
+            /* already gone */
+          }
+        },
+      };
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+      // Stale lock from a killed process? Clear it once and retry.
+      let holder: number | null = null;
+      try {
+        const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+        const pid = (parsed as { pid?: unknown }).pid;
+        holder = typeof pid === "number" ? pid : null;
+      } catch {
+        holder = null;
+      }
+      if (holder !== null && alive(holder)) return null;
+      try {
+        await unlink(path);
+      } catch {
+        return null;
+      }
+    }
+  }
+  return null;
+}