@zswarm/core 0.1.0 → 0.1.2

package/dist/exec.d.ts

@@ -1,3 +1,4 @@
+import { type RemoteShell } from "./zellij/ipc.js";
 export type ExecResult = {
     code: number;
     stdout: string;
@@ -23,7 +24,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,75 @@ 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 !== undefined)
+            return cached ?? undefined;
+        cached = (await discoverRemoteIpc(runner, target, timeoutMs)) ?? null;
+        return cached ?? undefined;
+    }
+    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);
     };
 }

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, parseListenAddress, 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, parseListenAddress, 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/bus.d.ts

@@ -23,6 +23,7 @@ export declare function planBus(client: ZellijClient, state: StateStore, env?: N
  * message and replies with nothing, so each attempt rotates to a new key. And a
  * freshly launched instance replies before Zellij has pushed it a manifest, so
  * a not-ready answer is retried once rather than reported as an empty session.
+ * If it is still cold after that, one same-title rename nudges Zellij to push.
  */
 export declare function busSnapshot(client: ZellijClient, state: StateStore, session: string, clock: Clock, env?: NodeJS.ProcessEnv, payload?: string): Promise<{
     snapshot: BusSnapshot;

package/dist/ops/bus.js

@@ -53,7 +53,7 @@ export function planBus(client, state, env = process.env) {
     if (!plugin) {
         return {
             ...base,
-            reason: "no plugin wasm found; build plugin/zswarm-events or set ZSWARM_BUS_PLUGIN",
+            reason: "no plugin wasm found; run pnpm build:plugin or set ZSWARM_BUS_PLUGIN",
         };
     }
     if (processDisabled)
@@ -69,6 +69,19 @@ async function askOnce(client, session, url, configKey, payload) {
     const result = await client.pipePlugin({ session, url, configKey, payload });
     return parseBusReply(result.stdout);
 }
+/**
+ * Zellij pushes a pane manifest on change, never on subscribe — there is no
+ * get_pane_manifest(). A quiet session leaves a freshly launched instance
+ * blind (ready:false, paneUpdates:0) until something moves. Renaming a pane
+ * to the title it already has is an invisible change that forces the push.
+ */
+async function nudgeManifest(client, session) {
+    const panes = await client.listPanes(session);
+    const pane = panes.find((p) => !p.isPlugin && !p.exited && p.title.trim());
+    if (!pane)
+        return;
+    await client.renamePane({ session, paneId: pane.id, name: pane.title });
+}
 /**
  * One pipe, one answer — or null, and the caller polls instead.
  *
@@ -76,6 +89,7 @@ async function askOnce(client, session, url, configKey, payload) {
  * message and replies with nothing, so each attempt rotates to a new key. And a
  * freshly launched instance replies before Zellij has pushed it a manifest, so
  * a not-ready answer is retried once rather than reported as an empty session.
+ * If it is still cold after that, one same-title rename nudges Zellij to push.
  */
 export async function busSnapshot(client, state, session, clock, env = process.env, payload = "status") {
     const plan = planBus(client, state, env);
@@ -83,6 +97,7 @@ export async function busSnapshot(client, state, session, clock, env = process.e
     if (!plan.enabled || !plan.url || !pluginPath)
         return null;
     let configKey = answeredWith.get(session) ?? plan.configKey;
+    let nudged = false;
     for (let attempt = 0; attempt < MAX_KEY_ATTEMPTS; attempt++) {
         let snapshot = await askOnce(client, session, plan.url, configKey, payload);
         if (snapshot && !snapshot.ready) {
@@ -91,6 +106,18 @@ export async function busSnapshot(client, state, session, clock, env = process.e
                 (await askOnce(client, session, plan.url, configKey, payload)) ??
                     snapshot;
         }
+        if (snapshot && !snapshot.ready && !nudged) {
+            nudged = true;
+            try {
+                await nudgeManifest(client, session);
+                snapshot =
+                    (await askOnce(client, session, plan.url, configKey, payload)) ??
+                        snapshot;
+            }
+            catch {
+                // A failed nudge must not fail the op — the caller polls instead.
+            }
+        }
         if (snapshot) {
             answeredWith.set(session, configKey);
             if (plan.installed && configKey !== plan.configKey) {
@@ -205,7 +232,7 @@ export async function busOp(client, state, args, clock, env = process.env, polic
         }
         const plugin = resolveBusPlugin(env);
         if (!plugin) {
-            throw new ZellijError("bus_missing", "no plugin wasm found; build plugin/zswarm-events or set ZSWARM_BUS_PLUGIN");
+            throw new ZellijError("bus_missing", "no plugin wasm found; run pnpm build:plugin or set ZSWARM_BUS_PLUGIN");
         }
         const previous = state.readBus();
         const force = isTrue(args.force);

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

@@ -20,6 +20,7 @@ import { OP_NAMES } from "../schema.js";
 import { dumpMaxChars, fail, isTrue, isVerbose, 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() : "";
@@ -57,7 +58,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 +72,31 @@ 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);
+        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));
+        }
+        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,39 @@
+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";
+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. */
+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<{
+    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): 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,197 @@
+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";
+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(":")
+            ? 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) {
+        throw new ZellijError("bad_arg", `listen address is not host:port (${text})`);
+    }
+    return { host, port, label: `${host}:${port}` };
+}
+/** Client-side wait: the op's own timeout plus slack, capped at ten minutes. */
+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);
+}
+/** 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;
+}
+export function startServe(listen, dispatch) {
+    const { host, port } = parseListenAddress(listen);
+    return new Promise((resolve, reject) => {
+        const server = createServer((socket) => {
+            let buf = "";
+            socket.setEncoding("utf8");
+            socket.on("data", (chunk) => {
+                buf += chunk;
+                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 args = JSON.parse(line);
+                            result = await dispatch(args);
+                        }
+                        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: `${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) {
+    const { host, port } = parseServeTarget(target);
+    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(args)}\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 = `Unregister-ScheduledTask -TaskName '${SERVE_TASK_NAME}' -Confirm:$false -ErrorAction SilentlyContinue`;
+    await runPowerShell(script);
+    return { task: SERVE_TASK_NAME, cleared: true };
+}

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[];
@@ -22,5 +22,4 @@ export declare const PARAMS: readonly ParamSpec[];
 export declare function mcpInputSchema(): Record<string, unknown>;
 export declare const MCP_TOOL_DESCRIPTION: string;
 export declare function cliUsage(): string;
-/** Turn argv (without the op) into dispatch args, driven by PARAMS. */
 export declare function parseCliArgv(argv: string[]): Record<string, unknown>;

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,12 +447,31 @@ 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.", "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", "");
     return lines.join("\n");
 }
 /** Turn argv (without the op) into dispatch args, driven by PARAMS. */
+/**
+ * Pull the op out of argv, tolerating flags before it.
+ *
+ * The op normally comes first. When it does not — `zswarm --session crew list`
+ * — the first token is a flag, and taking argv[0] blindly reported the flag as
+ * an unknown op. Only positions that already errored are affected: if argv[0]
+ * is a real op it wins, so `send reviewer list` still sends the word "list".
+ */
+function extractOp(argv) {
+    const first = argv[0];
+    if (first && !first.startsWith("-")) {
+        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)] };
+}
 export function parseCliArgv(argv) {
-    const [op, ...rest] = argv;
+    const { op, rest } = extractOp(argv);
     if (!op)
         throw new ZellijError("usage", "no op given");
     const out = { op };

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,200 @@
+/**
+ * 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);
+        if (match?.[1])
+            found.push(stripQuotes(match[1]));
+    }
+    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 '""';
+    if (/^[A-Za-z0-9_@%+=:,.\\/-]+$/.test(arg))
+        return arg;
+    return `"${arg.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\"",
+        "@(",
+        "  '@echo off'",
+        "  \"$inner > `\"$out`\" 2> `\"$err`\"\"",
+        "  \"echo %ERRORLEVEL% > `\"$code`\"\"",
+        ") | Set-Content -Path $bat -Encoding ASCII",
+        "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.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {
@@ -29,6 +29,6 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "pnpm run build && node --test tests/*.test.mjs"
+    "test": "pnpm run build && node --test"
   }
 }