@zswarm/core 0.1.4 → 0.1.6

package/dist/ops/bus.js

@@ -1,7 +1,9 @@
 import { existsSync } from "node:fs";
 import { ZellijError } from "../errors.js";
-import { DEFAULT_BUS_KEY, busPluginUrl, nextConfigKey, parseBusReply, parseChangedReply, parseScrollbackReply, parseWaitReply, resolveBusPlugin, scrollbackToScreen, } from "../zellij/bus.js";
-import { isTrue } from "./util.js";
+import { loadPolicy } from "../policy.js";
+import { DEFAULT_BUS_KEY, DEFAULT_BUS_TIMEOUT_MS, busPluginUrl, isBusPluginPane, parseBusReply, parseChangedReply, parseScrollbackReply, parseWaitReply, resolveBusPlugin, scrollbackToScreen, } from "../zellij/bus.js";
+import { DEFAULT_TIMEOUT_MS } from "../zellij/binary.js";
+import { isTrue, throwIfAborted } from "./util.js";
 /**
  * Whether to ask the event-bus plugin, and what to do when it does not answer.
  *
@@ -9,10 +11,14 @@ import { isTrue } from "./util.js";
  * prompt, because a pipe to a plugin that was never approved costs a process
  * and a timeout on every call and then falls back anyway.
  */
-/** Config keys to try before giving up; each one is a fresh pipe destination. */
-const MAX_KEY_ATTEMPTS = 3;
 /** A just-launched instance answers before Zellij has pushed it anything. */
 const COLD_RETRY_MS = 200;
+/**
+ * A marker written this recently with no live pane is an in-flight install,
+ * not a closed pane. Relaunching it is how concurrent agents used to stack
+ * 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;
 /** The key that actually answered, per session, for the life of this process. */
@@ -30,8 +36,8 @@ function negative(raw) {
     const v = (raw ?? "").trim().toLowerCase();
     return v === "0" || v === "false" || v === "no" || v === "off";
 }
