@zswarm/core 0.5.0 → 0.7.0

package/dist/host/cli.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { ZellijError } from "../errors.js";
-import { createStateStore } from "../state.js";
+import { createStateStore, defaultStateDir } from "../state.js";
 import { crewCheck, crewClient, crewDown, crewStart, crewStatus, crewUp } from "./crew.js";
 import { hostDoctor, hostInstall, hostInstallArgs, hostScriptPath } from "./host.js";
 import { listLeases } from "./lease.js";
@@ -151,6 +151,10 @@ async function relay(argv) {
         if (flags["--json"] === true)
             return json(() => ({ leases }));
         process.stdout.write(`${leaseTable(leases)}\n`);
+        if (leases.length === 0) {
+            // A tool that runs zswarm with its own ZSWARM_STATE_DIR keeps its leases there.
+            process.stderr.write(`no live leases in ${defaultStateDir()}; set ZSWARM_STATE_DIR to read another state directory\n`);
+        }
         return 0;
     }
     const cancelId = str(flags["--cancel"]);

package/dist/host/relay.d.ts

@@ -46,6 +46,9 @@ export type RelayConfig = {
     to: string;
     done: string;
     replyTo: string;
+    /** The reply pane's unique title when `replyTo` was a pane id: delivery tries
+     * the name first, because ids shift when panes are restarted or renumbered. */
+    replyToName?: string;
     replySession?: string;
     from: string;
     /** The target harness (`--harness`); sent with the body and the reply. */
@@ -112,6 +115,10 @@ export declare function fillMessage(template: string, fields: Record<string, str
  * the verdict and keeps waiting — the done line is the real proof of delivery.
  */
 export declare function softSendVerdict(res: OpsResult): boolean;
+/** The unique title of the reply pane when `replyTo` is a pane id (`terminal_14`, `14`),
+ * else undefined: an untitled pane (default shell title) or a title shared by two panes
+ * keeps delivery by id. */
+export declare function replyPaneName(cfg: Pick<RelayConfig, "replyTo" | "replySession">, env: NodeJS.ProcessEnv, call: NonNullable<RelayDeps["call"]>): Promise<string | undefined>;
 /** Paste `body` into the reply pane, retrying with backoff; false leaves it in undelivered/. */
 export declare function deliverMessage(cfg: RelayConfig, body: string, dir: string, deps?: RelayDeps): Promise<boolean>;
 /** The waiting loop; returns the final status and the message it delivered or left behind. */

package/dist/host/relay.js

@@ -111,6 +111,28 @@ export function softSendVerdict(res) {
     const submitted = res.data?.submitted;
     return submitted !== true;
 }
+/** The unique title of the reply pane when `replyTo` is a pane id (`terminal_14`, `14`),
+ * else undefined: an untitled pane (default shell title) or a title shared by two panes
+ * keeps delivery by id. */
+export async function replyPaneName(cfg, env, call) {
+    const ref = cfg.replyTo.trim();
+    if (!/^(terminal_)?\d+$/i.test(ref))
+        return undefined;
+    const args = { op: "list" };
+    if (cfg.replySession)
+        args.session = cfg.replySession;
+    const res = await call(args, localEnv(env)).catch(() => null);
+    if (!res?.ok)
+        return undefined;
+    const panes = (res.data.panes ?? [])
+        .filter((p) => !p.isPlugin);
+    const id = `terminal_${ref.replace(/^terminal_/i, "")}`;
+    const title = panes.find((p) => p.id === id)?.title?.trim();
+    if (!title || /^(Pane #\d+|-?(zsh|bash|fish|sh|pwsh|powershell))$/i.test(title))
+        return undefined;
+    const same = panes.filter((p) => (p.title ?? "").trim().toLowerCase() === title.toLowerCase());
+    return same.length === 1 ? title : undefined;
+}
 /** Paste `body` into the reply pane, retrying with backoff; false leaves it in undelivered/. */
 export async function deliverMessage(cfg, body, dir, deps = {}) {
     const env = deps.env ?? process.env;
@@ -125,13 +147,20 @@ export async function deliverMessage(cfg, body, dir, deps = {}) {
         await sleep(delay * 1000);
         // Generous Zellij budgets: this runs exactly when the machine is busiest.
         const args = {
-            op: "send", to: cfg.replyTo, body, from: cfg.from, fresh: true, settleMs: 800, observeMs: 30_000, timeoutMs: 60_000,
+            op: "send", to: cfg.replyToName ?? cfg.replyTo, body, from: cfg.from, fresh: true, settleMs: 800, observeMs: 30_000,
+            timeoutMs: 60_000,
         };
         if (cfg.replySession)
             args.session = cfg.replySession;
         if (cfg.harness)
             args.harness = cfg.harness;
-        const res = await call(args, localEnv(env)).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+        const send = (a) => call(a, localEnv(env)).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+        let res = await send(args);
+        if (!res.ok && cfg.replyToName && (res.error.code === "peer_not_found" || res.error.code === "peer_ambiguous")) {
+            // The named pane is gone or now ambiguous: the id it had at start is the last resort.
+            log(`message attempt ${i + 1}: pane "${cfg.replyToName}" ${res.error.code}; trying ${cfg.replyTo}`);
+            res = await send({ ...args, to: cfg.replyTo });
+        }
         if (res.ok) {
             const submitted = String(res.data?.submitted ?? "unknown");
             recordDelivery(dir, submitted, now());
@@ -430,6 +459,7 @@ export async function startRelay(input) {
     };
     // Read the body before the relay directory (and its token copy) exists.
     const body = input.bodyFile ? readFileSync(input.bodyFile, "utf8") : undefined;
+    cfg.replyToName = await replyPaneName(cfg, env, input.deps?.call ?? ((args, e) => dispatchZswarm(args, undefined, { env: e })));
     const dir = prepareRelay(cfg, { check: input.check, message: input.message }, env);
     const store = input.store ?? createStateStore({ env });
     const leaseTarget = { serve, session: cfg.session, pane: cfg.to };

package/dist/index.d.ts

@@ -5,11 +5,12 @@ export { createGitClient, defaultWorktreeRoot, normalizeRepoPath, parseWorktreeL
 export { expandHomePath, looksLikeZswarmBinary, isZellijVersionOutput, resolveZellijBinary, resetZellijIdentityCache, sanitizeZellijEnv, validateSshDestination, validateSshMode, type ZellijExecFn, type ZellijExecResult, } from "./zellij/binary.js";
 export { normalizePaneId, parsePaneList, resolvePane, type ZellijPane, } from "./zellij/panes.js";
 export { liveSessionNames, parseCreatedAge, parseSessionList, resolveSelfPaneId, resolveSelfSession, type ZellijSession, type ZellijSessionResolve, } from "./zellij/session.js";
-export { buildClosePaneArgs, buildDumpArgs, buildLaunchPluginArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, scrollbackPayload, waitPayload, type LaunchPluginInput, type NewPaneInput, type NewTabInput, type PaneDirection, type PipeInput, type ScrollbackRequest, type WaitRequest, } from "./zellij/args.js";
+export { assignServersToSessions, findAncestorServer, liveServers, matchServerToSession, paneMatchesId, parseServerArgs, readProcessTable, type ProcInfo, type ProcessRunner, type ReadProcessTableOptions, type ServerInfo, type SessionPanes, } from "./zellij/server-identity.js";
+export { buildClosePaneArgs, buildDumpArgs, buildLaunchPluginArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildRenameSessionArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, scrollbackPayload, waitPayload, type LaunchPluginInput, type NewPaneInput, type NewTabInput, type PaneDirection, type PipeInput, type ScrollbackRequest, type WaitRequest, } from "./zellij/args.js";
 export { busPluginUrl, busToPanes, isBusPluginPane, nextConfigKey, parseBusReply, parseScrollbackReply, resolveBusPlugin, scrollbackToScreen, BUS_PIPE_NAME, DEFAULT_BUS_KEY, DEFAULT_BUS_TIMEOUT_MS, type BusMarker, type BusPane, type BusScrollback, type BusScrollbackPane, type BusSnapshot, } from "./zellij/bus.js";
 export { busSnapshot, closeBusPluginPanes, planBus, resetBusCache, type BusPlan, } from "./ops/bus.js";
-export { createZellijClient, type ZellijClient, type ZellijClientOptions, type ZellijTransport, } from "./zellij/client.js";
-export { createStateStore, defaultStateDir, type LeaseRecord, type LogEntry, type SignalChannel, type StateStore, type StateStoreOptions, } from "./state.js";
+export { createZellijClient, resetSelfResolutionCache, type ZellijClient, type ZellijClientOptions, type ZellijTransport, } from "./zellij/client.js";
+export { createStateStore, defaultStateDir, type LeaseRecord, type LogEntry, type SessionAliasEntry, type SessionAliasMap, type SignalChannel, type StateStore, type StateStoreOptions, } from "./state.js";
 export { findLease, leaseKey, leaseStale, listLeases, releaseLease, releaseLeaseKey, takeLease, type LeaseTakeInput, type LeaseTakeResult, type LeaseTarget, } from "./host/lease.js";
 export { dispatchZswarm, resolveInvocationEnv } from "./ops/dispatch.js";
 export { EXIT_WAIT_MS, HANDOFF_INLINE_MAX, HANDOFF_MARKER, HANDOFF_SELF_WAIT_MS, READY_SETTLE_MS, READY_STABLE_GAP_MS, READY_WAIT_MS, restartLaunchCommand, restartPane, restartPaneKind, type RestartPaneKind, type RestartStep, } from "./ops/restart.js";
@@ -38,6 +39,6 @@ export { findPython, runSlot, slotScriptPath } from "./host/slot.js";
 export { installServeService, serveServiceName, serveServiceSpec, serveTokenFromEnv, serveTokenPath, uninstallServeService, SERVE_AWAIT_SESSION_ENV, SERVE_TOKEN_FILE_ENV, type ServeServiceInput, } from "./host/serve-service.js";
 export { accountArgv, installServices, launchdLabel, launchdPlist, removeServices, serviceAccount, serviceStates, systemdUnitName, systemdUnits, writeAccountFile, type Runner, type ServiceAccount, type ServiceHost, type ServiceKind, type ServiceSpec, type ServiceState, } from "./host/services.js";
 export { crewCheck, crewClient, crewDir, crewDown, crewServiceSpecs, crewStart, crewStatus, crewUp, firstLayoutPane, layoutPaneNames, parseEnvFile, type CrewDeps, type CrewUpInput, } from "./host/crew.js";
-export { cancelAllTo, cancelRelay, deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, listRelays, prepareRelay, pruneRelays, relayLoop, relaysDir, runRelayDir, scrubRelayToken, startRelay, waitForRelay, type RelayAdminDeps, type RelayCancelResult, type RelayConfig, type RelayDeps, type RelayJob, type RelayJobRunner, type RelayRow, type RelayStartInput, type RelayStatus, } from "./host/relay.js";
+export { cancelAllTo, cancelRelay, deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, listRelays, prepareRelay, pruneRelays, relayLoop, relaysDir, replyPaneName, runRelayDir, scrubRelayToken, startRelay, waitForRelay, type RelayAdminDeps, type RelayCancelResult, type RelayConfig, type RelayDeps, type RelayJob, type RelayJobRunner, type RelayRow, type RelayStartInput, type RelayStatus, } from "./host/relay.js";
 export { hostChecks, hostDoctor, hostInstall, hostInstallArgs, hostScriptPath, parseHostReport, type HostCheck, type HostDoctorInput, type HostInstallInput, type SshRunner, } from "./host/host.js";
 export { isSelfPane } from "./ops/guards.js";

package/dist/index.js

@@ -5,10 +5,11 @@ export { createGitClient, defaultWorktreeRoot, normalizeRepoPath, parseWorktreeL
 export { expandHomePath, looksLikeZswarmBinary, isZellijVersionOutput, resolveZellijBinary, resetZellijIdentityCache, sanitizeZellijEnv, validateSshDestination, validateSshMode, } from "./zellij/binary.js";
 export { normalizePaneId, parsePaneList, resolvePane, } from "./zellij/panes.js";
 export { liveSessionNames, parseCreatedAge, parseSessionList, resolveSelfPaneId, resolveSelfSession, } from "./zellij/session.js";
-export { buildClosePaneArgs, buildDumpArgs, buildLaunchPluginArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, scrollbackPayload, waitPayload, } from "./zellij/args.js";
+export { assignServersToSessions, findAncestorServer, liveServers, matchServerToSession, paneMatchesId, parseServerArgs, readProcessTable, } from "./zellij/server-identity.js";
+export { buildClosePaneArgs, buildDumpArgs, buildLaunchPluginArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildRenameSessionArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, scrollbackPayload, waitPayload, } from "./zellij/args.js";
 export { busPluginUrl, busToPanes, isBusPluginPane, nextConfigKey, parseBusReply, parseScrollbackReply, resolveBusPlugin, scrollbackToScreen, BUS_PIPE_NAME, DEFAULT_BUS_KEY, DEFAULT_BUS_TIMEOUT_MS, } from "./zellij/bus.js";
 export { busSnapshot, closeBusPluginPanes, planBus, resetBusCache, } from "./ops/bus.js";
-export { createZellijClient, } from "./zellij/client.js";
+export { createZellijClient, resetSelfResolutionCache, } from "./zellij/client.js";
 export { createStateStore, defaultStateDir, } from "./state.js";
 export { findLease, leaseKey, leaseStale, listLeases, releaseLease, releaseLeaseKey, takeLease, } from "./host/lease.js";
 export { dispatchZswarm, resolveInvocationEnv } from "./ops/dispatch.js";
@@ -36,6 +37,6 @@ export { findPython, runSlot, slotScriptPath } from "./host/slot.js";
 export { installServeService, serveServiceName, serveServiceSpec, serveTokenFromEnv, serveTokenPath, uninstallServeService, SERVE_AWAIT_SESSION_ENV, SERVE_TOKEN_FILE_ENV, } from "./host/serve-service.js";
 export { accountArgv, installServices, launchdLabel, launchdPlist, removeServices, serviceAccount, serviceStates, systemdUnitName, systemdUnits, writeAccountFile, } from "./host/services.js";
 export { crewCheck, crewClient, crewDir, crewDown, crewServiceSpecs, crewStart, crewStatus, crewUp, firstLayoutPane, layoutPaneNames, parseEnvFile, } from "./host/crew.js";
-export { cancelAllTo, cancelRelay, deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, listRelays, prepareRelay, pruneRelays, relayLoop, relaysDir, runRelayDir, scrubRelayToken, startRelay, waitForRelay, } from "./host/relay.js";
+export { cancelAllTo, cancelRelay, deliverMessage, doneLines, fillMessage, freshDoneLine, launchRelay, listRelays, prepareRelay, pruneRelays, relayLoop, relaysDir, replyPaneName, runRelayDir, scrubRelayToken, startRelay, waitForRelay, } from "./host/relay.js";
 export { hostChecks, hostDoctor, hostInstall, hostInstallArgs, hostScriptPath, parseHostReport, } from "./host/host.js";
 export { isSelfPane } from "./ops/guards.js";

package/dist/ops/delivery.d.ts

@@ -26,8 +26,12 @@ export type SenderOrigin = {
  * splittable), and the result is capped at 64 chars.
  */
 export declare function sanitizeOriginPart(raw: unknown): string | null;
-/** The origin of the caller's own process, read from its environment. */
-export declare function resolveSenderOrigin(env: NodeJS.ProcessEnv): SenderOrigin;
+/**
+ * The origin of the caller's own process, read from its environment.
+ * `session` overrides the env name when the caller has resolved the live
+ * session through the process table (a renamed session leaves the env stale).
+ */
+export declare function resolveSenderOrigin(env: NodeJS.ProcessEnv, session?: string | null): SenderOrigin;
 /**
  * The origin carried by a serve request. Only the serve worker trusts it: a
  * local caller cannot claim another pane. Missing/garbage input (an older

package/dist/ops/delivery.js

@@ -20,8 +20,12 @@ export function sanitizeOriginPart(raw) {
         ? cleaned
         : cleaned.slice(0, ORIGIN_PART_MAX).replace(/_+$/, "");
 }
-/** The origin of the caller's own process, read from its environment. */
-export function resolveSenderOrigin(env) {
+/**
+ * The origin of the caller's own process, read from its environment.
+ * `session` overrides the env name when the caller has resolved the live
+ * session through the process table (a renamed session leaves the env stale).
+ */
+export function resolveSenderOrigin(env, session) {
     const configured = env.ZSWARM_HOST;
     const host = configured === undefined
         ? sanitizeOriginPart(hostname().split(".")[0])
@@ -30,7 +34,7 @@ export function resolveSenderOrigin(env) {
             : sanitizeOriginPart(configured);
     return {
         host,
-        session: sanitizeOriginPart(resolveSelfSession(env)),
+        session: sanitizeOriginPart(session ?? resolveSelfSession(env)),
         pane: sanitizeOriginPart(resolveSelfPaneId(env)),
         via: null,
     };

package/dist/ops/dispatch.js

@@ -216,6 +216,18 @@ async function unglueScreen(client, session, pane, text, full, fromBus) {
     }
     return unfoldScreen(ansi, columns) ?? text;
 }
+/**
+ * Ops whose sender header or self-pane guard needs the caller's live session.
+ * Read-only ops never pay for that resolution.
+ */
+const SELF_SESSION_OPS = new Set([
+    "send",
+    "broadcast",
+    "keys",
+    "interrupt",
+    "close",
+    "restart",
+]);
 async function dispatchOperation(args, injected, deps, context, env) {
     const op = String(args.op ?? "");
     const verbose = isVerbose(args);
@@ -322,10 +334,20 @@ async function dispatchOperation(args, injected, deps, context, env) {
                 manager: deps.serveTunnels,
             });
         }
-        const baseClient = injected ?? createZellijClient({ env, signal, cache: isTrue(args.fresh) ? false : undefined });
+        const baseClient = injected ??
+            createZellijClient({
+                env,
+                signal,
+                cache: isTrue(args.fresh) ? false : undefined,
+                // Rename memory so stale env names keep working across runs.
+                aliases: state(),
+            });
         const client = {
             ...baseClient,
             get transport() { return baseClient.transport; },
+            // Pass the getter through: a spread would freeze the env value and the
+            // self-pane guard would compare a stale name.
+            get selfSession() { return baseClient.selfSession; },
             async resolveSession(...input) {
                 const resolved = await baseClient.resolveSession(...input);
                 context.session = resolved.session;
@@ -333,6 +355,15 @@ async function dispatchOperation(args, injected, deps, context, env) {
                 return resolved;
             },
         };
+        // Only ops that build a sender header or compare against the caller's own
+        // pane need the resolved self session; read-only ops must not pay a
+        // Zellij round-trip for it.
+        if (deps.viaServe !== true && SELF_SESSION_OPS.has(op) && typeof client.resolveSelf === "function") {
+            // The pane's ZELLIJ_SESSION_NAME can be stale after a rename; the header
+            // must name the live session peers can reply to.
+            const self = await client.resolveSelf();
+            args = { ...args, origin: resolveSenderOrigin(env, self) };
+        }
         switch (op) {
             case "sessions": {
                 // Resolve SSH/IPC first so a Windows interactive crew is reachable

package/dist/ops/panes.d.ts

@@ -3,7 +3,8 @@ import type { ZellijClient } from "../zellij/client.js";
 import type { OpsResult } from "./types.js";
 /**
  * Give a pane (or its tab) a stable name, so peers can be addressed as
- * `reviewer` instead of whatever id Zellij handed out.
+ * `reviewer` instead of whatever id Zellij handed out. With `sessionName`
+ * (and no `to`/`tab`) it renames the session itself instead.
  */
 export declare function renameTarget(client: ZellijClient, args: Record<string, unknown>, policy?: Policy): Promise<OpsResult>;
 export declare function focusTarget(client: ZellijClient, args: Record<string, unknown>, policy?: Policy): Promise<OpsResult>;

package/dist/ops/panes.js

@@ -7,14 +7,27 @@ async function session(client, args) {
 }
 /**
  * Give a pane (or its tab) a stable name, so peers can be addressed as
- * `reviewer` instead of whatever id Zellij handed out.
+ * `reviewer` instead of whatever id Zellij handed out. With `sessionName`
+ * (and no `to`/`tab`) it renames the session itself instead.
  */
 export async function renameTarget(client, args, policy) {
+    const sessionName = optionalString(args.sessionName);
+    const tabKey = optionalString(args.tab);
+    const to = optionalString(args.to);
+    if (sessionName && !tabKey && !to) {
+        // Renaming the session itself: resolve the old name first so a stale
+        // ZELLIJ_SESSION_NAME or alias still names the live session.
+        const resolved = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+        const renamed = await client.renameSession({
+            session: resolved.session,
+            name: sessionName,
+        });
+        return { ok: true, data: { session: renamed.session, was: renamed.was } };
+    }
     const name = optionalString(args.name);
     if (!name)
         throw new ZellijError("missing_name", "name required");
     const sess = await session(client, args);
-    const tabKey = optionalString(args.tab);
     if (tabKey) {
         const tab = client.resolveTab(await client.listTabs(sess, undefined, { fresh: true }), tabKey);
         const renamed = await client.renameTab({
@@ -27,7 +40,6 @@ export async function renameTarget(client, args, policy) {
             data: { session: sess, tab: renamed.tabId, was: tab.name, name },
         };
     }
-    const to = optionalString(args.to);
     if (!to)
         throw new ZellijError("missing_peer", "to (or tab) required");
     const pane = client.resolvePane(await client.listPanes(sess, undefined, { fresh: true }), to);

package/dist/schema.js

@@ -446,6 +446,13 @@ export const PARAMS = [
         ops: ["spawn", "rename"],
         description: "spawn: pane (or tab) name; rename: the new name",
     },
+    {
+        name: "sessionName",
+        type: "string",
+        flags: ["--session-name"],
+        ops: ["rename"],
+        description: "rename: rename the session itself to this name; the old name stays an alias so panes that still carry it keep working",
+    },
     {
         name: "submit",
         type: "string",

package/dist/state.d.ts

@@ -55,6 +55,20 @@ export type LeaseRecord = {
     /** Relays that forced through while this lease was held. */
     sharedBy?: string[];
 };
+/**
+ * What an old session name now resolves to. Zellij never updates the
+ * ZELLIJ_SESSION_NAME a pane started with, so after a rename every older pane
+ * keeps the old name; this is how zswarm maps it to the live session. The
+ * server pid pins the entry to the process that owned the old name, so a
+ * later session reusing that name does not inherit the alias.
+ */
+export type SessionAliasEntry = {
+    current: string;
+    serverPid: number | null;
+    creation: string | null;
+    at: number;
+};
+export type SessionAliasMap = Record<string, SessionAliasEntry>;
 /** How much of the end of the log `readLog` reads; older entries are not shown. */
 export declare const LOG_TAIL_BYTES: number;
 /**
@@ -78,6 +92,8 @@ export declare function createStateStore(options?: StateStoreOptions): {
     readCursor: (key: string) => string | null;
     writeCursor: (key: string, text: string) => void;
     clearCursor: (key: string) => void;
+    readSessionAliases: () => SessionAliasMap;
+    recordSessionAlias: (oldName: string, entry: SessionAliasEntry) => void;
     readBus: (session: string) => BusMarkerRecord | null;
     writeBus: (session: string, marker: BusMarkerRecord) => void;
     clearBus: (session?: string) => void;

package/dist/state.js

@@ -9,6 +9,8 @@ const CURSORS_LOCK = "cursors.lock";
 const BUS_FILE = "bus.json";
 const LEASES_FILE = "leases.json";
 const LEASES_LOCK = "leases.lock";
+const SESSION_ALIASES_FILE = "session-aliases.json";
+const SESSION_ALIASES_LOCK = "session-aliases.lock";
 /** How much of the end of the log `readLog` reads; older entries are not shown. */
 export const LOG_TAIL_BYTES = 512 * 1024;
 /**
@@ -397,6 +399,52 @@ export function createStateStore(options = {}) {
             writeJson(CURSORS_FILE, all);
         });
     }
+    function asAliasEntry(value) {
+        if (!value || typeof value !== "object")
+            return null;
+        const rec = value;
+        if (typeof rec.current !== "string" || !rec.current)
+            return null;
+        return {
+            current: rec.current,
+            serverPid: typeof rec.serverPid === "number" &&
+                Number.isInteger(rec.serverPid) &&
+                rec.serverPid > 0
+                ? rec.serverPid
+                : null,
+            creation: typeof rec.creation === "string" && rec.creation ? rec.creation : null,
+            at: typeof rec.at === "number" ? rec.at : 0,
+        };
+    }
+    function readSessionAliases() {
+        const raw = readJson(SESSION_ALIASES_FILE, {});
+        const out = {};
+        for (const [name, entry] of Object.entries(raw)) {
+            const parsed = asAliasEntry(entry);
+            if (parsed)
+                out[name] = parsed;
+        }
+        return out;
+    }
+    /**
+     * Remember `oldName -> entry.current` and repoint every existing entry whose
+     * current name was the old one, so rename chains A -> B -> C leave both A
+     * and B resolving to C.
+     */
+    function recordSessionAlias(oldName, entry) {
+        const key = oldName.trim();
+        if (!key)
+            return;
+        withFileLock(SESSION_ALIASES_LOCK, () => {
+            const all = readSessionAliases();
+            for (const [name, previous] of Object.entries(all)) {
+                if (previous.current === key)
+                    all[name] = { ...previous, current: entry.current };
+            }
+            all[key] = entry;
+            writeJson(SESSION_ALIASES_FILE, all);
+        });
+    }
     function asMarker(value) {
         if (!value || typeof value !== "object")
             return null;
@@ -495,6 +543,8 @@ export function createStateStore(options = {}) {
         readCursor,
         writeCursor,
         clearCursor,
+        readSessionAliases,
+        recordSessionAlias,
         readBus,
         writeBus,
         clearBus,

package/dist/zellij/args.d.ts

@@ -88,6 +88,8 @@ export declare function buildSendKeysArgs(session: string, paneId: string, keys:
 export declare function buildWriteCharsArgs(session: string, paneId: string, chars: string): string[];
 export declare function buildRenamePaneArgs(session: string, paneId: string, name: string): string[];
 export declare function buildRenameTabArgs(session: string, tabId: number, name: string): string[];
+/** Rename the session itself: `zellij --session <old> action rename-session <new>`. */
+export declare function buildRenameSessionArgs(session: string, name: string): string[];
 export declare function buildFocusPaneArgs(session: string, paneId: string): string[];
 export declare function buildListTabsArgs(session: string): string[];
 export declare function buildDumpLayoutArgs(session: string): string[];

package/dist/zellij/args.js

@@ -183,6 +183,10 @@ export function buildRenameTabArgs(session, tabId, name) {
         name,
     ];
 }
+/** Rename the session itself: `zellij --session <old> action rename-session <new>`. */
+export function buildRenameSessionArgs(session, name) {
+    return [...sessionPrefix(session), "action", "rename-session", name];
+}
 export function buildFocusPaneArgs(session, paneId) {
     return [
         ...sessionPrefix(session),

package/dist/zellij/client.d.ts

@@ -1,11 +1,13 @@
 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 { buildClosePaneArgs, buildDumpArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildRenameSessionArgs, 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 SenderOrigin } from "../ops/delivery.js";
 import { type ZellijExecFn } from "./binary.js";
 import { normalizePaneId, resolvePane, type ZellijPane } from "./panes.js";
+import { type ProcInfo } from "./server-identity.js";
 import { type ZellijSession, type ZellijSessionResolve } from "./session.js";
+import type { SessionAliasEntry, SessionAliasMap } from "../state.js";
 export type ZellijClientOptions = {
     exec?: ZellijExecFn;
     zellijPath?: string;
@@ -18,7 +20,18 @@ export type ZellijClientOptions = {
     cache?: ListingCache | false;
     /** Clock for cache TTLs; process deadlines continue using wall time. */
     now?: () => number;
+    /** Rename memory (StateStore); injected by dispatch, or by tests. */
+    aliases?: {
+        readSessionAliases(): SessionAliasMap;
+        recordSessionAlias(oldName: string, entry: SessionAliasEntry): void;
+    };
+    /** Process-table snapshot override (tests); defaults to a real read. */
+    processTable?: () => ProcInfo[] | Promise<ProcInfo[]>;
+    /** Platform override (tests); defaults to process.platform. */
+    platform?: NodeJS.Platform;
 };
+/** Test helper: forget every cached self resolution (and its process table). */
+export declare function resetSelfResolutionCache(): void;
 export type ZellijTransport = {
     kind: "local" | "ssh";
     mode: "local" | "ssh" | "interactive";
@@ -33,7 +46,12 @@ export type ZellijTransport = {
 export declare function createZellijClient(options?: ZellijClientOptions): {
     zellijPath: string;
     selfPaneId: string | null;
-    selfSession: string | null;
+    /**
+     * 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.
+     */
+    readonly selfSession: string | null;
     contextKey: () => string;
     invalidateListings: (session: string) => void;
     observeManifest: (session: string, revision: string) => void;
@@ -45,6 +63,7 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
     }) => Promise<ZellijSession[]>;
     deleteSession: (name: string, callTimeoutMs?: number) => Promise<void>;
     resolveSession: (explicit?: string | null, callTimeoutMs?: number) => Promise<ZellijSessionResolve>;
+    resolveSelf: () => Promise<string | null>;
     listPanes: (session: string, callTimeoutMs?: number, opts?: {
         fresh?: boolean;
     }) => Promise<ZellijPane[]>;
@@ -121,6 +140,14 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
         session: string;
         name: string;
     }>;
+    renameSession: (input: {
+        session: string;
+        name: string;
+        callTimeoutMs?: number;
+    }) => Promise<{
+        session: string;
+        was: string;
+    }>;
     focusPane: (input: {
         session: string;
         paneId: string;
@@ -194,5 +221,6 @@ export declare function createZellijClient(options?: ZellijClientOptions): {
     buildClosePaneArgs: typeof buildClosePaneArgs;
     buildNewPaneArgs: typeof buildNewPaneArgs;
     buildNewTabArgs: typeof buildNewTabArgs;
+    buildRenameSessionArgs: typeof buildRenameSessionArgs;
 };
 export type ZellijClient = ReturnType<typeof createZellijClient>;