@zswarm/core 0.1.5 → 0.1.7

package/dist/ops/dispatch.js

@@ -6,21 +6,60 @@ import { assertOpAllowed, assertPaneAllowed, loadPolicy, } from "../policy.js";
 import { createStateStore } from "../state.js";
 import { busToPanes } from "../zellij/bus.js";
 import { broadcast } from "./broadcast.js";
-import { busChanged, busOp, busScreens, busSnapshot, busWait } from "./bus.js";
+import { busChanged, busOp, busScreens, busSnapshot, busWait, planBus } from "./bus.js";
 import { dumpLayoutOp, focusTarget, listTabsOp, renameTarget, stackTargets, } from "./panes.js";
 import { peerCheckpoint, peerDiff } from "./review.js";
 import { attachKnownSender, deliverTo, withSenderLabel, selfPaneTitle } from "./delivery.js";
-import { assertNotPlugin, assertNotSelf, assertPaneExpects, assertWritable, } from "./guards.js";
+import { assertNotPlugin, assertNotSelf, assertExpectedScreen, assertWritable, } from "./guards.js";
 import { readDeliveryLog } from "./log.js";
 import { awaitSignal, listSignals, postSignal } from "./signals.js";
 import { spawnPane } from "./spawn.js";
-import { peerStatus } from "./status.js";
+import { observationBudget } from "./observation.js";
+import { invocationContext } from "./routing.js";
+import { DEFAULT_STATUS_TIMEOUT_MS, peerStatus, } from "./status.js";
 import { tailPane } from "./tail.js";
 import { OP_NAMES } from "../schema.js";
-import { dumpMaxChars, fail, isTrue, isVerbose, optionalString, paneViewBus, paneViewFull, paneViewSlim, throwIfAborted, truncateDumpText, } from "./util.js";
+import { dumpMaxChars, fail, isTrue, isVerbose, numberArg, optionalString, paneViewBus, paneViewFull, paneViewSlim, throwIfAborted, truncateDumpText, } from "./util.js";
 import { waitForPane } from "./wait.js";
 import { listPeerWorktrees, removePeerWorktree } from "./worktree.js";
 import { callServe, installServeLogon, serveCallTimeout, uninstallServeLogon, } from "./serve.js";
