@zswarm/core 0.1.6 → 0.1.8

package/dist/zellij/binary.js

@@ -7,6 +7,19 @@ import { applyIpcTmpEnv } from "./ipc.js";
 export { createSshExec };
 export const DEFAULT_TIMEOUT_MS = 15_000;
 export { NOT_FOUND_EXIT };
+/** Local Node spawn failure vs a process that actually started. */
+export function originFromExecResult(result) {
+    return result.spawn?.origin === "local" ? "local_spawn" : "remote";
+}
+export function zellijExecDetails(result) {
+    const origin = originFromExecResult(result);
+    return result.spawn
+        ? { origin, spawn: { origin: result.spawn.origin, errno: result.spawn.errno, bin: result.spawn.bin } }
+        : { origin };
+}
+export function zellijMissingError(zellijPath, result) {
+    return new ZellijError("zellij_missing", `zellij binary not found (${zellijPath}); install Zellij ≥ 0.42, add it to PATH, or set ZSWARM_BIN / ZSWARM_PATH`, zellijExecDetails(result));
+}
 /** Expand a leading `~/` or `~\` using USERPROFILE/HOME. */
 export function expandHomePath(input, env = process.env) {
     const trimmed = input.trim();
@@ -51,7 +64,7 @@ export function looksLikeZswarmBinary(path) {
 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)`);
+    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)`, { origin: "local_preflight", bin: path });
 }
 /**
  * ZSWARM_SSH is a destination, not a full ssh argv.
@@ -98,40 +111,48 @@ export function isZellijVersionOutput(stdout, stderr = "") {
  */
 export function identityCacheKey(zellijPath, ssh) {
     if (!ssh)
-        return zellijPath;
-    return [
+        return JSON.stringify([zellijPath]);
+    return JSON.stringify([
         zellijPath,
         ssh.host,
         ssh.remoteBin ?? "",
         ssh.mode ?? "ssh",
-        ssh.options.join("\0"),
-    ].join("|");
+        ssh.options,
+        ssh.sshBin ?? ssh.ssh ?? "",
+        ssh.remoteShell ?? "",
+    ]);
 }
 /**
  * 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.
+ * In-flight probes are never shared — each caller supplies its own timeout.
  */
-export async function ensureZellijIdentity(exec, zellijPath, timeoutMs = 3_000, cacheKey = zellijPath) {
+export async function ensureZellijIdentity(exec, zellijPath, timeoutMs = 3_000, cacheKey = zellijPath, signal) {
     if (identityCache.has(cacheKey))
         return true;
+    if (signal?.aborted)
+        return false;
     assertZellijBinaryPath(zellijPath);
     const result = await exec(["--version"], {
         timeoutMs: Math.min(timeoutMs, 5_000),
+        signal,
     });
     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`);
+        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath}). Set ZSWARM_BIN to the zellij executable`, zellijExecDetails(result));
     }
     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`);
+        throw zellijMissingError(zellijPath, result);
     }
     if (result.code === 0) {
+        if (signal?.aborted)
+            return false;
         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"}`);
+        throw new ZellijError("zellij_wrong_bin", `resolved binary is not Zellij (${zellijPath}); --version returned: ${result.stdout.trim() || result.stderr.trim() || "empty"}`, zellijExecDetails(result));
     }
     // Timeout / transport failure: leave unresolved so a later call retries.
     return false;
