swarph-cli 0.72.35__tar.gz → 0.72.37__tar.gz

{swarph_cli-0.72.35/src/swarph_cli.egg-info → swarph_cli-0.72.37}/PKG-INFO

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

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

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

{swarph_cli-0.72.35 → swarph_cli-0.72.37}/src/swarph_cli/bench/backends.py

@@ -38,6 +38,8 @@ import urllib.request
 from dataclasses import dataclass
 from typing import Any, Callable, Optional, Protocol
 
+from swarph_cli.redact import encode_outbound_json
+
 
 @dataclass
 class BackendResult:
@@ -510,7 +512,7 @@ class TypedHttpBackend:
             body = _request_body(prompt, system)
             req = urllib.request.Request(
                 endpoint,
-                data=json.dumps(body).encode(),
+                data=encode_outbound_json(body, caller="bench.SystemOneBackend.generate"),
                 headers={"Content-Type": "application/json"},
                 method="POST",
             )
@@ -626,7 +628,7 @@ class HttpBackend:
                 scheme = self.auth.get("scheme") or ""
                 token = f"{scheme} {value}".strip() if scheme else value
                 headers[self.auth["header"]] = token
-            raw_body = json.dumps(body).encode()
+            raw_body = encode_outbound_json(body, caller="bench.HttpBackend.generate")
             self.calls += 1
             if self.transport is not None:
                 status, reason, raw = self.transport(endpoint, headers, raw_body)
@@ -919,7 +921,7 @@ class DecisionsBackend:
                 scheme = self.auth.get("scheme") or ""
                 token = f"{scheme} {value}".strip() if scheme else value
                 headers[self.auth["header"]] = token
-            raw_body = json.dumps(body).encode()
+            raw_body = encode_outbound_json(body, caller="bench.DecisionsBackend.generate")
             self.calls += 1
             if self.transport is not None:
                 status, reason, raw = self.transport(endpoint, headers, raw_body)

{swarph_cli-0.72.35 → swarph_cli-0.72.37}/src/swarph_cli/commands/board.py

@@ -43,6 +43,7 @@ from swarph_cli.commands.mesh import (
     _resolve_self_name,
     _resolve_token,
 )
+from swarph_cli.redact import redact_text, redact_value, encode_outbound_json
 
 
 _SENTINEL = object()
@@ -51,7 +52,7 @@ _SENTINEL = object()
 # ── HTTP: PATCH (mesh.py has GET + POST; the board needs PATCH for move/link) ──
 
 def _patch_json(url: str, body: dict, token: str, *, timeout: float = 10.0) -> tuple[int, dict]:
-    data = json.dumps(body).encode("utf-8")
+    data = encode_outbound_json(body, caller="board._patch_json")
     req = urllib.request.Request(
         url, data=data, method="PATCH",
         headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
@@ -89,11 +90,12 @@ def _normalize_due_at(value: str) -> str:
 
 
 def _card_add_payload(actor, project_id, title, *, body=None, ai2=False, priority=0,
-                      labels=None, due_at=None) -> dict:
+                      labels=None, due_at=None, opt_out=False) -> dict:
+    title = redact_text(title, opt_out=opt_out, caller="board.cards.add")
     p = {"actor": actor, "project_id": int(project_id), "title": title,
          "ai2": bool(ai2), "priority": int(priority)}
     if body:
-        p["body"] = body
+        p["body"] = redact_text(body, opt_out=opt_out, caller="board.cards.add")
     if labels:
         p["labels"] = list(labels)
     if due_at is not None:
@@ -151,7 +153,7 @@ def _format_obligations(data: dict) -> str:
 
 
 def _card_edit_payload(actor, title, body, *, due_at=_SENTINEL, project_id=None,
-                       priority=None) -> dict:
+                       priority=None, opt_out=False) -> dict:
     """#191: the edit patch — title and/or body, the two fields that made a
     card's text write-once until the gateway grew them (BoardCardPatch).
 
@@ -173,9 +175,9 @@ def _card_edit_payload(actor, title, body, *, due_at=_SENTINEL, project_id=None,
     """
     patch = {"actor": actor}
     if title is not None:
