swarph-cli 0.72.34__tar.gz → 0.72.36__tar.gz

{swarph_cli-0.72.34/src/swarph_cli.egg-info → swarph_cli-0.72.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.72.34
+Version: 0.72.36
 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`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT

{swarph_cli-0.72.34 → swarph_cli-0.72.36}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.72.34"
+version = "0.72.36"
 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`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }

{swarph_cli-0.72.34 → swarph_cli-0.72.36}/src/swarph_cli/__init__.py

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

{swarph_cli-0.72.34 → swarph_cli-0.72.36}/src/swarph_cli/bench/backends.py

@@ -38,6 +38,8 @@ import urllib.request
 from dataclasses import dataclass
 from typing import Any, Callable, Optional, Protocol
 
+from swarph_cli.redact import encode_outbound_json
+
 
 @dataclass
 class BackendResult:
@@ -510,7 +512,7 @@ class TypedHttpBackend:
             body = _request_body(prompt, system)
             req = urllib.request.Request(
                 endpoint,
-                data=json.dumps(body).encode(),
+                data=encode_outbound_json(body, caller="bench.SystemOneBackend.generate"),
                 headers={"Content-Type": "application/json"},
                 method="POST",
             )
@@ -626,7 +628,7 @@ class HttpBackend:
                 scheme = self.auth.get("scheme") or ""
                 token = f"{scheme} {value}".strip() if scheme else value
                 headers[self.auth["header"]] = token
-            raw_body = json.dumps(body).encode()
+            raw_body = encode_outbound_json(body, caller="bench.HttpBackend.generate")
             self.calls += 1
             if self.transport is not None:
                 status, reason, raw = self.transport(endpoint, headers, raw_body)
@@ -919,7 +921,7 @@ class DecisionsBackend:
                 scheme = self.auth.get("scheme") or ""
                 token = f"{scheme} {value}".strip() if scheme else value
                 headers[self.auth["header"]] = token
-            raw_body = json.dumps(body).encode()
+            raw_body = encode_outbound_json(body, caller="bench.DecisionsBackend.generate")
             self.calls += 1
             if self.transport is not None:
                 status, reason, raw = self.transport(endpoint, headers, raw_body)

{swarph_cli-0.72.34 → swarph_cli-0.72.36}/src/swarph_cli/commands/board.py

@@ -43,6 +43,7 @@ from swarph_cli.commands.mesh import (
     _resolve_self_name,
     _resolve_token,
 )
+from swarph_cli.redact import redact_text, redact_value, encode_outbound_json
 
 
 _SENTINEL = object()
@@ -51,7 +52,7 @@ _SENTINEL = object()
 # ── HTTP: PATCH (mesh.py has GET + POST; the board needs PATCH for move/link) ──
 
 def _patch_json(url: str, body: dict, token: str, *, timeout: float = 10.0) -> tuple[int, dict]:
-    data = json.dumps(body).encode("utf-8")
+    data = encode_outbound_json(body, caller="board._patch_json")
     req = urllib.request.Request(
         url, data=data, method="PATCH",
         headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
@@ -89,11 +90,12 @@ def _normalize_due_at(value: str) -> str:
 
 
 def _card_add_payload(actor, project_id, title, *, body=None, ai2=False, priority=0,
-                      labels=None, due_at=None) -> dict:
+                      labels=None, due_at=None, opt_out=False) -> dict:
+    title = redact_text(title, opt_out=opt_out, caller="board.cards.add")
     p = {"actor": actor, "project_id": int(project_id), "title": title,
          "ai2": bool(ai2), "priority": int(priority)}
     if body:
-        p["body"] = body
+        p["body"] = redact_text(body, opt_out=opt_out, caller="board.cards.add")
     if labels:
         p["labels"] = list(labels)
     if due_at is not None:
@@ -151,7 +153,7 @@ def _format_obligations(data: dict) -> str:
 
 
 def _card_edit_payload(actor, title, body, *, due_at=_SENTINEL, project_id=None,
-                       priority=None) -> dict:
+                       priority=None, opt_out=False) -> dict:
     """#191: the edit patch — title and/or body, the two fields that made a
     card's text write-once until the gateway grew them (BoardCardPatch).
 
@@ -173,9 +175,9 @@ def _card_edit_payload(actor, title, body, *, due_at=_SENTINEL, project_id=None,
     """
     patch = {"actor": actor}
     if title is not None:
-        patch["title"] = title
+        patch["title"] = redact_text(title, opt_out=opt_out, caller="board.cards.edit")
     if body is not None:
