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

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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.72.8"
+version = "0.72.9"
 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.9}/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.9"
 
 __all__ = ["__version__"]

swarph_cli-0.72.9/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.8 → swarph_cli-0.72.9}/src/swarph_cli/guide/GUIDE.md

@@ -543,6 +543,7 @@ answers `--help`; hook-plumbing verbs are the callbacks hooks invoke, not comman
 - `swarph protocol-handler` -- register `swarph://` as an OS URL-scheme handler.
 - `swarph ratify` -- witness flip that admits an onboarded peer; takes the peer name and `--reason`.
 - `swarph rights` -- RBAC rights over the gateway (companion of `swarph group`).
+- `swarph roster` -- the gateway capacity table (card #1061): who builds, who reviews, quota, who is out until when. `swarph roster --peer <peer>`, `swarph roster set <peer> --roles build` (operators only).
 - `swarph rowclear-hook` -- SessionStart hook (card #432): when `source` is `clear`, write the new session id into the role's `<role>.session-id` pin so the next spawn resumes the cleared session.
 - `swarph scan` -- statically scan an artifact for dangerous patterns before publish.
 - `swarph schedule` -- the gateway's scheduled events: create, list, get, enable, disable, delete, fire-now.

{swarph_cli-0.72.8 → swarph_cli-0.72.9}/src/swarph_cli/main.py

@@ -110,6 +110,7 @@ _VERB_HANDLERS: dict[str, str] = {
     "board": "swarph_cli.commands.board.run_board",
     "group": "swarph_cli.commands.group.run_group",
     "rights": "swarph_cli.commands.group.run_rights",
+    "roster": "swarph_cli.commands.roster.run_roster",
     "mcp-server": "swarph_cli.commands.mcp_server.run_mcp_server",
     "compress": "swarph_cli.commands.compress.run_compress",
     "cell": "swarph_cli.commands.cell.run_cell",

{swarph_cli-0.72.8 → swarph_cli-0.72.9}/src/swarph_cli/rowclear.py

@@ -6,6 +6,10 @@ when the cell holds no live row, the pane reads idle, and no DM is owed.
 type nothing), or ``live``. v1 opt-in is drop-on-meta-edge only: a cell
 that owns a project keeps its context (design_1007 / optin_owners).
 
+v1.1 (#1362): a taken row whose step needs are UNMET is waiting, not
+working — it does not count as live. Needs state comes from the card's
+step graph; anything unreadable about it fails closed (no clear).
+
 A ``/clear`` mints a new Claude session id. The SessionStart hook with
 ``source=clear`` writes that id into the role's ``<role>.session-id``
 pin, so the next spawn resumes the cleared session instead of the long
@@ -95,11 +99,62 @@ def _dm_owed(state) -> bool:
     return False
 
 
+def _step_needs_met(state, row: dict, http_get: Callable,
+                      graphs: dict) -> Optional[bool]:
+    """Is this open row's work actionable (True), waiting (False), or
+    unevaluable (None)?
+
+    A row with no step has no needs to unmeet (ruling_1236: still live).
+    Otherwise the card's step graph (GET /board/cards/{id}/graph) names the
+    step's needs with a satisfied flag — every need satisfied means the
+    holder can act; one unsatisfied need means the cell is between rows.
+    Anything unreadable — no card id, a failed graph fetch, a missing step
+    entry, a needs entry without a boolean satisfied flag — is None: an
+    unevaluable row must not look like an empty cell (fail closed, #1362).
+    One graph fetch per card per poll; the same http_get the board read uses.
+    """
+    step = row.get("step")
+    if not step:
+        return True
+    card_id = row.get("card_id")
+    if not isinstance(card_id, int) or isinstance(card_id, bool):
+        return None
+    if card_id not in graphs:
+        url = f"{state.gateway}/board/cards/{card_id}/graph"
+        try:
+            status, body = http_get(url, state.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
+        graphs[card_id] = steps
+    for entry in graphs[card_id]:
+        if isinstance(entry, dict) and entry.get("step") == step:
+            needs = entry.get("needs")
+            if not isinstance(needs, list):
+                return None
+            for need in needs:
+                if not isinstance(need, dict) or not isinstance(
+                        need.get("satisfied"), bool):
+                    return None
+                if not need["satisfied"]:
+                    return False
+            return True
+    return None
+
+
 def _live_row_count(state, http_get: Callable) -> Optional[int]:
-    """How many unfinished rows this cell holds, or None if unread.
+    """How many ACTIONABLE rows this cell holds, or None if unread.
 
     None fails closed: an unreadable board must not look like an empty
     one, or a live row we failed to see gets a ``/clear``.
+
+    v1.1 (#1362): an open row whose step needs are unmet is waiting, not
+    working — it does not count. An open row with no step, or whose step
+    needs nothing, is still live (ruling_1236 unchanged).
     """
     url = f"{state.gateway}/board/obligations?holder={state.self_name}"
     try:
@@ -111,15 +166,21 @@ def _live_row_count(state, http_get: Callable) -> Optional[int]:
     rows = body.get("obligations")
     if not isinstance(rows, list):
         return None
+    graphs: dict = {}
     live = 0
     for row in rows:
         if not isinstance(row, dict):
             return None
         status = str(row.get("status") or "")
-        if status == _LIVE:
-            live += 1
-        elif status not in _FINISHED:
+        if status in _FINISHED:
+            continue
+        if status != _LIVE:
             return None
+        met = _step_needs_met(state, row, http_get, graphs)
+        if met is None:
+            return None
+        if met:
+            live += 1
     return live
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.72.8
+Version: 0.72.9
 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.9}/src/swarph_cli.egg-info/SOURCES.txt

@@ -110,6 +110,7 @@ src/swarph_cli/commands/peer_reply_drain.py
 src/swarph_cli/commands/postcompact_hook_output.py
 src/swarph_cli/commands/protocol_handler.py
 src/swarph_cli/commands/ratify.py
+src/swarph_cli/commands/roster.py
 src/swarph_cli/commands/rowclear_hook.py
 src/swarph_cli/commands/schedule.py
 src/swarph_cli/commands/security.py
@@ -196,6 +197,7 @@ tests/test_1017_muse_tui.py
 tests/test_1050_surrogate_wake.py
 tests/test_1052_opencode_deaf.py
 tests/test_1059_watchdog_unread_env.py
+tests/test_1061_roster_cli.py
 tests/test_124_register_merge.py
 tests/test_126_pending_from_complete.py
 tests/test_132_ensure_monitor_state_dir.py

swarph_cli-0.72.9/tests/test_1061_roster_cli.py

@@ -0,0 +1,137 @@
+"""card #1061 — ``swarph roster`` list + set against a faked gateway transport."""
+from __future__ import annotations
+
+from swarph_cli.commands import roster
+
+
+def _env(monkeypatch):
+    monkeypatch.setenv("MESH_GATEWAY_URL", "http://gw.test:8788")
+    monkeypatch.setenv("MESH_GATEWAY_TOKEN", "tok")
+
+
+def _fake_get(monkeypatch, payload, status=200):
+    calls = []
+
+    def _fake(url, token, **kw):
+        calls.append((url, token))
+        return status, payload
+
+    monkeypatch.setattr(roster, "_http_get_json", _fake)
+    return calls
+
+
+def _fake_put(monkeypatch, payload=None, status=200):
+    calls = []
+
+    def _fake(url, body, token, **kw):
+        calls.append((url, body, token))
+        return status, ({"peer": "p", "updated_by": "shared-token",
+                         **body} if payload is None else payload)
+
+    monkeypatch.setattr(roster, "_http_put_json", _fake)
+    return calls
+
+
+ROWS = {"roster": [
+    {"peer": "meta-muse", "model": None, "effort": "MAX", "roles": ["build"],
+     "quota_pool": None, "quota_used_pct": 4.0,
+     "quota_resets_at": None, "quota_as_of": "2026-10-07T17:00:00Z",
+     "unavailable_until": None, "note": None,
+     "updated_by": "seed #1061", "updated_at": "t"},
+    {"peer": "grok-researcher", "model": None, "effort": None, "roles": None,
+     "quota_pool": None, "quota_used_pct": None,
+     "quota_resets_at": None, "quota_as_of": None,
+     "unavailable_until": "2026-10-09T22:37:00Z", "note": None,
+     "updated_by": "seed #1061", "updated_at": "t"},
+]}
+
+
+def test_list_prints_one_line_per_peer(monkeypatch, capsys):
+    _env(monkeypatch)
+    _fake_get(monkeypatch, ROWS)
+    assert roster.run_roster([]) == 0
+    out = capsys.readouterr().out.splitlines()
+    assert len(out) == 2
+    assert out[0].startswith("meta-muse") and "roles=build" in out[0]
+    assert "out-until=2026-10-09T22:37:00Z" in out[1]
+
+
+def test_list_peer_filter_and_missing(monkeypatch, capsys):
+    _env(monkeypatch)
+    _fake_get(monkeypatch, ROWS)
+    assert roster.run_roster(["--peer", "grok-researcher"]) == 0
+    assert capsys.readouterr().out.startswith("grok-researcher")
+    assert roster.run_roster(["--peer", "nobody"]) == 1
+
+
+def test_list_gateway_error_is_exit_1(monkeypatch, capsys):
+    _env(monkeypatch)
+    _fake_get(monkeypatch, {"detail": "nope"}, status=403)
+    assert roster.run_roster([]) == 1
+    assert "403" in capsys.readouterr().err
+
+
+def test_set_sends_partial_body(monkeypatch, capsys):
+    _env(monkeypatch)
+    calls = _fake_put(monkeypatch)
+    rc = roster.run_roster(["set", "grok-researcher",
+                            "--until", "2026-10-09T22:37Z",
+                            "--note", "quota out"])
+    assert rc == 0
+    url, body, token = calls[0]
+    assert url == "http://gw.test:8788/roster/grok-researcher"
+    assert body == {"unavailable_until": "2026-10-09T22:37Z",
+                    "note": "quota out"}
+    assert token == "tok"
+    assert "shared-token" in capsys.readouterr().out
+
+
+def test_set_clear_until_sends_null(monkeypatch):
+    _env(monkeypatch)
+    calls = _fake_put(monkeypatch)
+    assert roster.run_roster(["set", "grok-researcher", "--clear-until"]) == 0
+    assert calls[0][1] == {"unavailable_until": None}
+
+
+def test_set_quota_without_as_of_refused_client_side(monkeypatch, capsys):
+    _env(monkeypatch)
+    calls = _fake_put(monkeypatch)
+    assert roster.run_roster(["set", "p", "--quota-used", "70"]) == 2
+    assert roster.run_roster(["set", "p", "--resets", "2026-10-13"]) == 2
+    assert calls == []  # refused before any transport
+    assert "as-of" in capsys.readouterr().err
+
+
+def test_set_quota_with_as_of_sends_all_three(monkeypatch):
+    _env(monkeypatch)
+    calls = _fake_put(monkeypatch)
+    assert roster.run_roster(["set", "cursor-lin", "--quota-pool", "Cursor",
+                              "--quota-used", "70",
+                              "--quota-as-of", "2026-10-07T17:00:00Z",
+                              "--resets", "2026-10-13"]) == 0
+    assert calls[0][1] == {"quota_pool": "Cursor", "quota_used_pct": 70.0,
+                           "quota_as_of": "2026-10-07T17:00:00Z",
+                           "quota_resets_at": "2026-10-13"}
+
+
+def test_set_unknown_role_refused_client_side(monkeypatch, capsys):
+    _env(monkeypatch)
+    calls = _fake_put(monkeypatch)
+    assert roster.run_roster(["set", "p", "--roles", "build,pilot"]) == 2
+    assert calls == []
+    assert "pilot" in capsys.readouterr().err
+
+
+def test_set_gateway_403_names_the_gate(monkeypatch, capsys):
+    _env(monkeypatch)
+    _fake_put(monkeypatch, {"detail": "roster PUT requires an operator"},
+              status=403)
+    assert roster.run_roster(["set", "p", "--model", "M"]) == 1
+    assert "403" in capsys.readouterr().err
+
+
+def test_set_with_no_fields_is_usage_error(monkeypatch, capsys):
+    _env(monkeypatch)
+    calls = _fake_put(monkeypatch)
+    assert roster.run_roster(["set", "p"]) == 2
+    assert calls == []