@zswarm/core 0.1.3 → 0.1.5

package/dist/ops/dispatch.js

@@ -9,7 +9,7 @@ import { broadcast } from "./broadcast.js";
 import { busChanged, busOp, busScreens, busSnapshot, busWait } from "./bus.js";
 import { dumpLayoutOp, focusTarget, listTabsOp, renameTarget, stackTargets, } from "./panes.js";
 import { peerCheckpoint, peerDiff } from "./review.js";
-import { deliverTo } from "./delivery.js";
+import { attachKnownSender, deliverTo, withSenderLabel, selfPaneTitle } from "./delivery.js";
 import { assertNotPlugin, assertNotSelf, assertPaneExpects, assertWritable, } from "./guards.js";
 import { readDeliveryLog } from "./log.js";
 import { awaitSignal, listSignals, postSignal } from "./signals.js";
@@ -17,7 +17,7 @@ import { spawnPane } from "./spawn.js";
 import { peerStatus } from "./status.js";
 import { tailPane } from "./tail.js";
 import { OP_NAMES } from "../schema.js";
-import { dumpMaxChars, fail, isTrue, isVerbose, optionalString, paneViewBus, paneViewFull, paneViewSlim, truncateDumpText, } from "./util.js";
+import { dumpMaxChars, fail, isTrue, isVerbose, 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";
@@ -35,17 +35,23 @@ const SSH_GIT_OPS = new Set([
     "diff",
     "checkpoint",
 ]);
+const SSH_LOCAL_BARRIER_OPS = new Set(["signal", "signals", "await"]);
 /**
  * SSH only forwards Zellij. Git worktrees, diffs, and checkpoints stay on this
  * machine, so mixing them with a remote pane cwd is how you delete the wrong tree.
+ * Client-local signal barriers cannot rendezvous with a remote crew either.
  */
 function assertSshGitAllowed(env, op, args) {
     if (!env.ZSWARM_SSH?.trim() || env.ZSWARM_SERVE?.trim())
         return;
     const worktreeSpawn = op === "spawn" && optionalString(args.worktree);
-    if (!worktreeSpawn && !SSH_GIT_OPS.has(op))
+    if (!worktreeSpawn && !SSH_GIT_OPS.has(op) && !SSH_LOCAL_BARRIER_OPS.has(op)) {
         return;
-    throw new ZellijError("ssh_git_unsupported", `${op} uses local git; ZSWARM_SSH only forwards Zellij. Run zswarm serve on the host that owns the session`);
+    }
+    const why = SSH_LOCAL_BARRIER_OPS.has(op)
+        ? "is a client-local barrier"
+        : "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) {
     const to = String(args.to ?? "").trim();
@@ -79,10 +85,23 @@ async function resolveTarget(client, args, state, clock, env, policy, op) {
 export async function dispatchZswarm(args, injected, deps = {}) {
     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 ??
-            ((ms) => new Promise((r) => setTimeout(r, ms))),
+            ((ms) => new Promise((resolve, reject) => {
+                if (signal?.aborted) {
+                    reject(new ZellijError("cancelled", "operation cancelled"));
+                    return;
+                }
+                const timer = setTimeout(resolve, ms);
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    reject(new ZellijError("cancelled", "operation cancelled"));
+                };
+                signal?.addEventListener("abort", onAbort, { once: true });
+            })),
     };
     // Only the worktree ops need git, so the client is built on demand.
     let gitClient = deps.git ?? null;
@@ -113,9 +132,9 @@ 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(), args, serveCallTimeout(args), env.ZSWARM_SERVE_TOKEN);
+            return await callServe(env.ZSWARM_SERVE.trim(), attachKnownSender(args, env), serveCallTimeout(args), env.ZSWARM_SERVE_TOKEN);
         }