-export function planBus(client, state, env = process.env) {
-    const marker = state.readBus();
+export function planBus(client, state, env = process.env, session = "") {
+    const marker = session ? state.readBus(session) : null;
     // A marker can outlive the wasm it names — an upgrade renames the artifact,
     // so a remembered path that no longer exists must not shadow the current one.
     const remembered = marker && existsSync(marker.plugin) ? marker : null;
@@ -65,8 +71,10 @@ export function planBus(client, state, env = process.env) {
         return { ...base, enabled: true, reason: "installed" };
     return { ...base, reason: 'not installed; run zswarm({op:"bus", install:true})' };
 }
-async function askOnce(client, session, url, configKey, payload) {
-    const result = await client.pipePlugin({ session, url, configKey, payload });
+async function askOnce(client, session, url, configKey, payload, timeoutMs) {
+    const result = await client.pipePlugin({
+        session, url, configKey, payload, timeoutMs,
+    });
     return parseBusReply(result.stdout);
 }
 /**
@@ -75,62 +83,80 @@ async function askOnce(client, session, url, configKey, payload) {
  * 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);
+async function nudgeManifest(client, session, env, remaining) {
+    if (loadPolicy(env).readOnly)
+        return;
+    const listBudget = Math.min(DEFAULT_TIMEOUT_MS, remaining());
+    if (listBudget <= 0)
+        return;
+    const panes = await client.listPanes(session, listBudget);
     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 });
+    const renameBudget = Math.min(DEFAULT_TIMEOUT_MS, remaining());
+    if (renameBudget <= 0)
+        return;
+    await client.renamePane({
+        session,
+        paneId: pane.id,
+        name: pane.title,
+        timeoutMs: renameBudget,
+    });
 }
 /**
  * One pipe, one answer — or null, and the caller polls instead.
  *
- * Two things go wrong in practice. A stale instance under the same key eats the
- * 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.
+ * 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. A silent pipe used to rotate `instance=` keys, and `zellij pipe
+ * --plugin` loads a new copy for each key — that is how a dead bus became
+ * dozens of WASM panes. One remembered key, then polling.
  */
-export async function busSnapshot(client, state, session, clock, env = process.env, payload = "status") {
-    const plan = planBus(client, state, env);
+export async function busSnapshot(client, state, session, clock, env = process.env, payload = "status", opts = {}) {
+    const remaining = () => {
+        throwIfAborted(opts.signal);
+        return opts.deadlineAt === undefined
+            ? Infinity
+            : Math.max(0, opts.deadlineAt - clock.now());
+    };
+    if (remaining() <= 0)
+        return null;
+    const plan = planBus(client, state, env, session);
     const pluginPath = plan.plugin;
-    if (!plan.enabled || !plan.url || !pluginPath)
+    const url = plan.url;
+    if (!plan.enabled || !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) {
-            await clock.sleep(COLD_RETRY_MS);
-            snapshot =
-                (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.
-            }
+    const configKey = answeredWith.get(session) ?? plan.configKey;
+    const ask = async () => {
+        const budget = Math.min(DEFAULT_BUS_TIMEOUT_MS, remaining());
+        if (budget <= 0)
+            return null;
+        const snapshot = await askOnce(client, session, url, configKey, payload, budget);
+        throwIfAborted(opts.signal);
+        return snapshot;
+    };
+    let snapshot = await ask();
+    if (snapshot && !snapshot.ready && remaining() > 0) {
+        await clock.sleep(Math.min(COLD_RETRY_MS, remaining()));
+        snapshot = (await ask()) ?? snapshot;
+    }
+    if (snapshot && !snapshot.ready && remaining() > 0) {
+        try {
+            await nudgeManifest(client, session, env, remaining);
+            snapshot = (await ask()) ?? snapshot;
         }
-        if (snapshot) {
-            answeredWith.set(session, configKey);
-            if (plan.installed && configKey !== plan.configKey) {
-                // Remember the rotation, so the next process starts on a live key.
-                state.writeBus({
-                    plugin: pluginPath,
-                    configKey,
-                    installedAt: clock.now(),
-                });
-            }
-            return { snapshot, configKey };
+        catch {
+            throwIfAborted(opts.signal);
+            // A failed nudge must not fail the op — the caller polls instead.
         }
-        configKey = nextConfigKey(configKey);
+    }
+    // An expired request says nothing about bus health or an empty cold manifest.
+    if (remaining() <= 0 && !snapshot?.ready)
+        return null;
+    if (snapshot) {
+        answeredWith.set(session, configKey);
+        return { snapshot, configKey };
     }
     processDisabled = "plugin did not answer; using zellij polling for this run";
     return null;
@@ -146,10 +172,10 @@ export async function busSnapshot(client, state, session, clock, env = process.e
  * `dump-screen` returns them ragged. `normalizeScreen` erases exactly that
  * difference, and every caller here already normalizes before comparing.
  */
-export async function busScreens(client, state, session, paneIds, clock, env = process.env) {
+export async function busScreens(client, state, session, paneIds, clock, env = process.env, timeoutMs) {
     if (paneIds.length < 2)
         return null;
-    const plan = planBus(client, state, env);
+    const plan = planBus(client, state, env, session);
     if (!plan.enabled || !plan.url)
         return null;
     const configKey = answeredWith.get(session) ?? plan.configKey;
@@ -158,6 +184,7 @@ export async function busScreens(client, state, session, paneIds, clock, env = p
         url: plan.url,
         configKey,
         panes: paneIds,
+        timeoutMs,
     });
     const parsed = parseScrollbackReply(reply.stdout);
     if (!parsed || !parsed.ready)
@@ -179,7 +206,7 @@ export async function busScreens(client, state, session, paneIds, clock, env = p
  * instance, no reply — and the caller runs its own loop.
  */
 export async function busWait(client, state, session, request, env = process.env) {
-    const plan = planBus(client, state, env);
+    const plan = planBus(client, state, env, session);
     if (!plan.enabled || !plan.url)
         return null;
     const configKey = answeredWith.get(session) ?? plan.configKey;
@@ -199,10 +226,10 @@ export async function busWait(client, state, session, request, env = process.env
  * `status` answers by sampling twice, without the gap between samples — but
  * relative to the previous call rather than a fixed window.
  */
-export async function busChanged(client, state, session, paneIds, env = process.env) {
+export async function busChanged(client, state, session, paneIds, env = process.env, timeoutMs) {
     if (paneIds.length === 0)
         return null;
-    const plan = planBus(client, state, env);
+    const plan = planBus(client, state, env, session);
     if (!plan.enabled || !plan.url)
         return null;
     const configKey = answeredWith.get(session) ?? plan.configKey;
@@ -211,20 +238,70 @@ export async function busChanged(client, state, session, paneIds, env = process.
         url: plan.url,
         configKey,
         panes: paneIds,
+        timeoutMs,
     });
     const parsed = parseChangedReply(reply.stdout);
     if (!parsed || !parsed.ready)
         return null;
     return parsed.panes.length === paneIds.length ? parsed : null;
 }
+function installedReply(session, plugin, configKey, ready, panes, extra = {}) {
+    return {
+        ok: true,
+        data: {
+            session,
+            installed: true,
+            plugin,
+            url: busPluginUrl(plugin),
+            configKey,
+            ready,
+            panes,
+            ...extra,
+        },
+    };
+}
+async function listBusPluginPanes(client, session, pluginPath) {
+    const panes = await client.listPanes(session);
+    return panes.filter((pane) => isBusPluginPane(pane, pluginPath));
+}
+/** Close every zswarm-bus plugin pane in this session. Best-effort per pane. */
+export async function closeBusPluginPanes(client, session, pluginPath) {
+    const closed = [];
+    const panes = await listBusPluginPanes(client, session, pluginPath);
+    for (const pane of panes) {
+        try {
+            await client.closePane({ session, paneId: pane.id });
+            closed.push(pane.id);
+        }
+        catch {
+            // A pane that vanished between list and close is the desired end state.
+        }
+    }
+    return closed;
+}
 /** Report on the bus, install it, or forget it. */
 export async function busOp(client, state, args, clock, env = process.env, policy) {
+    const sessionArg = typeof args.session === "string" ? args.session : undefined;
     if (isTrue(args.clear)) {
-        state.clearBus();
+        let session = null;
+        let closed = [];
+        try {
+            session = (await client.resolveSession(sessionArg)).session;
+        }
+        catch {
+            session = sessionArg?.trim() || null;
+        }
+        if (session) {
+            closed = await closeBusPluginPanes(client, session, resolveBusPlugin(env) ?? state.readBus(session)?.plugin ?? null);
+            state.clearBus(session);
+        }
+        else {
+            state.clearBus();
+        }
         resetBusCache();
-        return { ok: true, data: { installed: false, cleared: true } };
+        return { ok: true, data: { installed: false, cleared: true, closed } };
     }
-    const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+    const { session } = await client.resolveSession(sessionArg);
     if (isTrue(args.install)) {
         // Installing opens a pane, which a read-only crew is not allowed to do.
         if (policy?.readOnly) {
@@ -234,32 +311,31 @@ export async function busOp(client, state, args, clock, env = process.env, polic
         if (!plugin) {
             throw new ZellijError("bus_missing", "no plugin wasm found; run pnpm build:plugin or set ZSWARM_BUS_PLUGIN");
         }
-        const previous = state.readBus();
+        const previous = state.readBus(session);
         const force = isTrue(args.force);
-        // Launching again would add a second instance, so an install that is
-        // already answering is a no-op unless the caller asked for a fresh one.
         if (previous && !force) {
             const live = await busSnapshot(client, state, session, clock, env);
             if (live?.snapshot.ready) {
-                return {
-                    ok: true,
-                    data: {
-                        session,
-                        installed: true,
-                        plugin: previous.plugin,
-                        url: busPluginUrl(previous.plugin),
-                        configKey: live.configKey,
-                        ready: true,
-                        panes: live.snapshot.panes.length,
-                        note: "already installed; --force reloads under a fresh key",
-                    },
-                };
+                return installedReply(session, previous.plugin, live.configKey, true, live.snapshot.panes.length, { note: "already installed" });
+            }
+            const existing = await listBusPluginPanes(client, session, plugin);
+            if (existing.length > 0) {
+                return installedReply(session, previous.plugin, previous.configKey, false, null, {
+                    pane: existing[0]?.id ?? null,
+                    note: "already installed but not answering; approve the permission prompt in the existing pane — do not --force unless you intend to replace it",
+                });
+            }
+            if (clock.now() - previous.installedAt < INSTALL_IN_FLIGHT_MS) {
+                return installedReply(session, previous.plugin, previous.configKey, false, null, {
+                    note: "install already in flight; wait for the permission prompt rather than launching another pane",
+                });
             }
         }
-        // A reload needs a key Zellij has not already bound an instance to.
-        const configKey = force && previous
-            ? nextConfigKey(previous.configKey)
-            : (previous?.configKey ?? DEFAULT_BUS_KEY);
+        // Marker first so a concurrent install sees an in-flight write and
+        // stops. Then reap orphans so a reload cannot stack on the old copies.
+        const configKey = previous?.configKey ?? DEFAULT_BUS_KEY;
+        state.writeBus(session, { plugin, configKey, installedAt: clock.now() });
+        const closed = await closeBusPluginPanes(client, session, plugin);
         const url = busPluginUrl(plugin);
         const launched = await client.launchPlugin({
             session,
@@ -268,27 +344,17 @@ export async function busOp(client, state, args, clock, env = process.env, polic
             floating: true,
             skipCache: force,
         });
-        state.writeBus({ plugin, configKey, installedAt: clock.now() });
         resetBusCache();
         const probe = await busSnapshot(client, state, session, clock, env);
-        return {
-            ok: true,
-            data: {
-                session,
-                installed: true,
-                plugin,
-                url,
-                configKey,
-                pane: launched.paneId,
-                ready: probe?.snapshot.ready ?? false,
-                panes: probe?.snapshot.panes.length ?? null,
-                note: probe
-                    ? "bus answering; list and status use it now, and this pane can be closed"
-                    : "approve the plugin's permission prompt in the new pane, then re-run",
-            },
-        };
+        return installedReply(session, plugin, configKey, probe?.snapshot.ready ?? false, probe?.snapshot.panes.length ?? null, {
+            pane: launched.paneId,
+            closed,
+            note: probe
+                ? "bus answering; keep this floating pane open — closing it unloads the bus"
+                : "approve the plugin's permission prompt in the new pane, then re-run without --install",
+        });
     }
-    const plan = planBus(client, state, env);
+    const plan = planBus(client, state, env, session);
     const probe = plan.enabled
         ? await busSnapshot(client, state, session, clock, env)
         : null;

package/dist/ops/delivery.d.ts

@@ -40,9 +40,9 @@ export declare function withSenderLabel(args: Record<string, unknown>, opts?: {
     selfTitle?: string | null;
 }): Record<string, unknown>;
 /**
- * Before forwarding over `ZSWARM_SERVE`, keep a caller-chosen label and
- * leave `from` unset when it would default, so the Zellij-side process can
- * still fill in its own pane title.
+ * Before forwarding over `ZSWARM_SERVE`, stamp a caller-chosen label. Leaving
+ * `from` unset used to let the Zellij-side process fill in its pane title —
+ * which is the serve daemon when it runs in a pane, not the remote sender.
  */
 export declare function attachKnownSender(args: Record<string, unknown>, env: NodeJS.ProcessEnv): Record<string, unknown>;
 export declare function bodyText(client: ZellijClient, args: Record<string, unknown>, body: string): string;

package/dist/ops/delivery.js

@@ -45,19 +45,16 @@ export function withSenderLabel(args, opts = {}) {
     return { ...args, from: senderLabel(args, opts) };
 }
 /**
- * Before forwarding over `ZSWARM_SERVE`, keep a caller-chosen label and
- * leave `from` unset when it would default, so the Zellij-side process can
- * still fill in its own pane title.
+ * Before forwarding over `ZSWARM_SERVE`, stamp a caller-chosen label. Leaving
+ * `from` unset used to let the Zellij-side process fill in its pane title —
+ * which is the serve daemon when it runs in a pane, not the remote sender.
  */
 export function attachKnownSender(args, env) {
     const op = String(args.op ?? "");
     if (op !== "send" && op !== "broadcast")
         return args;
     const sender = resolveSender(args, { env });
-    if (sender.source === "arg" || sender.source === "env") {
-        return { ...args, from: sender.label };
-    }
-    return args;
+    return { ...args, from: sender.label };
 }
 export function bodyText(client, args, body) {
     return isTrue(args.raw) ? body : client.formatPeerMessage(senderLabel(args), body);

package/dist/ops/dispatch.d.ts

@@ -1,4 +1,10 @@
 import { type ZellijClient } from "../zellij/client.js";
 import type { DispatchDeps, OpsResult } from "./types.js";
-/** Shared MCP/CLI dispatch for zswarm ops. */
+/**
+ * Per-invocation routing from `--local` / `--ssh`. `--local` clears both SSH
+ * and serve (and remote IPC). `--ssh` sets the destination for this call and
+ * clears serve so the flag wins over a sticky ZSWARM_SERVE.
+ */
+export declare function resolveInvocationEnv(args: Record<string, unknown>, base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Shared MCP/CLI dispatch, with invocation routing on successes and failures. */
 export declare function dispatchZswarm(args: Record<string, unknown>, injected?: ZellijClient, deps?: DispatchDeps): Promise<OpsResult>;