-        patch["body"] = body
+        patch["body"] = redact_text(body, opt_out=opt_out, caller="board.cards.edit")
     if due_at is not _SENTINEL:
         # "" is the gateway's CLEAR sentinel; None means "not mentioned" and the
         # write is skipped while the old date is echoed back (#901).
@@ -190,7 +192,7 @@ def _card_edit_payload(actor, title, body, *, due_at=_SENTINEL, project_id=None,
     return patch
 
 
-def _write_card_preimage(actor, gateway, card_id, card, patch) -> Path:
+def _write_card_preimage(actor, gateway, card_id, card, patch, *, opt_out=False) -> Path:
     """Append the card's CURRENT title and body to a local log BEFORE an edit
     replaces them. Returns the path written.
 
@@ -213,10 +215,10 @@ def _write_card_preimage(actor, gateway, card_id, card, patch) -> Path:
         "gateway": gateway,
         "card": card_id,
         "body_version": card.get("body_version"),
-        "prev_title": card.get("title"),
-        "prev_body": card.get("body"),
-        "new_title": patch.get("title"),
-        "new_body": patch.get("body"),
+        "prev_title": redact_text(card.get("title"), opt_out=opt_out, caller="board.cards.edit"),
+        "prev_body": redact_text(card.get("body"), opt_out=opt_out, caller="board.cards.edit"),
+        "new_title": redact_text(patch.get("title"), opt_out=opt_out, caller="board.cards.edit"),
+        "new_body": redact_text(patch.get("body"), opt_out=opt_out, caller="board.cards.edit"),
     }
     path = card_preimage_path()
     path.parent.mkdir(parents=True, exist_ok=True)
@@ -251,10 +253,11 @@ def _apply_label(current: list, action: str, label: str) -> list:
     return [x for x in cur if x != lab]
 
 
-def _project_add_payload(actor, slug, title, *, goal=None) -> dict:
+def _project_add_payload(actor, slug, title, *, goal=None, opt_out: bool = False) -> dict:
+    title = redact_text(title, opt_out=opt_out, caller="board.projects")
     p = {"actor": actor, "slug": slug, "title": title}
     if goal:
-        p["goal"] = goal
+        p["goal"] = redact_text(goal, opt_out=opt_out, caller="board.projects")
     return p
 
 
@@ -546,7 +549,8 @@ def _say_line(resp: dict, card_id, to_node: str, *, reason: Optional[str] = None
 
 
 def _card_say_payload(from_node: str, to_node: str, kind: str, content: str,
-                      thread_uuid: str) -> dict:
+                      thread_uuid: str, *, opt_out=False) -> dict:
+    content = redact_text(content, opt_out=opt_out, caller="board.cards.say")
     return {
         "from_node": from_node,
         "to_node": to_node,
@@ -726,7 +730,7 @@ def _json_flag(flag: str, value: str):
 
 def _ask_payload(self_name, what, *, holder=None, step=None, needs=None, hours=None,
                  done=None, accept=None, accept_json=None, kind="action",
-                 timeout_hours=None, task=None, task_needs=None) -> dict:
+                 timeout_hours=None, task=None, task_needs=None, opt_out=False) -> dict:
     """POST /board/cards/{id}/ask body. None = not mentioned = key ABSENT (#191's
     rule; test_532 pins that a null `accept` on the wire would overwrite the
     gateway's own normalization). No holder → `requested`; `me` → the caller's
@@ -736,6 +740,7 @@ def _ask_payload(self_name, what, *, holder=None, step=None, needs=None, hours=N
     if accept is not None and accept_json is not None:
         raise ValueError("pass --accept or --accept-json, not both — "
                          "one check per row")
+    what = redact_text(what, opt_out=opt_out, caller="board.cards.ask")
     p = {"what": what, "created_by": self_name, "kind": kind}
     if holder is not None:
         p["holder"] = self_name if holder == "me" else holder
@@ -746,11 +751,11 @@ def _ask_payload(self_name, what, *, holder=None, step=None, needs=None, hours=N
     if hours is not None:
         p["hours"] = hours
     if done is not None:
-        p["done"] = done
+        p["done"] = redact_text(done, opt_out=opt_out, caller="board.cards.ask")
     if accept is not None:
-        p["accept"] = accept
+        p["accept"] = redact_text(accept, opt_out=opt_out, caller="board.cards.ask")
     if accept_json is not None:
-        p["accept_json"] = accept_json
+        p["accept_json"] = redact_value(accept_json, opt_out=opt_out, caller="board.cards.ask")
     if timeout_hours is not None:
         p["timeout_hours"] = timeout_hours
     if task is not None:
@@ -830,7 +835,7 @@ def _ask_line(d) -> str:
     return line
 
 
-def _confirm_flow_payload(actor: str, holders, what=None) -> dict:
+def _confirm_flow_payload(actor: str, holders, what=None, *, opt_out=False) -> dict:
     """#801: {actor, holders: {step: peer}, what}. `--holder STEP=PEER` is parsed here so a
     malformed override is refused before the request, naming the form."""
     body = {"actor": actor}
@@ -844,7 +849,7 @@ def _confirm_flow_payload(actor: str, holders, what=None) -> dict:
             out[step] = peer
         body["holders"] = out
     if what:
-        body["what"] = what
+        body["what"] = redact_text(what, opt_out=opt_out, caller="board.cards.confirm-flow")
     return body
 
 
@@ -924,7 +929,7 @@ def _move_line(x) -> str:
     return line
 
 
-def _close_payload(outcome, evidence=None, evidence_json=None) -> dict:
+def _close_payload(outcome, evidence=None, evidence_json=None, *, opt_out=False) -> dict:
     """POST /board/obligations/{id}/close body (#1068): --evidence and/or
     --evidence-json, at least one. The CLI cannot know the row's stored
     accept, so it sends what it was given — the gateway requires the map
@@ -934,15 +939,15 @@ def _close_payload(outcome, evidence=None, evidence_json=None) -> dict:
                          "--evidence-json")
     p = {"outcome": outcome}
     if evidence is not None:
-        p["evidence"] = evidence
+        p["evidence"] = redact_text(evidence, opt_out=opt_out, caller="board.obligations.close")
     if evidence_json is not None:
-        p["evidence_json"] = evidence_json
+        p["evidence_json"] = redact_value(evidence_json, opt_out=opt_out, caller="board.obligations.close")
     return p
 
 
 def _amend_payload(step=None, holder=None, accept=None, hours=None,
                    needs_add=None, needs_remove=None, needs=None,
-                   accept_json=None) -> dict:
+                   accept_json=None, *, opt_out=False) -> dict:
     """PATCH /board/obligations/{id}/amend body. None = not mentioned; an empty
     `holder` is a REAL value (clears → `requested`), so the test is
     `is not None`, never truthiness (#191). `needs` is the contract's signed
@@ -953,6 +958,10 @@ def _amend_payload(step=None, holder=None, accept=None, hours=None,
     if accept is not None and accept_json is not None:
         raise ValueError("pass --accept or --accept-json, not both — "
                          "one check per row")
+    if accept is not None:
+        accept = redact_text(accept, opt_out=opt_out, caller="board.obligations")
+    if accept_json is not None:
+        accept_json = redact_value(accept_json, opt_out=opt_out, caller="board.obligations")
     signed = _step_list(needs)
     add = _step_list(needs_add) + [x for x in signed if not x.startswith("-")]
     rem = _step_list(needs_remove) + [x[1:] for x in signed if x.startswith("-")]
@@ -1313,7 +1322,7 @@ def run_board(argv: list[str]) -> int:
             st, d = _http_get_json(f"{gw}/board/projects", token)
             return _out(st, d, _format_projects, aj)
         if args.command == "add":
-            st, d = _post_json(f"{gw}/board/projects", _project_add_payload(self_name, args.slug, args.title, goal=args.goal), token)
+            st, d = _post_json(f"{gw}/board/projects", _project_add_payload(self_name, args.slug, args.title, goal=args.goal, opt_out=getattr(args, "no_redact", False)), token)
             return _out(st, d, lambda x: f"created project #{x.get('id')} ({x.get('slug')})", aj)
 
     if args.group == "obligations":
@@ -1332,7 +1341,8 @@ def run_board(argv: list[str]) -> int:
             try:
                 evidence_json = (_json_flag("--evidence-json", args.evidence_json)
                                  if args.evidence_json is not None else None)
-                payload = _close_payload(args.outcome, evidence, evidence_json)
+                payload = _close_payload(args.outcome, evidence, evidence_json,
+                                         opt_out=getattr(args, "no_redact", False))
             except ValueError as exc:
                 print(f"swarph board obligations close: {exc}", file=sys.stderr)
                 return 2
@@ -1362,8 +1372,9 @@ def run_board(argv: list[str]) -> int:
             st, d = _post_json(f"{gw}/board/obligations/{args.id}/take", {}, token)
             return _out(st, d, _obligation_act_line, aj)
         if args.command == "decline":
+            why = redact_text(args.why, opt_out=getattr(args, "no_redact", False), caller="board.obligations")
             st, d = _post_json(f"{gw}/board/obligations/{args.id}/decline",
-                               {"why": args.why}, token)
+                               {"why": why}, token)
             return _out(st, d, _obligation_act_line, aj)
         if args.command == "amend":
             try:
@@ -1373,7 +1384,8 @@ def run_board(argv: list[str]) -> int:
                                        accept=args.accept, hours=args.hours,
                                        needs_add=args.needs_add,
                                        needs_remove=args.needs_remove, needs=args.needs,
-                                       accept_json=accept_json)
+                                       accept_json=accept_json,
+                                       opt_out=getattr(args, "no_redact", False))
             except ValueError as exc:
                 print(f"swarph board obligations amend: {exc}", file=sys.stderr)
                 return 2
@@ -1385,6 +1397,7 @@ def run_board(argv: list[str]) -> int:
                 print("swarph board obligations withdraw: --reason is "
                       "whitespace-only", file=sys.stderr)
                 return 2
+            reason = redact_text(reason, opt_out=getattr(args, "no_redact", False), caller="board.obligations")
             st, d = _post_json(
                 f"{gw}/board/obligations/{args.id}/withdraw",
                 {"reason": reason}, token)
@@ -1441,7 +1454,7 @@ def run_board(argv: list[str]) -> int:
             st, d = _post_json(f"{gw}/board/cards", _card_add_payload(
                 self_name, pid, title, body=body, ai2=args.ai2,
                 priority=args.priority, labels=getattr(args, "labels", None),
-                due_at=args.due), token)
+                due_at=args.due, opt_out=getattr(args, "no_redact", False)), token)
             return _out(st, d, lambda x: f"created card #{x.get('id')} [{x.get('stage')}] (stage defaults to proposed — use `cards move` to advance)", aj)
         if args.command == "label":
             # READ the current set before replacing it. If the GET fails we must
@@ -1491,7 +1504,8 @@ def run_board(argv: list[str]) -> int:
             try:
                 patch = _card_edit_payload(
                     self_name, title_text, body_text, due_at=args.due,
-                    project_id=project_id, priority=args.priority)
+                    project_id=project_id, priority=args.priority,
+                    opt_out=getattr(args, "no_redact", False))
             except ValueError as exc:
                 print(f"swarph board cards edit: {exc}", file=sys.stderr)
                 return 2
