@zswarm/core 0.1.5 → 0.1.6

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 = {

package/dist/zellij/bus.js

@@ -186,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,
     };
 }
@@ -290,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,

package/dist/zellij/client.d.ts

@@ -1,24 +1,38 @@
 import { buildClosePaneArgs, buildDumpArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, type WaitRequest, type LaunchPluginInput, type NewPaneInput, type NewTabInput, type PipeInput } from "./args.js";
 import { resolveTab, type ZellijTab } from "./tabs.js";
+import { type IpcDiscoveryState } from "../exec.js";
 import { type ZellijExecFn } from "./binary.js";
 import { normalizePaneId, resolvePane, type ZellijPane } from "./panes.js";
-import { type ZellijSessionResolve } from "./session.js";
+import { type ZellijSession, type ZellijSessionResolve } from "./session.js";
 export type ZellijClientOptions = {
     exec?: ZellijExecFn;
     zellijPath?: string;
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
     signal?: AbortSignal;
+    /** Skip the one-time `zellij --version` identity probe (tests). */
+    skipIdentityProbe?: boolean;
+};
+export type ZellijTransport = {
+    kind: "local" | "ssh";
+    mode: "local" | "ssh" | "interactive";
+    host?: string;
+    remoteBin?: string;
+    /** Configured or resolved IPC temp (`auto` until discovery succeeds). */
+    tmp?: string;
+    /** Outcome of `ZSWARM_TMP=auto` discovery when SSH routing is active. */
+    ipc?: IpcDiscoveryState;
 };
 /** Thin, stateless wrapper over the `zellij` binary. */
 export declare function createZellijClient(options?: ZellijClientOptions): {
     zellijPath: string;
     selfPaneId: string | null;
+    readonly transport: ZellijTransport;
     /** A `file:` plugin url only names a path on the machine running Zellij. */
     remote: boolean;
-    listSessions: () => Promise<string[]>;
-    resolveSession: (explicit?: string | null) => Promise<ZellijSessionResolve>;
-    listPanes: (session: string) => Promise<ZellijPane[]>;
+    listSessions: (callTimeoutMs?: number) => Promise<ZellijSession[]>;
+    resolveSession: (explicit?: string | null, callTimeoutMs?: number) => Promise<ZellijSessionResolve>;
+    listPanes: (session: string, callTimeoutMs?: number) => Promise<ZellijPane[]>;
     resolvePane: typeof resolvePane;
     injectPane: (input: {
         session: string;
@@ -32,6 +46,7 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
         session: string;
         paneId: string;
         full?: boolean;
+        timeoutMs?: number;
     }) => Promise<{
         paneId: string;
         session: string;
@@ -75,6 +90,7 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
         session: string;
         paneId: string;
         name: string;
+        timeoutMs?: number;
     }) => Promise<{
         paneId: string;
         session: string;
@@ -96,7 +112,7 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
         paneId: string;
         session: string;
     }>;
-    listTabs: (session: string) => Promise<ZellijTab[]>;
+    listTabs: (session: string, callTimeoutMs?: number) => Promise<ZellijTab[]>;
     dumpLayout: (session: string) => Promise<string>;
     stackPanes: (input: {
         session: string;
@@ -138,6 +154,7 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
         url: string;
         configKey: string;
         panes: string[];
+        timeoutMs?: number;
     }) => Promise<{
         code: number;
         stdout: string;

package/dist/zellij/client.js

@@ -3,55 +3,115 @@ 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, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, } from "./binary.js";
+import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, ensureZellijCapabilities, ensureZellijIdentity, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, } from "./binary.js";
 import { normalizePaneId, parsePaneList, resolvePane, } from "./panes.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;
-    // A remote crew never resolves a local binary.
+    // A remote crew never resolves a local binary. An injected exec is a unit
+    // test (or in-process stand-in) — skip PATH/env resolution so a poisoned
+    // ZSWARM_BIN in the host environment cannot fail client construction.
     const ssh = options.exec ? null : resolveSshTarget(env);
     const zellijPath = options.zellijPath ??
-        (ssh ? `ssh://${ssh.host}/${ssh.remoteBin}` : resolveZellijBinary(env));
+        (options.exec
+            ? "zellij"
+            : ssh
+                ? `ssh://${ssh.host}/${ssh.remoteBin}`
+                : resolveZellijBinary(env));
+    const sshExec = options.exec || !ssh
+        ? null
+        : createSshExec(ssh, sanitizeZellijEnv(env));
     const rawExec = options.exec ??
