@zswarm/core 0.1.7 → 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 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;

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 === "")
@@ -349,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();
@@ -383,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

@@ -15,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

@@ -15,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/bus.js

@@ -296,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;

package/dist/ops/dispatch.js

@@ -22,7 +22,10 @@ import { OP_NAMES } from "../schema.js";
 import { dumpMaxChars, fail, isTrue, isVerbose, numberArg, optionalString, paneViewBus, paneViewFull, paneViewSlim, throwIfAborted, truncateDumpText, } from "./util.js";
 import { waitForPane } from "./wait.js";
 import { listPeerWorktrees, removePeerWorktree } from "./worktree.js";
-import { callServe, installServeLogon, serveCallTimeout, uninstallServeLogon, } from "./serve.js";
+import { DEFAULT_SERVE_INSTALL_TIMEOUT_MS, installServeLogon, uninstallServeLogon, } from "./serve-install.js";
+import { serveCallTimeout, } from "./serve.js";
+import { doctorOp } from "./doctor.js";
+import { forwardServe } from "./serve-tunnel.js";
 /**
  * Per-invocation routing from `--local` / `--ssh`. `--local` clears both SSH
  * and serve (and remote IPC). `--ssh` sets the destination for this call and
@@ -171,18 +174,42 @@ async function dispatchOperation(args, injected, deps, context, env) {
         // Policy gates the op before anything touches the session.
         assertOpAllowed(policy, op);
         assertSshGitAllowed(env, op, args);
+        if (op === "doctor") {
+            // Before serve forwarding and session resolution so a dead tunnel still
+            // yields controller findings. Policy already ran.
+            return await doctorOp(args, injected, deps, context, env, clock);
+        }
         if (op === "serve") {
+            const timeoutMs = numberArg(args, "timeoutMs", DEFAULT_SERVE_INSTALL_TIMEOUT_MS, {
+                min: 1,
+                max: 900_000,
+            });
             if (isTrue(args.clear)) {
                 const cleared = await uninstallServeLogon({
-                    platform: process.platform,
+                    platform: deps.serveInstall?.platform ?? process.platform,
+                    timeoutMs,
+                    signal,
+                    env,
+                    token: env.ZSWARM_SERVE_TOKEN,
+                    ...deps.serveInstall,
                 });
                 return { ok: true, data: cleared };
             }
             if (isTrue(args.install)) {
                 const installed = await installServeLogon({
                     listen: typeof args.listen === "string" ? args.listen : undefined,
+                    session: optionalString(args.session),
+                    timeoutMs,
+                    signal,
+                    env,
+                    token: env.ZSWARM_SERVE_TOKEN,
+                    now: clock.now,
+                    sleep: clock.sleep,
+                    tailscaleStatus: deps.tailscaleStatus,
+                    networkInterfaces: deps.networkInterfaces,
+                    ...deps.serveInstall,
                 });
-                return { ok: true, data: { ...installed, running: true } };
+                return { ok: true, data: installed };
             }
             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");
         }
@@ -190,8 +217,15 @@ async function dispatchOperation(args, injected, deps, context, env) {
         // just because the host env has ZSWARM_SERVE set.
         if (!injected && env.ZSWARM_SERVE?.trim()) {
             const request = { ...attachKnownSender(args, env) };
-            delete request.serveAddress; // Routing is consumed here, never forwarded back into a tunnel.
-            return await callServe(env.ZSWARM_SERVE.trim(), request, serveCallTimeout(args), env.ZSWARM_SERVE_TOKEN);
+            return await forwardServe({
+                target: env.ZSWARM_SERVE.trim(),
+                args: request,
+                timeoutMs: serveCallTimeout(args),
+                token: env.ZSWARM_SERVE_TOKEN,
+                signal,
+                env,
+                manager: deps.serveTunnels,
+            });
         }
         const baseClient = injected ?? createZellijClient({ env, signal, cache: isTrue(args.fresh) ? false : undefined });
         const client = {

package/dist/ops/doctor.d.ts

@@ -0,0 +1,80 @@
+import { type ZellijClient } from "../zellij/client.js";
+import { type StateStore } from "../state.js";
+import type { RoutingContext } from "./routing.js";
+import { type ServeHelloData } from "./serve.js";
+import type { Clock, DispatchDeps, OpsResult } from "./types.js";
+/** Overall doctor deadline when `timeoutMs` is omitted. */
+export declare const DEFAULT_DOCTOR_TIMEOUT_MS = 10000;
+/** Internal serve-worker flag. Never a public CLI flag or MCP param. */
+export declare const DOCTOR_SCOPE_FIELD = "doctorScope";
+export declare const DOCTOR_SCOPE_HOST = "host";
+export declare const DOCTOR_FAILED_CODE = "doctor_failed";
+/** Host doctor reply after hello was empty, malformed, or not a report. */
+export declare const HOST_REPORT_INVALID_CODE = "host_report_invalid";
+/** Host doctor reply omitted required host/session coverage. */
+export declare const HOST_REPORT_INCOMPLETE_CODE = "host_report_incomplete";
+/** Cap for optional Tailscale so required SSH/hello/session keep budget. */
+export declare const DOCTOR_TAILSCALE_MAX_MS = 1500;
+export type DoctorCheckState = "ok" | "warn" | "fail" | "skipped";
+export type DoctorCheckScope = "controller" | "host";
+export type DoctorCheck = {
+    id: string;
+    scope: DoctorCheckScope;
+    state: DoctorCheckState;
+    code: string;
+    elapsedMs: number;
+    detail: Record<string, unknown>;
+    remedy: string | null;
+};
+export type DoctorRoute = {
+    transport: "local" | "ssh" | "serve";
+    endpoint: string;
+    session: string | null;
+    sessionOrigin: string;
+};
+export type DoctorReport = {
+    route: DoctorRoute;
+    server?: ServeHelloData;
+    checks: DoctorCheck[];
+};
+export type HostInspectInput = {
+    client: ZellijClient;
+    state: StateStore;
+    env: NodeJS.ProcessEnv;
+    sessionArg?: string | null;
+    clock: Clock;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    /** Direct SSH cannot treat controller-local bus files as host facts. */
+    busUnsupported?: boolean;
+    busRemedy?: string;
+};
+export type HostInspectResult = {
+    checks: DoctorCheck[];
+    session: string | null;
+    sessionOrigin: string;
+    cancelled?: boolean;
+    timedOut?: boolean;
+};
+/** Required-layer failure using accepted doctor semantics. Host install must reuse this. */
+export declare function isRequiredFailure(report: DoctorReport, item: DoctorCheck): boolean;
+/**
+ * Passive host inspection. Safe reads only: binary/version via the client,
+ * session listing, pane listing for an existing plugin pane, and StateStore
+ * reads. Never pipes, launches, nudges, or writes markers.
+ */
+export declare function inspectDoctorHost(input: HostInspectInput): Promise<HostInspectResult>;
+export declare function hostDoctorRequest(remainingMs: number, explicitSession: string | null): Record<string, unknown>;
+export declare function coverHostReport(checks: DoctorCheck[], explicit: string | null): DoctorCheck[];
+export declare function mergeHostReply(result: OpsResult): {
+    checks: DoctorCheck[];
+    session?: string | null;
+    sessionOrigin?: string;
+    unsupported?: boolean;
+    invalid?: boolean;
+};
+/**
+ * Inspect-only layered diagnostics. Handle this before ordinary serve
+ * forwarding so a dead tunnel still reports controller findings.
+ */
+export declare function doctorOp(args: Record<string, unknown>, injected: ZellijClient | undefined, deps: DispatchDeps, context: RoutingContext, env: NodeJS.ProcessEnv, clock: Clock): Promise<OpsResult>;