@@ -1508,7 +1522,8 @@ def run_board(argv: list[str]) -> int:
                       f"an unrecoverable one", file=sys.stderr)
                 return 1
             try:
-                pre = _write_card_preimage(self_name, gw, args.id, cur, patch)
+                pre = _write_card_preimage(self_name, gw, args.id, cur, patch,
+                                           opt_out=getattr(args, "no_redact", False))
             except OSError as exc:
                 print(f"swarph board cards edit: cannot write the pre-image log "
                       f"({exc}) — refusing to write, for the same reason: the "
@@ -1541,7 +1556,7 @@ def run_board(argv: list[str]) -> int:
             # the row in one gateway call, or neither.
             if args.holder is not None and args.holder_flag is not None:
                 print("swarph board cards ask: holder given twice (positional and "
-                      "--holder) — pass one", file=sys.stderr)
+                       "--holder) — pass one", file=sys.stderr)
                 return 2
             holder = args.holder_flag or args.holder
             if holder is None and args.step is None:
@@ -1562,7 +1577,8 @@ def run_board(argv: list[str]) -> int:
                                     done=args.done, accept=args.accept,
                                     accept_json=accept_json, kind=args.kind,
                                     timeout_hours=args.timeout_hours,
-                                    task=args.task, task_needs=args.task_needs)
+                                    task=args.task, task_needs=args.task_needs,
+                                    opt_out=getattr(args, "no_redact", False))
             except ValueError as exc:
                 print(f"swarph board cards ask: {exc}", file=sys.stderr)
                 return 2
