@zswarm/core 0.1.8 → 0.2.0

package/assets/host-install.sh

@@ -0,0 +1,120 @@
+#!/bin/sh
+# zswarm host install: Node.js, zswarm and Zellij on a Linux or macOS host,
+# as pinned upstream binaries under one prefix, linked into a bin dir.
+# Idempotent; prints one line per step. Run as root (or with write access to
+# the prefix and bin dir). Never touches other users or their services.
+#
+#   host-install.sh [--prefix /usr/local/lib/zswarm] [--bin-dir /usr/local/bin]
+#                   [--node V] [--zellij V] [--zswarm V]
+set -eu
+
+PREFIX=/usr/local/lib/zswarm
+BIN=/usr/local/bin
+NODE_VERSION=24.21.0
+ZELLIJ_VERSION=0.45.1
+ZSWARM_VERSION=latest
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --prefix) PREFIX="$2"; shift 2 ;;
+    --bin-dir) BIN="$2"; shift 2 ;;
+    --node) NODE_VERSION="$2"; shift 2 ;;
+    --zellij) ZELLIJ_VERSION="$2"; shift 2 ;;
+    --zswarm) ZSWARM_VERSION="$2"; shift 2 ;;
+    *) echo "host-install: unknown argument $1" >&2; exit 2 ;;
+  esac
+done
+
+step() { printf '%-10s %s\n' "$1" "$2"; }
+fetch() { curl -fsSL --retry 3 -o "$2" "$1"; }
+sha256() { if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1"; else shasum -a 256 "$1"; fi | cut -d' ' -f1; }
+# verify NAME FILE EXPECTED: stop on a mismatch; no expected sum means a
+# version we have no pinned sum for, which installs but says so.
+verify() {
+  if [ -z "$3" ]; then
+    step "$1" "unverified: no pinned sha256 for this version"
+  elif [ "$(sha256 "$2")" != "$3" ]; then
+    echo "host-install: $1 sha256 mismatch for $2 (expected $3)" >&2
+    exit 1
+  fi
+}
+
+os="$(uname -s)"; arch="$(uname -m)"
+case "$os/$arch" in
+  Linux/x86_64) node_os=linux; node_arch=x64; zellij_target=x86_64-unknown-linux-musl ;;
+  Linux/aarch64|Linux/arm64) node_os=linux; node_arch=arm64; zellij_target=aarch64-unknown-linux-musl ;;
+  Darwin/arm64) node_os=darwin; node_arch=arm64; zellij_target=aarch64-apple-darwin ;;
+  Darwin/x86_64) node_os=darwin; node_arch=x64; zellij_target=x86_64-apple-darwin ;;
+  *) echo "host-install: unsupported platform $os/$arch" >&2; exit 2 ;;
+esac
+# Pinned sums for the default versions. Node: the release tarball
+# (nodejs.org SHASUMS256.txt). Zellij: the extracted binary (the release's
+# .sha256sum files hash the binary, not the tarball).
+node_sha=; zellij_sha=
+if [ "$NODE_VERSION" = 24.21.0 ]; then
+  case "$node_os-$node_arch" in
+    linux-x64) node_sha=6e1db87ef58b8819e5d5402eff1536491b18edd8eb7bee5ef7897876e88dc5ff ;;
+    linux-arm64) node_sha=724282c3b43aec998aa9527380465b45d229e021b58035f5f4f63095eabfe5d5 ;;
+    darwin-arm64) node_sha=bed7eea5325e1108f32ce5228ddd6a5f0f08a499ee42aa7442aea583702f6057 ;;
+    darwin-x64) node_sha=1462cb3b3046b815cf8ea436d3da450ec1a9f11dac7e5a46b0ada5305d7e8097 ;;
+  esac
+fi
+if [ "$ZELLIJ_VERSION" = 0.45.1 ]; then
+  case "$zellij_target" in
+    x86_64-unknown-linux-musl) zellij_sha=d006c521dcb475a6005d741e9dd7c5758e5a23b28dd60a5c10cebfa4876319dd ;;
+    aarch64-unknown-linux-musl) zellij_sha=2a2c0621e6f3b11ecbb05d66939a48000a2508604620aa20727a5fd61c49f451 ;;
+    aarch64-apple-darwin) zellij_sha=ca5f9333735bdbc59a621f1d8ed8e24798845302a28ff175d253d4793d5a4a2c ;;
+    x86_64-apple-darwin) zellij_sha=e3afe876c04cb83ca3f68cb939113ec7b1abe5fb46c13727c102a64afcb4b7d4 ;;
+  esac
+fi
+command -v curl >/dev/null 2>&1 || { echo "host-install: needs curl" >&2; exit 2; }
+command -v tar >/dev/null 2>&1 || { echo "host-install: needs tar" >&2; exit 2; }
+mkdir -p "$PREFIX" "$BIN"
+
+# --- Node.js ---------------------------------------------------------------
+node_dir="$PREFIX/node-$NODE_VERSION"
+if [ ! -x "$node_dir/bin/node" ]; then
+  tmp="$(mktemp -d)"
+  fetch "https://nodejs.org/dist/v$NODE_VERSION/node-v$NODE_VERSION-$node_os-$node_arch.tar.gz" "$tmp/node.tgz"
+  verify node "$tmp/node.tgz" "$node_sha"
+  mkdir -p "$node_dir" && tar -xzf "$tmp/node.tgz" -C "$node_dir" --strip-components 1
+  rm -rf "$tmp"
+  step node "installed $NODE_VERSION"
+else
+  step node "present $NODE_VERSION"
+fi
+ln -sfn "$node_dir/bin/node" "$BIN/node"
+
+# --- zswarm (npm, own prefix) ------------------------------------------------
+npm_prefix="$PREFIX/npm"
+have="$(PATH="$node_dir/bin:$PATH" npm ls -g --prefix "$npm_prefix" zswarm --depth=0 2>/dev/null | sed -n 's/.*zswarm@\([0-9][0-9A-Za-z.+-]*\).*/\1/p' || true)"
+if [ "$ZSWARM_VERSION" = latest ] || [ "$have" != "$ZSWARM_VERSION" ]; then
+  PATH="$node_dir/bin:$PATH" npm install -g --prefix "$npm_prefix" "zswarm@$ZSWARM_VERSION" >/dev/null 2>&1
+  now="$(PATH="$node_dir/bin:$PATH" npm ls -g --prefix "$npm_prefix" zswarm --depth=0 2>/dev/null | sed -n 's/.*zswarm@\([0-9][0-9A-Za-z.+-]*\).*/\1/p' || true)"
+  if [ "$now" = "$have" ]; then step zswarm "present $now"; else step zswarm "installed $now (was ${have:-none})"; fi
+else
+  step zswarm "present $have"
+fi
+ln -sfn "$npm_prefix/bin/zswarm" "$BIN/zswarm"
+ln -sfn "$npm_prefix/bin/zswarm-mcp" "$BIN/zswarm-mcp"
+
+# --- Zellij ------------------------------------------------------------------
+have_zellij="$("$BIN/zellij" --version 2>/dev/null | awk '{print $2}' || true)"
+if [ "$have_zellij" != "$ZELLIJ_VERSION" ]; then
+  tmp="$(mktemp -d)"
+  fetch "https://github.com/zellij-org/zellij/releases/download/v$ZELLIJ_VERSION/zellij-$zellij_target.tar.gz" "$tmp/z.tgz"
+  tar -xzf "$tmp/z.tgz" -C "$tmp"
+  verify zellij "$tmp/zellij" "$zellij_sha"
+  cp "$tmp/zellij" "$BIN/zellij.new" && chmod 0755 "$BIN/zellij.new" && mv "$BIN/zellij.new" "$BIN/zellij"
+  rm -rf "$tmp"
+  step zellij "installed $ZELLIJ_VERSION (was ${have_zellij:-none})"
+else
+  step zellij "present $have_zellij"
+fi
+
+# --- Python (zswarm slot needs 3.9+; not installed here) ----------------------
+if python3 -c 'import sys; sys.exit(sys.version_info < (3, 9))' 2>/dev/null; then
+  step python3 "present $(python3 -c 'import platform; print(platform.python_version())')"
+else
+  step python3 "MISSING (zswarm slot needs Python 3.9+; install it with the system package manager)"
+fi

