swarph-cli 0.41.3__tar.gz → 0.41.7__tar.gz

{swarph_cli-0.41.3/src/swarph_cli.egg-info → swarph_cli-0.41.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.41.3
+Version: 0.41.7
 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`, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT
@@ -24,7 +24,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: swarph-mesh>=0.5.0
-Requires-Dist: swarph-shared>=0.4.0
+Requires-Dist: swarph-shared!=0.6.0,<0.7,>=0.4.0
 Requires-Dist: PyYAML>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
@@ -108,10 +108,38 @@ swarph board cards add --project <id|slug> --title "…" [--body "…"] [--ai2]
 swarph board cards move <id> <stage>          # advance the card (proposed→idea→spec→plan→build→test→done)
 swarph board cards link <id> <key> <value>    # add/update a link (merges — never clobbers existing links)
 swarph board cards assign <id> <who>
+swarph board cards thread <id> [--limit N]     # the card's conversation (a card IS a thread)
+swarph board cards say <id> --content "…" [--to <peer>] [--kind fyi|question|answer|status|unblock]
 ```
 
 `--project` accepts a numeric id **or** a slug (resolved via `projects list`). Note: card creation always starts at `proposed` (the gateway has no stage-on-create) — use `cards move` to advance.
 
+**`thread` / `say` (v0.41.6)** — every card carries a bound conversation, so a
+finding, a verdict, or a hand-off lands **on the card** instead of in a DM only the
+sender and one recipient can read.
+
+`say` needs a recipient because a card post is still a DM on the wire: `--to` wins,
+otherwise the card's **assignee**. With neither, it **refuses** rather than
+substituting a placeholder — the gateway accepts an unregistered `to_node` with a
+`200`, so a placeholder would be indistinguishable from delivery while being
+addressed to nobody.
+
+Attaching requires an explicit `propose` grant on the project, not merely read
+access: a message on a card publishes to everyone who can read that card, now and
+in future.
+
+> **A card thread is a mesh-wide surface, not a two-party one.** 13 of 14 projects
+> carry `group:ALL`, so a card's conversation is readable by **every ratified peer**.
+> That is the design — a card's discussion belongs on the card regardless of who
+> sent it — and it is the same fact as the feature's selling point, stated from the
+> other side.
+>
+> **Put the verdict on the card. Not the credential.** Findings, decisions,
+> hand-offs and review outcomes belong there and are better there than in one
+> inbox. Tokens, keys and client-confidential material are a DM or nothing.
+> There is no retraction: the message is a row, and *now and in future* means a
+> peer ratified next month reads what you post today.
+
 ### `swarph bench` (v0.38.0)
 
 A **deterministic** LLM benchmark: run an N-way model *showdown* on a **pack** — a self-contained, subject-agnostic unit of `{system, tasks, expected}` — and report quality (ground-truth **distance**, not vibes) alongside tokens / cost / latency. You define the correct answer; the score is math; anyone re-runs = the same number.

{swarph_cli-0.41.3 → swarph_cli-0.41.7}/README.md

@@ -62,10 +62,38 @@ swarph board cards add --project <id|slug> --title "…" [--body "…"] [--ai2]
 swarph board cards move <id> <stage>          # advance the card (proposed→idea→spec→plan→build→test→done)
 swarph board cards link <id> <key> <value>    # add/update a link (merges — never clobbers existing links)
 swarph board cards assign <id> <who>
+swarph board cards thread <id> [--limit N]     # the card's conversation (a card IS a thread)
+swarph board cards say <id> --content "…" [--to <peer>] [--kind fyi|question|answer|status|unblock]
 ```
 
 `--project` accepts a numeric id **or** a slug (resolved via `projects list`). Note: card creation always starts at `proposed` (the gateway has no stage-on-create) — use `cards move` to advance.
 
+**`thread` / `say` (v0.41.6)** — every card carries a bound conversation, so a
+finding, a verdict, or a hand-off lands **on the card** instead of in a DM only the
+sender and one recipient can read.
+
+`say` needs a recipient because a card post is still a DM on the wire: `--to` wins,
+otherwise the card's **assignee**. With neither, it **refuses** rather than
+substituting a placeholder — the gateway accepts an unregistered `to_node` with a
+`200`, so a placeholder would be indistinguishable from delivery while being
+addressed to nobody.
+
+Attaching requires an explicit `propose` grant on the project, not merely read
+access: a message on a card publishes to everyone who can read that card, now and
+in future.
+
+> **A card thread is a mesh-wide surface, not a two-party one.** 13 of 14 projects
+> carry `group:ALL`, so a card's conversation is readable by **every ratified peer**.
+> That is the design — a card's discussion belongs on the card regardless of who
+> sent it — and it is the same fact as the feature's selling point, stated from the
+> other side.
+>
+> **Put the verdict on the card. Not the credential.** Findings, decisions,
+> hand-offs and review outcomes belong there and are better there than in one
+> inbox. Tokens, keys and client-confidential material are a DM or nothing.
+> There is no retraction: the message is a row, and *now and in future* means a
+> peer ratified next month reads what you post today.
+
 ### `swarph bench` (v0.38.0)
 
 A **deterministic** LLM benchmark: run an N-way model *showdown* on a **pack** — a self-contained, subject-agnostic unit of `{system, tasks, expected}` — and report quality (ground-truth **distance**, not vibes) alongside tokens / cost / latency. You define the correct answer; the score is math; anyone re-runs = the same number.

{swarph_cli-0.41.3 → swarph_cli-0.41.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.41.3"
+version = "0.41.7"
 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`, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }
@@ -40,7 +40,23 @@ dependencies = [
     # >=0.3.1 is load-bearing: 0.3.1 is the first release whose
     # scrub_env_for_subprocess closes the ANTHROPIC_AUTH_TOKEN/*_BASE_URL
     # billing-redirect class that the membrane env builders delegate to.
-    "swarph-shared>=0.4.0",
+    # >>> UPPER BOUND IS LOAD-BEARING, NOT TIDINESS. Without it ANY swarph-shared
+    # release can break ANY already-released swarph-cli on FRESH installs, with no
+    # action by the user and no signal to either package — measured 2026-08-05:
+    # shared 0.6.0 added a provider with no membrane here, spawn.py's
+    # `VALID_PROVIDERS ⊆ MEMBRANES` guard raised AT IMPORT, and every fresh
+    # `pip install swarph-cli` got a dead `swarph spawn` for ~5h.
+    # >>> AND THE HARDENED RITUAL MADE IT WORSE: `pipx install --force
+    # swarph-cli==X.Y.Z` RE-RESOLVES the transitive dep, so pinning exactly what
+    # we told cells to pin did NOT protect them. The most diligent cells were the
+    # most exposed. <<<
+    # A bound converts a silent runtime break into a RESOLVER CONFLICT AT INSTALL
+    # TIME: loud, local, and before anything is running. Raise it deliberately
+    # when a shared release is verified against this package. Board #308.
+    # `!=0.6.0` is not belt-and-braces: 0.6.0 is KNOWN-BROKEN with this package
+    # (it whitelists `vibe`, which has no membrane here, and spawn.py raises at
+    # import). Without the exclusion a resolver may still legally select it.
+    "swarph-shared>=0.4.0,!=0.6.0,<0.7",
     # Phase 7 spawn — cell.yaml parser. PyYAML 6.x is the standard.
     # Stays a swarph-cli dep since file I/O is operator-tooling-layer
     # concern; swarph-shared cell module is pure-stdlib.

{swarph_cli-0.41.3 → swarph_cli-0.41.7}/src/swarph_cli/__init__.py

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

{swarph_cli-0.41.3 → swarph_cli-0.41.7}/src/swarph_cli/commands/board.py

@@ -50,20 +50,43 @@ def _patch_json(url: str, body: dict, token: str, *, timeout: float = 10.0) -> t
 
 # ── pure builders (unit-tested) ───────────────────────────────────────────────
 
-def _cards_list_url(gateway: str, *, project=None, stage=None, assignee=None) -> str:
-    q = {k: v for k, v in (("project", project), ("stage", stage), ("assignee", assignee)) if v}
+def _cards_list_url(gateway: str, *, project=None, stage=None, assignee=None,
+                    label=None) -> str:
+    q = {k: v for k, v in (("project", project), ("stage", stage),
+                           ("assignee", assignee), ("label", label)) if v}
     base = f"{gateway.rstrip('/')}/board/cards"
     return f"{base}?{urllib.parse.urlencode(q)}" if q else base
 
 
-def _card_add_payload(actor, project_id, title, *, body=None, ai2=False, priority=0) -> dict:
+def _card_add_payload(actor, project_id, title, *, body=None, ai2=False, priority=0,
+                      labels=None) -> dict:
     p = {"actor": actor, "project_id": int(project_id), "title": title,
          "ai2": bool(ai2), "priority": int(priority)}
     if body:
         p["body"] = body
+    if labels:
+        p["labels"] = list(labels)
     return p
 
 
+def _apply_label(current: list, action: str, label: str) -> list:
+    """Compute the NEW label set. Pure, so the read-modify-write is testable
+    without a gateway.
+
+    The server takes a FULL REPLACEMENT (labels are a set — a merge-only field
+    could never REMOVE one), so `label rm` is unavoidably read-modify-write. That
+    is last-writer-wins between two simultaneous editors of the SAME card, which
+    the board already has for `stage` and `assignee` — stated rather than hidden,
+    because the alternative (server-side add/rm ops) is a bigger surface than
+    this card justifies.
+    """
+    cur = [str(x).strip().lower() for x in (current or [])]
+    lab = label.strip().lower()
+    if action == "add":
+        return cur if lab in cur else cur + [lab]
+    return [x for x in cur if x != lab]
+
+
 def _project_add_payload(actor, slug, title, *, goal=None) -> dict:
     p = {"actor": actor, "slug": slug, "title": title}
     if goal:
@@ -138,6 +161,71 @@ def _format_projects(data) -> str:
     return "\n".join(lines)
 
 
+# ── #181: the card IS a thread ────────────────────────────────────────────────
+# The gateway has carried `GET /board/cards/{id}/thread` and the card-gated attach
+# path since 2026-08-05, and NOTHING COULD REACH THEM. No CLI verb existed, so the
+# card↔DM fusion lived entirely in the database and the OpenAPI schema: shipped,
+# deployed, and invisible to every human and cell. Found the way these are always
+# found — I tried to write a finding onto a card and had to send a DM instead.
+
+def _thread_url(gateway: str, card_id: int, *, limit: Optional[int] = None) -> str:
+    base = f"{gateway.rstrip('/')}/board/cards/{card_id}/thread"
+    return f"{base}?limit={limit}" if limit else base
+
+
+def _thread_recipient(card: dict, explicit_to: Optional[str]) -> str:
+    """Who a card-thread post is addressed to. `--to` wins, else the assignee.
+
+    >>> RAISES RATHER THAN INVENTING A SENTINEL. <<< POST /messages requires
+    exactly one of {to_node, channel}, so a card post needs a real recipient. The
+    tempting move is a placeholder like "board" or "__card__" — but board card
+    #259 measured what the gateway does with an unregistered to_node: it returns
+    200 and the message is addressed to nobody, indistinguishable from delivery.
+    A placeholder here would manufacture that defect once per card post.
+    """
+    if explicit_to:
+        return explicit_to
+    assignee = card.get("assignee")
+    if assignee:
+        return assignee
+    raise RuntimeError(
+        f"card #{card.get('id')} has no assignee, so there is no default recipient "
+        f"for a thread post — pass --to <peer>. (A card post is still a DM on the "
+        f"wire; it needs someone to be addressed to.)"
+    )
+
+
+def _card_say_payload(from_node: str, to_node: str, kind: str, content: str,
+                      thread_uuid: str) -> dict:
+    return {
+        "from_node": from_node,
+        "to_node": to_node,
+        "kind": kind,
+        "content": content,
+        "thread_id": thread_uuid,
+    }
+
+
+def _format_thread(data) -> str:
+    msgs = data.get("messages", []) if isinstance(data, dict) else (data or [])
+    card_id = data.get("card_id") if isinstance(data, dict) else None
+    if not msgs:
+        # NOT "(no messages)" alone — an empty thread and an unreadable one must not
+        # render the same. The gateway 403s an unreadable card and 409s an unmigrated
+        # one, so reaching here with [] genuinely means nobody has posted yet.
+        return f"card #{card_id}: thread is empty — no messages posted yet"
+    lines = [f"card #{card_id} — {len(msgs)} message(s)"]
+    for m in msgs:
+        ts = (m.get("created_at") or "")[:16].replace("T", " ")
+        lines.append(
+            f"\n  [{m.get('id')}] {ts}  {_s(m.get('from_node'))} -> "
+            f"{_s(m.get('to_node'))}  ({_s(m.get('kind'))})"
+        )
+        for ln in (_s(m.get("content")) or "").splitlines():
+            lines.append(f"      {ln}")
+    return "\n".join(lines)
+
+
 # ── parser + dispatch ─────────────────────────────────────────────────────────
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -153,13 +241,17 @@ def _build_parser() -> argparse.ArgumentParser:
     cards = top.add_parser("cards", help="board cards").add_subparsers(dest="command", required=True)
     cl = cards.add_parser("list", help="list cards")
     cl.add_argument("--project"); cl.add_argument("--stage"); cl.add_argument("--assignee")
+    cl.add_argument("--label", help="only cards carrying this label (exact match)")
     cl.add_argument("--json", action="store_true"); _add_common(cl)
     cs = cards.add_parser("show", help="show one card"); cs.add_argument("id", type=int)
     cs.add_argument("--json", action="store_true"); _add_common(cs)
     ca = cards.add_parser("add", help="create a card")
     ca.add_argument("--project", required=True, help="project id or slug"); ca.add_argument("--title", required=True)
     ca.add_argument("--body"); ca.add_argument("--ai2", action="store_true")
-    ca.add_argument("--priority", type=int, default=0); ca.add_argument("--json", action="store_true"); _add_common(ca)
+    ca.add_argument("--priority", type=int, default=0)
+    ca.add_argument("--label", action="append", dest="labels", metavar="LABEL",
+                    help="attach a label (repeatable)")
+    ca.add_argument("--json", action="store_true"); _add_common(ca)
     cm = cards.add_parser("move", help="move a card to a stage")
     cm.add_argument("id", type=int); cm.add_argument("stage"); cm.add_argument("--json", action="store_true"); _add_common(cm)
     ck = cards.add_parser("link", help="add/update a link on a card (merges)")
@@ -167,6 +259,22 @@ def _build_parser() -> argparse.ArgumentParser:
     ck.add_argument("--json", action="store_true"); _add_common(ck)
     cn = cards.add_parser("assign", help="set a card's assignee")
     cn.add_argument("id", type=int); cn.add_argument("assignee"); cn.add_argument("--json", action="store_true"); _add_common(cn)
+    cb = cards.add_parser("label", help="add/remove a label on a card")
+    cb.add_argument("action", choices=["add", "rm"])
+    cb.add_argument("id", type=int); cb.add_argument("label")
+    cb.add_argument("--json", action="store_true"); _add_common(cb)
+    ct = cards.add_parser("thread", help="show the card's conversation (#181: a card IS a thread)")
+    ct.add_argument("id", type=int)
+    ct.add_argument("--limit", type=int, default=None, help="max messages (gateway caps at 1000)")
+    _add_common(ct)
+    cy = cards.add_parser("say", help="post a message onto the card's thread")
+    cy.add_argument("id", type=int)
+    cy.add_argument("--content", required=True)
+    cy.add_argument("--kind", default="fyi", help="status|question|answer|unblock|fyi")
+    cy.add_argument("--to", dest="to_node", default=None,
+                    help="recipient peer (default: the card's assignee)")
+    _add_common(cy)
+
     cr = cards.add_parser("ready", help="flag a card ready-to-advance (move_ready) for the orchestrator")
     cr.add_argument("id", type=int); cr.add_argument("--clear", action="store_true", help="unset move_ready")
     cr.add_argument("--json", action="store_true"); _add_common(cr)
@@ -224,7 +332,9 @@ def run_board(argv: list[str]) -> int:
             if err:
                 print(f"swarph board: {err}", file=sys.stderr)
                 return 1
-            st, d = _http_get_json(_cards_list_url(gw, project=pid, stage=args.stage, assignee=args.assignee), token)
+            st, d = _http_get_json(_cards_list_url(gw, project=pid, stage=args.stage,
+                                                   assignee=args.assignee,
+                                                   label=getattr(args, "label", None)), token)
             return _out(st, d, _format_cards, aj)
         if args.command == "show":
             st, d = _http_get_json(f"{gw}/board/cards/{args.id}", token)
@@ -234,14 +344,74 @@ def run_board(argv: list[str]) -> int:
             if err or pid is None:
                 print(f"swarph board: {err or 'project required'}", file=sys.stderr)
                 return 1
-            st, d = _post_json(f"{gw}/board/cards", _card_add_payload(self_name, pid, args.title, body=args.body, ai2=args.ai2, priority=args.priority), token)
+            st, d = _post_json(f"{gw}/board/cards", _card_add_payload(
+                self_name, pid, args.title, body=args.body, ai2=args.ai2,
+                priority=args.priority, labels=getattr(args, "labels", None)), token)
             return _out(st, d, lambda x: f"created card #{x.get('id')} [{x.get('stage')}] (stage defaults to proposed — use `cards move` to advance)", aj)
+        if args.command == "label":
+            # READ the current set before replacing it. If the GET fails we must
+            # NOT write — a PATCH built on a failed read would silently CLOBBER
+            # every other label on the card. Refuse loudly instead.
+            st, cur = _http_get_json(f"{gw}/board/cards/{args.id}", token)
+            if st != 200 or not isinstance(cur, dict):
+                print(f"swarph board: cannot read card #{args.id} to modify its "
+                      f"labels (HTTP {st}) — refusing to write, a replacement built "
+                      f"on a failed read would drop the card's other labels",
+                      file=sys.stderr)
+                return 1
+            new = _apply_label(cur.get("labels") or [], args.action, args.label)
+            st, d = _patch_json(f"{gw}/board/cards/{args.id}",
+                                {"actor": self_name, "labels": new}, token)
+            return _out(st, d, lambda x: f"card #{x.get('id')} labels -> "
+                                         f"{', '.join(x.get('labels') or []) or '(none)'}", aj)
         if args.command == "move":
             st, d = _patch_json(f"{gw}/board/cards/{args.id}", {"actor": self_name, "stage": args.stage}, token)
             return _out(st, d, lambda x: f"card #{x.get('id')} -> {x.get('stage')}", aj)
         if args.command == "assign":
             st, d = _patch_json(f"{gw}/board/cards/{args.id}", {"actor": self_name, "assignee": args.assignee}, token)
             return _out(st, d, lambda x: f"card #{x.get('id')} assignee -> {x.get('assignee')}", aj)
+        if args.command == "thread":
+            st, d = _http_get_json(_thread_url(gw, args.id, limit=args.limit), token)
+            # NO special-casing of 403/409. `_out` already returns 1 and prints the
+            # gateway's `detail` verbatim for every non-2xx, so the refusal reaches
+            # the operator intact — a 409 ("predates #181a") and a 403 ("not
+            # readable") are never rendered as an empty thread.
+            # >>> A HAND-WRITTEN BRANCH HERE WAS DELETED: it re-printed the same
+            # detail under a different prefix, carried a comment asserting it
+            # prevented a flattening `_out` never did, and a mutation that removed
+            # it PASSED ALL 15 TESTS — the definition of a code path doing nothing.
+            # Reading it would not have found that; mutating it did. <<<
+            return _out(st, d, _format_thread, aj)
+        if args.command == "say":
+            st, card = _http_get_json(f"{gw}/board/cards/{args.id}", token)
+            if st != 200:
+                print(f"swarph board cards say: cannot read card #{args.id}: "
+                      f"{card.get('detail', card)}", file=sys.stderr)
+                return 1
+            thread_uuid = card.get("thread_uuid")
+            if not thread_uuid:
+                # Named refusal, not a silent no-op. Same reason the gateway 409s.
+                print(f"swarph board cards say: card #{args.id} has no bound thread "
+                      f"(it predates #181a). Run scripts/migrate_card_threads.py on "
+                      f"the gateway host.", file=sys.stderr)
+                return 1
+            try:
+                to_node = _thread_recipient(card, args.to_node)
+            except RuntimeError as exc:
+                print(f"swarph board cards say: {exc}", file=sys.stderr)
+                return 1
+            st, d = _post_json(
+                f"{gw}/messages",
+                _card_say_payload(self_name, to_node, args.kind, args.content, thread_uuid),
+                token,
+            )
+            # A 403 here carries the gateway's explanation that attaching PUBLISHES
+            # to everyone who can read the card, now and in future, so it needs an
+            # explicit `propose` grant. `_out` passes `detail` through whole; it does
+            # not need help, and a second copy of that logic is a second thing to
+            # keep in sync.
+            return _out(st, d, lambda x: f"posted id={x.get('id')} onto card "
+                                         f"#{args.id} (to {to_node})", aj)
         if args.command == "ready":
             st, d = _patch_json(f"{gw}/board/cards/{args.id}", {"actor": self_name, "move_ready": not args.clear}, token)
             return _out(st, d, lambda x: f"card #{x.get('id')} move_ready -> {x.get('move_ready')}", aj)

{swarph_cli-0.41.3 → swarph_cli-0.41.7}/src/swarph_cli/commands/daemon.py

@@ -138,7 +138,21 @@ def _resolve_state_dir(arg: Optional[str], self_name_arg: Optional[str]) -> Path
 
 
 def _resolve_token(token_file_arg: Optional[str]) -> str:
-    """Mirror onboard's resolution. env → secrets.toml mode 0600 → prompt."""
+    """DELEGATES to onboard's resolver (#243) — and this docstring used to lie.
+
+    It read "Mirror onboard's resolution. env -> secrets.toml mode 0600 ->
+    prompt", which describes a COPY. The body has always been a delegation, so
+    the fix for #243 reached this verb for free — but a reader auditing which
+    verbs inherited the retired-credential bug would have read this line and
+    concluded daemon had its own broken copy. I did exactly that, and carded it.
+
+    >>> A DOCSTRING THAT DESCRIBES A COPY OVER A BODY THAT DELEGATES IS A STALE
+    RECORD, AND IT COSTS THE NEXT READER THE SAME WRONG CONCLUSION. <<< The
+    resolution order it names is also now wrong: onboard gained
+    ~/.config/swarph/<SWARPH_SELF>.peer_token and REFUSES rather than prompting.
+    Naming the delegation instead of restating the order means this cannot go
+    stale again.
+    """
     from swarph_cli.commands.onboard import _resolve_token as _onboard_resolve
 
     return _onboard_resolve(token_file_arg)

{swarph_cli-0.41.3 → swarph_cli-0.41.7}/src/swarph_cli/commands/mesh.py

@@ -128,77 +128,28 @@ def _peer_token_path(self_name: str) -> Path:
     return Path.home() / ".config" / "swarph" / f"{self_name}.peer_token"
 
 
-_TOKEN_KEYS = ("MESH_GATEWAY_TOKEN", "SWARPH_TOKEN", "TOKEN")
+# _TOKEN_KEYS moved to swarph_cli.tokens.TOKEN_KEYS (#332). Not re-exported:
+# a second copy of a constant in a second module is precisely how the two token
+# PARSERS diverged in the first place. One definition, one address.
 
 
 def _read_token_file(path: Path) -> str:
     """Read a bearer token from a token file OR an env-style file.
 
-    ONE PARSER BEHIND ONE FLAG (droplet, 2026-07-26). This previously did
-    `read_text().strip()` and returned the ENTIRE FILE, so `--token-file
-    /root/.mesh.env` -- the shape the systemd unit itself documents -- put
-    comments and other variables into the Authorization header. droplet's
-    monitor died with
+    THE IMPLEMENTATION MOVED to `swarph_cli.tokens.read_token_file` (#332).
+    droplet's "one parser behind one flag" work (2026-07-26) lived here, in a
+    COMMAND module \u2014 so every other verb either reimplemented it or reached
+    into a sibling command's private helper. gpt-ops flagged that during the
+    #332 review: `onboard` must not depend on `mesh`'s internals. The parser is
+    byte-for-byte unchanged; only its address is.
 
-        UnicodeEncodeError: 'latin-1' codec can't encode character '\u2014'
-
-    from an em-dash in a COMMENT on line 5. Meanwhile `swarph daemon` read the
-    same flag through onboard._resolve_token, which has always skipped comments
-    and parsed KEY=VALUE. Two parsers, one flag -- the same one-thing-two-meanings
-    shape as the cursor that meant both observed and woken.
-
-    Accepts, in order:
-      1. an env-style line `MESH_GATEWAY_TOKEN=...` (quotes stripped), or
-      2. the first non-comment, non-blank, non-KEY=VALUE line as a bare token.
+    This wrapper stays because it is a PATCH POINT: existing suites monkeypatch
+    `mesh._read_token_file`, and deleting the name would make those patches
+    silently miss (the same trap documented on `_tmux_wake` above).
     """
-    try:
-        raw = path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise RuntimeError(f"cannot read token file {path}: {exc}") from exc
-
-    bare: Optional[str] = None
-    for lineno, line in enumerate(raw.splitlines(), start=1):
-        line = line.strip()
-        if not line or line.startswith("#"):
-            continue
-        if "=" in line:
-            key, value = line.split("=", 1)
-            if key.strip().upper() in _TOKEN_KEYS:
-                return _validated_token(value.strip().strip('"').strip("'"),
-                                        path, lineno)
-            continue
-        if bare is None:
-            bare = line
-            bare_lineno = lineno
-    if bare is not None:
-        return _validated_token(bare, path, bare_lineno)
-    raise RuntimeError(
-        f"token file {path} contains no token: expected a bare token line or "
-        f"one of {', '.join(_TOKEN_KEYS)}=<token>"
-    )
-
+    from swarph_cli.tokens import read_token_file
 
-def _validated_token(token: str, path: Path, lineno: int) -> str:
-    """Reject a token that cannot go in an HTTP header, NAMING THE SOURCE.
-
-    droplet's hardening, and it is worth more than the parse fix: a non-ASCII
-    byte in an outbound header surfaced as a latin-1 codec traceback twelve
-    frames deep in http/client.py, which points every reader at the HTTP layer
-    for what is a malformed config FILE. Fail at the boundary where the operator
-    can act, naming the file and the line.
-    """
-    try:
-        token.encode("latin-1")
-    except UnicodeEncodeError as exc:
-        bad = token[exc.start:exc.start + 1]
-        raise RuntimeError(
-            f"token file {path} line {lineno}: token contains a non-ASCII "
-            f"character {bad!r} (U+{ord(bad):04X}) at position {exc.start}, "
-            f"which cannot be sent in an HTTP Authorization header. "
-            f"If this line is a comment, prefix it with '#'; if the file is "
-            f"env-style, use MESH_GATEWAY_TOKEN=<token>."
-        ) from None
-    return token
+    return read_token_file(path)
 
 
 def _read_secrets_token(path: Path) -> str:
@@ -638,6 +589,25 @@ class TmuxSink(Sink):
         return f"{count} DM{plural} not yet delivered to {self.name}"
 
 
+class TmuxNotifySink(Sink):
+    """Show a tmux status-line notice without modifying the pane input buffer."""
+
+    is_push = True
+
+    def __init__(self, target: str):
+        super().__init__(f"tmux-notify:{target}")
+        self.target = target
+
+    def deliver(self, state: "MonitorState", dms: list, up_to_id: int) -> bool:
+        # A notification is deliberately content-free: it must not leak DM text
+        # into a shared status line, and unlike TmuxSink it never submits input.
+        return _tmux_notify(self.target, max(1, len(dms)))
+
+    def pending_label(self, count: int) -> str:
+        plural = "s" if count != 1 else ""
+        return f"{count} DM{plural} not yet notified to {self.name}"
+
+
 class StdoutSink(Sink):
     """Write the DM to stdout. Delivery always succeeds."""
 
@@ -672,6 +642,13 @@ def parse_sink(spec: str) -> Sink:
         return NoneSink()
     if spec == "stdout":
         return StdoutSink()
+    if spec.startswith("tmux-notify:"):
+        target = spec[len("tmux-notify:"):]
+        if not target:
+            raise MonitorSinkError(
+                "sink 'tmux-notify:' needs a target, e.g. tmux-notify:lab:0.0"
+            )
+        return TmuxNotifySink(target)
     if spec.startswith("tmux:"):
         target = spec[len("tmux:"):]
         if not target:
@@ -688,7 +665,8 @@ def parse_sink(spec: str) -> Sink:
             "ignored. Use --deliver pull / tmux:<target> / stdout / none."
         )
     raise MonitorSinkError(
-        f"unknown sink {spec!r}; expected pull, none, stdout, or tmux:<target>"
+        f"unknown sink {spec!r}; expected pull, none, stdout, tmux:<target>, "
+        "or tmux-notify:<target>"
     )
 
 
