@uluops/setup 0.6.5 → 0.8.1

package/dist/lib/config-merger.js

@@ -1,8 +1,39 @@
 import { readFile } from "node:fs/promises";
 import { atomicWrite } from "./atomic-write.js";
 const MCP_PACKAGES = ["@uluops/ops-mcp", "@uluops/registry-mcp"];
+/**
+ * In-process memoization for the npm availability probe.
+ *
+ * Setup runs once per process; with multi-harness installs (or any future
+ * code path that calls installMcp more than once), the probe was firing
+ * redundantly against the npm registry. We cache the in-flight promise so
+ * concurrent callers share a single round-trip and subsequent callers get
+ * the resolved value instantly. Cache lifetime is the process — setup is
+ * one-shot, so a TTL adds state without buying anything.
+ *
+ * `__resetAvailabilityCacheForTesting` exists ONLY for tests that stub
+ * `fetch` per-case. Without a reset, the first test in a file would lock
+ * the cached result for every subsequent test in the same process.
+ */
+let _availabilityCache = null;
+/** Test-only: drop the memoized availability promise so the next call re-probes. */
+export function __resetAvailabilityCacheForTesting() {
+    _availabilityCache = null;
+}
 /** Check whether the UluOps MCP client packages exist on the npm registry. Returns lists of available and missing packages. */
-export async function checkMcpPackageAvailability() {
+export function checkMcpPackageAvailability() {
+    if (_availabilityCache)
+        return _availabilityCache;
+    _availabilityCache = probeAvailability().catch((err) => {
+        // If the probe itself throws unexpectedly (not an individual fetch — those
+        // are caught by Promise.allSettled), drop the cache so retries don't
+        // permanently inherit a poisoned promise.
+        _availabilityCache = null;
+        throw err;
+    });
+    return _availabilityCache;
+}
+async function probeAvailability() {
     const available = [];
     const missing = [];
     const results = await Promise.allSettled(MCP_PACKAGES.map((pkg) => fetch(`https://registry.npmjs.org/${pkg}`, {
@@ -10,16 +41,28 @@ export async function checkMcpPackageAvailability() {
         signal: AbortSignal.timeout(5000),
         redirect: "follow",
     }).then((res) => ({ pkg, ok: res.ok }))));
+    // Per-index correspondence: results[i] corresponds to MCP_PACKAGES[i] by
+    // Promise.allSettled's stable ordering. The previous `?? "unknown"` fallback
+    // could emit a literal "unknown" string into `missing`, hiding the real
+    // failure reason (DNS error, timeout, 404) under an undiagnosable label.
     for (let i = 0; i < results.length; i++) {
         const result = results[i];
-        if (result.status === "fulfilled" && result.value.ok) {
-            available.push(result.value.pkg);
+        const pkg = MCP_PACKAGES[i];
+        if (result.status === "fulfilled") {
+            if (result.value.ok) {
+                available.push(pkg);
+            }
+            else {
+                // Registry returned non-2xx — package likely missing or unpublished.
+                missing.push(pkg);
+            }
         }
         else {
-            const pkg = result.status === "fulfilled"
-                ? result.value.pkg
-                : MCP_PACKAGES[i] ?? "unknown";
-            missing.push(pkg);
+            // Network failure: AbortError (timeout), DNS, TLS, EAI_AGAIN, etc.
+            const reason = result.reason instanceof Error
+                ? result.reason.message
+                : String(result.reason);
+            missing.push(`${pkg} (network: ${reason})`);
         }
     }
     return { available, missing };

package/dist/lib/display.d.ts

@@ -1,13 +1,29 @@
-import type { HarnessProfile } from "../harnesses/index.js";
+import type { PerHarnessResult } from "../commands/per-harness.js";
 declare const ok: (msg: string) => void;
 declare const warn: (msg: string) => void;
 declare const fail: (msg: string) => void;
 declare const info: (msg: string) => void;
 export { ok, warn, fail, info };
-export declare function printSetupSummary(opts: {
-    profile: HarnessProfile;
-    agentCount: number;
-    commandCount: number;
+/**
+ * Render the final post-run summary.
+ *
+ * Single-harness: preserves today's banner format (Setup complete!
+ * + agent list + restart instruction) — regression baseline.
+ *
+ * Multi-harness: aggregate header line, per-harness section block with
+ * status icons + counts + re-run hints, single API-key reminder, single
+ * restart instruction naming each successfully-installed harness.
+ *
+ * Status rendering:
+ *   ok       — ✓ green     installed (counts)
+ *   ok+files-failed — same line, the per-step warn()s already surfaced
+ *                     the failed files during install (not re-printed)
+ *   failed (partial) — ⚠ yellow  partial — failed at "<step>"; re-run hint
+ *   failed (pre-MCP)— ✗ red     failed — <error>; re-run hint
+ *   declined — ⊘ dim       skipped — user declined conflict prompt
+ */
+export declare function printSetupSummary(input: {
+    results: PerHarnessResult[];
     apiKey: string;
 }): Promise<void>;
 export declare function maskKey(key: string): string;

package/dist/lib/display.js

@@ -5,30 +5,135 @@ const warn = (msg) => console.log(`  ${chalk.yellow("⚠")} ${msg}`);
 const fail = (msg) => console.log(`  ${chalk.red("✗")} ${msg}`);
 const info = (msg) => console.log(`  ${msg}`);
 export { ok, warn, fail, info };
-export async function printSetupSummary(opts) {
+const DIVIDER = `  ${chalk.dim("━".repeat(46))}`;
+/**
+ * Render the final post-run summary.
+ *
+ * Single-harness: preserves today's banner format (Setup complete!
+ * + agent list + restart instruction) — regression baseline.
+ *
+ * Multi-harness: aggregate header line, per-harness section block with
+ * status icons + counts + re-run hints, single API-key reminder, single
+ * restart instruction naming each successfully-installed harness.
+ *
+ * Status rendering:
+ *   ok       — ✓ green     installed (counts)
+ *   ok+files-failed — same line, the per-step warn()s already surfaced
+ *                     the failed files during install (not re-printed)
+ *   failed (partial) — ⚠ yellow  partial — failed at "<step>"; re-run hint
+ *   failed (pre-MCP)— ✗ red     failed — <error>; re-run hint
+ *   declined — ⊘ dim       skipped — user declined conflict prompt
+ */
+export async function printSetupSummary(input) {
+    const { results, apiKey } = input;
+    if (results.length === 0) {
+        // runSetup's empty-list branch already printed "nothing to install"
+        // and returned; this is defense-in-depth so the summary never crashes
+        // on an empty input.
+        return;
+    }
     console.log();
-    console.log(`  ${chalk.dim("━".repeat(46))}`);
+    console.log(DIVIDER);
     console.log();
-    const parts = [`${opts.agentCount} agents`];
-    if (opts.commandCount > 0)
-        parts.push(`${opts.commandCount} slash commands`);
-    if (opts.profile.hooks)
-        parts.push("metrics");
-    console.log(`  ${chalk.bold("Setup complete!")} ${chalk.dim(`(${opts.profile.displayName})`)} ${parts.join(" · ")}`);
+    const installed = results.filter((r) => r.status === "ok").length;
+    const failed = results.filter((r) => r.status === "failed").length;
+    const declined = results.filter((r) => r.status === "declined").length;
+    const total = results.length;
+    // Header
+    if (total === 1) {
+        const only = results[0];
+        if (only.status === "ok") {
+            console.log(`  ${chalk.bold("Setup complete!")} ${chalk.dim(`(${only.profile.displayName})`)} ${renderCounts(only)}`);
+        }
+        else if (only.status === "declined") {
+            console.log(`  ${chalk.bold("Setup skipped")} ${chalk.dim(`(${only.profile.displayName})`)} — you declined the conflict prompt`);
+        }
+        else {
+            console.log(`  ${chalk.red.bold("Setup failed")} ${chalk.dim(`(${only.profile.displayName})`)} — ${only.error ?? "see output above"}`);
+        }
+    }
+    else {
+        const summaryParts = [`${installed} installed`];
+        if (failed > 0)
+            summaryParts.push(`${failed} failed`);
+        if (declined > 0)
+            summaryParts.push(`${declined} declined`);
+        const allOk = failed === 0 && declined === 0;
+        const headerLabel = allOk ? "Setup complete:" : "Setup finished:";
+        console.log(`  ${chalk.bold(headerLabel)} ${summaryParts.join(", ")} of ${total} harnesses`);
+        console.log();
+        for (const r of results) {
+            printHarnessLine(r);
+        }
+    }
     console.log();
-    if (opts.profile.name === "claude-code") {
+    // Agent list — only for single-harness claude-code success (the bulk of
+    // single-harness installs). Multi-harness summaries omit it: it's long
+    // and per-claude-code, and the multi-harness reader is more interested
+    // in the per-harness status block than the agent catalog.
+    if (total === 1 &&
+        results[0].status === "ok" &&
+        results[0].profile.name === "claude-code") {
         await printAgentList();
     }
-    const masked = maskKey(opts.apiKey);
+    // API-key reminder — once per run regardless of harness count.
+    const masked = maskKey(apiKey);
     info("For SDK/CLI usage, add to your shell profile:");
     info(`  ${chalk.cyan(`export ULUOPS_API_KEY="${masked}"`)}`);
     console.log();
     info(`Run again to update: ${chalk.cyan("npx @uluops/setup")}`);
     console.log();
-    console.log(`  ${chalk.dim("━".repeat(46))}`);
-    console.log();
-    console.log(`  ${chalk.yellow.bold(`Restart ${opts.profile.displayName} to load agents.`)}`);
+    console.log(DIVIDER);
     console.log();
+    // Restart instruction — names each successfully-installed harness so
+    // the user knows what to restart. Suppressed entirely when nothing
+    // installed (all declined / all failed pre-MCP) — there's nothing to
+    // restart.
+    const restartTargets = results.filter((r) => r.status === "ok");
+    if (restartTargets.length > 0) {
+        const names = restartTargets.map((r) => r.profile.displayName).join(", ");
+        const verb = restartTargets.length === 1 ? "Restart" : "Restart each of";
+        console.log(`  ${chalk.yellow.bold(`${verb} ${names} to load agents.`)}`);
+        console.log();
+    }
+}
+function printHarnessLine(r) {
+    const label = chalk.bold(`[${r.profile.displayName}]`);
+    switch (r.status) {
+        case "ok": {
+            const counts = renderCounts(r);
+            console.log(`  ${chalk.green("✓")} ${label} installed ${counts}`);
+            return;
+        }
+        case "failed": {
+            if (r.partial) {
+                console.log(`  ${chalk.yellow("⚠")} ${label} partial — failed at "${r.partial}"${r.error ? `: ${r.error}` : ""}`);
+            }
+            else {
+                console.log(`  ${chalk.red("✗")} ${label} failed — ${r.error ?? "see output above"}`);
+            }
+            console.log(`     ${chalk.dim(`Re-run: npx @uluops/setup --harness ${r.harnessName}`)}`);
+            return;
+        }
+        case "declined":
+            console.log(`  ${chalk.dim("⊘")} ${label} skipped — user declined conflict prompt`);
+            return;
+    }
+}
+function renderCounts(r) {
+    const parts = [];
+    const agents = r.agentsResult?.files.length ?? 0;
+    const commands = r.commandsResult?.files.length ?? 0;
+    const skills = r.skillsResult?.files.length ?? 0;
+    if (agents > 0)
+        parts.push(`${agents} agents`);
+    if (commands > 0)
+        parts.push(`${commands} commands`);
+    if (skills > 0)
+        parts.push(`${skills} skills`);
+    if (r.metricsResult?.hookConfigured)
+        parts.push("metrics");
+    return parts.length > 0 ? `(${parts.join(" · ")})` : "";
 }
 export function maskKey(key) {
     if (!key || key.length <= 4)

package/dist/lib/file-ops.d.ts

@@ -11,6 +11,19 @@ export declare function writeIfChanged(destPath: string, content: string, dryRun
  * Remove files from a directory. Returns count of successfully removed files.
  */
 export declare function unlinkFiles(dir: string, files: string[]): Promise<number>;
+/**
+ * Reconcile a manifest's old file list against the current source set,
+ * unlinking the files that were installed previously but are no longer in
+ * the source. Returns the count of files that would have been removed
+ * (whether or not the unlink actually ran in dry-run mode).
+ *
+ * Extracted from three near-identical blocks in syncAssets, installAgents,
+ * and installCommands. Errors from unlink are swallowed silently — the
+ * "already gone" case is the dominant one (idempotent re-run, manual user
+ * deletion, prior failed install), and there's no recovery the caller
+ * can usefully perform mid-loop.
+ */
+export declare function removeStaleFiles(destDir: string, oldManifestFiles: string[] | undefined, currentFiles: string[], dryRun: boolean): Promise<number>;
 /**
  * Ensure a directory exists, then copy matching .md files using hash comparison.
  * Returns list of copied files, skipped count, and removed count (for old manifest entries).
@@ -27,8 +40,3 @@ export declare function syncAssets(opts: {
     removed: number;
     files: string[];
 }>;
-/**
- * Back up a file to the UluOps backup directory before modifying it.
- * No-op if the source file doesn't exist.
- */
-export declare function backupFile(srcPath: string, backupDir: string): Promise<void>;

package/dist/lib/file-ops.js

@@ -1,5 +1,5 @@
-import { readFile, writeFile, mkdir, unlink, access, copyFile, readdir } from "node:fs/promises";
-import { join, basename } from "node:path";
+import { readFile, writeFile, mkdir, unlink, readdir } from "node:fs/promises";
+import { join } from "node:path";
 import { fileHash } from "./hash.js";
 /**
  * Copy a file if its content has changed (hash comparison). Returns "copied" or "skipped".
@@ -57,6 +57,37 @@ export async function unlinkFiles(dir, files) {
     }
     return removed;
 }
+/**
+ * Reconcile a manifest's old file list against the current source set,
+ * unlinking the files that were installed previously but are no longer in
+ * the source. Returns the count of files that would have been removed
+ * (whether or not the unlink actually ran in dry-run mode).
+ *
+ * Extracted from three near-identical blocks in syncAssets, installAgents,
+ * and installCommands. Errors from unlink are swallowed silently — the
+ * "already gone" case is the dominant one (idempotent re-run, manual user
+ * deletion, prior failed install), and there's no recovery the caller
+ * can usefully perform mid-loop.
+ */
+export async function removeStaleFiles(destDir, oldManifestFiles, currentFiles, dryRun) {
+    if (!oldManifestFiles)
+        return 0;
+    let removed = 0;
+    for (const oldFile of oldManifestFiles) {
+        if (!currentFiles.includes(oldFile)) {
+            if (!dryRun) {
+                try {
+                    await unlink(join(destDir, oldFile));
+                }
+                catch {
+                    // Already gone
+                }
+            }
+            removed++;
+        }
+    }
+    return removed;
+}
 /**
  * Ensure a directory exists, then copy matching .md files using hash comparison.
  * Returns list of copied files, skipped count, and removed count (for old manifest entries).
@@ -83,40 +114,9 @@ export async function syncAssets(opts) {
         }
     }
     // Remove files that were in the old manifest but no longer in the package
-    let removed = 0;
-    if (opts.oldManifestFiles) {
-        for (const oldFile of opts.oldManifestFiles) {
-            if (!assetFiles.includes(oldFile)) {
-                if (!opts.dryRun) {
-                    try {
-                        await unlink(join(opts.destDir, oldFile));
-                    }
-                    catch {
-                        // Already gone
-                    }
-                }
-                removed++;
-            }
-        }
-    }
+    const removed = await removeStaleFiles(opts.destDir, opts.oldManifestFiles, assetFiles, opts.dryRun);
     if (errors.length > 0) {
         throw new Error(`Failed to copy ${errors.length} file(s):\n  ${errors.join("\n  ")}`);
     }
     return { copied, skipped, removed, files: assetFiles };
 }
-/**
- * Back up a file to the UluOps backup directory before modifying it.
- * No-op if the source file doesn't exist.
- */
-export async function backupFile(srcPath, backupDir) {
-    try {
-        await access(srcPath);
-    }
-    catch {
-        return; // Nothing to back up
-    }
-    await mkdir(backupDir, { recursive: true });
-    const filename = basename(srcPath);
-    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    await copyFile(srcPath, join(backupDir, `${filename}.${timestamp}.bak`));
-}

package/dist/lib/install-lock.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Process-level mutex for uluops-setup install/uninstall operations.
+ *
+ * Solves the TOCTOU race surfaced by ship-pipeline code-auditor (AF-006):
+ * two concurrent `npx @uluops/setup` invocations both read shared state,
+ * each merges and writes its own version, second write clobbers first.
+ *
+ * Uses `mkdir` atomicity (POSIX + NTFS, ~50 years stable) instead of a
+ * dependency. Meta file inside the lock dir carries PID + hostname +
+ * start timestamp so stale locks can be reclaimed automatically.
+ *
+ * Scope is intentionally narrow: this protects setup-vs-setup races only.
+ * Setup-vs-harness races (the harness CLI writing to its own settings file
+ * concurrently) require a separate compare-and-swap design.
+ */
+export interface LockHandle {
+    release(): Promise<void>;
+}
+export interface AcquireOptions {
+    /** Max time a held lock is considered valid before being reclaimed (default 30 min). */
+    maxAgeMs?: number;
+    /** How long to wait for a held lock before failing (default 0). */
+    waitMs?: number;
+    /** Override the lock directory (test seam). */
+    lockDir?: string;
+}
+/** Thrown when another process holds the lock and waiting has exhausted. */
+export declare class InstallLockHeldError extends Error {
+    readonly holder: {
+        pid: number;
+        hostname: string;
+        ageMs: number;
+    };
+    constructor(holder: {
+        pid: number;
+        hostname: string;
+        ageMs: number;
+    });
+}
+/**
+ * Acquire the install lock. Resolves with a handle whose `release()` must be
+ * called in a `finally` block. Throws `InstallLockHeldError` if the lock is
+ * held by a live process and waiting (if any) has exhausted.
+ */
+export declare function acquireInstallLock(opts?: AcquireOptions): Promise<LockHandle>;
+/** Test-only: detach handlers and clear lock-dir tracking so tests can rebind. */
+export declare function __resetSignalHandlersForTesting(): void;

package/dist/lib/install-lock.js

@@ -0,0 +1,251 @@
+/**
+ * Process-level mutex for uluops-setup install/uninstall operations.
+ *
+ * Solves the TOCTOU race surfaced by ship-pipeline code-auditor (AF-006):
+ * two concurrent `npx @uluops/setup` invocations both read shared state,
+ * each merges and writes its own version, second write clobbers first.
+ *
+ * Uses `mkdir` atomicity (POSIX + NTFS, ~50 years stable) instead of a
+ * dependency. Meta file inside the lock dir carries PID + hostname +
+ * start timestamp so stale locks can be reclaimed automatically.
+ *
+ * Scope is intentionally narrow: this protects setup-vs-setup races only.
+ * Setup-vs-harness races (the harness CLI writing to its own settings file
+ * concurrently) require a separate compare-and-swap design.
+ */
+import { mkdir, readFile, rm, unlink, writeFile, } from "node:fs/promises";
+import { rmSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { getInstallLockDir } from "./paths.js";
+const META_FILENAME = "meta.json";
+const DEFAULT_MAX_AGE_MS = 30 * 60 * 1000; // 30 min
+const DEFAULT_WAIT_MS = 0;
+const POLL_INTERVAL_MS = 500;
+/** Thrown when another process holds the lock and waiting has exhausted. */
+export class InstallLockHeldError extends Error {
+    holder;
+    constructor(holder) {
+        super(`Another uluops-setup process is already running (PID ${holder.pid} on ${holder.hostname}, started ${Math.round(holder.ageMs / 1000)}s ago).`);
+        this.holder = holder;
+        this.name = "InstallLockHeldError";
+    }
+}
+/**
+ * Acquire the install lock. Resolves with a handle whose `release()` must be
+ * called in a `finally` block. Throws `InstallLockHeldError` if the lock is
+ * held by a live process and waiting (if any) has exhausted.
+ */
+export async function acquireInstallLock(opts = {}) {
+    const lockDir = opts.lockDir ?? getInstallLockDir();
+    const maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const waitMs = opts.waitMs ?? DEFAULT_WAIT_MS;
+    const deadline = Date.now() + waitMs;
+    // Ensure the parent directory exists before the atomic lock mkdir below.
+    // The lock dir itself is created with `recursive: false` to preserve
+    // mkdir-atomicity as the lock primitive (two racing processes can't both
+    // win the mkdir). But if the user has never run setup before, ~/.uluops/
+    // doesn't exist yet — and `recursive: false` mkdir surfaces ENOENT on
+    // the missing parent rather than EEXIST on the lock itself, so the loop
+    // below would treat that as an unrecoverable error. Pre-creating the
+    // parent with `recursive: true` is safe (it's idempotent and not part of
+    // the atomicity contract — only the lock dir mkdir is).
+    await mkdir(dirname(lockDir), { recursive: true });
+    // First try (and one retry after stale-lock reclaim).
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await mkdir(lockDir, { recursive: false });
+            // Won the race. Write metadata, register handlers, return handle.
+            const meta = {
+                pid: process.pid,
+                hostname: hostname(),
+                startedAt: Date.now(),
+            };
+            await writeFile(join(lockDir, META_FILENAME), JSON.stringify(meta));
+            return registerHandle(lockDir);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "EEXIST")
+                throw err;
+        }
+        // Lock exists. Inspect it.
+        const verdict = await inspectHeldLock(lockDir, maxAgeMs);
+        if (verdict.kind === "stale") {
+            // Reclaim and retry once.
+            await rm(lockDir, { recursive: true, force: true });
+            continue;
+        }
+        // Live holder. Optionally wait.
+        if (Date.now() < deadline) {
+            while (Date.now() < deadline) {
+                await sleep(POLL_INTERVAL_MS);
+                const recheck = await inspectHeldLock(lockDir, maxAgeMs);
+                if (recheck.kind === "stale") {
+                    // Holder released or died during wait.
+                    break;
+                }
+            }
+            // Retry once after wait.
+            continue;
+        }
+        throw new InstallLockHeldError({
+            pid: verdict.meta.pid,
+            hostname: verdict.meta.hostname,
+            ageMs: Date.now() - verdict.meta.startedAt,
+        });
+    }
+    // Both attempts exhausted without acquiring.
+    throw new InstallLockHeldError({ pid: -1, hostname: "unknown", ageMs: 0 });
+}
+async function inspectHeldLock(lockDir, maxAgeMs) {
+    const metaPath = join(lockDir, META_FILENAME);
+    let raw;
+    try {
+        raw = await readFile(metaPath, "utf-8");
+    }
+    catch {
+        // Lock dir exists but meta missing or unreadable — treat as stale.
+        return { kind: "stale", reason: "missing-meta" };
+    }
+    let meta;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isLockMeta(parsed)) {
+            return { kind: "stale", reason: "malformed-meta" };
+        }
+        meta = parsed;
+    }
+    catch {
+        return { kind: "stale", reason: "invalid-json" };
+    }
+    if (Date.now() - meta.startedAt > maxAgeMs) {
+        return { kind: "stale", reason: "timeout" };
+    }
+    // Same host: probe the PID. Different host: trust the meta until timeout.
+    if (meta.hostname === hostname()) {
+        if (!isPidAlive(meta.pid)) {
+            return { kind: "stale", reason: "dead-pid" };
+        }
+    }
+    return { kind: "live", meta };
+}
+function isLockMeta(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v["pid"] === "number" &&
+        typeof v["hostname"] === "string" &&
+        typeof v["startedAt"] === "number");
+}
+function isPidAlive(pid) {
+    if (pid <= 0 || !Number.isInteger(pid))
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM")
+            return true; // exists but we lack permission
+        return false;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ─── Signal handler registry ─────────────────────────────────────────────────
+//
+// All active lock dirs are tracked at module scope so signal handlers can
+// release every held lock synchronously before re-raising the signal.
+const heldLockDirs = new Set();
+let signalHandlersInstalled = false;
+let installedSigintHandler = null;
+let installedSigtermHandler = null;
+let installedUncaughtHandler = null;
+function registerHandle(lockDir) {
+    heldLockDirs.add(lockDir);
+    ensureSignalHandlers();
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            heldLockDirs.delete(lockDir);
+            try {
+                await unlink(join(lockDir, META_FILENAME));
+            }
+            catch {
+                // Already gone or unreadable; proceed to rmdir.
+            }
+            try {
+                await rm(lockDir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort; do not throw from release().
+            }
+        },
+    };
+}
+function ensureSignalHandlers() {
+    if (signalHandlersInstalled)
+        return;
+    signalHandlersInstalled = true;
+    const cleanup = (signal) => {
+        for (const dir of heldLockDirs) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort.
+            }
+        }
+        heldLockDirs.clear();
+        // Re-raise the signal so default Node behavior runs (exit with the
+        // conventional 128 + signum code). Listeners were already triggered.
+        process.removeListener(signal, cleanup);
+        process.kill(process.pid, signal);
+    };
+    const uncaught = (err) => {
+        for (const dir of heldLockDirs) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // Best-effort.
+            }
+        }
+        heldLockDirs.clear();
+        // Restore default behavior: print stack and exit 1.
+        console.error(err);
+        process.exit(1);
+    };
+    installedSigintHandler = cleanup;
+    installedSigtermHandler = cleanup;
+    installedUncaughtHandler = uncaught;
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+    process.on("uncaughtException", uncaught);
+}
+// ─── Test seams ──────────────────────────────────────────────────────────────
+/** Test-only: detach handlers and clear lock-dir tracking so tests can rebind. */
+export function __resetSignalHandlersForTesting() {
+    if (installedSigintHandler) {
+        process.removeListener("SIGINT", installedSigintHandler);
+        installedSigintHandler = null;
+    }
+    if (installedSigtermHandler) {
+        process.removeListener("SIGTERM", installedSigtermHandler);
+        installedSigtermHandler = null;
+    }
+    if (installedUncaughtHandler) {
+        process.removeListener("uncaughtException", installedUncaughtHandler);
+        installedUncaughtHandler = null;
+    }
+    signalHandlersInstalled = false;
+    heldLockDirs.clear();
+}