-        (ssh
-            ? createSshExec(ssh, sanitizeZellijEnv(env))
-            : defaultExec(zellijPath, env));
+        (sshExec ? sshExec : defaultExec(zellijPath, env));
     const exec = (args, opts) => rawExec(args, { ...opts, signal: opts.signal ?? options.signal });
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const selfPaneId = resolveSelfPaneId(env);
-    async function run(args, label) {
-        const result = await exec(args, { timeoutMs });
+    const probeKey = identityCacheKey(zellijPath, ssh);
+    function readTransport() {
+        if (!ssh)
+            return { kind: "local", mode: "local" };
+        const ipc = sshExec?.ipcState;
+        return {
+            kind: "ssh",
+            mode: ssh.mode ?? "ssh",
+            host: ssh.host,
+            remoteBin: ssh.remoteBin,
+            tmp: ipc?.tmp ?? ssh.tmp,
+            ipc: ipc
+                ? {
+                    requested: ipc.requested,
+                    status: ipc.status,
+                    tmp: ipc.tmp,
+                    socketDir: ipc.socketDir,
+                }
+                : undefined,
+        };
+    }
+    function operationBudget(budget, label) {
+        const deadline = Date.now() + budget;
+        return () => {
+            if (options.signal?.aborted) {
+                throw new ZellijError("cancelled", "operation cancelled");
+            }
+            const left = deadline - Date.now();
+            if (left <= 0) {
+                throw new ZellijError("zellij_failed", `${label} timed out after ${budget}ms`);
+            }
+            return left;
+        };
+    }
+    async function ensureIdentity(remaining) {
+        if (options.skipIdentityProbe || options.exec)
+            return;
+        // Only the helpers' positively verified results are cached. In-flight or
+        // unresolved probes must not tie this call to another operation's budget.
+        await ensureZellijIdentity(exec, zellijPath, remaining(), probeKey);
+        await ensureZellijCapabilities(exec, zellijPath, remaining(), probeKey);
+    }
+    async function run(args, label, callTimeoutMs = timeoutMs) {
+        const remaining = operationBudget(callTimeoutMs, label);
+        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`);
         }
         if (result.code !== 0) {
-            throw new ZellijError("zellij_failed", `${label} failed (exit ${result.code}): ${result.stderr.trim() || result.stdout.trim() || "no output"}`);
+            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_failed", `${label} failed (exit ${result.code}): ${detail}`);
         }
         return result;
     }
-    async function listSessions() {
-        const result = await exec(["list-sessions", "--short", "--no-formatting"], {
-            timeoutMs,
+    async function listSessions(callTimeoutMs = timeoutMs) {
+        const remaining = operationBudget(callTimeoutMs, "zellij list-sessions");
+        await ensureIdentity(remaining);
+        // Keep annotations (EXITED / current); --short drops them.
+        const result = await exec(["list-sessions", "--no-formatting"], {
+            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`);
         }
         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.
+            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}`);
+            }
             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"}`);
