@zswarm/core 0.1.3 → 0.1.4

package/dist/ops/broadcast.d.ts

@@ -16,4 +16,4 @@ export declare function selectTargets(client: ZellijClient, panes: ZellijPane[],
     skipped: Skipped[];
 };
 /** Send one body to many panes, reporting per-pane outcomes. */
-export declare function broadcast(client: ZellijClient, state: StateStore, args: Record<string, unknown>, clock: Clock, policy?: Policy): Promise<OpsResult>;
+export declare function broadcast(client: ZellijClient, state: StateStore, args: Record<string, unknown>, clock: Clock, policy?: Policy, env?: NodeJS.ProcessEnv): Promise<OpsResult>;

package/dist/ops/broadcast.js

@@ -1,6 +1,6 @@
 import { ZellijError } from "../errors.js";
 import { assertPaneAllowed } from "../policy.js";
-import { deliverTo } from "./delivery.js";
+import { deliverTo, selfPaneTitle, withSenderLabel } from "./delivery.js";
 import { isTrue, optionalString } from "./util.js";
 /**
  * Pick the panes a broadcast should reach: an explicit comma list, a tab, or
@@ -65,13 +65,17 @@ export function selectTargets(client, panes, args) {
     return { targets, skipped };
 }
 /** Send one body to many panes, reporting per-pane outcomes. */
-export async function broadcast(client, state, args, clock, policy) {
+export async function broadcast(client, state, args, clock, policy, env = process.env) {
     const body = String(args.body ?? args.text ?? "");
     if (!body.trim())
         throw new ZellijError("missing_body", "body required");
     const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
     const panes = await client.listPanes(session);
-    const { targets: selected, skipped } = selectTargets(client, panes, args);
+    const labeled = withSenderLabel(args, {
+        env,
+        selfTitle: selfPaneTitle(client, panes),
+    });
+    const { targets: selected, skipped } = selectTargets(client, panes, labeled);
     // Policy narrows the selection rather than failing the whole broadcast.
     const targets = selected.filter((pane) => {
         if (!policy)
@@ -90,7 +94,7 @@ export async function broadcast(client, state, args, clock, policy) {
     }
     const results = [];
     for (const pane of targets) {
-        results.push(await deliverTo(client, state, args, {
+        results.push(await deliverTo(client, state, labeled, {
             session,
             pane,
             body,
@@ -104,7 +108,7 @@ export async function broadcast(client, state, args, clock, policy) {
         ok: true,
         data: {
             session,
-            from: (typeof args.from === "string" && args.from.trim()) || "swarm",
+            from: labeled.from,
             delivered: delivered.map((r) => r.to),
             failed: results.filter((r) => !r.ok),
             skipped,

package/dist/ops/delivery.d.ts

@@ -14,7 +14,37 @@ export type DeliveryResult = {
     };
 };
 export type SubmitMode = "auto" | "double-enter" | "none";
-export declare function senderLabel(args: Record<string, unknown>): string;
+export type SenderSource = "arg" | "env" | "title" | "default";
+export type SenderLabel = {
+    label: string;
+    source: SenderSource;
+};
+/** Drop characters that would break `[zswarm from=…]` or wrap the prefix. */
+export declare function sanitizeSenderLabel(raw: string): string;
+export declare function selfPaneTitle(client: Pick<ZellijClient, "selfPaneId">, panes: ZellijPane[]): string | null;
+/**
+ * Label for `[zswarm from=…]`. Explicit `from` wins, then `ZSWARM_FROM`,
+ * then the sending pane's title when we know that pane, else `swarm`.
+ */
+export declare function resolveSender(args: Record<string, unknown>, opts?: {
+    env?: NodeJS.ProcessEnv;
+    selfTitle?: string | null;
+}): SenderLabel;
+export declare function senderLabel(args: Record<string, unknown>, opts?: {
+    env?: NodeJS.ProcessEnv;
+    selfTitle?: string | null;
+}): string;
+/** Stamp `from` so deliverTo and the op result use the same resolved label. */
+export declare function withSenderLabel(args: Record<string, unknown>, opts?: {
+    env?: NodeJS.ProcessEnv;
+    selfTitle?: string | null;
+}): Record<string, unknown>;
+/**
+ * Before forwarding over `ZSWARM_SERVE`, keep a caller-chosen label and
+ * leave `from` unset when it would default, so the Zellij-side process can
+ * still fill in its own pane title.
+ */
+export declare function attachKnownSender(args: Record<string, unknown>, env: NodeJS.ProcessEnv): Record<string, unknown>;
 export declare function bodyText(client: ZellijClient, args: Record<string, unknown>, body: string): string;
 /**
  * Caller `submit=` always wins. With none given, the pane's harness picks

package/dist/ops/delivery.js

@@ -2,8 +2,62 @@ import { resolveHarness } from "../harness.js";
 import { isTrue, numberArg } from "./util.js";
 /** Cursor / Claude leave this in scrollback after a successful submit. */
 const PASTE_MARKER = "[Pasted text";
-export function senderLabel(args) {
-    return (typeof args.from === "string" && args.from.trim()) || "swarm";
+const SENDER_LABEL_MAX = 48;
+/** Drop characters that would break `[zswarm from=…]` or wrap the prefix. */
+export function sanitizeSenderLabel(raw) {
+    const cleaned = raw.replace(/[\r\n[\]]+/g, " ").replace(/\s+/g, " ").trim();
+    if (!cleaned)
+        return "";
+    return cleaned.length <= SENDER_LABEL_MAX
+        ? cleaned
+        : cleaned.slice(0, SENDER_LABEL_MAX).trimEnd();
+}
+export function selfPaneTitle(client, panes) {
+    const id = client.selfPaneId;
+    if (!id)
+        return null;
+    const title = panes.find((p) => p.id === id)?.title;
+    return title?.trim() ? title : null;
+}
+/**
+ * Label for `[zswarm from=…]`. Explicit `from` wins, then `ZSWARM_FROM`,
+ * then the sending pane's title when we know that pane, else `swarm`.
+ */
+export function resolveSender(args, opts = {}) {
+    if (typeof args.from === "string") {
+        const explicit = sanitizeSenderLabel(args.from);
+        if (explicit)
+            return { label: explicit, source: "arg" };
+    }
+    const envFrom = sanitizeSenderLabel(opts.env?.ZSWARM_FROM ?? "");
+    if (envFrom)
+        return { label: envFrom, source: "env" };
+    const title = sanitizeSenderLabel(opts.selfTitle ?? "");
+    if (title)
+        return { label: title, source: "title" };
+    return { label: "swarm", source: "default" };
+}
+export function senderLabel(args, opts = {}) {
+    return resolveSender(args, opts).label;
+}
+/** Stamp `from` so deliverTo and the op result use the same resolved label. */
+export function withSenderLabel(args, opts = {}) {
+    return { ...args, from: senderLabel(args, opts) };
+}
+/**
+ * Before forwarding over `ZSWARM_SERVE`, keep a caller-chosen label and
+ * leave `from` unset when it would default, so the Zellij-side process can
+ * still fill in its own pane title.
+ */
+export function attachKnownSender(args, env) {
+    const op = String(args.op ?? "");
+    if (op !== "send" && op !== "broadcast")
+        return args;
+    const sender = resolveSender(args, { env });
+    if (sender.source === "arg" || sender.source === "env") {
+        return { ...args, from: sender.label };
+    }
+    return args;
 }
 export function bodyText(client, args, body) {
     return isTrue(args.raw) ? body : client.formatPeerMessage(senderLabel(args), body);

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";
@@ -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();
@@ -113,7 +119,7 @@ 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 });
         switch (op) {
@@ -146,7 +152,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 +162,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 +181,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 +189,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);
@@ -326,15 +336,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,14 @@ 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 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,24 @@ export function callServe(target, args, timeoutMs = 15_000, token) {
         });
     });
 }
-export function serveLogonCommand(execPath, scriptPath, listen) {
-    return `"${execPath}" "${scriptPath}" serve --listen ${listen}`;
+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 +297,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('" +

package/dist/schema.js

@@ -150,7 +150,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",
@@ -447,7 +447,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, 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, 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.js

@@ -1,10 +1,11 @@
-import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const LOG_FILE = "log.jsonl";
 const SIGNALS_FILE = "signals.json";
 const SIGNALS_LOCK = "signals.lock";
 const CURSORS_FILE = "cursors.json";
+const CURSORS_LOCK = "cursors.lock";
 const BUS_FILE = "bus.json";
 /** Keeps the log bounded without needing a rotation daemon. */
 const LOG_TAIL_BYTES = 512 * 1024;
@@ -77,32 +78,104 @@ export function createStateStore(options = {}) {
         }
         return out;
     }
-    function withSignalsLock(fn) {
+    function pidAlive(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (err) {
+            // ESRCH: gone. EPERM: exists, just unsignalable — still a live holder.
+            return err.code === "EPERM";
+        }
+    }
+    /** Owner recorded in the lock file so a crash can be distinguished from a live holder. */
+    function readLockOwner(lockPath) {
+        try {
+            const rec = JSON.parse(readFileSync(lockPath, "utf8"));
+            if (typeof rec.pid !== "number" || !Number.isInteger(rec.pid) || rec.pid <= 0)
+                return null;
+            const at = typeof rec.at === "number" ? rec.at : 0;
+            return { pid: rec.pid, at };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Dead pid → steal now. Empty leftover from older writers (wx with no owner
+     * bytes) → steal once mtime is older than the wait, so an in-flight create is
+     * not yanked out from under the holder.
+     * Owner is read once: a second read can see a pid that appeared after an
+     * empty snapshot and would steal a live lock.
+     */
+    function lockIsStale(lockPath) {
+        const owner = readLockOwner(lockPath);
+        if (owner)
+            return !pidAlive(owner.pid);
+        try {
+            return Date.now() - statSync(lockPath).mtimeMs >= LOCK_WAIT_MS;
+        }
+        catch {
+            return false;
+        }
+    }
+    function lockBusy(code) {
+        // Unix: O_EXCL on an existing file is EEXIST. Windows: a holder that still
+        // has the handle open (or a delete-pending name) is EPERM / EACCES / EBUSY.
+        return (code === "EEXIST" ||
+            code === "EPERM" ||
+            code === "EACCES" ||
+            code === "EBUSY");
+    }
+    function unlinkLock(lockPath) {
+        const until = Date.now() + 500;
+        while (true) {
+            try {
+                rmSync(lockPath, { force: true });
+                return;
+            }
+            catch (err) {
+                if (!lockBusy(err.code) || Date.now() >= until) {
+                    return;
+                }
+                sleepSync(10);
+            }
+        }
+    }
+    function withFileLock(lockName, fn) {
         ensureDir();
-        const lockPath = join(dir, SIGNALS_LOCK);
+        const lockPath = join(dir, lockName);
         const deadline = Date.now() + LOCK_WAIT_MS;
         while (true) {
             try {
                 const fd = openSync(lockPath, "wx");
                 try {
+                    writeFileSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
                     return fn();
                 }
                 finally {
                     closeSync(fd);
-                    rmSync(lockPath, { force: true });
+                    unlinkLock(lockPath);
                 }
             }
             catch (err) {
                 const code = err.code;
-                if (code !== "EEXIST")
+                if (!lockBusy(code))
                     throw err;
+                if (code === "EEXIST" && lockIsStale(lockPath)) {
+                    unlinkLock(lockPath);
+                    continue;
+                }
                 if (Date.now() >= deadline) {
-                    throw new Error(`timed out waiting for ${SIGNALS_LOCK}`);
+                    throw new Error(`timed out waiting for ${lockName}`);
                 }
                 sleepSync(10);
             }
         }
     }
+    function withSignalsLock(fn) {
+        return withFileLock(SIGNALS_LOCK, fn);
+    }
     function readSignals() {
         return readJson(SIGNALS_FILE, {});
     }
@@ -136,14 +209,18 @@ export function createStateStore(options = {}) {
         return all[key] ?? null;
     }
     function writeCursor(key, text) {
-        const all = readJson(CURSORS_FILE, {});
-        all[key] = text;
-        writeJson(CURSORS_FILE, all);
+        withFileLock(CURSORS_LOCK, () => {
+            const all = readJson(CURSORS_FILE, {});
+            all[key] = text;
+            writeJson(CURSORS_FILE, all);
+        });
     }
     function clearCursor(key) {
-        const all = readJson(CURSORS_FILE, {});
-        delete all[key];
-        writeJson(CURSORS_FILE, all);
+        withFileLock(CURSORS_LOCK, () => {
+            const all = readJson(CURSORS_FILE, {});
+            delete all[key];
+            writeJson(CURSORS_FILE, all);
+        });
     }
     function readBus() {
         const value = readJson(BUS_FILE, null);

package/dist/zellij/binary.d.ts

@@ -10,10 +10,12 @@ export declare function resolveZellijBinary(env?: NodeJS.ProcessEnv): string;
 export declare function sanitizeZellijEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /**
  * Remote crew: `ZSWARM_SSH=user@host` routes every zellij call over ssh.
- * `ZSWARM_SSH_OPTS` is split on whitespace; `BatchMode` keeps it non-interactive.
+ * `ZSWARM_SSH_OPTS` is split like a shell so quoted paths stay one arg;
+ * `BatchMode` keeps it non-interactive.
  * `ZSWARM_TMP` points at the interactive session's temp (or `auto` to discover).
  * `ZSWARM_SSH_MODE=interactive` runs each call in the Windows desktop session.
  */
+export declare function parseSshOpts(raw: string): string[];
 export declare function resolveSshTarget(env?: NodeJS.ProcessEnv): SshTarget | null;
 /** Runner bound to the resolved zellij binary and a cleaned environment. */
 export declare function defaultExec(zellijPath: string, env: NodeJS.ProcessEnv): ZellijExecFn;

package/dist/zellij/binary.js

@@ -75,15 +75,47 @@ export function sanitizeZellijEnv(env) {
 }
 /**
  * Remote crew: `ZSWARM_SSH=user@host` routes every zellij call over ssh.
- * `ZSWARM_SSH_OPTS` is split on whitespace; `BatchMode` keeps it non-interactive.
+ * `ZSWARM_SSH_OPTS` is split like a shell so quoted paths stay one arg;
+ * `BatchMode` keeps it non-interactive.
  * `ZSWARM_TMP` points at the interactive session's temp (or `auto` to discover).
  * `ZSWARM_SSH_MODE=interactive` runs each call in the Windows desktop session.
  */
+export function parseSshOpts(raw) {
+    const out = [];
+    let cur = "";
+    let quote = null;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                cur += ch;
+            }
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (/\s/.test(ch)) {
+            if (cur.length > 0) {
+                out.push(cur);
+                cur = "";
+            }
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (cur.length > 0)
+        out.push(cur);
+    return out;
+}
 export function resolveSshTarget(env = process.env) {
     const host = env.ZSWARM_SSH?.trim();
     if (!host)
         return null;
-    const options = (env.ZSWARM_SSH_OPTS ?? "").trim().split(/\s+/).filter(Boolean);
+    const options = parseSshOpts(env.ZSWARM_SSH_OPTS ?? "");
     if (!options.some((o) => o.startsWith("BatchMode"))) {
         options.unshift("-o", "BatchMode=yes");
     }

package/dist/zellij/client.js

@@ -5,7 +5,7 @@ import { parseTabList, resolveTab } from "./tabs.js";
 import { createSshExec } from "../exec.js";
 import { DEFAULT_TIMEOUT_MS, NOT_FOUND_EXIT, defaultExec, resolveSshTarget, resolveZellijBinary, sanitizeZellijEnv, } from "./binary.js";
 import { normalizePaneId, parsePaneList, resolvePane, } from "./panes.js";
-import { parseSessionList, resolveSelfPaneId, sessionFromEnv, sessionFromList, } from "./session.js";
+import { isZellijNoSessionsOutput, parseSessionList, resolveSelfPaneId, sessionFromEnv, sessionFromList, } from "./session.js";
 /** Thin, stateless wrapper over the `zellij` binary. */
 export function createZellijClient(options = {}) {
     const env = options.env ?? process.env;
@@ -30,7 +30,20 @@ export function createZellijClient(options = {}) {
         return result;
     }
     async function listSessions() {
-        const result = await run(["list-sessions", "--short", "--no-formatting"], "zellij list-sessions");
+        const result = await exec(["list-sessions", "--short", "--no-formatting"], {
+            timeoutMs,
+        });
+        if (result.code === NOT_FOUND_EXIT) {
+            throw new ZellijError("zellij_missing", `zellij binary not found (${zellijPath}); install Zellij ≥ 0.42, add it to PATH, or set ZSWARM_BIN / ZSWARM_PATH`);
+        }
+        if (result.code !== 0) {
+            // Nonzero here is Zellij's normal "none running", not a crash. Empty
+            // lets resolveSession throw zellij_no_session so unworktree can treat
+            // it as no occupants instead of zellij_failed.
+            if (isZellijNoSessionsOutput(result.stdout, result.stderr))
+                return [];
+            throw new ZellijError("zellij_failed", `zellij list-sessions failed (exit ${result.code}): ${result.stderr.trim() || result.stdout.trim() || "no output"}`);
+        }
         return parseSessionList(result.stdout);
     }
     async function resolveSession(explicit) {

package/dist/zellij/session.d.ts

@@ -8,6 +8,8 @@ export type ZellijSessionResolve = {
  */
 export declare function resolveSelfPaneId(env?: NodeJS.ProcessEnv): string | null;
 export declare function parseSessionList(stdout: string): string[];
+/** Zellij exits 1 and prints this when the machine simply has no sessions. */
+export declare function isZellijNoSessionsOutput(stdout: string, stderr: string): boolean;
 /** Session from an explicit argument or the environment, before asking Zellij. */
 export declare function sessionFromEnv(env: NodeJS.ProcessEnv, explicit?: string | null): ZellijSessionResolve | null;
 /** Pick a session when the environment gave no answer. */

package/dist/zellij/session.js

@@ -19,6 +19,10 @@ export function parseSessionList(stdout) {
         .map((l) => l.trim())
         .filter(Boolean);
 }
+/** Zellij exits 1 and prints this when the machine simply has no sessions. */
+export function isZellijNoSessionsOutput(stdout, stderr) {
+    return /no active zellij sessions found/i.test(`${stderr}\n${stdout}`);
+}
 /** Session from an explicit argument or the environment, before asking Zellij. */
 export function sessionFromEnv(env, explicit) {
     const arg = explicit?.trim();

package/package.json

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