@zswarm/core 0.1.5 → 0.1.7

package/dist/ops/status.js

@@ -1,5 +1,6 @@
+import { ZellijError } from "../errors.js";
 import { resolveHarness } from "../harness.js";
-import { isTrue, normalizeScreen, numberArg, optionalString } from "./util.js";
+import { isTrue, normalizeScreen, numberArg, optionalString, throwIfAborted, } from "./util.js";
 /**
  * Legacy last-line prompt shapes for callers without a profile. A term counts
  * only when it is a question, not chrome: a y/n form, a trailing `?`, or the
@@ -18,6 +19,10 @@ const QUESTION = /(\(y\/n\)|\[y\/n\]|\(yes\/no\)|\[y\/n\/a\]|password:|passphras
  * where it is or it would fire on chrome.
  */
 const PROMPT_WINDOW = 24;
+/** Default overall budget for a sampled status pass (covers IPC + dumps). */
+export const DEFAULT_STATUS_TIMEOUT_MS = 30_000;
+/** How many dump-screen calls to run at once on the direct (non-bus) path. */
+export const STATUS_DUMP_CONCURRENCY = 3;
 export function lastLine(screen) {
     const lines = screen.split("\n").filter((l) => l.trim());
     return lines.length > 0 ? lines[lines.length - 1].trim() : "";
@@ -30,25 +35,39 @@ function trailingLines(screen, n) {
         .filter((line) => line.length > 0)
         .slice(-n);
 }
-/**
- * True when the trailing window holds a named approval prompt. The profile's
- * waiting patterns run across the window; the legacy last-line QUESTION check
- * stays as the conservative fallback for callers without a profile. Bias is
- * toward false negatives: a hit must be prompt UI we can name, never a bare
- * question mark or "confirm".
- */
-function promptHolds(screen, profile) {
+export function waitingPrompt(screen, profile) {
     const lines = trailingLines(screen, PROMPT_WINDOW);
-    const patterns = profile?.waiting;
-    if (patterns && patterns.length > 0) {
-        for (const line of lines) {
-            for (const re of patterns) {
-                if (re.test(line))
-                    return true;
-            }
+    // A menu requires a choice structure AND navigation chrome. A lone "Allow
+    // once" in logs/help must not turn a worker into an approval request.
+    const choices = lines.filter((line) => /^(?:[›❯>●]\s*)?\d+[.)]\s+(?:Yes\b|No\b|Allow\b|Deny\b|Cancel\b)/i.test(line));
+    const navigation = lines.some((line) => /(?:enter|return)\s+(?:to\s+)?(?:select|confirm)|(?:esc|escape)\s+(?:to\s+)?cancel/i.test(line));
+    const approval = lines.find((line) => /^(?:[›❯>]\s*)?(?:Approve (?:this|the) (?:operation|command|action)|Approval required|Would you like to run the following command\?|Run this command\?)[?:]?$/i.test(line));
+    if (approval && choices.length >= 2 && navigation) {
+        return { reason: "approval_menu", evidence: choices.slice(0, 3).join("\n").slice(0, 320), source: "screen" };
+    }
+    for (const line of lines) {
+        if (profile?.waiting.some((re) => re.test(line))) {
+            return { reason: "prompt", evidence: line.slice(0, 320), source: "screen" };
         }
     }
-    return QUESTION.test(lines[lines.length - 1] ?? "");
+    const last = lines[lines.length - 1] ?? "";
+    return QUESTION.test(last) ? { reason: "prompt", evidence: last.slice(0, 320), source: "screen" } : null;
+}
+function promptHolds(screen, profile) {
+    return waitingPrompt(screen, profile) !== null;
+}
+/** Compact summary of the selected terminal peers, including inactive tabs. */
+export function statusTabs(peers) {
+    const tabs = new Map();
+    for (const peer of peers) {
+        const key = JSON.stringify([peer.tabId, peer.tab]);
+        const tab = tabs.get(key) ?? { id: peer.tabId, name: peer.tab, panes: 0, states: {} };
+        tab.panes++;
+        const state = String(peer.state);
+        tab.states[state] = (tab.states[state] ?? 0) + 1;
+        tabs.set(key, tab);
+    }
+    return [...tabs.values()];
 }
 export function classify(input) {
     if (input.exited)
@@ -57,72 +76,121 @@ export function classify(input) {
         return "busy";
     return promptHolds(input.after, input.profile) ? "waiting" : "idle";
 }
+/** Run `fn` over items with at most `limit` in flight. */
+export async function mapPool(items, limit, fn) {
+    if (items.length === 0)
+        return [];
+    const concurrency = Math.max(1, Math.min(limit, items.length));
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        while (next < items.length) {
+            const i = next++;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    await Promise.all(Array.from({ length: concurrency }, () => worker()));
+    return results;
+}
+function isCancelledError(err) {
+    return ((err instanceof ZellijError && err.code === "cancelled") ||
+        (err instanceof Error && /cancelled/i.test(err.message)));
+}
+function peerEntry(pane, state, screen, verbose, extra) {
+    const entry = {
+        id: pane.id,
+        title: pane.title,
+        tab: pane.tabName ?? null,
+        tabId: pane.tabId ?? null,
+        state,
+        lastLine: lastLine(screen).slice(0, 160),
+        ...extra,
+    };
+    if (state === "waiting")
+        entry.waiting = waitingPrompt(screen, resolveHarness(pane));
+    if (verbose) {
+        entry.command = pane.command ?? null;
+        entry.cwd = pane.cwd ?? null;
+    }
+    return entry;
+}
 /**
  * Sample every pane twice and say who is working, who is stuck on a prompt,
  * and who is free — the routing question `list` cannot answer.
+ *
+ * `deadlineAt` is the absolute clock deadline for the whole status op (setup
+ * included). When omitted, one is derived from `timeoutMs` at entry.
  */
-export async function peerStatus(client, args, clock, supplied) {
+export async function peerStatus(client, args, clock, supplied, opts = {}) {
+    const signal = opts.signal;
+    throwIfAborted(signal);
+    const budget = numberArg(args, "timeoutMs", DEFAULT_STATUS_TIMEOUT_MS, {
+        min: 1_000,
+        max: 900_000,
+    });
+    const deadline = opts.deadlineAt ?? clock.now() + budget;
+    const remaining = () => Math.max(0, deadline - clock.now());
+    const setupBudget = () => {
+        throwIfAborted(signal);
+        const left = remaining();
+        if (left <= 0) {
+            throw new ZellijError("zellij_failed", "status timed out during setup");
+        }
+        return left;
+    };
+    // Prefer the caller's already-resolved session/panes so dispatch's setup
+    // budget is not spent twice.
     const session = supplied?.session ??
-        (await client.resolveSession(typeof args.session === "string" ? args.session : undefined)).session;
-    const panes = supplied?.panes ?? (await client.listPanes(session));
+        (await client.resolveSession(typeof args.session === "string" ? args.session : undefined, setupBudget())).session;
+    throwIfAborted(signal);
+    const panes = supplied?.panes ?? (await client.listPanes(session, setupBudget()));
+    throwIfAborted(signal);
     const source = supplied?.source ?? "zellij";
     const only = optionalString(args.to);
+    const verbose = isTrue(args.verbose);
     const targets = only
         ? [client.resolvePane(panes, only)]
         : panes.filter((p) => !p.isPlugin);
-    // sampleMs=0 asks for the cheap answer: who is alive, from state the plugin
-    // already holds. Below that, two samples too close together read as idle.
     const requested = numberArg(args, "sampleMs", 400, { min: 0, max: 10_000 });
     if (requested === 0) {
         const peers = targets
-            .map((pane) => {
-            const entry = {
-                id: pane.id,
-                title: pane.title,
-                state: pane.exited ? "exited" : "running",
-            };
-            if (isTrue(args.verbose)) {
-                entry.command = pane.command ?? null;
-                entry.cwd = pane.cwd ?? null;
-                entry.tab = pane.tabName ?? null;
-            }
-            return entry;
-        })
+            .map((pane) => peerEntry(pane, pane.exited ? "exited" : "running", "", verbose))
             .sort((a, b) => String(a.id).localeCompare(String(b.id)));
-        // No `free`: without sampling there is no way to tell busy from idle.
         return {
             ok: true,
-            data: { session, source, sampled: false, sampleMs: 0, peers },
+            data: { session, source, sampled: false, sampleMs: 0, peers, tabs: statusTabs(peers) },
         };
     }
     const sampleMs = Math.max(50, requested);
-    const live = targets.filter((pane) => !pane.exited).map((pane) => pane.id);
-    // sinceLast trades the fixed 400ms window for "moved since your last call".
-    // The plugin remembers the previous screen, so there is no gap to wait out —
-    // but ask twice in quick succession and everything reads idle.
-    if (isTrue(args.sinceLast) && supplied?.readChanged) {
-        const changed = await supplied.readChanged(live);
+    const live = targets.filter((pane) => !pane.exited);
+    // Explicit sampling retains its interval semantics. Ordinary status prefers
+    // one bus observation, including a single-pane crew, with no sample sleep.
+    const preferChanges = isTrue(args.sinceLast) || (args.sinceLast === undefined && args.sampleMs === undefined);
+    if (preferChanges && supplied?.readChanged) {
+        const left = remaining();
+        let changed = null;
+        try {
+            changed = live.length === 0 ? new Map() : left > 0 ? await supplied.readChanged(live.map((p) => p.id), left) : null;
+        }
+        catch (err) {
+            if (isCancelledError(err) || signal?.aborted)
+                throw new ZellijError("cancelled", "operation cancelled");
+            // A missing/older bus falls back to bounded screen samples below.
+        }
+        throwIfAborted(signal);
         if (changed) {
             const peers = targets
                 .map((pane) => {
+                if (pane.exited) {
+                    return peerEntry(pane, "exited", "", verbose);
+                }
                 const row = changed.get(pane.id);
-                const state = pane.exited
-                    ? "exited"
-                    : row?.changed
-                        ? "busy"
-                        : promptHolds(row?.screen ?? "", resolveHarness(pane))
-                            ? "waiting"
-                            : "idle";
-                const entry = {
-                    id: pane.id,
-                    title: pane.title,
-                    state,
-                    lastLine: lastLine(row?.screen ?? "").slice(0, 160),
-                };
-                // First sight has nothing to compare against, so idle is a guess.
-                if (row?.first)
-                    entry.first = true;
-                return entry;
+                const state = !row ? "unknown"
+                    : promptHolds(row.screen, resolveHarness(pane)) ? "waiting"
+                        : row.first ? "unknown" : row.changed ? "busy" : "idle";
+                return peerEntry(pane, state, row?.screen ?? "", verbose, {
+                    ...(row?.first ? { first: true } : {}),
+                });
             })
                 .sort((a, b) => String(a.id).localeCompare(String(b.id)));
             return {
@@ -132,61 +200,142 @@ export async function peerStatus(client, args, clock, supplied) {
                     source,
                     sampled: false,
                     sinceLast: true,
+                    observation: "bus-changes",
                     peers,
+                    tabs: statusTabs(peers),
                     free: peers.filter((p) => p.state === "idle").map((p) => p.id),
                 },
             };
         }
     }
     /**
-     * One batched read when the bus can serve it, otherwise a process per pane.
-     * Both paths normalize, which is what makes them comparable: the plugin pads
-     * lines to the terminal width and `dump-screen` does not.
+     * Bus path: one batched read per round, each bounded by the remaining budget.
+     * Direct path: each pane completes its own before→sleep→after pair under a
+     * shared concurrency limit so one stall does not block healthy peers.
      */
-    const sample = async () => {
-        const batched = supplied?.readScreens
-            ? await supplied.readScreens(live)
-            : null;
-        if (batched) {
-            return new Map([...batched].map(([id, text]) => [id, normalizeScreen(text)]));
+    const samples = new Map();
+    if (supplied?.readScreens) {
+        const sampleRound = async () => {
+            throwIfAborted(signal);
+            const left = remaining();
+            if (left <= 0) {
+                return new Map(live.map((p) => [p.id, null]));
+            }
+            try {
+                const batched = await supplied.readScreens(live.map((p) => p.id), left);
+                throwIfAborted(signal);
+                if (!batched)
+                    return new Map(); // signal fallback to dumps below
+                return new Map(live.map((p) => {
+                    const text = batched.get(p.id);
+                    return [
+                        p.id,
+                        text === undefined ? null : normalizeScreen(text),
+                    ];
+                }));
+            }
+            catch (err) {
+                if (isCancelledError(err) || signal?.aborted) {
+                    throw new ZellijError("cancelled", "operation cancelled");
+                }
+                return new Map(live.map((p) => [p.id, null]));
+            }
+        };
+        let before = await sampleRound();
+        if (before.size === 0) {
+            // Bus declined — fall through to per-pane dumps.
+            before = new Map();
         }
-        const screens = new Map();
-        for (const id of live) {
-            const dumped = await client.dumpPane({ session, paneId: id });
-            screens.set(id, normalizeScreen(dumped.text));
+        else {
+            let after = new Map();
+            if (remaining() > sampleMs) {
+                await clock.sleep(sampleMs);
+                throwIfAborted(signal);
+                after = await sampleRound();
+            }
+            for (const pane of live) {
+                samples.set(pane.id, {
+                    before: before.get(pane.id) ?? null,
+                    after: after.get(pane.id) ?? null,
+                });
+            }
         }
-        return screens;
-    };
-    const before = await sample();
-    await clock.sleep(sampleMs);
-    const afterScreens = await sample();
+    }
+    if (samples.size === 0) {
+        // Per-pane sample pairs under bounded concurrency.
+        await mapPool(live, STATUS_DUMP_CONCURRENCY, async (pane) => {
+            throwIfAborted(signal);
+            const dumpOne = async () => {
+                const left = remaining();
+                if (left <= 0)
+                    return null;
+                try {
+                    const dumped = await client.dumpPane({
+                        session,
+                        paneId: pane.id,
+                        timeoutMs: left,
+                    });
+                    throwIfAborted(signal);
+                    return normalizeScreen(dumped.text);
+                }
+                catch (err) {
+                    if (isCancelledError(err) || signal?.aborted) {
+                        throw new ZellijError("cancelled", "operation cancelled");
+                    }
+                    return null;
+                }
+            };
+            const before = await dumpOne();
+            throwIfAborted(signal);
+            let after = null;
+            // This pane's interval starts when its first screen is available. Queue
+            // time and a slow first read cannot replace time between observations.
+            // Without room for the whole interval, keep it unknown rather than idle.
+            if (before !== null && remaining() > sampleMs) {
+                await clock.sleep(sampleMs);
+                throwIfAborted(signal);
+                after = await dumpOne();
+            }
+            samples.set(pane.id, { before, after });
+        });
+    }
+    throwIfAborted(signal);
     const peers = [];
+    let partial = false;
     for (const pane of targets) {
-        const first = before.get(pane.id) ?? "";
-        const after = pane.exited ? first : (afterScreens.get(pane.id) ?? "");
+        if (pane.exited) {
+            peers.push(peerEntry(pane, "exited", "", verbose));
+            continue;
+        }
+        const pair = samples.get(pane.id);
+        const first = pair?.before ?? null;
+        const after = pair?.after ?? null;
+        if (first == null || after == null) {
+            partial = true;
+            peers.push(peerEntry(pane, "unknown", after ?? first ?? "", verbose));
+            continue;
+        }
         const state = classify({
-            exited: pane.exited,
+            exited: false,
             before: first,
             after,
             profile: resolveHarness(pane),
         });
-        const entry = {
-            id: pane.id,
-            title: pane.title,
-            state,
-            lastLine: lastLine(after).slice(0, 160),
-        };
-        if (isTrue(args.verbose)) {
-            entry.command = pane.command ?? null;
-            entry.cwd = pane.cwd ?? null;
-            entry.tab = pane.tabName ?? null;
-        }
-        peers.push(entry);
+        peers.push(peerEntry(pane, state, after, verbose));
     }
     peers.sort((a, b) => String(a.id).localeCompare(String(b.id)));
     const free = peers.filter((p) => p.state === "idle").map((p) => p.id);
-    return {
-        ok: true,
-        data: { session, source, sampled: true, sampleMs, peers, free },
+    const data = {
+        session,
+        source,
+        sampled: true,
+        observation: "samples",
+        sampleMs,
+        peers,
+        tabs: statusTabs(peers),
+        free,
     };
+    if (partial || remaining() <= 0)
+        data.partial = true;
+    return { ok: true, data };
 }

package/dist/ops/types.d.ts

@@ -1,4 +1,5 @@
-export type OpsResult = {
+import type { RoutingContext } from "./routing.js";
+export type OpsResult = ({
     ok: true;
     data: unknown;
 } | {
@@ -6,7 +7,10 @@ export type OpsResult = {
     error: {
         code: string;
         message: string;
+        details?: Record<string, unknown>;
     };
+}) & {
+    context?: RoutingContext;
 };
 import type { GitClient } from "../git.js";
 import type { Policy } from "../policy.js";

package/dist/ops/util.d.ts

@@ -13,6 +13,7 @@ export declare function paneViewSlim(p: ZellijPane): {
     title: string;
     command: string | null;
     tab: string | null;
+    tabId: number | null;
 };
 /**
  * The event-bus view. Zellij's pane manifest carries no command, so the key is
@@ -22,6 +23,7 @@ export declare function paneViewBus(p: ZellijPane): {
     id: string;
     title: string;
     tab: string | null;
+    tabId: number | null;
 };
 export declare function paneViewFull(p: ZellijPane): {
     cwd: string | null;
@@ -32,6 +34,7 @@ export declare function paneViewFull(p: ZellijPane): {
     title: string;
     command: string | null;
     tab: string | null;
+    tabId: number | null;
 };
 /** Truncate dump text; default keeps the tail (recent output). */
 export declare function truncateDumpText(text: string, maxChars: number, keep?: "tail" | "head"): {

package/dist/ops/util.js

@@ -25,6 +25,7 @@ export function paneViewSlim(p) {
         title: p.title,
         command: p.command ?? null,
         tab: p.tabName ?? null,
+        tabId: p.tabId ?? null,
     };
 }
 /**
@@ -32,7 +33,7 @@ export function paneViewSlim(p) {
  * left out rather than reported as null — absent means unknown, not none.
  */
 export function paneViewBus(p) {
-    return { id: p.id, title: p.title, tab: p.tabName ?? null };
+    return { id: p.id, title: p.title, tab: p.tabName ?? null, tabId: p.tabId ?? null };
 }
 export function paneViewFull(p) {
     return {

package/dist/ops/worktree.js

@@ -62,7 +62,7 @@ export async function listPeerWorktrees(git, client, args) {
     let panes = [];
     try {
         const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
-        panes = await client.listPanes(session);
+        panes = await client.listPanes(session, undefined, { fresh: true });
     }
     catch {
         // Worktrees are useful to list even with no live Zellij session.
@@ -118,7 +118,7 @@ export async function removePeerWorktree(git, client, args, env = process.env) {
     let occupants = [];
     try {
         const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
-        occupants = panesIn(await client.listPanes(session), target.path);
+        occupants = panesIn(await client.listPanes(session, undefined, { fresh: true }), target.path);
     }
     catch (err) {
         // No live session means nobody is working in it. Any other failure must

package/dist/schema.d.ts

@@ -14,6 +14,8 @@ export type ParamSpec = {
     flags: string[];
     /** Repeatable flags collect into an array (`--key a --key b`). */
     repeat?: boolean;
+    /** Local CLI preprocessing, excluded from the MCP protocol. */
+    cliOnly?: boolean;
     values?: readonly string[];
     description: string;
 };

package/dist/schema.js

@@ -63,7 +63,25 @@ export const PARAMS = [
         name: "all",
         type: "boolean",
         flags: ["--all", "-a"],
-        description: "broadcast: every terminal pane in the session",
+        description: "broadcast: every terminal pane in the session; sessions: include EXITED resurrectable sessions",
+    },
+    {
+        name: "live",
+        type: "boolean",
+        flags: ["--live", "--active"],
+        description: "sessions: only live (non-EXITED) sessions — this is the default; use --all to include EXITED",
+    },
+    {
+        name: "local",
+        type: "boolean",
+        flags: ["--local"],
+        description: "route this call to the local machine only — clears ZSWARM_SSH, ZSWARM_SERVE, and remote ZSWARM_TMP for the invocation",
+    },
+    {
+        name: "ssh",
+        type: "string",
+        flags: ["--ssh"],
+        description: "route this call over SSH to user@host (or an alias) for the invocation; clears ZSWARM_SERVE; put flags in ZSWARM_SSH_OPTS",
     },
     {
         name: "group",
@@ -111,13 +129,25 @@ export const PARAMS = [
         name: "sampleMs",
         type: "number",
         flags: ["--sample-ms"],
-        description: "status: gap between the two screen samples (default 400); 0 skips sampling and reports running/exited only",
+        description: "status: explicitly sample twice with this gap (fallback default 400); 0 reports running/exited only; default prefers bus changes",
     },
     {
         name: "sinceLast",
         type: "boolean",
         flags: ["--since-last"],
-        description: "status: classify by what changed since the last status call instead of sampling twice; needs the event bus, no sample gap",
+        description: "status: classify changes since the previous bus observation (default when bus available); first observation is unknown unless a prompt is recognized",
+    },
+    {
+        name: "fresh",
+        type: "boolean",
+        flags: ["--fresh"],
+        description: "bypass the short-lived session/pane/tab listing cache for this call",
+    },
+    {
+        name: "serveAddress",
+        type: "string",
+        flags: ["--serve"],
+        description: "use an existing serve endpoint (e.g. 127.0.0.1:9419 through an SSH tunnel); preferred for frequent status calls; uses ZSWARM_SERVE_TOKEN",
     },
     {
         name: "limit",
@@ -143,6 +173,13 @@ export const PARAMS = [
         flags: ["--body", "-b", "--text"],
         description: "send: message body",
     },
+    {
+        name: "bodyFile",
+        type: "string",
+        flags: ["--body-file"],
+        cliOnly: true,
+        description: "send: read UTF-8 on the caller from PATH, or - for stdin; cannot combine with --body/--text",
+    },
     {
         name: "text",
         type: "string",
@@ -220,7 +257,7 @@ export const PARAMS = [
         name: "timeoutMs",
         type: "number",
         flags: ["--timeout-ms"],
-        description: "wait: give up after this long (default 60000)",
+        description: "wait: timeout (default 60000); status/spawn: overall deadline (default 30000), including setup and observation",
     },
     {
         name: "keys",
@@ -302,6 +339,12 @@ export const PARAMS = [
         values: ["auto", "double-enter", "none"],
         description: "send/broadcast: auto verifies the paste actually submitted and presses Enter again if not (default)",
     },
+    {
+        name: "observeMs",
+        type: "number",
+        flags: ["--observe-ms"],
+        description: "spawn: observe creation/alias for up to 3000ms; pane lookup: retry absence for 1000ms; 0 disables retries",
+    },
     {
         name: "settleMs",
         type: "number",
@@ -312,7 +355,7 @@ export const PARAMS = [
         name: "expect",
         type: "string",
         flags: ["--expect"],
-        description: "text the target pane's screen must contain before zswarm will write to it",
+        description: "send/keys/interrupt: case-insensitive substring required on the current screen immediately before input",
     },
     {
         name: "message",
@@ -423,8 +466,10 @@ export function mcpInputSchema() {
             description: OP_NAMES.join(" | "),
         },
     };
-    for (const param of PARAMS)
-        properties[param.name] = propertyFor(param);
+    for (const param of PARAMS) {
+        if (!param.cliOnly)
+            properties[param.name] = propertyFor(param);
+    }
     return {
         type: "object",
         additionalProperties: false,
@@ -450,7 +495,7 @@ export function cliUsage() {
         const value = param.type === "boolean" ? "" : param.type === "number" ? " N" : " VALUE";
         lines.push(`  ${param.flags.join(", ").padEnd(28)}${value.trim().padEnd(6)}${param.description}`);
     }
-    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once per Zellij session. `--force` closes orphan bus panes and reloads; do not use it as a retry.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE (+ ZSWARM_SERVE_TOKEN). Serve binds loopback only and always requires a token.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN", "");
+    lines.push("", "Guards: writes refuse zswarm's own pane (--allow-self) and exited panes (--force). --expect requires the screen to contain a substring first.", "Bus: `zswarm bus --install` once per Zellij session. `--force` closes orphan bus panes and reloads; do not use it as a retry.", "Remote: ZSWARM_SSH (+ ZSWARM_TMP=auto or ZSWARM_SSH_MODE=interactive on Windows). Or run `zswarm serve --listen` next to Zellij and set ZSWARM_SERVE (+ ZSWARM_SERVE_TOKEN). Serve binds loopback only and always requires a token.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_CACHE_TTL_MS", "");
     return lines.join("\n");
 }
 /** Turn argv (without the op) into dispatch args, driven by PARAMS. */
@@ -499,6 +544,9 @@ export function parseCliArgv(argv) {
                 out[param.name] = true;
                 continue;
             }
+            if ((param.name === "body" || param.name === "bodyFile") && Object.hasOwn(out, param.name)) {
+                throw new ZellijError("usage", "provide exactly one body source");
+            }
             const value = rest[++i];
             if (value === undefined) {
                 throw new ZellijError("usage", `${token} needs a value`);
@@ -519,7 +567,7 @@ export function parseCliArgv(argv) {
             out.to = token;
             continue;
         }
-        if (!out.body && op === "send") {
+        if (!Object.hasOwn(out, "body") && op === "send") {
             out.body = token;
             continue;
         }
@@ -527,5 +575,8 @@ export function parseCliArgv(argv) {
     }
     for (const [name, values] of repeated)
         out[name] = values;
+    if (out.bodyFile !== undefined && (op !== "send" || out.body !== undefined || out.text !== undefined)) {
+        throw new ZellijError("usage", "--body-file requires send and cannot be combined with another body source");
+    }
     return out;
 }