swarph-cli 0.72.17__tar.gz → 0.72.18__tar.gz

{swarph_cli-0.72.17/src/swarph_cli.egg-info → swarph_cli-0.72.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.72.17
+Version: 0.72.18
 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
@@ -497,6 +497,14 @@ swarph monitor stop
 | `none` | genuinely nothing: observe, append `inbox.log`, no ledger, **no unread tracking**. |
 | `webhook:<url>` | **held** pending an egress review — exits non-zero rather than silently no-op. |
 
+**Copilot tmux panes.** The reader recognizes Copilot CLI 1.0.94's color input
+box and `--no-color` composer using the bottom AIC summary, input borders, and
+status footer. It defers while `esc interrupt` indicates a running turn or
+the composer holds a human draft. The wake names `swarph_dm_unread`; delivery
+is recorded only after the composer is observed clear. Missing or incomplete
+pane captures send no keystrokes and leave delivery pending with a visible
+failure. Keep `pull` for layouts that hide or customize this chrome.
+
 **Two pieces of state that never share a variable.** The *observation cursor* (`cursor.json`) is what this monitor has READ from the gateway; it advances on observation, always, gated on nothing. A *delivery ledger* (`ledgers.json`, one per sink) advances only when that sink is satisfied and may lag arbitrarily far. So a dead tmux pane can no longer freeze the cursor, one dead sink cannot stall another, and a sink attached tomorrow starts with an empty ledger and replays from `inbox.log` (bounded, and it reports what it skipped).
 
 **Pull beats push.** Every push sink's liveness is a precondition for hearing anything — if the pane dies, "no wake arrived" is indistinguishable from "no mail arrived". A pull check run *by* the cell lives one layer above tmux and cannot die with it. Designed to drop straight into a SessionStart hook:

{swarph_cli-0.72.17 → swarph_cli-0.72.18}/README.md

@@ -448,6 +448,14 @@ swarph monitor stop
 | `none` | genuinely nothing: observe, append `inbox.log`, no ledger, **no unread tracking**. |
 | `webhook:<url>` | **held** pending an egress review — exits non-zero rather than silently no-op. |
 
+**Copilot tmux panes.** The reader recognizes Copilot CLI 1.0.94's color input
+box and `--no-color` composer using the bottom AIC summary, input borders, and
+status footer. It defers while `esc interrupt` indicates a running turn or
+the composer holds a human draft. The wake names `swarph_dm_unread`; delivery
+is recorded only after the composer is observed clear. Missing or incomplete
+pane captures send no keystrokes and leave delivery pending with a visible
+failure. Keep `pull` for layouts that hide or customize this chrome.
+
 **Two pieces of state that never share a variable.** The *observation cursor* (`cursor.json`) is what this monitor has READ from the gateway; it advances on observation, always, gated on nothing. A *delivery ledger* (`ledgers.json`, one per sink) advances only when that sink is satisfied and may lag arbitrarily far. So a dead tmux pane can no longer freeze the cursor, one dead sink cannot stall another, and a sink attached tomorrow starts with an empty ledger and replays from `inbox.log` (bounded, and it reports what it skipped).
 
 **Pull beats push.** Every push sink's liveness is a precondition for hearing anything — if the pane dies, "no wake arrived" is indistinguishable from "no mail arrived". A pull check run *by* the cell lives one layer above tmux and cannot die with it. Designed to drop straight into a SessionStart hook:

{swarph_cli-0.72.17 → swarph_cli-0.72.18}/pyproject.toml

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

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

{swarph_cli-0.72.17 → swarph_cli-0.72.18}/src/swarph_cli/commands/board.py

@@ -132,6 +132,12 @@ def _format_obligations(data: dict) -> str:
             marks.append(f"UNCLOSABLE:{_s(o['unclosable_reason'])}")
         state = _s(o.get("accept_state"))
         marks.append(f"accept:{state}" if state else "accept:missing")
+        if o.get("accept_format") == "json":
+            # #1068: a structured row reads evidenced/total — the reviewer
+            # checks condition by condition (--json carries each pair).
+            conds = o.get("conditions") or []
+            ev = sum(1 for x in conds if x.get("evidence"))
+            marks.append(f"conds:{ev}/{len(conds)}")
         if o.get("status") != "open":
             # a NULL outcome on a closed row is a pre-#562 legacy close — name
             # the absence rather than print a blank that reads as recorded
@@ -547,6 +553,28 @@ def _card_say_payload(from_node: str, to_node: str, kind: str, content: str,
 _NO_TIMEOUT = "NO TIMEOUT — this never goes red on its own; pass --timeout-hours if it should"
 
 
+def _parse_accept_conditions(accept):
+    """#1068: read a stored accept the way the gateway does — a JSON row
+    yields {"pass", "fail"}, prose or missing yields None. Never raises:
+    a render helper must not 500 a listing over one odd row."""
+    if not accept or not str(accept).strip():
+        return None
+    try:
+        obj = json.loads(str(accept))
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(obj, dict) or not isinstance(obj.get("pass"), list):
+        return None
+    passes = [p for p in obj["pass"]
+              if isinstance(p, dict) and isinstance(p.get("id"), str)
+              and isinstance(p.get("text"), str)]
+    if len(passes) != len(obj["pass"]) or not passes:
+        return None
+    fails = obj.get("fail", [])
+    return {"pass": [{"id": p["id"], "text": p["text"]} for p in passes],
+            "fail": [f for f in fails if isinstance(f, str)]}
+
+
 def _accept_line(accept) -> str:
     """#532's mint-time falsifier readout — shared by the pre-#591 and the §2
     success lines, because the rule is about the MOMENT, not the response
@@ -556,6 +584,13 @@ def _accept_line(accept) -> str:
         return ("NO ACCEPT CHECK — reads RED in the sweep; pass --accept "
                 "\"PASS = ... | FAIL = ...\" naming an observable and a way "
                 "it comes out negative")
+    parsed = _parse_accept_conditions(accept)
+    if parsed is not None:
+        # #1068: a structured check reads condition by condition, not as a blob.
+        line = "; ".join(f"{p['id']}: {p['text']}" for p in parsed["pass"])
+        if parsed["fail"]:
+            line += " | FAIL: " + "; ".join(parsed["fail"])
+        return f"accept: {line}"
     if not _FAIL_MARKER_RE.search(str(accept)):
         return ("accept check has NO FAIL BRANCH — marked NO-FAIL-BRANCH in "
                 "the sweep; a check that cannot come out negative is not one")
@@ -630,15 +665,28 @@ def _step_list(values) -> list[str]:
     return [n for n in names if n]
 
 
+def _json_flag(flag: str, value: str):
+    """Parse a --*-json flag locally (#1068): invalid JSON is refused here
+    (exit 2 via the caller's ValueError catch), never sent as a string the
+    gateway would have to guess at."""
+    try:
+        return json.loads(value)
+    except (ValueError, TypeError) as exc:
+        raise ValueError(f"{flag} is not valid JSON: {exc}")
+
+
 def _ask_payload(self_name, what, *, holder=None, step=None, needs=None, hours=None,
-                 done=None, accept=None, kind="action", timeout_hours=None,
-                 task=None, task_needs=None) -> dict:
+                 done=None, accept=None, accept_json=None, kind="action",
+                 timeout_hours=None, task=None, task_needs=None) -> 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
     own `--as` identity (the contract binds `me` to the token, never to an env
     var). `needs` is whatever `--needs` collected — see `_step_list`.
     """
+    if accept is not None and accept_json is not None:
+        raise ValueError("pass --accept or --accept-json, not both — "
+                         "one check per row")
     p = {"what": what, "created_by": self_name, "kind": kind}
     if holder is not None:
         p["holder"] = self_name if holder == "me" else holder
@@ -652,6 +700,8 @@ def _ask_payload(self_name, what, *, holder=None, step=None, needs=None, hours=N
         p["done"] = done
     if accept is not None:
         p["accept"] = accept
+    if accept_json is not None:
+        p["accept_json"] = accept_json
     if timeout_hours is not None:
         p["timeout_hours"] = timeout_hours
     if task is not None:
@@ -818,8 +868,25 @@ def _move_line(x) -> str:
     return line
 
 
+def _close_payload(outcome, evidence=None, evidence_json=None) -> 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
+    for a JSON pass, the string everywhere else."""
+    if evidence is None and evidence_json is None:
+        raise ValueError("nothing observed — pass --evidence and/or "
+                         "--evidence-json")
+    p = {"outcome": outcome}
+    if evidence is not None:
+        p["evidence"] = evidence
+    if evidence_json is not None:
+        p["evidence_json"] = evidence_json
+    return p
+
+
 def _amend_payload(step=None, holder=None, accept=None, hours=None,
-                   needs_add=None, needs_remove=None, needs=None) -> dict:
+                   needs_add=None, needs_remove=None, needs=None,
+                   accept_json=None) -> 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
@@ -827,15 +894,19 @@ def _amend_payload(step=None, holder=None, accept=None, hours=None,
     needs_remove; every edge list flattens through `_step_list`. Refuses the
     empty patch locally — the gateway 400s it too, but a round trip to learn
     you said nothing is the #256 shape one hop later."""
+    if accept is not None and accept_json is not None:
+        raise ValueError("pass --accept or --accept-json, not both — "
+                         "one check per row")
     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("-")]
     patch = {k: v for k, v in (("step", step), ("holder", holder), ("accept", accept),
+                               ("accept_json", accept_json),
                                ("hours", hours), ("needs_add", add or None),
                                ("needs_remove", rem or None)) if v is not None}
     if not patch:
-        raise ValueError("nothing to amend — pass --step, --holder, --accept, --hours, "
-                         "--needs-add and/or --needs-remove")
+        raise ValueError("nothing to amend — pass --step, --holder, --accept, --accept-json, "
+                         "--hours, --needs-add and/or --needs-remove")
     return patch
 
 
@@ -968,6 +1039,11 @@ def _build_parser() -> argparse.ArgumentParser:
                          "(#532). Omitting it mints an obligation that reads RED "
                          "in the sweep; a check with no FAIL branch is marked "
                          "NO-FAIL-BRANCH — 'verify it works' is not a check")
+    ck.add_argument("--accept-json", default=None, metavar="'{...}'",
+                    help="the structured check (#1068): '{\"pass\": [{\"id\", "
+                         "\"text\"}], \"fail\": [...]}'. Mutually exclusive "
+                         "with --accept; a PASS close of such a row needs "
+                         "--evidence-json keyed by condition id")
     ck.add_argument("--kind", default="action", help="obligation kind (default: action)")
     # #591: the step graph. `--holder` is an OPTION with its own dest — sharing
     # the positional's dest makes `--holder me --step build "<what>"` parse
@@ -1063,10 +1139,15 @@ def _build_parser() -> argparse.ArgumentParser:
                     choices=("pass", "fail", "cannot_evaluate", "skipped"),
                     help="the accept check's OUTCOME (`skipped` only on an "
                          "optional step — #591)")
-    oc.add_argument("--evidence", required=True,
+    oc.add_argument("--evidence", required=False, default=None,
                     help="what you OBSERVED running the check — whitespace is "
                          "refused: whitespace evidence is the vibe-close this "
                          "endpoint exists to kill")
+    oc.add_argument("--evidence-json", default=None, metavar="'{...}'",
+                    help="the per-condition evidence map (#1068): '{\"c1\": "
+                         "\"...\", ...}' keyed by the row's condition ids. "
+                         "Pass --evidence and/or --evidence-json; the gateway "
+                         "requires what the row's stored accept demands")
     oc.add_argument("--json", action="store_true"); _add_common(oc)
 
     ol = obl.add_parser(
@@ -1101,6 +1182,9 @@ def _build_parser() -> argparse.ArgumentParser:
     oa.add_argument("--holder", default=None, metavar="PEER",
                     help="reassign; pass an empty string to clear (back to requested)")
     oa.add_argument("--accept", default=None, metavar='"PASS = ... | FAIL = ..."')
+    oa.add_argument("--accept-json", default=None, metavar="'{...}'",
+                    help="replace the check with a structured one (#1068); "
+                         "mutually exclusive with --accept")
     oa.add_argument("--hours", type=int, default=None, help="clock override, up to 4x the menu value")
     oa.add_argument("--needs-add", action="append", dest="needs_add", default=None,
                     metavar="STEP", help="add an edge (repeatable)")
@@ -1172,17 +1256,23 @@ def run_board(argv: list[str]) -> int:
             # #562's CLI half: the explicit close act. The gateway guards the
             # identity (holder, creator, or board orchestrator) and refuses a
             # second close; the CLI's job is to refuse what it can see —
-            # whitespace evidence — and to propagate the gateway's refusals
-            # with their detail intact.
+            # whitespace evidence, invalid JSON, neither evidence — and to
+            # propagate the gateway's refusals with their detail intact.
             evidence = args.evidence
-            if not evidence.strip():
+            if evidence is not None and not evidence.strip():
                 print("swarph board obligations close: --evidence is "
                       "whitespace-only — the close act records what you "
                       "OBSERVED, and nothing was observed", file=sys.stderr)
                 return 2
+            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)
+            except ValueError as exc:
+                print(f"swarph board obligations close: {exc}", file=sys.stderr)
+                return 2
             st, d = _post_json(
-                f"{gw}/board/obligations/{args.id}/close",
-                {"outcome": args.outcome, "evidence": evidence}, token)
+                f"{gw}/board/obligations/{args.id}/close", payload, token)
             if st < 200 or st >= 300:
                 detail = d.get("detail", d) if isinstance(d, dict) else d
                 print(f"swarph board obligations close: gateway {st}: {_s(detail)}",
@@ -1212,10 +1302,13 @@ def run_board(argv: list[str]) -> int:
             return _out(st, d, _obligation_act_line, aj)
         if args.command == "amend":
             try:
+                accept_json = (_json_flag("--accept-json", args.accept_json)
+                               if args.accept_json is not None else None)
                 patch = _amend_payload(step=args.step, holder=args.holder,
                                        accept=args.accept, hours=args.hours,
                                        needs_add=args.needs_add,
-                                       needs_remove=args.needs_remove, needs=args.needs)
+                                       needs_remove=args.needs_remove, needs=args.needs,
+                                       accept_json=accept_json)
             except ValueError as exc:
                 print(f"swarph board obligations amend: {exc}", file=sys.stderr)
                 return 2
@@ -1388,11 +1481,18 @@ def run_board(argv: list[str]) -> int:
                       f"or positional). If {args.what!r} was meant as the holder, the "
                       f"\"<what>\" text is missing", file=sys.stderr)
                 return 2
-            body = _ask_payload(self_name, args.what, holder=holder,
-                                step=args.step, needs=args.needs, hours=args.hours,
-                                done=args.done, accept=args.accept, kind=args.kind,
-                                timeout_hours=args.timeout_hours,
-                                task=args.task, task_needs=args.task_needs)
+            try:
+                accept_json = (_json_flag("--accept-json", args.accept_json)
+                               if args.accept_json is not None else None)
+                body = _ask_payload(self_name, args.what, holder=holder,
+                                    step=args.step, needs=args.needs, hours=args.hours,
+                                    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)
+            except ValueError as exc:
+                print(f"swarph board cards ask: {exc}", file=sys.stderr)
+                return 2
             st, d = _post_json(f"{gw}/board/cards/{args.id}/ask", body, token)
             return _out(st, d, _ask_line, args.json)
         if args.command == "confirm-flow":

{swarph_cli-0.72.17 → swarph_cli-0.72.18}/src/swarph_cli/commands/mesh.py

@@ -2350,6 +2350,7 @@ _GROK_WAKE_PROMPT = "check mesh: swarph_dm_unread"
 # Muse 1.4.1 has no push channel either. The wake names the pull tool,
 # same text the grok and opencode sinks inject.
 _MUSE_WAKE_PROMPT = "check mesh: swarph_dm_unread"
+_COPILOT_WAKE_PROMPT = "check mesh: swarph_dm_unread"
 # A finished turn keeps its ▣ header and adds a duration.
 # Short turns read `· 3.3s` (drop-on-meta-edge, 1.18.33, card #961 post
 # 54557). A longer idle turn reads `· 3m 4s` (opencode pane, 2026-09-29
@@ -2991,6 +2992,8 @@ def _muse_running(lines: list[str]) -> bool:
 
 
 def _wake_prompt_for(lines: Optional[list[str]]) -> str:
+    if lines and _copilot_frame(lines) is not None:
+        return _COPILOT_WAKE_PROMPT
     if lines and _is_grok_pane(lines):
         return _GROK_WAKE_PROMPT
     if lines and _is_opencode_pane(lines):
@@ -3013,6 +3016,67 @@ def _sink_failure_detail(target: str) -> str:
     return "the sink is probably gone (session restart / renamed target)"
 
 
+def _copilot_frame(
+    lines: list[str],
+) -> Optional[tuple[Optional[str], Optional[bool]]]:
+    """Read Copilot's bottom input block, not transcript quotes (#386).
+
+    Both measured 1.0.94 layouts put the AIC summary immediately above
+    the input: ``--no-color`` uses rules and ``❯``; color uses a ``┃``
+    box. An identified but incomplete block stays unknown.
+    """
+    tail = _nonempty_tail(lines, 12)
+    summary = next(
+        (i for i in range(len(tail) - 1, -1, -1)
+         if re.search(r"Plan: .* · Session: .* AIC\b", tail[i])),
+        None,
+    )
+    if summary is None:
+        return None
+    block = [ln.strip() for ln in tail[summary + 1:]]
+    if not block:
+        return (None, None)
+    text = None
+    running = None
+    if block[0].startswith("╻▄"):
+        bottom = next(
+            (i for i, ln in enumerate(block) if ln.startswith("╹▀")), None,
+        )
+        if bottom is not None and bottom + 1 < len(block) - 1:
+            return None  # This block is history above another composer.
+        if bottom is not None and bottom + 1 == len(block) - 1:
+            footer = block[-1]
+            rows = block[1:bottom]
+            if rows and all(ln.startswith("┃") for ln in rows):
+                text = "\n".join(ln[1:].strip() for ln in rows).strip()
+                if "esc interrupt" in footer:
+                    running = True
+                elif "Interactive ·" in footer or "· autopilot ·" in footer:
+                    running = False
+    elif _is_muse_rule(block[0]):
+        bottom = next(
+            (i for i in range(1, len(block))
+             if _is_muse_rule(block[i])), None,
+        )
+        if bottom is not None and bottom + 1 < len(block) - 1:
+            return None
+        if bottom is not None and bottom + 1 == len(block) - 1:
+            rows = block[1:bottom]
+            if rows and rows[0].startswith("❯"):
+                text = "\n".join([rows[0][1:].strip(), *rows[1:]]).strip()
+                footer = block[-1]
+                if "esc interrupt" in footer:
+                    running = True
+                elif "Interactive ·" in footer or "· autopilot ·" in footer:
+                    running = False
+    else:
+        return None
+    if text is None or running is None:
+        return (None, None)
+    composer = "clear" if not text else "wake" if _only_wake_text(text) else "busy"
+    return (composer, running)
+
+
 def _agent_running(target: str) -> Optional[bool]:
     """True while a keystroke would miss the idle composer.
 
@@ -3030,6 +3094,9 @@ def _agent_running(target: str) -> Optional[bool]:
     lines = _capture_pane_lines(target)
     if lines is None:
         return None
+    copilot = _copilot_frame(lines)
+    if copilot is not None:
+        return copilot[1]
     if _is_opencode_pane(lines):
         return _opencode_running(lines)
     if _is_grok_pane(lines):
@@ -3080,6 +3147,9 @@ def _composer_state(target: str) -> Optional[str]:
     lines = _capture_pane_lines(target)
     if lines is None:
         return None
+    copilot = _copilot_frame(lines)
+    if copilot is not None:
+        return copilot[0]
     if _is_opencode_pane(lines):
         return _opencode_composer_state(lines)
     if _is_grok_pane(lines):

{swarph_cli-0.72.17 → swarph_cli-0.72.18}/src/swarph_cli/commands/roster.py

@@ -14,14 +14,26 @@ 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).
+
+  swarph roster sync [--peer PEER]... [--service-log PEER=PATH]...
+      [--state PATH] [--json]
+
+card #1071: one quota pass over local tmux panes — parse each membrane's
+usage display, PUT the roster on change, DM the commander on a crossing.
+Runs as the quota-writer #417 service (its token via MESH_GATEWAY_TOKEN /
+--token-file); at most one pane read per peer per 5 minutes.
 """
 from __future__ import annotations
 
 import argparse
 import json
+import os
+import subprocess
 import sys
 import urllib.error
 import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
 
 # 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
@@ -219,15 +231,199 @@ def _build_parser():
     group.add_argument("--clear-until", action="store_true",
                        help="clear unavailable_until (peer is back)")
     s.add_argument("--note", default=None)
+    sy = sub.add_parser("sync", help="one quota pass over local tmux panes "
+                                    "(card #1071): parse, PUT on change, "
+                                    "alert on crossing")
+    _add_global(sy)
+    sy.add_argument("--json", action="store_true",
+                    help="print the raw sync summary")
+    sy.add_argument("--peer", action="append", default=None,
+                    help="peer to read (repeatable; default: all local "
+                         "tmux sessions)")
+    sy.add_argument("--service-log", action="append", default=None,
+                    metavar="PEER=PATH",
+                    help="provider log tail for the headless error path "
+                         "(repeatable)")
+    sy.add_argument("--state", default=None, metavar="PATH",
+                    help="state file override (default: "
+                         "$XDG_STATE_HOME/swarph/quota_sync_state.json)")
     return p
 
 
+def _sync_state_path(explicit=None) -> Path:
+    """$XDG_STATE_HOME/swarph/quota_sync_state.json, else ~/.local/state —
+    the watchdog dm-wake convention, one file over."""
+    if explicit:
+        return Path(explicit).expanduser()
+    root = os.environ.get("XDG_STATE_HOME", "").strip()
+    if root:
+        return Path(root) / "swarph" / "quota_sync_state.json"
+    return Path.home() / ".local" / "state" / "swarph" / "quota_sync_state.json"
+
+
+def _load_sync_state(path: Path) -> dict:
+    try:
+        with Path(path).open(encoding="utf-8") as fp:
+            data = json.load(fp)
+    except (FileNotFoundError, OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _save_sync_state(path: Path, state: dict) -> None:
+    """Atomic best-effort persist (temp sibling + os.replace, never raises)."""
+    path = Path(path)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(state), encoding="utf-8")
+        os.replace(tmp, path)
+    except OSError:
+        pass
+
+
+def _local_tmux_peers() -> list:
+    """Session names on this box. [] when tmux is missing — sync then covers
+    only --peer/--service-log peers instead of failing the whole pass."""
+    try:
+        out = subprocess.run(["tmux", "list-sessions", "-F", "#{session_name}"],
+                             capture_output=True, timeout=10, text=True,
+                             encoding="utf-8", errors="replace")
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return []
+    if out.returncode != 0:
+        return []
+    return [ln.strip() for ln in (out.stdout or "").splitlines() if ln.strip()]
+
+
+def _capture_peer_pane(peer: str):
+    """One read-only full-height capture of the peer's active pane. Never
+    sends keys (ruling 6); None on any failure — the peer reads unknown."""
+    try:
+        out = subprocess.run(["tmux", "capture-pane", "-p", "-t", peer],
+                             capture_output=True, timeout=10, text=True,
+                             encoding="utf-8", errors="replace")
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return None
+    if out.returncode != 0:
+        return None
+    return out.stdout or ""
+
+
+def _parse_service_logs(values) -> dict:
+    """['PEER=PATH', ...] -> {peer: tail text}. A missing/unreadable log is
+    skipped (its peer still gets the pane path), never fatal."""
+    logs = {}
+    for item in values or []:
+        if "=" not in item:
+            raise ValueError(f"--service-log takes PEER=PATH, got {item!r}")
+        peer, _, path = item.partition("=")
+        peer, path = peer.strip(), path.strip()
+        if not peer or not path:
+            raise ValueError(f"--service-log takes PEER=PATH, got {item!r}")
+        try:
+            with open(path, encoding="utf-8", errors="replace") as fp:
+                fp.seek(0, os.SEEK_END)
+                size = fp.tell()
+                fp.seek(max(0, size - 65536))
+                logs[peer] = fp.read()
+        except OSError:
+            continue
+    return logs
+
+
+def _post_message(gateway: str, token: str, to_node: str, content: str) -> bool:
+    """DM the commander as the quota-writer service. True on HTTP 2xx."""
+    from swarph_cli.commands.mesh import _require_absolute_gateway_url
+    _require_absolute_gateway_url(gateway)
+    data = json.dumps({"from_node": "quota-writer", "to_node": to_node,
+                       "kind": "fyi", "content": content}).encode("utf-8")
+    req = urllib.request.Request(
+        f"{gateway}/messages", data=data, method="POST",
+        headers={"Authorization": f"Bearer {token}",
+                 "Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=10.0) as resp:
+            return 200 <= resp.status < 300
+    except (urllib.error.URLError, OSError):
+        return False
+
+
+def _run_sync(args):
+    from swarph_cli import quota_sync as qs
+    token = _resolve(args)
+    if token is None:
+        return 2
+    gateway = args.gateway.rstrip("/")
+    try:
+        service_logs = _parse_service_logs(args.service_log)
+    except ValueError as exc:
+        print(f"swarph roster sync: {exc}", file=sys.stderr)
+        return 2
+    peers = list(args.peer or []) or _local_tmux_peers()
+    for peer in service_logs:
+        if peer not in peers:
+            peers.append(peer)
+    if not peers:
+        print("swarph roster sync: no peers (no --peer, no tmux sessions, "
+              "no --service-log)", file=sys.stderr)
+        return 1
+
+    def _get_roster():
+        status, payload = _http_get_json(f"{gateway}/roster", token)
+        if status < 200 or status >= 300 or not isinstance(payload, dict):
+            return []
+        rows = payload.get("roster")
+        return rows if isinstance(rows, list) else []
+
+    failures = []
+
+    def _put_roster(peer, body):
+        status, payload = _http_put_json(
+            f"{gateway}/roster/{peer}", body, token)
+        if status < 200 or status >= 300:
+            failures.append(peer)
+
+    def _send_alert(peer, text):
+        _post_message(gateway, token, "commander",
+                      f"quota [{peer}]: {text}")
+
+    state_path = _sync_state_path(args.state)
+    summary = qs.sync_once(
+        peers=peers, capture=_capture_peer_pane, get_roster=_get_roster,
+        put_roster=_put_roster, send_alert=_send_alert,
+        service_logs=service_logs,
+        state=_load_sync_state(state_path),
+        now=datetime.now(timezone.utc))
+    _save_sync_state(state_path, summary.get("state", {}))
+    if args.json:
+        print(json.dumps(summary, indent=2))
+    else:
+        for peer, entry in summary.get("peers", {}).items():
+            if entry.get("skipped"):
+                print(f"  {peer}: skipped ({entry['skipped']})")
+                continue
+            bits = [entry.get("record", "?")]
+            if entry.get("put"):
+                bits.append("PUT")
+            for threshold in entry.get("alerts", []):
+                bits.append(f"ALERT {threshold}")
+            print(f"  {peer}: {' '.join(bits)}")
+    if failures:
+        print(f"swarph roster sync: PUT failed for: {', '.join(failures)}",
+              file=sys.stderr)
+        return 1
+    return 0
+
+
 def run_roster(argv):
     parser = _build_parser()
     args = parser.parse_args(argv)
     try:
         if args.command == "set":
             return _run_set(args)
+        if args.command == "sync":
+            return _run_sync(args)
         if args.command is None:
             return _run_list(args)
         parser.error(f"unknown command: {args.command}")