@zswarm/core 0.1.6 → 0.1.8

package/README.md

@@ -30,6 +30,14 @@ const result = await dispatchZswarm({ op: "list" });
 `{ ok, data }` or `{ ok: false, error }`, with routing `context` once the
 invocation's destination is known.
 
+`ZSWARM_SERVE` / `--serve` may be `host:port`, `tcp://host:port`, or
+`ssh://user@host[:sshPort]?servePort=9419`. The ssh URI opens a process-owned
+SSH LocalForward and calls `probeServe` before ops (including before reuse);
+pass a `serveTunnels` manager if the caller (MCP) should reuse it. Omitting
+the SSH port leaves `Port` to OpenSSH instead of forcing 22. `tcp://` also
+names a private Tailscale Serve frontend over a loopback backend; see
+[Tailscale crew](../../docs/tailscale.md).
+
 Spawn lifecycle, body files, guarded keys, status tabs and routing context: [crew operations](../../docs/crew-operations.md).
 
 Ops, env, and the event bus: the [zswarm README](../../README.md).

package/dist/errors.d.ts

@@ -1,5 +1,6 @@
 /** Every zSwarm failure carries a stable machine-readable code. */
 export declare class ZellijError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
 }

package/dist/errors.js

@@ -1,9 +1,12 @@
 /** Every zSwarm failure carries a stable machine-readable code. */
 export class ZellijError extends Error {
     code;
-    constructor(code, message) {
+    details;
+    constructor(code, message, details) {
         super(message);
         this.name = "ZellijError";
         this.code = code;
+        if (details && Object.keys(details).length > 0)
+            this.details = details;
     }
 }

package/dist/exec.d.ts

@@ -1,8 +1,16 @@
-import { type RemoteShell } from "./zellij/ipc.js";
+import { type IpcDirs, type RemoteShell } from "./zellij/ipc.js";
+export type ExecSpawnFailure = {
+    /** Node could not start this process. Distinct from a remote 127. */
+    origin: "local";
+    errno: string;
+    bin: string;
+};
 export type ExecResult = {
     code: number;
     stdout: string;
     stderr: string;
+    /** Present only when this host failed to spawn the binary. */
+    spawn?: ExecSpawnFailure;
 };
 export type ExecOptions = {
     timeoutMs: number;
@@ -49,10 +57,44 @@ export type IpcDiscoveryState = {
 };
 export type SshExecFn = ExecFn & {
     ipcState: IpcDiscoveryState;
+    /**
+     * Resolve `ZSWARM_TMP=auto` once under this caller's budget before parallel
+     * identity/capability probes. Independent of other callers' in-flight work.
+     */
+    prepareIpc: (timeoutMs: number, signal?: AbortSignal) => Promise<IpcDirs | undefined>;
 };
+/** Positive `auto` IPC hits only; failures/cancels never enter this map. */
+export declare const DEFAULT_IPC_DISCOVERY_TTL_MS = 15000;
+export declare const DEFAULT_IPC_DISCOVERY_CACHE_LIMIT = 512;
+/** Fully scoped key so hosts / SSH bins / remote shells / users never collide. */
+export declare function ipcDiscoveryCacheKey(target: SshTarget, env?: NodeJS.ProcessEnv): string;
+/**
+ * Probe list for `ZSWARM_TMP=auto`. Known Windows (cmd / interactive / .exe)
+ * skips the Unix `ps` fallback; explicit `sh` skips PowerShell. Unknown
+ * `zellij` still tries both — a Windows host with remoteBin=zellij looks Unix.
+ */
+export declare function ipcDiscoveryProbes(target: SshTarget): string[];
+export declare function resetIpcDiscoveryCache(): void;
+/** Test helper: shrink the positive-hit TTL without exposing the map. */
+export declare function setIpcDiscoveryTtlMs(ttlMs: number): void;
+export declare function peekIpcDiscoveryCache(key: string): IpcDirs | undefined;
+/**
+ * Canonical SSH + resolved IPC namespace. Listing caches should hash this
+ * (or `ipcState.tmp` / `socketDir` after a refreshed read) so a warmed
+ * socket context matches across `createSshExec` instances.
+ */
+export declare function sshIpcContextKey(target: SshTarget, env?: NodeJS.ProcessEnv, ipc?: {
+    tmp?: string;
+    socketDir?: string;
+} | null): string;
+/** Test helper: shrink the positive-hit map so eviction is observable. */
+export declare function setIpcDiscoveryCacheLimit(limit: number): void;
+export declare function ipcDiscoveryCacheSize(): number;
 /**
  * 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 declare function createSshExec(target: SshTarget, env: NodeJS.ProcessEnv): SshExecFn;
+export declare function createSshExec(target: SshTarget, env: NodeJS.ProcessEnv, options?: {
+    pinIpc?: boolean;
+}): SshExecFn;
 export declare function createExec(binPath: string, env: NodeJS.ProcessEnv): ExecFn;

package/dist/exec.js

@@ -1,6 +1,16 @@
 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;
+function localSpawnResult(err, binPath) {
+    const errno = typeof err.code === "string" && err.code ? err.code : "error";
+    const missing = errno === "ENOENT" || errno === "ENOTDIR";
+    return {
+        code: missing ? NOT_FOUND_EXIT : 1,
+        stdout: "",
+        stderr: `${errno}: ${err.message} (bin=${binPath})`,
+        spawn: { origin: "local", errno, bin: binPath },
+    };
+}
 /** POSIX single-quoting, for building a command line the remote shell parses. */
 export function shellQuote(arg) {
     if (arg === "")
@@ -35,17 +45,104 @@ export function buildSshRemoteCommand(target, args, tmp, timeoutMs, socketDir) {
     }
     return withTmp;
 }
-async function discoverRemoteIpc(runner, target, remaining, signal) {
+/** Positive `auto` IPC hits only; failures/cancels never enter this map. */
+export const DEFAULT_IPC_DISCOVERY_TTL_MS = 15_000;
+export const DEFAULT_IPC_DISCOVERY_CACHE_LIMIT = 512;
+const ipcDiscoveryCache = new Map();
+let ipcDiscoveryTtlMs = DEFAULT_IPC_DISCOVERY_TTL_MS;
+let ipcDiscoveryCacheLimit = DEFAULT_IPC_DISCOVERY_CACHE_LIMIT;
+const IPC_USER_ENV = [
+    "USER",
+    "USERNAME",
+    "LOGNAME",
+    "HOME",
+    "USERPROFILE",
+    "USERDOMAIN",
+    "SSH_AUTH_SOCK",
+    "PATH",
+    "Path",
+    "XDG_CONFIG_HOME",
+];
+/** Fully scoped key so hosts / SSH bins / remote shells / users never collide. */
+export function ipcDiscoveryCacheKey(target, env = {}) {
+    const requested = target.tmp?.trim() ?? "";
+    const user = IPC_USER_ENV.map((name) => env[name] ?? "");
+    return JSON.stringify([
+        target.ssh,
+        target.host,
+        target.options,
+        target.remoteBin,
+        target.remoteShell ?? "",
+        target.mode ?? "ssh",
+        requested.toLowerCase() === "auto" ? "auto" : requested,
+        user,
+    ]);
+}
+/**
+ * Probe list for `ZSWARM_TMP=auto`. Known Windows (cmd / interactive / .exe)
+ * skips the Unix `ps` fallback; explicit `sh` skips PowerShell. Unknown
+ * `zellij` still tries both — a Windows host with remoteBin=zellij looks Unix.
+ */
+export function ipcDiscoveryProbes(target) {
     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()];
+    const windows = windowsDiscoverRemote();
+    const unix = unixDiscoverRemote();
+    if (shell === "cmd")
+        return [windows];
+    if (target.remoteShell === "sh")
+        return [unix];
+    return [unix, windows];
+}
+export function resetIpcDiscoveryCache() {
+    ipcDiscoveryCache.clear();
+    ipcDiscoveryTtlMs = DEFAULT_IPC_DISCOVERY_TTL_MS;
+    ipcDiscoveryCacheLimit = DEFAULT_IPC_DISCOVERY_CACHE_LIMIT;
+}
+/** Test helper: shrink the positive-hit TTL without exposing the map. */
+export function setIpcDiscoveryTtlMs(ttlMs) {
+    ipcDiscoveryTtlMs = Math.max(0, ttlMs);
+}
+export function peekIpcDiscoveryCache(key) {
+    const entry = ipcDiscoveryCache.get(key);
+    if (!entry)
+        return undefined;
+    if (entry.expiresAt <= Date.now()) {
+        ipcDiscoveryCache.delete(key);
+        return undefined;
+    }
+    return { tmp: entry.dirs.tmp, socketDir: entry.dirs.socketDir };
+}
+/**
+ * Canonical SSH + resolved IPC namespace. Listing caches should hash this
+ * (or `ipcState.tmp` / `socketDir` after a refreshed read) so a warmed
+ * socket context matches across `createSshExec` instances.
+ */
+export function sshIpcContextKey(target, env = {}, ipc) {
+    return JSON.stringify([ipcDiscoveryCacheKey(target, env), ipc?.tmp ?? "", ipc?.socketDir ?? ""]);
+}
+/** Test helper: shrink the positive-hit map so eviction is observable. */
+export function setIpcDiscoveryCacheLimit(limit) {
+    ipcDiscoveryCacheLimit = Math.max(1, limit);
+}
+export function ipcDiscoveryCacheSize() {
+    return ipcDiscoveryCache.size;
+}
+function storeIpcDiscovery(key, dirs) {
+    ipcDiscoveryCache.delete(key);
+    ipcDiscoveryCache.set(key, {
+        dirs: { ...dirs },
+        expiresAt: Date.now() + ipcDiscoveryTtlMs,
+    });
+    while (ipcDiscoveryCache.size > ipcDiscoveryCacheLimit) {
+        ipcDiscoveryCache.delete(ipcDiscoveryCache.keys().next().value);
+    }
+}
+async function discoverRemoteIpc(runner, target, remaining, signal) {
+    const probes = ipcDiscoveryProbes(target);
     for (const probe of probes) {
         if (signal?.aborted)
             return undefined;
@@ -56,6 +153,10 @@ async function discoverRemoteIpc(runner, target, remaining, signal) {
             timeoutMs: left,
             signal,
         });
+        if (result.code !== 0)
+            continue;
+        if (remaining() <= 0)
+            return undefined;
         const dirs = pickIpcDirs(parseZellijServerPaths(result.stdout));
         if (dirs)
             return dirs;
@@ -66,22 +167,63 @@ async function discoverRemoteIpc(runner, target, remaining, signal) {
  * 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) {
+export function createSshExec(target, env, options = {}) {
     const runner = createExec(target.ssh, env);
-    let cached;
-    let autoAttempted = false;
-    const requestedTmp = target.tmp?.trim() || null;
+    const cacheKey = ipcDiscoveryCacheKey(target, env);
+    let autoFailed = false;
+    let pinnedIpc;
     const ipcState = {
-        requested: requestedTmp,
-        status: !requestedTmp
-            ? "none"
-            : requestedTmp.toLowerCase() === "auto"
-                ? "none"
-                : "skipped",
-        ...(requestedTmp && requestedTmp.toLowerCase() !== "auto"
-            ? { tmp: requestedTmp, socketDir: "" }
-            : {}),
+        requested: null,
+        status: "none",
     };
+    function adopt(dirs) {
+        if (options.pinIpc) {
+            pinnedIpc ??= { ...dirs };
+            dirs = pinnedIpc;
+        }
+        autoFailed = false;
+        ipcState.status = "resolved";
+        ipcState.tmp = dirs.tmp;
+        ipcState.socketDir = dirs.socketDir;
+        return { ...dirs };
+    }
+    /** Seed from a positive hit; unpinned execs drop resolved dirs after TTL. */
+    function refreshIpcView() {
+        const requested = target.tmp?.trim() || null;
+        ipcState.requested = requested;
+        if (!requested) {
+            ipcState.status = "none";
+            delete ipcState.tmp;
+            delete ipcState.socketDir;
+            return ipcState;
+        }
+        if (requested.toLowerCase() !== "auto") {
+            ipcState.status = "skipped";
+            ipcState.tmp = requested;
+            ipcState.socketDir = "";
+            return ipcState;
+        }
+        // A high-level client pins its namespace so pane lookup and the following
+        // write cannot switch sockets when another caller refreshes discovery.
+        if (pinnedIpc)
+            return ipcState;
+        // Diagnostics describe this exec's last attempt, not a sibling's later
+        // success. A subsequent actual invocation may adopt a positive cache hit.
+        if (autoFailed)
+            return ipcState;
+        const cached = peekIpcDiscoveryCache(cacheKey);
+        if (cached) {
+            adopt(cached);
+            return ipcState;
+        }
+        if (ipcState.status === "resolved") {
+            ipcState.status = "none";
+            delete ipcState.tmp;
+            delete ipcState.socketDir;
+        }
+        return ipcState;
+    }
+    refreshIpcView();
     async function resolveIpc(remaining, signal) {
         const requested = target.tmp?.trim();
         if (!requested) {
@@ -96,40 +238,50 @@ export function createSshExec(target, env) {
             ipcState.socketDir = "";
             return { tmp: requested, socketDir: "" };
         }
-        if (cached) {
-            ipcState.status = "resolved";
-            ipcState.tmp = cached.tmp;
-            ipcState.socketDir = cached.socketDir;
-            return cached;
-        }
+        if (pinnedIpc)
+            return adopt(pinnedIpc);
+        const cached = peekIpcDiscoveryCache(cacheKey);
+        if (cached)
+            return adopt(cached);
         // Do not re-probe after a failed/expired/cancelled attempt on this exec.
-        if (autoAttempted)
+        // A later createSshExec with the same key still probes — failures are not
+        // stored, and in-flight work is never shared across callers' budgets.
+        if (autoFailed)
             return undefined;
         if (signal?.aborted) {
+            autoFailed = true;
             ipcState.status = "cancelled";
             return undefined;
         }
         if (remaining() <= 0) {
+            autoFailed = true;
             ipcState.status = "expired";
             return undefined;
         }
-        autoAttempted = true;
         const dirs = await discoverRemoteIpc(runner, target, remaining, signal);
+        // Another probe on this client may have pinned a namespace while we were
+        // waiting. Its first positive result wins, even if this probe failed.
+        if (pinnedIpc)
+            return adopt(pinnedIpc);
         if (signal?.aborted) {
+            autoFailed = true;
             ipcState.status = "cancelled";
             return undefined;
         }
         if (dirs) {
-            cached = dirs;
-            ipcState.status = "resolved";
-            ipcState.tmp = dirs.tmp;
-            ipcState.socketDir = dirs.socketDir;
-            return dirs;
+            if (remaining() <= 0) {
+                autoFailed = true;
+                ipcState.status = "expired";
+                return undefined;
+            }
+            storeIpcDiscovery(cacheKey, dirs);
+            return adopt(dirs);
         }
+        autoFailed = true;
         ipcState.status = remaining() <= 0 ? "expired" : "failed";
         return undefined;
     }
-    const exec = async (args, options) => {
+    const exec = (async (args, options) => {
         const deadline = Date.now() + options.timeoutMs;
         const remaining = () => Math.max(0, deadline - Date.now());
         const ipc = await resolveIpc(remaining, options.signal);
@@ -156,8 +308,18 @@ export function createSshExec(target, env) {
             ...options,
             timeoutMs: left,
         });
+    });
+    Object.defineProperty(exec, "ipcState", {
+        enumerable: true,
+        configurable: true,
+        get() {
+            return { ...refreshIpcView() };
+        },
+    });
+    exec.prepareIpc = (timeoutMs, signal) => {
+        const deadline = Date.now() + timeoutMs;
+        return resolveIpc(() => Math.max(0, deadline - Date.now()), signal);
     };
-    exec.ipcState = ipcState;
     return exec;
 }
 /** Read stdout until the answer is in hand, then stop caring about the child. */
@@ -197,12 +359,7 @@ function runUntil(binPath, args, env, options) {
         }
         options.signal?.addEventListener("abort", onAbort, { once: true });
         child.on("error", (err) => {
-            const missing = err.code === "ENOENT" || err.code === "ENOTDIR";
-            finish({
-                code: missing ? NOT_FOUND_EXIT : 1,
-                stdout: "",
-                stderr: `${err.code ?? "error"}: ${err.message} (bin=${binPath})`,
-            });
+            finish(localSpawnResult(err, binPath));
         });
         child.stdout.on("data", (chunk) => {
             stdout += chunk.toString();
@@ -231,12 +388,7 @@ function runToExit(binPath, args, env, options) {
         }, (error, stdout, stderr) => {
             const failure = error;
             if (failure && typeof failure.code === "string") {
-                const missing = failure.code === "ENOENT" || failure.code === "ENOTDIR";
-                resolve({
-                    code: missing ? NOT_FOUND_EXIT : 1,
-                    stdout: "",
-                    stderr: `${failure.code}: ${failure.message} (bin=${binPath})`,
-                });
+                resolve(localSpawnResult(failure, binPath));
                 return;
             }
             if (failure &&

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { ZellijError } from "./errors.js";
+export { ListingCache } from "./zellij/cache.js";
 export { createExec, NOT_FOUND_EXIT, type ExecFn, type ExecOptions, type ExecResult, } from "./exec.js";
 export { createGitClient, defaultWorktreeRoot, normalizeRepoPath, parseWorktreeList, worktreeDirName, type GitClient, type GitClientOptions, type Worktree, } from "./git.js";
 export { expandHomePath, looksLikeZswarmBinary, isZellijVersionOutput, resolveZellijBinary, resetZellijIdentityCache, sanitizeZellijEnv, validateSshDestination, validateSshMode, type ZellijExecFn, type ZellijExecResult, } from "./zellij/binary.js";
@@ -14,13 +15,17 @@ export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, type Policy,
 export { buildSshRemoteCommand, createSshExec, quoteRemoteArg, shellQuote, type IpcDiscoveryState, type SshExecFn, 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, redactServeSecret, SERVE_CALL_TIMEOUT_CAP_MS, SERVE_MAX_REQUEST_BYTES, SERVE_TASK_NAME, serveCallTimeout, serveChildEnv, serveLogonCommand, startServe, uninstallServeLogon, } from "./ops/serve.js";
+export { callServe, DEFAULT_SERVE_LISTEN, isLoopbackHost, parseListenAddress, probeServe, redactServeSecret, SERVE_CALL_TIMEOUT_CAP_MS, SERVE_CAPABILITY_HELLO, SERVE_CONNECT_TIMEOUT_MS, SERVE_CONTROL_FIELD, SERVE_HELLO_CONTROL, SERVE_HELLO_TIMEOUT_MS, SERVE_CORE_VERSION, SERVE_LAUNCH_ID_ENV, SERVE_MAX_HELLO_BYTES, SERVE_MAX_REPLY_BYTES, SERVE_MAX_REQUEST_BYTES, SERVE_CAPTURE_BUDGET_BYTES, SERVE_PROTOCOL, SERVE_REMEDY, SERVE_TASK_NAME, serveCallTimeout, serveChildEnv, serveLogonCommand, serveMaxReplyBytes, startServe, type CallServeOptions, type ProbeServeOptions, type ServeCapability, type ServeDelivery, type ServeErrorDetails, type ServeHelloData, type ServePhase, type StartServeOptions, } from "./ops/serve.js";
+export { authorizeServeListen, canonicalizeListenIp, expandIPv6, sameCanonicalIp, SERVE_BIND_REMEDY, SERVE_BIND_STATUS_MAX_BYTES, SERVE_BIND_VERIFY_TIMEOUT_MS, SERVE_TAILSCALE_BIN_ENV, type ServeBindAuthorization, type ServeBindDeps, } from "./ops/serve-bind.js";
+export { buildServeTaskScript, DEFAULT_SERVE_INSTALL_TIMEOUT_MS, installServeLogon, looksLikeCliEntrypoint, looksLikeMcpEntrypoint, resolveServeCliLaunch, sameWindowsAccount, sameWindowsSid, SERVE_NOT_READY_CODE, SERVE_TASK_OWNED_CODE, serveCommandFingerprint, serveTaskChildEnv, serveTaskLaunchEnv, uninstallServeLogon, type ServeCliLaunch, type ServeInstallInput, type ServeInstallSuccess, type ServeTaskAction, } from "./ops/serve-install.js";
+export { allocateLoopbackPort, assertSafeSshTunnelOpts, buildSshTunnelArgv, createServeTunnelManager, DEFAULT_SSH_PORT, DEFAULT_SSH_SERVE_PORT, describeServeTarget, formatSshServeTarget, forwardServe, isSshServeTarget, parseSshServeTarget, redactSshUserinfo, serveTunnelCacheKey, SSH_SERVE_REMOTE_HOST, SSH_TUNNEL_KEEPALIVE_COUNT, SSH_TUNNEL_KEEPALIVE_INTERVAL_S, stripControllerRouting, type AcquireServeTunnelOptions, type ParsedSshServeTarget, type ServeTunnelHandle, type ServeTunnelManager, type ServeTunnelManagerOptions, } from "./ops/serve-tunnel.js";
 export { parseTabList, resolveTab, type ZellijTab } from "./zellij/tabs.js";
 export { selectTargets } from "./ops/broadcast.js";
 export { diffScreens, cursorKey } from "./ops/tail.js";
 export { classify, lastLine, mapPool, peerStatus, DEFAULT_STATUS_TIMEOUT_MS, STATUS_DUMP_CONCURRENCY, type PeerState, } from "./ops/status.js";
 export { normalizeScreen, truncateDumpText, DEFAULT_DUMP_MAX_CHARS, DEFAULT_WAIT_MAX_CHARS, } from "./ops/util.js";
 export type { RoutingContext } from "./ops/routing.js";
-export type { DispatchDeps, OpsResult } from "./ops/types.js";
+export type { DispatchDeps, OpsResult, ServeInstallDeps } from "./ops/types.js";
+export { DEFAULT_DOCTOR_TIMEOUT_MS, DOCTOR_FAILED_CODE, DOCTOR_SCOPE_FIELD, DOCTOR_SCOPE_HOST, DOCTOR_TAILSCALE_MAX_MS, HOST_REPORT_INCOMPLETE_CODE, HOST_REPORT_INVALID_CODE, doctorOp, inspectDoctorHost, coverHostReport, hostDoctorRequest, isRequiredFailure, mergeHostReply, type DoctorCheck, type DoctorCheckScope, type DoctorCheckState, type DoctorReport, type DoctorRoute, type HostInspectInput, } from "./ops/doctor.js";
 export { normalizeKey, normalizeKeys, tokenizeCommand } from "./keys.js";
 export { cliUsage, mcpInputSchema, parseCliArgv, MCP_TOOL_DESCRIPTION, OP_NAMES, PARAMS, TARGET_OPS, type OpName, type ParamSpec, type ParamType, } from "./schema.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { ZellijError } from "./errors.js";
+export { ListingCache } from "./zellij/cache.js";
 export { createExec, NOT_FOUND_EXIT, } from "./exec.js";
 export { createGitClient, defaultWorktreeRoot, normalizeRepoPath, parseWorktreeList, worktreeDirName, } from "./git.js";
 export { expandHomePath, looksLikeZswarmBinary, isZellijVersionOutput, resolveZellijBinary, resetZellijIdentityCache, sanitizeZellijEnv, validateSshDestination, validateSshMode, } from "./zellij/binary.js";
@@ -14,11 +15,15 @@ export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, } from "./po
 export { buildSshRemoteCommand, createSshExec, quoteRemoteArg, shellQuote, } from "./exec.js";
 export { resolveSshTarget } from "./zellij/binary.js";
 export { applyIpcTmpEnv, cmdQuote, concreteTmp, encodePowerShellCommand, inferRemoteShell, parseZellijServerPaths, pickIpcDirs, pickIpcTmp, socketDirFromServerPath, tmpFromServerPath, unixDiscoverRemote, windowsDiscoverRemote, windowsInteractiveRemote, wrapWithTmpEnv, } from "./zellij/ipc.js";
-export { callServe, DEFAULT_SERVE_LISTEN, installServeLogon, isLoopbackHost, parseListenAddress, redactServeSecret, SERVE_CALL_TIMEOUT_CAP_MS, SERVE_MAX_REQUEST_BYTES, SERVE_TASK_NAME, serveCallTimeout, serveChildEnv, serveLogonCommand, startServe, uninstallServeLogon, } from "./ops/serve.js";
+export { callServe, DEFAULT_SERVE_LISTEN, isLoopbackHost, parseListenAddress, probeServe, redactServeSecret, SERVE_CALL_TIMEOUT_CAP_MS, SERVE_CAPABILITY_HELLO, SERVE_CONNECT_TIMEOUT_MS, SERVE_CONTROL_FIELD, SERVE_HELLO_CONTROL, SERVE_HELLO_TIMEOUT_MS, SERVE_CORE_VERSION, SERVE_LAUNCH_ID_ENV, SERVE_MAX_HELLO_BYTES, SERVE_MAX_REPLY_BYTES, SERVE_MAX_REQUEST_BYTES, SERVE_CAPTURE_BUDGET_BYTES, SERVE_PROTOCOL, SERVE_REMEDY, SERVE_TASK_NAME, serveCallTimeout, serveChildEnv, serveLogonCommand, serveMaxReplyBytes, startServe, } from "./ops/serve.js";
+export { authorizeServeListen, canonicalizeListenIp, expandIPv6, sameCanonicalIp, SERVE_BIND_REMEDY, SERVE_BIND_STATUS_MAX_BYTES, SERVE_BIND_VERIFY_TIMEOUT_MS, SERVE_TAILSCALE_BIN_ENV, } from "./ops/serve-bind.js";
+export { buildServeTaskScript, DEFAULT_SERVE_INSTALL_TIMEOUT_MS, installServeLogon, looksLikeCliEntrypoint, looksLikeMcpEntrypoint, resolveServeCliLaunch, sameWindowsAccount, sameWindowsSid, SERVE_NOT_READY_CODE, SERVE_TASK_OWNED_CODE, serveCommandFingerprint, serveTaskChildEnv, serveTaskLaunchEnv, uninstallServeLogon, } from "./ops/serve-install.js";
+export { allocateLoopbackPort, assertSafeSshTunnelOpts, buildSshTunnelArgv, createServeTunnelManager, DEFAULT_SSH_PORT, DEFAULT_SSH_SERVE_PORT, describeServeTarget, formatSshServeTarget, forwardServe, isSshServeTarget, parseSshServeTarget, redactSshUserinfo, serveTunnelCacheKey, SSH_SERVE_REMOTE_HOST, SSH_TUNNEL_KEEPALIVE_COUNT, SSH_TUNNEL_KEEPALIVE_INTERVAL_S, stripControllerRouting, } from "./ops/serve-tunnel.js";
 export { parseTabList, resolveTab } from "./zellij/tabs.js";
 export { selectTargets } from "./ops/broadcast.js";
 export { diffScreens, cursorKey } from "./ops/tail.js";
 export { classify, lastLine, mapPool, peerStatus, DEFAULT_STATUS_TIMEOUT_MS, STATUS_DUMP_CONCURRENCY, } from "./ops/status.js";
 export { normalizeScreen, truncateDumpText, DEFAULT_DUMP_MAX_CHARS, DEFAULT_WAIT_MAX_CHARS, } from "./ops/util.js";
+export { DEFAULT_DOCTOR_TIMEOUT_MS, DOCTOR_FAILED_CODE, DOCTOR_SCOPE_FIELD, DOCTOR_SCOPE_HOST, DOCTOR_TAILSCALE_MAX_MS, HOST_REPORT_INCOMPLETE_CODE, HOST_REPORT_INVALID_CODE, doctorOp, inspectDoctorHost, coverHostReport, hostDoctorRequest, isRequiredFailure, mergeHostReply, } from "./ops/doctor.js";
 export { normalizeKey, normalizeKeys, tokenizeCommand } from "./keys.js";
 export { cliUsage, mcpInputSchema, parseCliArgv, MCP_TOOL_DESCRIPTION, OP_NAMES, PARAMS, TARGET_OPS, } from "./schema.js";

package/dist/ops/broadcast.js

@@ -70,7 +70,7 @@ export async function broadcast(client, state, args, clock, policy, env = proces
     if (!body.trim())
         throw new ZellijError("missing_body", "body required");
     const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
-    const panes = await client.listPanes(session);
+    const panes = await client.listPanes(session, undefined, { fresh: true });
     const labeled = withSenderLabel(args, {
         env,
         selfTitle: selfPaneTitle(client, panes),

package/dist/ops/bus.js

@@ -19,15 +19,18 @@ const COLD_RETRY_MS = 200;
  * copies.
  */
 const INSTALL_IN_FLIGHT_MS = 10_000;
-/** Set once a pipe has failed, so one dead plugin costs one timeout, not many. */
-let processDisabled = null;
+/** Back off failed pipes briefly, isolated to their transport/session/plugin. */
+const busFailures = new Map();
 /** The key that actually answered, per session, for the life of this process. */
 const answeredWith = new Map();
 /** Tests share a module instance; this drops what a previous case cached. */
 export function resetBusCache() {
-    processDisabled = null;
+    busFailures.clear();
     answeredWith.clear();
 }
+function busScope(client, session, plan) {
+    return JSON.stringify([client.contextKey(), session, plan.url, plan.configKey]);
+}
 function affirmative(raw) {
     const v = (raw ?? "").trim().toLowerCase();
     return v === "1" || v === "true" || v === "yes" || v === "on";
@@ -62,8 +65,12 @@ export function planBus(client, state, env = process.env, session = "") {
             reason: "no plugin wasm found; run pnpm build:plugin or set ZSWARM_BUS_PLUGIN",
         };
     }
-    if (processDisabled)
-        return { ...base, reason: processDisabled };
+    const scope = busScope(client, session, base);
+    const failed = busFailures.get(scope);
+    if (failed && Date.now() < failed.until)
+        return { ...base, reason: failed.reason };
+    if (failed)
+        busFailures.delete(scope);
     if (affirmative(env.ZSWARM_BUS)) {
         return { ...base, enabled: true, reason: "ZSWARM_BUS=1" };
     }
@@ -89,7 +96,7 @@ async function nudgeManifest(client, session, env, remaining) {
     const listBudget = Math.min(DEFAULT_TIMEOUT_MS, remaining());
     if (listBudget <= 0)
         return;
-    const panes = await client.listPanes(session, listBudget);
+    const panes = await client.listPanes(session, listBudget, { fresh: true });
     const pane = panes.find((p) => !p.isPlugin && !p.exited && p.title.trim());
     if (!pane)
         return;
@@ -127,7 +134,8 @@ export async function busSnapshot(client, state, session, clock, env = process.e
     const url = plan.url;
     if (!plan.enabled || !url || !pluginPath)
         return null;
-    const configKey = answeredWith.get(session) ?? plan.configKey;
+    const scope = busScope(client, session, plan);
+    const configKey = answeredWith.get(scope) ?? plan.configKey;
     const ask = async () => {
         const budget = Math.min(DEFAULT_BUS_TIMEOUT_MS, remaining());
         if (budget <= 0)
@@ -155,10 +163,18 @@ export async function busSnapshot(client, state, session, clock, env = process.e
     if (remaining() <= 0 && !snapshot?.ready)
         return null;
     if (snapshot) {
-        answeredWith.set(session, configKey);
+        answeredWith.set(scope, configKey);
+        if (answeredWith.size > 256)
+            answeredWith.delete(answeredWith.keys().next().value);
+        if (snapshot.ready)
+            client.observeManifest(session, JSON.stringify([
+                scope, snapshot.paneUpdates, snapshot.tabUpdates, snapshot.panes, snapshot.tabs, snapshot.tabIds,
+            ]));
         return { snapshot, configKey };
     }
-    processDisabled = "plugin did not answer; using zellij polling for this run";
+    busFailures.set(scope, { reason: "plugin did not answer; using zellij polling for 5s", until: Date.now() + 5000 });
+    if (busFailures.size > 256)
+        busFailures.delete(busFailures.keys().next().value);
     return null;
 }
 /**
@@ -178,7 +194,7 @@ export async function busScreens(client, state, session, paneIds, clock, env = p
     const plan = planBus(client, state, env, session);
     if (!plan.enabled || !plan.url)
         return null;
-    const configKey = answeredWith.get(session) ?? plan.configKey;
+    const configKey = answeredWith.get(busScope(client, session, plan)) ?? plan.configKey;
     const reply = await client.scrollbackPlugin({
         session,
         url: plan.url,
@@ -209,7 +225,7 @@ export async function busWait(client, state, session, request, env = process.env
     const plan = planBus(client, state, env, session);
     if (!plan.enabled || !plan.url)
         return null;
-    const configKey = answeredWith.get(session) ?? plan.configKey;
+    const configKey = answeredWith.get(busScope(client, session, plan)) ?? plan.configKey;
     const reply = await client.waitPlugin({
         session,
         url: plan.url,
@@ -232,7 +248,7 @@ export async function busChanged(client, state, session, paneIds, env = process.
     const plan = planBus(client, state, env, session);
     if (!plan.enabled || !plan.url)
         return null;
-    const configKey = answeredWith.get(session) ?? plan.configKey;
+    const configKey = answeredWith.get(busScope(client, session, plan)) ?? plan.configKey;
     const reply = await client.changedPlugin({
         session,
         url: plan.url,
@@ -243,7 +259,8 @@ export async function busChanged(client, state, session, paneIds, env = process.
     const parsed = parseChangedReply(reply.stdout);
     if (!parsed || !parsed.ready)
         return null;
-    return parsed.panes.length === paneIds.length ? parsed : null;
+    const received = new Set([...parsed.panes.map((pane) => pane.id), ...parsed.missing]);
+    return paneIds.every((id) => received.has(id)) ? parsed : null;
 }
 function installedReply(session, plugin, configKey, ready, panes, extra = {}) {
     return {
@@ -261,7 +278,7 @@ function installedReply(session, plugin, configKey, ready, panes, extra = {}) {
     };
 }
 async function listBusPluginPanes(client, session, pluginPath) {
-    const panes = await client.listPanes(session);
+    const panes = await client.listPanes(session, undefined, { fresh: true });
     return panes.filter((pane) => isBusPluginPane(pane, pluginPath));
 }
 /** Close every zswarm-bus plugin pane in this session. Best-effort per pane. */
@@ -279,8 +296,15 @@ export async function closeBusPluginPanes(client, session, pluginPath) {
     }
     return closed;
 }
+/** Effective SSH transport — not controller OS, not leftover ZSWARM_SSH in env. */
+function isDirectSshClient(client) {
+    return client.remote || client.transport.kind === "ssh";
+}
 /** Report on the bus, install it, or forget it. */
 export async function busOp(client, state, args, clock, env = process.env, policy) {
+    if ((isTrue(args.install) || isTrue(args.clear)) && isDirectSshClient(client)) {
+        throw new ZellijError("bus_remote_unsupported", "run on Zellij host or use --serve through a tunnel; direct SSH cannot install/clear the bus");
+    }
     const sessionArg = typeof args.session === "string" ? args.session : undefined;
     if (isTrue(args.clear)) {
         let session = null;