@zswarm/core 0.1.4 → 0.1.6

package/dist/zellij/client.d.ts

@@ -1,23 +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;
@@ -31,6 +46,7 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
         session: string;
         paneId: string;
         full?: boolean;
+        timeoutMs?: number;
     }) => Promise<{
         paneId: string;
         session: string;
@@ -74,6 +90,7 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
         session: string;
         paneId: string;
         name: string;
+        timeoutMs?: number;
     }) => Promise<{
         paneId: string;
         session: string;
@@ -95,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;
@@ -137,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,54 +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));
-    const exec = options.exec ??
-        (ssh
-            ? createSshExec(ssh, sanitizeZellijEnv(env))
-            : defaultExec(zellijPath, 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 ??
+        (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) {
@@ -64,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) {
@@ -88,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) {
@@ -103,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) {
@@ -128,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),
@@ -140,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(),
         };
     }
@@ -200,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,
         });
     }
@@ -214,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=`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {
@@ -25,10 +25,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@zswarm/wasm": "0.1.1"
+    "@zswarm/wasm": "0.1.3"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "pnpm run build && node --test"
+    "test": "pnpm run build && node --import ./test-support/clean-env.mjs --test"
   }
 }