@zswarm/core 0.1.3 → 0.1.5

package/dist/exec.d.ts

@@ -16,6 +16,8 @@ export type ExecOptions = {
      * timeout.
      */
     until?: (stdout: string) => boolean;
+    /** Kill the child when aborted (MCP cancellation). */
+    signal?: AbortSignal;
 };
 export type ExecFn = (args: string[], options: ExecOptions) => Promise<ExecResult>;
 export declare const NOT_FOUND_EXIT = 127;

package/dist/exec.js

@@ -100,14 +100,25 @@ function runUntil(binPath, args, env, options) {
                 return;
             settled = true;
             clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
             child.kill();
             resolve(result);
         };
+        const onAbort = () => finish({
+            code: -1,
+            stdout,
+            stderr: `${binPath} cancelled`,
+        });
         const timer = setTimeout(() => finish({
             code: -1,
             stdout,
             stderr: `${binPath} timed out after ${options.timeoutMs}ms`,
         }), options.timeoutMs);
+        if (options.signal?.aborted) {
+            onAbort();
+            return;
+        }
+        options.signal?.addEventListener("abort", onAbort, { once: true });
         child.on("error", (err) => {
             const missing = err.code === "ENOENT" || err.code === "ENOTDIR";
             finish({
@@ -138,6 +149,7 @@ function runToExit(binPath, args, env, options) {
             cwd: options.cwd,
             maxBuffer: 8 * 1024 * 1024,
             windowsHide: true,
+            signal: options.signal,
             env: options.env ? { ...env, ...options.env } : env,
         }, (error, stdout, stderr) => {
             const failure = error;
@@ -151,11 +163,15 @@ function runToExit(binPath, args, env, options) {
                 return;
             }
             if (failure &&
-                (failure.killed === true || typeof failure.signal === "string")) {
+                (failure.killed === true ||
+                    typeof failure.signal === "string" ||
+                    failure.name === "AbortError")) {
                 resolve({
                     code: -1,
                     stdout: String(stdout ?? ""),
-                    stderr: `${binPath} timed out after ${options.timeoutMs}ms`,
+                    stderr: failure.name === "AbortError"
+                        ? `${binPath} cancelled`
+                        : `${binPath} timed out after ${options.timeoutMs}ms`,
                 });
                 return;
             }

package/dist/index.d.ts

@@ -4,9 +4,9 @@ export { createGitClient, defaultWorktreeRoot, normalizeRepoPath, parseWorktreeL
 export { expandHomePath, resolveZellijBinary, sanitizeZellijEnv, type ZellijExecFn, type ZellijExecResult, } from "./zellij/binary.js";
 export { normalizePaneId, parsePaneList, resolvePane, type ZellijPane, } from "./zellij/panes.js";
 export { parseSessionList, resolveSelfPaneId, type ZellijSessionResolve, } from "./zellij/session.js";
-export { buildClosePaneArgs, buildDumpArgs, buildLaunchPluginArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, scrollbackPayload, type LaunchPluginInput, type NewPaneInput, type NewTabInput, type PaneDirection, type PipeInput, type ScrollbackRequest, } from "./zellij/args.js";
-export { busPluginUrl, busToPanes, nextConfigKey, parseBusReply, parseScrollbackReply, resolveBusPlugin, scrollbackToScreen, BUS_PIPE_NAME, DEFAULT_BUS_KEY, DEFAULT_BUS_TIMEOUT_MS, type BusMarker, type BusPane, type BusScrollback, type BusScrollbackPane, type BusSnapshot, } from "./zellij/bus.js";
-export { busSnapshot, planBus, resetBusCache, type BusPlan, } from "./ops/bus.js";
+export { buildClosePaneArgs, buildDumpArgs, buildLaunchPluginArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, scrollbackPayload, waitPayload, type LaunchPluginInput, type NewPaneInput, type NewTabInput, type PaneDirection, type PipeInput, type ScrollbackRequest, type WaitRequest, } from "./zellij/args.js";
+export { busPluginUrl, busToPanes, isBusPluginPane, nextConfigKey, parseBusReply, parseScrollbackReply, resolveBusPlugin, scrollbackToScreen, BUS_PIPE_NAME, DEFAULT_BUS_KEY, DEFAULT_BUS_TIMEOUT_MS, type BusMarker, type BusPane, type BusScrollback, type BusScrollbackPane, type BusSnapshot, } from "./zellij/bus.js";
+export { busSnapshot, closeBusPluginPanes, planBus, resetBusCache, type BusPlan, } from "./ops/bus.js";
 export { createZellijClient, type ZellijClient, type ZellijClientOptions, } from "./zellij/client.js";
 export { createStateStore, defaultStateDir, type LogEntry, type SignalChannel, type StateStore, type StateStoreOptions, } from "./state.js";
 export { dispatchZswarm } from "./ops/dispatch.js";
@@ -14,7 +14,7 @@ export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, type Policy,
 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, isLoopbackHost, parseListenAddress, 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, 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 { 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

@@ -4,9 +4,9 @@ export { createGitClient, defaultWorktreeRoot, normalizeRepoPath, parseWorktreeL
 export { expandHomePath, resolveZellijBinary, sanitizeZellijEnv, } from "./zellij/binary.js";
 export { normalizePaneId, parsePaneList, resolvePane, } from "./zellij/panes.js";
 export { parseSessionList, resolveSelfPaneId, } from "./zellij/session.js";
-export { buildClosePaneArgs, buildDumpArgs, buildLaunchPluginArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, scrollbackPayload, } from "./zellij/args.js";
-export { busPluginUrl, busToPanes, nextConfigKey, parseBusReply, parseScrollbackReply, resolveBusPlugin, scrollbackToScreen, BUS_PIPE_NAME, DEFAULT_BUS_KEY, DEFAULT_BUS_TIMEOUT_MS, } from "./zellij/bus.js";
-export { busSnapshot, planBus, resetBusCache, } from "./ops/bus.js";
+export { buildClosePaneArgs, buildDumpArgs, buildLaunchPluginArgs, buildListPanesArgs, buildNewPaneArgs, buildNewTabArgs, buildPasteArgs, buildPipeArgs, buildSendEnterArgs, buildSendKeysArgs, buildWriteCharsArgs, scrollbackPayload, waitPayload, } from "./zellij/args.js";
+export { busPluginUrl, busToPanes, isBusPluginPane, nextConfigKey, parseBusReply, parseScrollbackReply, resolveBusPlugin, scrollbackToScreen, BUS_PIPE_NAME, DEFAULT_BUS_KEY, DEFAULT_BUS_TIMEOUT_MS, } from "./zellij/bus.js";
+export { busSnapshot, closeBusPluginPanes, planBus, resetBusCache, } from "./ops/bus.js";
 export { createZellijClient, } from "./zellij/client.js";
 export { createStateStore, defaultStateDir, } from "./state.js";
 export { dispatchZswarm } from "./ops/dispatch.js";
@@ -14,7 +14,7 @@ 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, 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, 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 { parseTabList, resolveTab } from "./zellij/tabs.js";
 export { selectTargets } from "./ops/broadcast.js";
 export { diffScreens, cursorKey } from "./ops/tail.js";

package/dist/ops/broadcast.d.ts

@@ -16,4 +16,4 @@ export declare function selectTargets(client: ZellijClient, panes: ZellijPane[],
     skipped: Skipped[];
 };
 /** Send one body to many panes, reporting per-pane outcomes. */
-export declare function broadcast(client: ZellijClient, state: StateStore, args: Record<string, unknown>, clock: Clock, policy?: Policy): Promise<OpsResult>;
+export declare function broadcast(client: ZellijClient, state: StateStore, args: Record<string, unknown>, clock: Clock, policy?: Policy, env?: NodeJS.ProcessEnv): Promise<OpsResult>;

package/dist/ops/broadcast.js

@@ -1,6 +1,6 @@
 import { ZellijError } from "../errors.js";
 import { assertPaneAllowed } from "../policy.js";
-import { deliverTo } from "./delivery.js";
+import { deliverTo, selfPaneTitle, withSenderLabel } from "./delivery.js";
 import { isTrue, optionalString } from "./util.js";
 /**
  * Pick the panes a broadcast should reach: an explicit comma list, a tab, or
@@ -65,13 +65,17 @@ export function selectTargets(client, panes, args) {
     return { targets, skipped };
 }
 /** Send one body to many panes, reporting per-pane outcomes. */
-export async function broadcast(client, state, args, clock, policy) {
+export async function broadcast(client, state, args, clock, policy, env = process.env) {
     const body = String(args.body ?? args.text ?? "");
     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 { targets: selected, skipped } = selectTargets(client, panes, args);
+    const labeled = withSenderLabel(args, {
+        env,
+        selfTitle: selfPaneTitle(client, panes),
+    });
+    const { targets: selected, skipped } = selectTargets(client, panes, labeled);
     // Policy narrows the selection rather than failing the whole broadcast.
     const targets = selected.filter((pane) => {
         if (!policy)
@@ -90,7 +94,7 @@ export async function broadcast(client, state, args, clock, policy) {
     }
     const results = [];
     for (const pane of targets) {
-        results.push(await deliverTo(client, state, args, {
+        results.push(await deliverTo(client, state, labeled, {
             session,
             pane,
             body,
@@ -104,7 +108,7 @@ export async function broadcast(client, state, args, clock, policy) {
         ok: true,
         data: {
             session,
-            from: (typeof args.from === "string" && args.from.trim()) || "swarm",
+            from: labeled.from,
             delivered: delivered.map((r) => r.to),
             failed: results.filter((r) => !r.ok),
             skipped,

package/dist/ops/bus.d.ts

@@ -1,4 +1,4 @@
-import type { Policy } from "../policy.js";
+import { type Policy } from "../policy.js";
 import type { StateStore } from "../state.js";
 import { type BusChanged, type BusSnapshot, type BusWait } from "../zellij/bus.js";
 import type { WaitRequest } from "../zellij/args.js";
@@ -15,15 +15,16 @@ export type BusPlan = {
 };
 /** Tests share a module instance; this drops what a previous case cached. */
 export declare function resetBusCache(): void;
-export declare function planBus(client: ZellijClient, state: StateStore, env?: NodeJS.ProcessEnv): BusPlan;
+export declare function planBus(client: ZellijClient, state: StateStore, env?: NodeJS.ProcessEnv, session?: string): BusPlan;
 /**
  * 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 declare function busSnapshot(client: ZellijClient, state: StateStore, session: string, clock: Clock, env?: NodeJS.ProcessEnv, payload?: string): Promise<{
     snapshot: BusSnapshot;
@@ -56,5 +57,7 @@ export declare function busWait(client: ZellijClient, state: StateStore, session
  * relative to the previous call rather than a fixed window.
  */
 export declare function busChanged(client: ZellijClient, state: StateStore, session: string, paneIds: string[], env?: NodeJS.ProcessEnv): Promise<BusChanged | null>;
+/** Close every zswarm-bus plugin pane in this session. Best-effort per pane. */
+export declare function closeBusPluginPanes(client: ZellijClient, session: string, pluginPath: string | null): Promise<string[]>;
 /** Report on the bus, install it, or forget it. */
 export declare function busOp(client: ZellijClient, state: StateStore, args: Record<string, unknown>, clock: Clock, env?: NodeJS.ProcessEnv, policy?: Policy): Promise<OpsResult>;

package/dist/ops/bus.js

@@ -1,6 +1,7 @@
 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 { loadPolicy } from "../policy.js";
+import { DEFAULT_BUS_KEY, busPluginUrl, isBusPluginPane, parseBusReply, parseChangedReply, parseScrollbackReply, parseWaitReply, resolveBusPlugin, scrollbackToScreen, } from "../zellij/bus.js";
 import { isTrue } from "./util.js";
 /**
  * Whether to ask the event-bus plugin, and what to do when it does not answer.
@@ -9,10 +10,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 +35,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;
@@ -75,7 +80,9 @@ 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) {
+async function nudgeManifest(client, session, env) {
+    if (loadPolicy(env).readOnly)
+        return;
     const panes = await client.listPanes(session);
     const pane = panes.find((p) => !p.isPlugin && !p.exited && p.title.trim());
     if (!pane)
@@ -85,52 +92,40 @@ async function nudgeManifest(client, session) {
 /**
  * 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);
+    const plan = planBus(client, state, env, session);
     const pluginPath = plan.plugin;
     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) {
-            await clock.sleep(COLD_RETRY_MS);
+    const configKey = answeredWith.get(session) ?? plan.configKey;
+    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) {
+        try {
+            await nudgeManifest(client, session, env);
             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.
-            }
-        }
-        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 {
+            // A failed nudge must not fail the op — the caller polls instead.
         }
-        configKey = nextConfigKey(configKey);
+    }
+    if (snapshot) {
+        answeredWith.set(session, configKey);
+        return { snapshot, configKey };
     }
     processDisabled = "plugin did not answer; using zellij polling for this run";
     return null;
@@ -149,7 +144,7 @@ export async function busSnapshot(client, state, session, clock, env = process.e
 export async function busScreens(client, state, session, paneIds, clock, env = process.env) {
     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;
@@ -179,7 +174,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;
@@ -202,7 +197,7 @@ export async function busWait(client, state, session, request, env = process.env
 export async function busChanged(client, state, session, paneIds, env = process.env) {
     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;
@@ -217,14 +212,63 @@ export async function busChanged(client, state, session, paneIds, env = process.
         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 +278,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 +311,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

@@ -14,7 +14,37 @@ export type DeliveryResult = {
     };
 };
 export type SubmitMode = "auto" | "double-enter" | "none";
-export declare function senderLabel(args: Record<string, unknown>): string;
+export type SenderSource = "arg" | "env" | "title" | "default";
+export type SenderLabel = {
+    label: string;
+    source: SenderSource;
+};
+/** Drop characters that would break `[zswarm from=…]` or wrap the prefix. */
+export declare function sanitizeSenderLabel(raw: string): string;
+export declare function selfPaneTitle(client: Pick<ZellijClient, "selfPaneId">, panes: ZellijPane[]): string | null;
+/**
+ * Label for `[zswarm from=…]`. Explicit `from` wins, then `ZSWARM_FROM`,
+ * then the sending pane's title when we know that pane, else `swarm`.
+ */
+export declare function resolveSender(args: Record<string, unknown>, opts?: {
+    env?: NodeJS.ProcessEnv;
+    selfTitle?: string | null;
+}): SenderLabel;
+export declare function senderLabel(args: Record<string, unknown>, opts?: {
+    env?: NodeJS.ProcessEnv;
+    selfTitle?: string | null;
+}): string;
+/** Stamp `from` so deliverTo and the op result use the same resolved label. */
+export declare function withSenderLabel(args: Record<string, unknown>, opts?: {
+    env?: NodeJS.ProcessEnv;
+    selfTitle?: string | null;
+}): Record<string, unknown>;
+/**
+ * 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;
 /**
  * Caller `submit=` always wins. With none given, the pane's harness picks

package/dist/ops/delivery.js

@@ -2,8 +2,59 @@ import { resolveHarness } from "../harness.js";
 import { isTrue, numberArg } from "./util.js";
 /** Cursor / Claude leave this in scrollback after a successful submit. */
 const PASTE_MARKER = "[Pasted text";
-export function senderLabel(args) {
-    return (typeof args.from === "string" && args.from.trim()) || "swarm";
+const SENDER_LABEL_MAX = 48;
+/** Drop characters that would break `[zswarm from=…]` or wrap the prefix. */
+export function sanitizeSenderLabel(raw) {
+    const cleaned = raw.replace(/[\r\n[\]]+/g, " ").replace(/\s+/g, " ").trim();
+    if (!cleaned)
+        return "";
+    return cleaned.length <= SENDER_LABEL_MAX
+        ? cleaned
+        : cleaned.slice(0, SENDER_LABEL_MAX).trimEnd();
+}
+export function selfPaneTitle(client, panes) {
+    const id = client.selfPaneId;
+    if (!id)
+        return null;
+    const title = panes.find((p) => p.id === id)?.title;
+    return title?.trim() ? title : null;
+}
+/**
+ * Label for `[zswarm from=…]`. Explicit `from` wins, then `ZSWARM_FROM`,
+ * then the sending pane's title when we know that pane, else `swarm`.
+ */
+export function resolveSender(args, opts = {}) {
+    if (typeof args.from === "string") {
+        const explicit = sanitizeSenderLabel(args.from);
+        if (explicit)
+            return { label: explicit, source: "arg" };
+    }
+    const envFrom = sanitizeSenderLabel(opts.env?.ZSWARM_FROM ?? "");
+    if (envFrom)
+        return { label: envFrom, source: "env" };
+    const title = sanitizeSenderLabel(opts.selfTitle ?? "");
+    if (title)
+        return { label: title, source: "title" };
+    return { label: "swarm", source: "default" };
+}
+export function senderLabel(args, opts = {}) {
+    return resolveSender(args, opts).label;
+}
+/** Stamp `from` so deliverTo and the op result use the same resolved label. */
+export function withSenderLabel(args, opts = {}) {
+    return { ...args, from: senderLabel(args, opts) };
+}
+/**
+ * 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 });
+    return { ...args, from: sender.label };
 }
 export function bodyText(client, args, body) {
     return isTrue(args.raw) ? body : client.formatPeerMessage(senderLabel(args), body);