@@ -873,6 +851,24 @@ def _tmux_wake(target: str) -> bool:
         return False
 
 
+def _tmux_notify(target: str, dm_count: int) -> bool:
+    """Show a transient tmux notice without sending any pane keystrokes."""
+    plural = "s" if dm_count != 1 else ""
+    try:
+        subprocess.run(
+            ["tmux", "display-message", "-t", target,
+             f"mesh: {dm_count} new DM{plural}; inbox pending"],
+            check=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+        return True
+    except (OSError, subprocess.CalledProcessError) as exc:
+        print(f"[monitor] tmux notification failed: {exc}", file=sys.stderr, flush=True)
+        return False
+
+
 def _select_next_poll_seconds(state: MonitorState) -> int:
     if state.disconnect_since is not None:
         if time.time() - state.disconnect_since > _BACKOFF_5XX_THRESHOLD_SECONDS:

{swarph_cli-0.41.3 → swarph_cli-0.41.7}/src/swarph_cli/commands/monitor.py

@@ -56,7 +56,8 @@ def _build_parser() -> argparse.ArgumentParser:
         action="append",
         default=[],
         metavar="SINK",
-        help="repeatable; pull (default) | tmux:<target> | stdout | none. "
+        help="repeatable; pull (default) | tmux:<target> | tmux-notify:<target> "
+        "| stdout | none. "
         "Each sink gets its OWN delivery ledger.",
     )
     start.add_argument("--poll-s", type=int, default=mesh._DEFAULT_POLL_S)