-        patch["title"] = title
+        patch["title"] = redact_text(title, opt_out=opt_out, caller="board.cards.edit")
     if body is not None:
-        patch["body"] = body
+        patch["body"] = redact_text(body, opt_out=opt_out, caller="board.cards.edit")
     if due_at is not _SENTINEL:
         # "" is the gateway's CLEAR sentinel; None means "not mentioned" and the
         # write is skipped while the old date is echoed back (#901).
@@ -190,7 +192,7 @@ def _card_edit_payload(actor, title, body, *, due_at=_SENTINEL, project_id=None,
     return patch
 
 
-def _write_card_preimage(actor, gateway, card_id, card, patch) -> Path:
+def _write_card_preimage(actor, gateway, card_id, card, patch, *, opt_out=False) -> Path:
     """Append the card's CURRENT title and body to a local log BEFORE an edit
     replaces them. Returns the path written.
 
@@ -213,10 +215,10 @@ def _write_card_preimage(actor, gateway, card_id, card, patch) -> Path:
         "gateway": gateway,
         "card": card_id,
         "body_version": card.get("body_version"),
-        "prev_title": card.get("title"),
-        "prev_body": card.get("body"),
-        "new_title": patch.get("title"),
-        "new_body": patch.get("body"),
+        "prev_title": redact_text(card.get("title"), opt_out=opt_out, caller="board.cards.edit"),
+        "prev_body": redact_text(card.get("body"), opt_out=opt_out, caller="board.cards.edit"),
+        "new_title": redact_text(patch.get("title"), opt_out=opt_out, caller="board.cards.edit"),
+        "new_body": redact_text(patch.get("body"), opt_out=opt_out, caller="board.cards.edit"),
     }
     path = card_preimage_path()
     path.parent.mkdir(parents=True, exist_ok=True)
@@ -251,10 +253,11 @@ def _apply_label(current: list, action: str, label: str) -> list:
     return [x for x in cur if x != lab]
 
 
-def _project_add_payload(actor, slug, title, *, goal=None) -> dict:
+def _project_add_payload(actor, slug, title, *, goal=None, opt_out: bool = False) -> dict:
+    title = redact_text(title, opt_out=opt_out, caller="board.projects")
     p = {"actor": actor, "slug": slug, "title": title}
     if goal:
-        p["goal"] = goal
+        p["goal"] = redact_text(goal, opt_out=opt_out, caller="board.projects")
     return p
 
 
@@ -546,7 +549,8 @@ def _say_line(resp: dict, card_id, to_node: str, *, reason: Optional[str] = None
 
 
 def _card_say_payload(from_node: str, to_node: str, kind: str, content: str,
-                      thread_uuid: str) -> dict:
+                      thread_uuid: str, *, opt_out=False) -> dict:
+    content = redact_text(content, opt_out=opt_out, caller="board.cards.say")
     return {
         "from_node": from_node,
         "to_node": to_node,
@@ -726,7 +730,7 @@ def _json_flag(flag: str, value: str):
 
 def _ask_payload(self_name, what, *, holder=None, step=None, needs=None, hours=None,
                  done=None, accept=None, accept_json=None, kind="action",
-                 timeout_hours=None, task=None, task_needs=None) -> dict:
+                 timeout_hours=None, task=None, task_needs=None, opt_out=False) -> 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
@@ -736,6 +740,7 @@ def _ask_payload(self_name, what, *, holder=None, step=None, needs=None, hours=N
     if accept is not None and accept_json is not None:
         raise ValueError("pass --accept or --accept-json, not both — "
                          "one check per row")
+    what = redact_text(what, opt_out=opt_out, caller="board.cards.ask")
     p = {"what": what, "created_by": self_name, "kind": kind}
     if holder is not None:
         p["holder"] = self_name if holder == "me" else holder
@@ -746,11 +751,11 @@ def _ask_payload(self_name, what, *, holder=None, step=None, needs=None, hours=N
     if hours is not None:
         p["hours"] = hours
     if done is not None:
-        p["done"] = done
+        p["done"] = redact_text(done, opt_out=opt_out, caller="board.cards.ask")
     if accept is not None:
-        p["accept"] = accept
+        p["accept"] = redact_text(accept, opt_out=opt_out, caller="board.cards.ask")
     if accept_json is not None:
-        p["accept_json"] = accept_json
+        p["accept_json"] = redact_value(accept_json, opt_out=opt_out, caller="board.cards.ask")
     if timeout_hours is not None:
         p["timeout_hours"] = timeout_hours
     if task is not None:
@@ -830,7 +835,7 @@ def _ask_line(d) -> str:
     return line
 
 
-def _confirm_flow_payload(actor: str, holders, what=None) -> dict:
+def _confirm_flow_payload(actor: str, holders, what=None, *, opt_out=False) -> dict:
     """#801: {actor, holders: {step: peer}, what}. `--holder STEP=PEER` is parsed here so a
     malformed override is refused before the request, naming the form."""
     body = {"actor": actor}
@@ -844,7 +849,7 @@ def _confirm_flow_payload(actor: str, holders, what=None) -> dict:
             out[step] = peer
         body["holders"] = out
     if what:
-        body["what"] = what
+        body["what"] = redact_text(what, opt_out=opt_out, caller="board.cards.confirm-flow")
     return body
 
 
@@ -924,25 +929,47 @@ def _move_line(x) -> str:
     return line
 
 
-def _close_payload(outcome, evidence=None, evidence_json=None) -> dict:
+def _close_payload(outcome, evidence=None, evidence_json=None, *, opt_out=False,
+                   usage=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."""
+    for a JSON pass, the string everywhere else.
+
+    Card #1277: usage is attached on every close. When the caller does not
+    pass it, it is read from this cell's transcript (or left unknown)."""
     if evidence is None and evidence_json is None:
         raise ValueError("nothing observed — pass --evidence and/or "
                          "--evidence-json")
-    p = {"outcome": outcome}
+    if usage is None:
+        from swarph_cli.commands.board_usage import read_close_usage
+        usage = read_close_usage()
+    p = {"outcome": outcome, "usage": usage}
     if evidence is not None:
-        p["evidence"] = evidence
+        p["evidence"] = redact_text(evidence, opt_out=opt_out, caller="board.obligations.close")
     if evidence_json is not None:
-        p["evidence_json"] = evidence_json
+        p["evidence_json"] = redact_value(evidence_json, opt_out=opt_out, caller="board.obligations.close")
     return p
 
 
+def _obligation_taken_at(gw: str, token: str, obligation_id: int):
+    """The row's taken_at, or None when the list does not show it.
+
+    The transcript sum is bounded by this instant. Without it the close
+    sends unknown rather than summing some other window."""
+    status, body = _http_get_json(
+        f"{gw}/board/obligations?obligation_id={obligation_id}", token)
+    if not (status and 200 <= status < 300) or not isinstance(body, dict):
+        return None
+    for item in body.get("obligations") or []:
+        if isinstance(item, dict) and item.get("id") == obligation_id:
+            return item.get("taken_at")
+    return None
+
+
 def _amend_payload(step=None, holder=None, accept=None, hours=None,
                    needs_add=None, needs_remove=None, needs=None,
-                   accept_json=None) -> dict:
+                   accept_json=None, *, opt_out=False) -> 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
@@ -953,6 +980,10 @@ def _amend_payload(step=None, holder=None, accept=None, hours=None,
     if accept is not None and accept_json is not None:
         raise ValueError("pass --accept or --accept-json, not both — "
                          "one check per row")
+    if accept is not None:
+        accept = redact_text(accept, opt_out=opt_out, caller="board.obligations")
+    if accept_json is not None:
+        accept_json = redact_value(accept_json, opt_out=opt_out, caller="board.obligations")
     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("-")]
