@zswarm/core 0.2.5 → 0.2.7

package/dist/schema.js

@@ -15,6 +15,7 @@ export const OP_NAMES = [
     "keys",
     "interrupt",
     "spawn",
+    "restart",
     "close",
     "worktrees",
     "unworktree",
@@ -42,6 +43,7 @@ export const TARGET_OPS = [
     "status",
     "keys",
     "interrupt",
+    "restart",
     "close",
     "rename",
     "focus",
@@ -57,25 +59,29 @@ export const PARAMS = [
     {
         name: "to",
         type: "string",
-        flags: ["--to", "-t"],
+        flags: ["--to", "-t", "--pane"],
+        ops: [...TARGET_OPS, "broadcast", "log"],
         description: "target pane: id (3 / terminal_3) or unique title/command; broadcast takes a comma list; log filters by it",
     },
     {
         name: "all",
         type: "boolean",
         flags: ["--all", "-a"],
+        ops: ["broadcast", "sessions"],
         description: "broadcast: every terminal pane in the session; sessions: include EXITED resurrectable sessions",
     },
     {
         name: "live",
         type: "boolean",
         flags: ["--live", "--active"],
+        ops: ["sessions"],
         description: "sessions: only live (non-EXITED) sessions — this is the default; use --all to include EXITED",
     },
     {
         name: "exited",
         type: "boolean",
         flags: ["--exited"],
+        ops: ["sessions"],
         cliOnly: true,
         description: "sessions: list only EXITED (resurrectable) sessions; rows carry name, exited, age and ageSeconds",
     },
@@ -83,6 +89,7 @@ export const PARAMS = [
         name: "pruneExited",
         type: "boolean",
         flags: ["--prune-exited"],
+        ops: ["sessions"],
         cliOnly: true,
         description: "sessions: delete EXITED sessions (all, or those matching --older-than) with zellij delete-session; a live session is never removed",
     },
@@ -90,6 +97,7 @@ export const PARAMS = [
         name: "olderThan",
         type: "string",
         flags: ["--older-than"],
+        ops: ["sessions"],
         cliOnly: true,
         description: "sessions --prune-exited: only delete sessions created at least this long ago (e.g. 7d, 12h, 30m; default all exited)",
     },
@@ -97,6 +105,7 @@ export const PARAMS = [
         name: "dryRun",
         type: "boolean",
         flags: ["--dry-run"],
+        ops: ["sessions"],
         cliOnly: true,
         description: "sessions --prune-exited: report what would be deleted without deleting",
     },
@@ -104,6 +113,7 @@ export const PARAMS = [
         name: "json",
         type: "boolean",
         flags: ["--json"],
+        ops: ["sessions"],
         cliOnly: true,
         description: "sessions: rows are name, exited, age and ageSeconds; the CLI prints JSON either way",
     },
@@ -123,60 +133,70 @@ export const PARAMS = [
         name: "group",
         type: "string",
         flags: ["--group", "-g"],
+        ops: ["broadcast"],
         description: "broadcast: narrow the selection to panes whose title or command contains this",
     },
     {
         name: "channel",
         type: "string",
         flags: ["--channel"],
+        ops: ["signal", "await"],
         description: "signal/await: channel name",
     },
     {
         name: "payload",
         type: "string",
         flags: ["--payload"],
+        ops: ["signal"],
         description: "signal: short note stored with the post",
     },
     {
         name: "count",
         type: "number",
         flags: ["--count"],
+        ops: ["await"],
         description: "await: how many posts to wait for (default 1)",
     },
     {
         name: "clear",
         type: "boolean",
         flags: ["--clear"],
+        ops: ["signal", "bus", "serve"],
         description: "signal: reset the channel (all channels when none is given); bus: forget the installed plugin; serve: stop and unregister the owned Windows zswarm-serve logon task, or the Linux/macOS serve service, if present",
     },
     {
         name: "install",
         type: "boolean",
         flags: ["--install"],
+        ops: ["bus", "serve"],
         description: "bus: load the event-bus plugin in a pane so its permission prompt can be answered, then remember it; serve: register the current-user Windows Interactive logon task, or on Linux/macOS a systemd user unit (with linger) or launchd job whose token lives in ~/.zswarm/serve/, and wait for authenticated hello plus host session visibility",
     },
     {
         name: "runAs",
         type: "string",
         flags: ["--run-as"],
+        ops: ["serve"],
         description: "serve --install/--clear on Linux/macOS, run as root: install the service for this user (a LaunchDaemon with UserName on macOS, the user's systemd units on Linux), for accounts that never log in",
     },
     {
         name: "reset",
         type: "boolean",
         flags: ["--reset"],
+        ops: ["tail"],
         description: "tail: forget the stored cursor and return the whole screen",
     },
     {
         name: "sampleMs",
         type: "number",
         flags: ["--sample-ms"],
+        ops: ["status"],
         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"],
+        ops: ["status"],
         description: "status: classify changes since the previous bus observation (default when bus available); first observation is unknown unless a prompt is recognized",
     },
     {
@@ -195,33 +215,60 @@ export const PARAMS = [
         name: "limit",
         type: "number",
         flags: ["--limit"],
+        ops: ["log"],
         description: "log: how many entries to return (default 20)",
     },
     {
         name: "since",
         type: "string",
         flags: ["--since"],
+        ops: ["log"],
         description: "log: only entries at or after this epoch millisecond",
     },
     {
         name: "failed",
         type: "boolean",
         flags: ["--failed"],
+        ops: ["log"],
         description: "log: only deliveries that did not land",
     },
     {
         name: "body",
         type: "string",
         flags: ["--body", "-b", "--text"],
+        ops: ["send", "broadcast"],
         description: "send: message body",
     },
     {
         name: "bodyFile",
         type: "string",
         flags: ["--body-file"],
+        ops: ["send"],
         cliOnly: true,
         description: "send: read UTF-8 on the caller from PATH, or - for stdin; cannot combine with --body/--text",
     },
+    {
+        name: "handoff",
+        type: "string",
+        flags: [],
+        ops: ["restart"],
+        description: "restart: handoff text to deliver to the relaunched agent (MCP inline form; the CLI fills this from --handoff-file)",
+    },
+    {
+        name: "handoffFile",
+        type: "string",
+        flags: ["--handoff-file"],
+        ops: ["restart"],
+        cliOnly: true,
+        description: "restart: read the handoff UTF-8 on the caller from PATH, or - for stdin; a short handoff is pasted, a long one becomes a pointer line, and --handoff-self writes the agent's handoff to this path",
+    },
+    {
+        name: "handoffSelf",
+        type: "boolean",
+        flags: ["--handoff-self"],
+        ops: ["restart"],
+        description: "restart: before exiting, ask the running agent to write its handoff to the file and print a marker, then deliver it after relaunch",
+    },
     {
         name: "text",
         type: "string",
@@ -232,36 +279,42 @@ export const PARAMS = [
         name: "from",
         type: "string",
         flags: ["--from", "-f"],
+        ops: ["send", "broadcast"],
         description: "send: sender label in the [zswarm from=…] prefix (default: ZSWARM_FROM, else the sending pane's title, else swarm)",
     },
     {
         name: "raw",
         type: "boolean",
         flags: ["--raw"],
+        ops: ["send", "broadcast"],
         description: "send: skip the peer prefix (default false)",
     },
     {
         name: "full",
         type: "boolean",
         flags: ["--full"],
+        ops: ["dump", "wait", "tail"],
         description: "dump/wait: include full scrollback (default false)",
     },
     {
         name: "max",
         type: "number",
         flags: ["--max"],
+        ops: ["dump", "wait", "tail", "layout", "diff"],
         description: "dump/wait: max text chars (dump 8000, wait 2000; keeps tail, 0 = unlimited)",
     },
     {
         name: "head",
         type: "boolean",
         flags: ["--head"],
+        ops: ["dump"],
         description: "dump: keep the start instead of the tail when truncating",
     },
     {
         name: "for",
         type: "string",
         flags: ["--for"],
+        ops: ["wait"],
         values: ["idle", "match", "either"],
         description: "wait: stop on a quiet screen, on a match, or whichever lands first (default: match if match= given, else idle)",
     },
@@ -269,42 +322,49 @@ export const PARAMS = [
         name: "match",
         type: "string",
         flags: ["--match", "-m"],
+        ops: ["wait"],
         description: "wait: text to look for in the pane screen",
     },
     {
         name: "regex",
         type: "boolean",
         flags: ["--regex"],
+        ops: ["wait"],
         description: "wait: treat match as a regex (default false)",
     },
     {
         name: "ignoreCase",
         type: "boolean",
         flags: ["--ignore-case"],
+        ops: ["wait"],
         description: "wait: case-insensitive match (default false)",
     },
     {
         name: "idleMs",
         type: "number",
         flags: ["--idle-ms"],
+        ops: ["wait"],
         description: "wait: screen must be unchanged this long to count as idle (default 2000)",
     },
     {
         name: "pollMs",
         type: "number",
         flags: ["--poll-ms"],
+        ops: ["wait"],
         description: "wait: fallback poll interval (default 150; bus path polls at 50ms)",
     },
     {
         name: "timeoutMs",
         type: "number",
         flags: ["--timeout-ms"],
-        description: "wait: timeout (default 60000); status/spawn: overall deadline (default 30000); doctor: overall deadline (default 10000), including Tailscale/SSH/hello/host checks; serve --install: overall install/readiness deadline (default 30000)",
+        ops: ["wait", "status", "spawn", "restart", "doctor", "serve", "send", "dump", "tail", "keys", "interrupt", "close", "await"],
+        description: "wait: timeout (default 60000); status/spawn/restart: overall deadline (default 30000); doctor: overall deadline (default 10000), including Tailscale/SSH/hello/host checks; serve --install: overall install/readiness deadline (default 30000)",
     },
     {
         name: "keys",
         type: "stringOrArray",
         flags: ["--key", "--keys", "-k"],
+        ops: ["keys", "interrupt"],
         repeat: true,
         description: 'keys: key specs, one per entry — "Ctrl c", "Esc", "F1", "Up". A bare string is one key; comma-separate for several.',
     },
@@ -312,72 +372,84 @@ export const PARAMS = [
         name: "chars",
         type: "string",
         flags: ["--chars"],
+        ops: ["keys"],
         description: "keys: literal characters to type instead of key specs (no Enter unless enter=true)",
     },
     {
         name: "enter",
         type: "boolean",
         flags: ["--enter"],
+        ops: ["keys"],
         description: "keys: press Enter after the keys/chars",
     },
     {
         name: "hard",
         type: "boolean",
         flags: ["--hard"],
+        ops: ["interrupt"],
         description: "interrupt: send Ctrl c instead of the default Esc",
     },
     {
         name: "command",
         type: "stringOrArray",
         flags: ["--command", "--cmd", "-c"],
-        description: "spawn: program to run in the new pane, argv-style (no shell). Empty starts a plain shell.",
+        ops: ["spawn", "restart"],
+        description: "spawn: program to run in the new pane, argv-style (no shell). Empty starts a plain shell. restart: command to type in a shell pane instead of the profile's launch command",
     },
     {
         name: "cwd",
         type: "string",
         flags: ["--cwd"],
+        ops: ["spawn", "worktrees", "unworktree", "diff", "checkpoint"],
         description: "spawn: working directory for the new pane; worktrees/unworktree: any directory inside the repo",
     },
     {
         name: "worktree",
         type: "string",
         flags: ["--worktree", "-w"],
+        ops: ["spawn", "unworktree"],
         description: "spawn: branch to give the peer its own git worktree (overrides cwd); unworktree: alias for branch",
     },
     {
         name: "worktreeRoot",
         type: "string",
         flags: ["--worktree-root"],
+        ops: ["spawn", "unworktree"],
         description: "where worktrees live (default <repo>-worktrees beside the repo, or ZSWARM_WORKTREE_ROOT)",
     },
     {
         name: "baseRef",
         type: "string",
         flags: ["--base-ref", "--base"],
+        ops: ["spawn"],
         description: "spawn: ref to branch from when the worktree branch is new",
     },
     {
         name: "path",
         type: "string",
         flags: ["--path"],
+        ops: ["unworktree", "diff", "checkpoint"],
         description: "unworktree: worktree path to remove",
     },
     {
         name: "branch",
         type: "string",
         flags: ["--branch"],
+        ops: ["unworktree", "diff", "checkpoint"],
         description: "unworktree: remove the worktree holding this branch",
     },
     {
         name: "name",
         type: "string",
         flags: ["--name", "-n"],
+        ops: ["spawn", "rename"],
         description: "spawn: pane (or tab) name; rename: the new name",
     },
     {
         name: "submit",
         type: "string",
         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)',
     },
@@ -385,48 +457,56 @@ export const PARAMS = [
         name: "observeMs",
         type: "number",
         flags: ["--observe-ms"],
+        ops: ["send", "dump", "tail", "wait", "keys", "interrupt", "close", "spawn"],
         description: "spawn: observe creation/alias for up to 3000ms; pane lookup: retry absence for 1000ms (scaled up to 5x when the first Zellij call is slow); 0 disables retries",
     },
     {
         name: "settleMs",
         type: "number",
         flags: ["--settle-ms"],
+        ops: ["send", "broadcast"],
         description: "send/broadcast: pause before checking the paste landed (default 300, scaled up to 5x when the first Zellij call is slow; explicit value wins)",
     },
     {
         name: "confirm",
         type: "boolean",
         flags: ["--confirm"],
+        ops: ["send", "broadcast"],
         description: 'send/broadcast: after the send, dump once more and report what it sees; paste again only on "not-delivered" (positive evidence nothing landed), press Enter when the body is still in the composer, and never paste the body twice',
     },
     {
         name: "ifIdle",
         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",
     },
     {
         name: "expect",
         type: "string",
         flags: ["--expect"],
+        ops: ["send", "keys", "interrupt"],
         description: "send/keys/interrupt: case-insensitive substring required on the current screen immediately before input",
     },
     {
         name: "message",
         type: "string",
         flags: ["--message"],
+        ops: ["checkpoint"],
         description: "checkpoint: commit message",
     },
     {
         name: "stat",
         type: "boolean",
         flags: ["--stat"],
+        ops: ["diff"],
         description: "diff: stat only, no patch body",
     },
     {
         name: "direction",
         type: "string",
         flags: ["--direction", "-d"],
+        ops: ["spawn"],
         values: ["right", "left", "up", "down"],
         description: "spawn: split direction",
     },
@@ -434,66 +514,77 @@ export const PARAMS = [
         name: "floating",
         type: "boolean",
         flags: ["--floating"],
+        ops: ["spawn"],
         description: "spawn: open the pane floating",
     },
     {
         name: "width",
         type: "string",
         flags: ["--width"],
+        ops: ["spawn"],
         description: "spawn: floating pane width (e.g. 80 or 50%)",
     },
     {
         name: "height",
         type: "string",
         flags: ["--height"],
+        ops: ["spawn"],
         description: "spawn: floating pane height (e.g. 20 or 40%)",
     },
     {
         name: "tab",
         type: "string",
         flags: ["--tab"],
+        ops: ["broadcast", "rename", "spawn"],
         description: "tab name: broadcast targets it, rename retitles it, spawn opens the new pane's tab by it",
     },
     {
         name: "newTab",
         type: "boolean",
         flags: ["--new-tab"],
+        ops: ["spawn"],
         description: "spawn: open a new tab instead of splitting",
     },
     {
         name: "layout",
         type: "string",
         flags: ["--layout", "-l"],
+        ops: ["spawn"],
         description: "spawn: layout name for the new tab (newTab=true)",
     },
     {
         name: "closeOnExit",
         type: "boolean",
         flags: ["--close-on-exit"],
+        ops: ["spawn"],
         description: "spawn: close the pane when its command exits",
     },
     {
         name: "allowSelf",
         type: "boolean",
         flags: ["--allow-self"],
+        ops: ["send", "keys", "close", "interrupt", "broadcast"],
         description: "send/keys/close: allow targeting zswarm's own pane (default false)",
     },
     {
         name: "force",
         type: "boolean",
         flags: ["--force"],
-        description: "send/keys: write to a pane whose command has exited; unworktree: remove a busy or dirty worktree; bus: close orphan bus panes and reload this session's plugin",
+        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",
     },
     {
         name: "listen",
         type: "string",
         flags: ["--listen"],
+        ops: ["serve"],
         description: "serve: bind address (default 127.0.0.1:9419). Loopback needs no Tailscale; a non-loopback literal must be a verified local Tailscale IP (see docs/tailscale.md). Reach via ZSWARM_SERVE / --serve (direct host:port, private Tailscale Serve tcp:// frontend, or ssh:// to remote loopback)",
     },
     {
         name: "verbose",
         type: "boolean",
         flags: ["--verbose", "-v"],
+        ops: ["list", "send", "spawn", "status"],
         description: "list/send/spawn: include cwd/focus/exited/floating (and the pane on send/spawn)",
     },
 ];
@@ -533,7 +624,7 @@ export function mcpInputSchema() {
 }
 export const MCP_TOOL_DESCRIPTION = `zSwarm Zellij pane coordination (op=${OP_NAMES.join("|")}). ` +
     "List panes, send text into a CLI pane (paste+Enter), block until a pane goes idle or prints a match, " +
-    "send raw keys, open or close panes, and give a peer its own git worktree. " +
+    "send raw keys, open or close panes, restart an agent in its pane with an optional handoff, and give a peer its own git worktree. " +
     "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() {
@@ -552,6 +643,49 @@ export function cliUsage() {
     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 <command> --help` for each.", "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, 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_SERVE, ZSWARM_SERVE_TOKEN, ZSWARM_TAILSCALE_BIN, ZSWARM_CACHE_TTL_MS", "");
     return lines.join("\n");
 }
+/**
+ * True when argv asks for help: `--help` or `-h` as a flag of its own, not the
+ * value of a flag that takes one (`--body -h` sends "-h") and not after `--`.
+ */
+export function wantsHelp(argv) {
+    const valued = new Set(PARAMS.filter((p) => p.type !== "boolean").flatMap((p) => p.flags));
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--")
+            return false;
+        if (arg === "--help" || arg === "-h")
+            return true;
+        if (valued.has(arg))
+            i++; // its value may be anything, "-h" included
+    }
+    return false;
+}
+/**
+ * Per-command help for `zswarm <op> --help`: the usage line, the positional
+ * shorthand, and only the flags whose `ops` include this op. A flag without
+ * `ops` (session, --local, --ssh, --fresh, --serve) applies to every op.
+ * Render from the same PARAMS table that parses the flags, so they cannot drift.
+ */
+export function commandUsage(op) {
+    const lines = [`usage: zswarm ${op} [options]`, ""];
+    const positional = op === "send"
+        ? "  positional: first bare argument is --to, second is --body"
+        : TARGET_OPS.includes(op)
+            ? "  positional: first bare argument is --to"
+            : undefined;
+    if (positional)
+        lines.push(positional, "");
+    for (const param of PARAMS) {
+        if (param.flags.length === 0)
+            continue;
+        if (param.ops && !param.ops.includes(op))
+            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("");
+    return lines.join("\n");
+}
 /** Turn argv (without the op) into dispatch args, driven by PARAMS. */
 /**
  * Pull the op out of argv, tolerating flags before it.
@@ -561,7 +695,7 @@ export function cliUsage() {
  * an unknown op. Only positions that already errored are affected: if argv[0]
  * is a real op it wins, so `send reviewer list` still sends the word "list".
  */
-function extractOp(argv) {
+export function extractOp(argv) {
     const first = argv[0];
     if (first && !first.startsWith("-")) {
         return { op: first, rest: argv.slice(1) };

package/package.json

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