+/**
+ * Per-invocation routing from `--local` / `--ssh`. `--local` clears both SSH
+ * and serve (and remote IPC). `--ssh` sets the destination for this call and
+ * clears serve so the flag wins over a sticky ZSWARM_SERVE.
+ */
+export function resolveInvocationEnv(args, base) {
+    const local = isTrue(args.local);
+    const sshDest = typeof args.ssh === "string" && args.ssh.trim() ? args.ssh.trim() : null;
+    const serveAddress = optionalString(args.serveAddress);
+    if (Number(local) + Number(Boolean(sshDest)) + Number(Boolean(serveAddress)) > 1) {
+        throw new ZellijError("usage", "choose only one of --local, --ssh, or --serve");
+    }
+    if (!local && !sshDest && !serveAddress)
+        return base;
+    const env = { ...base };
+    if (serveAddress) {
+        env.ZSWARM_SERVE = serveAddress;
+        delete env.ZSWARM_SSH;
+        return env;
+    }
+    if (local) {
+        delete env.ZSWARM_SSH;
+        delete env.ZSWARM_SSH_OPTS;
+        delete env.ZSWARM_SSH_MODE;
+        delete env.ZSWARM_SSH_BIN;
+        delete env.ZSWARM_TMP;
+        delete env.ZSWARM_REMOTE_BIN;
+        delete env.ZSWARM_REMOTE_SHELL;
+        delete env.ZSWARM_SERVE;
+        delete env.ZSWARM_SERVE_TOKEN;
+        return env;
+    }
+    env.ZSWARM_SSH = sshDest;
+    delete env.ZSWARM_SERVE;
+    delete env.ZSWARM_SERVE_TOKEN;
+    return env;
+}
 /** Same default `wait` applies: match when a needle is given, else idle. */
 function waitMode(args) {
     const requested = typeof args.for === "string" ? args.for.trim() : "";
@@ -53,40 +92,54 @@ function assertSshGitAllowed(env, op, args) {
         : "uses local git";
     throw new ZellijError("ssh_git_unsupported", `${op} ${why}; ZSWARM_SSH only forwards Zellij. Run zswarm serve on the host that owns the session`);
 }
-async function resolveTarget(client, args, state, clock, env, policy, op) {
+async function resolveTarget(client, args, state, clock, env, policy, op, signal) {
     const to = String(args.to ?? "").trim();
     if (!to)
         throw new ZellijError("missing_peer", "to required");
-    const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
-    // The plugin manifest carries no cwd/command/floating, so verbose
-    // responses have to go the polling route.
-    const bus = isVerbose(args)
-        ? null
-        : await busSnapshot(client, state, session, clock, env);
+    const budget = observationBudget(clock, numberArg(args, "timeoutMs", 30_000, { min: 1, max: 900_000 }), signal);
+    const observeMs = numberArg(args, "observeMs", 1_000, { min: 0, max: 30_000 });
+    const { session } = await client.resolveSession(optionalString(args.session), budget.require());
+    const bus = isVerbose(args) ? null : await busSnapshot(client, state, session, clock, env, "status", {
+        deadlineAt: budget.deadline, signal,
+    });
     let panes = null;
     if (bus) {
-        const busPanes = busToPanes(bus.snapshot);
+        const snapshot = busToPanes(bus.snapshot);
         try {
-            client.resolvePane(busPanes, to);
-            panes = busPanes;
+            client.resolvePane(snapshot, to);
+            panes = snapshot;
         }
-        catch {
-            // A command-shaped `to` only matches the polled list.
+        catch { /* An absent title/command/ID gets a fresh direct observation. */ }
+    }
+    const until = Math.min(budget.deadline, clock.now() + observeMs);
+    let pane;
+    let fresh = isTrue(args.fresh) || Boolean(op);
+    for (;;) {
+        const left = observeMs === 0 ? budget.require() : Math.min(budget.require(), Math.max(1, until - clock.now()));
+        panes ??= await client.listPanes(session, left, { fresh });
+        throwIfAborted(signal);
+        try {
+            pane = client.resolvePane(panes, to);
+            break;
+        }
+        catch (err) {
+            if (!(err instanceof ZellijError) || err.code !== "peer_not_found" || clock.now() >= until)
+                throw err;
+            await budget.pause(until);
+            if (clock.now() >= until)
+                throw err;
+            panes = null;
+            fresh = true;
         }
     }
-    if (!panes)
-        panes = await client.listPanes(session);
-    const pane = client.resolvePane(panes, to);
     if (policy && op)
         assertPaneAllowed(policy, pane, op);
     return { session, panes, pane };
 }
-/** Shared MCP/CLI dispatch for zswarm ops. */
-export async function dispatchZswarm(args, injected, deps = {}) {
+async function dispatchOperation(args, injected, deps, context, env) {
     const op = String(args.op ?? "");
     const verbose = isVerbose(args);
     const signal = deps.signal;
-    throwIfAborted(signal);
     const clock = {
         now: deps.now ?? (() => Date.now()),
         sleep: deps.sleep ??
@@ -95,9 +148,13 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                     reject(new ZellijError("cancelled", "operation cancelled"));
                     return;
                 }
-                const timer = setTimeout(resolve, ms);
+                const timer = setTimeout(() => {
+                    signal?.removeEventListener("abort", onAbort);
+                    resolve();
+                }, ms);
                 const onAbort = () => {
                     clearTimeout(timer);
+                    signal?.removeEventListener("abort", onAbort);
                     reject(new ZellijError("cancelled", "operation cancelled"));
                 };
                 signal?.addEventListener("abort", onAbort, { once: true });
@@ -107,10 +164,10 @@ export async function dispatchZswarm(args, injected, deps = {}) {
     let gitClient = deps.git ?? null;
     const git = () => (gitClient ??= createGitClient());
     let stateStore = deps.state ?? null;
-    const state = () => (stateStore ??= createStateStore());
-    const policy = deps.policy ?? loadPolicy(deps.env);
-    const env = deps.env ?? process.env;
+    const state = () => (stateStore ??= createStateStore({ env }));
     try {
+        throwIfAborted(signal);
+        const policy = deps.policy ?? loadPolicy(env);
         // Policy gates the op before anything touches the session.
         assertOpAllowed(policy, op);
         assertSshGitAllowed(env, op, args);
@@ -132,21 +189,55 @@ export async function dispatchZswarm(args, injected, deps = {}) {
         // An injected client is a unit-test (or in-process) Zellij; do not skip it
         // just because the host env has ZSWARM_SERVE set.
         if (!injected && env.ZSWARM_SERVE?.trim()) {
-            return await callServe(env.ZSWARM_SERVE.trim(), attachKnownSender(args, env), serveCallTimeout(args), env.ZSWARM_SERVE_TOKEN);
+            const request = { ...attachKnownSender(args, env) };
+            delete request.serveAddress; // Routing is consumed here, never forwarded back into a tunnel.
+            return await callServe(env.ZSWARM_SERVE.trim(), request, serveCallTimeout(args), env.ZSWARM_SERVE_TOKEN);
         }
-        const client = injected ?? createZellijClient({ env: deps.env, signal });
+        const baseClient = injected ?? createZellijClient({ env, signal, cache: isTrue(args.fresh) ? false : undefined });
+        const client = {
+            ...baseClient,
+            get transport() { return baseClient.transport; },
+            async resolveSession(...input) {
+                const resolved = await baseClient.resolveSession(...input);
+                context.session = resolved.session;
+                context.origin.session = resolved.source;
+                return resolved;
+            },
+        };
         switch (op) {
             case "sessions": {
-                const sessions = await client.listSessions();
-                return { ok: true, data: { sessions, zellij: client.zellijPath } };
+                // Resolve SSH/IPC first so a Windows interactive crew is reachable
+                // before --live filters EXITED rows.
+                const listed = await client.listSessions();
+                const transport = client.transport;
+                const ipc = transport.ipc;
+                if (ipc &&
+                    ipc.requested?.toLowerCase() === "auto" &&
+                    (ipc.status === "failed" ||
+                        ipc.status === "expired" ||
+                        ipc.status === "cancelled")) {
+                    throw new ZellijError("ipc_unreachable", `ZSWARM_TMP=auto could not discover the remote Zellij IPC directory (status=${ipc.status}). Set ZSWARM_TMP to the desktop TEMP, confirm ZSWARM_SSH_MODE=interactive with a logged-on user, or use zswarm serve. Refusing to treat EXITED rows as "no live crew".`);
+                }
+                const includeExited = isTrue(args.all);
+                const sessions = includeExited
+                    ? listed
+                    : listed.filter((s) => !s.exited);
+                const data = {
+                    sessions,
+                    zellij: client.zellijPath,
+                    transport,
+                    filter: includeExited ? "all" : "live",
+                };
+                return { ok: true, data };
             }
             case "list": {
                 const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
                 // The plugin's manifest carries no cwd or floating flag, so anything
                 // verbose has to go the polling route.
-                const bus = verbose
+                const observedBus = verbose
                     ? null
-                    : await busSnapshot(client, state(), session, clock, deps.env);
+                    : await busSnapshot(client, state(), session, clock, env);
+                const bus = observedBus?.snapshot.ready ? observedBus : null;
                 const view = bus ? paneViewBus : verbose ? paneViewFull : paneViewSlim;
                 const panes = (bus ? busToPanes(bus.snapshot) : await client.listPanes(session))
                     .filter((p) => !p.isPlugin)
@@ -165,16 +256,9 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                 const body = String(args.body ?? args.text ?? "");
                 if (!body.trim())
                     throw new ZellijError("missing_body", "body required");
-                const { session, pane, panes } = await resolveTarget(client, args, state(), clock, deps.env, policy, op);
+                const { session, pane, panes } = await resolveTarget(client, args, state(), clock, env, policy, op, signal);
                 assertWritable(client, pane, args, "send");
-                // A pane that dropped back to a shell will *run* the message. There is
-                // no reliable way to tell an agent from a prompt, so the caller names
-                // something the screen must show first.
-                const expect = typeof args.expect === "string" ? args.expect.trim() : "";
-                if (expect) {
-                    const screen = await client.dumpPane({ session, paneId: pane.id });
-                    assertPaneExpects(screen.text, expect, pane.id);
-                }
+                await assertExpectedScreen(client, session, pane.id, args, signal);
                 const labeled = withSenderLabel(args, {
                     env,
                     selfTitle: selfPaneTitle(client, panes),
@@ -205,8 +289,9 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                 return await broadcast(client, state(), args, clock, policy, env);
             case "keys":
             case "interrupt": {
-                const { session, pane } = await resolveTarget(client, args, state(), clock, deps.env, policy, op);
+                const { session, pane } = await resolveTarget(client, args, state(), clock, env, policy, op, signal);
                 assertWritable(client, pane, args, op);
+                await assertExpectedScreen(client, session, pane.id, args, signal);
                 const chars = typeof args.chars === "string" ? args.chars : "";
                 if (op === "keys" && chars) {
                     await client.writeChars({ session, paneId: pane.id, chars });
@@ -259,7 +344,7 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                 };
             }
             case "dump": {
-                const { session, pane } = await resolveTarget(client, args, state(), clock, deps.env);
+                const { session, pane } = await resolveTarget(client, args, state(), clock, env, undefined, undefined, signal);
                 const dumped = await client.dumpPane({
                     session,
                     paneId: pane.id,
@@ -281,11 +366,11 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                 };
             }
             case "tail": {
-                const target = await resolveTarget(client, args, state(), clock, deps.env);
+                const target = await resolveTarget(client, args, state(), clock, env, undefined, undefined, signal);
                 return await tailPane(client, state(), args, target);
             }
             case "wait": {
-                const target = await resolveTarget(client, args, state(), clock, deps.env);
+                const target = await resolveTarget(client, args, state(), clock, env, undefined, undefined, signal);
                 // The plugin holds one pipe for the whole wait and polls far tighter
                 // than spawning a process allows. It declines a regex needle — it has
                 // no engine — and then this is the loop that runs.
@@ -297,24 +382,66 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                         match: typeof args.match === "string" ? args.match : null,
                         ignoreCase: isTrue(args.ignoreCase),
                         ...timing,
-                    }, deps.env);
+                    }, env);
                 return await waitForPane(client, target, args, clock, viaBus, deps.signal);
             }
             case "status": {
-                const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
-                // Verbose reports cwd and command, which the plugin manifest lacks.
-                const bus = verbose
-                    ? null
-                    : await busSnapshot(client, state(), session, clock, deps.env);
-                let supplied = bus
-                    ? {
-                        session,
-                        panes: busToPanes(bus.snapshot),
-                        source: "plugin",
-                        // Sampling is 2N dumps; the plugin reads them all in one pipe.
-                        readScreens: (paneIds) => busScreens(client, state(), session, paneIds, clock, deps.env),
-                        readChanged: async (paneIds) => {
-                            const reply = await busChanged(client, state(), session, paneIds, deps.env);
+                // One overall deadline covering session resolve, bus snapshot, IPC,
+                // and screen samples — not just the dump loop inside peerStatus.
+                const statusBudget = numberArg(args, "timeoutMs", DEFAULT_STATUS_TIMEOUT_MS, { min: 1_000, max: 900_000 });
+                const deadlineAt = clock.now() + statusBudget;
+                const remaining = () => Math.max(0, deadlineAt - clock.now());
+                const setupBudget = () => {
+                    throwIfAborted(signal);
+                    const left = remaining();
+                    if (left <= 0) {
+                        throw new ZellijError("zellij_failed", "status timed out during setup");
+                    }
+                    return left;
+                };
+                throwIfAborted(signal);
+                const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined, setupBudget());
+                throwIfAborted(signal);
+                // Once the session is known, verbose metadata and the bus manifest
+                // are independent reads. Both consume this operation's remaining time.
+                const readBus = () => remaining() <= 0 ? Promise.resolve(null)
+                    : busSnapshot(client, state(), session, clock, env, "status", { deadlineAt, signal });
+                let observedBus;
+                let detailedPanes;
+                if (verbose) {
+                    const reads = await Promise.allSettled([
+                        readBus(), client.listPanes(session, setupBudget(), { fresh: true }),
+                    ]);
+                    throwIfAborted(signal);
+                    if (reads[1].status === "rejected")
+                        throw reads[1].reason;
+                    if (reads[0].status === "rejected")
+                        throw reads[0].reason;
+                    observedBus = reads[0].value;
+                    detailedPanes = reads[1].value;
+                }
+                else {
+                    observedBus = await readBus();
+                }
+                const bus = observedBus?.snapshot.ready ? observedBus : null;
+                throwIfAborted(signal);
+                // Always hand peerStatus the resolved session (and panes) so it does
+                // not spend the overall budget resolving again.
+                const panes = detailedPanes ?? (bus
+                    ? busToPanes(bus.snapshot)
+                    : await client.listPanes(session, setupBudget()));
+                throwIfAborted(signal);
+                let supplied = {
+                    session,
+                    panes,
+                    source: bus && !verbose ? "plugin" : "zellij",
+                };
+                if (bus) {
+                    supplied = {
+                        ...supplied,
+                        readScreens: (paneIds, timeoutMs) => busScreens(client, state(), session, paneIds, clock, env, timeoutMs),
+                        readChanged: async (paneIds, timeoutMs) => {
+                            const reply = await busChanged(client, state(), session, paneIds, env, timeoutMs);
                             if (!reply)
                                 return null;
                             return new Map(reply.panes.map((p) => [
@@ -322,23 +449,37 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                                 { changed: p.changed, first: p.first, screen: p.screen },
                             ]));
                         },
-                    }
-                    : null;
+                    };
+                }
                 const only = typeof args.to === "string" ? args.to.trim() : "";
-                if (supplied && only) {
+                if (bus && only) {
                     try {
                         client.resolvePane(supplied.panes, only);
                     }
                     catch {
-                        // The manifest has no commands, so a command-shaped `to` only
-                        // resolves against the polled list.
-                        supplied = null;
+                        // Command-shaped `to` needs the polled list; re-fetch without bus.
+                        const polled = await client.listPanes(session, setupBudget());
+                        supplied = { ...supplied, session, panes: polled, source: "zellij" };
                     }
                 }
-                return await peerStatus(client, args, clock, supplied);
+                const result = await peerStatus(client, args, clock, supplied, {
+                    deadlineAt,
+                    signal,
+                });
+                if (result.ok && result.data && typeof result.data === "object") {
+                    const data = result.data;
+                    data.polling = {
+                        busAvailable: Boolean(bus),
+                        ...(bus ? {} : { reason: planBus(client, state(), env, session).reason }),
+                        ...(client.remote ? {
+                            recommendation: "For frequent status calls, run zswarm serve beside Zellij and use --serve 127.0.0.1:9419 through an SSH tunnel; direct SSH cannot use the local event bus.",
+                        } : {}),
+                    };
+                }
+                return result;
             }
             case "bus":
-                return await busOp(client, state(), args, clock, deps.env, policy);
+                return await busOp(client, state(), args, clock, env, policy);
             case "signal":
                 return postSignal(state(), args, clock);
             case "signals":
@@ -362,13 +503,13 @@ export async function dispatchZswarm(args, injected, deps = {}) {
             case "checkpoint":
                 return await peerCheckpoint(git(), args, clock);
             case "spawn":
-                return await spawnPane(client, args, deps.git);
+                return await spawnPane(client, args, deps.git, clock, signal);
             case "worktrees":
                 return await listPeerWorktrees(git(), client, args);
             case "unworktree":
                 return await removePeerWorktree(git(), client, args);
             case "close": {
-                const { session, pane } = await resolveTarget(client, args, state(), clock, deps.env, policy, op);
+                const { session, pane } = await resolveTarget(client, args, state(), clock, env, policy, op, signal);
                 // Not assertWritable: closing an exited pane is the point of close.
                 assertNotPlugin(pane, "close");
                 assertNotSelf(client, pane, args, "close");
@@ -393,3 +534,27 @@ export async function dispatchZswarm(args, injected, deps = {}) {
         return fail(err);
     }
 }
+/** Shared MCP/CLI dispatch, with invocation routing on successes and failures. */
+export async function dispatchZswarm(args, injected, deps = {}) {
+    try {
+        const env = resolveInvocationEnv(args, deps.env ?? process.env);
+        const context = invocationContext(args, env, injected?.transport);
+        const result = await dispatchOperation(args, injected, deps, context, env);
+        if (context.transport === "serve" && result.context) {
+            context.server = result.context;
+            context.session = result.context.session;
+            context.origin.session = result.context.origin.session;
+        }
+        else if (context.transport === "serve" && result.ok && result.data && typeof result.data === "object") {
+            const session = result.data.session;
+            if (typeof session === "string") {
+                context.session = session;
+                context.origin.session = "server";
+            }
+        }
+        return { ...result, context };
+    }
+    catch (err) {
+        return fail(err);
+    }
+}

package/dist/ops/guards.d.ts

@@ -13,3 +13,5 @@ export declare function assertWritable(client: ZellijClient, pane: ZellijPane, a
  * in a safety check is a foot-gun.
  */
 export declare function assertPaneExpects(screen: string, expect: string, paneId: string): void;
+/** Check immediately before input. A failed read or mismatch must not write. */
+export declare function assertExpectedScreen(client: ZellijClient, session: string, paneId: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<void>;

package/dist/ops/guards.js

@@ -1,5 +1,5 @@
 import { ZellijError } from "../errors.js";
-import { isTrue } from "./util.js";
+import { isTrue, optionalString, throwIfAborted } from "./util.js";
 export function assertNotPlugin(pane, action) {
     if (pane.isPlugin) {
         throw new ZellijError("pane_is_plugin", `${pane.id} is a plugin pane; ${action} targets terminal panes`);
@@ -34,3 +34,13 @@ export function assertPaneExpects(screen, expect, paneId) {
         return;
     throw new ZellijError("expect_missing", `${paneId} screen does not contain ${JSON.stringify(expect)}`);
 }
+/** Check immediately before input. A failed read or mismatch must not write. */
+export async function assertExpectedScreen(client, session, paneId, args, signal) {
+    throwIfAborted(signal);
+    const expect = optionalString(args.expect);
+    if (!expect)
+        return;
+    const screen = await client.dumpPane({ session, paneId });
+    throwIfAborted(signal);
+    assertPaneExpects(screen.text, expect, paneId);
+}

package/dist/ops/observation.d.ts

@@ -0,0 +1,8 @@
+import type { Clock } from "./types.js";
+/** One deadline shared by setup, child processes, retries, and sleeps. */
+export declare function observationBudget(clock: Clock, timeoutMs: number, signal?: AbortSignal): {
+    deadline: number;
+    remaining: () => number;
+    require(): number;
+    pause(until?: number): Promise<void>;
+};

package/dist/ops/observation.js

@@ -0,0 +1,26 @@
+import { ZellijError } from "../errors.js";
+import { throwIfAborted } from "./util.js";
+/** One deadline shared by setup, child processes, retries, and sleeps. */
+export function observationBudget(clock, timeoutMs, signal) {
+    const deadline = clock.now() + timeoutMs;
+    const remaining = () => {
+        throwIfAborted(signal);
+        return Math.max(0, deadline - clock.now());
+    };
+    return {
+        deadline,
+        remaining,
+        require() {
+            const left = remaining();
+            if (left <= 0)
+                throw new ZellijError("observation_timeout", "observation deadline expired");
+            return left;
+        },
+        async pause(until = deadline) {
+            const ms = Math.min(100, remaining(), Math.max(0, until - clock.now()));
+            if (ms > 0)
+                await clock.sleep(ms);
+            throwIfAborted(signal);
+        },
+    };
+}

package/dist/ops/panes.js

@@ -16,7 +16,7 @@ export async function renameTarget(client, args, policy) {
     const sess = await session(client, args);
     const tabKey = optionalString(args.tab);
     if (tabKey) {
-        const tab = client.resolveTab(await client.listTabs(sess), tabKey);
+        const tab = client.resolveTab(await client.listTabs(sess, undefined, { fresh: true }), tabKey);
         const renamed = await client.renameTab({
             session: sess,
             tabId: tab.id,
@@ -30,7 +30,7 @@ export async function renameTarget(client, args, policy) {
     const to = optionalString(args.to);
     if (!to)
         throw new ZellijError("missing_peer", "to (or tab) required");
-    const pane = client.resolvePane(await client.listPanes(sess), to);
+    const pane = client.resolvePane(await client.listPanes(sess, undefined, { fresh: true }), to);
     if (policy)
         assertPaneAllowed(policy, pane, "rename");
     await client.renamePane({ session: sess, paneId: pane.id, name });
@@ -44,7 +44,7 @@ export async function focusTarget(client, args, policy) {
     if (!to)
         throw new ZellijError("missing_peer", "to required");
     const sess = await session(client, args);
-    const pane = client.resolvePane(await client.listPanes(sess), to);
+    const pane = client.resolvePane(await client.listPanes(sess, undefined, { fresh: true }), to);
     if (policy)
         assertPaneAllowed(policy, pane, "focus");
     // Zellij exits non-zero when asked to focus the already-focused pane.
@@ -104,7 +104,7 @@ export async function stackTargets(client, args, policy) {
     if (!list)
         throw new ZellijError("missing_peer", "to (comma list) required");
     const sess = await session(client, args);
-    const panes = await client.listPanes(sess);
+    const panes = await client.listPanes(sess, undefined, { fresh: true });
     const ids = list
         .split(",")
         .map((k) => k.trim())

package/dist/ops/routing.d.ts

@@ -0,0 +1,13 @@
+import type { ZellijTransport } from "../zellij/client.js";
+export type RoutingContext = {
+    transport: "local" | "ssh" | "serve";
+    host: string;
+    session: string | null;
+    origin: {
+        transport: string;
+        session: string;
+    };
+    /** The serve endpoint can be a local tunnel; this identifies its server. */
+    server?: RoutingContext;
+};
+export declare function invocationContext(args: Record<string, unknown>, env: NodeJS.ProcessEnv, injected?: ZellijTransport): RoutingContext;

package/dist/ops/routing.js

@@ -0,0 +1,21 @@
+import { hostname } from "node:os";
+import { sessionFromEnv } from "../zellij/session.js";
+import { isTrue, optionalString } from "./util.js";
+export function invocationContext(args, env, injected) {
+    const serve = optionalString(env.ZSWARM_SERVE);
+    const ssh = optionalString(env.ZSWARM_SSH);
+    // Serve forwards explicit arguments; inherited session defaults belong to
+    // the server, not the caller (which might only be a local tunnel).
+    const selected = sessionFromEnv(serve && !injected ? {} : env, optionalString(args.session));
+    return {
+        transport: injected?.kind ?? (serve ? "serve" : ssh ? "ssh" : "local"),
+        host: injected ? injected.host ?? hostname() : serve ?? ssh ?? hostname(),
+        session: selected?.session ?? null,
+        origin: {
+            transport: injected ? "injected" : isTrue(args.local) ? "--local"
+                : optionalString(args.ssh) ? "--ssh" : optionalString(args.serveAddress) ? "--serve" : serve ? "ZSWARM_SERVE"
+                    : ssh ? "ZSWARM_SSH" : "default",
+            session: selected?.source ?? "unresolved",
+        },
+    };
+}

package/dist/ops/spawn.d.ts

@@ -1,5 +1,5 @@
 import { type GitClient } from "../git.js";
 import type { ZellijClient } from "../zellij/client.js";
-import type { OpsResult } from "./types.js";
-/** Open a new pane (or tab) and report which pane it became. */
-export declare function spawnPane(client: ZellijClient, args: Record<string, unknown>, git?: GitClient): Promise<OpsResult>;
+import type { Clock, OpsResult } from "./types.js";
+/** Create exactly once. Only observations are retried, never the create action. */
+export declare function spawnPane(client: ZellijClient, args: Record<string, unknown>, git?: GitClient, clock?: Clock, signal?: AbortSignal): Promise<OpsResult>;