package/assets/host-report.sh

@@ -0,0 +1,29 @@
+#!/bin/sh
+# zswarm host doctor, host side: read-only facts as KEY=VALUE lines.
+#   host-report.sh [session]
+PATH="$PATH:/usr/local/bin:/opt/homebrew/bin:$HOME/.local/bin"
+session="${1:-}"
+v() { "$@" 2>/dev/null | head -1; }
+echo "os=$(uname -s)"
+echo "arch=$(uname -m)"
+echo "user=$(id -un)"
+echo "node=$(v node --version | sed 's/^v//')"
+zv="$(v zswarm --version)"
+case "$zv" in
+  [0-9]*) ;;
+  *) command -v zswarm >/dev/null 2>&1 && zv="unknown (older than zswarm --version)" || zv="" ;;
+esac
+echo "zswarm=$zv"
+echo "zellij=$(v zellij --version | awk '{print $2}')"
+echo "python3=$(v python3 -c 'import platform; print(platform.python_version())')"
+echo "disk_home_gb=$(df -Pk "$HOME" 2>/dev/null | awk 'NR==2 {printf "%d", $4/1048576}')"
+echo "disk_tmp_gb=$(df -Pk "${TMPDIR:-/tmp}" 2>/dev/null | awk 'NR==2 {printf "%d", $4/1048576}')"
+echo "sessions=$(zellij list-sessions --no-formatting 2>/dev/null | grep -v EXITED | awk '{print $1}' | tr '\n' ' ')"
+if [ "$(uname -s)" = Linux ]; then
+  echo "linger=$(loginctl show-user "$(id -un)" -p Linger --value 2>/dev/null)"
+  systemctl --user list-units --all --plain --no-legend 'zswarm-*' 2>/dev/null | awk '{print "service=" $1 " " $3 " " $4}'
+else
+  launchctl list 2>/dev/null | awk '$3 ~ /^zswarm\./ {print "service=" $3 " pid=" $1 " last=" $2}'
+fi
+[ -n "$session" ] && echo "session_wanted=$session"
+exit 0

