@zswarm/core 0.1.6 → 0.1.8

package/dist/ops/dispatch.js

@@ -6,7 +6,7 @@ import { assertOpAllowed, assertPaneAllowed, loadPolicy, } from "../policy.js";
 import { createStateStore } from "../state.js";
 import { busToPanes } from "../zellij/bus.js";
 import { broadcast } from "./broadcast.js";
-import { busChanged, busOp, busScreens, busSnapshot, busWait } from "./bus.js";
+import { busChanged, busOp, busScreens, busSnapshot, busWait, planBus } from "./bus.js";
 import { dumpLayoutOp, focusTarget, listTabsOp, renameTarget, stackTargets, } from "./panes.js";
 import { peerCheckpoint, peerDiff } from "./review.js";
 import { attachKnownSender, deliverTo, withSenderLabel, selfPaneTitle } from "./delivery.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
@@ -31,12 +34,18 @@ import { callServe, installServeLogon, serveCallTimeout, uninstallServeLogon, }
 export function resolveInvocationEnv(args, base) {
     const local = isTrue(args.local);
     const sshDest = typeof args.ssh === "string" && args.ssh.trim() ? args.ssh.trim() : null;
-    if (local && sshDest) {
-        throw new ZellijError("usage", "pass --local or --ssh, not both");
+    const serveAddress = optionalString(args.serveAddress);
+    if (Number(local) + Number(Boolean(sshDest)) + Number(Boolean(serveAddress)) > 1) {
+        throw new ZellijError("usage", "choose only one of --local, --ssh, or --serve");
     }
-    if (!local && !sshDest)
+    if (!local && !sshDest && !serveAddress)
         return base;
     const env = { ...base };
+    if (serveAddress) {
+        env.ZSWARM_SERVE = serveAddress;
+        delete env.ZSWARM_SSH;
+        return env;
+    }
     if (local) {
         delete env.ZSWARM_SSH;
         delete env.ZSWARM_SSH_OPTS;
@@ -107,9 +116,10 @@ async function resolveTarget(client, args, state, clock, env, policy, op, signal
     }
     const until = Math.min(budget.deadline, clock.now() + observeMs);
     let pane;
+    let fresh = isTrue(args.fresh) || Boolean(op);
     for (;;) {
         const left = observeMs === 0 ? budget.require() : Math.min(budget.require(), Math.max(1, until - clock.now()));
-        panes ??= await client.listPanes(session, left);
+        panes ??= await client.listPanes(session, left, { fresh });
         throwIfAborted(signal);
         try {
             pane = client.resolvePane(panes, to);
@@ -122,6 +132,7 @@ async function resolveTarget(client, args, state, clock, env, policy, op, signal
             if (clock.now() >= until)
                 throw err;
             panes = null;
+            fresh = true;
         }
     }
     if (policy && op)
@@ -163,27 +174,60 @@ 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");
         }
         // 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(), attachKnownSender(args, env), serveCallTimeout(args), env.ZSWARM_SERVE_TOKEN);
+            const request = { ...attachKnownSender(args, env) };
+            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 });
+        const baseClient = injected ?? createZellijClient({ env, signal, cache: isTrue(args.fresh) ? false : undefined });
         const client = {
             ...baseClient,
             get transport() { return baseClient.transport; },
@@ -224,9 +268,10 @@ async function dispatchOperation(args, injected, deps, context, env) {
                 const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
                 // The plugin's manifest carries no cwd or floating flag, so anything
                 // verbose has to go the polling route.
-                const bus = verbose
+                const observedBus = verbose
                     ? null
                     : await busSnapshot(client, state(), session, clock, env);
+                const bus = observedBus?.snapshot.ready ? observedBus : null;
                 const view = bus ? paneViewBus : verbose ? paneViewFull : paneViewSlim;
                 const panes = (bus ? busToPanes(bus.snapshot) : await client.listPanes(session))
                     .filter((p) => !p.isPlugin)
@@ -391,24 +436,39 @@ async function dispatchOperation(args, injected, deps, context, env) {
                 throwIfAborted(signal);
                 const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined, setupBudget());
                 throwIfAborted(signal);
-                // Verbose reports cwd and command, which the plugin manifest lacks.
-                const bus = verbose || remaining() <= 0
-                    ? null
-                    : await busSnapshot(client, state(), session, clock, env, "status", {
-                        deadlineAt,
-                        signal,
-                    });
+                // Once the session is known, verbose metadata and the bus manifest
+                // are independent reads. Both consume this operation's remaining time.
+                const readBus = () => remaining() <= 0 ? Promise.resolve(null)
+                    : busSnapshot(client, state(), session, clock, env, "status", { deadlineAt, signal });
+                let observedBus;
+                let detailedPanes;
+                if (verbose) {
+                    const reads = await Promise.allSettled([
+                        readBus(), client.listPanes(session, setupBudget(), { fresh: true }),
+                    ]);
+                    throwIfAborted(signal);
+                    if (reads[1].status === "rejected")
+                        throw reads[1].reason;
+                    if (reads[0].status === "rejected")
+                        throw reads[0].reason;
+                    observedBus = reads[0].value;
+                    detailedPanes = reads[1].value;
+                }
+                else {
+                    observedBus = await readBus();
+                }
+                const bus = observedBus?.snapshot.ready ? observedBus : null;
                 throwIfAborted(signal);
                 // Always hand peerStatus the resolved session (and panes) so it does
                 // not spend the overall budget resolving again.
-                const panes = bus
+                const panes = detailedPanes ?? (bus
                     ? busToPanes(bus.snapshot)
-                    : await client.listPanes(session, setupBudget());
+                    : await client.listPanes(session, setupBudget()));
                 throwIfAborted(signal);
                 let supplied = {
                     session,
                     panes,
-                    source: bus ? "plugin" : "zellij",
+                    source: bus && !verbose ? "plugin" : "zellij",
                 };
                 if (bus) {
                     supplied = {
@@ -433,13 +493,24 @@ async function dispatchOperation(args, injected, deps, context, env) {
                     catch {
                         // Command-shaped `to` needs the polled list; re-fetch without bus.
                         const polled = await client.listPanes(session, setupBudget());
-                        supplied = { session, panes: polled, source: "zellij" };
+                        supplied = { ...supplied, session, panes: polled, source: "zellij" };
                     }
                 }
-                return await peerStatus(client, args, clock, supplied, {
+                const result = await peerStatus(client, args, clock, supplied, {
                     deadlineAt,
                     signal,
                 });
+                if (result.ok && result.data && typeof result.data === "object") {
+                    const data = result.data;
+                    data.polling = {
+                        busAvailable: Boolean(bus),
+                        ...(bus ? {} : { reason: planBus(client, state(), env, session).reason }),
+                        ...(client.remote ? {
+                            recommendation: "For frequent status calls, run zswarm serve beside Zellij and use --serve 127.0.0.1:9419 through an SSH tunnel; direct SSH cannot use the local event bus.",
+                        } : {}),
+                    };
+                }
+                return result;
             }
             case "bus":
                 return await busOp(client, state(), args, clock, env, policy);

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>;