@zswarm/core 0.8.1 → 0.8.3

package/dist/harness.d.ts

@@ -66,6 +66,15 @@ export declare function queuedPrompt(screen: string, profile: HarnessProfile): b
 export declare function busyMarker(screen: string, profile: HarnessProfile): RegExp | null;
 /** Does this screen's trailing lines show the harness actively working? */
 export declare function busyPrompt(screen: string, profile: HarnessProfile): boolean;
+/**
+ * The waiting-prompt regex a screen shows on its trailing lines, or null. Only
+ * the last few lines count: a quoted dialog in scrollback is not a live menu.
+ * `send` uses this before pasting; status uses its own wider window because a
+ * full-screen TUI can hide the prompt under chrome.
+ */
+export declare function waitingMarker(screen: string, profile: HarnessProfile): RegExp | null;
+/** Does this screen's trailing lines show a prompt that wants the user's answer? */
+export declare function waitingPrompt(screen: string, profile: HarnessProfile): boolean;
 /**
  * Does this screen's trailing lines show the harness ready for input? An empty
  * ready set is unknown, never a match: a profile that never declared a marker

package/dist/harness.js

@@ -51,14 +51,42 @@ const WAITING = {
         /^(?:[›❯>]\s*)?(?:Run this command|Allow this command|Do you want to run this command)\?/i,
         /^(?:[›❯>]\s*)?(?:Allow|Approve) (?:this|the) (?:tool|command|operation)(?: call)?\?/i,
     ],
-    opencode: [...GENERIC_WAITING, /Permission required/i, /Allow once/i],
+    opencode: [
+        ...GENERIC_WAITING,
+        /Permission required/i,
+        /Allow once/i,
+        // OpenCode 2.2.5 TUI question dialog. packages/tui/src/mini/footer.form.tsx
+        // renders the free-text row as "Type your own answer" (line 517) and the
+        // footer as "↑↓ select   enter choose   tab next   esc dismiss" (line 611;
+        // the mono variant at line 610 says "up/down select..."). While the answer
+        // is being edited the footer becomes "enter save   esc dismiss" (line 606)
+        // and the confirmation step uses "enter submit   esc dismiss" (line 604).
+        /^\s*>?\s*\d+\.\s+Type your own answer\s*$/i,
+        /^(?:↑↓|up\/down) select\s+enter choose\s+tab next\s+esc dismiss\s*$/i,
+        /^enter (?:save|submit)\s+esc dismiss\s*$/i,
+    ],
     gemini: [
         ...GENERIC_WAITING,
         /Do you want to proceed\?/i,
         /Accept this file edit\?/i,
     ],
     pi: GENERIC_WAITING,
-    claude: [...GENERIC_WAITING, /Do you want to (?:proceed|continue)\?/i],
+    claude: [
+        ...GENERIC_WAITING,
+        /Do you want to (?:proceed|continue)\?/i,
+        // Claude Code 2.1.316 AskUserQuestion menu. The free-text row is labelled
+        // "Other" with placeholder "Type something." (single-select) or
+        // "Type something" (multi-select); the footer is
+        // "Enter to select · ↑/↓ to navigate · n to add notes · Esc to cancel".
+        // These strings are in the installed 2.1.316 build (checked against its
+        // bundle), and code.claude.com/docs/en/tools-reference names the "Other
+        // row" for typed answers. The other ordering is the permission/selection
+        // footer: "↑/↓ to navigate · Enter to select · Esc to cancel".
+        /^(?:[›❯>]\s*)?\d+\.\s+Other\s*$/i,
+        /^Type something\.?$/i,
+        /^Enter to select\s+·\s+.*\s+·\s+Esc to cancel$/i,
+        /^(?:↑\/↓|up\/down) to navigate\s+·\s+Enter to select\s+·\s+Esc to cancel$/i,
+    ],
 };
 /**
  * Queued-message hints seen live. Claude Code prints
@@ -230,6 +258,20 @@ export function busyMarker(screen, profile) {
 export function busyPrompt(screen, profile) {
     return busyMarker(screen, profile) !== null;
 }
+/**
+ * The waiting-prompt regex a screen shows on its trailing lines, or null. Only
+ * the last few lines count: a quoted dialog in scrollback is not a live menu.
+ * `send` uses this before pasting; status uses its own wider window because a
+ * full-screen TUI can hide the prompt under chrome.
+ */
+export function waitingMarker(screen, profile) {
+    const lines = trailingLines(screen);
+    return profile.waiting.find((re) => lines.some((line) => re.test(line))) ?? null;
+}
+/** Does this screen's trailing lines show a prompt that wants the user's answer? */
+export function waitingPrompt(screen, profile) {
+    return waitingMarker(screen, profile) !== null;
+}
 /**
  * Does this screen's trailing lines show the harness ready for input? An empty
  * ready set is unknown, never a match: a profile that never declared a marker

package/dist/host/cli.js

@@ -272,6 +272,7 @@ const COMMANDS = {
             "      unless --queue waits for the lease to free or --force shares it",
             "      --if-idle applies send's busy check before the lease: a harness that shows it is working fails pane_busy",
             "      without sending; --queue then waits for the pane to go idle as well as for the lease, and --force skips the check",
+            "      a target showing a question/selection dialog is refused pane_waiting (--queue waits for it to close)",
             "zswarm relay --list [--json]   id, state, delivery, target, session, age, last check, job and lease per relay dir",
             "zswarm relay --leases [--json]   live pane leases and the relay that holds each",
             "zswarm relay --cancel ID | --cancel-all --to PANE   stop the job, mark it CANCELLED, paste nothing",

package/dist/host/relay.js

@@ -2,7 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { ZellijError } from "../errors.js";
-import { dispatchZswarm, paneBusyMarker } from "../ops/dispatch.js";
+import { dispatchZswarm, paneBusyMarker, paneWaitingMarker } from "../ops/dispatch.js";
 import { resolveServeCliLaunch } from "../ops/serve-install.js";
 import { createStateStore, defaultStateDir } from "../state.js";
 import { findLease, leaseKey, releaseLeaseKey, takeLease } from "./lease.js";
@@ -498,6 +498,19 @@ export async function startRelay(input) {
         return paneBusyMarker(String(res.data?.text ?? ""), idlePane ?? { title: cfg.to }, cfg.harness);
     };
     const deadline = leaseNow() + cfg.timeoutMin * 60_000;
+    /**
+     * The waiting dialog one dump of the target shows, or null. The send op
+     * checks this itself before pasting; --queue also waits on it here so a
+     * question the owner is answering delays the relay instead of failing it.
+     */
+    let gatePane = idlePane;
+    const waitingProfilePane = async () => (gatePane ??= await resolveRemotePane());
+    const waitingNow = async () => {
+        const res = await call(target({ op: "dump", to: cfg.to, max: 400 }), remote).catch((err) => ({ ok: false, error: { code: "failed", message: String(err) } }));
+        if (!res.ok)
+            return null; // cannot see the screen: the send op still checks
+        return paneWaitingMarker(String(res.data?.text ?? ""), await waitingProfilePane(), cfg.harness);
+    };
     let busy = null;
     let taken;
     if (!input.queue) {
@@ -511,13 +524,16 @@ export async function startRelay(input) {
         taken = take();
     }
     else {
-        // --queue polls the lease and, under --if-idle, the busy marker. The lease
-        // is only taken once the pane is not visibly working.
+        // --queue polls the lease, the busy marker under --if-idle, and a waiting
+        // question/selection dialog. The lease is only taken once the pane is
+        // neither visibly working nor asking the owner a question.
         let attempt;
+        let dialog = null;
         for (;;) {
             if (checkIdle)
                 busy = await busyMarkerNow();
-            attempt = busy ? undefined : take();
+            dialog = busy ? null : await waitingNow();
+            attempt = busy || dialog ? undefined : take();
             if (attempt?.ok)
                 break;
             if (leaseNow() >= deadline)
@@ -530,6 +546,10 @@ export async function startRelay(input) {
             rmSync(dir, { recursive: true, force: true });
             throw new ZellijError("pane_busy", `pane ${cfg.to} is busy with a task (marker: ${busy}) and did not free before --timeout-min`);
         }
+        else if (dialog) {
+            rmSync(dir, { recursive: true, force: true });
+            throw new ZellijError("pane_waiting", `pane ${cfg.to} is showing a question/selection dialog (prompt: ${dialog}) and it did not close before --timeout-min`);
+        }
         else
             taken = attempt ?? take();
     }
@@ -564,7 +584,9 @@ export async function startRelay(input) {
                 const screen = dump.ok ? String(dump.data.text ?? "") : "";
                 const tail = screen.trim().split("\n").slice(-4).join("\n");
                 const firstLine = body.trim().split("\n")[0]?.slice(0, 60) ?? "";
-                if ((firstLine && tail.includes(firstLine)) || tail.includes("[zswarm from=") || tail.includes("[Pasted text")) {
+                const dialog = paneWaitingMarker(screen, { title: cfg.to }, cfg.harness);
+                if (!dialog &&
+                    ((firstLine && tail.includes(firstLine)) || tail.includes("[zswarm from=") || tail.includes("[Pasted text"))) {
                     await call(target({ op: "keys", to: cfg.to, keys: "Enter" }), remote);
                     sent = "enter-pressed";
                 }

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { createStateStore, defaultStateDir, type LeaseRecord, type LogEntry, typ
 export { findLease, leaseKey, leaseStale, listLeases, releaseLease, releaseLeaseKey, takeLease, type LeaseTakeInput, type LeaseTakeResult, type LeaseTarget, } from "./host/lease.js";
 export { dispatchZswarm, resolveInvocationEnv } from "./ops/dispatch.js";
 export { EXIT_WAIT_MS, HANDOFF_INLINE_MAX, HANDOFF_MARKER, HANDOFF_SELF_WAIT_MS, READY_SETTLE_MS, READY_STABLE_GAP_MS, READY_WAIT_MS, restartLaunchCommand, restartPane, restartPaneKind, type RestartPaneKind, type RestartStep, } from "./ops/restart.js";
-export { busyPrompt, queuedPrompt, readyPrompt, resolveHarness, type HarnessExitRecipe, type HarnessProfile, type SubmitStrategy, } from "./harness.js";
+export { busyPrompt, queuedPrompt, readyPrompt, resolveHarness, waitingMarker, waitingPrompt, type HarnessExitRecipe, type HarnessProfile, type SubmitStrategy, } from "./harness.js";
 export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, type Policy, } from "./policy.js";
 export { buildSshRemoteCommand, createSshExec, quoteRemoteArg, shellQuote, type IpcDiscoveryState, type SshExecFn, type SshTarget, } from "./exec.js";
 export { resolveSshTarget } from "./zellij/binary.js";

package/dist/index.js

@@ -14,7 +14,7 @@ export { createStateStore, defaultStateDir, } from "./state.js";
 export { findLease, leaseKey, leaseStale, listLeases, releaseLease, releaseLeaseKey, takeLease, } from "./host/lease.js";
 export { dispatchZswarm, resolveInvocationEnv } from "./ops/dispatch.js";
 export { EXIT_WAIT_MS, HANDOFF_INLINE_MAX, HANDOFF_MARKER, HANDOFF_SELF_WAIT_MS, READY_SETTLE_MS, READY_STABLE_GAP_MS, READY_WAIT_MS, restartLaunchCommand, restartPane, restartPaneKind, } from "./ops/restart.js";
-export { busyPrompt, queuedPrompt, readyPrompt, resolveHarness, } from "./harness.js";
+export { busyPrompt, queuedPrompt, readyPrompt, resolveHarness, waitingMarker, waitingPrompt, } from "./harness.js";
 export { assertOpAllowed, assertPaneAllowed, isWriteOp, loadPolicy, } from "./policy.js";
 export { buildSshRemoteCommand, createSshExec, quoteRemoteArg, shellQuote, } from "./exec.js";
 export { resolveSshTarget } from "./zellij/binary.js";

package/dist/ops/delivery.d.ts

@@ -3,7 +3,7 @@ import type { StateStore } from "../state.js";
 import type { ZellijClient } from "../zellij/client.js";
 import type { ZellijPane } from "../zellij/panes.js";
 import type { Clock } from "./types.js";
-export type Submitted = boolean | "queued" | "unverified" | "not-delivered";
+export type Submitted = boolean | "queued" | "unverified" | "not-delivered" | "waiting";
 /**
  * Where a message came from: the sending machine, the sender's Zellij session
  * and pane, and whether this host received the op over `serve`. Every part is

package/dist/ops/delivery.js

@@ -1,5 +1,5 @@
 import { hostname } from "node:os";
-import { busyMarker, queuedPrompt, resolveHarness } from "../harness.js";
+import { busyMarker, queuedPrompt, resolveHarness, waitingMarker } from "../harness.js";
 import { resolveSelfPaneId, resolveSelfSession } from "../zellij/session.js";
 import { isTrue, numberArg, optionalString } from "./util.js";
 /** Cap for one origin part; keeps a spoofed value from wrapping the header. */
@@ -320,6 +320,10 @@ async function verifySubmit(client, input) {
     if (verdict === true || verdict === "queued")
         return verdict;
     if (verdict === false) {
+        // A dialog appeared (or was already there) between the gate and this dump:
+        // Enter would choose its highlighted option, so never send the rescue key.
+        if (waitingMarker(after, profile))
+            return "waiting";
         await client.sendKeys({ session, paneId, keys: ["Enter"] });
         await clock.sleep(settleMs);
         const rescued = await dumpOrNull(client, session, paneId);
@@ -438,11 +442,18 @@ export async function deliverTo(client, state, args, input) {
                 });
             }
             else if (submitted === false) {
-                // The paste is still in the composer: press Enter, never paste again.
-                await client.sendKeys({ session, paneId: delivered.paneId, keys: ["Enter"] });
-                const seen = await dumpOrNull(client, session, delivered.paneId);
-                if (seen !== null && before !== null) {
-                    submitted = classifySubmit(before, seen, body, { queued });
+                // The paste is still in the composer: press Enter, never paste again —
+                // unless a dialog is now on screen, where Enter would answer it.
+                const current = await dumpOrNull(client, session, delivered.paneId);
+                if (current !== null && waitingMarker(current, profile)) {
+                    submitted = "waiting";
+                }
+                else {
+                    await client.sendKeys({ session, paneId: delivered.paneId, keys: ["Enter"] });
+                    const seen = await dumpOrNull(client, session, delivered.paneId);
+                    if (seen !== null && before !== null) {
+                        submitted = classifySubmit(before, seen, body, { queued });
+                    }
                 }
             }
             else {
@@ -453,6 +464,32 @@ export async function deliverTo(client, state, args, input) {
                 }
             }
         }
+        if (submitted === "waiting") {
+            state.appendLog({
+                at,
+                op,
+                session,
+                to: delivered.paneId,
+                from,
+                fromHost: origin.host,
+                fromSession: origin.session,
+                fromPane: origin.pane,
+                via: origin.via,
+                bytes: body.length,
+                ok: false,
+                detail: "submitted=waiting",
+            });
+            return {
+                to: delivered.paneId,
+                ok: false,
+                delivery: "zellij_paste",
+                submitted,
+                error: {
+                    code: "pane_waiting",
+                    message: "the pane is showing a question/selection dialog; zswarm did not press Enter because that would answer it — answer it in the pane, then resend",
+                },
+            };
+        }
         if (submitted === "not-delivered") {
             state.appendLog({
                 at,

package/dist/ops/dispatch.d.ts

@@ -9,6 +9,17 @@ export declare function paneBusyMarker(screen: string, pane: {
     command?: string | null;
     title?: string | null;
 }, harness?: string | null): string | null;
+/**
+ * The harness waiting-prompt regex a dumped screen shows for `pane`, or null.
+ * `send` always checks this before pasting: the pane may be showing an
+ * interactive question/selection dialog (OpenCode's question tool, Claude
+ * Code's AskUserQuestion or permission menu), where a paste lands in the
+ * free-text answer and an Enter picks the highlighted option.
+ */
+export declare function paneWaitingMarker(screen: string, pane: {
+    command?: string | null;
+    title?: string | null;
+}, harness?: string | null): string | null;
 /**
  * Per-invocation routing from `--local` / `--ssh`. `--local` clears both SSH
  * and serve (and remote IPC). `--ssh` sets the destination for this call and

package/dist/ops/dispatch.js

@@ -1,6 +1,6 @@
 import { ZellijError } from "../errors.js";
 import { createGitClient } from "../git.js";
-import { busyMarker, resolveHarness } from "../harness.js";
+import { busyMarker, resolveHarness, waitingMarker } from "../harness.js";
 import { findLease } from "../host/lease.js";
 import { normalizeKeys } from "../keys.js";
 import { createZellijClient } from "../zellij/client.js";
@@ -40,6 +40,16 @@ import { installServeService, uninstallServeService } from "../host/serve-servic
 export function paneBusyMarker(screen, pane, harness) {
     return busyMarker(screen, resolveHarness(pane, harness))?.source ?? null;
 }
+/**
+ * The harness waiting-prompt regex a dumped screen shows for `pane`, or null.
+ * `send` always checks this before pasting: the pane may be showing an
+ * interactive question/selection dialog (OpenCode's question tool, Claude
+ * Code's AskUserQuestion or permission menu), where a paste lands in the
+ * free-text answer and an Enter picks the highlighted option.
+ */
+export function paneWaitingMarker(screen, pane, harness) {
+    return waitingMarker(screen, resolveHarness(pane, harness))?.source ?? null;
+}
 /**
  * Per-invocation routing from `--local` / `--ssh`. `--local` clears both SSH
  * and serve (and remote IPC). `--ssh` sets the destination for this call and
@@ -453,10 +463,21 @@ async function dispatchOperation(args, injected, deps, context, env) {
                 const { session, pane, panes, firstCallMs, timeoutMs } = await resolveTarget(client, args, state(), clock, env, policy, op, signal);
                 assertWritable(client, pane, args, "send", session);
                 await assertExpectedScreen(client, session, pane.id, args, signal);
+                // Always check for an interactive dialog before pasting, not only with
+                // --if-idle: a paste into a question's free-text field and an Enter on
+                // its highlighted option can silently answer what the owner was meant
+                // to answer. An unreadable pane cannot be checked; delivery proceeds.
+                const to = String(args.to ?? "").trim();
+                const screen = await client.dumpPane({ session, paneId: pane.id }).then((res) => res.text, () => null);
+                if (!isTrue(args.force) && screen !== null) {
+                    const waiting = paneWaitingMarker(screen, pane, optionalString(args.harness));
+                    if (waiting) {
+                        throw new ZellijError("pane_waiting", `pane ${to} is showing a question/selection dialog (prompt: ${waiting}); nothing was pasted — answer it in the pane, or retry when it closes (or pass --force to paste anyway)`);
+                    }
+                }
                 if (isTrue(args.ifIdle)) {
                     // Before delivery starts: a live pane lease (a relay working it) is a
                     // hard refusal; a harness that is visibly working is the softer one.
-                    const to = String(args.to ?? "").trim();
                     const held = findLease(state(), {
                         serve: typeof args.serve === "string" ? args.serve : env.ZSWARM_SERVE,
                         session,
@@ -465,7 +486,6 @@ async function dispatchOperation(args, injected, deps, context, env) {
                     if (held) {
                         throw new ZellijError("pane_leased", `pane ${to} is leased by relay ${held.relayId} (from ${held.from}, since ${new Date(held.at).toISOString()})`, { relayId: held.relayId, from: held.from, at: held.at, dir: held.dir });
                     }
-                    const screen = await client.dumpPane({ session, paneId: pane.id }).then((res) => res.text, () => null);
                     if (screen !== null) {
                         const marker = paneBusyMarker(screen, pane, optionalString(args.harness));
                         if (marker) {

package/dist/schema.js

@@ -466,7 +466,7 @@ export const PARAMS = [
         flags: ["--submit"],
         ops: ["send", "broadcast"],
         values: ["auto", "double-enter", "none"],
-        description: 'send/broadcast: auto verifies the paste actually submitted and presses Enter again if not (default). The result reports submitted: true, "queued" (held behind a running turn), false (still in the composer), "unverified" (the screen changed but the body is not visible), or "not-delivered" (the pane was unchanged apart from the composer, so the op fails not_delivered and a resend is safe)',
+        description: 'send/broadcast: auto verifies the paste actually submitted and presses Enter again if not (default). The result reports submitted: true, "queued" (held behind a running turn), false (still in the composer), "unverified" (the screen changed but the body is not visible), "not-delivered" (the pane was unchanged apart from the composer, so the op fails not_delivered and a resend is safe), or "waiting" (a question/selection dialog appeared, Enter was withheld, and the op fails pane_waiting)',
     },
     {
         name: "observeMs",
@@ -501,7 +501,7 @@ export const PARAMS = [
         type: "boolean",
         flags: ["--if-idle"],
         ops: ["send"],
-        description: "send: refuse a pane that a relay has leased (pane_leased) or whose harness is visibly working (pane_busy) instead of pasting into it",
+        description: "send: refuse a pane that a relay has leased (pane_leased) or whose harness is visibly working (pane_busy) instead of pasting into it; a pane showing a question/selection dialog is refused as pane_waiting with or without this flag",
     },
     {
         name: "expect",
@@ -593,7 +593,7 @@ export const PARAMS = [
         type: "boolean",
         flags: ["--force"],
         ops: ["send", "keys", "unworktree", "bus", "interrupt", "broadcast", "restart"],
-        description: "send/keys: write to a pane whose command has exited; restart: restart a pane that a relay has leased; unworktree: remove a busy or dirty worktree; bus: close orphan bus panes and reload this session's plugin",
+        description: "send/keys: write to a pane whose command has exited; send: also paste into a pane showing a question/selection dialog; restart: restart a pane that a relay has leased; unworktree: remove a busy or dirty worktree; bus: close orphan bus panes and reload this session's plugin",
     },
     {
         name: "listen",
@@ -650,20 +650,31 @@ export const MCP_TOOL_DESCRIPTION = `zSwarm Zellij pane coordination (op=${OP_NA
     "Same host as Zellij, or ZSWARM_SSH / ZSWARM_SERVE for a remote crew.";
 const FLAG_INDEX = new Map(PARAMS.flatMap((p) => p.flags.map((flag) => [flag, p])));
 export function cliUsage() {
-    const lines = [
+    return [
         `usage: zswarm <${OP_NAMES.join("|")}> [options]`,
         "",
         "  positional: first bare argument is --to, second is --body for send",
         "",
-    ];
-    for (const param of PARAMS) {
-        if (param.flags.length === 0)
-            continue;
-        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 / --serve (host:port, tcp://, or ssh://user@host?servePort=9419) plus ZSWARM_SERVE_TOKEN. Serve defaults to loopback and always requires a token; an explicit local Tailscale IP is allowed only after host verification. Private raw TCP Tailscale Serve keeps the backend on 127.0.0.1 behind `tailscale serve --tcp=…` (docs/tailscale.md). ssh:// does not start remote serve. Windows default recipe: `zswarm serve --install` (verified readiness).", "Hosts (CLI only, see docs/hosts.md): `zswarm slot`, `zswarm crew`, `zswarm relay`, `zswarm host`, `zswarm gate`; `zswarm <command> --help` for each.", "Gate (docs/gate.md): a send-only ssh key. Receiver: `zswarm gate allow ID --key-file K --session S --pane P`. Sender: `zswarm send --gate DEST --session S --to P --body …`.", "Doctor: `zswarm doctor --session crew` inspects local, --ssh, and --serve routes without installs, pane changes, or plugin launch. See docs/doctor.md and docs/tailscale.md.", "Env: ZSWARM_BIN, ZSWARM_PATH, ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZSWARM_HOST, ZELLIJ_PANE_ID, ZELLIJ_SESSION_NAME, ZSWARM_BUS, ZSWARM_BUS_PLUGIN, ZSWARM_SSH, ZSWARM_SSH_BIN, ZSWARM_SSH_OPTS, ZSWARM_TMP, ZSWARM_SSH_MODE, ZSWARM_GATE_CONFIG, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_TAILSCALE_BIN, ZSWARM_CACHE_TTL_MS", "");
-    return lines.join("\n");
+        "  --session, -s VALUE     Zellij session (or ZSWARM_SESSION / ZELLIJ_SESSION_NAME)",
+        "  --to, -t, --pane VALUE  target pane: id, terminal_3, or a unique title; broadcast takes a comma list",
+        "  --fresh                 bypass the short-lived session/pane/tab listing cache",
+        "  --local                 route this call to the local machine only",
+        "  --ssh VALUE             route this call over SSH to user@host or an alias",
+        "  --serve VALUE           existing serve endpoint: host:port, tcp://, or ssh://user@host",
+        "  --help, -h              this list; `zswarm <op> --help` shows that op's flags",
+        "",
+        "  examples:",
+        "  zswarm list",
+        "  zswarm send --session crew --to worker --body \"text\"",
+        "  zswarm wait --session crew --to worker --match \"RESULT\" --timeout-ms 900000",
+        "",
+        "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 / --serve plus ZSWARM_SERVE_TOKEN. Serve defaults to loopback and always requires a token; an explicit local Tailscale IP is allowed only after host verification. See docs/tailscale.md.",
+        "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, not a retry.",
+        "Hosts (CLI only, see docs/hosts.md): `zswarm slot`, `zswarm crew`, `zswarm relay`, `zswarm host`, `zswarm gate`; `zswarm <command> --help` for each. Gate: docs/gate.md. Doctor: docs/doctor.md.",
+        "Env: ZSWARM_SESSION, ZSWARM_SELF_PANE, ZSWARM_FROM, ZSWARM_HOST, ZSWARM_BUS, ZSWARM_SSH, ZSWARM_SSH_MODE, ZSWARM_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_CACHE_TTL_MS (full list in docs/hosts.md).",
+        "",
+    ].join("\n");
 }
 /**
  * True when argv asks for help: `--help` or `-h` as a flag of its own, not the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zswarm/core",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "type": "module",
   "description": "zSwarm Zellij client and shared ops dispatch",
   "exports": {