@@ -1268,6 +1299,13 @@ def _build_parser() -> argparse.ArgumentParser:
     ow.add_argument("--reason", required=True,
                     help="why the row is withdrawn; whitespace is refused")
     ow.add_argument("--json", action="store_true"); _add_common(ow)
+    cost = top.add_parser(
+        "cost",
+        help="tokens by job, the perfect-run rate, and cost per accepted outcome")
+    cost.add_argument("--card", type=int, default=None)
+    cost.add_argument("--since", default=None, metavar="DATE")
+    cost.add_argument("--json", action="store_true")
+    _add_common(cost)
     return p
 
 
@@ -1313,9 +1351,27 @@ def run_board(argv: list[str]) -> int:
             st, d = _http_get_json(f"{gw}/board/projects", token)
             return _out(st, d, _format_projects, aj)
         if args.command == "add":
-            st, d = _post_json(f"{gw}/board/projects", _project_add_payload(self_name, args.slug, args.title, goal=args.goal), token)
+            st, d = _post_json(f"{gw}/board/projects", _project_add_payload(self_name, args.slug, args.title, goal=args.goal, opt_out=getattr(args, "no_redact", False)), token)
             return _out(st, d, lambda x: f"created project #{x.get('id')} ({x.get('slug')})", aj)
 
+    if args.group == "cost":
+        from swarph_cli.commands.board_cost import format_cost
+        query = []
+        if getattr(args, "card", None) is not None:
+            query.append(f"card={args.card}")
+        if getattr(args, "since", None):
+            query.append("since=" + args.since)
+        url = f"{gw}/board/cost" + (("?" + "&".join(query)) if query else "")
+        st, d = _http_get_json(url, token)
+        rates = None
+        if st and 200 <= st < 300:
+            try:
+                from swarph_shared.llm_cost import fetch_price_base
+                rates = fetch_price_base()
+            except Exception:
+                rates = None
+        return _out(st, d, lambda body: format_cost(body, rates), aj)
+
     if args.group == "obligations":
         if args.command == "close":
             # #562's CLI half: the explicit close act. The gateway guards the
@@ -1332,7 +1388,12 @@ def run_board(argv: list[str]) -> int:
             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)
+                taken_at = _obligation_taken_at(gw, token, args.id)
+                from swarph_cli.commands.board_usage import read_close_usage
+                usage = read_close_usage(agent=self_name, taken_at=taken_at)
+                payload = _close_payload(args.outcome, evidence, evidence_json,
+                                         opt_out=getattr(args, "no_redact", False),
+                                         usage=usage)
             except ValueError as exc:
                 print(f"swarph board obligations close: {exc}", file=sys.stderr)
                 return 2
@@ -1362,8 +1423,9 @@ def run_board(argv: list[str]) -> int:
             st, d = _post_json(f"{gw}/board/obligations/{args.id}/take", {}, token)
             return _out(st, d, _obligation_act_line, aj)
         if args.command == "decline":
+            why = redact_text(args.why, opt_out=getattr(args, "no_redact", False), caller="board.obligations")
             st, d = _post_json(f"{gw}/board/obligations/{args.id}/decline",
-                               {"why": args.why}, token)
+                               {"why": why}, token)
             return _out(st, d, _obligation_act_line, aj)
         if args.command == "amend":
             try:
@@ -1373,7 +1435,8 @@ def run_board(argv: list[str]) -> int:
                                        accept=args.accept, hours=args.hours,
                                        needs_add=args.needs_add,
                                        needs_remove=args.needs_remove, needs=args.needs,
-                                       accept_json=accept_json)
+                                       accept_json=accept_json,
+                                       opt_out=getattr(args, "no_redact", False))
             except ValueError as exc:
                 print(f"swarph board obligations amend: {exc}", file=sys.stderr)
                 return 2
