@zswarm/core 0.1.1 → 0.1.3

package/dist/exec.d.ts

@@ -1,3 +1,4 @@
+import { type RemoteShell } from "./zellij/ipc.js";
 export type ExecResult = {
     code: number;
     stdout: string;
@@ -6,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
@@ -23,7 +26,17 @@ export type SshTarget = {
     host: string;
     remoteBin: string;
     options: string[];
+    /** Concrete IPC temp, or `auto` to read `--server` off a live zellij process. */
+    tmp?: string;
+    /** `interactive` runs the CLI in the Windows desktop session (schtasks /IT). */
+    mode?: "ssh" | "interactive";
+    remoteShell?: "cmd" | "sh";
 };
+export declare function quoteRemoteArg(arg: string, shell: RemoteShell): string;
+/**
+ * The string `ssh host <this>` runs. Tests assert this rather than spawning ssh.
+ */
+export declare function buildSshRemoteCommand(target: SshTarget, args: string[], tmp: string | undefined, timeoutMs: number, socketDir?: string): string;
 /**
  * Run the remote zellij over ssh. The whole invocation is quoted into a single
  * command string, because the remote login shell re-parses it.

package/dist/exec.js

@@ -1,4 +1,5 @@
 import { execFile, spawn } from "node:child_process";
+import { cmdQuote, inferRemoteShell, parseZellijServerPaths, pickIpcDirs, unixDiscoverRemote, windowsDiscoverRemote, windowsInteractiveRemote, wrapWithTmpEnv, } from "./zellij/ipc.js";
 export const NOT_FOUND_EXIT = 127;
 /** POSIX single-quoting, for building a command line the remote shell parses. */
 export function shellQuote(arg) {
@@ -8,14 +9,77 @@ export function shellQuote(arg) {
         return arg;
     return `'${arg.replace(/'/g, `'\\''`)}'`;
 }
+export function quoteRemoteArg(arg, shell) {
+    return shell === "cmd" ? cmdQuote(arg) : shellQuote(arg);
+}
+/**
+ * The string `ssh host <this>` runs. Tests assert this rather than spawning ssh.
+ */
+export function buildSshRemoteCommand(target, args, tmp, timeoutMs, socketDir) {
+    const shell = inferRemoteShell({
+        explicit: target.remoteShell,
+        tmp,
+        remoteBin: target.remoteBin,
+        mode: target.mode,
+    });
+    const zellij = [target.remoteBin, ...args]
+        .map((arg) => quoteRemoteArg(arg, shell))
+        .join(" ");
+    const withTmp = tmp ? wrapWithTmpEnv(zellij, tmp, shell, socketDir) : zellij;
+    if (target.mode === "interactive") {
+        return windowsInteractiveRemote(withTmp, timeoutMs);
+    }
+    // Windows OpenSSH often logs into PowerShell; `set "TEMP=…"` only works in cmd.
+    if (shell === "cmd") {
+        return `cmd.exe /c ${cmdQuote(withTmp)}`;
+    }
+    return withTmp;
+}
+async function discoverRemoteIpc(runner, target, timeoutMs) {
+    const shell = inferRemoteShell({
+        explicit: target.remoteShell,
+        remoteBin: target.remoteBin,
+        mode: target.mode,
+    });
+    // `auto` has no tmp yet, so a Windows host with remoteBin=zellij still looks
+    // like Unix. Try both listings; pickIpcDirs ignores lines without --server.
+    const probes = shell === "cmd"
+        ? [windowsDiscoverRemote(), unixDiscoverRemote()]
+        : [unixDiscoverRemote(), windowsDiscoverRemote()];
+    for (const probe of probes) {
+        const result = await runner([...target.options, target.host, probe], {
+            timeoutMs,
+        });
+        const dirs = pickIpcDirs(parseZellijServerPaths(result.stdout));
+        if (dirs)
+            return dirs;
+    }
+    return undefined;
+}
 /**
  * Run the remote zellij over ssh. The whole invocation is quoted into a single
  * command string, because the remote login shell re-parses it.
  */
 export function createSshExec(target, env) {
     const runner = createExec(target.ssh, env);
-    return (args, options) => {
-        const remote = [target.remoteBin, ...args].map(shellQuote).join(" ");
+    let cached;
+    async function resolveIpc(timeoutMs) {
+        const requested = target.tmp?.trim();
+        if (!requested)
+            return undefined;
+        if (requested.toLowerCase() !== "auto") {
+            return { tmp: requested, socketDir: "" };
+        }
+        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);
+        const remote = buildSshRemoteCommand(target, args, ipc?.tmp, options.timeoutMs, ipc?.socketDir);
         return runner([...target.options, target.host, remote], options);
     };
 }
@@ -23,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"],
@@ -74,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

@@ -11,8 +11,10 @@ export { createZellijClient, type ZellijClient, type ZellijClientOptions, } from
 export { createStateStore, defaultStateDir, type LogEntry, type SignalChannel, type StateStore, type StateStoreOptions, } from "./state.js";
 export { dispatchZswarm } from "./ops/dispatch.js";
 export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, type Policy, } from "./policy.js";
-export { createSshExec, shellQuote, type SshTarget } from "./exec.js";
+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, 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

@@ -11,8 +11,10 @@ export { createZellijClient, } from "./zellij/client.js";
 export { createStateStore, defaultStateDir, } from "./state.js";
 export { dispatchZswarm } from "./ops/dispatch.js";
 export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, } from "./policy.js";
-export { createSshExec, shellQuote } from "./exec.js";
+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, 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.d.ts

@@ -1,4 +1,4 @@
 import { type ZellijClient } from "../zellij/client.js";
 import type { DispatchDeps, OpsResult } from "./types.js";
 /** Shared MCP/CLI dispatch for zswarm ops. */
-export declare function dispatchZswarm(args: Record<string, unknown>, client?: ZellijClient, deps?: DispatchDeps): Promise<OpsResult>;
+export declare function dispatchZswarm(args: Record<string, unknown>, injected?: ZellijClient, deps?: DispatchDeps): Promise<OpsResult>;

package/dist/ops/dispatch.js

@@ -17,9 +17,10 @@ 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";
 /** Same default `wait` applies: match when a needle is given, else idle. */
 function waitMode(args) {
     const requested = typeof args.for === "string" ? args.for.trim() : "";
@@ -28,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)
@@ -57,7 +76,7 @@ async function resolveTarget(client, args, state, clock, env, policy, op) {
     return { session, panes, pane };
 }
 /** Shared MCP/CLI dispatch for zswarm ops. */
-export async function dispatchZswarm(args, client = createZellijClient(), deps = {}) {
+export async function dispatchZswarm(args, injected, deps = {}) {
     const op = String(args.op ?? "");
     const verbose = isVerbose(args);
     const clock = {
@@ -71,9 +90,32 @@ export async function dispatchZswarm(args, client = createZellijClient(), deps =
     let stateStore = deps.state ?? null;
     const state = () => (stateStore ??= createStateStore());
     const policy = deps.policy ?? loadPolicy(deps.env);
+    const env = deps.env ?? process.env;
     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({
+                    platform: process.platform,
+                });
+                return { ok: true, data: cleared };
+            }
+            if (isTrue(args.install)) {
+                const installed = await installServeLogon({
+                    listen: typeof args.listen === "string" ? args.listen : undefined,
+                });
+                return { ok: true, data: { ...installed, running: true } };
+            }
+            throw new ZellijError("usage", "serve --listen is CLI-only; MCP/dispatch would hang the tool call. Run `zswarm serve --listen` in the session that owns Zellij");
+        }
+        // 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);
+        }
+        const client = injected ?? createZellijClient({ env: deps.env });
         switch (op) {
             case "sessions": {
                 const sessions = await client.listSessions();

package/dist/ops/serve.d.ts

@@ -0,0 +1,49 @@
+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. */
+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 type StartServeOptions = {
+    token?: string;
+    maxRequestBytes?: number;
+};
+export declare function startServe(listen: string | undefined, dispatch: ServeDispatch, options?: StartServeOptions): Promise<{
+    label: string;
+    close: () => Promise<void>;
+}>;
+export declare function parseServeTarget(raw: string): {
+    host: 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 installServeLogon(input: {
+    listen?: string;
+    execPath?: string;
+    scriptPath?: string;
+    platform?: NodeJS.Platform;
+}): Promise<{
+    task: string;
+    listen: string;
+    command: string;
+}>;
+export declare function uninstallServeLogon(input?: {
+    platform?: NodeJS.Platform;
+}): Promise<{
+    task: string;
+    cleared: true;
+}>;

package/dist/ops/serve.js

@@ -0,0 +1,280 @@
+import { createServer, connect } from "node:net";
+import { execFile } from "node:child_process";
+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, "");
+    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(":");
+        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: formatListenLabel(host, port) };
+}
+/** 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), 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) {
+    const out = { ...env };
+    delete out.ZSWARM_SERVE;
+    delete out.ZSWARM_SSH;
+    return out;
+}
+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() {
+                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();
+                            }
+                            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 } };
+                        }
+                        socket.write(`${JSON.stringify(result)}\n`);
+                    }
+                    nl = buf.indexOf("\n");
+                }
+            }
+        });
+        server.on("error", reject);
+        server.listen(port, host, () => {
+            const addr = server.address();
+            const actualPort = typeof addr === "object" && addr ? addr.port : port;
+            resolve({
+                label: formatListenLabel(host, actualPort),
+                close: () => new Promise((done, fail) => {
+                    server.close((err) => (err ? fail(err) : done()));
+                }),
+            });
+        });
+    });
+}
+export function parseServeTarget(raw) {
+    return parseListenAddress(raw);
+}
+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 = "";
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({
+                ok: false,
+                error: {
+                    code: "timeout",
+                    message: `zswarm serve at ${host}:${port} timed out after ${timeoutMs}ms`,
+                },
+            });
+        }, timeoutMs);
+        socket.setEncoding("utf8");
+        socket.on("error", (err) => {
+            finish({
+                ok: false,
+                error: {
+                    code: "serve_unreachable",
+                    message: `cannot reach zswarm serve at ${host}:${port}: ${err.message}`,
+                },
+            });
+        });
+        socket.on("data", (chunk) => {
+            buf += chunk;
+            const nl = buf.indexOf("\n");
+            if (nl === -1)
+                return;
+            const line = buf.slice(0, nl).trim();
+            try {
+                finish(JSON.parse(line));
+            }
+            catch {
+                finish({
+                    ok: false,
+                    error: { code: "failed", message: `serve returned non-JSON: ${line}` },
+                });
+            }
+        });
+        socket.on("connect", () => {
+            socket.write(`${JSON.stringify(payload)}\n`);
+        });
+    });
+}
+export function serveLogonCommand(execPath, scriptPath, listen) {
+    return `"${execPath}" "${scriptPath}" serve --listen ${listen}`;
+}
+function runPowerShell(script) {
+    return new Promise((resolve) => {
+        execFile("powershell.exe", [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-EncodedCommand",
+            encodePowerShellCommand(script),
+        ], { windowsHide: true, timeout: 20_000 }, (error, stdout, stderr) => {
+            const code = error && typeof error.code === "number"
+                ? error.code
+                : error
+                    ? 1
+                    : 0;
+            resolve({
+                code,
+                stdout: String(stdout ?? ""),
+                stderr: String(stderr ?? ""),
+            });
+        });
+    });
+}
+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 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 commandB64 = Buffer.from(command, "utf8").toString("base64");
+    const script = [
+        "$cmd = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('" +
+            commandB64 +
+            "'))",
+        "$action = New-ScheduledTaskAction -Execute 'cmd.exe' -Argument \"/c $cmd\"",
+        "$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive -RunLevel Limited",
+        "$trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME",
+        `Register-ScheduledTask -TaskName '${SERVE_TASK_NAME}' -Action $action -Principal $principal -Trigger $trigger -Force | Out-Null`,
+        `Start-ScheduledTask -TaskName '${SERVE_TASK_NAME}'`,
+    ].join("\n");
+    const result = await runPowerShell(script);
+    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 };
+}
+export async function uninstallServeLogon(input = {}) {
+    if ((input.platform ?? process.platform) !== "win32") {
+        throw new ZellijError("usage", "serve --clear is Windows-only");
+    }
+    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.d.ts

@@ -2,7 +2,7 @@
  * One description of the zswarm surface. The MCP tool schema, the CLI flags,
  * and the CLI help text are all generated from it, so they cannot drift apart.
  */
-export declare const OP_NAMES: readonly ["list", "sessions", "send", "broadcast", "dump", "tail", "wait", "status", "keys", "interrupt", "spawn", "close", "worktrees", "unworktree", "signal", "signals", "await", "log", "rename", "focus", "tabs", "layout", "stack", "diff", "checkpoint", "bus"];
+export declare const OP_NAMES: readonly ["list", "sessions", "send", "broadcast", "dump", "tail", "wait", "status", "keys", "interrupt", "spawn", "close", "worktrees", "unworktree", "signal", "signals", "await", "log", "rename", "focus", "tabs", "layout", "stack", "diff", "checkpoint", "bus", "serve"];
 export type OpName = (typeof OP_NAMES)[number];
 /** Ops that address an existing pane through `to`. */
 export declare const TARGET_OPS: readonly OpName[];

package/dist/schema.js

@@ -30,6 +30,7 @@ export const OP_NAMES = [
     "diff",
     "checkpoint",
     "bus",
+    "serve",
 ];
 /** Ops that address an existing pane through `to`. */
 export const TARGET_OPS = [
@@ -89,13 +90,13 @@ export const PARAMS = [
         name: "clear",
         type: "boolean",
         flags: ["--clear"],
-        description: "signal: reset the channel (all channels when none is given); bus: forget the installed plugin",
+        description: "signal: reset the channel (all channels when none is given); bus: forget the installed plugin; serve: unregister the Windows logon task",
     },
     {
         name: "install",
         type: "boolean",
         flags: ["--install"],
-        description: "bus: load the event-bus plugin in a pane so its permission prompt can be answered, then remember it",
+        description: "bus: load the event-bus plugin in a pane so its permission prompt can be answered, then remember it; serve: register a Windows logon task that listens for remote zswarm",
     },
     {
         name: "reset",
@@ -383,6 +384,12 @@ export const PARAMS = [
         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",
     },
+    {
+        name: "listen",
+        type: "string",
+        flags: ["--listen"],
+        description: "serve: bind address (default 127.0.0.1:9419). Reach it from another machine with ZSWARM_SERVE after an SSH tunnel",
+    },
     {
         name: "verbose",
         type: "boolean",
@@ -424,7 +431,8 @@ export function mcpInputSchema() {
 }
 export const MCP_TOOL_DESCRIPTION = `zSwarm Zellij pane coordination (op=${OP_NAMES.join("|")}). ` +
     "List panes, send text into a CLI pane (paste+Enter), block until a pane goes idle or prints a match, " +
-    "send raw keys, open or close panes, and give a peer its own git worktree. Local Zellij only.";
+    "send raw keys, open or close panes, and give a peer its own git worktree. " +
+    "Same host as Zellij, or ZSWARM_SSH / ZSWARM_SERVE for a remote crew.";
 const FLAG_INDEX = new Map(PARAMS.flatMap((p) => p.flags.map((flag) => [flag, p])));
 export function cliUsage() {
     const lines = [
@@ -439,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/status read pane state from the plugin instead of polling.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN", "");
+    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. */
@@ -457,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/binary.d.ts

@@ -11,6 +11,8 @@ export declare function sanitizeZellijEnv(env: NodeJS.ProcessEnv): NodeJS.Proces
 /**
  * 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_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 resolveSshTarget(env?: NodeJS.ProcessEnv): SshTarget | null;
 /** Runner bound to the resolved zellij binary and a cleaned environment. */

package/dist/zellij/binary.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { createExec, createSshExec, NOT_FOUND_EXIT, } from "../exec.js";
+import { applyIpcTmpEnv } from "./ipc.js";
 export { createSshExec };
 export const DEFAULT_TIMEOUT_MS = 15_000;
 export { NOT_FOUND_EXIT };
@@ -54,9 +55,10 @@ export function resolveZellijBinary(env = process.env) {
     return process.platform === "win32" ? "zellij.exe" : "zellij";
 }
 export function sanitizeZellijEnv(env) {
+    const withTmp = applyIpcTmpEnv(env);
     const out = {};
-    for (const key of Object.keys(env)) {
-        const value = env[key];
+    for (const key of Object.keys(withTmp)) {
+        const value = withTmp[key];
         if (typeof value === "string")
             out[key] = value;
     }
@@ -74,6 +76,8 @@ 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_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 resolveSshTarget(env = process.env) {
     const host = env.ZSWARM_SSH?.trim();
@@ -83,11 +87,19 @@ export function resolveSshTarget(env = process.env) {
     if (!options.some((o) => o.startsWith("BatchMode"))) {
         options.unshift("-o", "BatchMode=yes");
     }
+    const shellRaw = (env.ZSWARM_REMOTE_SHELL ?? "").trim().toLowerCase();
+    const modeRaw = (env.ZSWARM_SSH_MODE ?? "").trim().toLowerCase();
+    const tmpRaw = env.ZSWARM_TMP?.trim();
+    const interactive = modeRaw === "interactive";
     return {
         ssh: env.ZSWARM_SSH_BIN?.trim() || "ssh",
         host,
         remoteBin: env.ZSWARM_REMOTE_BIN?.trim() || "zellij",
         options,
+        // Interactive tasks do not inherit the desktop TEMP; discover it unless set.
+        tmp: tmpRaw || (interactive ? "auto" : undefined),
+        mode: interactive ? "interactive" : "ssh",
+        remoteShell: shellRaw === "cmd" || shellRaw === "sh" ? shellRaw : undefined,
     };
 }
 /** Runner bound to the resolved zellij binary and a cleaned environment. */

package/dist/zellij/ipc.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Zellij keeps its session sockets under TEMP (Windows) / TMPDIR (Unix).
+ * An SSH login on Windows is a different session from the interactive desktop,
+ * so the CLI looks in the wrong directory unless we point it at the live one.
+ * Windows pane attach still uses named pipes in that desktop session — TEMP
+ * is enough to list sessions; `interactive` or `serve` is what can write.
+ */
+/** Drive letter plus rest, or a UNC / posix path. */
+export declare function looksLikeWindowsPath(path: string): boolean;
+/**
+ * `--server C:\Temp\zellij\contract_version_1\crew` → `C:\Temp`.
+ * The session file sits in `…/zellij[-uid]/contract_version_N/<name>`; TEMP is
+ * the parent of that `zellij` directory.
+ */
+export declare function tmpFromServerPath(serverPath: string): string | null;
+/**
+ * Directory Zellij treats as `ZELLIJ_SOCKET_DIR` — the `zellij` / `zellij-<uid>`
+ * folder that contains `contract_version_N`.
+ */
+export declare function socketDirFromServerPath(serverPath: string): string | null;
+export type IpcDirs = {
+    tmp: string;
+    socketDir: string;
+};
+/** Pull every `--server <path>` out of process command lines. */
+export declare function parseZellijServerPaths(commandLines: string): string[];
+/** Majority vote so a stray SSH-session server does not win. */
+export declare function pickIpcDirs(serverPaths: string[]): IpcDirs | null;
+export declare function pickIpcTmp(serverPaths: string[]): string | null;
+export declare function concreteTmp(raw: string | undefined): string | undefined;
+export type RemoteShell = "cmd" | "sh";
+export declare function inferRemoteShell(input: {
+    explicit?: string;
+    tmp?: string;
+    remoteBin?: string;
+    mode?: string;
+}): RemoteShell;
+/** cmd.exe quoting: double quotes, doubled inner quotes. */
+export declare function cmdQuote(arg: string): string;
+export declare function wrapWithTmpEnv(command: string, tmp: string, shell: RemoteShell, socketDir?: string): string;
+/** UTF-16LE base64, which `powershell -EncodedCommand` expects. */
+export declare function encodePowerShellCommand(script: string): string;
+export declare function windowsDiscoverRemote(): string;
+export declare function unixDiscoverRemote(): string;
+/**
+ * Run `innerCmd` (a cmd.exe command line) in the interactive Windows session
+ * via a one-shot `schtasks /IT` job. SSH itself stays in session 0; the task
+ * is what can see the desktop's named pipes.
+ */
+export declare function windowsInteractiveRemote(innerCmd: string, timeoutMs: number): string;
+export declare function applyIpcTmpEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/zellij/ipc.js

@@ -0,0 +1,206 @@
+/**
+ * Zellij keeps its session sockets under TEMP (Windows) / TMPDIR (Unix).
+ * An SSH login on Windows is a different session from the interactive desktop,
+ * so the CLI looks in the wrong directory unless we point it at the live one.
+ * Windows pane attach still uses named pipes in that desktop session — TEMP
+ * is enough to list sessions; `interactive` or `serve` is what can write.
+ */
+/** `…/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+))/;
+/** Drive letter plus rest, or a UNC / posix path. */
+export function looksLikeWindowsPath(path) {
+    return /^[A-Za-z]:[\\/]/.test(path) || path.includes("\\");
+}
+function stripQuotes(path) {
+    return path.trim().replace(/^["']|["']$/g, "");
+}
+/**
+ * `--server C:\Temp\zellij\contract_version_1\crew` → `C:\Temp`.
+ * The session file sits in `…/zellij[-uid]/contract_version_N/<name>`; TEMP is
+ * the parent of that `zellij` directory.
+ */
+export function tmpFromServerPath(serverPath) {
+    const trimmed = stripQuotes(serverPath);
+    if (!trimmed)
+        return null;
+    const match = ZELLIJ_DIR.exec(trimmed);
+    if (!match || match.index <= 0)
+        return null;
+    return trimmed.slice(0, match.index);
+}
+/**
+ * Directory Zellij treats as `ZELLIJ_SOCKET_DIR` — the `zellij` / `zellij-<uid>`
+ * folder that contains `contract_version_N`.
+ */
+export function socketDirFromServerPath(serverPath) {
+    const trimmed = stripQuotes(serverPath);
+    if (!trimmed)
+        return null;
+    const match = ZELLIJ_DIR.exec(trimmed);
+    if (!match || match.index < 0)
+        return null;
+    const name = match[1];
+    if (!name)
+        return null;
+    return trimmed.slice(0, match.index + 1 + name.length);
+}
+/** Pull every `--server <path>` out of process command lines. */
+export function parseZellijServerPaths(commandLines) {
+    const found = [];
+    for (const line of commandLines.split(/\r?\n/)) {
+        const match = SERVER_FLAG.exec(line);
+        const captured = match?.[1] || match?.[2] || match?.[3];
+        if (captured)
+            found.push(stripQuotes(captured));
+    }
+    return found;
+}
+/** Majority vote so a stray SSH-session server does not win. */
+export function pickIpcDirs(serverPaths) {
+    const counts = new Map();
+    for (const server of serverPaths) {
+        const tmp = tmpFromServerPath(server);
+        const socketDir = socketDirFromServerPath(server);
+        if (!tmp || !socketDir)
+            continue;
+        const prev = counts.get(tmp);
+        if (prev)
+            prev.count += 1;
+        else
+            counts.set(tmp, { count: 1, socketDir });
+    }
+    let best = null;
+    let bestCount = 0;
+    for (const [tmp, { count, socketDir }] of counts) {
+        if (count > bestCount) {
+            best = { tmp, socketDir };
+            bestCount = count;
+        }
+    }
+    return best;
+}
+export function pickIpcTmp(serverPaths) {
+    return pickIpcDirs(serverPaths)?.tmp ?? null;
+}
+export function concreteTmp(raw) {
+    const trimmed = raw?.trim();
+    if (!trimmed || trimmed.toLowerCase() === "auto")
+        return undefined;
+    return trimmed;
+}
+export function inferRemoteShell(input) {
+    const explicit = input.explicit?.trim().toLowerCase();
+    if (explicit === "cmd" || explicit === "sh")
+        return explicit;
+    if (input.mode === "interactive")
+        return "cmd";
+    if (input.remoteBin && /\.exe$/i.test(input.remoteBin))
+        return "cmd";
+    if (input.tmp && looksLikeWindowsPath(input.tmp))
+        return "cmd";
+    return "sh";
+}
+/** cmd.exe quoting: double quotes, doubled inner quotes. */
+export function cmdQuote(arg) {
+    if (arg === "")
+        return '""';
+    // 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")
+        return undefined;
+    return tmp.replace(/[\\/]+$/, "") + "\\zellij";
+}
+export function wrapWithTmpEnv(command, tmp, shell, socketDir) {
+    const sock = socketDir || defaultSocketDir(tmp, shell);
+    if (shell === "cmd") {
+        let prefix = `set "TEMP=${tmp}" && set "TMP=${tmp}"`;
+        if (sock)
+            prefix += ` && set "ZELLIJ_SOCKET_DIR=${sock}"`;
+        return `${prefix} && ${command}`;
+    }
+    const q = tmp.replace(/'/g, `'\\''`);
+    let prefix = `TMPDIR='${q}' TEMP='${q}' TMP='${q}'`;
+    if (sock) {
+        const sq = sock.replace(/'/g, `'\\''`);
+        prefix += ` ZELLIJ_SOCKET_DIR='${sq}'`;
+    }
+    return `${prefix} ${command}`;
+}
+const WINDOWS_DISCOVER_PS = "Get-CimInstance Win32_Process -Filter \"Name='zellij.exe'\" | ForEach-Object { $_.CommandLine }";
+/** UTF-16LE base64, which `powershell -EncodedCommand` expects. */
+export function encodePowerShellCommand(script) {
+    return Buffer.from(script, "utf16le").toString("base64");
+}
+export function windowsDiscoverRemote() {
+    return `powershell.exe -NoProfile -EncodedCommand ${encodePowerShellCommand(WINDOWS_DISCOVER_PS)}`;
+}
+export function unixDiscoverRemote() {
+    return "ps ax -o args=";
+}
+/**
+ * Run `innerCmd` (a cmd.exe command line) in the interactive Windows session
+ * via a one-shot `schtasks /IT` job. SSH itself stays in session 0; the task
+ * is what can see the desktop's named pipes.
+ */
+export function windowsInteractiveRemote(innerCmd, timeoutMs) {
+    const innerB64 = Buffer.from(innerCmd, "utf8").toString("base64");
+    const waitMs = Math.max(1000, timeoutMs - 2000);
+    const script = [
+        "$ProgressPreference = 'SilentlyContinue'",
+        "$inner = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('" +
+            innerB64 +
+            "'))",
+        "$id = [guid]::NewGuid().ToString('n').Substring(0,8)",
+        "$task = \"zswarm-$id\"",
+        "$dir = Join-Path $env:LOCALAPPDATA 'Temp'",
+        "New-Item -ItemType Directory -Force -Path $dir | Out-Null",
+        "$bat = Join-Path $dir \"zswarm-$id.bat\"",
+        "$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`\"\"",
+        ")",
+        "[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) {",
+        "    [Console]::Error.Write(($create | Out-String).Trim())",
+        "    exit 1",
+        "  }",
+        "  # schtasks /Run ignores /IT and stays in session 0. Start-ScheduledTask honours it.",
+        "  Start-ScheduledTask -TaskName $task",
+        "  $deadline = (Get-Date).AddMilliseconds(" + waitMs + ")",
+        "  do { Start-Sleep -Milliseconds 200 } while (-not (Test-Path $code) -and (Get-Date) -lt $deadline)",
+        "  if (Test-Path $out) { [Console]::Out.Write([IO.File]::ReadAllText($out)) }",
+        "  if (Test-Path $err) { [Console]::Error.Write([IO.File]::ReadAllText($err)) }",
+        "  if (Test-Path $code) { exit [int](((Get-Content $code -TotalCount 1) | Out-String).Trim()) }",
+        "  [Console]::Error.Write('zswarm: interactive task produced no exit code; is a desktop session logged on?')",
+        "  exit 1",
+        "} finally {",
+        "  & schtasks.exe /Delete /TN $task /F 2>&1 | Out-Null",
+        "  Remove-Item $bat,$out,$err,$code -Force -ErrorAction SilentlyContinue",
+        "}",
+    ].join("\n");
+    return `powershell.exe -NoProfile -ExecutionPolicy Bypass -EncodedCommand ${encodePowerShellCommand(script)}`;
+}
+export function applyIpcTmpEnv(env) {
+    const tmp = concreteTmp(env.ZSWARM_TMP);
+    if (!tmp)
+        return env;
+    const out = { ...env, TEMP: tmp, TMP: tmp, TMPDIR: tmp };
+    const sock = defaultSocketDir(tmp, looksLikeWindowsPath(tmp) ? "cmd" : "sh");
+    if (sock)
+        out.ZELLIJ_SOCKET_DIR = sock;
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.1.1",
+  "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",