@zswarm/core 0.1.4 → 0.1.6

package/dist/schema.js

@@ -42,6 +42,9 @@ export const TARGET_OPS = [
     "keys",
     "interrupt",
     "close",
+    "rename",
+    "focus",
+    "stack",
 ];
 export const PARAMS = [
     {
@@ -60,7 +63,25 @@ export const PARAMS = [
         name: "all",
         type: "boolean",
         flags: ["--all", "-a"],
-        description: "broadcast: every terminal pane in the session",
+        description: "broadcast: every terminal pane in the session; sessions: include EXITED resurrectable sessions",
+    },
+    {
+        name: "live",
+        type: "boolean",
+        flags: ["--live", "--active"],
+        description: "sessions: only live (non-EXITED) sessions — this is the default; use --all to include EXITED",
+    },
+    {
+        name: "local",
+        type: "boolean",
+        flags: ["--local"],
+        description: "route this call to the local machine only — clears ZSWARM_SSH, ZSWARM_SERVE, and remote ZSWARM_TMP for the invocation",
+    },
+    {
+        name: "ssh",
+        type: "string",
+        flags: ["--ssh"],
+        description: "route this call over SSH to user@host (or an alias) for the invocation; clears ZSWARM_SERVE; put flags in ZSWARM_SSH_OPTS",
     },
     {
         name: "group",
@@ -140,6 +161,13 @@ export const PARAMS = [
         flags: ["--body", "-b", "--text"],
         description: "send: message body",
     },
+    {
+        name: "bodyFile",
+        type: "string",
+        flags: ["--body-file"],
+        cliOnly: true,
+        description: "send: read UTF-8 on the caller from PATH, or - for stdin; cannot combine with --body/--text",
+    },
     {
         name: "text",
         type: "string",
@@ -217,7 +245,7 @@ export const PARAMS = [
         name: "timeoutMs",
         type: "number",
         flags: ["--timeout-ms"],
-        description: "wait: give up after this long (default 60000)",
+        description: "wait: timeout (default 60000); status/spawn: overall deadline (default 30000), including setup and observation",
     },
     {
         name: "keys",
@@ -299,6 +327,12 @@ export const PARAMS = [
         values: ["auto", "double-enter", "none"],
         description: "send/broadcast: auto verifies the paste actually submitted and presses Enter again if not (default)",
     },
+    {
+        name: "observeMs",
+        type: "number",
+        flags: ["--observe-ms"],
+        description: "spawn: observe creation/alias for up to 3000ms; pane lookup: retry absence for 1000ms; 0 disables retries",
+    },
     {
         name: "settleMs",
         type: "number",
@@ -309,7 +343,7 @@ export const PARAMS = [
         name: "expect",
         type: "string",
         flags: ["--expect"],
-        description: "text the target pane's screen must contain before zswarm will write to it",
+        description: "send/keys/interrupt: case-insensitive substring required on the current screen immediately before input",
     },
     {
         name: "message",
@@ -382,7 +416,7 @@ export const PARAMS = [
         name: "force",
         type: "boolean",
         flags: ["--force"],
-        description: "send/keys: write to a pane whose command has exited; unworktree: remove a busy or dirty worktree; bus: reinstall under a fresh key",
+        description: "send/keys: write to a pane whose command has exited; unworktree: remove a busy or dirty worktree; bus: close orphan bus panes and reload this session's plugin",
     },
     {
         name: "listen",
@@ -420,8 +454,10 @@ export function mcpInputSchema() {
             description: OP_NAMES.join(" | "),
         },
     };
-    for (const param of PARAMS)
-        properties[param.name] = propertyFor(param);
+    for (const param of PARAMS) {
+        if (!param.cliOnly)
+            properties[param.name] = propertyFor(param);
+    }
     return {
         type: "object",
         additionalProperties: false,
@@ -447,7 +483,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 (+ 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", "");
+    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", "");
     return lines.join("\n");
 }
 /** Turn argv (without the op) into dispatch args, driven by PARAMS. */
@@ -496,6 +532,9 @@ export function parseCliArgv(argv) {
                 out[param.name] = true;
                 continue;
             }
+            if ((param.name === "body" || param.name === "bodyFile") && Object.hasOwn(out, param.name)) {
+                throw new ZellijError("usage", "provide exactly one body source");
+            }
             const value = rest[++i];
             if (value === undefined) {
                 throw new ZellijError("usage", `${token} needs a value`);
@@ -516,7 +555,7 @@ export function parseCliArgv(argv) {
             out.to = token;
             continue;
         }
-        if (!out.body && op === "send") {
+        if (!Object.hasOwn(out, "body") && op === "send") {
             out.body = token;
             continue;
         }
@@ -524,5 +563,8 @@ export function parseCliArgv(argv) {
     }
     for (const [name, values] of repeated)
         out[name] = values;
+    if (out.bodyFile !== undefined && (op !== "send" || out.body !== undefined || out.text !== undefined)) {
+        throw new ZellijError("usage", "--body-file requires send and cannot be combined with another body source");
+    }
     return out;
 }

package/dist/state.d.ts

@@ -19,9 +19,10 @@ export type SignalChannel = {
     last: string | null;
 };
 /**
- * Written once by `bus --install`, after the plugin's permission prompt has
- * been answered. Its presence is what lets later runs try the fast path without
- * every cold `zswarm status` paying for a pipe that was never going to answer.
+ * Written by `bus --install` per Zellij session, after the plugin's permission
+ * prompt has been answered. Its presence is what lets later runs try the fast
+ * path without every cold `zswarm status` paying for a pipe that was never
+ * going to answer.
  */
 export type BusMarkerRecord = {
     plugin: string;
@@ -44,9 +45,9 @@ export declare function createStateStore(options?: StateStoreOptions): {
     readCursor: (key: string) => string | null;
     writeCursor: (key: string, text: string) => void;
     clearCursor: (key: string) => void;
-    readBus: () => BusMarkerRecord | null;
-    writeBus: (marker: BusMarkerRecord) => void;
-    clearBus: () => void;
+    readBus: (session: string) => BusMarkerRecord | null;
+    writeBus: (session: string, marker: BusMarkerRecord) => void;
+    clearBus: (session?: string) => void;
     reset: () => void;
 };
 export type StateStore = ReturnType<typeof createStateStore>;

package/dist/state.js

@@ -10,6 +10,8 @@ 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;
+/** A live pid older than this is treated as a recycle of a crashed holder. */
+const LOCK_STALE_MS = 30_000;
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
@@ -102,16 +104,24 @@ export function createStateStore(options = {}) {
         }
     }
     /**
-     * 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.
+     * 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)
-            return !pidAlive(owner.pid);
+        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;
         }
@@ -162,7 +172,7 @@ export function createStateStore(options = {}) {
                 const code = err.code;
                 if (!lockBusy(code))
                     throw err;
-                if (code === "EEXIST" && lockIsStale(lockPath)) {
+                if (lockIsStale(lockPath)) {
                     unlinkLock(lockPath);
                     continue;
                 }
@@ -222,22 +232,72 @@ export function createStateStore(options = {}) {
             writeJson(CURSORS_FILE, all);
         });
     }
-    function readBus() {
-        const value = readJson(BUS_FILE, null);
-        if (!value || typeof value.plugin !== "string" || !value.plugin)
+    function asMarker(value) {
+        if (!value || typeof value !== "object")
+            return null;
+        const rec = value;
+        if (typeof rec.plugin !== "string" || !rec.plugin)
+            return null;
+        if (typeof rec.configKey !== "string" || !rec.configKey)
             return null;
-        return value;
+        return {
+            plugin: rec.plugin,
+            configKey: rec.configKey,
+            installedAt: typeof rec.installedAt === "number" ? rec.installedAt : 0,
+        };
     }
-    function writeBus(marker) {
-        writeJson(BUS_FILE, marker);
+    /**
+     * Current `{ sessions: { <name>: marker } }` plus the pre-0.1.6 flat file
+     * `{ plugin, configKey, installedAt }`, which any session may inherit until
+     * the next write namespaces it.
+     */
+    function readBusFile() {
+        const raw = readJson(BUS_FILE, null);
+        if (!raw || typeof raw !== "object")
+            return { sessions: {}, legacy: null };
+        const sessions = {};
+        if (raw.sessions && typeof raw.sessions === "object") {
+            for (const [name, marker] of Object.entries(raw.sessions)) {
+                const parsed = asMarker(marker);
+                if (parsed)
+                    sessions[name] = parsed;
+            }
+        }
+        return { sessions, legacy: asMarker(raw) };
     }
-    function clearBus() {
-        try {
-            rmSync(join(dir, BUS_FILE), { force: true });
+    function readBus(session) {
+        if (!session)
+            return null;
+        const { sessions, legacy } = readBusFile();
+        return sessions[session] ?? legacy;
+    }
+    function writeBus(session, marker) {
+        const { sessions } = readBusFile();
+        sessions[session] = marker;
+        writeJson(BUS_FILE, { sessions });
+    }
+    function clearBus(session) {
+        if (!session) {
+            try {
+                rmSync(join(dir, BUS_FILE), { force: true });
+            }
+            catch {
+                // Nothing to forget.
+            }
+            return;
         }
-        catch {
-            // Nothing to forget.
+        const { sessions } = readBusFile();
+        delete sessions[session];
+        if (Object.keys(sessions).length === 0) {
+            try {
+                rmSync(join(dir, BUS_FILE), { force: true });
+            }
+            catch {
+                // Nothing to forget.
+            }
+            return;
         }
+        writeJson(BUS_FILE, { sessions });
     }
     /** Test helper: drop everything this store wrote. */
     function reset() {

package/dist/zellij/args.d.ts

@@ -1,6 +1,7 @@
 export type PaneDirection = "right" | "left" | "up" | "down";
 export type NewPaneInput = {
     session: string;
+    timeoutMs?: number;
     command?: string[];
     cwd?: string | null;
     name?: string | null;
@@ -13,6 +14,7 @@ export type NewPaneInput = {
 };
 export type NewTabInput = {
     session: string;
+    timeoutMs?: number;
     command?: string[];
     cwd?: string | null;
     name?: string | null;
@@ -47,6 +49,8 @@ export type WaitRequest = {
     idleMs?: number;
     timeoutMs?: number;
     pollMs?: number;
+    /** Read scrollback above the viewport, matching dump --full. */
+    full?: boolean;
 };
 /**
  * `regex` is deliberately absent: the plugin has no regex engine, refuses such

package/dist/zellij/args.js

@@ -35,6 +35,7 @@ export function waitPayload(req) {
         idleMs: req.idleMs ?? 2000,
         timeoutMs: req.timeoutMs ?? 60000,
         pollMs: req.pollMs ?? 50,
+        full: req.full === true,
     });
 }
 /** Screens plus "did this move since you last asked", so status needs no gap. */

package/dist/zellij/binary.d.ts

@@ -6,6 +6,40 @@ export declare const DEFAULT_TIMEOUT_MS = 15000;
 export { NOT_FOUND_EXIT };
 /** Expand a leading `~/` or `~\` using USERPROFILE/HOME. */
 export declare function expandHomePath(input: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * True when a path (or basename) is the zswarm CLI rather than Zellij.
+ * Setting ZSWARM_BIN to zswarm makes `list-sessions --short` fail with
+ * "unknown arg: --short" because zswarm re-parses argv as its own CLI.
+ */
+export declare function looksLikeZswarmBinary(path: string): boolean;
+export declare function assertZellijBinaryPath(path: string): void;
+/**
+ * ZSWARM_SSH is a destination, not a full ssh argv.
+ * Accept `user@host` or an SSH config alias; put flags in ZSWARM_SSH_OPTS.
+ */
+export declare function validateSshDestination(raw: string): string;
+export declare function validateSshMode(raw: string): "ssh" | "interactive";
+/** True when `--version` output is positively Zellij. */
+export declare function isZellijVersionOutput(stdout: string, stderr?: string): boolean;
+/**
+ * Cache key covering the resolved binary and SSH routing that can change the
+ * actual remote executable (opts, mode, remote bin).
+ */
+export declare function identityCacheKey(zellijPath: string, ssh?: {
+    host: string;
+    options: string[];
+    mode?: string;
+    remoteBin?: 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.
+ */
+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>;
+/** Test helper: drop cached identity/capability probes. */
+export declare function resetZellijIdentityCache(): void;
 export declare function resolveZellijBinary(env?: NodeJS.ProcessEnv): string;
 export declare function sanitizeZellijEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**

package/dist/zellij/binary.js

@@ -1,6 +1,7 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { delimiter, join } from "node:path";
+import { basename, delimiter, join } from "node:path";
+import { ZellijError } from "../errors.js";
 import { createExec, createSshExec, NOT_FOUND_EXIT, } from "../exec.js";
 import { applyIpcTmpEnv } from "./ipc.js";
 export { createSshExec };
@@ -16,15 +17,174 @@ export function expandHomePath(input, env = process.env) {
         return trimmed;
     return join(home, trimmed.slice(2));
 }
+/**
+ * True when a path (or basename) is the zswarm CLI rather than Zellij.
+ * Setting ZSWARM_BIN to zswarm makes `list-sessions --short` fail with
+ * "unknown arg: --short" because zswarm re-parses argv as its own CLI.
+ */
+export function looksLikeZswarmBinary(path) {
+    const trimmed = path.trim();
+    const base = basename(trimmed).toLowerCase();
+    // Windows paths on a Linux host still use backslashes in env values.
+    const winBase = trimmed.replace(/\\/g, "/").split("/").pop()?.toLowerCase() ?? base;
+    const name = winBase || base;
+    if (/^zswarm(\.(exe|cmd|js|mjs|cjs))?$/.test(name))
+        return true;
+    // Native binaries are never the Node CLI wrapper.
+    if (/\.(exe|dll|so|dylib)$/i.test(name))
+        return false;
+    if (name === "zellij")
+        return false;
+    // Shebang wrappers may keep another basename; sniff a short readable prefix.
+    try {
+        if (!existsSync(trimmed))
+            return false;
+        const head = readFileSync(trimmed, { encoding: "utf8" }).slice(0, 400);
+        if (head.includes("\0"))
+            return false;
+        return /@zswarm\/cli/.test(head) || /usage:\s*zswarm/i.test(head);
+    }
+    catch {
+        return false;
+    }
+}
+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)`);
+}
+/**
+ * ZSWARM_SSH is a destination, not a full ssh argv.
+ * Accept `user@host` or an SSH config alias; put flags in ZSWARM_SSH_OPTS.
+ */
+export function validateSshDestination(raw) {
+    const host = raw.trim();
+    if (!host) {
+        throw new ZellijError("bad_ssh", "ZSWARM_SSH is empty");
+    }
+    if (/^ssh(\s|$)/i.test(host)) {
+        throw new ZellijError("bad_ssh", `ZSWARM_SSH should be user@host or an SSH alias, not a full ssh command. Put flags in ZSWARM_SSH_OPTS. Got: ${JSON.stringify(host)}`);
+    }
+    // Leading dashes are SSH options (`-V`, `-F…`, `-o…`), not destinations.
+    if (host.startsWith("-")) {
+        throw new ZellijError("bad_ssh", `ZSWARM_SSH looks like an SSH option (${JSON.stringify(host)}); put flags in ZSWARM_SSH_OPTS and set ZSWARM_SSH to user@host or an alias`);
+    }
+    if (/\s/.test(host)) {
+        throw new ZellijError("bad_ssh", `ZSWARM_SSH must be a single destination (user@host or alias); put options in ZSWARM_SSH_OPTS. Got: ${JSON.stringify(host)}`);
+    }
+    if (/[;|&$<>()]/.test(host)) {
+        throw new ZellijError("bad_ssh", `ZSWARM_SSH contains shell metacharacters; expected user@host or an SSH alias. Got: ${JSON.stringify(host)}`);
+    }
+    return host;
+}
+export function validateSshMode(raw) {
+    const mode = raw.trim().toLowerCase();
+    if (!mode || mode === "ssh")
+        return "ssh";
+    if (mode === "interactive")
+        return "interactive";
+    throw new ZellijError("bad_ssh_mode", `ZSWARM_SSH_MODE must be "interactive" or "ssh" (or unset); got ${JSON.stringify(raw.trim())}`);
+}
+/** Cache of verified `zellij --version` probes keyed by target identity. */
+const identityCache = new Set();
+/** True when `--version` output is positively Zellij. */
+export function isZellijVersionOutput(stdout, stderr = "") {
+    const text = `${stdout}\n${stderr}`;
+    return /\bzellij\s+\d+\.\d+/i.test(text) || /^\s*zellij\b/im.test(stdout);
+}
+/**
+ * Cache key covering the resolved binary and SSH routing that can change the
+ * actual remote executable (opts, mode, remote bin).
+ */
+export function identityCacheKey(zellijPath, ssh) {
+    if (!ssh)
+        return zellijPath;
+    return [
+        zellijPath,
+        ssh.host,
+        ssh.remoteBin ?? "",
+        ssh.mode ?? "ssh",
+        ssh.options.join("\0"),
+    ].join("|");
+}
+/**
+ * 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.
+ */
+export async function ensureZellijIdentity(exec, zellijPath, timeoutMs = 3_000, cacheKey = zellijPath) {
+    if (identityCache.has(cacheKey))
+        return true;
+    assertZellijBinaryPath(zellijPath);
+    const result = await exec(["--version"], {
+        timeoutMs: Math.min(timeoutMs, 5_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`);
+    }
+    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) {
+        if (isZellijVersionOutput(result.stdout, result.stderr)) {
+            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"}`);
+    }
+    // Timeout / transport failure: leave unresolved so a later call retries.
+    return false;
+}
+/**
+ * Probe that the target understands the session-list flags we rely on.
+ * Cached with the same key as identity once verified.
+ * Returns false when the transport cannot verify support.
+ */
+const capabilityCache = new Set();
+export async function ensureZellijCapabilities(exec, zellijPath, timeoutMs = 3_000, cacheKey = zellijPath) {
+    if (capabilityCache.has(cacheKey))
+        return true;
+    const result = await exec(["list-sessions", "--help"], {
+        timeoutMs: Math.min(timeoutMs, 5_000),
+    });
+    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})`);
+    }
+    if (result.code === NOT_FOUND_EXIT) {
+        throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath})`);
+    }
+    // Require the flags this client always passes.
+    if (result.code === 0 &&
+        /--no-formatting/i.test(text) &&
+        /list-sessions/i.test(text)) {
+        capabilityCache.add(cacheKey);
+        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`);
+    }
+    // Soft: leave unresolved on transport failure.
+    return false;
+}
+/** Test helper: drop cached identity/capability probes. */
+export function resetZellijIdentityCache() {
+    identityCache.clear();
+    capabilityCache.clear();
+}
 export function resolveZellijBinary(env = process.env) {
     const fromEnv = expandHomePath((env.ZSWARM_BIN ?? env.ZSWARM_PATH ?? env.ZELLIJ_BIN ?? "")
         .trim()
         .replace(/^['"]|['"]$/g, ""), env);
     if (fromEnv && existsSync(fromEnv)) {
+        assertZellijBinaryPath(fromEnv);
         if (/\.cmd$/i.test(fromEnv)) {
             const exe = fromEnv.replace(/\.cmd$/i, ".exe");
-            if (existsSync(exe))
+            if (existsSync(exe)) {
+                assertZellijBinaryPath(exe);
                 return exe;
+            }
             const wingetExe = join(env.LOCALAPPDATA ||
                 join(env.USERPROFILE || env.HOME || homedir(), "AppData", "Local"), "Zellij", "zellij.exe");
             if (existsSync(wingetExe))
@@ -112,17 +272,18 @@ export function parseSshOpts(raw) {
     return out;
 }
 export function resolveSshTarget(env = process.env) {
-    const host = env.ZSWARM_SSH?.trim();
-    if (!host)
+    const raw = env.ZSWARM_SSH?.trim();
+    if (!raw)
         return null;
+    const host = validateSshDestination(raw);
     const options = parseSshOpts(env.ZSWARM_SSH_OPTS ?? "");
     if (!options.some((o) => o.startsWith("BatchMode"))) {
         options.unshift("-o", "BatchMode=yes");
     }
     const shellRaw = (env.ZSWARM_REMOTE_SHELL ?? "").trim().toLowerCase();
-    const modeRaw = (env.ZSWARM_SSH_MODE ?? "").trim().toLowerCase();
+    const mode = validateSshMode(env.ZSWARM_SSH_MODE ?? "");
     const tmpRaw = env.ZSWARM_TMP?.trim();
-    const interactive = modeRaw === "interactive";
+    const interactive = mode === "interactive";
     return {
         ssh: env.ZSWARM_SSH_BIN?.trim() || "ssh",
         host,
@@ -130,7 +291,7 @@ export function resolveSshTarget(env = process.env) {
         options,
         // Interactive tasks do not inherit the desktop TEMP; discover it unless set.
         tmp: tmpRaw || (interactive ? "auto" : undefined),
-        mode: interactive ? "interactive" : "ssh",
+        mode,
         remoteShell: shellRaw === "cmd" || shellRaw === "sh" ? shellRaw : undefined,
     };
 }

package/dist/zellij/bus.d.ts

@@ -23,6 +23,8 @@ export type BusSnapshot = {
     paneUpdates: number;
     tabUpdates: number;
     tabs: string[];
+    /** Stable IDs by tab position; absent on older running plugin instances. */
+    tabIds?: (number | null)[];
     panes: BusPane[];
 };
 export type BusMarker = {
@@ -67,6 +69,15 @@ export declare function resolveBusPlugin(env?: NodeJS.ProcessEnv): string | null
 export declare function busPluginUrl(pluginPath: string): string;
 /** zswarm-bus → zswarm-bus-2 → zswarm-bus-3: a fresh pipe destination each time. */
 export declare function nextConfigKey(key: string): string;
+/**
+ * Plugin panes belonging to this bus — never tab-bar / status-bar / room.
+ * Titles are the `file:` URL (or the wasm basename) Zellij shows for the pane.
+ */
+export declare function isBusPluginPane(pane: {
+    isPlugin?: boolean;
+    title?: string;
+    command?: string | null;
+}, pluginPath?: string | null): boolean;
 /**
  * Pull the plugin's answer out of the pipe. Zellij interleaves its own notices
  * ("Action CliPipe did not complete within 1s timeout" shows up on successful

package/dist/zellij/bus.js

@@ -140,6 +140,26 @@ export function nextConfigKey(key) {
         return `${key}-2`;
     return `${match[1]}-${Number(match[2]) + 1}`;
 }
+/**
+ * Plugin panes belonging to this bus — never tab-bar / status-bar / room.
+ * Titles are the `file:` URL (or the wasm basename) Zellij shows for the pane.
+ */
+export function isBusPluginPane(pane, pluginPath) {
+    if (!pane.isPlugin)
+        return false;
+    const hay = `${pane.title ?? ""}\n${pane.command ?? ""}`
+        .replace(/\\/g, "/")
+        .toLowerCase();
+    if (hay.includes("zswarm-bus") || hay.includes("zswarm-events"))
+        return true;
+    if (!pluginPath)
+        return false;
+    const normalized = pluginPath.replace(/\\/g, "/").toLowerCase();
+    if (normalized && hay.includes(normalized))
+        return true;
+    const base = normalized.split("/").pop();
+    return Boolean(base && hay.includes(base));
+}
 function toSnapshot(value) {
     if (value.ok !== true || !Array.isArray(value.panes))
         return null;
@@ -166,6 +186,7 @@ function toSnapshot(value) {
         tabs: Array.isArray(value.tabs)
             ? value.tabs.filter((t) => typeof t === "string")
             : [],
+        ...(Array.isArray(value.tabIds) ? { tabIds: value.tabIds.map((id) => typeof id === "number" && Number.isInteger(id) && id >= 0 ? id : null) } : {}),
         panes,
     };
 }
@@ -270,7 +291,7 @@ export function busToPanes(snapshot) {
             command: pane.command,
             cwd: null,
             tabName: snapshot.tabs[pane.tab] ?? null,
-            tabId: pane.tab,
+            tabId: snapshot.tabIds?.[pane.tab] ?? null,
             focused: pane.focused,
             exited: pane.exited,
             floating: false,