@@ -1385,6 +1448,7 @@ def run_board(argv: list[str]) -> int:
                 print("swarph board obligations withdraw: --reason is "
                       "whitespace-only", file=sys.stderr)
                 return 2
+            reason = redact_text(reason, opt_out=getattr(args, "no_redact", False), caller="board.obligations")
             st, d = _post_json(
                 f"{gw}/board/obligations/{args.id}/withdraw",
                 {"reason": reason}, token)
@@ -1441,7 +1505,7 @@ def run_board(argv: list[str]) -> int:
             st, d = _post_json(f"{gw}/board/cards", _card_add_payload(
                 self_name, pid, title, body=body, ai2=args.ai2,
                 priority=args.priority, labels=getattr(args, "labels", None),
-                due_at=args.due), token)
+                due_at=args.due, opt_out=getattr(args, "no_redact", False)), 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
@@ -1491,7 +1555,8 @@ def run_board(argv: list[str]) -> int:
             try:
                 patch = _card_edit_payload(
                     self_name, title_text, body_text, due_at=args.due,
-                    project_id=project_id, priority=args.priority)
+                    project_id=project_id, priority=args.priority,
+                    opt_out=getattr(args, "no_redact", False))
             except ValueError as exc:
                 print(f"swarph board cards edit: {exc}", file=sys.stderr)
                 return 2
@@ -1508,7 +1573,8 @@ def run_board(argv: list[str]) -> int:
                       f"an unrecoverable one", file=sys.stderr)
                 return 1
             try:
-                pre = _write_card_preimage(self_name, gw, args.id, cur, patch)
+                pre = _write_card_preimage(self_name, gw, args.id, cur, patch,
+                                           opt_out=getattr(args, "no_redact", False))
             except OSError as exc:
                 print(f"swarph board cards edit: cannot write the pre-image log "
                       f"({exc}) — refusing to write, for the same reason: the "
@@ -1541,7 +1607,7 @@ def run_board(argv: list[str]) -> int:
             # the row in one gateway call, or neither.
             if args.holder is not None and args.holder_flag is not None:
                 print("swarph board cards ask: holder given twice (positional and "
-                      "--holder) — pass one", file=sys.stderr)
+                       "--holder) — pass one", file=sys.stderr)
                 return 2
             holder = args.holder_flag or args.holder
             if holder is None and args.step is None:
@@ -1562,7 +1628,8 @@ def run_board(argv: list[str]) -> int:
                                     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)
+                                    task=args.task, task_needs=args.task_needs,
+                                    opt_out=getattr(args, "no_redact", False))
             except ValueError as exc:
                 print(f"swarph board cards ask: {exc}", file=sys.stderr)
                 return 2
@@ -1570,7 +1637,8 @@ def run_board(argv: list[str]) -> int:
             return _out(st, d, _ask_line, args.json)
         if args.command == "confirm-flow":
             try:
-                body = _confirm_flow_payload(self_name, args.holder, args.what)
+                body = _confirm_flow_payload(self_name, args.holder, args.what,
+                                            opt_out=getattr(args, "no_redact", False))
             except ValueError as e:
                 print(f"swarph board cards confirm-flow: {e}", file=sys.stderr)
                 return 2
@@ -1614,7 +1682,8 @@ def run_board(argv: list[str]) -> int:
                 return 1
             st, d = _post_json(
                 f"{gw}/messages",
-                _card_say_payload(self_name, to_node, args.kind, content, thread_uuid),
+                _card_say_payload(self_name, to_node, args.kind, content, thread_uuid,
+                                  opt_out=getattr(args, "no_redact", False)),
                 token,
             )
             # A 403 here carries the gateway's explanation that attaching PUBLISHES

swarph_cli-0.72.37/src/swarph_cli/commands/board_cost.py