+            throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${detail}`);
         }
         return parseSessionList(result.stdout);
     }
-    async function resolveSession(explicit) {
-        return sessionFromEnv(env, explicit) ?? sessionFromList(await listSessions());
+    async function resolveSession(explicit, callTimeoutMs = timeoutMs) {
+        return (sessionFromEnv(env, explicit) ??
+            sessionFromList(await listSessions(callTimeoutMs)));
     }
-    async function listPanes(session) {
-        const result = await run(buildListPanesArgs(session), "zellij action list-panes");
+    async function listPanes(session, callTimeoutMs = timeoutMs) {
+        const result = await run(buildListPanesArgs(session), "zellij action list-panes", callTimeoutMs);
         return parsePaneList(result.stdout);
     }
     async function injectPane(input) {
@@ -65,7 +125,7 @@ export function createZellijClient(options = {}) {
     }
     async function dumpPane(input) {
         const paneId = normalizePaneId(input.paneId);
-        const result = await run(buildDumpArgs(input.session, paneId, input.full), "zellij action dump-screen");
+        const result = await run(buildDumpArgs(input.session, paneId, input.full), "zellij action dump-screen", input.timeoutMs ?? timeoutMs);
         return { paneId, session: input.session, text: result.stdout };
     }
     async function sendKeys(input) {
@@ -89,7 +149,7 @@ export function createZellijClient(options = {}) {
         if (!input.name.trim()) {
             throw new ZellijError("missing_name", "name required");
         }
-        await run(buildRenamePaneArgs(input.session, paneId, input.name), "zellij action rename-pane");
+        await run(buildRenamePaneArgs(input.session, paneId, input.name), "zellij action rename-pane", input.timeoutMs ?? timeoutMs);
         return { paneId, session: input.session, name: input.name };
     }
     async function renameTab(input) {
@@ -104,8 +164,8 @@ export function createZellijClient(options = {}) {
         await run(buildFocusPaneArgs(input.session, paneId), "zellij action focus-pane-id");
         return { paneId, session: input.session };
     }
-    async function listTabs(session) {
-        const result = await run(buildListTabsArgs(session), "zellij action list-tabs");
+    async function listTabs(session, callTimeoutMs = timeoutMs) {
+        const result = await run(buildListTabsArgs(session), "zellij action list-tabs", callTimeoutMs);
         return parseTabList(result.stdout);
     }
     async function dumpLayout(session) {
@@ -129,11 +189,12 @@ export function createZellijClient(options = {}) {
     }
     /** `new-pane` prints the created pane id; `new-tab` prints a tab id instead. */
     function parseCreatedPaneId(stdout) {
-        const match = /(terminal|plugin)_\d+/i.exec(stdout);
-        return match ? match[0].toLowerCase() : null;
+        const ids = new Set(stdout.split(/\r?\n/).map((line) => line.trim().toLowerCase())
+            .filter((line) => /^(terminal|plugin)_\d+$/.test(line)));
+        return ids.size === 1 ? [...ids][0] : null;
     }
     async function newPane(input) {
-        const result = await run(buildNewPaneArgs(input), "zellij action new-pane");
+        const result = await run(buildNewPaneArgs(input), "zellij action new-pane", input.timeoutMs ?? timeoutMs);
         return {
             session: input.session,
             paneId: parseCreatedPaneId(result.stdout),
@@ -141,11 +202,12 @@ export function createZellijClient(options = {}) {
         };
     }
     async function newTab(input) {
-        const result = await run(buildNewTabArgs(input), "zellij action new-tab");
-        const digits = /-?\d+/.exec(result.stdout);
+        const result = await run(buildNewTabArgs(input), "zellij action new-tab", input.timeoutMs ?? timeoutMs);
+        const ids = new Set(result.stdout.split(/\r?\n/).map((line) => line.trim())
+            .filter((line) => /^\d+$/.test(line)).map(Number).filter(Number.isSafeInteger));
         return {
             session: input.session,
-            tabId: digits ? Number(digits[0]) : null,
+            tabId: ids.size === 1 ? [...ids][0] : null,
             stdout: result.stdout.trim(),
         };
     }
@@ -201,7 +263,7 @@ export function createZellijClient(options = {}) {
             configKey: input.configKey,
             payload: changedPayload(input.panes),
         }), {
-            timeoutMs: DEFAULT_BUS_TIMEOUT_MS,
+            timeoutMs: input.timeoutMs ?? DEFAULT_BUS_TIMEOUT_MS,
             until: (stdout) => parseChangedReply(stdout) !== null,
         });
     }
@@ -215,11 +277,14 @@ export function createZellijClient(options = {}) {
     /** Visible prefix so peer CLIs can tell zSwarm injects from human prompts. */
     function formatPeerMessage(from, body) {
         const sender = from.trim() || "swarm";
-        return `[zswarm from=${sender}]\n${body.trim()}`;
+        return `[zswarm from=${sender}]\n${body}`;
     }
     return {
         zellijPath,
         selfPaneId,
+        get transport() {
+            return readTransport();
+        },
         /** A `file:` plugin url only names a path on the machine running Zellij. */
         remote: ssh !== null,
         listSessions,

package/dist/zellij/panes.js

@@ -68,6 +68,9 @@ export function resolvePane(panes, to) {
     const byTypedId = panes.find((p) => p.id === key.toLowerCase());
     if (byTypedId)
         return byTypedId;
+    if (/^(terminal|plugin)_\d+$/i.test(key)) {
+        throw new ZellijError("peer_not_found", `pane ${key} is not in the current listing`);
+    }
     if (/^\d+$/.test(key)) {
         const terminals = panes.filter((p) => !p.isPlugin && String(p.numericId) === key);
         if (terminals.length === 1)

package/dist/zellij/session.d.ts

@@ -2,15 +2,31 @@ export type ZellijSessionResolve = {
     session: string;
     source: "arg" | "env_zswarm" | "env_zellij" | "sole_live";
 };
+/** One row from `zellij list-sessions --no-formatting` (not `--short`). */
+export type ZellijSession = {
+    name: string;
+    /** True when Zellij marks the row EXITED (resurrectable, no live server). */
+    exited: boolean;
+    /** True when the listing marks this session as the caller's current one. */
+    current: boolean;
+};
 /**
  * Pane hosting the caller, so writes can refuse to loop back into it.
  * `ZSWARM_SELF_PANE` wins; Zellij exports `ZELLIJ_PANE_ID` inside a pane.
  */
 export declare function resolveSelfPaneId(env?: NodeJS.ProcessEnv): string | null;
-export declare function parseSessionList(stdout: string): string[];
+/**
+ * Parse `list-sessions --no-formatting` output.
+ *
+ * Annotated form: `name [Created …] [(current)| (EXITED - …)]`.
+ * Bare names (from `--short` or test mocks) are treated as live.
+ */
+export declare function parseSessionList(stdout: string): ZellijSession[];
+/** Live session names only — used when auto-picking a sole session. */
+export declare function liveSessionNames(sessions: ZellijSession[]): string[];
 /** Zellij exits 1 and prints this when the machine simply has no sessions. */
 export declare function isZellijNoSessionsOutput(stdout: string, stderr: string): boolean;
 /** Session from an explicit argument or the environment, before asking Zellij. */
 export declare function sessionFromEnv(env: NodeJS.ProcessEnv, explicit?: string | null): ZellijSessionResolve | null;
-/** Pick a session when the environment gave no answer. */
-export declare function sessionFromList(sessions: string[]): ZellijSessionResolve;
+/** Pick a session when the environment gave no answer. EXITED rows do not count. */
+export declare function sessionFromList(sessions: ZellijSession[]): ZellijSessionResolve;

package/dist/zellij/session.js

@@ -13,11 +13,40 @@ export function resolveSelfPaneId(env = process.env) {
         return raw.toLowerCase();
     return null;
 }
+/**
+ * Parse `list-sessions --no-formatting` output.
+ *
+ * Annotated form: `name [Created …] [(current)| (EXITED - …)]`.
+ * Bare names (from `--short` or test mocks) are treated as live.
+ */
 export function parseSessionList(stdout) {
-    return stdout
-        .split(/\r?\n/)
-        .map((l) => l.trim())
-        .filter(Boolean);
+    const sessions = [];
+    for (const raw of stdout.split(/\r?\n/)) {
+        // Drop ANSI in case a caller forgot --no-formatting.
+        const line = raw.replace(/\x1B\[[0-9;]*m/g, "").trim();
+        if (!line)
+            continue;
+        const created = line.indexOf(" [Created ");
+        if (created >= 0) {
+            const name = line.slice(0, created).trim();
+            if (!name)
+                continue;
+            const suffix = line.slice(created);
+            sessions.push({
+                name,
+                exited: /\(EXITED\b/i.test(suffix),
+                current: /\(current\)/i.test(suffix),
+            });
+            continue;
+        }
+        // Bare name from --short or a mock.
+        sessions.push({ name: line, exited: false, current: false });
+    }
+    return sessions;
+}
+/** Live session names only — used when auto-picking a sole session. */
+export function liveSessionNames(sessions) {
+    return sessions.filter((s) => !s.exited).map((s) => s.name);
 }
 /** Zellij exits 1 and prints this when the machine simply has no sessions. */
 export function isZellijNoSessionsOutput(stdout, stderr) {
@@ -36,13 +65,14 @@ export function sessionFromEnv(env, explicit) {
         return { session: zellijEnv, source: "env_zellij" };
     return null;
 }
-/** Pick a session when the environment gave no answer. */
+/** Pick a session when the environment gave no answer. EXITED rows do not count. */
 export function sessionFromList(sessions) {
-    if (sessions.length === 1) {
-        return { session: sessions[0], source: "sole_live" };
+    const live = liveSessionNames(sessions);
+    if (live.length === 1) {
+        return { session: live[0], source: "sole_live" };
     }
-    if (sessions.length === 0) {
+    if (live.length === 0) {
         throw new ZellijError("zellij_no_session", "no live Zellij sessions; start zellij or pass session=");
     }
-    throw new ZellijError("zellij_session_ambiguous", `multiple Zellij sessions (${sessions.join(", ")}); pass session=`);
+    throw new ZellijError("zellij_session_ambiguous", `multiple Zellij sessions (${live.join(", ")}); pass session=`);
 }