swarph-cli 0.18.0__tar.gz → 0.20.0__tar.gz

{swarph_cli-0.18.0/src/swarph_cli.egg-info → swarph_cli-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.18.0
+Version: 0.20.0
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -51,6 +51,8 @@ pip install swarph-cli
 swarph --version
 ```
 
+> **System requirement — a terminal multiplexer.** The session verbs (`spawn`, `cell`, `watchdog`) drive a `tmux`-compatible multiplexer. On **Linux/macOS** install `tmux` (`apt install tmux` / `brew install tmux`). On **Windows** there is no native tmux — install [**psmux**](https://github.com/psmux/psmux) (a Rust tmux-for-Windows, MIT) with `swarph install-multiplexer` (fetches the pinned, checksum-verified binary into `~/.swarph/bin`) or `winget install marlocarlo.psmux`.
+
 **What it is:** a multi-provider LLM command line. Run one-shot prompts or an interactive REPL against any supported provider; spawn long-lived agent *cells* that persist across restarts and coordinate over a mesh; install hooks, MCP servers, and skills by content-addressed URI. An open, inspectable substrate — not a closed orchestration platform.
 
 **Who it's for:** builders running more than one LLM who want them to *cooperate* instead of sitting in separate tabs — multi-agent systems across vendors, agnostic by design. A thin client over the [`swarph-mesh`](https://github.com/BrainSurfing-tech/swarph-mesh) substrate library.
@@ -72,10 +74,14 @@ swarph brain-ask "<q>"   search the swarph-brain (gbrain) memory — $0 cited an
 swarph brain serve       run the gbrain HTTP brain server (the $0 semantic memory)
 swarph gateway serve     run the bundled mesh-gateway server (the mesh's coordination/DM hub)
 swarph service serve     stand up a $0 subscription-LLM HTTP lane (claude/codex/gemini)
+swarph channel <sub>     mesh channels — create/join/leave/list/members
+swarph schedule <sub>    scheduled events — create/list/get/enable/disable/delete/fire-now
+swarph lane <sub>        $0-lane orchestration — list/create/scale/delete/enqueue
 swarph highlight "<x>"   log a highlight to the shared git-backed swarph timeline
 swarph spawn <role>      launch a long-lived agent session as a named mesh cell
 swarph daemon            foreground inbox-drain loop (the mesh doorbell)
 swarph watchdog          detect + recover stranded agent sessions (cron- or systemd-driven)
+swarph install-multiplexer   fetch the Windows tmux multiplexer (psmux) — pinned + checksum-verified
 swarph add <uri>         install a hook / MCP server / skill by content-addressed URI
 swarph hooks             install Claude Code hooks as reusable artifacts
 swarph onboard / ratify  bring a new peer into the mesh (mechanics + witness ratification)
@@ -138,6 +144,31 @@ $ curl -s localhost:8799/delegate -H "Authorization: Bearer $TOK" \
 
 The load-bearing piece is **billing-scrub**: the subprocess env has every known provider API-key var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, …) stripped, so the wrapped CLI can *only* use its $0 subscription auth — it can never silently fall back to metered API billing. Default loopback bind (expose a tailnet IP explicitly); the bearer is `--token` > `SWARPH_SERVICE_TOKEN` > a freshly minted+printed token. Note the `gemini` (agy) lane reads the prompt from argv only and hard-caps its length (~4 KB) — very long prompts are rejected, not truncated. Run without the extra and the verb prints a `pip install "swarph-cli[service]"` hint and exits.
 
+### `swarph channel` / `swarph schedule` / `swarph lane`
+
+The gateway's **automation control plane** — channels (pub/sub), scheduled events, and the $0-lane orchestration — as first-class client verbs. They share `mesh`'s auth: identity is `--as` / `SWARPH_SELF`, the bearer is `--token-file` / `MESH_GATEWAY_TOKEN` / the peer-token file, and `--gateway` (default `http://localhost:8788`) points at the hub.
+
+```bash
+# channels — converge work into pub/sub rooms
+$ swarph channel create research --kind topic --description "market-structure notes"
+$ swarph channel join research --wake-policy mentions_only
+$ swarph channel list
+
+# scheduled events — operator-gated recurring/ conditional fires (a 403 is surfaced verbatim)
+$ swarph schedule create nightly-digest --trigger time --cron "0 7 * * *" \
+    --target lab-ovh --task "compile the overnight digest" --context "[[some-anchor]]"
+$ swarph schedule enable nightly-digest
+$ swarph schedule fire-now nightly-digest
+
+# lanes — drive the gateway's $0 worker pools
+$ swarph lane list
+$ swarph lane create judges --provider claude --model sonnet --n 3
+$ swarph lane enqueue judges --prompt "score this design ..."
+$ swarph lane scale judges --n 0
+```
+
+Pure-stdlib clients (no extra needed). Mutating channel/schedule/lane operations are operator-gated *server-side* — the verb just shapes and sends the request; an unauthorized caller sees the gateway's `403` on the normal error path.
+
 ### `swarph highlight`
 
 The swarph **timeline** is an append-only, multi-author `TIMELINE.md` — a git-backed continuous-learning log where every cell's highlights converge into one file. `swarph highlight` is the mechanics; *you* (or your agent) decide what's worth logging and which memory it links to.

{swarph_cli-0.18.0 → swarph_cli-0.20.0}/README.md

@@ -7,6 +7,8 @@ pip install swarph-cli
 swarph --version
 ```
 
+> **System requirement — a terminal multiplexer.** The session verbs (`spawn`, `cell`, `watchdog`) drive a `tmux`-compatible multiplexer. On **Linux/macOS** install `tmux` (`apt install tmux` / `brew install tmux`). On **Windows** there is no native tmux — install [**psmux**](https://github.com/psmux/psmux) (a Rust tmux-for-Windows, MIT) with `swarph install-multiplexer` (fetches the pinned, checksum-verified binary into `~/.swarph/bin`) or `winget install marlocarlo.psmux`.
+
 **What it is:** a multi-provider LLM command line. Run one-shot prompts or an interactive REPL against any supported provider; spawn long-lived agent *cells* that persist across restarts and coordinate over a mesh; install hooks, MCP servers, and skills by content-addressed URI. An open, inspectable substrate — not a closed orchestration platform.
 
 **Who it's for:** builders running more than one LLM who want them to *cooperate* instead of sitting in separate tabs — multi-agent systems across vendors, agnostic by design. A thin client over the [`swarph-mesh`](https://github.com/BrainSurfing-tech/swarph-mesh) substrate library.
@@ -28,10 +30,14 @@ swarph brain-ask "<q>"   search the swarph-brain (gbrain) memory — $0 cited an
 swarph brain serve       run the gbrain HTTP brain server (the $0 semantic memory)
 swarph gateway serve     run the bundled mesh-gateway server (the mesh's coordination/DM hub)
 swarph service serve     stand up a $0 subscription-LLM HTTP lane (claude/codex/gemini)
+swarph channel <sub>     mesh channels — create/join/leave/list/members
+swarph schedule <sub>    scheduled events — create/list/get/enable/disable/delete/fire-now
+swarph lane <sub>        $0-lane orchestration — list/create/scale/delete/enqueue
 swarph highlight "<x>"   log a highlight to the shared git-backed swarph timeline
 swarph spawn <role>      launch a long-lived agent session as a named mesh cell
 swarph daemon            foreground inbox-drain loop (the mesh doorbell)
 swarph watchdog          detect + recover stranded agent sessions (cron- or systemd-driven)
+swarph install-multiplexer   fetch the Windows tmux multiplexer (psmux) — pinned + checksum-verified
 swarph add <uri>         install a hook / MCP server / skill by content-addressed URI
 swarph hooks             install Claude Code hooks as reusable artifacts
 swarph onboard / ratify  bring a new peer into the mesh (mechanics + witness ratification)
@@ -94,6 +100,31 @@ $ curl -s localhost:8799/delegate -H "Authorization: Bearer $TOK" \
 
 The load-bearing piece is **billing-scrub**: the subprocess env has every known provider API-key var (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, …) stripped, so the wrapped CLI can *only* use its $0 subscription auth — it can never silently fall back to metered API billing. Default loopback bind (expose a tailnet IP explicitly); the bearer is `--token` > `SWARPH_SERVICE_TOKEN` > a freshly minted+printed token. Note the `gemini` (agy) lane reads the prompt from argv only and hard-caps its length (~4 KB) — very long prompts are rejected, not truncated. Run without the extra and the verb prints a `pip install "swarph-cli[service]"` hint and exits.
 
+### `swarph channel` / `swarph schedule` / `swarph lane`
+
+The gateway's **automation control plane** — channels (pub/sub), scheduled events, and the $0-lane orchestration — as first-class client verbs. They share `mesh`'s auth: identity is `--as` / `SWARPH_SELF`, the bearer is `--token-file` / `MESH_GATEWAY_TOKEN` / the peer-token file, and `--gateway` (default `http://localhost:8788`) points at the hub.
+
+```bash
+# channels — converge work into pub/sub rooms
+$ swarph channel create research --kind topic --description "market-structure notes"
+$ swarph channel join research --wake-policy mentions_only
+$ swarph channel list
+
+# scheduled events — operator-gated recurring/ conditional fires (a 403 is surfaced verbatim)
+$ swarph schedule create nightly-digest --trigger time --cron "0 7 * * *" \
+    --target lab-ovh --task "compile the overnight digest" --context "[[some-anchor]]"
+$ swarph schedule enable nightly-digest
+$ swarph schedule fire-now nightly-digest
+
+# lanes — drive the gateway's $0 worker pools
+$ swarph lane list
+$ swarph lane create judges --provider claude --model sonnet --n 3
+$ swarph lane enqueue judges --prompt "score this design ..."
+$ swarph lane scale judges --n 0
+```
+
+Pure-stdlib clients (no extra needed). Mutating channel/schedule/lane operations are operator-gated *server-side* — the verb just shapes and sends the request; an unauthorized caller sees the gateway's `403` on the normal error path.
+
 ### `swarph highlight`
 
 The swarph **timeline** is an append-only, multi-author `TIMELINE.md` — a git-backed continuous-learning log where every cell's highlights converge into one file. `swarph highlight` is the mechanics; *you* (or your agent) decide what's worth logging and which memory it links to.

{swarph_cli-0.18.0 → swarph_cli-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.18.0"
+version = "0.20.0"
 description = "The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }

{swarph_cli-0.18.0 → swarph_cli-0.20.0}/src/swarph_cli/__init__.py

@@ -16,6 +16,6 @@ The architecture splits CLI from substrate so:
 
 from __future__ import annotations
 
-__version__ = "0.18.0"
+__version__ = "0.20.0"
 
 __all__ = ["__version__"]

swarph_cli-0.20.0/src/swarph_cli/commands/_gateway_client.py

@@ -0,0 +1,38 @@
+"""Shared mesh-gateway HTTP-client helpers for the control-plane client verbs
+(``channel`` / ``schedule`` / ``lane``).
+
+Thin re-export of the ``mesh`` verb's proven auth + HTTP layer (so all gateway
+clients resolve identity/token and shape requests identically), plus a DELETE
+helper that ``mesh`` didn't need. Importing the underlying ``mesh`` helpers keeps
+one battle-tested implementation rather than four divergent copies.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+from .mesh import _add_common as add_common_args  # noqa: F401
+from .mesh import _http_get_json as get_json  # noqa: F401
+from .mesh import _post_json as post_json  # noqa: F401
+from .mesh import _resolve_self_name as resolve_self_name  # noqa: F401
+from .mesh import _resolve_token as resolve_token  # noqa: F401
+
+
+def delete_json(url: str, token: str, *, timeout: float = 10.0):
+    """DELETE ``url`` with a bearer token, returning ``(status, body)`` like the
+    mesh GET/POST helpers (status 0 on a connection-level URLError)."""
+    req = urllib.request.Request(
+        url, method="DELETE", headers={"Authorization": f"Bearer {token}"})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status, json.loads(resp.read().decode("utf-8") or "{}")
+    except urllib.error.HTTPError as exc:
+        try:
+            err_body = json.loads(exc.read().decode("utf-8") or "{}")
+        except Exception:
+            err_body = {"detail": str(exc)}
+        return exc.code, err_body
+    except urllib.error.URLError as exc:
+        return 0, {"detail": str(exc)}

swarph_cli-0.20.0/src/swarph_cli/commands/channel.py

@@ -0,0 +1,154 @@
+"""``swarph channel`` — mesh CHANNELS control-plane client (create / list /
+join / leave / members) over the shared gateway HTTP layer."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.parse
+
+from ._gateway_client import (
+    add_common_args,
+    get_json,
+    post_json,
+    resolve_self_name,
+    resolve_token,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="swarph channel",
+        description="Mesh CHANNELS control-plane commands.",
+    )
+    sub = p.add_subparsers(dest="command")
+
+    create = sub.add_parser("create", help="create a channel")
+    create.add_argument("name", help="channel name")
+    create.add_argument(
+        "--kind", required=True, choices=["announce", "topic", "group"]
+    )
+    create.add_argument("--visibility", default=None, choices=["open", "invite"])
+    create.add_argument("--description", default=None)
+    add_common_args(create)
+
+    listp = sub.add_parser("list", help="list channels")
+    add_common_args(listp)
+
+    join = sub.add_parser("join", help="join a channel")
+    join.add_argument("name", help="channel name")
+    join.add_argument(
+        "--wake-policy",
+        default=None,
+        choices=["mentions_only", "here_and_mentions", "all", "muted"],
+    )
+    add_common_args(join)
+
+    leave = sub.add_parser("leave", help="leave a channel")
+    leave.add_argument("name", help="channel name")
+    add_common_args(leave)
+
+    members = sub.add_parser("members", help="list channel members")
+    members.add_argument("name", help="channel name")
+    add_common_args(members)
+
+    return p
+
+
+def _ctx(args: argparse.Namespace) -> tuple[str, str, str]:
+    self_name = resolve_self_name(args.self_name)
+    token = resolve_token(self_name, args.token_file)
+    return self_name, token, args.gateway.rstrip("/")
+
+
+def _fail(sub: str, status: int, payload: dict) -> int:
+    detail = payload.get("detail", "<error>")
+    print(f"swarph channel {sub}: gateway {status}: {detail}", file=sys.stderr)
+    return 1
+
+
+def _ok(status: int) -> bool:
+    return 200 <= status < 300
+
+
+def _run_create(args: argparse.Namespace) -> int:
+    self_name, token, base = _ctx(args)
+    body = {"name": args.name, "kind": args.kind, "created_by": self_name}
+    if args.visibility is not None:
+        body["visibility"] = args.visibility
+    if args.description is not None:
+        body["description"] = args.description
+    status, payload = post_json(f"{base}/channels", body, token)
+    if not _ok(status):
+        return _fail("create", status, payload)
+    print(f"created channel {args.name}")
+    return 0
+
+
+def _run_list(args: argparse.Namespace) -> int:
+    _self, token, base = _ctx(args)
+    status, payload = get_json(f"{base}/channels", token)
+    if not _ok(status):
+        return _fail("list", status, payload)
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+def _run_join(args: argparse.Namespace) -> int:
+    self_name, token, base = _ctx(args)
+    name = urllib.parse.quote(args.name, safe="")
+    body = {"peer": self_name}
+    if args.wake_policy is not None:
+        body["wake_policy"] = args.wake_policy
+    status, payload = post_json(f"{base}/channels/{name}/join", body, token)
+    if not _ok(status):
+        return _fail("join", status, payload)
+    print(f"joined {args.name}")
+    return 0
+
+
+def _run_leave(args: argparse.Namespace) -> int:
+    self_name, token, base = _ctx(args)
+    name = urllib.parse.quote(args.name, safe="")
+    status, payload = post_json(
+        f"{base}/channels/{name}/leave", {"peer": self_name}, token
+    )
+    if not _ok(status):
+        return _fail("leave", status, payload)
+    print(f"left {args.name}")
+    return 0
+
+
+def _run_members(args: argparse.Namespace) -> int:
+    _self, token, base = _ctx(args)
+    name = urllib.parse.quote(args.name, safe="")
+    status, payload = get_json(f"{base}/channels/{name}/members", token)
+    if not _ok(status):
+        return _fail("members", status, payload)
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+def run_channel(argv: list) -> int:
+    p = _build_parser()
+    args = p.parse_args(argv)
+    if args.command is None:
+        p.print_help()
+        return 0
+    try:
+        if args.command == "create":
+            return _run_create(args)
+        if args.command == "list":
+            return _run_list(args)
+        if args.command == "join":
+            return _run_join(args)
+        if args.command == "leave":
+            return _run_leave(args)
+        if args.command == "members":
+            return _run_members(args)
+    except RuntimeError as e:
+        print(f"swarph channel: {e}", file=sys.stderr)
+        return 2
+    p.print_help()
+    return 0

swarph_cli-0.20.0/src/swarph_cli/commands/install_multiplexer.py

@@ -0,0 +1,59 @@
+"""``swarph install-multiplexer`` — fetch the checksum-verified psmux binary.
+
+swarph's session machinery needs a ``tmux``-compatible multiplexer on PATH. On
+Linux/macOS that's native ``tmux`` (install via apt/brew). On Windows there's no
+pip/npm package, so this verb fetches the pinned, SHA-256-verified **psmux**
+release zip and drops its ``tmux.exe`` into ``--dir`` (default
+``~/.swarph/bin``). The download is verified before anything is written.
+
+Usage:
+  swarph install-multiplexer [--dir DIR] [--force] [--version 3.3.6]
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from swarph_cli.multiplexer import (
+    PSMUX_VERSION,
+    find_multiplexer,
+    install_psmux,
+)
+
+
+def run_install_multiplexer(argv: list) -> int:
+    p = argparse.ArgumentParser(
+        prog="swarph install-multiplexer",
+        description="Fetch the checksum-verified psmux (tmux-for-Windows) binary.")
+    p.add_argument("--dir", default=os.path.expanduser("~/.swarph/bin"),
+                   help="install directory (default ~/.swarph/bin)")
+    p.add_argument("--force", action="store_true",
+                   help="reinstall even if a multiplexer is already on PATH")
+    p.add_argument("--version", default=PSMUX_VERSION,
+                   help=f"psmux version to fetch (default {PSMUX_VERSION})")
+    args = p.parse_args(argv)
+
+    if sys.platform != "win32":
+        print("swarph install-multiplexer fetches the Windows psmux binary. On "
+              "Linux/macOS, tmux is the native multiplexer — install it via your "
+              "package manager (`apt install tmux` / `brew install tmux`).",
+              file=sys.stderr)
+        return 0
+
+    if not args.force:
+        present = find_multiplexer()
+        if present:
+            print(f"multiplexer already present at {present}")
+            return 0
+
+    try:
+        path = install_psmux(args.dir, version=args.version)
+    except (RuntimeError, ValueError, OSError) as err:
+        print(f"swarph install-multiplexer: {err}", file=sys.stderr)
+        return 1
+
+    print(f"installed psmux {args.version} -> {path}; "
+          f"add {args.dir} to your PATH")
+    return 0

swarph_cli-0.20.0/src/swarph_cli/commands/lane.py

@@ -0,0 +1,175 @@
+"""``swarph lane`` — client for the gateway's $0-lane orchestration.
+
+A lane is a pool of provider-backed workers the gateway scales on demand;
+``list``/``create``/``scale``/``delete``/``enqueue`` drive that control plane.
+Create/scale/delete are operator-gated server-side, so a 403 surfaces through
+the non-2xx path here like any other gateway error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.parse
+
+from ._gateway_client import (
+    add_common_args,
+    delete_json,
+    get_json,
+    post_json,
+    resolve_self_name,
+    resolve_token,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="swarph lane",
+        description="Drive the gateway's $0-lane orchestration.",
+    )
+    sub = p.add_subparsers(dest="command")
+
+    ls = sub.add_parser("list", help="list lanes")
+    add_common_args(ls)
+
+    create = sub.add_parser("create", help="create a lane (operator-gated)")
+    create.add_argument("name", help="lane name")
+    create.add_argument("--provider", required=True, help="lane provider")
+    create.add_argument("--model", required=True, help="provider model")
+    create.add_argument("--n", type=int, default=0, help="initial worker count")
+    create.add_argument("--context-text", default=None, help="inline context text")
+    create.add_argument(
+        "--context-file",
+        action="append",
+        default=[],
+        help="context file path (repeatable)",
+    )
+    add_common_args(create)
+
+    scale = sub.add_parser("scale", help="scale a lane (operator-gated)")
+    scale.add_argument("name", help="lane name")
+    scale.add_argument("--n", type=int, required=True, help="target worker count")
+    add_common_args(scale)
+
+    delete = sub.add_parser("delete", help="delete a lane (operator-gated)")
+    delete.add_argument("name", help="lane name")
+    add_common_args(delete)
+
+    enqueue = sub.add_parser("enqueue", help="enqueue a job on a lane")
+    enqueue.add_argument("name", help="lane name")
+    enqueue.add_argument("--prompt", required=True, help="job prompt")
+    enqueue.add_argument("--context-text", default=None, help="inline context text")
+    enqueue.add_argument(
+        "--context-file",
+        action="append",
+        default=[],
+        help="context file path (repeatable)",
+    )
+    add_common_args(enqueue)
+
+    return p
+
+
+def _fail(sub: str, status: int, payload: dict) -> int:
+    detail = payload.get("detail", "<error>")
+    print(f"swarph lane {sub}: gateway {status}: {detail}", file=sys.stderr)
+    return 1
+
+
+def _ok(status: int) -> bool:
+    return 200 <= status < 300
+
+
+def _auth(args: argparse.Namespace) -> tuple[str, str]:
+    self_name = resolve_self_name(args.self_name)
+    token = resolve_token(self_name, args.token_file)
+    return self_name, token
+
+
+def _run_list(args: argparse.Namespace) -> int:
+    _, token = _auth(args)
+    base = args.gateway.rstrip("/")
+    status, payload = get_json(f"{base}/lanes", token)
+    if not _ok(status):
+        return _fail("list", status, payload)
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+def _run_create(args: argparse.Namespace) -> int:
+    _, token = _auth(args)
+    base = args.gateway.rstrip("/")
+    body = {
+        "name": args.name,
+        "provider": args.provider,
+        "model": args.model,
+        "n": args.n,
+        "context_text": args.context_text or "",
+        "context_files": args.context_file,
+    }
+    status, payload = post_json(f"{base}/lanes", body, token)
+    if not _ok(status):
+        return _fail("create", status, payload)
+    print(f"created lane {args.name}")
+    return 0
+
+
+def _run_scale(args: argparse.Namespace) -> int:
+    _, token = _auth(args)
+    base = args.gateway.rstrip("/")
+    name = urllib.parse.quote(args.name, safe="")
+    status, payload = post_json(f"{base}/lanes/{name}/scale", {"n": args.n}, token)
+    if not _ok(status):
+        return _fail("scale", status, payload)
+    print(f"scaled {args.name} -> {args.n}")
+    return 0
+
+
+def _run_delete(args: argparse.Namespace) -> int:
+    _, token = _auth(args)
+    base = args.gateway.rstrip("/")
+    name = urllib.parse.quote(args.name, safe="")
+    status, payload = delete_json(f"{base}/lanes/{name}", token)
+    if not _ok(status):
+        return _fail("delete", status, payload)
+    print(f"deleted lane {args.name}")
+    return 0
+
+
+def _run_enqueue(args: argparse.Namespace) -> int:
+    _, token = _auth(args)
+    base = args.gateway.rstrip("/")
+    name = urllib.parse.quote(args.name, safe="")
+    body = {
+        "prompt": args.prompt,
+        "context_text": args.context_text or "",
+        "context_files": args.context_file,
+    }
+    status, payload = post_json(f"{base}/lanes/{name}/enqueue", body, token)
+    if not _ok(status):
+        return _fail("enqueue", status, payload)
+    print(f"enqueued on {args.name}: {json.dumps(payload)}")
+    return 0
+
+
+_DISPATCH = {
+    "list": _run_list,
+    "create": _run_create,
+    "scale": _run_scale,
+    "delete": _run_delete,
+    "enqueue": _run_enqueue,
+}
+
+
+def run_lane(argv: list) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        return 0
+    try:
+        return _DISPATCH[args.command](args)
+    except RuntimeError as exc:
+        print(f"swarph lane: {exc}", file=sys.stderr)
+        return 2