@@ -1570,7 +1586,8 @@ def run_board(argv: list[str]) -> int:
             return _out(st, d, _ask_line, args.json)
         if args.command == "confirm-flow":
             try:
-                body = _confirm_flow_payload(self_name, args.holder, args.what)
+                body = _confirm_flow_payload(self_name, args.holder, args.what,
+                                            opt_out=getattr(args, "no_redact", False))
             except ValueError as e:
                 print(f"swarph board cards confirm-flow: {e}", file=sys.stderr)
                 return 2
@@ -1614,7 +1631,8 @@ def run_board(argv: list[str]) -> int:
                 return 1
             st, d = _post_json(
                 f"{gw}/messages",
-                _card_say_payload(self_name, to_node, args.kind, content, thread_uuid),
+                _card_say_payload(self_name, to_node, args.kind, content, thread_uuid,
+                                  opt_out=getattr(args, "no_redact", False)),
                 token,
             )
             # A 403 here carries the gateway's explanation that attaching PUBLISHES

{swarph_cli-0.72.34 → swarph_cli-0.72.36}/src/swarph_cli/commands/brain_ask.py

@@ -33,6 +33,7 @@ import urllib.request
 
 from swarph_cli import identity
 from swarph_cli import tokens
+from swarph_cli.redact import encode_outbound_json
 from pathlib import Path
 from typing import Optional
 
@@ -204,7 +205,7 @@ def _resolve_token(token_file: Optional[str], self_name: str) -> Optional[str]:
 def _http_post(url: str, body: dict, token: str,
                accept: str = "application/json, text/event-stream",
                timeout: int = 30) -> str:
-    data = json.dumps(body).encode("utf-8")
+    data = encode_outbound_json(body, caller="brain_ask._http_post")
     req = urllib.request.Request(url, data=data, method="POST")
     req.add_header("Content-Type", "application/json")
     req.add_header("Accept", accept)

{swarph_cli-0.72.34 → swarph_cli-0.72.36}/src/swarph_cli/commands/cell_probe.py

@@ -145,9 +145,11 @@ def gateway_memory_list(gateway: str, token: str, timeout: int = 15) -> list[str
     gateway; :8792 is gbrain itself and speaks MCP at /mcp, where POST /memory is
     correctly refused. A route named without its coordinate cost a peer a
     measurement on 2026-09-05."""
+    from swarph_cli.redact import encode_outbound_json
+
     req = urllib.request.Request(
         gateway.rstrip("/") + "/memory",
-        data=json.dumps({"op": "list", "arguments": {}}).encode(),
+        data=encode_outbound_json({"op": "list", "arguments": {}}, caller="cell_probe.gateway_memory_list"),
         headers={"Authorization": "Bearer " + token,
                  "Content-Type": "application/json"})
     doc = json.loads(urllib.request.urlopen(req, timeout=timeout).read())

{swarph_cli-0.72.34 → swarph_cli-0.72.36}/src/swarph_cli/commands/channel.py

@@ -18,6 +18,7 @@ from ._gateway_client import (
     resolve_token,
 )
 from swarph_cli.console_safe import print_safe
+from swarph_cli.redact import redact_text
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -74,9 +75,10 @@ def _build_parser() -> argparse.ArgumentParser:
 
 # ── pure helpers (unit-tested) ────────────────────────────────────────────────
 
-def _post_payload(self_name: str, channel: str, kind: str, content: str) -> dict:
+def _post_payload(self_name: str, channel: str, kind: str, content: str, *, opt_out: bool = False) -> dict:
     """A channel post carries ``channel`` and NEVER ``to_node`` — the gateway
     rejects a message with both ("exactly one of {to_node, channel} required")."""
+    content = redact_text(content, opt_out=opt_out, caller="channel.post")
     return {"from_node": self_name, "channel": channel, "kind": kind, "content": content}
 
 
@@ -120,7 +122,7 @@ def _run_create(args: argparse.Namespace) -> int:
     if args.visibility is not None:
         body["visibility"] = args.visibility
     if args.description is not None:
-        body["description"] = args.description
+        body["description"] = redact_text(args.description, opt_out=getattr(args, "no_redact", False), caller="channel.create")
     status, payload = post_json(f"{base}/channels", body, token)
     if not _ok(status):
         return _fail("create", status, payload)
@@ -178,9 +180,10 @@ def _run_post(args: argparse.Namespace) -> int:
     except ContentError as exc:
         print(f"swarph channel post: {exc}", file=sys.stderr)
         return 1
+    content = redact_text(content, opt_out=getattr(args, "no_redact", False), caller="channel.post") or ""
     self_name, token, base = _ctx(args)
     status, payload = post_json(
-        f"{base}/messages", _post_payload(self_name, args.name, args.kind, content), token
+        f"{base}/messages", _post_payload(self_name, args.name, args.kind, content, opt_out=getattr(args, "no_redact", False)), token
     )
     if not _ok(status):
         return _fail("post", status, payload)

{swarph_cli-0.72.34 → swarph_cli-0.72.36}/src/swarph_cli/commands/codegraph_hook.py

@@ -35,6 +35,7 @@ from pathlib import Path
 from typing import Optional
 from swarph_cli import identity
 from swarph_cli.gateway_default import env_gateway
+from swarph_cli.redact import encode_outbound_json
 
 TIMEOUT_S = 6
 MAX_ROWS = 6
@@ -326,7 +327,7 @@ def query_gateway(term: str, gateway: str, token: str,
                          "gateway host (#578) — the graph was never asked"}
     req = urllib.request.Request(
         f"{gateway.rstrip('/')}/codegraph",
-        data=json.dumps({"query": term, "limit": limit}).encode(),
+        data=encode_outbound_json({"query": term, "limit": limit}, caller="codegraph_hook.query_gateway"),
         headers={"Authorization": f"Bearer {token}",
                  "Content-Type": "application/json"},
         method="POST",

swarph_cli-0.72.36/src/swarph_cli/commands/commander.py

@@ -0,0 +1,95 @@
+"""``swarph commander`` — propose a decision or an action. Card #1297.
+
+The cell asks. The commander decides, from the desktop, with a credential
+this command never holds. ``ask`` posts a decision. ``request`` posts
+``merge_pr`` or ``release_finish``. An MCP tool for the same queue is a
+later card.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from swarph_cli.commands import mesh as mesh_cmd
+
+
+def ask_body(question: str, options: list[str], card: int | None) -> dict:
+    body: dict = {"type": "decision", "question": question, "options": options}
+    if card is not None:
+        body["card_id"] = card
+    return body
+
+
+def request_body(kind: str, *, repo: str | None, pr: int | None,
+                 head: str | None, version: str | None, card: int | None) -> dict:
+    body: dict = {"type": kind, "pr": pr, "head_sha": head}
+    if kind == "merge_pr":
+        body["repo"] = repo
+    if kind == "release_finish":
+        body["version"] = version
+    if card is not None:
+        body["card_id"] = card
+    return body
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="swarph commander")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    ask = sub.add_parser("ask", help="propose a decision")
+    mesh_cmd._add_common(ask)
+    ask.add_argument("--question", required=True)
+    ask.add_argument("--options", default=None,
+                     help="comma-separated choices, e.g. yes,no")
+    ask.add_argument("--card", type=int, default=None)
+
+    req = sub.add_parser("request", help="propose merge_pr or release_finish")
+    mesh_cmd._add_common(req)
+    req.add_argument("type", choices=["merge_pr", "release_finish"])
+    req.add_argument("--repo", default=None)
+    req.add_argument("--pr", type=int, default=None)
+    req.add_argument("--head", default=None)
+    req.add_argument("--version", default=None)
+    req.add_argument("--card", type=int, default=None)
+    return p
+
+
+def _options(raw: str | None) -> list[str]:
+    if not raw:
+        return []
+    return [part.strip() for part in raw.split(",") if part.strip()]
+
+
+def run_commander(argv: list[str]) -> int:
+    args = _build_parser().parse_args(argv)
+    try:
+        self_name = mesh_cmd._resolve_self_name(args.self_name)
+        token = mesh_cmd._resolve_token(self_name, args.token_file)
+    except RuntimeError as exc:
+        print(f"swarph commander: {exc}", file=sys.stderr)
+        return 1
+    gw = args.gateway.rstrip("/")
+    if args.command == "ask":
+        body = ask_body(args.question, _options(args.options), args.card)
+    else:
+        if args.pr is None or not args.head:
+            print("swarph commander request: --pr and --head are required",
+                  file=sys.stderr)
+            return 2
+        if args.type == "merge_pr" and not args.repo:
+            print("swarph commander request: merge_pr requires --repo",
+                  file=sys.stderr)
+            return 2
+        if args.type == "release_finish" and not args.version:
+            print("swarph commander request: release_finish requires --version",
+                  file=sys.stderr)
+            return 2
+        body = request_body(args.type, repo=args.repo, pr=args.pr, head=args.head,
+                            version=args.version, card=args.card)
+    status, payload = mesh_cmd._post_json(f"{gw}/commander/requests", body, token)
+    if status in (200, 201):
+        print(f"commander request #{payload.get('id')} {payload.get('status')}")
+        return 0
+    detail = payload.get("detail") if isinstance(payload, dict) else payload
+    print(f"swarph commander: {detail}", file=sys.stderr)
+    return 1