@@ -142,32 +163,56 @@ export async function ensureZellijIdentity(exec, zellijPath, timeoutMs = 3_000,
  * Returns false when the transport cannot verify support.
  */
 const capabilityCache = new Set();
-export async function ensureZellijCapabilities(exec, zellijPath, timeoutMs = 3_000, cacheKey = zellijPath) {
+export async function ensureZellijCapabilities(exec, zellijPath, timeoutMs = 3_000, cacheKey = zellijPath, signal) {
     if (capabilityCache.has(cacheKey))
         return true;
+    if (signal?.aborted)
+        return false;
     const result = await exec(["list-sessions", "--help"], {
         timeoutMs: Math.min(timeoutMs, 5_000),
+        signal,
     });
     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})`);
+        throw new ZellijError("zellij_wrong_bin", `resolved binary is zswarm, not Zellij (${zellijPath})`, zellijExecDetails(result));
     }
     if (result.code === NOT_FOUND_EXIT) {
-        throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath})`);
+        throw zellijMissingError(zellijPath, result);
     }
     // Require the flags this client always passes.
     if (result.code === 0 &&
         /--no-formatting/i.test(text) &&
         /list-sessions/i.test(text)) {
+        if (signal?.aborted)
+            return false;
         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`);
+        throw new ZellijError("zellij_incompatible", `Zellij at ${zellijPath} does not advertise list-sessions --no-formatting; upgrade Zellij (≥ 0.42) or zswarm`, zellijExecDetails(result));
     }
     // Soft: leave unresolved on transport failure.
     return false;
 }
+/**
+ * Identity and capability are independent reads. Run them together under one
+ * remaining budget; do not share in-flight work with another caller.
+ */
+export async function ensureZellijProbes(exec, zellijPath, timeoutMs = 3_000, cacheKey = zellijPath, signal) {
+    if (signal?.aborted)
+        return { identity: false, capabilities: false };
+    const probeTimeout = Math.min(timeoutMs, 5_000);
+    // Settle both so a wrong-bin throw does not leave the other SSH probe running.
+    const settled = await Promise.allSettled([
+        ensureZellijIdentity(exec, zellijPath, probeTimeout, cacheKey, signal),
+        ensureZellijCapabilities(exec, zellijPath, probeTimeout, cacheKey, signal),
+    ]);
+    if (settled[0].status === "rejected")
+        throw settled[0].reason;
+    if (settled[1].status === "rejected")
+        throw settled[1].reason;
+    return { identity: settled[0].value, capabilities: settled[1].value };
+}
 /** Test helper: drop cached identity/capability probes. */
 export function resetZellijIdentityCache() {
     identityCache.clear();

package/dist/zellij/bus.js

@@ -74,7 +74,7 @@ export function parseChangedReply(stdout) {
             if (!row || typeof row !== "object")
                 continue;
             const p = row;
-            if (typeof p.id !== "string")
+            if (typeof p.id !== "string" || typeof p.changed !== "boolean" || typeof p.first !== "boolean" || !Array.isArray(p.viewport))
                 continue;
             panes.push({
                 id: p.id,

package/dist/zellij/cache.d.ts

@@ -0,0 +1,24 @@
+/** Short-lived, completed observations only. Never shares a caller's promise or budget. */
+export declare class ListingCache {
+    private readonly limit;
+    private entries;
+    private scopes;
+    constructor(limit?: number);
+    begin(scope: string): {
+        state: {
+            version: number;
+            revision?: string;
+        };
+        version: number;
+    };
+    get<T>(key: string, now: number): T | undefined;
+    put<T>(key: string, scope: string, ticket: ReturnType<ListingCache["begin"]>, value: T, ttl: number, now: number): void;
+    invalidate(scope: string): void;
+    observe(scope: string, revision: string): boolean;
+    clear(): void;
+}
+export declare const sharedListings: ListingCache;
+export declare function executorIdentity(exec?: object): number | null;
+/** Environment fields that select local sockets or an SSH identity/config. */
+export declare function routingEnvironment(env: NodeJS.ProcessEnv): Record<string, string | null>;
+export declare function listingTtl(env: NodeJS.ProcessEnv): number;

package/dist/zellij/cache.js

@@ -0,0 +1,90 @@
+/** Short-lived, completed observations only. Never shares a caller's promise or budget. */
+export class ListingCache {
+    limit;
+    entries = new Map();
+    scopes = new Map();
+    constructor(limit = 512) {
+        this.limit = limit;
+    }
+    begin(scope) {
+        let state = this.scopes.get(scope);
+        if (!state) {
+            state = { version: 0 };
+            this.scopes.set(scope, state);
+            if (this.scopes.size > this.limit) {
+                const oldest = this.scopes.keys().next().value;
+                this.scopes.delete(oldest);
+                for (const [key, entry] of this.entries)
+                    if (entry.scope === oldest)
+                        this.entries.delete(key);
+            }
+        }
+        return { state, version: state.version };
+    }
+    get(key, now) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (now >= entry.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return structuredClone(entry.value);
+    }
+    put(key, scope, ticket, value, ttl, now) {
+        // A mutation/event during this read must not resurrect an older manifest.
+        if (ttl <= 0 || this.scopes.get(scope) !== ticket.state || ticket.state.version !== ticket.version)
+            return;
+        this.entries.delete(key);
+        this.entries.set(key, { scope, value: structuredClone(value), expiresAt: now + ttl });
+        while (this.entries.size > this.limit)
+            this.entries.delete(this.entries.keys().next().value);
+    }
+    invalidate(scope) {
+        this.begin(scope).state.version++;
+        for (const [key, entry] of this.entries)
+            if (entry.scope === scope)
+                this.entries.delete(key);
+    }
+    observe(scope, revision) {
+        const { state } = this.begin(scope);
+        if (state.revision === revision)
+            return false;
+        this.invalidate(scope);
+        state.revision = revision;
+        return true;
+    }
+    clear() {
+        this.entries.clear();
+        this.scopes.clear();
+    }
+}
+export const sharedListings = new ListingCache();
+const executors = new WeakMap();
+let nextExecutor = 0;
+export function executorIdentity(exec) {
+    if (!exec)
+        return null;
+    let id = executors.get(exec);
+    if (id === undefined) {
+        id = ++nextExecutor;
+        executors.set(exec, id);
+    }
+    return id;
+}
+/** Environment fields that select local sockets or an SSH identity/config. */
+export function routingEnvironment(env) {
+    return Object.fromEntries([
+        "ZSWARM_TMP", "ZELLIJ_SOCKET_DIR", "TMPDIR", "TEMP", "TMP", "XDG_RUNTIME_DIR",
+        "HOME", "USERPROFILE", "USER", "USERNAME", "LOGNAME", "USERDOMAIN", "SSH_AUTH_SOCK",
+        "PATH", "Path", "PATHEXT", "XDG_CONFIG_HOME", "ZELLIJ_CONFIG_DIR",
+        "ZELLIJ_SESSION_NAME", "ZSWARM_SESSION",
+    ].map((key) => [key, env[key] ?? null]));
+}
+export function listingTtl(env) {
+    const value = env.ZSWARM_CACHE_TTL_MS;
+    if (value === undefined || value.trim() === "")
+        return 500;
+    const ttl = Number(value);
+    return Number.isFinite(ttl) ? Math.max(0, Math.min(5000, ttl)) : 500;
+}

package/dist/zellij/client.d.ts

@@ -1,3 +1,4 @@
+import { ListingCache } from "./cache.js";
 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";
@@ -12,6 +13,10 @@ export type ZellijClientOptions = {
     signal?: AbortSignal;
     /** Skip the one-time `zellij --version` identity probe (tests). */
     skipIdentityProbe?: boolean;
+    /** Completed listing cache shared by long-lived MCP/serve calls; false bypasses reads. */
+    cache?: ListingCache | false;
+    /** Clock for cache TTLs; process deadlines continue using wall time. */
+    now?: () => number;
 };
 export type ZellijTransport = {
     kind: "local" | "ssh";
@@ -23,16 +28,23 @@ export type ZellijTransport = {
     /** Outcome of `ZSWARM_TMP=auto` discovery when SSH routing is active. */
     ipc?: IpcDiscoveryState;
 };
-/** Thin, stateless wrapper over the `zellij` binary. */
+/** Zellij wrapper with bounded caches of completed discovery observations. */
 export declare function createZellijClient(options?: ZellijClientOptions): {
     zellijPath: string;
     selfPaneId: string | null;
+    contextKey: () => string;
+    invalidateListings: (session: string) => void;
+    observeManifest: (session: string, revision: string) => void;
     readonly transport: ZellijTransport;
     /** A `file:` plugin url only names a path on the machine running Zellij. */
     remote: boolean;
-    listSessions: (callTimeoutMs?: number) => Promise<ZellijSession[]>;
+    listSessions: (callTimeoutMs?: number, opts?: {
+        fresh?: boolean;
+    }) => Promise<ZellijSession[]>;
     resolveSession: (explicit?: string | null, callTimeoutMs?: number) => Promise<ZellijSessionResolve>;
-    listPanes: (session: string, callTimeoutMs?: number) => Promise<ZellijPane[]>;
+    listPanes: (session: string, callTimeoutMs?: number, opts?: {
+        fresh?: boolean;
+    }) => Promise<ZellijPane[]>;
     resolvePane: typeof resolvePane;
     injectPane: (input: {
         session: string;
@@ -112,7 +124,9 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
         paneId: string;
         session: string;
     }>;
-    listTabs: (session: string, callTimeoutMs?: number) => Promise<ZellijTab[]>;
+    listTabs: (session: string, callTimeoutMs?: number, opts?: {
+        fresh?: boolean;
+    }) => Promise<ZellijTab[]>;
     dumpLayout: (session: string) => Promise<string>;
     stackPanes: (input: {
         session: string;

package/dist/zellij/client.js

@@ -1,12 +1,13 @@
 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, ensureZellijCapabilities, ensureZellijIdentity, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, } from "./binary.js";
+import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, ensureZellijProbes, identityCacheKey, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, zellijExecDetails, zellijMissingError, } 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. An injected exec is a unit
@@ -21,13 +22,56 @@ export function createZellijClient(options = {}) {
                 : resolveZellijBinary(env));
     const sshExec = options.exec || !ssh
         ? null
-        : createSshExec(ssh, sanitizeZellijEnv(env));
+        : createSshExec(ssh, sanitizeZellijEnv(env), { pinIpc: true });
     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);
-    const probeKey = identityCacheKey(zellijPath, ssh);
+    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" };
@@ -66,53 +110,78 @@ export function createZellijClient(options = {}) {
             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);
+        if (sshExec?.prepareIpc)
+            await sshExec.prepareIpc(remaining(), options.signal);
+        await ensureZellijProbes(exec, zellijPath, remaining(), probeKey, options.signal);
     }
-    async function run(args, label, callTimeoutMs = timeoutMs) {
+    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`);
+            throw zellijMissingError(zellijPath, result);
         }
         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}`);
+                throw new ZellijError("zellij_wrong_bin", `resolved binary looks like zswarm, not Zellij (${zellijPath}): ${detail}`, zellijExecDetails(result));
             }
-            throw new ZellijError("zellij_failed", `${label} failed (exit ${result.code}): ${detail}`);
+            throw new ZellijError("zellij_failed", `${label} failed (exit ${result.code}): ${detail}`, zellijExecDetails(result));
         }
         return result;
     }
-    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`);
+    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) {
-            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}`);
+        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 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 zellijMissingError(zellijPath, result);
+            }
+            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}`, zellijExecDetails(result));
+                }
+                if (isZellijNoSessionsOutput(result.stdout, result.stderr))
+                    return [];
+                throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${detail}`, zellijExecDetails(result));
+            }
+            return parseSessionList(result.stdout);
+        });
     }
     async function resolveSession(explicit, callTimeoutMs = timeoutMs) {
         return (sessionFromEnv(env, explicit) ??
             sessionFromList(await listSessions(callTimeoutMs)));
     }
-    async function listPanes(session, callTimeoutMs = timeoutMs) {
-        const result = await run(buildListPanesArgs(session), "zellij action list-panes", callTimeoutMs);
-        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);
@@ -164,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, callTimeoutMs = timeoutMs) {
-        const result = await run(buildListTabsArgs(session), "zellij action list-tabs", callTimeoutMs);
-        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");
@@ -282,6 +353,9 @@ export function createZellijClient(options = {}) {
     return {
         zellijPath,
         selfPaneId,
+        contextKey,
+        invalidateListings,
+        observeManifest,
         get transport() {
             return readTransport();
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {