swarph-cli 0.72.8__tar.gz → 0.72.10__tar.gz

{swarph_cli-0.72.8/src/swarph_cli.egg-info → swarph_cli-0.72.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.72.8
+Version: 0.72.10
 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.8 → swarph_cli-0.72.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.72.8"
+version = "0.72.10"
 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.8 → swarph_cli-0.72.10}/src/swarph_cli/__init__.py

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

swarph_cli-0.72.10/src/swarph_cli/commands/roster.py

@@ -0,0 +1,237 @@
+"""``swarph roster`` — read/write the gateway's operator-maintained capacity table.
+
+card #1061 (ROSTER AS DATA): the roster replaces tribal knowledge about who
+builds, who reviews, on which model/effort, under which quota, and who is out
+until when. Reads hit GET /roster (any authenticated caller); writes hit
+PUT /roster/{peer} (operators only — the gateway 403s the rest).
+
+  swarph roster [--peer PEER] [--json]          list the table (or one row)
+  swarph roster set PEER [--model M] [--effort E] [--roles r1,r2]
+      [--quota-pool P] [--quota-used PCT --quota-as-of TS] [--resets DATE]
+      [--until TS | --clear-until] [--note TEXT]
+
+A quota VALUE without its as_of coordinate is a rumour: --quota-used /
+--resets without --quota-as-of are refused client-side (exit 2) before the
+gateway's own 400. The pool NAME needs no coordinate (identifier, not a
+measurement). --clear-until is the grok-returns flow (explicit null clears).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.request
+
+# card #1061 role vocabulary — mirrors the gateway's _ROSTER_ROLES. A role
+# the gateway does not know is refused here (exit 2) before its 400; when the
+# vocabulary grows, BOTH pins change together (gateway tests + test_1061 below).
+ROSTER_ROLES = ("build", "validate", "plan-review", "orchestrate")
+
+
+def _http_get_json(url, token, *, timeout=10.0):
+    from swarph_cli.commands.mesh import _http_get_json as _get
+    return _get(url, token, timeout=timeout)
+
+
+def _http_put_json(url, body, token, *, timeout=10.0):
+    from swarph_cli.commands.mesh import _require_absolute_gateway_url
+    _require_absolute_gateway_url(url)
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data, method="PUT",
+        headers={"Authorization": f"Bearer {token}",
+                 "Content-Type": "application/json"})
+    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)}
+
+
+def _resolve(args):
+    from swarph_cli.tokens import resolve_token
+    resolution = resolve_token(args.self_name, args.token_file,
+                               identity_is_explicit=bool(args.self_name))
+    if resolution is None:
+        print("swarph roster: no token (set MESH_GATEWAY_TOKEN, pass "
+              "--token-file, or --as a peer with a stored token)",
+              file=sys.stderr)
+        return None
+    return resolution.token
+
+
+def _quota_compact(r):
+    if r.get("quota_used_pct") is None and not r.get("quota_pool"):
+        return "-"
+    parts = []
+    if r.get("quota_pool"):
+        parts.append(str(r["quota_pool"]))
+    if r.get("quota_used_pct") is not None:
+        parts.append(f"{r['quota_used_pct']}%")
+    if r.get("quota_as_of"):
+        parts.append(f"@{r['quota_as_of']}")
+    if r.get("quota_resets_at"):
+        parts.append(f"(resets {r['quota_resets_at']})")
+    return " ".join(parts)
+
+
+def _line(r):
+    roles = ",".join(r["roles"]) if r.get("roles") else "-"
+    bits = [r["peer"],
+            f"model={r.get('model') or '-'}",
+            f"effort={r.get('effort') or '-'}",
+            f"roles={roles}",
+            f"quota={_quota_compact(r)}"]
+    if r.get("unavailable_until"):
+        bits.append(f"out-until={r['unavailable_until']}")
+    bits.append(f"updated_by={r.get('updated_by') or '?'}")
+    return "  ".join(bits)
+
+
+def _run_list(args):
+    token = _resolve(args)
+    if token is None:
+        return 2
+    gateway = args.gateway.rstrip("/")
+    status, payload = _http_get_json(f"{gateway}/roster", token)
+    if status < 200 or status >= 300:
+        detail = payload.get("detail", "<gateway error>") if isinstance(payload, dict) else "<gateway error>"
+        print(f"swarph roster: gateway {status}: {detail}", file=sys.stderr)
+        return 1
+    rows = payload.get("roster") if isinstance(payload, dict) else None
+    if not isinstance(rows, list):
+        print("swarph roster: unexpected /roster shape (no roster list)",
+              file=sys.stderr)
+        return 1
+    if args.peer:
+        rows = [r for r in rows if isinstance(r, dict) and r.get("peer") == args.peer]
+        if not rows:
+            print(f"swarph roster: no row for {args.peer!r}", file=sys.stderr)
+            return 1
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        for r in rows:
+            print(_line(r) if isinstance(r, dict) else r)
+    return 0
+
+
+def _run_set(args):
+    token = _resolve(args)
+    if token is None:
+        return 2
+    if ((args.quota_used is not None or args.resets is not None)
+            and args.quota_as_of is None):
+        print("swarph roster set: --quota-used / --resets need --quota-as-of "
+              "(a quota value without its coordinate is a rumour)",
+              file=sys.stderr)
+        return 2
+    body = {}
+    if args.model is not None:
+        body["model"] = args.model
+    if args.effort is not None:
+        body["effort"] = args.effort
+    if args.roles is not None:
+        roles = [x.strip() for x in args.roles.split(",") if x.strip()]
+        bad = [x for x in roles if x not in ROSTER_ROLES]
+        if bad:
+            print(f"swarph roster set: unknown role(s) {bad} "
+                  f"(vocabulary: {', '.join(ROSTER_ROLES)})", file=sys.stderr)
+            return 2
+        body["roles"] = roles
+    if args.quota_pool is not None:
+        body["quota_pool"] = args.quota_pool
+    if args.quota_used is not None:
+        body["quota_used_pct"] = args.quota_used
+    if args.resets is not None:
+        body["quota_resets_at"] = args.resets
+    if args.quota_as_of is not None:
+        body["quota_as_of"] = args.quota_as_of
+    if args.until is not None:
+        body["unavailable_until"] = args.until
+    if args.clear_until:
+        body["unavailable_until"] = None
+    if args.note is not None:
+        body["note"] = args.note
+    if not body:
+        print("swarph roster set: nothing to set (pass a field flag)",
+              file=sys.stderr)
+        return 2
+    gateway = args.gateway.rstrip("/")
+    status, payload = _http_put_json(
+        f"{gateway}/roster/{args.peer}", body, token)
+    if status < 200 or status >= 300:
+        detail = payload.get("detail", "<gateway error>") if isinstance(payload, dict) else "<gateway error>"
+        print(f"swarph roster set: gateway {status}: {detail}", file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(payload, indent=2))
+    else:
+        print(f"updated {args.peer} (updated_by={payload.get('updated_by', '?')})")
+    return 0
+
+
+def _add_global(p):
+    p.add_argument("--as", dest="self_name", default=None,
+                   help="peer identity for token resolution")
+    from swarph_cli.gateway_default import env_gateway
+    p.add_argument("--gateway", default=env_gateway(),
+                   help="mesh-gateway base URL")
+    p.add_argument("--token-file", default=None,
+                   help="explicit Bearer [REDACTED] file")
+
+
+def _build_parser():
+    p = argparse.ArgumentParser(
+        prog="swarph roster",
+        description="Read/write the gateway capacity roster (card #1061).")
+    _add_global(p)
+    p.add_argument("--peer", default=None,
+                   help="show only this peer (list mode)")
+    p.add_argument("--json", action="store_true",
+                   help="print the raw gateway payload")
+    sub = p.add_subparsers(dest="command")
+    s = sub.add_parser("set", help="upsert one roster row (operators only)")
+    _add_global(s)
+    s.add_argument("peer", help="peer the row belongs to")
+    s.add_argument("--json", action="store_true",
+                   help="print the raw gateway payload")
+    s.add_argument("--model", default=None)
+    s.add_argument("--effort", default=None)
+    s.add_argument("--roles", default=None,
+                   help="comma-separated subset of " + ",".join(ROSTER_ROLES))
+    s.add_argument("--quota-pool", default=None)
+    s.add_argument("--quota-used", type=float, default=None,
+                   help="quota_used_pct (needs --quota-as-of)")
+    s.add_argument("--quota-as-of", default=None)
+    s.add_argument("--resets", default=None,
+                   help="quota_resets_at date (needs --quota-as-of)")
+    group = s.add_mutually_exclusive_group()
+    group.add_argument("--until", default=None,
+                       help="unavailable_until timestamp")
+    group.add_argument("--clear-until", action="store_true",
+                       help="clear unavailable_until (peer is back)")
+    s.add_argument("--note", default=None)
+    return p
+
+
+def run_roster(argv):
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "set":
+            return _run_set(args)
+        if args.command is None:
+            return _run_list(args)
+        parser.error(f"unknown command: {args.command}")
+    except RuntimeError as exc:
+        print(f"swarph roster: {exc}", file=sys.stderr)
+        return 2
+    return 2

swarph_cli-0.72.10/src/swarph_cli/commands/sweep.py

@@ -0,0 +1,413 @@
+"""``swarph sweep`` — the card-#1064 stuck-work sweep, one daily shot.
+
+Finds (a) open/taken rows blocked >=48h on an unmoving dependency and (b)
+approved-or-old open PRs with no obligation row naming them; DMs each
+finding's BLOCKING holder once per 24h (never the waiter) and appends one
+line per finding to the nightly watchtower report file. Never closes or
+reassigns: the only board write is the DM itself (POST /messages).
+
+  swarph sweep [--dry-run] [--repos R1,R2] [--state-file P] [--report-file P]
+      [--as SELF] [--gateway URL] [--token-file F] [--json]
+
+--dry-run reads the live board and GitHub, prints the findings, and writes
+nothing (no DMs, no state, no report) — the rehearsal shape.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+_STUCK_H = 48
+_RESEND_H = 24
+
+_DEFAULT_REPOS = (
+    "BrainSurfing-tech/swarph-cli",
+    "BrainSurfing-tech/mesh-gateway",
+    "BrainSurfing-tech/swarph-codegraph-fed",
+)
+
+_PR_URL_RE = re.compile(
+    r"github\.com/([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)/pull/(\d+)",
+    re.IGNORECASE)
+_PR_NUM_RE = re.compile(r"\bPR\s*#?(\d+)\b", re.IGNORECASE)
+
+
+def _parse_ts(v):
+    """Tolerant ISO parse -> epoch seconds, or None. Never raises: an
+    unparseable timestamp is unevaluable, not zero."""
+    if not v:
+        return None
+    try:
+        dt = datetime.fromisoformat(str(v).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        return None
+    try:
+        return dt.timestamp()
+    except (TypeError, ValueError, OverflowError, OSError):
+        return None
+
+
+def _age_days(now, ts):
+    return round((now - ts) / 86400)
+
+
+def _row_last_change(row):
+    for k in ("closed_at", "taken_at", "created_at"):
+        ts = _parse_ts(row.get(k))
+        if ts is not None:
+            return ts
+    return None
+
+
+def _named_prs(rows):
+    """(repo-or-None, number) pairs obligation rows name: full URLs match
+    exactly; bare PR numbers match by number across tracked repos."""
+    named = set()
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        blob = " ".join(
+            str(row.get(k) or "") for k in ("accept", "close_evidence"))
+        for m in _PR_URL_RE.finditer(blob):
+            try:
+                named.add((m.group(1).lower(), int(m.group(2))))
+            except ValueError:
+                continue
+        for m in _PR_NUM_RE.finditer(blob):
+            try:
+                named.add((None, int(m.group(1))))
+            except ValueError:
+                continue
+    return named
+
+
+def _graph_steps(http_get, gateway, token, card_id, cache):
+    if card_id in cache:
+        return cache[card_id]
+    try:
+        status, body = http_get(
+            f"{gateway}/board/cards/{card_id}/graph", token)
+    except Exception:
+        return None
+    if status != 200 or not isinstance(body, dict):
+        return None
+    steps = body.get("steps")
+    if not isinstance(steps, list):
+        return None
+    cache[card_id] = steps
+    return steps
+
+
+def _row_findings(rows, by_id, http_get, gateway, token, now):
+    """Kind (a): one finding per (open taken waiter, unsatisfied old need)."""
+    out = []
+    cache = {}
+    for w in rows:
+        if w.get("status") != "open" or not w.get("taken_at"):
+            continue
+        step = w.get("step")
+        if not step:
+            continue
+        card_id = w.get("card_id")
+        if not isinstance(card_id, int) or isinstance(card_id, bool):
+            continue
+        steps = _graph_steps(http_get, gateway, token, card_id, cache)
+        if steps is None:
+            continue
+        entry = next((e for e in steps
+                      if isinstance(e, dict) and e.get("step") == step), None)
+        if entry is None:
+            continue
+        needs = entry.get("needs")
+        if not isinstance(needs, list):
+            continue
+        for need in needs:
+            if not isinstance(need, dict):
+                continue
+            sat = need.get("satisfied")
+            if sat is True:
+                continue
+            if sat is not False:
+                continue  # unevaluable need names no finding
+            rid = need.get("row_id")
+            dep = by_id.get(rid)
+            if not isinstance(dep, dict):
+                continue
+            if dep.get("status") == "closed":
+                continue  # terminal: satisfied or a rework case, not unmoving
+            changed = _row_last_change(dep)
+            if changed is None or now - changed < _STUCK_H * 3600:
+                continue
+            holder = dep.get("holder")
+            blocker = holder if holder and dep.get("holder_known", True) else None
+            out.append({
+                "kind": "row",
+                "waiter_id": w.get("id"),
+                "waiter": w.get("holder"),
+                "waiter_step": step,
+                "card_id": card_id,
+                "need": need.get("step"),
+                "need_id": rid,
+                "blocker": blocker,
+                "age_days": _age_days(now, changed),
+            })
+    return out
+
+
+def _pr_findings(named, gh_prs, repos, peers, now):
+    """Kind (b): approved-or-old open PRs no row names. An author with no
+    mesh peer is report-only — the CLI must not invent a recipient."""
+    out = []
+    for repo in repos:
+        try:
+            prs = gh_prs(repo)
+        except Exception:
+            continue
+        if not isinstance(prs, list):
+            continue
+        for pr in prs:
+            if not isinstance(pr, dict):
+                continue
+            try:
+                number = int(pr.get("number"))
+            except (TypeError, ValueError):
+                continue
+            if (repo.lower(), number) in named or (None, number) in named:
+                continue
+            approved = pr.get("reviewDecision") == "APPROVED"
+            created = _parse_ts(pr.get("createdAt"))
+            old = created is not None and now - created >= _STUCK_H * 3600
+            if not approved and not old:
+                continue
+            author = pr.get("author") or {}
+            login = author.get("login") if isinstance(author, dict) else None
+            # blocker names the responsible party even when they have no
+            # mesh peer — the SEND step DMs only peers (report-only else).
+            out.append({
+                "kind": "pr",
+                "repo": repo,
+                "number": number,
+                "title": pr.get("title") or "",
+                "url": pr.get("url") or "",
+                "approved": approved,
+                "age_days": _age_days(now, created) if created else None,
+                "blocker": login,
+            })
+    return out
+
+
+def _finding_key(f):
+    if f["kind"] == "row":
+        return f"row:{f['waiter_id']}:{f['need']}"
+    return f"pr:{f['repo']}#{f['number']}"
+
+
+def _report_line(now_iso, f):
+    if f["kind"] == "row":
+        return (f"{now_iso} STUCK row waiter=#{f['waiter_id']}({f['waiter']}) "
+                f"step={f['waiter_step']} card=#{f['card_id']} "
+                f"blocked-by=#{f['need_id']}({f['blocker']}) "
+                f"need={f['need']} need-age={f['age_days']}d")
+    how = "approved" if f["approved"] else f"age={f['age_days']}d"
+    return (f"{now_iso} STUCK pr {f['repo']}#{f['number']} "
+            f"'{f['title']}' ({how}, no review row) author={f['blocker']}")
+
+
+def _dm_content(f):
+    if f["kind"] == "row":
+        return (f"STUCK-WORK SWEEP: row #{f['waiter_id']} ({f['waiter']}, "
+                f"{f['waiter_step']}, card #{f['card_id']}) has waited on "
+                f"your row #{f['need_id']} ({f['need']}, unchanged "
+                f"{f['age_days']}d). Please move it, fail it, or say what "
+                f"it waits on.")
+    state = "approved" if f["approved"] else "open %sd" % (f['age_days'],)
+    return (f"STUCK-WORK SWEEP: your PR {f['repo']}#{f['number']} "
+            f"'{f['title']}' ({f['url']}) is {state} "
+            f"with no review row naming it. Please land it or ask for review.")
+
+
+def run_sweep(*, gateway, token, sender, repos, state_file, report_file,
+              now, http_get, http_post, gh_prs, dry_run=False):
+    """One sweep. Returns (rc, findings): rc 1 only when the board itself is
+    unreadable (nothing evaluable); findings are the SENT (or dry-run, would
+    send) findings. Only ever writes DMs + the two local files."""
+    gateway = gateway.rstrip("/")
+    try:
+        status, body = http_get(f"{gateway}/board/obligations", token)
+    except Exception:
+        status, body = None, None
+    if status != 200 or not isinstance(body, dict) or not isinstance(
+            body.get("obligations"), list):
+        print("swarph sweep: board unreadable — no findings, nothing sent",
+              file=sys.stderr)
+        return 1, []
+    rows = [r for r in body["obligations"] if isinstance(r, dict)]
+    by_id = {r.get("id"): r for r in rows
+             if isinstance(r.get("id"), int)}
+    try:
+        pstatus, pbody = http_get(f"{gateway}/peers", token)
+        peers = {p["name"] for p in pbody.get("peers", [])
+                 if isinstance(p, dict) and p.get("name")}
+        if pstatus != 200:
+            peers = set()
+    except Exception:
+        peers = set()
+
+    findings = _row_findings(rows, by_id, http_get, gateway, token, now)
+    findings += _pr_findings(_named_prs(rows), gh_prs, repos, peers, now)
+
+    try:
+        with open(state_file, encoding="utf-8") as fp:
+            sent = json.load(fp)
+        sent = sent if isinstance(sent, dict) else {}
+    except (OSError, ValueError):
+        sent = {}
+    now_iso = datetime.fromtimestamp(now, timezone.utc).isoformat()
+    fresh, updates = [], {}
+    for f in findings:
+        key = _finding_key(f)
+        try:
+            last = _parse_ts(sent.get(key))
+        except Exception:
+            last = None
+        if last is not None and now - last < _RESEND_H * 3600:
+            continue
+        fresh.append(f)
+        updates[key] = now_iso
+
+    if dry_run:
+        for f in fresh:
+            print("DRY " + _report_line(now_iso, f))
+        return 0, fresh
+
+    for f in fresh:
+        # DM only a blocker with a mesh peer: pinging the waiter instead is
+        # the FAIL, and inventing a recipient for a gh login is its cousin.
+        if f["blocker"] is not None and f["blocker"] in peers:
+            status, payload = http_post(
+                f"{gateway}/messages",
+                {"from_node": sender, "to_node": f["blocker"],
+                 "kind": "fyi", "content": _dm_content(f)},
+                token)
+            if status < 200 or status >= 300:
+                detail = (payload.get("detail", "<gateway error>")
+                          if isinstance(payload, dict) else "<gateway error>")
+                print(f"swarph sweep: DM to {f['blocker']} failed "
+                      f"{status}: {detail}", file=sys.stderr)
+                continue
+        line = _report_line(now_iso, f)
+        print(line)
+        try:
+            with open(report_file, "a", encoding="utf-8") as fp:
+                fp.write(line + "\n")
+        except OSError as exc:
+            print(f"swarph sweep: report append failed: {exc}",
+                  file=sys.stderr)
+    if updates:
+        sent.update(updates)
+        try:
+            with open(state_file, "w", encoding="utf-8") as fp:
+                json.dump(sent, fp)
+        except OSError as exc:
+            print(f"swarph sweep: state write failed: {exc}", file=sys.stderr)
+    return 0, fresh
+
+
+def _gh_prs(repo):
+    """Live gh transport: open PRs with the fields the matcher needs, or
+    None when gh is unusable (that repo's findings are skipped, not
+    invented)."""
+    try:
+        p = subprocess.run(
+            ["gh", "pr", "list", "--repo", repo, "--state", "open",
+             "--limit", "100", "--json",
+             "number,title,createdAt,reviewDecision,url,author"],
+            capture_output=True, text=True, encoding="utf-8",
+            errors="replace", timeout=60)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if p.returncode != 0:
+        return None
+    try:
+        data = json.loads(p.stdout or "[]")
+    except ValueError:
+        return None
+    return data if isinstance(data, list) else None
+
+
+def _default_state_file():
+    xdg = os.environ.get("XDG_STATE_HOME", "").strip()
+    root = xdg if xdg else os.path.join(os.path.expanduser("~"), ".local", "state")
+    return os.path.join(root, "swarph", "stuck-sweep.json")
+
+
+def _build_parser():
+    p = argparse.ArgumentParser(
+        prog="swarph sweep",
+        description="Daily stuck-work sweep: blocked rows + unreviewed PRs "
+                    "(card #1064). DMs blockers, never closes/reassigns.")
+    p.add_argument("--dry-run", action="store_true",
+                   help="print findings; send/record/write nothing")
+    p.add_argument("--repos", default=None,
+                   help="comma-separated owner/repo list (default "
+                        "$SWARPH_SWEEP_REPOS or the fleet three)")
+    p.add_argument("--state-file", default=None)
+    p.add_argument("--report-file", default=None,
+                   help="nightly watchtower report path "
+                        "(default $SWARPH_SWEEP_REPORT or state-adjacent log)")
+    p.add_argument("--json", action="store_true")
+    p.add_argument("--as", dest="self_name", default=None,
+                   help="DM sender identity")
+    from swarph_cli.gateway_default import env_gateway
+    p.add_argument("--gateway", default=env_gateway())
+    p.add_argument("--token-file", default=None)
+    return p
+
+
+def run_sweep_cmd(argv):
+    import time as _time
+    from swarph_cli.commands import mesh as _mesh
+    from swarph_cli.tokens import resolve_token
+    args = _build_parser().parse_args(argv)
+    try:
+        # #872 doctrine: an automated DM must name its sender. Dry-run sends
+        # nothing and needs no identity.
+        if not args.self_name and not args.dry_run:
+            print("swarph sweep: --as a sender is required (automated DMs "
+                  "must name their sender; --dry-run needs no identity)",
+                  file=sys.stderr)
+            return 2
+        resolution = resolve_token(
+            args.self_name, args.token_file,
+            identity_is_explicit=bool(args.self_name))
+        if resolution is None:
+            print("swarph sweep: no token (set MESH_GATEWAY_TOKEN, pass "
+                  "--token-file, or --as a sender)", file=sys.stderr)
+            return 2
+        sender = args.self_name or "(dry-run)"
+        repos = ([r.strip() for r in args.repos.split(",") if r.strip()]
+                 if args.repos else
+                 [r.strip() for r in os.environ.get(
+                     "SWARPH_SWEEP_REPOS", ",".join(_DEFAULT_REPOS)
+                 ).split(",") if r.strip()])
+        state_file = args.state_file or os.environ.get(
+            "SWARPH_SWEEP_STATE", _default_state_file())
+        report_file = (args.report_file or os.environ.get("SWARPH_SWEEP_REPORT")
+                       or os.path.splitext(state_file)[0] + ".log")
+        rc, findings = run_sweep(
+            gateway=args.gateway, token=resolution.token, sender=sender,
+            repos=repos, state_file=state_file, report_file=report_file,
+            now=_time.time(), http_get=_mesh._http_get_json,
+            http_post=_mesh._post_json, gh_prs=_gh_prs,
+            dry_run=args.dry_run)
+        if args.json:
+            print(json.dumps(findings, indent=2))
+        return rc
+    except RuntimeError as exc:
+        print(f"swarph sweep: {exc}", file=sys.stderr)
+        return 2