@zswarm/core 0.1.7 → 0.1.8

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/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.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;
 /**

package/dist/zellij/binary.js

@@ -7,6 +7,19 @@ import { applyIpcTmpEnv } from "./ipc.js";
 export { createSshExec };
 export const DEFAULT_TIMEOUT_MS = 15_000;
 export { NOT_FOUND_EXIT };
+/** Local Node spawn failure vs a process that actually started. */
+export function originFromExecResult(result) {
+    return result.spawn?.origin === "local" ? "local_spawn" : "remote";
+}
+export function zellijExecDetails(result) {
+    const origin = originFromExecResult(result);
+    return result.spawn
+        ? { origin, spawn: { origin: result.spawn.origin, errno: result.spawn.errno, bin: result.spawn.bin } }
+        : { origin };
+}
+export function zellijMissingError(zellijPath, result) {
+    return new ZellijError("zellij_missing", `zellij binary not found (${zellijPath}); install Zellij ≥ 0.42, add it to PATH, or set ZSWARM_BIN / ZSWARM_PATH`, zellijExecDetails(result));
+}
 /** Expand a leading `~/` or `~\` using USERPROFILE/HOME. */
 export function expandHomePath(input, env = process.env) {
     const trimmed = input.trim();
@@ -51,7 +64,7 @@ export function looksLikeZswarmBinary(path) {
 export function assertZellijBinaryPath(path) {
     if (!looksLikeZswarmBinary(path))
         return;
-    throw new ZellijError("zellij_wrong_bin", `ZSWARM_BIN/ZSWARM_PATH points at zswarm (${path}), not Zellij. Set it to the zellij binary (e.g. ~/.local/bin/zellij)`);
+    throw new ZellijError("zellij_wrong_bin", `ZSWARM_BIN/ZSWARM_PATH points at zswarm (${path}), not Zellij. Set it to the zellij binary (e.g. ~/.local/bin/zellij)`, { origin: "local_preflight", bin: path });
 }
 /**
  * ZSWARM_SSH is a destination, not a full ssh argv.
@@ -127,10 +140,10 @@ export async function ensureZellijIdentity(exec, zellijPath, timeoutMs = 3_000,
     });
     const text = `${result.stdout}\n${result.stderr}`;
     if (/usage:\s*zswarm/i.test(text) || /unknown arg:/i.test(text)) {
-        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath}). Set ZSWARM_BIN to the zellij executable`);
+        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath}). Set ZSWARM_BIN to the zellij executable`, zellijExecDetails(result));
     }
     if (result.code === NOT_FOUND_EXIT) {
-        throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath}); install Zellij ≥ 0.42, add it to PATH, or set ZSWARM_BIN / ZSWARM_PATH`);
+        throw zellijMissingError(zellijPath, result);
     }
     if (result.code === 0) {
         if (signal?.aborted)
@@ -139,7 +152,7 @@ export async function ensureZellijIdentity(exec, zellijPath, timeoutMs = 3_000,
             identityCache.add(cacheKey);
             return true;
         }
-        throw new ZellijError("zellij_wrong_bin", `resolved binary is not Zellij (${zellijPath}); --version returned: ${result.stdout.trim() || result.stderr.trim() || "empty"}`);
+        throw new ZellijError("zellij_wrong_bin", `resolved binary is not Zellij (${zellijPath}); --version returned: ${result.stdout.trim() || result.stderr.trim() || "empty"}`, zellijExecDetails(result));
     }
     // Timeout / transport failure: leave unresolved so a later call retries.
     return false;
@@ -161,10 +174,10 @@ export async function ensureZellijCapabilities(exec, zellijPath, timeoutMs = 3_0
     });
     const text = `${result.stdout}\n${result.stderr}`;
     if (/usage:\s*zswarm/i.test(text)) {
-        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath})`);
+        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath})`, zellijExecDetails(result));
     }
     if (result.code === NOT_FOUND_EXIT) {
-        throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath})`);
+        throw zellijMissingError(zellijPath, result);
     }
     // Require the flags this client always passes.
     if (result.code === 0 &&
@@ -176,7 +189,7 @@ export async function ensureZellijCapabilities(exec, zellijPath, timeoutMs = 3_0
         return true;
     }
     if (result.code === 0) {
-        throw new ZellijError("zellij_incompatible", `Zellij at ${zellijPath} does not advertise list-sessions --no-formatting; upgrade Zellij (≥ 0.42) or zswarm`);
+        throw new ZellijError("zellij_incompatible", `Zellij at ${zellijPath} does not advertise list-sessions --no-formatting; upgrade Zellij (≥ 0.42) or zswarm`, zellijExecDetails(result));
     }
     // Soft: leave unresolved on transport failure.
     return false;

package/dist/zellij/client.js

@@ -4,7 +4,7 @@ import { buildClosePaneArgs, buildDumpArgs, buildDumpLayoutArgs, buildFocusPaneA
 import { DEFAULT_BUS_TIMEOUT_MS, parseBusReply, parseChangedReply, parseScrollbackReply, parseWaitReply, } from "./bus.js";
 import { parseTabList, resolveTab } from "./tabs.js";
 import { createSshExec } from "../exec.js";
-import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, ensureZellijProbes, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, } from "./binary.js";
+import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, ensureZellijProbes, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, zellijExecDetails, zellijMissingError, } from "./binary.js";
 import { normalizePaneId, parsePaneList, resolvePane, } from "./panes.js";
 import { isZellijNoSessionsOutput, parseSessionList, resolveSelfPaneId, sessionFromEnv, sessionFromList, } from "./session.js";
 /** Zellij wrapper with bounded caches of completed discovery observations. */
@@ -119,14 +119,14 @@ export function createZellijClient(options = {}) {
         await ensureIdentity(remaining);
         const result = await exec(args, { timeoutMs: remaining() });
         if (result.code === NOT_FOUND_EXIT) {
-            throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath}); install Zellij ≥ 0.42, add it to PATH, or set ZSWARM_BIN / ZSWARM_PATH`);
+            throw zellijMissingError(zellijPath, result);
         }
         if (result.code !== 0) {
             const detail = result.stderr.trim() || result.stdout.trim() || "no output";
             if (/usage:\s*zswarm/i.test(detail) || /unknown arg:/i.test(detail)) {
-                throw new ZellijError("zellij_wrong_bin", `resolved binary looks like zswarm, not Zellij (${zellijPath}): ${detail}`);
+                throw new ZellijError("zellij_wrong_bin", `resolved binary looks like zswarm, not Zellij (${zellijPath}): ${detail}`, zellijExecDetails(result));
             }
-            throw new ZellijError("zellij_failed", `${label} failed (exit ${result.code}): ${detail}`);
+            throw new ZellijError("zellij_failed", `${label} failed (exit ${result.code}): ${detail}`, zellijExecDetails(result));
         }
         return result;
     }
@@ -159,16 +159,16 @@ export function createZellijClient(options = {}) {
                 timeoutMs: remaining(),
             });
             if (result.code === NOT_FOUND_EXIT) {
-                throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath}); install Zellij ≥ 0.42, add it to PATH, or set ZSWARM_BIN / ZSWARM_PATH`);
+                throw zellijMissingError(zellijPath, result);
             }
             if (result.code !== 0) {
                 const detail = result.stderr.trim() || result.stdout.trim() || "no output";
                 if (/usage:\s*zswarm/i.test(detail) || /unknown arg:/i.test(detail)) {
-                    throw new ZellijError("zellij_wrong_bin", `resolved binary looks like zswarm, not Zellij (${zellijPath}): ${detail}`);
+                    throw new ZellijError("zellij_wrong_bin", `resolved binary looks like zswarm, not Zellij (${zellijPath}): ${detail}`, zellijExecDetails(result));
                 }
                 if (isZellijNoSessionsOutput(result.stdout, result.stderr))
                     return [];
-                throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${detail}`);
+                throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${detail}`, zellijExecDetails(result));
             }
             return parseSessionList(result.stdout);
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {