@zswarm/core 0.1.2 → 0.1.3

package/dist/exec.d.ts

@@ -7,6 +7,8 @@ export type ExecResult = {
 export type ExecOptions = {
     timeoutMs: number;
     cwd?: string;
+    /** Overlay on the runner's env (e.g. GIT_INDEX_FILE for a scratch index). */
+    env?: NodeJS.ProcessEnv;
     /**
      * Stop as soon as the accumulated stdout satisfies this, instead of waiting
      * for the process to exit. `zellij pipe` answers in milliseconds but stays

package/dist/exec.js

@@ -70,10 +70,12 @@ export function createSshExec(target, env) {
         if (requested.toLowerCase() !== "auto") {
             return { tmp: requested, socketDir: "" };
         }
-        if (cached !== undefined)
-            return cached ?? undefined;
-        cached = (await discoverRemoteIpc(runner, target, timeoutMs)) ?? null;
-        return cached ?? undefined;
+        if (cached)
+            return cached;
+        const dirs = await discoverRemoteIpc(runner, target, timeoutMs);
+        if (dirs)
+            cached = dirs;
+        return dirs;
     }
     return async (args, options) => {
         const ipc = await resolveIpc(options.timeoutMs);
@@ -85,7 +87,7 @@ export function createSshExec(target, env) {
 function runUntil(binPath, args, env, options) {
     return new Promise((resolve) => {
         const child = spawn(binPath, args, {
-            env,
+            env: options.env ? { ...env, ...options.env } : env,
             cwd: options.cwd,
             windowsHide: true,
             stdio: ["ignore", "pipe", "pipe"],
@@ -136,7 +138,7 @@ function runToExit(binPath, args, env, options) {
             cwd: options.cwd,
             maxBuffer: 8 * 1024 * 1024,
             windowsHide: true,
-            env,
+            env: options.env ? { ...env, ...options.env } : env,
         }, (error, stdout, stderr) => {
             const failure = error;
             if (failure && typeof failure.code === "string") {

package/dist/git.js

@@ -1,4 +1,6 @@
-import { basename, dirname, join } from "node:path";
+import { copyFileSync, rmSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import { ZellijError } from "./errors.js";
 import { createExec, NOT_FOUND_EXIT } from "./exec.js";
 const DEFAULT_TIMEOUT_MS = 20_000;
@@ -77,8 +79,8 @@ export function createGitClient(options = {}) {
     const gitPath = options.gitPath ?? env.ZSWARM_GIT_BIN?.trim() ?? "git";
     const exec = options.exec ?? createExec(gitPath, env);
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    async function run(args, cwd, label) {
-        const result = await exec(args, { timeoutMs, cwd });
+    async function run(args, cwd, label, extraEnv) {
+        const result = await exec(args, { timeoutMs, cwd, env: extraEnv });
         if (result.code === NOT_FOUND_EXIT) {
             throw new ZellijError("git_missing", `git not found (${gitPath}); install git or set ZSWARM_GIT_BIN`);
         }
@@ -136,32 +138,54 @@ export function createGitClient(options = {}) {
         return result.stdout.trim().length > 0;
     }
     /**
-     * Stage untracked paths as intent-to-add so they appear in `git diff`
-     * (without copying blob contents into the object database).
+     * Stage untracked paths as intent-to-add in a scratch index so they appear
+     * in `git diff` without mutating the real `.git/index`.
      */
-    async function intentAddUntracked(path) {
-        await run(["add", "-A", "--intent-to-add"], path, "git add --intent-to-add");
+    async function withScratchIndex(path, fn) {
+        const located = await run(["rev-parse", "--git-path", "index"], path, "git rev-parse --git-path index");
+        const indexRel = located.stdout.trim();
+        const indexAbs = isAbsolute(indexRel) ? indexRel : join(path, indexRel);
+        const scratch = `${indexAbs}.zswarm-${process.pid}-${randomBytes(4).toString("hex")}`;
+        try {
+            copyFileSync(indexAbs, scratch);
+        }
+        catch {
+            // No index yet (empty repo / new worktree).
+        }
+        try {
+            return await fn({ GIT_INDEX_FILE: scratch });
+        }
+        finally {
+            rmSync(scratch, { force: true });
+        }
     }
-    /** `git diff --stat HEAD`, including untracked via `--intent-to-add`. */
+    async function intentAddUntracked(path, indexEnv) {
+        await run(["add", "-A", "--intent-to-add"], path, "git add --intent-to-add", indexEnv);
+    }
+    /** `git diff --stat HEAD`, including untracked via a scratch intent-to-add. */
     async function diffStat(path) {
-        await intentAddUntracked(path);
-        const result = await run(["diff", "--stat", "HEAD"], path, "git diff --stat");
-        return result.stdout;
+        return withScratchIndex(path, async (indexEnv) => {
+            await intentAddUntracked(path, indexEnv);
+            const result = await run(["diff", "--stat", "HEAD"], path, "git diff --stat", indexEnv);
+            return result.stdout;
+        });
     }
     /**
-     * `git diff HEAD`, including untracked via `--intent-to-add`.
+     * `git diff HEAD`, including untracked via a scratch intent-to-add.
      * When `maxChars > 0` and the patch is longer, keep the head and set
      * `truncated`. `chars` is always the full patch length before truncating.
      */
     async function diffPatch(path, maxChars) {
-        await intentAddUntracked(path);
-        const result = await run(["diff", "HEAD"], path, "git diff");
-        const full = result.stdout;
-        const chars = full.length;
-        if (maxChars <= 0 || chars <= maxChars) {
-            return { patch: full, truncated: false, chars };
-        }
-        return { patch: full.slice(0, maxChars), truncated: true, chars };
+        return withScratchIndex(path, async (indexEnv) => {
+            await intentAddUntracked(path, indexEnv);
+            const result = await run(["diff", "HEAD"], path, "git diff", indexEnv);
+            const full = result.stdout;
+            const chars = full.length;
+            if (maxChars <= 0 || chars <= maxChars) {
+                return { patch: full, truncated: false, chars };
+            }
+            return { patch: full.slice(0, maxChars), truncated: true, chars };
+        });
     }
     /** `git add -A` then `git commit -m`; returns the new short HEAD sha. */
     async function commitAll(path, message) {

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, type Policy,
 export { buildSshRemoteCommand, createSshExec, quoteRemoteArg, shellQuote, type SshTarget, } from "./exec.js";
 export { resolveSshTarget } from "./zellij/binary.js";
 export { applyIpcTmpEnv, cmdQuote, concreteTmp, encodePowerShellCommand, inferRemoteShell, parseZellijServerPaths, pickIpcDirs, pickIpcTmp, socketDirFromServerPath, tmpFromServerPath, unixDiscoverRemote, windowsDiscoverRemote, windowsInteractiveRemote, wrapWithTmpEnv, } from "./zellij/ipc.js";
-export { callServe, DEFAULT_SERVE_LISTEN, installServeLogon, parseListenAddress, SERVE_TASK_NAME, serveCallTimeout, serveChildEnv, serveLogonCommand, startServe, uninstallServeLogon, } from "./ops/serve.js";
+export { callServe, DEFAULT_SERVE_LISTEN, installServeLogon, isLoopbackHost, parseListenAddress, SERVE_CALL_TIMEOUT_CAP_MS, SERVE_MAX_REQUEST_BYTES, SERVE_TASK_NAME, serveCallTimeout, serveChildEnv, serveLogonCommand, startServe, uninstallServeLogon, } from "./ops/serve.js";
 export { parseTabList, resolveTab, type ZellijTab } from "./zellij/tabs.js";
 export { selectTargets } from "./ops/broadcast.js";
 export { diffScreens, cursorKey } from "./ops/tail.js";

package/dist/index.js

@@ -14,7 +14,7 @@ export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, } from "./po
 export { buildSshRemoteCommand, createSshExec, quoteRemoteArg, shellQuote, } from "./exec.js";
 export { resolveSshTarget } from "./zellij/binary.js";
 export { applyIpcTmpEnv, cmdQuote, concreteTmp, encodePowerShellCommand, inferRemoteShell, parseZellijServerPaths, pickIpcDirs, pickIpcTmp, socketDirFromServerPath, tmpFromServerPath, unixDiscoverRemote, windowsDiscoverRemote, windowsInteractiveRemote, wrapWithTmpEnv, } from "./zellij/ipc.js";
-export { callServe, DEFAULT_SERVE_LISTEN, installServeLogon, parseListenAddress, SERVE_TASK_NAME, serveCallTimeout, serveChildEnv, serveLogonCommand, startServe, uninstallServeLogon, } from "./ops/serve.js";
+export { callServe, DEFAULT_SERVE_LISTEN, installServeLogon, isLoopbackHost, parseListenAddress, SERVE_CALL_TIMEOUT_CAP_MS, SERVE_MAX_REQUEST_BYTES, SERVE_TASK_NAME, serveCallTimeout, serveChildEnv, serveLogonCommand, startServe, uninstallServeLogon, } from "./ops/serve.js";
 export { parseTabList, resolveTab } from "./zellij/tabs.js";
 export { selectTargets } from "./ops/broadcast.js";
 export { diffScreens, cursorKey } from "./ops/tail.js";

package/dist/ops/dispatch.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, paneViewBus, paneViewFull, paneViewSlim, truncateDumpText, } from "./util.js";
+import { dumpMaxChars, fail, isTrue, isVerbose, optionalString, paneViewBus, paneViewFull, paneViewSlim, truncateDumpText, } from "./util.js";
 import { waitForPane } from "./wait.js";
 import { listPeerWorktrees, removePeerWorktree } from "./worktree.js";
 import { callServe, installServeLogon, serveCallTimeout, uninstallServeLogon, } from "./serve.js";
@@ -29,6 +29,24 @@ function waitMode(args) {
     }
     return typeof args.match === "string" && args.match ? "match" : "idle";
 }
+const SSH_GIT_OPS = new Set([
+    "worktrees",
+    "unworktree",
+    "diff",
+    "checkpoint",
+]);
+/**
+ * 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.
+ */
+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))
+        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`);
+}
 async function resolveTarget(client, args, state, clock, env, policy, op) {
     const to = String(args.to ?? "").trim();
     if (!to)
@@ -76,6 +94,7 @@ export async function dispatchZswarm(args, injected, deps = {}) {
     try {
         // Policy gates the op before anything touches the session.
         assertOpAllowed(policy, op);
+        assertSshGitAllowed(env, op, args);
         if (op === "serve") {
             if (isTrue(args.clear)) {
                 const cleared = await uninstallServeLogon({
@@ -94,7 +113,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));
+            return await callServe(env.ZSWARM_SERVE.trim(), args, serveCallTimeout(args), env.ZSWARM_SERVE_TOKEN);
         }
         const client = injected ?? createZellijClient({ env: deps.env });
         switch (op) {

package/dist/ops/serve.d.ts

@@ -1,17 +1,27 @@
 import type { OpsResult } from "./types.js";
 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;
+/** 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;
+export declare function formatListenLabel(host: string, port: number): string;
 export declare function parseListenAddress(raw: string | undefined): {
     host: string;
     port: number;
     label: string;
 };
-/** Client-side wait: the op's own timeout plus slack, capped at ten minutes. */
+/** Client-side wait: the op's own timeout plus slack. */
 export declare function serveCallTimeout(args: Record<string, unknown>): number;
 /** Env for a serve worker: talk to the local Zellij, never loop back into serve/ssh. */
 export declare function serveChildEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export type ServeDispatch = (args: Record<string, unknown>) => Promise<OpsResult>;
-export declare function startServe(listen: string | undefined, dispatch: ServeDispatch): Promise<{
+export type StartServeOptions = {
+    token?: string;
+    maxRequestBytes?: number;
+};
+export declare function startServe(listen: string | undefined, dispatch: ServeDispatch, options?: StartServeOptions): Promise<{
     label: string;
     close: () => Promise<void>;
 }>;
@@ -19,7 +29,7 @@ export declare function parseServeTarget(raw: string): {
     host: string;
     port: number;
 };
-export declare function callServe(target: string, args: Record<string, unknown>, timeoutMs?: number): Promise<OpsResult>;
+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 installServeLogon(input: {
     listen?: string;

package/dist/ops/serve.js

@@ -4,27 +4,56 @@ import { ZellijError } from "../errors.js";
 import { encodePowerShellCommand } from "../zellij/ipc.js";
 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;
+/** 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";
+export function isLoopbackHost(host) {
+    const h = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    return (h === "127.0.0.1" ||
+        h === "localhost" ||
+        h === "::1" ||
+        h === "0:0:0:0:0:0:0:1");
+}
+export function formatListenLabel(host, port) {
+    return host.includes(":") ? `[${host}]:${port}` : `${host}:${port}`;
+}
 export function parseListenAddress(raw) {
     const text = (raw ?? DEFAULT_SERVE_LISTEN).trim() || DEFAULT_SERVE_LISTEN;
     const stripped = text.replace(/^tcp:\/\//i, "");
-    const hostPort = stripped.includes("]")
-        ? stripped
-        : stripped.includes(":")
+    let host;
+    let port;
+    if (stripped.startsWith("[")) {
+        const end = stripped.indexOf("]");
+        if (end === -1) {
+            throw new ZellijError("bad_arg", `listen address is not host:port (${text})`);
+        }
+        host = stripped.slice(1, end);
+        const rest = stripped.slice(end + 1);
+        if (!rest.startsWith(":")) {
+            throw new ZellijError("bad_arg", `listen address is not host:port (${text})`);
+        }
+        port = Number(rest.slice(1));
+    }
+    else {
+        const hostPort = stripped.includes(":")
             ? stripped
             : `127.0.0.1:${stripped}`;
-    const colon = hostPort.lastIndexOf(":");
-    const host = colon === -1 ? "127.0.0.1" : hostPort.slice(0, colon) || "127.0.0.1";
-    const port = Number(colon === -1 ? hostPort : hostPort.slice(colon + 1));
-    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        const colon = hostPort.lastIndexOf(":");
+        host = colon === -1 ? "127.0.0.1" : hostPort.slice(0, colon) || "127.0.0.1";
+        port = Number(colon === -1 ? hostPort : hostPort.slice(colon + 1));
+    }
+    if (!host || !Number.isInteger(port) || port < 0 || port > 65535) {
         throw new ZellijError("bad_arg", `listen address is not host:port (${text})`);
     }
-    return { host, port, label: `${host}:${port}` };
+    return { host, port, label: formatListenLabel(host, port) };
 }
-/** Client-side wait: the op's own timeout plus slack, capped at ten minutes. */
+/** Client-side wait: the op's own timeout plus slack. */
 export function serveCallTimeout(args) {
     const requested = Number(args.timeoutMs);
     const base = Number.isFinite(requested) && requested > 0 ? requested : 60_000;
-    return Math.min(Math.max(base + 5_000, 15_000), 10 * 60_000);
+    return Math.min(Math.max(base + 5_000, 15_000), SERVE_CALL_TIMEOUT_CAP_MS);
 }
 /** Env for a serve worker: talk to the local Zellij, never loop back into serve/ssh. */
 export function serveChildEnv(env) {
@@ -33,14 +62,47 @@ export function serveChildEnv(env) {
     delete out.ZSWARM_SSH;
     return out;
 }
-export function startServe(listen, dispatch) {
+function unauthorized() {
+    return {
+        ok: false,
+        error: {
+            code: "serve_unauthorized",
+            message: "zswarm serve rejected the request (missing or wrong ZSWARM_SERVE_TOKEN)",
+        },
+    };
+}
+function takeServeToken(args) {
+    const token = typeof args[SERVE_TOKEN_FIELD] === "string"
+        ? args[SERVE_TOKEN_FIELD]
+        : undefined;
+    const request = { ...args };
+    delete request[SERVE_TOKEN_FIELD];
+    return { token, request };
+}
+export function startServe(listen, dispatch, options = {}) {
     const { host, port } = parseListenAddress(listen);
+    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`));
+    }
+    const maxRequestBytes = options.maxRequestBytes ?? SERVE_MAX_REQUEST_BYTES;
     return new Promise((resolve, reject) => {
         const server = createServer((socket) => {
             let buf = "";
             socket.setEncoding("utf8");
             socket.on("data", (chunk) => {
                 buf += chunk;
+                if (buf.length > maxRequestBytes) {
+                    socket.write(`${JSON.stringify({
+                        ok: false,
+                        error: {
+                            code: "bad_arg",
+                            message: `serve request exceeded ${maxRequestBytes} bytes`,
+                        },
+                    })}\n`);
+                    socket.destroy();
+                    return;
+                }
                 void drain();
             });
             async function drain() {
@@ -51,8 +113,14 @@ export function startServe(listen, dispatch) {
                     if (line) {
                         let result;
                         try {
-                            const args = JSON.parse(line);
-                            result = await dispatch(args);
+                            const parsed = JSON.parse(line);
+                            const taken = takeServeToken(parsed);
+                            if (token && taken.token !== token) {
+                                result = unauthorized();
+                            }
+                            else {
+                                result = await dispatch(taken.request);
+                            }
                         }
                         catch (err) {
                             const message = err instanceof Error ? err.message : String(err);
@@ -69,7 +137,7 @@ export function startServe(listen, dispatch) {
             const addr = server.address();
             const actualPort = typeof addr === "object" && addr ? addr.port : port;
             resolve({
-                label: `${host}:${actualPort}`,
+                label: formatListenLabel(host, actualPort),
                 close: () => new Promise((done, fail) => {
                     server.close((err) => (err ? fail(err) : done()));
                 }),
@@ -80,8 +148,11 @@ export function startServe(listen, dispatch) {
 export function parseServeTarget(raw) {
     return parseListenAddress(raw);
 }
-export function callServe(target, args, timeoutMs = 15_000) {
+export function callServe(target, args, timeoutMs = 15_000, token) {
     const { host, port } = parseServeTarget(target);
+    const payload = token && token.trim()
+        ? { ...args, [SERVE_TOKEN_FIELD]: token.trim() }
+        : args;
     return new Promise((resolve) => {
         const socket = connect({ host, port });
         let buf = "";
@@ -130,7 +201,7 @@ export function callServe(target, args, timeoutMs = 15_000) {
             }
         });
         socket.on("connect", () => {
-            socket.write(`${JSON.stringify(args)}\n`);
+            socket.write(`${JSON.stringify(payload)}\n`);
         });
     });
 }
@@ -191,7 +262,19 @@ export async function uninstallServeLogon(input = {}) {
     if ((input.platform ?? process.platform) !== "win32") {
         throw new ZellijError("usage", "serve --clear is Windows-only");
     }
-    const script = `Unregister-ScheduledTask -TaskName '${SERVE_TASK_NAME}' -Confirm:$false -ErrorAction SilentlyContinue`;
-    await runPowerShell(script);
+    const script = [
+        "$ProgressPreference = 'SilentlyContinue'",
+        "try {",
+        `  Unregister-ScheduledTask -TaskName '${SERVE_TASK_NAME}' -Confirm:$false`,
+        "} catch {",
+        "  if ($_.CategoryInfo.Category -eq 'ObjectNotFound') { exit 0 }",
+        "  [Console]::Error.Write(($_ | Out-String).Trim())",
+        "  exit 1",
+        "}",
+    ].join("\n");
+    const result = await runPowerShell(script);
+    if (result.code !== 0) {
+        throw new ZellijError("zellij_failed", `serve --clear failed: ${(result.stderr || result.stdout).trim() || "no output"}`);
+    }
     return { task: SERVE_TASK_NAME, cleared: true };
 }

package/dist/ops/worktree.js

@@ -120,8 +120,15 @@ export async function removePeerWorktree(git, client, args, env = process.env) {
         const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
         occupants = panesIn(await client.listPanes(session), target.path);
     }
-    catch {
-        // No live session means nobody is working in it.
+    catch (err) {
+        // No live session means nobody is working in it. Any other failure must
+        // not look like "empty" — that is how a clean busy worktree gets deleted.
+        if (err instanceof ZellijError && err.code === "zellij_no_session") {
+            occupants = [];
+        }
+        else {
+            throw err;
+        }
     }
     if (occupants.length > 0 && !force) {
         throw new ZellijError("worktree_busy", `${occupants.join(", ")} still working in ${target.path}; close the pane or pass force=true`);

package/dist/policy.js

@@ -7,6 +7,12 @@ const WRITE_OPS = new Set([
     "spawn",
     "close",
     "unworktree",
+    "checkpoint",
+    "signal",
+    "rename",
+    "focus",
+    "stack",
+    "serve",
 ]);
 /** Explicit disable tokens for ZSWARM_ALLOW_* switches. */
 function isDisabled(raw) {

package/dist/schema.js

@@ -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.", "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", "");
+    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", "");
     return lines.join("\n");
 }
 /** Turn argv (without the op) into dispatch args, driven by PARAMS. */
@@ -465,10 +465,22 @@ function extractOp(argv) {
         return { op: first, rest: argv.slice(1) };
     }
     const names = OP_NAMES;
-    const at = argv.findIndex((token) => names.includes(token));
-    if (at === -1)
-        return { op: first ?? "", rest: argv.slice(1) };
-    return { op: argv[at], rest: [...argv.slice(0, at), ...argv.slice(at + 1)] };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith("-")) {
+            const param = FLAG_INDEX.get(token);
+            if (param && param.type !== "boolean")
+                i += 1;
+            continue;
+        }
+        if (names.includes(token)) {
+            return {
+                op: token,
+                rest: [...argv.slice(0, i), ...argv.slice(i + 1)],
+            };
+        }
+    }
+    return { op: first ?? "", rest: argv.slice(1) };
 }
 export function parseCliArgv(argv) {
     const { op, rest } = extractOp(argv);

package/dist/state.js

@@ -1,12 +1,17 @@
-import { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, 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 BUS_FILE = "bus.json";
 /** Keeps the log bounded without needing a rotation daemon. */
 const LOG_TAIL_BYTES = 512 * 1024;
+const LOCK_WAIT_MS = 5_000;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 export function defaultStateDir(env = process.env) {
     const explicit = env.ZSWARM_STATE_DIR?.trim();
     if (explicit)
@@ -72,29 +77,59 @@ export function createStateStore(options = {}) {
         }
         return out;
     }
+    function withSignalsLock(fn) {
+        ensureDir();
+        const lockPath = join(dir, SIGNALS_LOCK);
+        const deadline = Date.now() + LOCK_WAIT_MS;
+        while (true) {
+            try {
+                const fd = openSync(lockPath, "wx");
+                try {
+                    return fn();
+                }
+                finally {
+                    closeSync(fd);
+                    rmSync(lockPath, { force: true });
+                }
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "EEXIST")
+                    throw err;
+                if (Date.now() >= deadline) {
+                    throw new Error(`timed out waiting for ${SIGNALS_LOCK}`);
+                }
+                sleepSync(10);
+            }
+        }
+    }
     function readSignals() {
         return readJson(SIGNALS_FILE, {});
     }
     function postSignal(channel, payload, at) {
-        const all = readSignals();
-        const prev = all[channel];
-        const next = {
-            count: (prev?.count ?? 0) + 1,
-            at,
-            last: payload,
-        };
-        all[channel] = next;
-        writeJson(SIGNALS_FILE, all);
-        return next;
+        return withSignalsLock(() => {
+            const all = readSignals();
+            const prev = all[channel];
+            const next = {
+                count: (prev?.count ?? 0) + 1,
+                at,
+                last: payload,
+            };
+            all[channel] = next;
+            writeJson(SIGNALS_FILE, all);
+            return next;
+        });
     }
     function clearSignal(channel) {
-        if (channel === null) {
-            writeJson(SIGNALS_FILE, {});
-            return;
-        }
-        const all = readSignals();
-        delete all[channel];
-        writeJson(SIGNALS_FILE, all);
+        withSignalsLock(() => {
+            if (channel === null) {
+                writeJson(SIGNALS_FILE, {});
+                return;
+            }
+            const all = readSignals();
+            delete all[channel];
+            writeJson(SIGNALS_FILE, all);
+        });
     }
     function readCursor(key) {
         const all = readJson(CURSORS_FILE, {});

package/dist/zellij/ipc.js

@@ -7,7 +7,7 @@
  */
 /** `…/zellij/contract_version_N/…` or Unix `…/zellij-<uid>/contract_version_N/…`. */
 const ZELLIJ_DIR = /[\\/](zellij(?:-\d+)?)[\\/]contract_version_[^\\/]+[\\/]/i;
-const SERVER_FLAG = /(?:^|\s)--server(?:\s+|=)(\S+)/;
+const SERVER_FLAG = /(?:^|\s)--server(?:\s+|=)(?:"([^"]+)"|'([^']+)'|(\S+))/;
 /** Drive letter plus rest, or a UNC / posix path. */
 export function looksLikeWindowsPath(path) {
     return /^[A-Za-z]:[\\/]/.test(path) || path.includes("\\");
@@ -50,8 +50,9 @@ export function parseZellijServerPaths(commandLines) {
     const found = [];
     for (const line of commandLines.split(/\r?\n/)) {
         const match = SERVER_FLAG.exec(line);
-        if (match?.[1])
-            found.push(stripQuotes(match[1]));
+        const captured = match?.[1] || match?.[2] || match?.[3];
+        if (captured)
+            found.push(stripQuotes(captured));
     }
     return found;
 }
@@ -104,9 +105,12 @@ export function inferRemoteShell(input) {
 export function cmdQuote(arg) {
     if (arg === "")
         return '""';
-    if (/^[A-Za-z0-9_@%+=:,.\\/-]+$/.test(arg))
-        return arg;
-    return `"${arg.replace(/"/g, '""')}"`;
+    // cmd.exe expands %VAR% even inside quotes; double percents to keep literals.
+    const escaped = arg.replace(/%/g, "%%");
+    if (/^[A-Za-z0-9_@+=:,.\\/-]+$/.test(escaped.replace(/%%/g, ""))) {
+        return escaped;
+    }
+    return `"${escaped.replace(/"/g, '""')}"`;
 }
 function defaultSocketDir(tmp, shell) {
     if (shell !== "cmd")
@@ -161,11 +165,13 @@ export function windowsInteractiveRemote(innerCmd, timeoutMs) {
         "$out = Join-Path $dir \"zswarm-$id.out\"",
         "$err = Join-Path $dir \"zswarm-$id.err\"",
         "$code = Join-Path $dir \"zswarm-$id.code\"",
-        "@(",
+        "$lines = @(",
         "  '@echo off'",
+        "  'chcp 65001 >nul'",
         "  \"$inner > `\"$out`\" 2> `\"$err`\"\"",
         "  \"echo %ERRORLEVEL% > `\"$code`\"\"",
-        ") | Set-Content -Path $bat -Encoding ASCII",
+        ")",
+        "[IO.File]::WriteAllLines($bat, $lines, [Text.UTF8Encoding]::new($false))",
         "try {",
         "  $create = & schtasks.exe /Create /TN $task /TR $bat /SC ONCE /ST 00:00 /IT /F /RL LIMITED 2>&1",
         "  if ($LASTEXITCODE -ne 0) {",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@zswarm/wasm": "0.1.0"
+    "@zswarm/wasm": "0.1.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",