@zswarm/core 0.1.6 → 0.1.8

package/dist/ops/spawn.js

@@ -27,7 +27,7 @@ export async function spawnPane(client, args, git, clock = { now: Date.now, slee
         : null;
     const cwd = worktree ? worktree.path : optionalString(args.cwd);
     const name = optionalString(args.name) ?? worktree?.branch ?? null;
-    const beforePanes = await client.listPanes(session, budget.require());
+    const beforePanes = await client.listPanes(session, budget.require(), { fresh: true });
     const before = new Set(beforePanes.map((p) => p.id));
     let paneId = null;
     let tabId = null;
@@ -49,7 +49,7 @@ export async function spawnPane(client, args, git, clock = { now: Date.now, slee
             tabId = args.tabId;
         }
         else if (tabName) {
-            tabId = client.resolveTab(await client.listTabs(session, budget.require()), tabName).id;
+            tabId = client.resolveTab(await client.listTabs(session, budget.require(), { fresh: true }), tabName).id;
         }
         else {
             // Address a tab explicitly even when no viewer is attached.
@@ -58,7 +58,7 @@ export async function spawnPane(client, args, git, clock = { now: Date.now, slee
             tabId = focused?.tabId ?? first?.tabId ?? null;
             tabSource = focused ? "focused-pane" : "first-tab";
             if (tabId === null) {
-                const tabs = await client.listTabs(session, budget.require());
+                const tabs = await client.listTabs(session, budget.require(), { fresh: true });
                 tabId = [...tabs].sort((a, b) => a.position - b.position)[0]?.id ?? null;
             }
             if (tabId === null)
@@ -83,7 +83,7 @@ export async function spawnPane(client, args, git, clock = { now: Date.now, slee
             firstRead = false;
             try {
                 const left = observeMs === 0 ? budget.require() : Math.min(budget.require(), Math.max(1, observedUntil - clock.now()));
-                const panes = await client.listPanes(session, left);
+                const panes = await client.listPanes(session, left, { fresh: true });
                 throwIfAborted(signal);
                 if (paneId) {
                     pane = panes.find((p) => p.id === paneId && !p.isPlugin) ?? null;

package/dist/ops/status.js

@@ -163,9 +163,20 @@ export async function peerStatus(client, args, clock, supplied, opts = {}) {
     }
     const sampleMs = Math.max(50, requested);
     const live = targets.filter((pane) => !pane.exited);
-    if (isTrue(args.sinceLast) && supplied?.readChanged) {
+    // Explicit sampling retains its interval semantics. Ordinary status prefers
+    // one bus observation, including a single-pane crew, with no sample sleep.
+    const preferChanges = isTrue(args.sinceLast) || (args.sinceLast === undefined && args.sampleMs === undefined);
+    if (preferChanges && supplied?.readChanged) {
         const left = remaining();
-        const changed = left > 0 ? await supplied.readChanged(live.map((p) => p.id), left) : null;
+        let changed = null;
+        try {
+            changed = live.length === 0 ? new Map() : left > 0 ? await supplied.readChanged(live.map((p) => p.id), left) : null;
+        }
+        catch (err) {
+            if (isCancelledError(err) || signal?.aborted)
+                throw new ZellijError("cancelled", "operation cancelled");
+            // A missing/older bus falls back to bounded screen samples below.
+        }
         throwIfAborted(signal);
         if (changed) {
             const peers = targets
@@ -174,13 +185,9 @@ export async function peerStatus(client, args, clock, supplied, opts = {}) {
                     return peerEntry(pane, "exited", "", verbose);
                 }
                 const row = changed.get(pane.id);
-                const state = !row
-                    ? "unknown"
-                    : row.changed
-                        ? "busy"
-                        : promptHolds(row?.screen ?? "", resolveHarness(pane))
-                            ? "waiting"
-                            : "idle";
+                const state = !row ? "unknown"
+                    : promptHolds(row.screen, resolveHarness(pane)) ? "waiting"
+                        : row.first ? "unknown" : row.changed ? "busy" : "idle";
                 return peerEntry(pane, state, row?.screen ?? "", verbose, {
                     ...(row?.first ? { first: true } : {}),
                 });
@@ -193,6 +200,7 @@ export async function peerStatus(client, args, clock, supplied, opts = {}) {
                     source,
                     sampled: false,
                     sinceLast: true,
+                    observation: "bus-changes",
                     peers,
                     tabs: statusTabs(peers),
                     free: peers.filter((p) => p.state === "idle").map((p) => p.id),
@@ -321,6 +329,7 @@ export async function peerStatus(client, args, clock, supplied, opts = {}) {
         session,
         source,
         sampled: true,
+        observation: "samples",
         sampleMs,
         peers,
         tabs: statusTabs(peers),

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/worktree.js

@@ -62,7 +62,7 @@ export async function listPeerWorktrees(git, client, args) {
     let panes = [];
     try {
         const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
-        panes = await client.listPanes(session);
+        panes = await client.listPanes(session, undefined, { fresh: true });
     }
     catch {
         // Worktrees are useful to list even with no live Zellij session.
@@ -118,7 +118,7 @@ export async function removePeerWorktree(git, client, args, env = process.env) {
     let occupants = [];
     try {
         const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
-        occupants = panesIn(await client.listPanes(session), target.path);
+        occupants = panesIn(await client.listPanes(session, undefined, { fresh: true }), target.path);
     }
     catch (err) {
         // No live session means nobody is working in it. Any other failure must

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",
@@ -129,13 +130,25 @@ export const PARAMS = [
         name: "sampleMs",
         type: "number",
         flags: ["--sample-ms"],
-        description: "status: gap between the two screen samples (default 400); 0 skips sampling and reports running/exited only",
+        description: "status: explicitly sample twice with this gap (fallback default 400); 0 reports running/exited only; default prefers bus changes",
     },
     {
         name: "sinceLast",
         type: "boolean",
         flags: ["--since-last"],
-        description: "status: classify by what changed since the last status call instead of sampling twice; needs the event bus, no sample gap",
+        description: "status: classify changes since the previous bus observation (default when bus available); first observation is unknown unless a prompt is recognized",
+    },
+    {
+        name: "fresh",
+        type: "boolean",
+        flags: ["--fresh"],
+        description: "bypass the short-lived session/pane/tab listing cache for this call",
+    },
+    {
+        name: "serveAddress",
+        type: "string",
+        flags: ["--serve"],
+        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",
@@ -245,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",
@@ -422,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",
@@ -483,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", "");
+    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.js

@@ -1,4 +1,4 @@
-import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const LOG_FILE = "log.jsonl";
@@ -9,9 +9,13 @@ 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;
+/** 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;
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -103,32 +107,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 +115,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) {

package/dist/zellij/binary.d.ts

@@ -1,9 +1,16 @@
+import { ZellijError } from "../errors.js";
 import { createSshExec, NOT_FOUND_EXIT, type ExecFn, type ExecResult, type SshTarget } from "../exec.js";
 export { createSshExec, type SshTarget };
 export type ZellijExecResult = ExecResult;
 export type ZellijExecFn = ExecFn;
+/** Where a missing/wrong-Zellij failure was produced. */
+export type ZellijFailureOrigin = "local_spawn" | "local_preflight" | "remote";
 export declare const DEFAULT_TIMEOUT_MS = 15000;
 export { NOT_FOUND_EXIT };
+/** Local Node spawn failure vs a process that actually started. */
+export declare function originFromExecResult(result: ExecResult): Exclude<ZellijFailureOrigin, "local_preflight">;
+export declare function zellijExecDetails(result: ExecResult): Record<string, unknown>;
+export declare function zellijMissingError(zellijPath: string, result: ExecResult): ZellijError;
 /** Expand a leading `~/` or `~\` using USERPROFILE/HOME. */
 export declare function expandHomePath(input: string, env?: NodeJS.ProcessEnv): string;
 /**
@@ -30,14 +37,27 @@ export declare function identityCacheKey(zellijPath: string, ssh?: {
     options: string[];
     mode?: string;
     remoteBin?: string;
+    /** SSH client binary (`SshTarget.ssh`). */
+    ssh?: string;
+    sshBin?: string;
+    remoteShell?: string;
 } | null): string;
 /**
  * Confirm the resolved binary is Zellij. Only verified identities are cached.
  * Transport timeouts leave the cache empty so a later call can retry.
  * Returns false when verification is unresolved; only true is cached.
+ * In-flight probes are never shared — each caller supplies its own timeout.
  */
-export declare function ensureZellijIdentity(exec: ExecFn, zellijPath: string, timeoutMs?: number, cacheKey?: string): Promise<boolean>;
-export declare function ensureZellijCapabilities(exec: ExecFn, zellijPath: string, timeoutMs?: number, cacheKey?: string): Promise<boolean>;
+export declare function ensureZellijIdentity(exec: ExecFn, zellijPath: string, timeoutMs?: number, cacheKey?: string, signal?: AbortSignal): Promise<boolean>;
+export declare function ensureZellijCapabilities(exec: ExecFn, zellijPath: string, timeoutMs?: number, cacheKey?: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Identity and capability are independent reads. Run them together under one
+ * remaining budget; do not share in-flight work with another caller.
+ */
+export declare function ensureZellijProbes(exec: ExecFn, zellijPath: string, timeoutMs?: number, cacheKey?: string, signal?: AbortSignal): Promise<{
+    identity: boolean;
+    capabilities: boolean;
+}>;
 /** Test helper: drop cached identity/capability probes. */
 export declare function resetZellijIdentityCache(): void;
 export declare function resolveZellijBinary(env?: NodeJS.ProcessEnv): string;