-        const client = injected ?? createZellijClient({ env: deps.env });
+        const client = injected ?? createZellijClient({ env: deps.env, signal });
         switch (op) {
             case "sessions": {
                 const sessions = await client.listSessions();
@@ -146,7 +165,7 @@ 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 } = await resolveTarget(client, args, state(), clock, deps.env, policy, op);
+                const { session, pane, panes } = await resolveTarget(client, args, state(), clock, deps.env, policy, op);
                 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
@@ -156,7 +175,11 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                     const screen = await client.dumpPane({ session, paneId: pane.id });
                     assertPaneExpects(screen.text, expect, pane.id);
                 }
-                const result = await deliverTo(client, state(), args, {
+                const labeled = withSenderLabel(args, {
+                    env,
+                    selfTitle: selfPaneTitle(client, panes),
+                });
+                const result = await deliverTo(client, state(), labeled, {
                     session,
                     pane,
                     body,
@@ -171,7 +194,7 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                     delivery: result.delivery,
                     session,
                     to: result.to,
-                    from: (typeof args.from === "string" && args.from.trim()) || "swarm",
+                    from: labeled.from,
                     submitted: result.submitted,
                 };
                 if (verbose)
@@ -179,7 +202,7 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                 return { ok: true, data };
             }
             case "broadcast":
-                return await broadcast(client, state(), args, clock, policy);
+                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);
@@ -268,15 +291,14 @@ export async function dispatchZswarm(args, injected, deps = {}) {
                 // no engine — and then this is the loop that runs.
                 const viaBus = isTrue(args.regex)
                     ? undefined
-                    : () => busWait(client, state(), target.session, {
+                    : (timing) => busWait(client, state(), target.session, {
                         pane: target.pane.id,
                         for: waitMode(args),
                         match: typeof args.match === "string" ? args.match : null,
                         ignoreCase: isTrue(args.ignoreCase),
-                        idleMs: Number(args.idleMs ?? 2000),
-                        timeoutMs: Number(args.timeoutMs ?? 60_000),
+                        ...timing,
                     }, deps.env);
-                return await waitForPane(client, target, args, clock, viaBus);
+                return await waitForPane(client, target, args, clock, viaBus, deps.signal);
             }
             case "status": {
                 const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
@@ -326,15 +348,15 @@ export async function dispatchZswarm(args, injected, deps = {}) {
             case "log":
                 return readDeliveryLog(state(), args);
             case "rename":
-                return await renameTarget(client, args);
+                return await renameTarget(client, args, policy);
             case "focus":
-                return await focusTarget(client, args);
+                return await focusTarget(client, args, policy);
             case "tabs":
                 return await listTabsOp(client, args);
             case "layout":
                 return await dumpLayoutOp(client, args);
             case "stack":
-                return await stackTargets(client, args);
+                return await stackTargets(client, args, policy);
             case "diff":
                 return await peerDiff(git(), args);
             case "checkpoint":

package/dist/ops/panes.d.ts

@@ -1,13 +1,14 @@
+import { type Policy } from "../policy.js";
 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.
  */
-export declare function renameTarget(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
-export declare function focusTarget(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
+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>;
 export declare function listTabsOp(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
 /** The session's current layout as KDL — a spawnable description of the crew. */
 export declare function dumpLayoutOp(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
 /** Collapse several peers into one stack so a big crew stays readable. */
-export declare function stackTargets(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
+export declare function stackTargets(client: ZellijClient, args: Record<string, unknown>, policy?: Policy): Promise<OpsResult>;

package/dist/ops/panes.js

@@ -1,4 +1,5 @@
 import { ZellijError } from "../errors.js";
+import { assertPaneAllowed } from "../policy.js";
 import { dumpMaxChars, optionalString, truncateDumpText } from "./util.js";
 async function session(client, args) {
     const resolved = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
@@ -8,7 +9,7 @@ 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.
  */
-export async function renameTarget(client, args) {
+export async function renameTarget(client, args, policy) {
     const name = optionalString(args.name);
     if (!name)
         throw new ZellijError("missing_name", "name required");
@@ -30,18 +31,22 @@ export async function renameTarget(client, args) {
     if (!to)
         throw new ZellijError("missing_peer", "to (or tab) required");
     const pane = client.resolvePane(await client.listPanes(sess), to);
+    if (policy)
+        assertPaneAllowed(policy, pane, "rename");
     await client.renamePane({ session: sess, paneId: pane.id, name });
     return {
         ok: true,
         data: { session: sess, to: pane.id, was: pane.title, name },
     };
 }
-export async function focusTarget(client, args) {
+export async function focusTarget(client, args, policy) {
     const to = optionalString(args.to);
     if (!to)
         throw new ZellijError("missing_peer", "to required");
     const sess = await session(client, args);
     const pane = client.resolvePane(await client.listPanes(sess), to);
+    if (policy)
+        assertPaneAllowed(policy, pane, "focus");
     // Zellij exits non-zero when asked to focus the already-focused pane.
     if (pane.focused) {
         return {
@@ -94,7 +99,7 @@ export async function dumpLayoutOp(client, args) {
     };
 }
 /** Collapse several peers into one stack so a big crew stays readable. */
-export async function stackTargets(client, args) {
+export async function stackTargets(client, args, policy) {
     const list = optionalString(args.to);
     if (!list)
         throw new ZellijError("missing_peer", "to (comma list) required");
@@ -104,7 +109,12 @@ export async function stackTargets(client, args) {
         .split(",")
         .map((k) => k.trim())
         .filter(Boolean)
-        .map((key) => client.resolvePane(panes, key).id);
+        .map((key) => {
+        const pane = client.resolvePane(panes, key);
+        if (policy)
+            assertPaneAllowed(policy, pane, "stack");
+        return pane.id;
+    });
     const unique = [...new Set(ids)];
     const stacked = await client.stackPanes({ session: sess, paneIds: unique });
     return { ok: true, data: { session: sess, stacked: stacked.paneIds } };

package/dist/ops/serve.d.ts

@@ -3,6 +3,10 @@ export declare const DEFAULT_SERVE_LISTEN = "127.0.0.1:9419";
 export declare const SERVE_TASK_NAME = "zswarm-serve";
 /** One JSONL request; a client that never sends newline cannot grow forever. */
 export declare const SERVE_MAX_REQUEST_BYTES: number;
+/** Drop a socket that never finishes a JSONL line. */
+export declare const SERVE_IDLE_TIMEOUT_MS = 30000;
+/** Concurrent TCP clients, including in-flight wait ops. */
+export declare const SERVE_MAX_CONNECTIONS = 32;
 /** Wait/await allow 15 minutes; this is that plus slack. */
 export declare const SERVE_CALL_TIMEOUT_CAP_MS: number;
 export declare function isLoopbackHost(host: string): boolean;
@@ -20,6 +24,8 @@ export type ServeDispatch = (args: Record<string, unknown>) => Promise<OpsResult
 export type StartServeOptions = {
     token?: string;
     maxRequestBytes?: number;
+    idleTimeoutMs?: number;
+    maxConnections?: number;
 };
 export declare function startServe(listen: string | undefined, dispatch: ServeDispatch, options?: StartServeOptions): Promise<{
     label: string;
@@ -30,12 +36,15 @@ export declare function parseServeTarget(raw: string): {
     port: number;
 };
 export declare function callServe(target: string, args: Record<string, unknown>, timeoutMs?: number, token?: string): Promise<OpsResult>;
-export declare function serveLogonCommand(execPath: string, scriptPath: string, listen: string): string;
+export declare function redactServeSecret(command: string, token: string): string;
+export declare function serveLogonCommand(execPath: string, scriptPath: string, listen: string, token?: string): string;
 export declare function installServeLogon(input: {
     listen?: string;
     execPath?: string;
     scriptPath?: string;
     platform?: NodeJS.Platform;
+    token?: string;
+    env?: NodeJS.ProcessEnv;
 }): Promise<{
     task: string;
     listen: string;

package/dist/ops/serve.js

@@ -6,6 +6,10 @@ export const DEFAULT_SERVE_LISTEN = "127.0.0.1:9419";
 export const SERVE_TASK_NAME = "zswarm-serve";
 /** One JSONL request; a client that never sends newline cannot grow forever. */
 export const SERVE_MAX_REQUEST_BYTES = 1024 * 1024;
+/** Drop a socket that never finishes a JSONL line. */
+export const SERVE_IDLE_TIMEOUT_MS = 30_000;
+/** Concurrent TCP clients, including in-flight wait ops. */
+export const SERVE_MAX_CONNECTIONS = 32;
 /** Wait/await allow 15 minutes; this is that plus slack. */
 export const SERVE_CALL_TIMEOUT_CAP_MS = 16 * 60_000;
 const SERVE_TOKEN_FIELD = "serveToken";
@@ -81,15 +85,37 @@ function takeServeToken(args) {
 }
 export function startServe(listen, dispatch, options = {}) {
     const { host, port } = parseListenAddress(listen);
+    if (!isLoopbackHost(host)) {
+        return Promise.reject(new ZellijError("serve_auth", `zswarm serve only listens on loopback (127.0.0.1 / ::1); off-machine access is an SSH tunnel to 127.0.0.1 (${host} refused)`));
+    }
     const token = options.token?.trim() || undefined;
-    if (!token && !isLoopbackHost(host)) {
-        return Promise.reject(new ZellijError("serve_auth", `listening on ${host} requires ZSWARM_SERVE_TOKEN; loopback can run without one`));
+    if (!token) {
+        return Promise.reject(new ZellijError("serve_auth", "zswarm serve requires ZSWARM_SERVE_TOKEN; another local OS user can connect to 127.0.0.1"));
     }
     const maxRequestBytes = options.maxRequestBytes ?? SERVE_MAX_REQUEST_BYTES;
+    const idleTimeoutMs = options.idleTimeoutMs ?? SERVE_IDLE_TIMEOUT_MS;
+    const maxConnections = options.maxConnections ?? SERVE_MAX_CONNECTIONS;
     return new Promise((resolve, reject) => {
+        const sockets = new Set();
         const server = createServer((socket) => {
+            socket.on("error", () => {
+                socket.destroy();
+            });
+            if (sockets.size >= maxConnections) {
+                socket.destroy();
+                return;
+            }
+            sockets.add(socket);
+            socket.on("close", () => {
+                sockets.delete(socket);
+            });
             let buf = "";
+            let draining = false;
             socket.setEncoding("utf8");
+            socket.setTimeout(idleTimeoutMs);
+            socket.on("timeout", () => {
+                socket.destroy();
+            });
             socket.on("data", (chunk) => {
                 buf += chunk;
                 if (buf.length > maxRequestBytes) {
@@ -106,29 +132,48 @@ export function startServe(listen, dispatch, options = {}) {
                 void drain();
             });
             async function drain() {
-                let nl = buf.indexOf("\n");
-                while (nl !== -1) {
-                    const line = buf.slice(0, nl).trim();
-                    buf = buf.slice(nl + 1);
-                    if (line) {
-                        let result;
-                        try {
-                            const parsed = JSON.parse(line);
-                            const taken = takeServeToken(parsed);
-                            if (token && taken.token !== token) {
-                                result = unauthorized();
+                if (draining)
+                    return;
+                draining = true;
+                socket.setTimeout(0);
+                try {
+                    let nl = buf.indexOf("\n");
+                    while (nl !== -1) {
+                        const line = buf.slice(0, nl).trim();
+                        buf = buf.slice(nl + 1);
+                        if (line) {
+                            let result;
+                            try {
+                                const parsed = JSON.parse(line);
+                                const taken = takeServeToken(parsed);
+                                if (taken.token !== token) {
+                                    result = unauthorized();
+                                }
+                                else {
+                                    result = await dispatch(taken.request);
+                                }
                             }
-                            else {
-                                result = await dispatch(taken.request);
+                            catch (err) {
+                                const message = err instanceof Error ? err.message : String(err);
+                                result = { ok: false, error: { code: "bad_arg", message } };
+                            }
+                            if (!socket.destroyed) {
+                                socket.write(`${JSON.stringify(result)}\n`);
                             }
                         }
-                        catch (err) {
-                            const message = err instanceof Error ? err.message : String(err);
-                            result = { ok: false, error: { code: "bad_arg", message } };
-                        }
-                        socket.write(`${JSON.stringify(result)}\n`);
+                        nl = buf.indexOf("\n");
+                    }
+                }
+                finally {
+                    draining = false;
+                    if (socket.destroyed)
+                        return;
+                    if (buf.includes("\n")) {
+                        void drain();
+                    }
+                    else {
+                        socket.setTimeout(idleTimeoutMs);
                     }
-                    nl = buf.indexOf("\n");
                 }
             }
         });
@@ -139,6 +184,8 @@ export function startServe(listen, dispatch, options = {}) {
             resolve({
                 label: formatListenLabel(host, actualPort),
                 close: () => new Promise((done, fail) => {
+                    for (const open of sockets)
+                        open.destroy();
                     server.close((err) => (err ? fail(err) : done()));
                 }),
             });
@@ -205,8 +252,30 @@ export function callServe(target, args, timeoutMs = 15_000, token) {
         });
     });
 }
-export function serveLogonCommand(execPath, scriptPath, listen) {
-    return `"${execPath}" "${scriptPath}" serve --listen ${listen}`;
+export function redactServeSecret(command, token) {
+    const secret = token.trim();
+    if (!secret)
+        return command;
+    return command.split(secret).join("***");
+}
+export function serveLogonCommand(execPath, scriptPath, listen, token) {
+    const launch = `"${execPath}" "${scriptPath}" serve --listen ${listen}`;
+    const secret = token?.trim();
+    if (!secret)
+        return launch;
+    if (/[\0\r\n"%]/.test(secret)) {
+        throw new ZellijError("bad_arg", "ZSWARM_SERVE_TOKEN must not contain quotes, newlines, or %");
+    }
+    return `set "ZSWARM_SERVE_TOKEN=${secret}"&& ${launch}`;
+}
+function serveInstallToken(input) {
+    const raw = input.token ??
+        (input.env ? input.env.ZSWARM_SERVE_TOKEN : process.env.ZSWARM_SERVE_TOKEN);
+    const secret = raw?.trim() ?? "";
+    if (!secret) {
+        throw new ZellijError("serve_auth", "zswarm serve requires ZSWARM_SERVE_TOKEN; another local OS user can connect to 127.0.0.1");
+    }
+    return secret;
 }
 function runPowerShell(script) {
     return new Promise((resolve) => {
@@ -234,13 +303,17 @@ export async function installServeLogon(input) {
     if ((input.platform ?? process.platform) !== "win32") {
         throw new ZellijError("usage", "serve --install registers a Windows logon task; on Unix start `zswarm serve --listen` in the session that owns Zellij");
     }
-    const { label } = parseListenAddress(input.listen);
+    const { host, label } = parseListenAddress(input.listen);
+    if (!isLoopbackHost(host)) {
+        throw new ZellijError("serve_auth", `zswarm serve only listens on loopback (127.0.0.1 / ::1); off-machine access is an SSH tunnel to 127.0.0.1 (${host} refused)`);
+    }
+    const token = serveInstallToken(input);
     const execPath = input.execPath ?? process.execPath;
     const scriptPath = input.scriptPath ?? process.argv[1];
     if (!scriptPath) {
         throw new ZellijError("usage", "cannot resolve the zswarm script path for the logon task");
     }
-    const command = serveLogonCommand(execPath, scriptPath, label);
+    const command = serveLogonCommand(execPath, scriptPath, label, token);
     const commandB64 = Buffer.from(command, "utf8").toString("base64");
     const script = [
         "$cmd = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('" +
@@ -256,7 +329,7 @@ export async function installServeLogon(input) {
     if (result.code !== 0) {
         throw new ZellijError("zellij_failed", `serve --install failed: ${(result.stderr || result.stdout).trim() || "no output"}`);
     }
-    return { task: SERVE_TASK_NAME, listen: label, command };
+    return { task: SERVE_TASK_NAME, listen: label, command: redactServeSecret(command, token) };
 }
 export async function uninstallServeLogon(input = {}) {
     if ((input.platform ?? process.platform) !== "win32") {

package/dist/ops/types.d.ts

@@ -19,6 +19,8 @@ export type DispatchDeps = {
     state?: StateStore;
     policy?: Policy;
     env?: NodeJS.ProcessEnv;
+    /** MCP cancellation; aborted waits stop instead of running to timeout. */
+    signal?: AbortSignal;
 };
 export type Clock = {
     now: () => number;

package/dist/ops/util.d.ts

@@ -45,4 +45,5 @@ export declare function numberArg(args: Record<string, unknown>, key: string, fa
     min: number;
     max: number;
 }): number;
+export declare function throwIfAborted(signal?: AbortSignal): void;
 export declare function dumpMaxChars(args: Record<string, unknown>, fallback?: number): number;

package/dist/ops/util.js

@@ -73,6 +73,11 @@ export function numberArg(args, key, fallback, limits) {
     }
     return Math.min(limits.max, Math.max(limits.min, Math.floor(n)));
 }
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new ZellijError("cancelled", "operation cancelled");
+    }
+}
 export function dumpMaxChars(args, fallback = DEFAULT_DUMP_MAX_CHARS) {
     if (args.max === undefined || args.max === null || args.max === "") {
         return fallback;

package/dist/ops/wait.d.ts

@@ -5,6 +5,13 @@ import type { Clock, OpsResult } from "./types.js";
 export declare function buildMatcher(args: Record<string, unknown>): ((text: string) => boolean) | null;
 /** Held-pipe wait answer, shaped by `parseWaitReply` in `zellij/bus.ts`. */
 export type { BusWait };
+/** Clamped timing the bus path must use — never the raw request numbers. */
+export type WaitBusTiming = {
+    idleMs: number;
+    timeoutMs: number;
+    pollMs: number;
+    full: boolean;
+};
 /**
  * Poll a pane's screen until it goes quiet, prints a match, or the deadline
  * passes — so callers stop re-dumping in a loop of their own.
@@ -16,4 +23,4 @@ export type { BusWait };
 export declare function waitForPane(client: ZellijClient, target: {
     session: string;
     pane: ZellijPane;
-}, args: Record<string, unknown>, clock: Clock, waitViaBus?: () => Promise<BusWait | null>): Promise<OpsResult>;
+}, args: Record<string, unknown>, clock: Clock, waitViaBus?: (timing: WaitBusTiming) => Promise<BusWait | null>, signal?: AbortSignal): Promise<OpsResult>;

package/dist/ops/wait.js

@@ -1,5 +1,5 @@
 import { ZellijError } from "../errors.js";
-import { DEFAULT_WAIT_MAX_CHARS, dumpMaxChars, isTrue, normalizeScreen, numberArg, optionalString, truncateDumpText, } from "./util.js";
+import { DEFAULT_WAIT_MAX_CHARS, dumpMaxChars, isTrue, normalizeScreen, numberArg, optionalString, throwIfAborted, truncateDumpText, } from "./util.js";
 const WAIT_DEFAULTS = {
     idleMs: 2_000,
     pollMs: 150,
@@ -56,7 +56,7 @@ function waitResult(reason, ctx) {
  * Null (plugin missing or silent) falls back to dump-screen polling. The
  * pipe's own timeout belongs to the transport; this op does not cap it.
  */
-export async function waitForPane(client, target, args, clock, waitViaBus) {
+export async function waitForPane(client, target, args, clock, waitViaBus, signal) {
     const { session, pane } = target;
     const matcher = buildMatcher(args);
     const requested = optionalString(args.for) ?? (matcher ? "match" : "idle");
@@ -72,8 +72,11 @@ export async function waitForPane(client, target, args, clock, waitViaBus) {
     const pollMs = numberArg(args, "pollMs", WAIT_DEFAULTS.pollMs, WAIT_LIMITS.pollMs);
     const timeoutMs = numberArg(args, "timeoutMs", WAIT_DEFAULTS.timeoutMs, WAIT_LIMITS.timeoutMs);
     const started = clock.now();
+    const full = isTrue(args.full);
     if (waitViaBus) {
-        const reply = await waitViaBus();
+        throwIfAborted(signal);
+        const reply = await waitViaBus({ idleMs, timeoutMs, pollMs, full });
+        throwIfAborted(signal);
         // `gone` is filtered upstream: a pane that vanished mid-wait is reported by
         // the polling path, which has the error message for it.
         if (reply && reply.reason !== "gone") {
@@ -96,6 +99,7 @@ export async function waitForPane(client, target, args, clock, waitViaBus) {
     let polls = 0;
     let changes = 0;
     for (;;) {
+        throwIfAborted(signal);
         const dumped = await client.dumpPane({
             session,
             paneId: pane.id,

package/dist/schema.js

@@ -42,6 +42,9 @@ export const TARGET_OPS = [
     "keys",
     "interrupt",
     "close",
+    "rename",
+    "focus",
+    "stack",
 ];
 export const PARAMS = [
     {
@@ -150,7 +153,7 @@ export const PARAMS = [
         name: "from",
         type: "string",
         flags: ["--from", "-f"],
-        description: "send: sender label in the [zswarm from=…] prefix",
+        description: "send: sender label in the [zswarm from=…] prefix (default: ZSWARM_FROM, else the sending pane's title, else swarm)",
     },
     {
         name: "raw",
@@ -382,7 +385,7 @@ export const PARAMS = [
         name: "force",
         type: "boolean",
         flags: ["--force"],
-        description: "send/keys: write to a pane whose command has exited; unworktree: remove a busy or dirty worktree; bus: reinstall under a fresh key",
+        description: "send/keys: write to a pane whose command has exited; unworktree: remove a busy or dirty worktree; bus: close orphan bus panes and reload this session's plugin",
     },
     {
         name: "listen",
@@ -447,7 +450,7 @@ export function cliUsage() {
         const value = param.type === "boolean" ? "" : param.type === "number" ? " N" : " VALUE";
         lines.push(`  ${param.flags.join(", ").padEnd(28)}${value.trim().padEnd(6)}${param.description}`);
     }
-    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once, then list and status use it now.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE (+ ZSWARM_SERVE_TOKEN off loopback).", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN", "");
+    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once per Zellij session. `--force` closes orphan bus panes and reloads; do not use it as a retry.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE (+ ZSWARM_SERVE_TOKEN). Serve binds loopback only and always requires a token.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN", "");
     return lines.join("\n");
 }
 /** Turn argv (without the op) into dispatch args, driven by PARAMS. */

package/dist/state.d.ts

@@ -19,9 +19,10 @@ export type SignalChannel = {
     last: string | null;
 };
 /**
- * Written once by `bus --install`, after the plugin's permission prompt has
- * been answered. Its presence is what lets later runs try the fast path without
- * every cold `zswarm status` paying for a pipe that was never going to answer.
+ * Written by `bus --install` per Zellij session, after the plugin's permission
+ * prompt has been answered. Its presence is what lets later runs try the fast
+ * path without every cold `zswarm status` paying for a pipe that was never
+ * going to answer.
  */
 export type BusMarkerRecord = {
     plugin: string;
@@ -44,9 +45,9 @@ export declare function createStateStore(options?: StateStoreOptions): {
     readCursor: (key: string) => string | null;
     writeCursor: (key: string, text: string) => void;
     clearCursor: (key: string) => void;
-    readBus: () => BusMarkerRecord | null;
-    writeBus: (marker: BusMarkerRecord) => void;
-    clearBus: () => void;
+    readBus: (session: string) => BusMarkerRecord | null;
+    writeBus: (session: string, marker: BusMarkerRecord) => void;
+    clearBus: (session?: string) => void;
     reset: () => void;
 };
 export type StateStore = ReturnType<typeof createStateStore>;