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

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

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

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

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

{swarph_cli-0.72.9 → swarph_cli-0.72.11}/src/swarph_cli/channel.py

@@ -15,7 +15,12 @@ from pathlib import Path
 
 from swarph_cli import identity
 from swarph_cli.dm_frame import FIRST_START_GRACE_S, created_within, frame_text, rows
-from swarph_cli.scripts.dm_notify_filter import is_real_dm
+from swarph_cli.scripts.dm_notify_filter import (
+    _QUIET_CAP_S,
+    is_quiet_dm,
+    is_real_dm,
+    quiet_enabled,
+)
 
 PROTOCOL_VERSION = "2025-06-18"
 METHOD = "notifications/claude/channel"
@@ -127,8 +132,15 @@ class Channel:
         First start keeps a present row when created_at is within 30s before
         this poll or any time after, via dm_frame.created_within. Older rows
         set the cursor and are not pushed.
+
+        Card #1066: with quiet wakes enabled, TAKEN receipts and repo.merged
+        events are HELD, not pushed — carried with the next real push or
+        once each passes the cap. The hold is durable: held ids persist in
+        the cursor file, so a restart neither loses nor double-pushes them.
+        A held id missing from the inbox (rotated away) is dropped.
         """
         now = time.time() if now is None else now
+        quiet_on = quiet_enabled()
         notes: list[dict] = []
         if not self.inbox.is_file():
             self._heartbeat(now, None)
@@ -153,6 +165,8 @@ class Channel:
                 "offset": 0,
                 "anomaly_sent": False,
             }
+            if quiet_on:
+                self.cursor["held_quiet"] = []
             self._save()
             notes.append(_note(self.armed_line()))
         if self.cursor.get("inode") != st.st_ino:
@@ -162,6 +176,7 @@ class Channel:
         fresh = _rows(text[offset:])
         last = self.cursor.get("last_pushed_id")
         last_i = int(last) if last is not None else -1
+        held = self._held_entries()
         pending = []
         for row in fresh:
             if row.get("to_node") != self.cell:
@@ -175,30 +190,75 @@ class Channel:
                 continue
             if rid <= last_i:
                 continue
+            if quiet_on and is_quiet_dm(row):
+                if all(h["id"] != rid for h in held):
+                    held.append({"id": rid, "at": now})
+                continue
             pending.append(row)
         if self.foreign and not self.anomaly_sent:
             notes.append(_note(
                 f"{self.foreign} inbox rows dropped: to_node was not {self.cell}"))
             self.anomaly_sent = True
             self.cursor["anomaly_sent"] = True
+        # Card #1066 carry + cap: held rows flush with the first real push
+        # (held first — they arrived earlier) or once each passes the cap.
+        # Held rows are NEVER backlog-truncated: dropping a waited-on row
+        # would lose it, the exact FAIL this card names.
+        by_id = {}
+        for row in rows:
+            try:
+                by_id[int(row["id"])] = row
+            except (KeyError, TypeError, ValueError):
+                continue
+        carried, kept = [], []
+        for h in held:
+            if h["id"] not in by_id:
+                continue  # rotated out of the inbox: undeliverable, drop
+            if pending or now - h["at"] >= _QUIET_CAP_S:
+                carried.append(by_id[h["id"]])
+            else:
+                kept.append(h)
         if len(pending) > BACKLOG:
             skipped = len(pending) - BACKLOG
             pending = pending[-BACKLOG:]
             notes.append(_note(f"{skipped} older DMs not pushed, read the inbox"))
-        for row in pending:
+        for row in carried + pending:
             notes.append(_frame(row))
             self.cursor["last_pushed_id"] = int(row["id"])
+        # Byte-identical cursors when quiet is off: never introduce the key
+        # into a cursor that never had it.
+        if quiet_on or "held_quiet" in self.cursor:
+            self.cursor["held_quiet"] = kept
         self.cursor["offset"] = st.st_size
         self.cursor["inode"] = st.st_ino
         self._save()
-        if newest is not None and self.cursor.get("last_pushed_id") is not None:
-            if int(newest) > int(self.cursor["last_pushed_id"]):
+        covered = self.cursor.get("last_pushed_id")
+        for h in kept:
+            if covered is None or h["id"] > covered:
+                covered = h["id"]
+        if newest is not None and covered is not None:
+            if int(newest) > int(covered):
                 self.stall_since = self.stall_since or now
             else:
                 self.stall_since = None
         self._heartbeat(now, newest)
         return notes
 
+    def _held_entries(self) -> list:
+        """Durable hold, validated: a corrupt held_quiet resets, never kills
+        the poll (a dead channel from a bad cursor is worse than a re-push —
+        re-read rows re-hold by id)."""
+        raw = (self.cursor or {}).get("held_quiet") or []
+        out = []
+        for h in raw:
+            try:
+                if not isinstance(h, dict):
+                    continue
+                out.append({"id": int(h["id"]), "at": float(h["at"])})
+            except (KeyError, TypeError, ValueError):
+                continue
+        return out
+
     def _save(self) -> None:
         self.cursor_path.parent.mkdir(parents=True, exist_ok=True)
         self.cursor_path.write_text(json.dumps(self.cursor), encoding="utf-8")

swarph_cli-0.72.11/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

{swarph_cli-0.72.9 → swarph_cli-0.72.11}/src/swarph_cli/guide/GUIDE.md

@@ -549,6 +549,7 @@ answers `--help`; hook-plumbing verbs are the callbacks hooks invoke, not comman
 - `swarph schedule` -- the gateway's scheduled events: create, list, get, enable, disable, delete, fire-now.
 - `swarph service` -- stand up a $0 subscription-LLM HTTP lane.
 - `swarph spawn` -- run a cell from its role name or yaml path.
+- `swarph sweep` -- the card-#1064 stuck-work sweep: blocked rows and unreviewed PRs, DMs the blocker, `swarph sweep --dry-run` reads only.
 - `swarph timeline` -- deterministic temporal lookup over the timeline: around, since, range (see [Code and history](#code-and-history)).
 - `swarph version` -- per-module versions and install origin (PEP 610).
 - `swarph wake-hook-output` -- hook plumbing: the silent-wake SessionStart callback.

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

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