package/assets/slot.py

@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+"""zswarm slot: run one build or test command inside a machine-wide build slot.
+
+    zswarm slot [--project NAME] [--] COMMAND [ARG ...]
+    zswarm slot --status
+    zswarm slot --setup --slots N [--jobs J] [--group G]        (root)
+    zswarm slot --setup-project NAME --cap M [--group G]        (root)
+
+A host has N build slots and each project may be capped lower. The command
+runs only while it holds one global slot and, for a capped project, one of
+its project's slots; both are flock(2) locks (msvcrt byte locks on Windows)
+held by this process while it waits for the command. The descriptors are close-on-exec, so a
+daemon the command leaves running (a compiler server, a cache) never
+inherits them, and the slot frees when the command exits or slot dies. A
+slot run inside another (ZSWARM_SLOT set) reuses the outer slot instead of
+deadlocking on a second one.
+
+Unless already set, the command gets CARGO_BUILD_JOBS, NEXTEST_TEST_THREADS
+and MAKEFLAGS sized to the per-slot job count, and runs at nice 5 so other
+work on the machine (a CI runner, say) keeps priority.
+
+Layout:
+    <etc>/slots.conf              slots=N  jobs=J
+    <etc>/projects/<name>.conf    slots=M
+    <dir>/global-<i>.lock, <dir>/<name>-<i>.lock
+<etc> is ZSWARM_SLOT_ETC (default /etc/zswarm, %ProgramData%\\zswarm\\etc),
+<dir> is ZSWARM_SLOT_DIR (default /var/lib/zswarm/slots, %ProgramData%\\zswarm\\slots).
+The project defaults to ZSWARM_SLOT_PROJECT, else the user name.
+
+This is cooperative capacity control, not isolation: a process that skips
+slot is not stopped.
+"""
+
+from __future__ import annotations  # macOS ships Python 3.9
+
+import os
+import re
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+WINDOWS = os.name == "nt"
+if WINDOWS:
+    import msvcrt
+else:
+    import fcntl
+    import grp
+    import pwd
+
+_win_root = Path(os.environ.get("ProgramData") or "C:/ProgramData") / "zswarm"
+ETC = Path(os.environ.get("ZSWARM_SLOT_ETC") or (_win_root / "etc" if WINDOWS else "/etc/zswarm"))
+SLOTS = Path(os.environ.get("ZSWARM_SLOT_DIR") or (_win_root / "slots" if WINDOWS else "/var/lib/zswarm/slots"))
+NAME = re.compile(r"[a-z0-9][a-z0-9_-]{0,31}")
+
+
+def die(msg: str, code: int = 2) -> None:
+    print(f"slot: {msg}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def read_conf(path: Path) -> dict[str, int]:
+    values: dict[str, int] = {}
+    try:
+        text = path.read_text()
+    except FileNotFoundError:
+        return values
+    for line in text.splitlines():
+        line = line.split("#", 1)[0].strip()
+        if not line:
+            continue
+        key, _, value = line.partition("=")
+        try:
+            values[key.strip()] = int(value.strip())
+        except ValueError:
+            die(f"{path}: {key.strip()} is not an integer")
+    return values
+
+
+def bounded(value: int, what: str) -> int:
+    if not 1 <= value <= 64:
+        die(f"{what}={value} is outside 1..64")
+    return value
+
+
+def host_conf() -> tuple[int, int]:
+    conf = read_conf(ETC / "slots.conf")
+    if "slots" not in conf:
+        die(f"{ETC / 'slots.conf'} missing or has no slots= line (run zswarm slot --setup)")
+    return bounded(conf["slots"], "slots"), bounded(conf.get("jobs", 4), "jobs")
+
+
+def project_cap(project: str, host_slots: int) -> int | None:
+    """The project's cap, or None when it has no conf (only the host slots apply)."""
+    path = ETC / "projects" / f"{project}.conf"
+    if not path.exists():
+        return None
+    conf = read_conf(path)
+    return min(bounded(conf.get("slots", host_slots), "project slots"), host_slots)
+
+
+def default_project() -> str:
+    if os.environ.get("ZSWARM_SLOT_PROJECT"):
+        return os.environ["ZSWARM_SLOT_PROJECT"]
+    return os.environ.get("USERNAME", "unknown").lower() if WINDOWS else pwd.getpwuid(os.getuid()).pw_name
+
+
+def lock_nb(fd: int) -> bool:
+    """Take an exclusive lock without waiting; False if someone holds it."""
+    try:
+        if WINDOWS:
+            os.lseek(fd, 0, os.SEEK_SET)
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        else:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        return True
+    except OSError:  # BlockingIOError on POSIX, PermissionError on Windows
+        return False
+
+
+def lock_paths(prefix: str, count: int) -> list[Path]:
+    return [SLOTS / f"{prefix}-{i}.lock" for i in range(count)]
+
+
+def try_lock(paths: list[Path]) -> tuple[int, Path] | None:
+    if not any(p.exists() for p in paths):
+        die(f"no lock files {paths[0].name}.. in {SLOTS} (run zswarm slot --setup / --setup-project)")
+    for path in paths:
+        try:
+            flags = os.O_RDWR | getattr(os, "O_CLOEXEC", 0) | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NOINHERIT", 0)
+            fd = os.open(path, flags)
+        except FileNotFoundError:
+            continue  # count raised before setup created the file
+        except PermissionError:
+            die(f"no access to {path} (not in the slot group?)")
+        if not lock_nb(fd):
+            os.close(fd)
+            continue
+        return fd, path
+    return None
+
+
+def note_holder(fd: int, project: str, command: list[str]) -> None:
+    # The lock file itself carries who holds it, for --status.
+    line = f"{os.getpid()} {project} {int(time.time())} {' '.join(command)[:200]}\n"
+    if WINDOWS:
+        return  # byte 0 is locked; the holder note lives only on POSIX hosts
+    os.ftruncate(fd, 0)
+    os.pwrite(fd, line.encode(), 0)
+
+
+def status() -> int:
+    host_slots, jobs = host_conf()
+    print(f"host: {host_slots} slots, {jobs} jobs per slot")
+    busy = 0
+    for path in lock_paths("global", host_slots):
+        held = try_lock([path])
+        if held:
+            os.close(held[0])
+            print(f"  {path.name}: free")
+        else:
+            busy += 1
+            try:
+                holder = path.read_text().strip() or "?"
+            except OSError:
+                holder = "(held)"
+            print(f"  {path.name}: busy  {holder}")
+    print(f"busy {busy}/{host_slots}")
+    return 0
+
+
+def lock_file(path: Path, gid: int | None) -> None:
+    # Without a group every user must be able to open the lock read-write
+    # (the holder note is written through it). Slots are cooperative, so
+    # world-writable lock files cost nothing a user could not already do.
+    mode = 0o660 if gid is not None else 0o666
+    if not path.exists():
+        path.touch(mode=mode)
+    if gid is not None:
+        os.chown(path, 0, gid)
+    if not WINDOWS:
+        os.chmod(path, mode)
+
+
+def setup_dirs(group: str | None) -> int | None:
+    if not WINDOWS and os.geteuid() != 0:
+        die("--setup needs root")
+    gid = None
+    if group and not WINDOWS:
+        try:
+            gid = grp.getgrnam(group).gr_gid
+        except KeyError:
+            die(f"group {group} does not exist (create it first)")
+    (ETC / "projects").mkdir(parents=True, exist_ok=True)
+    SLOTS.mkdir(parents=True, exist_ok=True)
+    if not WINDOWS:
+        os.chmod(ETC, 0o755)
+        os.chmod(ETC / "projects", 0o755)
+        if gid is not None:
+            os.chown(SLOTS, 0, gid)
+        os.chmod(SLOTS, 0o770 if gid is not None else 0o755)
+    return gid
+
+
+def write_conf(path: Path, text: str) -> None:
+    tmp = path.with_name(path.name + ".new")
+    tmp.write_text(text)
+    if not WINDOWS:
+        os.chmod(tmp, 0o644)
+    os.replace(tmp, path)
+
+
+def option(argv: list[str], name: str, default: str | None = None) -> str | None:
+    if name in argv:
+        i = argv.index(name)
+        if i + 1 >= len(argv):
+            die(f"{name} needs a value")
+        return argv[i + 1]
+    return default
+
+
+def setup(argv: list[str]) -> int:
+    slots = bounded(int(option(argv, "--slots") or die("--setup needs --slots N")), "slots")
+    jobs = bounded(int(option(argv, "--jobs", "4")), "jobs")
+    gid = setup_dirs(option(argv, "--group"))
+    write_conf(ETC / "slots.conf", f"slots={slots}\njobs={jobs}\n")
+    for path in lock_paths("global", slots):
+        lock_file(path, gid)
+    print(f"slot: {slots} slots x {jobs} jobs in {SLOTS}")
+    return 0
+
+
+def setup_project(argv: list[str]) -> int:
+    project = option(argv, "--setup-project")
+    if not project or not NAME.fullmatch(project):
+        die(f"invalid project name {project!r}")
+    cap = bounded(int(option(argv, "--cap") or die("--setup-project needs --cap M")), "cap")
+    gid = setup_dirs(option(argv, "--group"))
+    write_conf(ETC / "projects" / f"{project}.conf", f"slots={cap}\n")
+    for path in lock_paths(project, cap):
+        lock_file(path, gid)
+    print(f"slot: project {project} capped at {cap}")
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    if argv[:1] == ["--status"]:
+        return status()
+    if argv[:1] == ["--setup"]:
+        return setup(argv)
+    if argv[:1] == ["--setup-project"]:
+        return setup_project(argv)
+    project = None
+    if argv[:1] == ["--project"]:
+        if len(argv) < 2:
+            die("--project needs a name")
+        project, argv = argv[1], argv[2:]
+    if argv[:1] == ["--"]:
+        argv = argv[1:]
+    if not argv:
+        die("usage: zswarm slot [--project NAME] [--] COMMAND [ARG ...] | --status | --setup | --setup-project")
+    if os.environ.get("ZSWARM_SLOT"):
+        # Already inside a slot (a script run under slot calls slot again):
+        # the parent's slot covers this command; locking again would deadlock.
+        return run(argv, dict(os.environ), renice=False)
+    project = project or default_project()
+    if not NAME.fullmatch(project):
+        die(f"invalid project name {project!r}")
+
+    host_slots, jobs = host_conf()
+    cap = project_cap(project, host_slots)
+    project_locks = lock_paths(project, cap) if cap else []
+    global_locks = lock_paths("global", host_slots)
+
+    announced = False
+    while True:
+        mine = try_lock(project_locks) if project_locks else None
+        if mine or not project_locks:
+            shared = try_lock(global_locks)
+            if shared:
+                break
+            if mine:
+                os.close(mine[0])
+        if not announced:
+            capped = f"cap {cap}, " if cap else ""
+            print(f"slot: waiting for a build slot ({project} {capped}host {host_slots})", file=sys.stderr)
+            announced = True
+        time.sleep(float(os.environ.get("ZSWARM_SLOT_POLL", "1")))
+
+    for held in (mine, shared):
+        if held:
+            note_holder(held[0], project, argv)
+
+    env = dict(os.environ)
+    env.setdefault("CARGO_BUILD_JOBS", str(jobs))
+    env.setdefault("NEXTEST_TEST_THREADS", str(jobs))
+    env.setdefault("MAKEFLAGS", f"-j{jobs}")
+    env["ZSWARM_SLOT"] = shared[1].name
+    return run(argv, env)
+
+
+def run(argv: list[str], env: dict[str, str], renice: bool = True) -> int:
+    """Run the command as a child and wait. The lock descriptors stay in this
+    process (close-on-exec), so a daemon the command leaves behind never
+    inherits them and the slot frees when the command exits."""
+    if renice and not WINDOWS:
+        try:
+            os.nice(5)
+        except OSError:
+            pass
+    try:
+        child = subprocess.Popen(argv, env=env)
+    except FileNotFoundError:
+        die(f"{argv[0]}: command not found", 127)
+    for sig in (signal.SIGINT, signal.SIGTERM, getattr(signal, "SIGHUP", None)):
+        if sig is not None:
+            signal.signal(sig, lambda signum, _frame: child.send_signal(signum))
+    code = child.wait()
+    return 128 - code if code < 0 else code
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/dist/exec.d.ts

@@ -21,7 +21,8 @@ export type ExecOptions = {
      * Stop as soon as the accumulated stdout satisfies this, instead of waiting
      * for the process to exit. `zellij pipe` answers in milliseconds but stays
      * resident when it has no terminal, so waiting for exit means waiting for the
-     * timeout.
+     * timeout. Replies are JSON lines, so this is only consulted when a chunk
+     * could have completed one (see `mayCompleteLine`).
      */
     until?: (stdout: string) => boolean;
     /** Kill the child when aborted (MCP cancellation). */

package/dist/exec.js

@@ -322,6 +322,14 @@ export function createSshExec(target, env, options = {}) {
     };
     return exec;
 }
+/**
+ * A JSON line is complete once its newline arrives, or once the stream ends on
+ * `}` (a last line written without one). Asking `until` about every chunk
+ * re-parses a multi-megabyte single-line scrollback reply once per 64KB read.
+ */
+function mayCompleteLine(chunk) {
+    return chunk.includes("\n") || chunk.trimEnd().endsWith("}");
+}
 /** Read stdout until the answer is in hand, then stop caring about the child. */
 function runUntil(binPath, args, env, options) {
     return new Promise((resolve) => {
@@ -361,13 +369,18 @@ function runUntil(binPath, args, env, options) {
         child.on("error", (err) => {
             finish(localSpawnResult(err, binPath));
         });
+        // Decode across reads: a multi-byte character split between two chunks
+        // must not come out as U+FFFD in the screen text.
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
         child.stdout.on("data", (chunk) => {
-            stdout += chunk.toString();
-            if (options.until(stdout))
+            stdout += chunk;
+            if (mayCompleteLine(chunk) && options.until(stdout)) {
                 finish({ code: 0, stdout, stderr });
+            }
         });
         child.stderr.on("data", (chunk) => {
-            stderr += chunk.toString();
+            stderr += chunk;
         });
         child.on("close", (code) => finish({ code: code ?? 0, stdout, stderr }));
     });

package/dist/host/cli.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Host commands: CLI-only (not MCP ops), because they run long, pass argv
+ * through or print plain text. `zswarm <command> --help` prints the usage.
+ */
+/** `--flag value` pairs and positionals; boolean flags are listed in `bools`. */
+export declare function parseHostArgs(argv: string[], bools?: string[]): {
+    flags: Record<string, string | true>;
+    rest: string[];
+};
+export declare const HOST_COMMANDS: readonly string[];
+export declare function hostUsage(): string;
+/** Run a host command; resolves to the process exit code. */
+export declare function runHostCommand(argv: string[]): Promise<number>;