@@ -0,0 +1,199 @@
+"""Card #1277 — cost per accepted outcome, from recorded usage only.
+
+A row whose usage is unknown is counted and excluded from the token
+totals. It is never treated as zero.
+"""
+from __future__ import annotations
+
+_ALWAYS = ("input_tokens", "output_tokens", "cache_read_tokens")
+_JOBS = ("execute", "grade", "advise", "rework", "other")
+_GRADE = {"validate", "plan-review", "second-seat", "spec-review"}
+
+
+def job_of(row) -> str | None:
+    if row.get("rework") or row.get("step") == "rework":
+        return "rework"
+    step = row.get("step")
+    if step is None or step == "":
+        return "other"
+    if step == "build":
+        return "execute"
+    if step in _GRADE:
+        return "grade"
+    if step in {"advise", "advisor", "pre-read"} or "advise" in step:
+        return "advise"
+    return None
+
+
+def _as_int(value):
+    if isinstance(value, bool) or not isinstance(value, int):
+        return None
+    return value
+
+
+def token_total(usage):
+    """Sum the fields that were read. Unknown is not zero.
+
+    Thinking is a breakdown of output_tokens and is not added again.
+    A cache split that was read is the cache total. A flat
+    cache_creation with no split is the total instead. Having neither
+    makes the row unknown."""
+    if not isinstance(usage, dict):
+        return None
+    total = 0
+    for name in _ALWAYS:
+        value = _as_int(usage.get(name, "unknown"))
+        if value is None:
+            return None
+        total += value
+    one_h = _as_int(usage.get("cache_creation_1h_tokens", "unknown"))
+    five = _as_int(usage.get("cache_creation_5m_tokens", "unknown"))
+    unsplit = _as_int(usage.get("cache_creation_unsplit_tokens", "unknown"))
+    if one_h is not None and five is not None:
+        return total + one_h + five
+    if unsplit is not None and one_h is None and five is None:
+        return total + unsplit
+    return None
+
+
+def row_cost(usage, rates):
+    """USD from llm_cost.compute_cost, or None when a price row or a
+    reading is missing. Unknown tokens are not passed in as zero."""
+    if token_total(usage) is None or not isinstance(usage, dict):
+        return None
+    model = usage.get("model")
+    price = (rates or {}).get(model) if isinstance(rates, dict) else None
+    if price is None:
+        return None
+    from swarph_shared.llm_cost import TokenUsage, compute_cost
+    one_h = _as_int(usage.get("cache_creation_1h_tokens", "unknown"))
+    five = _as_int(usage.get("cache_creation_5m_tokens", "unknown"))
+    unsplit = _as_int(usage.get("cache_creation_unsplit_tokens", "unknown"))
+    if one_h is not None and five is not None:
+        parsed = TokenUsage(
+            input_tokens=usage["input_tokens"],
+            output_tokens=usage["output_tokens"],
+            cache_read_tokens=usage["cache_read_tokens"],
+            cache_creation_1h_tokens=one_h,
+            cache_creation_5m_tokens=five,
+        )
+    elif unsplit is not None:
+        parsed = TokenUsage(
+            input_tokens=usage["input_tokens"],
+            output_tokens=usage["output_tokens"],
+            cache_read_tokens=usage["cache_read_tokens"],
+            cache_creation_unsplit_tokens=unsplit,
+        )
+    else:
+        return None
+    return compute_cost(parsed, price)
+
+
+def _window_label(window) -> str:
+    window = window or {}
+    card = window.get("card")
+    since = window.get("since") or "-"
+    until = window.get("until") or "-"
+    where = f"card #{card}" if card else "all cards"
+    return f"{where} since {since} until {until}"
+
+
+def format_cost(report: dict, rates=None) -> str:
+    closes = report.get("closes") or []
+    later = report.get("later_fix") or {}
+    by_card: dict = {}
+    for row in closes:
+        by_card.setdefault(row.get("card_id"), []).append(row)
+    if rates is None:
+        rates = report.get("rates")
+    lines = [f"window: {_window_label(report.get('window'))}"]
+    unknown_rows = 0
+    usd_parts = []
+    usd_blocked = False
+    underestimated = False
+    done_known = []
+    perfect_known = []
+    done = 0
+    perfect = 0
+    for card_id, rows in by_card.items():
+        stage = rows[0].get("stage") or "-"
+        fixes = later.get(str(card_id)) or later.get(card_id) or []
+        fails = sum(1 for row in rows if row.get("outcome") == "fail")
+        reworks = sum(1 for row in rows if row.get("rework") or row.get("step") == "rework")
+        fix_label = (" later-fix=" + ",".join(f"#{n}" for n in fixes)) if fixes else ""
+        lines.append(f"card #{card_id} stage={stage}{fix_label}")
+        buckets = {job: {"tokens": 0, "known": 0, "unknown": 0} for job in _JOBS}
+        card_known = 0
+        card_unknown = 0
+        for row in rows:
+            total = token_total(row.get("usage"))
+            job = job_of(row)
+            if total is None:
+                unknown_rows += 1
+                card_unknown += 1
+                if job in buckets:
+                    buckets[job]["unknown"] += 1
+                continue
+            card_known += total
+            if job in buckets:
+                buckets[job]["tokens"] += total
+                buckets[job]["known"] += 1
+        for job in _JOBS:
+            bucket = buckets[job]
+            lines.append(
+                f"  {job}: {bucket['tokens']} tokens over {bucket['known']} "
+                f"known rows (unknown {bucket['unknown']})")
+        lines.append(f"  rows: {len(rows)} FAIL: {fails} reworks: {reworks}")
+        if stage == "done":
+            for row in rows:
+                priced = row_cost(row.get("usage"), rates)
+                if priced is None:
+                    usd_blocked = True
+                else:
+                    usd_parts.append(priced.cost_usd)
+                    underestimated = underestimated or priced.underestimated
+        is_done = stage == "done"
+        is_perfect = is_done and fails == 0 and reworks == 0 and not fixes
+        if is_done:
+            done += 1
+            if card_unknown == 0:
+                done_known.append(card_known)
+            if is_perfect:
+                perfect += 1
+                if card_unknown == 0:
+                    perfect_known.append(card_known)
+    lines.append(f"unknown rows: {unknown_rows}")
+    known_sum = sum(done_known)
+    if done and len(done_known) == done:
+        lines.append(
+            f"tokens per card done: {known_sum}/{done} "
+            f"(known tokens, unknown rows excluded)")
+        lines.append(
+            f"cost per accepted outcome: {known_sum}/{done} "
+            f"tokens per done card (unknown rows: {unknown_rows})")
+    else:
+        lines.append(
+            "tokens per card done: unknown "
+            f"({len(done_known)} of {done} done cards fully read)")
+        lines.append(
+            "cost per accepted outcome: unknown "
+            f"({len(done_known)} of {done} done cards fully read, "
+            f"unknown rows: {unknown_rows})")
+    lines.append(f"perfect-run rate: {perfect}/{done}")
+    if perfect and len(perfect_known) == perfect:
+        lines.append(
+            f"cost per perfect run: {sum(perfect_known)}/{perfect} "
+            f"tokens per perfect card (unknown rows: {unknown_rows})")
+    else:
+        lines.append(f"cost per perfect run: no perfect runs ({perfect})")
+    if usd_blocked or not usd_parts:
+        lines.append("usd: unknown")
+    else:
+        total_usd = sum(usd_parts)
+        shown = int(total_usd) if total_usd == int(total_usd) else total_usd
+        note = " (unsplit cache priced at the 5m rate)" if underestimated else ""
+        lines.append(f"usd: {shown}{note}")
+    lines.append(
+        "sub-agent spend: included in each close "
+        "(that session's subagents, each response once)")
+    return "\n".join(lines)