@zswarm/core 0.1.2 → 0.1.4

package/dist/ops/serve.js

@@ -4,27 +4,60 @@ import { ZellijError } from "../errors.js";
 import { encodePowerShellCommand } from "../zellij/ipc.js";
 export const DEFAULT_SERVE_LISTEN = "127.0.0.1:9419";
 export const SERVE_TASK_NAME = "zswarm-serve";
+/** One JSONL request; a client that never sends newline cannot grow forever. */
+export const SERVE_MAX_REQUEST_BYTES = 1024 * 1024;
+/** Drop a socket that never finishes a JSONL line. */
+export const SERVE_IDLE_TIMEOUT_MS = 30_000;
+/** Concurrent TCP clients, including in-flight wait ops. */
+export const SERVE_MAX_CONNECTIONS = 32;
+/** Wait/await allow 15 minutes; this is that plus slack. */
+export const SERVE_CALL_TIMEOUT_CAP_MS = 16 * 60_000;
+const SERVE_TOKEN_FIELD = "serveToken";
+export function isLoopbackHost(host) {
+    const h = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    return (h === "127.0.0.1" ||
+        h === "localhost" ||
+        h === "::1" ||
+        h === "0:0:0:0:0:0:0:1");
+}
+export function formatListenLabel(host, port) {
+    return host.includes(":") ? `[${host}]:${port}` : `${host}:${port}`;
+}
 export function parseListenAddress(raw) {
     const text = (raw ?? DEFAULT_SERVE_LISTEN).trim() || DEFAULT_SERVE_LISTEN;
     const stripped = text.replace(/^tcp:\/\//i, "");
-    const hostPort = stripped.includes("]")
-        ? stripped
-        : stripped.includes(":")
+    let host;
+    let port;
+    if (stripped.startsWith("[")) {
+        const end = stripped.indexOf("]");
+        if (end === -1) {
+            throw new ZellijError("bad_arg", `listen address is not host:port (${text})`);
+        }
+        host = stripped.slice(1, end);
+        const rest = stripped.slice(end + 1);
+        if (!rest.startsWith(":")) {
+            throw new ZellijError("bad_arg", `listen address is not host:port (${text})`);
+        }
+        port = Number(rest.slice(1));
+    }
+    else {
+        const hostPort = stripped.includes(":")
             ? stripped
             : `127.0.0.1:${stripped}`;
-    const colon = hostPort.lastIndexOf(":");
-    const host = colon === -1 ? "127.0.0.1" : hostPort.slice(0, colon) || "127.0.0.1";
-    const port = Number(colon === -1 ? hostPort : hostPort.slice(colon + 1));
-    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        const colon = hostPort.lastIndexOf(":");
+        host = colon === -1 ? "127.0.0.1" : hostPort.slice(0, colon) || "127.0.0.1";
+        port = Number(colon === -1 ? hostPort : hostPort.slice(colon + 1));
+    }
+    if (!host || !Number.isInteger(port) || port < 0 || port > 65535) {
         throw new ZellijError("bad_arg", `listen address is not host:port (${text})`);
     }
-    return { host, port, label: `${host}:${port}` };
+    return { host, port, label: formatListenLabel(host, port) };
 }
-/** Client-side wait: the op's own timeout plus slack, capped at ten minutes. */
+/** Client-side wait: the op's own timeout plus slack. */
 export function serveCallTimeout(args) {
     const requested = Number(args.timeoutMs);
     const base = Number.isFinite(requested) && requested > 0 ? requested : 60_000;
-    return Math.min(Math.max(base + 5_000, 15_000), 10 * 60_000);
+    return Math.min(Math.max(base + 5_000, 15_000), SERVE_CALL_TIMEOUT_CAP_MS);
 }
 /** Env for a serve worker: talk to the local Zellij, never loop back into serve/ssh. */
 export function serveChildEnv(env) {
@@ -33,34 +66,114 @@ export function serveChildEnv(env) {
     delete out.ZSWARM_SSH;
     return out;
 }
-export function startServe(listen, dispatch) {
+function unauthorized() {
+    return {
+        ok: false,
+        error: {
+            code: "serve_unauthorized",
+            message: "zswarm serve rejected the request (missing or wrong ZSWARM_SERVE_TOKEN)",
+        },
+    };
+}
+function takeServeToken(args) {
+    const token = typeof args[SERVE_TOKEN_FIELD] === "string"
+        ? args[SERVE_TOKEN_FIELD]
+        : undefined;
+    const request = { ...args };
+    delete request[SERVE_TOKEN_FIELD];
+    return { token, request };
+}
+export function startServe(listen, dispatch, options = {}) {
     const { host, port } = parseListenAddress(listen);
+    if (!isLoopbackHost(host)) {
+        return Promise.reject(new ZellijError("serve_auth", `zswarm serve only listens on loopback (127.0.0.1 / ::1); off-machine access is an SSH tunnel to 127.0.0.1 (${host} refused)`));
+    }
+    const token = options.token?.trim() || undefined;
+    if (!token) {
+        return Promise.reject(new ZellijError("serve_auth", "zswarm serve requires ZSWARM_SERVE_TOKEN; another local OS user can connect to 127.0.0.1"));
+    }
+    const maxRequestBytes = options.maxRequestBytes ?? SERVE_MAX_REQUEST_BYTES;
+    const idleTimeoutMs = options.idleTimeoutMs ?? SERVE_IDLE_TIMEOUT_MS;
+    const maxConnections = options.maxConnections ?? SERVE_MAX_CONNECTIONS;
     return new Promise((resolve, reject) => {
+        const sockets = new Set();
         const server = createServer((socket) => {
+            socket.on("error", () => {
+                socket.destroy();
+            });
+            if (sockets.size >= maxConnections) {
+                socket.destroy();
+                return;
+            }
+            sockets.add(socket);
+            socket.on("close", () => {
+                sockets.delete(socket);
+            });
             let buf = "";
+            let draining = false;
             socket.setEncoding("utf8");
+            socket.setTimeout(idleTimeoutMs);
+            socket.on("timeout", () => {
+                socket.destroy();
+            });
             socket.on("data", (chunk) => {
                 buf += chunk;
+                if (buf.length > maxRequestBytes) {
+                    socket.write(`${JSON.stringify({
+                        ok: false,
+                        error: {
+                            code: "bad_arg",
+                            message: `serve request exceeded ${maxRequestBytes} bytes`,
+                        },
+                    })}\n`);
+                    socket.destroy();
+                    return;
+                }
                 void drain();
             });
             async function drain() {
-                let nl = buf.indexOf("\n");
-                while (nl !== -1) {
-                    const line = buf.slice(0, nl).trim();
-                    buf = buf.slice(nl + 1);
-                    if (line) {
-                        let result;
-                        try {
-                            const args = JSON.parse(line);
-                            result = await dispatch(args);
+                if (draining)
+                    return;
+                draining = true;
+                socket.setTimeout(0);
+                try {
+                    let nl = buf.indexOf("\n");
+                    while (nl !== -1) {
+                        const line = buf.slice(0, nl).trim();
+                        buf = buf.slice(nl + 1);
+                        if (line) {
+                            let result;
+                            try {
+                                const parsed = JSON.parse(line);
+                                const taken = takeServeToken(parsed);
+                                if (taken.token !== token) {
+                                    result = unauthorized();
+                                }
+                                else {
+                                    result = await dispatch(taken.request);
+                                }
+                            }
+                            catch (err) {
+                                const message = err instanceof Error ? err.message : String(err);
+                                result = { ok: false, error: { code: "bad_arg", message } };
+                            }
+                            if (!socket.destroyed) {
+                                socket.write(`${JSON.stringify(result)}\n`);
+                            }
                         }
-                        catch (err) {
-                            const message = err instanceof Error ? err.message : String(err);
-                            result = { ok: false, error: { code: "bad_arg", message } };
-                        }
-                        socket.write(`${JSON.stringify(result)}\n`);
+                        nl = buf.indexOf("\n");
+                    }
+                }
+                finally {
+                    draining = false;
+                    if (socket.destroyed)
+                        return;
+                    if (buf.includes("\n")) {
+                        void drain();
+                    }
+                    else {
+                        socket.setTimeout(idleTimeoutMs);
                     }
-                    nl = buf.indexOf("\n");
                 }
             }
         });
@@ -69,8 +182,10 @@ export function startServe(listen, dispatch) {
             const addr = server.address();
             const actualPort = typeof addr === "object" && addr ? addr.port : port;
             resolve({
-                label: `${host}:${actualPort}`,
+                label: formatListenLabel(host, actualPort),
                 close: () => new Promise((done, fail) => {
+                    for (const open of sockets)
+                        open.destroy();
                     server.close((err) => (err ? fail(err) : done()));
                 }),
             });
@@ -80,8 +195,11 @@ export function startServe(listen, dispatch) {
 export function parseServeTarget(raw) {
     return parseListenAddress(raw);
 }
-export function callServe(target, args, timeoutMs = 15_000) {
+export function callServe(target, args, timeoutMs = 15_000, token) {
     const { host, port } = parseServeTarget(target);
+    const payload = token && token.trim()
+        ? { ...args, [SERVE_TOKEN_FIELD]: token.trim() }
+        : args;
     return new Promise((resolve) => {
         const socket = connect({ host, port });
         let buf = "";
@@ -130,12 +248,28 @@ export function callServe(target, args, timeoutMs = 15_000) {
             }
         });
         socket.on("connect", () => {
-            socket.write(`${JSON.stringify(args)}\n`);
+            socket.write(`${JSON.stringify(payload)}\n`);
         });
     });
 }
-export function serveLogonCommand(execPath, scriptPath, listen) {
-    return `"${execPath}" "${scriptPath}" serve --listen ${listen}`;
+export function serveLogonCommand(execPath, scriptPath, listen, token) {
+    const launch = `"${execPath}" "${scriptPath}" serve --listen ${listen}`;
+    const secret = token?.trim();
+    if (!secret)
+        return launch;
+    if (/[\0\r\n"%]/.test(secret)) {
+        throw new ZellijError("bad_arg", "ZSWARM_SERVE_TOKEN must not contain quotes, newlines, or %");
+    }
+    return `set "ZSWARM_SERVE_TOKEN=${secret}"&& ${launch}`;
+}
+function serveInstallToken(input) {
+    const raw = input.token ??
+        (input.env ? input.env.ZSWARM_SERVE_TOKEN : process.env.ZSWARM_SERVE_TOKEN);
+    const secret = raw?.trim() ?? "";
+    if (!secret) {
+        throw new ZellijError("serve_auth", "zswarm serve requires ZSWARM_SERVE_TOKEN; another local OS user can connect to 127.0.0.1");
+    }
+    return secret;
 }
 function runPowerShell(script) {
     return new Promise((resolve) => {
@@ -163,13 +297,17 @@ export async function installServeLogon(input) {
     if ((input.platform ?? process.platform) !== "win32") {
         throw new ZellijError("usage", "serve --install registers a Windows logon task; on Unix start `zswarm serve --listen` in the session that owns Zellij");
     }
-    const { label } = parseListenAddress(input.listen);
+    const { host, label } = parseListenAddress(input.listen);
+    if (!isLoopbackHost(host)) {
+        throw new ZellijError("serve_auth", `zswarm serve only listens on loopback (127.0.0.1 / ::1); off-machine access is an SSH tunnel to 127.0.0.1 (${host} refused)`);
+    }
+    const token = serveInstallToken(input);
     const execPath = input.execPath ?? process.execPath;
     const scriptPath = input.scriptPath ?? process.argv[1];
     if (!scriptPath) {
         throw new ZellijError("usage", "cannot resolve the zswarm script path for the logon task");
     }
-    const command = serveLogonCommand(execPath, scriptPath, label);
+    const command = serveLogonCommand(execPath, scriptPath, label, token);
     const commandB64 = Buffer.from(command, "utf8").toString("base64");
     const script = [
         "$cmd = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('" +
@@ -191,7 +329,19 @@ export async function uninstallServeLogon(input = {}) {
     if ((input.platform ?? process.platform) !== "win32") {
         throw new ZellijError("usage", "serve --clear is Windows-only");
     }
-    const script = `Unregister-ScheduledTask -TaskName '${SERVE_TASK_NAME}' -Confirm:$false -ErrorAction SilentlyContinue`;
-    await runPowerShell(script);
+    const script = [
+        "$ProgressPreference = 'SilentlyContinue'",
+        "try {",
+        `  Unregister-ScheduledTask -TaskName '${SERVE_TASK_NAME}' -Confirm:$false`,
+        "} catch {",
+        "  if ($_.CategoryInfo.Category -eq 'ObjectNotFound') { exit 0 }",
+        "  [Console]::Error.Write(($_ | Out-String).Trim())",
+        "  exit 1",
+        "}",
+    ].join("\n");
+    const result = await runPowerShell(script);
+    if (result.code !== 0) {
+        throw new ZellijError("zellij_failed", `serve --clear failed: ${(result.stderr || result.stdout).trim() || "no output"}`);
+    }
     return { task: SERVE_TASK_NAME, cleared: true };
 }

package/dist/ops/worktree.js

@@ -120,8 +120,15 @@ export async function removePeerWorktree(git, client, args, env = process.env) {
         const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
         occupants = panesIn(await client.listPanes(session), target.path);
     }
-    catch {
-        // No live session means nobody is working in it.
+    catch (err) {
+        // No live session means nobody is working in it. Any other failure must
+        // not look like "empty" — that is how a clean busy worktree gets deleted.
+        if (err instanceof ZellijError && err.code === "zellij_no_session") {
+            occupants = [];
+        }
+        else {
+            throw err;
+        }
     }
     if (occupants.length > 0 && !force) {
         throw new ZellijError("worktree_busy", `${occupants.join(", ")} still working in ${target.path}; close the pane or pass force=true`);

package/dist/policy.js

@@ -7,6 +7,12 @@ const WRITE_OPS = new Set([
     "spawn",
     "close",
     "unworktree",
+    "checkpoint",
+    "signal",
+    "rename",
+    "focus",
+    "stack",
+    "serve",
 ]);
 /** Explicit disable tokens for ZSWARM_ALLOW_* switches. */
 function isDisabled(raw) {

package/dist/schema.js

@@ -150,7 +150,7 @@ export const PARAMS = [
         name: "from",
         type: "string",
         flags: ["--from", "-f"],
-        description: "send: sender label in the [zswarm from=…] prefix",
+        description: "send: sender label in the [zswarm from=…] prefix (default: ZSWARM_FROM, else the sending pane's title, else swarm)",
     },
     {
         name: "raw",
@@ -447,7 +447,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, then list and status use it now.", "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.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE", "");
+    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, then list and status use it now.", "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 off loopback).", "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", "");
     return lines.join("\n");
 }
 /** Turn argv (without the op) into dispatch args, driven by PARAMS. */
@@ -465,10 +465,22 @@ function extractOp(argv) {
         return { op: first, rest: argv.slice(1) };
     }
     const names = OP_NAMES;
-    const at = argv.findIndex((token) => names.includes(token));
-    if (at === -1)
-        return { op: first ?? "", rest: argv.slice(1) };
-    return { op: argv[at], rest: [...argv.slice(0, at), ...argv.slice(at + 1)] };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith("-")) {
+            const param = FLAG_INDEX.get(token);
+            if (param && param.type !== "boolean")
+                i += 1;
+            continue;
+        }
+        if (names.includes(token)) {
+            return {
+                op: token,
+                rest: [...argv.slice(0, i), ...argv.slice(i + 1)],
+            };
+        }
+    }
+    return { op: first ?? "", rest: argv.slice(1) };
 }
 export function parseCliArgv(argv) {
     const { op, rest } = extractOp(argv);

package/dist/state.js

@@ -1,12 +1,18 @@
-import { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const LOG_FILE = "log.jsonl";
 const SIGNALS_FILE = "signals.json";
+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;
+const LOCK_WAIT_MS = 5_000;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 export function defaultStateDir(env = process.env) {
     const explicit = env.ZSWARM_STATE_DIR?.trim();
     if (explicit)
@@ -72,43 +78,149 @@ export function createStateStore(options = {}) {
         }
         return out;
     }
+    function pidAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (err) {
+            // ESRCH: gone. EPERM: exists, just unsignalable — still a live holder.
+            return err.code === "EPERM";
+        }
+    }
+    /** Owner recorded in the lock file so a crash can be distinguished from a live holder. */
+    function readLockOwner(lockPath) {
+        try {
+            const rec = JSON.parse(readFileSync(lockPath, "utf8"));
+            if (typeof rec.pid !== "number" || !Number.isInteger(rec.pid) || rec.pid <= 0)
+                return null;
+            const at = typeof rec.at === "number" ? rec.at : 0;
+            return { pid: rec.pid, at };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Dead pid → steal now. 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)
+            return !pidAlive(owner.pid);
+        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.
+        return (code === "EEXIST" ||
+            code === "EPERM" ||
+            code === "EACCES" ||
+            code === "EBUSY");
+    }
+    function unlinkLock(lockPath) {
+        const until = Date.now() + 500;
+        while (true) {
+            try {
+                rmSync(lockPath, { force: true });
+                return;
+            }
+            catch (err) {
+                if (!lockBusy(err.code) || Date.now() >= until) {
+                    return;
+                }
+                sleepSync(10);
+            }
+        }
+    }
+    function withFileLock(lockName, fn) {
+        ensureDir();
+        const lockPath = join(dir, lockName);
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        while (true) {
+            try {
+                const fd = openSync(lockPath, "wx");
+                try {
+                    writeFileSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
+                    return fn();
+                }
+                finally {
+                    closeSync(fd);
+                    unlinkLock(lockPath);
+                }
+            }
+            catch (err) {
+                const code = err.code;
+                if (!lockBusy(code))
+                    throw err;
+                if (code === "EEXIST" && lockIsStale(lockPath)) {
+                    unlinkLock(lockPath);
+                    continue;
+                }
+                if (Date.now() >= deadline) {
+                    throw new Error(`timed out waiting for ${lockName}`);
+                }
+                sleepSync(10);
+            }
+        }
+    }
+    function withSignalsLock(fn) {
+        return withFileLock(SIGNALS_LOCK, fn);
+    }
     function readSignals() {
         return readJson(SIGNALS_FILE, {});
     }
     function postSignal(channel, payload, at) {
-        const all = readSignals();
-        const prev = all[channel];
-        const next = {
-            count: (prev?.count ?? 0) + 1,
-            at,
-            last: payload,
-        };
-        all[channel] = next;
-        writeJson(SIGNALS_FILE, all);
-        return next;
+        return withSignalsLock(() => {
+            const all = readSignals();
+            const prev = all[channel];
+            const next = {
+                count: (prev?.count ?? 0) + 1,
+                at,
+                last: payload,
+            };
+            all[channel] = next;
+            writeJson(SIGNALS_FILE, all);
+            return next;
+        });
     }
     function clearSignal(channel) {
-        if (channel === null) {
-            writeJson(SIGNALS_FILE, {});
-            return;
-        }
-        const all = readSignals();
-        delete all[channel];
-        writeJson(SIGNALS_FILE, all);
+        withSignalsLock(() => {
+            if (channel === null) {
+                writeJson(SIGNALS_FILE, {});
+                return;
+            }
+            const all = readSignals();
+            delete all[channel];
+            writeJson(SIGNALS_FILE, all);
+        });
     }
     function readCursor(key) {
         const all = readJson(CURSORS_FILE, {});
         return all[key] ?? null;
     }
     function writeCursor(key, text) {
-        const all = readJson(CURSORS_FILE, {});
-        all[key] = text;
-        writeJson(CURSORS_FILE, all);
+        withFileLock(CURSORS_LOCK, () => {
+            const all = readJson(CURSORS_FILE, {});
+            all[key] = text;
+            writeJson(CURSORS_FILE, all);
+        });
     }
     function clearCursor(key) {
-        const all = readJson(CURSORS_FILE, {});
-        delete all[key];
-        writeJson(CURSORS_FILE, all);
+        withFileLock(CURSORS_LOCK, () => {
+            const all = readJson(CURSORS_FILE, {});
+            delete all[key];
+            writeJson(CURSORS_FILE, all);
+        });
     }
     function readBus() {
         const value = readJson(BUS_FILE, null);

package/dist/zellij/binary.d.ts

@@ -10,10 +10,12 @@ export declare function resolveZellijBinary(env?: NodeJS.ProcessEnv): string;
 export declare function sanitizeZellijEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**
  * Remote crew: `ZSWARM_SSH=user@host` routes every zellij call over ssh.
- * `ZSWARM_SSH_OPTS` is split on whitespace; `BatchMode` keeps it non-interactive.
+ * `ZSWARM_SSH_OPTS` is split like a shell so quoted paths stay one arg;
+ * `BatchMode` keeps it non-interactive.
  * `ZSWARM_TMP` points at the interactive session's temp (or `auto` to discover).
  * `ZSWARM_SSH_MODE=interactive` runs each call in the Windows desktop session.
  */
+export declare function parseSshOpts(raw: string): string[];
 export declare function resolveSshTarget(env?: NodeJS.ProcessEnv): SshTarget | null;
 /** Runner bound to the resolved zellij binary and a cleaned environment. */
 export declare function defaultExec(zellijPath: string, env: NodeJS.ProcessEnv): ZellijExecFn;

package/dist/zellij/binary.js

@@ -75,15 +75,47 @@ export function sanitizeZellijEnv(env) {
 }
 /**
  * Remote crew: `ZSWARM_SSH=user@host` routes every zellij call over ssh.
- * `ZSWARM_SSH_OPTS` is split on whitespace; `BatchMode` keeps it non-interactive.
+ * `ZSWARM_SSH_OPTS` is split like a shell so quoted paths stay one arg;
+ * `BatchMode` keeps it non-interactive.
  * `ZSWARM_TMP` points at the interactive session's temp (or `auto` to discover).
  * `ZSWARM_SSH_MODE=interactive` runs each call in the Windows desktop session.
  */
+export function parseSshOpts(raw) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                cur += ch;
+            }
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (/\s/.test(ch)) {
+            if (cur.length > 0) {
+                out.push(cur);
+                cur = "";
+            }
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (cur.length > 0)
+        out.push(cur);
+    return out;
+}
 export function resolveSshTarget(env = process.env) {
     const host = env.ZSWARM_SSH?.trim();
     if (!host)
         return null;
-    const options = (env.ZSWARM_SSH_OPTS ?? "").trim().split(/\s+/).filter(Boolean);
+    const options = parseSshOpts(env.ZSWARM_SSH_OPTS ?? "");
     if (!options.some((o) => o.startsWith("BatchMode"))) {
         options.unshift("-o", "BatchMode=yes");
     }

package/dist/zellij/client.js

@@ -5,7 +5,7 @@ import { parseTabList, resolveTab } from "./tabs.js";
 import { createSshExec } from "../exec.js";
 import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, } from "./binary.js";
 import { normalizePaneId, parsePaneList, resolvePane, } from "./panes.js";
-import { parseSessionList, resolveSelfPaneId, sessionFromEnv, sessionFromList, } from "./session.js";
+import { isZellijNoSessionsOutput, parseSessionList, resolveSelfPaneId, sessionFromEnv, sessionFromList, } from "./session.js";
 /** Thin, stateless wrapper over the `zellij` binary. */
 export function createZellijClient(options = {}) {
     const env = options.env ?? process.env;
@@ -30,7 +30,20 @@ export function createZellijClient(options = {}) {
         return result;
     }
     async function listSessions() {
-        const result = await run(["list-sessions", "--short", "--no-formatting"], "zellij list-sessions");
+        const result = await exec(["list-sessions", "--short", "--no-formatting"], {
+            timeoutMs,
+        });
+        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`);
+        }
+        if (result.code !== 0) {
+            // Nonzero here is Zellij's normal "none running", not a crash. Empty
+            // lets resolveSession throw zellij_no_session so unworktree can treat
+            // it as no occupants instead of zellij_failed.
+            if (isZellijNoSessionsOutput(result.stdout, result.stderr))
+                return [];
+            throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${result.stderr.trim() || result.stdout.trim() || "no output"}`);
+        }
         return parseSessionList(result.stdout);
     }
     async function resolveSession(explicit) {