@zswarm/core 0.1.5 → 0.1.7

package/dist/zellij/client.js

@@ -1,58 +1,187 @@
 import { ZellijError } from "../errors.js";
+import { ListingCache, executorIdentity, listingTtl, routingEnvironment, sharedListings } from "./cache.js";
 import { buildClosePaneArgs, buildDumpArgs, buildDumpLayoutArgs, buildFocusPaneArgs, buildLaunchPluginArgs, buildListPanesArgs, buildListTabsArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildRenamePaneArgs, buildRenameTabArgs, buildSendEnterArgs, buildSendKeysArgs, buildStackPanesArgs, buildWriteCharsArgs, changedPayload, scrollbackPayload, waitPayload, } from "./args.js";
 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, ensureZellijProbes, 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. */
+/** Zellij wrapper with bounded caches of completed discovery observations. */
 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), { pinIpc: true });
     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 = JSON.stringify([identityCacheKey(zellijPath, ssh), routingEnvironment(env)]);
+    const now = options.now ?? Date.now;
+    const cache = options.cache instanceof ListingCache ? options.cache : sharedListings;
+    const ttl = options.cache === false || (options.exec && !options.cache) ? 0 : listingTtl(env);
+    const baseContext = JSON.stringify([zellijPath, ssh, executorIdentity(options.exec), routingEnvironment(env)]);
+    const scopeFor = (session) => JSON.stringify([baseContext, session ?? null]);
+    const contextKey = () => JSON.stringify([baseContext, readTransport().ipc ?? null]);
+    const cacheUsable = () => {
+        const ipc = readTransport().ipc;
+        return ttl > 0 && (ipc?.requested?.toLowerCase() !== "auto" || ipc.status === "resolved");
+    };
+    function invalidateListings(session) {
+        cache.invalidate(scopeFor(session));
+        cache.invalidate(scopeFor());
+    }
+    function observeManifest(session, revision) {
+        if (cache.observe(scopeFor(session), revision))
+            cache.invalidate(scopeFor());
+    }
+    async function listing(kind, session, budget, fresh, read) {
+        const remaining = operationBudget(budget, `zellij ${kind}`);
+        remaining(); // An aborted/expired caller cannot consume a cached value.
+        // Resolve auto IPC before selecting the namespace, including cold reads.
+        // A sibling can refresh discovery while this read is in flight, so keep
+        // the original namespace and refuse to cache under a different one later.
+        if (ssh?.tmp?.trim().toLowerCase() === "auto") {
+            await sshExec.prepareIpc(remaining(), options.signal);
+            remaining();
+        }
+        const key = () => JSON.stringify([contextKey(), session ?? null, kind]);
+        const startedKey = key();
+        if (cacheUsable() && !fresh) {
+            const hit = cache.get(startedKey, now());
+            if (hit !== undefined)
+                return hit;
+        }
+        const scope = scopeFor(session);
+        const ticket = cache.begin(scope);
+        const value = await read(remaining);
+        remaining();
+        if (cacheUsable() && key() === startedKey)
+            cache.put(startedKey, scope, ticket, value, ttl, now());
+        return value;
+    }
+    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.
+        if (sshExec?.prepareIpc)
+            await sshExec.prepareIpc(remaining(), options.signal);
+        await ensureZellijProbes(exec, zellijPath, remaining(), probeKey, options.signal);
+    }
+    async function runCommand(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,
-        });
-        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`);
+    const mutations = new Set([
+        "new-pane", "new-tab", "close-pane", "rename-pane", "rename-tab-by-id",
+        "focus-pane-id", "stack-panes", "launch-or-focus-plugin", "paste", "send-keys", "write-chars",
+    ]);
+    async function run(args, label, callTimeoutMs = timeoutMs) {
+        const action = args[args.indexOf("action") + 1];
+        const index = args.indexOf("--session");
+        const session = index >= 0 ? args[index + 1] : undefined;
+        const mutation = session && mutations.has(action ?? "");
+        if (mutation)
+            invalidateListings(session);
+        try {
+            return await runCommand(args, label, callTimeoutMs);
         }
-        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"}`);
+        finally {
+            // Failed/uncertain writes can still have reached Zellij. Drop both reads
+            // from before the write and reads that raced while it was in flight.
+            if (mutation)
+                invalidateListings(session);
         }
-        return parseSessionList(result.stdout);
     }
-    async function resolveSession(explicit) {
-        return sessionFromEnv(env, explicit) ?? sessionFromList(await listSessions());
+    async function listSessions(callTimeoutMs = timeoutMs, opts = {}) {
+        return listing("list-sessions", undefined, callTimeoutMs, opts.fresh === true, async (remaining) => {
+            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) {
+                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}): ${detail}`);
+            }
+            return parseSessionList(result.stdout);
+        });
+    }
+    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");
-        return parsePaneList(result.stdout);
+    async function listPanes(session, callTimeoutMs = timeoutMs, opts = {}) {
+        return listing("list-panes", session, callTimeoutMs, opts.fresh === true, async (remaining) => {
+            const result = await run(buildListPanesArgs(session), "zellij action list-panes", remaining());
+            return parsePaneList(result.stdout);
+        });
     }
     async function injectPane(input) {
         const paneId = normalizePaneId(input.paneId);
@@ -65,7 +194,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 +218,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,9 +233,11 @@ 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");
-        return parseTabList(result.stdout);
+    async function listTabs(session, callTimeoutMs = timeoutMs, opts = {}) {
+        return listing("list-tabs", session, callTimeoutMs, opts.fresh === true, async (remaining) => {
+            const result = await run(buildListTabsArgs(session), "zellij action list-tabs", remaining());
+            return parseTabList(result.stdout);
+        });
     }
     async function dumpLayout(session) {
         const result = await run(buildDumpLayoutArgs(session), "zellij action dump-layout");
@@ -129,11 +260,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 +273,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 +334,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 +348,17 @@ 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,
+        contextKey,
+        invalidateListings,
+        observeManifest,
+        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.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {
@@ -25,10 +25,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@zswarm/wasm": "0.1.2"
+    "@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"
   }
 }