@zswarm/core 0.4.2 → 0.6.0

package/dist/zellij/client.js

@@ -1,13 +1,60 @@
 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 { buildClosePaneArgs, buildDumpArgs, buildDumpLayoutArgs, buildFocusPaneArgs, buildLaunchPluginArgs, buildListPanesArgs, buildListTabsArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildRenamePaneArgs, buildRenameSessionArgs, 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 { originSuffix } from "../ops/delivery.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 { assignServersToSessions, findAncestorServer, liveServers, matchServerToSession, paneMatchesId, readProcessTable, } from "./server-identity.js";
 import { isZellijNoSessionsOutput, parseSessionList, resolveSelfPaneId, resolveSelfSession, sessionFromEnv, sessionFromList, } from "./session.js";
+/** How long one process-table snapshot is reused, for the whole process. */
+const PROCESS_TABLE_TTL_MS = 2_000;
+/** How long a resolved self session is trusted across clients. */
+const SELF_RESOLUTION_TTL_MS = 30_000;
+/**
+ * Process-wide caches. MCP/serve processes are long-lived but create a client
+ * per dispatch, so caches kept inside a client never survive to the next call.
+ */
+let sharedProcessTable = null;
+let sharedProcessTableInFlight = null;
+const selfResolutionCache = new Map();
+/** Test helper: forget every cached self resolution (and its process table). */
+export function resetSelfResolutionCache() {
+    selfResolutionCache.clear();
+    sharedProcessTable = null;
+    sharedProcessTableInFlight = null;
+}
+/**
+ * Drop cached self resolutions that name `session` (as the env name a pane
+ * carries or as the resolved live name); a renamed or closed session must not
+ * be served from cache.
+ */
+function invalidateSelfResolutionCache(session) {
+    for (const [key, entry] of selfResolutionCache) {
+        if (entry.env === session || entry.name === session)
+            selfResolutionCache.delete(key);
+    }
+}
+async function sharedProcessTableSnapshot(platform) {
+    const at = Date.now();
+    if (sharedProcessTable && at - sharedProcessTable.at <= PROCESS_TABLE_TTL_MS) {
+        return sharedProcessTable.rows;
+    }
+    // Collapse concurrent readers onto one spawn so N clients do not each pay.
+    if (!sharedProcessTableInFlight) {
+        sharedProcessTableInFlight = readProcessTable({ platform })
+            .then((rows) => {
+            sharedProcessTable = { at: Date.now(), rows };
+            return rows;
+        })
+            .finally(() => {
+            sharedProcessTableInFlight = null;
+        });
+    }
+    return sharedProcessTableInFlight;
+}
 /** Zellij wrapper with bounded caches of completed discovery observations. */
 export function createZellijClient(options = {}) {
     const env = options.env ?? process.env;
@@ -28,9 +75,28 @@ export function createZellijClient(options = {}) {
         (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 platform = options.platform ?? process.platform;
     const selfPaneId = resolveSelfPaneId(env);
     // Over SSH the target is another machine's Zellij: no pane there is ours.
-    const selfSession = ssh ? null : resolveSelfSession(env);
+    const staticSelfSession = ssh ? null : resolveSelfSession(env);
+    // The live name of this pane's session once resolved through the process
+    // table (the env name can be stale after a rename).
+    let selfResolved = null;
+    let selfFailureAt = 0;
+    // Explicit names seen by this client (arg/env_zswarm -> source label), used
+    // to diagnose a failed Zellij call on the failure path only. Bounded so a
+    // long-lived MCP process cannot grow it without limit.
+    const explicitSessions = new Map();
+    function rememberExplicitSession(session, source) {
+        explicitSessions.delete(session);
+        explicitSessions.set(session, source);
+        if (explicitSessions.size > 256) {
+            const oldest = explicitSessions.keys().next().value;
+            if (oldest !== undefined)
+                explicitSessions.delete(oldest);
+        }
+    }
+    const aliases = options.aliases ?? null;
     const probeKey = JSON.stringify([identityCacheKey(zellijPath, ssh), routingEnvironment(env)]);
     const now = options.now ?? Date.now;
     const cache = options.cache instanceof ListingCache ? options.cache : sharedListings;
@@ -42,6 +108,11 @@ export function createZellijClient(options = {}) {
         const ipc = readTransport().ipc;
         return ttl > 0 && (ipc?.requested?.toLowerCase() !== "auto" || ipc.status === "resolved");
     };
+    async function processTable() {
+        if (options.processTable)
+            return await options.processTable();
+        return sharedProcessTableSnapshot(platform);
+    }
     function invalidateListings(session) {
         cache.invalidate(scopeFor(session));
         cache.invalidate(scopeFor());
@@ -135,7 +206,8 @@ export function createZellijClient(options = {}) {
     }
     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",
+        "rename-session", "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];
@@ -191,14 +263,358 @@ export function createZellijClient(options = {}) {
         }
         invalidateListings(name);
     }
+    /** A clear failure for a session name that is not (and does not map to) a live one. */
+    function sessionNotLiveError(candidate, source, live) {
+        const liveList = live.length > 0 ? live.join(", ") : "none";
+        const stale = source === "env_zellij"
+            ? " (this pane's ZELLIJ_SESSION_NAME is stale)"
+            : "";
+        return new ZellijError("session_not_live", `session "${candidate}" is not a live Zellij session (renamed or closed?); live sessions: ${liveList}; pass session=<name>${stale}`, { requested: candidate, source, live });
+    }
+    /**
+     * Match a server process to the live session whose panes it owns. Lists the
+     * panes of every live session under the caller's remaining budget.
+     */
+    async function matchViaServer(candidate, isSelf, live, table, ancestor, budget) {
+        let server = ancestor;
+        if (!server) {
+            const byCreation = liveServers(table).filter((item) => item.creationName === candidate);
+            if (byCreation.length !== 1)
+                return null;
+            server = byCreation[0];
+        }
+        const withPanes = [];
+        for (const session of live) {
+            try {
+                withPanes.push({
+                    name: session.name,
+                    panes: await listPanes(session.name, budget()),
+                });
+            }
+            catch {
+                // A session that closed mid-resolution cannot be the answer.
+            }
+        }
+        // The deterministic global assignment resolves generic-command ties via
+        // creation-name pins and single-candidate propagation. In the self case a
+        // pinned session is only trusted when it actually holds our pane; else
+        // fall back to the pane-id-filtered single match.
+        let match = null;
+        const pinned = assignServersToSessions(table, withPanes).get(server.pid);
+        if (pinned) {
+            const pinnedSession = withPanes.find((session) => session.name === pinned);
+            if (!isSelf ||
+                !selfPaneId ||
+                pinnedSession?.panes.some((pane) => paneMatchesId(pane, selfPaneId))) {
+                match = pinned;
+            }
+        }
+        if (!match) {
+            match = matchServerToSession(server.pid, table, withPanes, {
+                ...(isSelf && selfPaneId ? { paneId: selfPaneId } : {}),
+            });
+        }
+        if (!match)
+            return null;
+        if (aliases) {
+            const entry = {
+                current: match,
+                serverPid: server.pid,
+                creation: server.creationName,
+                at: now(),
+            };
+            aliases.recordSessionAlias(candidate, entry);
+            if (server.creationName && server.creationName !== candidate) {
+                aliases.recordSessionAlias(server.creationName, entry);
+            }
+        }
+        return { session: match, source: "renamed", requested: candidate };
+    }
+    /**
+     * Session resolution beyond the environment. An explicit name is trusted
+     * without a listing (callers that name their session do not pay a round
+     * trip to confirm it), except that a remembered rename is applied from the
+     * alias store; a live server pid locally proves the alias still leads to a
+     * live session. A pane's own env name gets the full treatment: the process
+     * table disambiguates a reused name and the server behind a renamed one.
+     */
+    async function resolveCandidate(fromEnv, callTimeoutMs) {
+        const candidate = fromEnv.session;
+        const source = fromEnv.source;
+        const isSelf = source === "env_zellij";
+        if (!isSelf) {
+            if (aliases) {
+                const entry = aliases.readSessionAliases()[candidate];
+                if (entry?.serverPid != null) {
+                    const table = await processTable();
+                    if (liveServers(table).some((server) => server.pid === entry.serverPid)) {
+                        return { session: entry.current, source: "alias", requested: candidate };
+                    }
+                }
+            }
+            return fromEnv;
+        }
+        const deadline = Date.now() + callTimeoutMs;
+        const budget = () => Math.max(1, deadline - Date.now());
+        const sessions = await listSessions(budget());
+        const live = sessions.filter((session) => !session.exited);
+        const liveNames = live.map((session) => session.name);
+        if (liveNames.includes(candidate)) {
+            // Windows pays one PowerShell CIM call (often 1-2 s) for the process
+            // table, so a live env name is trusted there; the reuse check stays
+            // POSIX-only and the table is read only when the name is not live.
+            if (platform === "win32")
+                return fromEnv;
+            const table = await processTable();
+            const ancestor = findAncestorServer(table, process.pid);
+            // A live session may have been created with this name after our session
+            // moved off it; another server carrying the name is what tells us so.
+            const reused = liveServers(table).some((server) => server.creationName === candidate && server.pid !== ancestor?.pid);
+            if (!reused)
+                return fromEnv;
+            const viaServer = await matchViaServer(candidate, isSelf, live, table, ancestor, budget);
+            if (viaServer)
+                return viaServer;
+            invalidateSelfResolutionCache(candidate);
+            throw sessionNotLiveError(candidate, source, liveNames);
+        }
+        if (aliases) {
+            const entry = aliases.readSessionAliases()[candidate];
+            if (entry && liveNames.includes(entry.current)) {
+                const table = await processTable();
+                if (entry.serverPid !== null &&
+                    liveServers(table).some((server) => server.pid === entry.serverPid)) {
+                    return { session: entry.current, source: "alias", requested: candidate };
+                }
+            }
+        }
+        const table = await processTable();
+        const ancestor = findAncestorServer(table, process.pid);
+        const viaServer = await matchViaServer(candidate, isSelf, live, table, ancestor, budget);
+        if (viaServer)
+            return viaServer;
+        invalidateSelfResolutionCache(candidate);
+        throw sessionNotLiveError(candidate, source, liveNames);
+    }
     async function resolveSession(explicit, callTimeoutMs = timeoutMs) {
-        return (sessionFromEnv(env, explicit) ??
-            sessionFromList(await listSessions(callTimeoutMs)));
+        const fromEnv = sessionFromEnv(env, explicit);
+        if (!fromEnv)
+            return sessionFromList(await listSessions(callTimeoutMs));
+        // Over SSH the process table describes the wrong machine; an explicit or
+        // env name is all this transport can trust.
+        if (ssh)
+            return fromEnv;
+        if (fromEnv.source === "arg" || fromEnv.source === "env_zswarm") {
+            rememberExplicitSession(fromEnv.session, fromEnv.source);
+        }
+        const resolved = await resolveCandidate(fromEnv, callTimeoutMs);
+        if (fromEnv.source === "env_zellij") {
+            selfResolved = resolved.session;
+        }
+        else if (fromEnv.source === "arg" || fromEnv.source === "env_zswarm") {
+            rememberExplicitSession(resolved.session, fromEnv.source);
+        }
+        return resolved;
+    }
+    /**
+     * Cache key for a self resolution: env name + pane id + the pane's ancestor
+     * server pid when known, so a reused name cannot be served from another
+     * pane's entry. On win32 the process table costs one PowerShell CIM call
+     * (often 1-2 s) and the fast path must not pay it, so the pid is left out.
+     */
+    async function selfResolutionKey(candidate) {
+        const pane = selfPaneId ?? "";
+        let pid = null;
+        if (platform !== "win32") {
+            try {
+                const table = await processTable();
+                pid = findAncestorServer(table, process.pid)?.pid ?? null;
+            }
+            catch {
+                pid = null;
+            }
+        }
+        return JSON.stringify([candidate, pane, pid]);
+    }
+    /**
+     * The live session this process runs in, resolved through its server
+     * process; null when there is no pane env or resolution fails. Cached per
+     * client and, for long-lived processes (MCP/serve), across clients for 30 s.
+     */
+    async function resolveSelf() {
+        if (ssh)
+            return null;
+        if (selfResolved)
+            return selfResolved;
+        if (selfFailureAt && now() - selfFailureAt < PROCESS_TABLE_TTL_MS)
+            return null;
+        const fromEnv = sessionFromEnv(env, null);
+        if (!fromEnv || fromEnv.source !== "env_zellij")
+            return null;
+        const key = await selfResolutionKey(fromEnv.session);
+        const cached = selfResolutionCache.get(key);
+        if (cached && Date.now() - cached.at <= SELF_RESOLUTION_TTL_MS) {
+            selfResolved = cached.name;
+            return cached.name;
+        }
+        if (cached)
+            selfResolutionCache.delete(key);
+        try {
+            const resolved = await resolveCandidate(fromEnv, timeoutMs);
+            selfResolved = resolved.session;
+            selfResolutionCache.set(key, {
+                env: fromEnv.session,
+                name: resolved.session,
+                at: Date.now(),
+            });
+            return selfResolved;
+        }
+        catch {
+            selfFailureAt = now();
+            return null;
+        }
+    }
+    /** Rename the session itself. Refuses a name that is already live. */
+    async function renameSession(input) {
+        const was = input.session.trim();
+        const name = input.name.trim();
+        if (!was)
+            throw new ZellijError("missing_session", "session required");
+        if (!name)
+            throw new ZellijError("missing_name", "name required");
+        const sessions = await listSessions(input.callTimeoutMs ?? timeoutMs, { fresh: true });
+        if (sessions.some((session) => !session.exited && session.name === name)) {
+            throw new ZellijError("name_taken", `session "${name}" is already live; pick another name or close it first`, { name });
+        }
+        // The server process keeps its pid across the rename; remember its
+        // identity before the old name is gone.
+        let serverPid = null;
+        let creation = null;
+        if (!ssh) {
+            const table = await processTable();
+            const byCreation = liveServers(table).find((server) => server.creationName === was);
+            if (byCreation) {
+                serverPid = byCreation.pid;
+                creation = byCreation.creationName;
+            }
+            else {
+                const remembered = aliases?.readSessionAliases();
+                const entry = remembered
+                    ? (remembered[was] ??
+                        Object.values(remembered).find((item) => item.current === was))
+                    : undefined;
+                if (entry?.serverPid != null) {
+                    serverPid = entry.serverPid;
+                    creation = entry.creation;
+                }
+                else if (was === (selfResolved ?? staticSelfSession)) {
+                    const ancestor = findAncestorServer(table, process.pid);
+                    if (ancestor) {
+                        serverPid = ancestor.pid;
+                        creation = ancestor.creationName;
+                    }
+                }
+            }
+        }
+        invalidateListings(was);
+        invalidateListings(name);
+        try {
+            await run(buildRenameSessionArgs(was, name), "zellij action rename-session", input.callTimeoutMs ?? timeoutMs);
+        }
+        finally {
+            invalidateListings(was);
+            invalidateListings(name);
+        }
+        if (aliases) {
+            aliases.recordSessionAlias(was, { current: name, serverPid, creation, at: now() });
+        }
+        if (was === selfResolved || was === staticSelfSession)
+            selfResolved = name;
+        // A rename invalidates every cached self resolution of the old name, for
+        // this client and for other clients in the process.
+        invalidateSelfResolutionCache(was);
+        invalidateSelfResolutionCache(name);
+        return { session: name, was };
+    }
+    /** Raw list-panes call: shared by the normal path and the failure diagnosis. */
+    async function fetchPanes(session, remaining) {
+        const result = await run(buildListPanesArgs(session), "zellij action list-panes", remaining());
+        return parsePaneList(result.stdout, result.stderr);
+    }
+    /**
+     * A trusted explicit name that just failed a Zellij call may be an old name
+     * whose rename zswarm has not recorded yet. Diagnose once, on the failure
+     * path only (passing calls keep their exact Zellij call counts):
+     * the session is live -> keep the original error; renamed -> record the
+     * alias and throw session_renamed; gone -> session_not_live + live list.
+     */
+    async function diagnoseFailedExplicitSession(session, err) {
+        if (!(err instanceof ZellijError) || err.code !== "zellij_failed")
+            return err;
+        // A timeout is not evidence of a dead name: Zellij fails fast for a
+        // missing session, and diagnosing a timeout only doubles the budget that
+        // callers are already sharing (status deadline tests pin this).
+        if (/timed out/i.test(err.message))
+            return err;
+        const source = explicitSessions.get(session);
+        if (ssh || !source)
+            return err;
+        try {
+            const deadline = Date.now() + Math.min(timeoutMs, 5_000);
+            const budget = () => Math.max(1, deadline - Date.now());
+            const listed = await listSessions(budget(), { fresh: true });
+            const live = listed.filter((item) => !item.exited);
+            const liveNames = live.map((item) => item.name);
+            if (liveNames.includes(session))
+                return err;
+            invalidateSelfResolutionCache(session);
+            const table = await processTable();
+            const byCreation = liveServers(table).filter((server) => server.creationName === session);
+            if (byCreation.length !== 1)
+                return sessionNotLiveError(session, source, liveNames);
+            const server = byCreation[0];
+            const withPanes = [];
+            for (const item of live) {
+                try {
+                    withPanes.push({ name: item.name, panes: await fetchPanes(item.name, budget) });
+                }
+                catch {
+                    // A session that closed mid-diagnosis cannot be the answer.
+                }
+            }
+            // Prefer the deterministic global assignment; fall back to the
+            // single-match test for a server the assignment could not pin.
+            const match = assignServersToSessions(table, withPanes).get(server.pid) ??
+                matchServerToSession(server.pid, table, withPanes);
+            if (!match)
+                return sessionNotLiveError(session, source, liveNames);
+            if (aliases) {
+                const entry = {
+                    current: match,
+                    serverPid: server.pid,
+                    creation: server.creationName,
+                    at: now(),
+                };
+                aliases.recordSessionAlias(session, entry);
+                if (server.creationName && server.creationName !== session) {
+                    aliases.recordSessionAlias(server.creationName, entry);
+                }
+            }
+            return new ZellijError("session_renamed", `session "${session}" was renamed to "${match}"; use session=${match} (zswarm now maps the old name)`, { requested: session, current: match, live: liveNames });
+        }
+        catch {
+            // Diagnosis is best-effort; the original failure is still the answer.
+            return err;
+        }
     }
     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);
+            try {
+                return await fetchPanes(session, remaining);
+            }
+            catch (err) {
+                throw await diagnoseFailedExplicitSession(session, err);
+            }
         });
     }
     async function injectPane(input) {
@@ -371,7 +787,14 @@ export function createZellijClient(options = {}) {
     return {
         zellijPath,
         selfPaneId,
-        selfSession,
+        /**
+         * The caller's session: the resolved live name once resolveSelf (or a
+         * self resolveSession) has run, else the raw ZELLIJ_SESSION_NAME. A getter
+         * so a rename resolution is visible to the self-pane guard.
+         */
+        get selfSession() {
+            return ssh ? null : (selfResolved ?? staticSelfSession);
+        },
         contextKey,
         invalidateListings,
         observeManifest,
@@ -383,6 +806,7 @@ export function createZellijClient(options = {}) {
         listSessions,
         deleteSession,
         resolveSession,
+        resolveSelf,
         listPanes,
         resolvePane,
         injectPane,
@@ -394,6 +818,7 @@ export function createZellijClient(options = {}) {
         newTab,
         renamePane,
         renameTab,
+        renameSession,
         focusPane,
         listTabs,
         dumpLayout,
@@ -415,5 +840,6 @@ export function createZellijClient(options = {}) {
         buildClosePaneArgs,
         buildNewPaneArgs,
         buildNewTabArgs,
+        buildRenameSessionArgs,
     };
 }

package/dist/zellij/panes.d.ts

@@ -16,7 +16,7 @@ export type ZellijPane = {
 };
 export declare function normalizePaneId(raw: string, isPlugin?: boolean): string;
 /** Parse `list-panes --json` output. */
-export declare function parsePaneList(stdout: string): ZellijPane[];
+export declare function parsePaneList(stdout: string, stderr?: string): ZellijPane[];
 /**
  * Find a pane by typed id, bare number, exact title, command, then partial
  * title. Ambiguity is an error rather than a guess.

package/dist/zellij/panes.js

@@ -38,17 +38,22 @@ function parsePaneRow(row) {
             : null,
     };
 }
+/** First 200 characters of what Zellij printed, for an actionable failure. */
+function paneListFailure(message, stdout, stderr) {
+    const detail = `${stdout}\n${stderr}`.trim().slice(0, 200);
+    return detail ? `${message}: ${detail}` : message;
+}
 /** Parse `list-panes --json` output. */
-export function parsePaneList(stdout) {
+export function parsePaneList(stdout, stderr = "") {
     let parsed;
     try {
         parsed = JSON.parse(stdout);
     }
     catch {
-        throw new ZellijError("zellij_failed", "list-panes returned non-JSON output");
+        throw new ZellijError("zellij_failed", paneListFailure("list-panes returned non-JSON output", stdout, stderr));
     }
     if (!Array.isArray(parsed)) {
-        throw new ZellijError("zellij_failed", "list-panes JSON was not an array");
+        throw new ZellijError("zellij_failed", paneListFailure("list-panes JSON was not an array", stdout, stderr));
     }
     const panes = [];
     for (const row of parsed) {

package/dist/zellij/server-identity.d.ts

@@ -0,0 +1,95 @@
+import type { ZellijPane } from "./panes.js";
+/**
+ * Identify a Zellij session through the server process that owns it.
+ *
+ * Zellij exports ZELLIJ_SESSION_NAME once, when a pane starts, and never
+ * updates it after `rename-session`. Worse, a renamed session's server process
+ * keeps its *creation* name on its command line forever. This module bridges
+ * the two: it reads the process table, finds the `zellij --server <path>`
+ * ancestor of the caller (or any live server), and matches a server to the
+ * session whose panes are its descendants.
+ *
+ * Everything here is pure and never throws: a failed read is an empty table.
+ */
+export type ProcInfo = {
+    pid: number;
+    ppid: number;
+    /** Full command line, args joined with spaces. */
+    args: string;
+};
+export type ServerInfo = {
+    pid: number;
+    creationName: string;
+    socketPath: string;
+};
+/** One row from a pane listing plus its session name. */
+export type SessionPanes = {
+    name: string;
+    panes: ZellijPane[];
+};
+export type ProcessRunner = (file: string, args: string[], options: {
+    timeout: number;
+    windowsHide?: boolean;
+}) => Promise<{
+    stdout: string;
+    stderr?: string;
+}>;
+export type ReadProcessTableOptions = {
+    /** Override process.platform (tests). */
+    platform?: NodeJS.Platform;
+    /** Injected execFile (tests); defaults to node:child_process. */
+    runner?: ProcessRunner;
+};
+/**
+ * Snapshot the local process table. Never throws: a failure returns [].
+ * Linux reads /proc; macOS/other POSIX shells out to `ps`; Windows asks
+ * PowerShell for Win32_Process. Both external reads are bounded at 5s.
+ */
+export declare function readProcessTable(opts?: ReadProcessTableOptions): Promise<ProcInfo[]>;
+/**
+ * Parse the argv of a `zellij --server <socketPath>` server process.
+ * Returns null for anything that is not a Zellij server. The creation name is
+ * the last path segment of the socket path (the name the session had when its
+ * server started; renames do not touch it).
+ */
+export declare function parseServerArgs(args: string): {
+    socketPath: string;
+    creationName: string;
+} | null;
+/**
+ * Walk parents from `pid` (up to 64 hops, stopping on a cycle or a missing
+ * row) and return the first Zellij server found, or null.
+ */
+export declare function findAncestorServer(table: ProcInfo[], pid: number): ServerInfo | null;
+/** Every Zellij server currently present in the table. */
+export declare function liveServers(table: ProcInfo[]): ServerInfo[];
+/** True when a pane row is the requested (non-plugin) pane id. */
+export declare function paneMatchesId(pane: ZellijPane, paneId: string): boolean;
+/**
+ * Pick the one live session whose panes belong to `serverPid`.
+ *
+ * The server's direct children are its panes' processes. A session matches
+ * when it has exactly as many non-plugin, non-exited, non-held panes as the
+ * server has direct children, and the panes can be assigned one-to-one to
+ * distinct children whose subtree argv (child plus descendants) contains the
+ * pane's command. With `opts.paneId`, the session must also contain that
+ * pane. Zero or several matches return null — this never guesses.
+ */
+export declare function matchServerToSession(serverPid: number, table: ProcInfo[], sessions: SessionPanes[], opts?: {
+    paneId?: string;
+}): string | null;
+/**
+ * Pair live servers with live sessions using forced assignments only:
+ *
+ * 1. A server whose creation name is a live session name is pinned to it when
+ *    that session fits. A creation name shared by two fitting servers (name
+ *    reuse) is a guess, so neither is pinned and the session stays unassigned.
+ * 2. Repeat until stable: an unpinned server with exactly one unpinned fitting
+ *    session is pinned to it, and an unpinned session fitted by exactly one
+ *    unpinned server pins that pair. Nothing else: no backtracking, no
+ *    picking among ties.
+ *
+ * Returns only the pinned pairs. Servers and sessions left ambiguous are
+ * absent; the caller still has the pane-id-filtered single-match test.
+ */
+export declare function assignServersToSessions(table: ProcInfo[], sessions: SessionPanes[]): Map<number, string>;