@zswarm/core 0.1.7 → 0.1.9

package/dist/ops/status.d.ts

@@ -40,12 +40,13 @@ export declare function statusTabs(peers: Record<string, unknown>[]): {
     panes: number;
     states: Record<string, number>;
 }[];
-export declare function classify(input: {
+type ScreenPair = {
     exited: boolean;
     before: string;
     after: string;
     profile?: HarnessProfile | null;
-}): PeerState;
+};
+export declare function classify(input: ScreenPair): PeerState;
 /** Run `fn` over items with at most `limit` in flight. */
 export declare function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
 /**
@@ -59,3 +60,4 @@ export declare function peerStatus(client: ZellijClient, args: Record<string, un
     deadlineAt?: number;
     signal?: AbortSignal;
 }): Promise<OpsResult>;
+export {};

package/dist/ops/status.js

@@ -53,9 +53,6 @@ export function waitingPrompt(screen, profile) {
     const last = lines[lines.length - 1] ?? "";
     return QUESTION.test(last) ? { reason: "prompt", evidence: last.slice(0, 320), source: "screen" } : null;
 }
-function promptHolds(screen, profile) {
-    return waitingPrompt(screen, profile) !== null;
-}
 /** Compact summary of the selected terminal peers, including inactive tabs. */
 export function statusTabs(peers) {
     const tabs = new Map();
@@ -69,12 +66,17 @@ export function statusTabs(peers) {
     }
     return [...tabs.values()];
 }
-export function classify(input) {
+/** The verdict and, for `waiting`, the prompt behind it — one screen scan. */
+function classifyWithEvidence(input) {
     if (input.exited)
-        return "exited";
+        return { state: "exited", waiting: null };
     if (input.before !== input.after)
-        return "busy";
-    return promptHolds(input.after, input.profile) ? "waiting" : "idle";
+        return { state: "busy", waiting: null };
+    const waiting = waitingPrompt(input.after, input.profile);
+    return { state: waiting ? "waiting" : "idle", waiting };
+}
+export function classify(input) {
+    return classifyWithEvidence(input).state;
 }
 /** Run `fn` over items with at most `limit` in flight. */
 export async function mapPool(items, limit, fn) {
@@ -96,6 +98,7 @@ function isCancelledError(err) {
     return ((err instanceof ZellijError && err.code === "cancelled") ||
         (err instanceof Error && /cancelled/i.test(err.message)));
 }
+/** A `waiting` peer carries its evidence in `extra`, found when it was classified. */
 function peerEntry(pane, state, screen, verbose, extra) {
     const entry = {
         id: pane.id,
@@ -106,8 +109,6 @@ function peerEntry(pane, state, screen, verbose, extra) {
         lastLine: lastLine(screen).slice(0, 160),
         ...extra,
     };
-    if (state === "waiting")
-        entry.waiting = waitingPrompt(screen, resolveHarness(pane));
     if (verbose) {
         entry.command = pane.command ?? null;
         entry.cwd = pane.cwd ?? null;
@@ -185,11 +186,13 @@ export async function peerStatus(client, args, clock, supplied, opts = {}) {
                     return peerEntry(pane, "exited", "", verbose);
                 }
                 const row = changed.get(pane.id);
+                const waiting = row ? waitingPrompt(row.screen, resolveHarness(pane)) : null;
                 const state = !row ? "unknown"
-                    : promptHolds(row.screen, resolveHarness(pane)) ? "waiting"
+                    : waiting ? "waiting"
                         : row.first ? "unknown" : row.changed ? "busy" : "idle";
                 return peerEntry(pane, state, row?.screen ?? "", verbose, {
                     ...(row?.first ? { first: true } : {}),
+                    ...(waiting ? { waiting } : {}),
                 });
             })
                 .sort((a, b) => String(a.id).localeCompare(String(b.id)));
@@ -315,13 +318,13 @@ export async function peerStatus(client, args, clock, supplied, opts = {}) {
             peers.push(peerEntry(pane, "unknown", after ?? first ?? "", verbose));
             continue;
         }
-        const state = classify({
+        const { state, waiting } = classifyWithEvidence({
             exited: false,
             before: first,
             after,
             profile: resolveHarness(pane),
         });
-        peers.push(peerEntry(pane, state, after, verbose));
+        peers.push(peerEntry(pane, state, after, verbose, waiting ? { waiting } : undefined));
     }
     peers.sort((a, b) => String(a.id).localeCompare(String(b.id)));
     const free = peers.filter((p) => p.state === "idle").map((p) => p.id);

package/dist/ops/types.d.ts

@@ -1,4 +1,5 @@
 import type { RoutingContext } from "./routing.js";
+import type { ServeTunnelManager } from "./serve-tunnel.js";
 export type OpsResult = ({
     ok: true;
     data: unknown;
@@ -25,6 +26,54 @@ export type DispatchDeps = {
     env?: NodeJS.ProcessEnv;
     /** MCP cancellation; aborted waits stop instead of running to timeout. */
     signal?: AbortSignal;
+    /** Process-owned ssh:// LocalForward manager. CLI disposes; MCP reuses. */
+    serveTunnels?: ServeTunnelManager;
+    /**
+     * Test seam for optional Tailscale `status --json`. Default runs the
+     * `tailscale` CLI with a bounded timeout and output cap.
+     * Used by doctor (peer mapping) and by serve bind verification.
+     */
+    tailscaleStatus?: (input: {
+        timeoutMs: number;
+        signal?: AbortSignal;
+        env: NodeJS.ProcessEnv;
+    }) => Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Test seam for OS interface address ownership during Tailscale serve bind. */
+    networkInterfaces?: () => NodeJS.Dict<import("node:os").NetworkInterfaceInfo[]>;
+    /** Narrow injectables for Windows `serve --install` / `--clear`. */
+    serveInstall?: ServeInstallDeps;
+};
+export type ServePowerShellResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+    aborted?: boolean;
+    timedOut?: boolean;
+};
+export type ServeInstallDeps = {
+    platform?: NodeJS.Platform;
+    runPowerShell?: (script: string, options: {
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }) => Promise<ServePowerShellResult>;
+    probeServe?: (target: string, options?: {
+        token?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }) => Promise<OpsResult>;
+    callServe?: (target: string, args: Record<string, unknown>, options: {
+        timeoutMs: number;
+        token?: string;
+        signal?: AbortSignal;
+    }) => Promise<OpsResult>;
+    execPath?: string;
+    scriptPath?: string;
+    argv?: string[];
+    launchId?: string;
 };
 export type Clock = {
     now: () => number;

package/dist/ops/util.js

@@ -5,7 +5,14 @@ export const DEFAULT_DUMP_MAX_CHARS = 8_000;
 export const DEFAULT_WAIT_MAX_CHARS = 2_000;
 export function fail(err) {
     if (err instanceof ZellijError) {
-        return { ok: false, error: { code: err.code, message: err.message } };
+        return {
+            ok: false,
+            error: {
+                code: err.code,
+                message: err.message,
+                ...(err.details ? { details: err.details } : {}),
+            },
+        };
     }
     const message = err instanceof Error ? err.message : String(err);
     return { ok: false, error: { code: "failed", message } };

package/dist/ops/wait.js

@@ -1,4 +1,5 @@
 import { ZellijError } from "../errors.js";
+import { DEFAULT_TIMEOUT_MS } from "../zellij/binary.js";
 import { DEFAULT_WAIT_MAX_CHARS, dumpMaxChars, isTrue, normalizeScreen, numberArg, optionalString, throwIfAborted, truncateDumpText, } from "./util.js";
 const WAIT_DEFAULTS = {
     idleMs: 2_000,
@@ -10,6 +11,11 @@ const WAIT_LIMITS = {
     pollMs: { min: 50, max: 30_000 },
     timeoutMs: { min: 1_000, max: 900_000 },
 };
+/**
+ * A poll at the deadline still gets this long, so `timeout` reports the screen
+ * at the deadline; a hung dump there overruns the wait by at most this much.
+ */
+const FINAL_DUMP_MS = 1_000;
 export function buildMatcher(args) {
     const match = optionalString(args.match);
     if (!match)
@@ -98,15 +104,29 @@ export async function waitForPane(client, target, args, clock, waitViaBus, signa
     let lastChangeAt = started;
     let polls = 0;
     let changes = 0;
+    let last = null;
     for (;;) {
         throwIfAborted(signal);
-        const dumped = await client.dumpPane({
-            session,
-            paneId: pane.id,
-            full: isTrue(args.full),
-        });
+        const left = timeoutMs - (clock.now() - started);
+        let text;
+        try {
+            const dumped = await client.dumpPane({
+                session,
+                paneId: pane.id,
+                full,
+                timeoutMs: Math.max(FINAL_DUMP_MS, Math.min(left, DEFAULT_TIMEOUT_MS)),
+            });
+            text = dumped.text;
+        }
+        catch (err) {
+            throwIfAborted(signal);
+            // Out of time with a screen in hand: the wait timed out, it did not fail.
+            if (last && clock.now() - started >= timeoutMs) {
+                return waitResult("timeout", { ...last, at: clock.now() });
+            }
+            throw err;
+        }
         polls++;
-        const text = dumped.text;
         const screen = normalizeScreen(text);
         const at = clock.now();
         const ctx = {
@@ -137,6 +157,8 @@ export async function waitForPane(client, target, args, clock, waitViaBus, signa
         }
         if (at - started >= timeoutMs)
             return waitResult("timeout", ctx);
-        await clock.sleep(pollMs);
+        last = ctx;
+        // The last poll lands on the deadline, not up to a whole pollMs past it.
+        await clock.sleep(Math.min(pollMs, timeoutMs - (at - started)));
     }
 }

package/dist/schema.d.ts

@@ -2,7 +2,7 @@
  * One description of the zswarm surface. The MCP tool schema, the CLI flags,
  * and the CLI help text are all generated from it, so they cannot drift apart.
  */
-export declare const OP_NAMES: readonly ["list", "sessions", "send", "broadcast", "dump", "tail", "wait", "status", "keys", "interrupt", "spawn", "close", "worktrees", "unworktree", "signal", "signals", "await", "log", "rename", "focus", "tabs", "layout", "stack", "diff", "checkpoint", "bus", "serve"];
+export declare const OP_NAMES: readonly ["list", "sessions", "send", "broadcast", "dump", "tail", "wait", "status", "keys", "interrupt", "spawn", "close", "worktrees", "unworktree", "signal", "signals", "await", "log", "rename", "focus", "tabs", "layout", "stack", "diff", "checkpoint", "bus", "serve", "doctor"];
 export type OpName = (typeof OP_NAMES)[number];
 /** Ops that address an existing pane through `to`. */
 export declare const TARGET_OPS: readonly OpName[];

package/dist/schema.js

@@ -31,6 +31,7 @@ export const OP_NAMES = [
     "checkpoint",
     "bus",
     "serve",
+    "doctor",
 ];
 /** Ops that address an existing pane through `to`. */
 export const TARGET_OPS = [
@@ -51,7 +52,7 @@ export const PARAMS = [
         name: "session",
         type: "string",
         flags: ["--session", "-s"],
-        description: "Zellij session name (optional if sole live session or ZSWARM_SESSION / ZELLIJ_SESSION_NAME)",
+        description: "Zellij session name (optional if sole live session or ZSWARM_SESSION / ZELLIJ_SESSION_NAME). serve --install: readiness target only — does not change the task's default routing",
     },
     {
         name: "to",
@@ -111,13 +112,13 @@ export const PARAMS = [
         name: "clear",
         type: "boolean",
         flags: ["--clear"],
-        description: "signal: reset the channel (all channels when none is given); bus: forget the installed plugin; serve: unregister the Windows logon task",
+        description: "signal: reset the channel (all channels when none is given); bus: forget the installed plugin; serve: stop and unregister the owned Windows zswarm-serve logon task if present",
     },
     {
         name: "install",
         type: "boolean",
         flags: ["--install"],
-        description: "bus: load the event-bus plugin in a pane so its permission prompt can be answered, then remember it; serve: register a Windows logon task that listens for remote zswarm",
+        description: "bus: load the event-bus plugin in a pane so its permission prompt can be answered, then remember it; serve: register the current-user Windows Interactive logon task and wait for authenticated hello plus host session visibility",
     },
     {
         name: "reset",
@@ -147,7 +148,7 @@ export const PARAMS = [
         name: "serveAddress",
         type: "string",
         flags: ["--serve"],
-        description: "use an existing serve endpoint (e.g. 127.0.0.1:9419 through an SSH tunnel); preferred for frequent status calls; uses ZSWARM_SERVE_TOKEN",
+        description: "existing serve endpoint: host:port, tcp://host:port, or ssh://user@host[:sshPort]?servePort=9419. ssh:// opens a process-owned SSH LocalForward and probes hello before ops (desktop serve must already be running). Omit sshPort to use ssh_config Port. tcp:// also names a private Tailscale Serve frontend over loopback (docs/tailscale.md). Uses ZSWARM_SERVE_TOKEN",
     },
     {
         name: "limit",
@@ -257,7 +258,7 @@ export const PARAMS = [
         name: "timeoutMs",
         type: "number",
         flags: ["--timeout-ms"],
-        description: "wait: timeout (default 60000); status/spawn: overall deadline (default 30000), including setup and observation",
+        description: "wait: timeout (default 60000); status/spawn: overall deadline (default 30000); doctor: overall deadline (default 10000), including Tailscale/SSH/hello/host checks; serve --install: overall install/readiness deadline (default 30000)",
     },
     {
         name: "keys",
@@ -434,7 +435,7 @@ export const PARAMS = [
         name: "listen",
         type: "string",
         flags: ["--listen"],
-        description: "serve: bind address (default 127.0.0.1:9419). Reach it from another machine with ZSWARM_SERVE after an SSH tunnel",
+        description: "serve: bind address (default 127.0.0.1:9419). Loopback needs no Tailscale; a non-loopback literal must be a verified local Tailscale IP (see docs/tailscale.md). Reach via ZSWARM_SERVE / --serve (direct host:port, private Tailscale Serve tcp:// frontend, or ssh:// to remote loopback)",
     },
     {
         name: "verbose",
@@ -495,7 +496,7 @@ export function cliUsage() {
         const value = param.type === "boolean" ? "" : param.type === "number" ? " N" : " VALUE";
         lines.push(`  ${param.flags.join(", ").padEnd(28)}${value.trim().padEnd(6)}${param.description}`);
     }
-    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once per Zellij session. `--force` closes orphan bus panes and reloads; do not use it as a retry.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE (+ ZSWARM_SERVE_TOKEN). Serve binds loopback only and always requires a token.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_CACHE_TTL_MS", "");
+    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once per Zellij session. `--force` closes orphan bus panes and reloads; do not use it as a retry.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE / --serve (host:port, tcp://, or ssh://user@host?servePort=9419) plus ZSWARM_SERVE_TOKEN. Serve defaults to loopback and always requires a token; an explicit local Tailscale IP is allowed only after host verification. Private raw TCP Tailscale Serve keeps the backend on 127.0.0.1 behind `tailscale serve --tcp=…` (docs/tailscale.md). ssh:// does not start remote serve. Windows default recipe: `zswarm serve --install` (verified readiness).", "Doctor: `zswarm doctor --session crew` inspects local, --ssh, and --serve routes without installs, pane changes, or plugin launch. See docs/doctor.md and docs/tailscale.md.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_SSH_BIN, ZSWARM_SSH_OPTS, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_TAILSCALE_BIN, ZSWARM_CACHE_TTL_MS", "");
     return lines.join("\n");
 }
 /** Turn argv (without the op) into dispatch args, driven by PARAMS. */

package/dist/state.d.ts

@@ -29,6 +29,13 @@ export type BusMarkerRecord = {
     configKey: string;
     installedAt: number;
 };
+/** How much of the end of the log `readLog` reads; older entries are not shown. */
+export declare const LOG_TAIL_BYTES: number;
+/**
+ * Past this, the append that crossed it trims the file back to its readable
+ * tail. Keeps the log bounded without needing a rotation daemon.
+ */
+export declare const LOG_MAX_BYTES: number;
 export declare function defaultStateDir(env?: NodeJS.ProcessEnv): string;
 export type StateStoreOptions = {
     dir?: string;

package/dist/state.js

@@ -1,4 +1,4 @@
-import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const LOG_FILE = "log.jsonl";
@@ -7,11 +7,59 @@ const SIGNALS_LOCK = "signals.lock";
 const CURSORS_FILE = "cursors.json";
 const CURSORS_LOCK = "cursors.lock";
 const BUS_FILE = "bus.json";
-/** Keeps the log bounded without needing a rotation daemon. */
-const LOG_TAIL_BYTES = 512 * 1024;
+/** How much of the end of the log `readLog` reads; older entries are not shown. */
+export const LOG_TAIL_BYTES = 512 * 1024;
+/**
+ * Past this, the append that crossed it trims the file back to its readable
+ * tail. Keeps the log bounded without needing a rotation daemon.
+ */
+export const LOG_MAX_BYTES = 4 * 1024 * 1024;
+/** Bound for waiting on a *live* lock holder before failing. */
 const LOCK_WAIT_MS = 5_000;
-/** A live pid older than this is treated as a recycle of a crashed holder. */
-const LOCK_STALE_MS = 30_000;
+/**
+ * Fresh empty/malformed lock files this young are treated as an in-flight
+ * exclusive create (wait), not as abandoned debris (refuse).
+ */
+const LOCK_PENDING_MS = LOCK_WAIT_MS;
+/**
+ * The last `bytes` of a file, starting at its first whole line. Reads only
+ * that window, so a long-lived log does not cost a full read per `log` call.
+ */
+function readFileTail(path, bytes) {
+    const fd = openSync(path, "r");
+    try {
+        const size = fstatSync(fd).size;
+        // One byte of lead-in says whether the window already starts a line.
+        const start = Math.max(0, size - bytes - 1);
+        const buf = Buffer.alloc(size - start);
+        let read = 0;
+        while (read < buf.length) {
+            const n = readSync(fd, buf, read, buf.length - read, start + read);
+            if (n === 0)
+                break;
+            read += n;
+        }
+        const text = buf.toString("utf8", 0, read);
+        return start === 0 ? text : text.slice(text.indexOf("\n") + 1);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Keep only a file's readable tail. Everything before it is already invisible
+ * to `readLog`; an append racing the rename can be lost, and the log is an aid.
+ */
+function trimToTail(path, bytes) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, readFileTail(path, bytes), "utf8");
+        renameSync(tmp, path);
+    }
+    catch {
+        rmSync(tmp, { force: true });
+    }
+}
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -49,7 +97,10 @@ export function createStateStore(options = {}) {
             return;
         try {
             ensureDir();
-            appendFileSync(join(dir, LOG_FILE), `${JSON.stringify(entry)}\n`, "utf8");
+            const path = join(dir, LOG_FILE);
+            appendFileSync(path, `${JSON.stringify(entry)}\n`, "utf8");
+            if (statSync(path).size > LOG_MAX_BYTES)
+                trimToTail(path, LOG_TAIL_BYTES);
         }
         catch {
             // The log is an aid, never a reason to fail an op.
@@ -58,15 +109,11 @@ export function createStateStore(options = {}) {
     function readLog() {
         let raw;
         try {
-            raw = readFileSync(join(dir, LOG_FILE), "utf8");
+            raw = readFileTail(join(dir, LOG_FILE), LOG_TAIL_BYTES);
         }
         catch {
             return [];
         }
-        if (raw.length > LOG_TAIL_BYTES) {
-            raw = raw.slice(raw.length - LOG_TAIL_BYTES);
-            raw = raw.slice(raw.indexOf("\n") + 1);
-        }
         const out = [];
         for (const line of raw.split("\n")) {
             if (!line.trim())
@@ -103,32 +150,6 @@ export function createStateStore(options = {}) {
             return null;
         }
     }
-    /**
-     * Dead pid → steal now. This process's own leftover (unlink failed, or a
-     * non-reentrant re-entry) → steal now. A live pid whose `at` is older than
-     * LOCK_STALE_MS is a recycled pid, not a holder still inside fn().
-     * Empty leftover from older writers (wx with no owner bytes) → steal once
-     * mtime is older than the wait, so an in-flight create is not yanked out
-     * from under the holder.
-     * Owner is read once: a second read can see a pid that appeared after an
-     * empty snapshot and would steal a live lock.
-     */
-    function lockIsStale(lockPath) {
-        const owner = readLockOwner(lockPath);
-        if (owner) {
-            if (owner.pid === process.pid)
-                return true;
-            if (!pidAlive(owner.pid))
-                return true;
-            return Date.now() - owner.at >= LOCK_STALE_MS;
-        }
-        try {
-            return Date.now() - statSync(lockPath).mtimeMs >= LOCK_WAIT_MS;
-        }
-        catch {
-            return false;
-        }
-    }
     function lockBusy(code) {
         // Unix: O_EXCL on an existing file is EEXIST. Windows: a holder that still
         // has the handle open (or a delete-pending name) is EPERM / EACCES / EBUSY.
@@ -137,43 +158,185 @@ export function createStateStore(options = {}) {
             code === "EACCES" ||
             code === "EBUSY");
     }
-    function unlinkLock(lockPath) {
+    /**
+     * Cursor/signal locks: exclusive create (`wx`) + owner stamp; release by
+     * generation-matched unlink of the stamp this process published.
+     *
+     * Foreign / abandoned / empty-old lock files are NOT auto-reclaimed.
+     * Portable check-then-rename/unlink reclaim can move a live holder's shared
+     * name aside and admit another writer into that critical section (demonstrated
+     * with real cooperating writeCursor processes). Prefer bounded fail-closed
+     * refusal over unsafe automatic recovery.
+     *
+     * A dead-looking owner observation is only refused when that same generation
+     * is still present. If normal release removed the path or another writer
+     * published a new generation between observation and the liveness check,
+     * contenders retry exclusive create within the original LOCK_WAIT_MS budget
+     * (generation churn does not reset the deadline).
+     *
+     * Self-pid leftovers (same process, prior unlink failed) may be removed when
+     * the on-disk generation still matches — this process is not inside `fn()`.
+     *
+     * Operator recovery: if acquisition refuses an abandoned lock, confirm the
+     * recorded pid is gone and no writer holds the file, then remove the lock
+     * path manually and retry.
+     */
+    function unlinkIfMatchingOwner(lockPath, expected) {
         const until = Date.now() + 500;
         while (true) {
+            const current = readLockOwner(lockPath);
+            if (!current ||
+                current.pid !== expected.pid ||
+                current.at !== expected.at) {
+                return false;
+            }
             try {
                 rmSync(lockPath, { force: true });
-                return;
+                return true;
             }
             catch (err) {
                 if (!lockBusy(err.code) || Date.now() >= until) {
-                    return;
+                    return false;
                 }
                 sleepSync(10);
             }
         }
     }
+    /** Only this process may clear its own leftover generation. */
+    function tryReclaimSelfLock(lockPath) {
+        const owner = readLockOwner(lockPath);
+        if (!owner || owner.pid !== process.pid)
+            return false;
+        return unlinkIfMatchingOwner(lockPath, owner);
+    }
+    function abandonedLockError(lockName, lockPath, observed) {
+        // Use the generation that justified refusal — do not re-read the path and
+        // accidentally describe a live successor as needing operator recovery.
+        if (observed) {
+            return new Error(`refusing automatic reclaim of ${lockName} (dead-or-abandoned owner pid=${observed.pid} at=${observed.at}); ` +
+                `remove ${lockPath} only after confirming that process is gone and no writer holds the file, then retry`);
+        }
+        return new Error(`refusing automatic reclaim of ${lockName} (empty or malformed lock without a safe owner record); ` +
+            `remove ${lockPath} only when no writer is using it, then retry`);
+    }
+    /**
+     * Classify a blocking lock against the *current* generation.
+     *
+     * `wait` = live holder or fresh in-flight create.
+     * `refuse` = unchanged abandoned foreign/empty debris — fail closed.
+     * `self` = reclaimable same-pid leftover.
+     * `retry` = observation went stale during the check (normal release removed
+     * the path, or a new generation superseded the departed owner). Contender
+     * must retry exclusive create within the original wait budget — not refuse
+     * a lock that is no longer abandoned, and not unlink/rename anything.
+     */
+    function classifyBlockingLock(lockPath) {
+        const owner = readLockOwner(lockPath);
+        if (owner) {
+            if (owner.pid === process.pid)
+                return { kind: "self", observed: owner };
+            if (pidAlive(owner.pid))
+                return { kind: "wait", observed: owner };
+            // Dead-looking foreign owner: only refuse if THIS generation is still
+            // current. Normal release+exit between read and liveness check leaves
+            // the path absent or replaced by a live successor — that is not
+            // abandoned debris.
+            const still = readLockOwner(lockPath);
+            if (!still)
+                return { kind: "retry", observed: null };
+            if (still.pid !== owner.pid || still.at !== owner.at) {
+                return { kind: "retry", observed: still };
+            }
+            return { kind: "refuse", observed: owner };
+        }
+        try {
+            if (Date.now() - statSync(lockPath).mtimeMs < LOCK_PENDING_MS) {
+                return { kind: "wait", observed: null };
+            }
+        }
+        catch {
+            // Path disappeared between the busy create and this check.
+            return { kind: "retry", observed: null };
+        }
+        // Old empty/malformed: confirm it is still present and still ownerless
+        // before refusing — a successor may have published while we inspected.
+        const again = readLockOwner(lockPath);
+        if (again) {
+            if (again.pid === process.pid)
+                return { kind: "self", observed: again };
+            if (pidAlive(again.pid))
+                return { kind: "wait", observed: again };
+            const confirm = readLockOwner(lockPath);
+            if (!confirm)
+                return { kind: "retry", observed: null };
+            if (confirm.pid !== again.pid || confirm.at !== again.at) {
+                return { kind: "retry", observed: confirm };
+            }
+            return { kind: "refuse", observed: again };
+        }
+        try {
+            statSync(lockPath);
+        }
+        catch {
+            return { kind: "retry", observed: null };
+        }
+        return { kind: "refuse", observed: null };
+    }
+    /**
+     * Drop this process's lock only when the generation we published is still at
+     * the well-known path. Under fail-closed foreign reclaim, generations are not
+     * stolen while we hold the critical section, so a matching unlink cannot
+     * remove a successor published by another cooperating writer.
+     */
+    function unlinkOwnedLock(lockPath, stamp) {
+        unlinkIfMatchingOwner(lockPath, stamp);
+    }
     function withFileLock(lockName, fn) {
         ensureDir();
         const lockPath = join(dir, lockName);
         const deadline = Date.now() + LOCK_WAIT_MS;
         while (true) {
+            const stamp = { pid: process.pid, at: Date.now() };
             try {
-                const fd = openSync(lockPath, "wx");
+                // Exclusive create (`wx`) plus a write of the owner record. That is
+                // not one atomic publish of populated bytes — create and write still
+                // have an interval. The UTF-8 fast path keeps that interval in one
+                // native writeFileSync rather than two JS turns (openSync then write).
+                // Abandoned foreign/empty locks are refused (not renamed or unlinked).
+                writeFileSync(lockPath, JSON.stringify(stamp), {
+                    encoding: "utf8",
+                    flag: "wx",
+                });
                 try {
-                    writeFileSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
                     return fn();
                 }
                 finally {
-                    closeSync(fd);
-                    unlinkLock(lockPath);
+                    unlinkOwnedLock(lockPath, stamp);
                 }
             }
             catch (err) {
                 const code = err.code;
                 if (!lockBusy(code))
                     throw err;
-                if (lockIsStale(lockPath)) {
-                    unlinkLock(lockPath);
+                if (tryReclaimSelfLock(lockPath)) {
+                    continue;
+                }
+                const { kind, observed } = classifyBlockingLock(lockPath);
+                if (kind === "self") {
+                    if (tryReclaimSelfLock(lockPath))
+                        continue;
+                }
+                if (kind === "refuse") {
+                    throw abandonedLockError(lockName, lockPath, observed);
+                }
+                if (kind === "retry") {
+                    // Observation changed (released or superseded). Retry exclusive
+                    // create within the original budget — do not reset the deadline on
+                    // generation churn (unbounded handoffs become a timeout).
+                    if (Date.now() >= deadline) {
+                        throw new Error(`timed out waiting for ${lockName}`);
+                    }
+                    sleepSync(10);
                     continue;
                 }
                 if (Date.now() >= deadline) {