@techierathore/techieflow 1.0.3 → 1.1.0

package/.tfcore/telemetry/tf-metrics.sh

@@ -26,7 +26,7 @@ set -uo pipefail
 
 command -v python3 >/dev/null 2>&1 || { echo "tf-metrics: python3 is required." >&2; exit 1; }
 
-exec python3 - "$@" <<'PYEOF'
+TF_METRICS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" exec python3 - "$@" <<'PYEOF'
 import glob
 import json
 import os
@@ -53,12 +53,77 @@ LATE_GATES = {"perf": "2026-08-10", "assets": "2026-08-31", "mockup-parity": "20
 # fill, so counting it as "not assessed" understates the practice being measured.
 # It leaves that field's denominator and is reported separately. SCHEMA.md §5.5.6 /
 # §3.5. Keep this table in sync when an optional field is added to any stream.
-FIELD_SINCE = {"why_missed": "2026-08-28", "sort": "2026-09-07"}
+FIELD_SINCE = {"why_missed": "2026-08-28", "sort": "2026-09-07", "what": "2026-09-07"}
+
+
+def _span(r):
+    """Seconds between a run's own `started` and `ended`, or None if they cannot be read."""
+    a, b = r.get("started"), r.get("ended")
+    if not isinstance(a, str) or not isinstance(b, str):
+        return None
+    try:
+        fmt = "%Y-%m-%dT%H:%M:%SZ"
+        return int((datetime.strptime(b, fmt) - datetime.strptime(a, fmt)).total_seconds())
+    except Exception:
+        return None
+
+
+def _dur(r):
+    """A run's duration in seconds, or None when the record does not carry a real one.
+
+    THE TIMESTAMPS WIN. A record stores a start, an end and a duration, and on a stream
+    written before the emitter checked them the third can contradict the first two:
+    TechieBlog holds 14 such records, one storing -166 and thirteen storing a plausible
+    round number (3600, 2700, 1800, 900, 600) that bears no relation to their own clocks
+    -- `refresh-status` started 20:05:00, ended 17:59:39, stored 600. Only the one that
+    stored the negative was ever detectable by reading the number alone.
+
+    So the duration is taken from the timestamps whenever they can be read, and a record
+    whose timestamps are themselves impossible carries NO duration rather than a
+    plausible one. The count of both is published (`duration_excluded_n`,
+    `duration_recomputed_n`) and printed, because "32 records, correct" is only honest
+    when the reader is also told that 14 were dropped. Every consumer goes through this
+    one function, so the two readers of a stream cannot disagree about the same record.
+    tests/regression/run.sh tf_015."""
+    span = _span(r)
+    if span is not None:
+        return span if span > 0 else None
+    d = r.get("duration_s")
+    return d if isinstance(d, (int, float)) and d > 0 else None
+
+
+def _dur_quality(records):
+    """(impossible, absent, recomputed) -- what _dur changed, split so the report can be
+    accurate rather than merely alarming.
+
+    "Its start is after its end" and "it never carried a duration" are different facts and
+    were briefly reported as one, which made this repo look like it held 30 corrupt records
+    when it holds 30 records that simply record no elapsed time (`started` == `ended`, no
+    `duration_s`). Neither reached a figure before or after -- but a reader told the wrong
+    reason chases the wrong thing."""
+    impossible = absent = recomputed = 0
+    for r in records:
+        span, stored = _span(r), r.get("duration_s")
+        has_stored = isinstance(stored, (int, float)) and stored > 0
+        if span is not None and span < 0:
+            impossible += 1
+        elif span is not None and span == 0:
+            absent += 1
+        elif span is None and not has_stored:
+            absent += 1
+        elif span is not None and has_stored and abs(span - stored) > 1:
+            recomputed += 1
+    return impossible, absent, recomputed
 
 # Fields a `miss-amend` record may complete, and their closed vocabularies.
 # Kept identical to tf-emit.sh's `_AMENDABLE`; the emitter enforces it on write and
 # this enforces it again on read, because a merged stream can carry records this
 # machine's emitter never saw. SCHEMA.md §5.5.7 states the rule for extending it.
+# `what` is the miss's own sentence: free text, not a vocabulary. Kept amendable
+# because the never-overwrite rule -- not the vocabulary -- is what stops an amend
+# altering a fact. MISS-TechieFlow-20260909-02; tests/regression/run.sh tf_018.
+AMENDABLE_TEXT_FIELDS = ("what",)
+
 AMENDABLE_FIELDS = {
     "why_missed": ("missing-checklist-item", "insufficient-verify-method",
                    "code-audit-limitation", "ambiguous-acceptance",
@@ -71,6 +136,72 @@ SORT_WORDS = {"spec": "the app's spec did not say it", "unsaid": "the framework
 MIN_N = 3  # fewer supporting records than this -> "insufficient data", never a number
 
 
+# --------------------------------------------------- list price (report time)
+# WHERE PRICING BELONGS (owner, 2026-09-10). The framework's job is to record what it MEASURED:
+# tokens, per model, and whatever cost the provider itself reported. Turning tokens into money is
+# a reporting job — this file's, and TfLens's — so it happens HERE, at report time, from the
+# fields already on the stream. Nothing priced is ever written to a record. That is SCHEMA.md §8's
+# existing rule ("derived metrics are computed, never stored") applied to money, and it is why a
+# rate card can change, or a reader disagree with this one, without a single record being wrong.
+#
+# The rate itself comes from `tf-model-pick.sh rate`, so the rate card is defined once and the
+# project's own `.tfcore/rate-card.json` wins where it exists.
+_RATE_CACHE = {}
+REPO_OF = {}          # id(record) -> the repo it was read from; never written into a record
+
+
+def rate_for(repo, model):
+    key = (repo, model)
+    if key not in _RATE_CACHE:
+        got = None
+        for base in (os.path.join(repo, ".tfcore", "utils"),
+                     os.path.join(os.environ.get("TF_METRICS_DIR", ""), "..", "utils")):
+            script = os.path.join(base, "tf-model-pick.sh")
+            if not os.path.isfile(script):
+                continue
+            try:
+                out = subprocess.run(["bash", script, "rate", model],
+                                     capture_output=True, text=True, timeout=20,
+                                     env=dict(os.environ, TF_PROJECT_DIR=repo))
+                if out.returncode == 0:
+                    parts = (out.stdout or "").strip().split("\t")
+                    if len(parts) >= 4:
+                        got = tuple(float(x) for x in parts[:4])
+                        break
+            except Exception:
+                pass
+        _RATE_CACHE[key] = got
+    return _RATE_CACHE[key]
+
+
+def list_price(repo, rec):
+    """What one run's measured tokens cost at list price, or None when nothing prices its model.
+
+    Output tokens are exact per model (`model_tokens_out`). Input and cache tokens are counted for
+    the window as a whole, so where a window ran several models they are shared out by each
+    model's output share — arithmetic, and the caller is told."""
+    split = rec.get("model_tokens_out")
+    if not isinstance(split, dict) or not split:
+        m = rec.get("model")
+        if not m or rec.get("tokens_out") is None:
+            return None
+        split = {m: rec.get("tokens_out") or 0}
+    total_out = sum(v or 0 for v in split.values())
+    ti = rec.get("tokens_in") or 0
+    tcr = rec.get("tokens_cache_read") or 0
+    tcw = rec.get("tokens_cache_write") or 0
+    usd, priced = 0.0, 0
+    for m, out in split.items():
+        r = rate_for(repo, m)
+        if not r:
+            continue
+        share = (float(out or 0) / total_out) if total_out else 0.0
+        usd += (ti * share * r[0] + (out or 0) * r[1]
+                + tcr * share * r[2] + tcw * share * r[3]) / 1_000_000.0
+        priced += 1
+    return round(usd, 6) if priced else None
+
+
 # ---------------------------------------------------------------- utilities
 def die(msg):
     sys.stderr.write("tf-metrics: %s\n" % msg)
@@ -99,6 +230,42 @@ def read_stream(repo, stream):
     return out
 
 
+def apply_voids(runs, app=None):
+    """Drop the run records a `run-void` names, and hand back what was dropped.
+
+    A stream is append-only, so a run record written with a wrong figure can be
+    neither edited nor deleted — and nothing inside the record says it is wrong, so
+    every figure over it is quietly polluted. The correction is therefore another
+    record: `run-void` names a run by the pair every run carries (`cmd` + `started`)
+    and says why (SCHEMA.md §2.7, written by `tf-emit.sh --void-run`).
+
+    Two rules, both the same one this file applies everywhere else. The voided record
+    leaves every figure — it is not clamped, guessed at or half-counted. And the count
+    of what left travels with the figures, because a total offered without its
+    exclusions is just a different wrong number. A void naming no run on this stream
+    is an orphan: it is counted and reported, never silently dropped, exactly as an
+    orphaned miss-amend is. tests/regression/run.sh tf_void."""
+    key = lambda r: (r.get("cmd"), r.get("started"))
+    voids = {}
+    for v in runs:
+        if v.get("kind") == "run-void" and v.get("started"):
+            voids[key(v)] = v
+    kept, dropped, reasons = [], 0, []
+    matched = set()
+    for r in runs:
+        if r.get("kind") == "run-void":
+            continue
+        if key(r) in voids:
+            matched.add(key(r))
+            dropped += 1
+            v = voids[key(r)]
+            reasons.append("%s %s %s — %s" % (app or r.get("app") or "?", r.get("cmd"),
+                                              r.get("started"), v.get("reason") or "no reason recorded"))
+            continue
+        kept.append(r)
+    return kept, dropped, reasons, len(set(voids) - matched)
+
+
 def emit(repo, stream, records, dry_run, quiet=False):
     """Append via tf-emit.sh — the single append primitive. Never write JSONL directly.
 
@@ -208,6 +375,11 @@ def analyse_misses(misses):
 
     Raw counts and the miss-class distribution ARE poolable: a miss counts as a miss
     whoever missed it; only its attribution is confidence-bounded."""
+    # a miss withdrawn by a miss-void leaves every figure, with its fixes and amends (§5.5.11)
+    voids = {m.get("miss_id"): m for m in misses if m.get("kind") == "miss-void"}
+    ids = {m.get("miss_id") for m in misses if m.get("kind") == "miss"}
+    voided = ["%s — %s" % (k, v.get("reason") or "no reason recorded") for k, v in voids.items() if k in ids]
+    misses = [m for m in misses if m.get("miss_id") not in voids or m.get("kind") == "review"]
     opened = [m for m in misses if m.get("kind") == "miss" and not m.get("backfilled")]
     fixes = [m for m in misses if m.get("kind") == "miss-fix" and not m.get("backfilled")]
     amends = [m for m in misses if m.get("kind") == "miss-amend"]
@@ -227,11 +399,14 @@ def analyse_misses(misses):
     for a in sorted(amends, key=lambda r: r.get("ts") or ""):
         parent = opened_by_id.get(a.get("miss_id"))
         fld = a.get("field")
-        if parent is None or fld not in AMENDABLE_FIELDS:
+        if parent is None or (fld not in AMENDABLE_FIELDS and fld not in AMENDABLE_TEXT_FIELDS):
             orphan_amends += 1
             continue
-        if parent.get(fld) is None and a.get("value") in AMENDABLE_FIELDS[fld]:
-            parent[fld] = a["value"]
+        val = a.get("value")
+        ok = (isinstance(val, str) and val.strip()) if fld in AMENDABLE_TEXT_FIELDS \
+             else (val in AMENDABLE_FIELDS.get(fld, ()))
+        if parent.get(fld) is None and ok:
+            parent[fld] = val
             amended += 1
 
     # ---- eligibility floor for optional fields added mid-stream (SCHEMA.md §3.5,
@@ -360,7 +535,21 @@ def analyse_misses(misses):
     # Dollars exist ONLY where a harness measured them. Claude Code carries
     # cost_usd:null permanently (SCHEMA.md §4) and are never priced from a rate card
     # here — a pooled sum over mixed harnesses would silently under-report.
-    paid = [f for f in sole if f.get("cost_usd") is not None]
+    #
+    # A null was never the only way to have no money figure, though. An OpenCode run on a
+    # subscription records cost_usd 0.0 — a real, measured zero, because the plan was already
+    # paid for — and averaging that in as a FREE repair is the TF-005 defect again, in the
+    # column right beside the one TF-005 was found in. Only a `metered` record is money
+    # (SCHEMA.md §2.5b). A record written before billing_mode existed is admitted on its old
+    # terms, and counted, so the change does not silently rewrite the past.
+    paid = [f for f in sole if f.get("cost_usd") is not None
+            and (f.get("billing_mode") in (None, "metered"))]
+    unpriced_subscription_n = len([f for f in sole if f.get("cost_usd") is not None
+                                   and f.get("billing_mode") not in (None, "metered")])
+    # And the figure that works on every harness: what the repair's tokens cost at list price,
+    # worked out here from the tokens the record carries. It is the only money-shaped number a
+    # Claude Code repair can have, because a Max subscription bills nothing per token.
+    listed = [p for p in (list_price(REPO_OF.get(id(f), ""), f) for f in sole) if p is not None]
     escaped = [m for m in opened if m.get("found_by") in ("owner", "production")]
     design = [m for m in opened if m.get("miss_class") == "unspecified-gap"]
 
@@ -382,6 +571,9 @@ def analyse_misses(misses):
         "resolved_misses": len(resolved),
         "amendments_applied": amended,
         "orphan_amends": orphan_amends,
+        "misses_voided_n": len(voided),
+        "misses_voided": voided,
+        "miss_voids_orphaned_n": len(voids) - len(voided),
         # Denominator is records that CARRY the field — why_missed is optional (§5.5.6)
         # and a missing value means "not assessed", never a zero for some category —
         # AND records that COULD have carried it: one written before 2026-08-28 had no
@@ -462,6 +654,12 @@ def analyse_misses(misses):
         "cost_usd_per_miss_measured": round(
             sum(f["cost_usd"] for f in paid) / len(paid), 4) if len(paid) >= MIN_N else None,
         "cost_usd_records": len(paid),
+        # Repairs whose dollars were measured and are NOT money: a subscription's zero, a local
+        # model's absent bill. Printed beside the figure, never inside it.
+        "cost_usd_excluded_not_money_n": unpriced_subscription_n,
+        "cost_list_usd_per_miss": round(
+            sum(listed) / len(listed), 4) if len(listed) >= MIN_N else None,
+        "cost_list_usd_records": len(listed),
     }
 
 
@@ -512,9 +710,16 @@ def analyse_phases(runs):
         except Exception:
             return None
 
+    # A stored duration of zero or less is not a measurement: it is an impossible record
+    # (`ended` before `started`) that reached the stream before the emitter refused those.
+    # Treat it as absent so it is re-derived here, and -- when the timestamps are just as
+    # impossible -- excluded from every figure below rather than admitted by a truthiness
+    # test. tests/regression/run.sh tf_015.
     derived_n = 0
+    negative_durations = sum(1 for r in live
+                             if isinstance(r.get("duration_s"), (int, float)) and r["duration_s"] < 0)
     for r in live:
-        if r.get("duration_s") or not r.get("started"):
+        if _dur(r) is not None or not r.get("started"):
             continue
         end = r.get("ended") or r.get("ts")
         if not end:
@@ -542,16 +747,28 @@ def analyse_phases(runs):
         return scope_of(r) == "tree" and r.get("subagent_runs") is not None
 
     grand_out = sum(r.get("tokens_out") or 0 for r in live if has_tokens(r))
-    grand_dur = sum(r.get("duration_s") or 0 for r in live if r.get("duration_s"))
+    grand_dur = sum(_dur(r) or 0 for r in live if _dur(r) is not None)
 
     phases = OrderedDict()
     for cmd in sorted({r.get("cmd") or "?" for r in live}):
         rs = [r for r in live if (r.get("cmd") or "?") == cmd]
         priced = [r for r in rs if has_tokens(r)]
-        durs = [r["duration_s"] for r in rs if r.get("duration_s")]
+        durs = [_dur(r) for r in rs if _dur(r) is not None]
         fan = [r for r in rs if sees_subagents(r)]
 
         models = defaultdict(lambda: {"runs": 0, "tokens_out": 0})
+        # List price, COMPUTED HERE from the tokens the record carries (see list_price above —
+        # pricing is a reporting job, and nothing priced is ever stored). Per model, attributed
+        # only where the window ran ONE model, the same rule the measured dollars follow below.
+        list_of = {}
+        for r in priced:
+            lp = list_price(REPO_OF.get(id(r), ""), r)
+            if lp is None:
+                continue
+            list_of[id(r)] = lp
+            ms = r.get("models") or ([r["model"]] if r.get("model") else [])
+            if len(ms) == 1:
+                models[ms[0]]["list_usd"] = round(models[ms[0]].get("list_usd", 0.0) + lp, 6)
         for r in priced:
             split = r.get("model_tokens_out")
             if isinstance(split, dict) and split:
@@ -578,12 +795,42 @@ def analyse_phases(runs):
         sub_out = sum(r.get("tokens_out_subagents") or 0 for r in fan)
         fan_out_total = sum(r.get("tokens_out") or 0 for r in fan if has_tokens(r))
 
+        # DOLLARS, and what each one means. A harness split was never enough: one OpenCode
+        # machine mixes a flat-fee subscription (whose marginal cost is a true zero), a metered
+        # API key (whose dollars are real money) and a local model (which has no bill at all),
+        # and pooling those three produces a money figure that is neither the money spent nor
+        # the effort used. `billing_mode` is the separation; only `metered` is money.
         cost_by_harness = defaultdict(float)
         cost_n = Counter()
+        cost_by_mode = defaultdict(float)
+        mode_n = Counter()
+        model_usd = defaultdict(float)
+        model_usd_n = Counter()
+        plan_by_model = defaultdict(float)
+        usd_unattributed, usd_unattributed_n = 0.0, 0
         for r in priced:
+            mode = r.get("billing_mode") or "unrecorded"
+            mode_n[mode] += 1
             if r.get("cost_usd") is not None:
                 cost_by_harness[r.get("harness") or "?"] += r["cost_usd"]
                 cost_n[r.get("harness") or "?"] += 1
+                cost_by_mode[mode] += r["cost_usd"]
+                if mode == "plan":
+                    ms = r.get("models") or ([r["model"]] if r.get("model") else [])
+                    if len(ms) == 1:
+                        plan_by_model[ms[0]] += r["cost_usd"]
+                if mode == "metered":
+                    # Per-model spend is attributed ONLY where the window ran one model.
+                    # Splitting one window's dollars across several models by their token
+                    # share is arithmetic, not measurement — the same line §5.5.3 draws
+                    # between `sole` and `shared`, one stream over.
+                    ms = r.get("models") or ([r["model"]] if r.get("model") else [])
+                    if len(ms) == 1:
+                        model_usd[ms[0]] += r["cost_usd"]
+                        model_usd_n[ms[0]] += 1
+                    else:
+                        usd_unattributed += r["cost_usd"]
+                        usd_unattributed_n += 1
 
         tok = lambda k: sum(r.get(k) or 0 for r in priced)
         phases[cmd] = {
@@ -621,7 +868,7 @@ def analyse_phases(runs):
             "by_mode": OrderedDict(
                 (mode, {
                     "runs": len([r for r in rs if (r.get("mode") or "—") == mode]),
-                    "duration_s": sum(r.get("duration_s") or 0
+                    "duration_s": sum(_dur(r) or 0
                                       for r in rs if (r.get("mode") or "—") == mode),
                     "tokens_out": sum(r.get("tokens_out") or 0
                                       for r in rs if (r.get("mode") or "—") == mode and has_tokens(r)),
@@ -666,6 +913,36 @@ def analyse_phases(runs):
             "cost_usd_by_harness": OrderedDict(
                 (h, {"usd": round(v, 6), "records": cost_n[h]})
                 for h, v in sorted(cost_by_harness.items())),
+            # …and per billing mode, which is the separation that decides whether a number
+            # is money at all (SCHEMA.md §2.5b).
+            "billing_modes": OrderedDict(sorted(mode_n.items())),
+            "cost_usd_by_billing_mode": OrderedDict(
+                (mode, round(v, 6)) for mode, v in sorted(cost_by_mode.items())),
+            "money_usd": round(cost_by_mode.get("metered", 0.0), 6),
+            "money_records": mode_n.get("metered", 0),
+            # A window that mixed a metered model with a subscription one really was billed, but
+            # the bill cannot be separated from the part that was already paid for. Real money,
+            # reported on its own line rather than folded into the headline or dropped.
+            "money_mixed_usd": round(cost_by_mode.get("mixed", 0.0), 6),
+            "money_mixed_records": mode_n.get("mixed", 0),
+            "spend_by_model": OrderedDict(
+                (m, {"usd": round(v, 6), "records": model_usd_n[m]})
+                for m, v in sorted(model_usd.items(), key=lambda kv: (-kv[1], kv[0]))),
+            "spend_unattributed": {"usd": round(usd_unattributed, 6), "records": usd_unattributed_n},
+            # LIST PRICE — what these tokens would cost bought at the published rate. It is the
+            # only figure that compares a subscription phase with a metered one, and it is a
+            # price list applied to a measurement, never a bill. Reported apart from `money_usd`
+            # for exactly that reason, with the unpriced count beside it.
+            "list_usd": round(sum(list_of.values()), 6),
+            "list_usd_records": len(list_of),
+            "list_usd_unpriced_n": len(priced) - len(list_of),
+            # A monthly plan reports dollars too, but they are ALLOWANCE CONSUMED against a
+            # per-model limit, not an invoice — and they are the numbers that produce the limit
+            # the fallback chain exists for, so they are worth their own line.
+            "plan_allowance_usd": round(cost_by_mode.get("plan", 0.0), 6),
+            "plan_allowance_records": mode_n.get("plan", 0),
+            "plan_allowance_by_model": OrderedDict(
+                (m, round(v, 6)) for m, v in sorted(plan_by_model.items(), key=lambda kv: -kv[1])),
         }
 
     return {
@@ -673,6 +950,12 @@ def analyse_phases(runs):
         "scope_coverage": OrderedDict(sorted(scope_cov.items())),
         "tokens_out_total": grand_out,
         "duration_s_total": grand_dur,
+        # What the duration figures are actually built on. A total is only honest when the
+        # reader is told what it left out: TechieBlog's 46 run records yield 32 usable ones.
+        "duration_measured_n": len([r for r in live if _dur(r) is not None]),
+        "duration_impossible_n": _dur_quality(live)[0],
+        "duration_absent_n": _dur_quality(live)[1],
+        "duration_recomputed_n": _dur_quality(live)[2],
         "phases": phases,
         "note": ("Per-phase effort over LIVE run records, aggregated by `cmd`. Token "
                  "figures exclude runs whose window could not be computed; fan-out "
@@ -965,10 +1248,15 @@ def analyse(repos):
     per_repo = []
     commit_dupes = 0
     session_dupes = 0
+    voided_runs = 0
+    void_reasons = []
+    void_orphans = 0
     for repo in repos:
         g = read_stream(repo, "gates")
-        r = read_stream(repo, "runs")
-        misses += read_stream(repo, "misses")
+        r, vn, vr, vo = apply_voids(read_stream(repo, "runs"), app_name(repo))
+        voided_runs += vn; void_reasons += vr; void_orphans += vo
+        repo_misses = read_stream(repo, "misses")
+        misses += repo_misses
         # Per repo, not across them (SCHEMA.md §4): the OpenCode plugin
         # appends a cumulative snapshot at every root-session idle.
         s, sd = dedupe_sessions(read_stream(repo, "sessions"))
@@ -976,13 +1264,18 @@ def analyse(repos):
         # Per repo, not across them: two repos may legitimately share a short sha.
         c, d = dedupe_commits(read_stream(repo, "commits"))
         commit_dupes += d
+        # Which repo each record came from, so the report can price it with THAT project's rate
+        # card and routing. Kept beside the records rather than written into them: nothing here
+        # may add a field a record did not have.
+        for _x in r + repo_misses:
+            REPO_OF[id(_x)] = repo
         gates += g; runs += r; sessions += s; commits += c
         per_repo.append({"repo": repo, "app": app_name(repo),
                          "project_type": project_type(repo)[0],
                          "gates": len(g), "gates_backfilled": sum(1 for x in g if x.get("backfilled")),
                          "runs": len(r), "sessions": len(s), "commits": len(c),
-                         "misses": sum(1 for x in read_stream(repo, "misses")
-                                       if x.get("kind") == "miss"),
+                         "misses": sum(1 for x in repo_misses if x.get("kind") == "miss" and x.get("miss_id") not in
+                                       {v.get("miss_id") for v in repo_misses if v.get("kind") == "miss-void"}),
                          # A repo reclassified after records were written (most often a
                          # greenfield project born `docs` and upgraded once it grew a head)
                          # keeps the OLD value on every existing record — append-only means
@@ -996,9 +1289,19 @@ def analyse(repos):
                          "commit_hook": has_commit_hook(repo)})
 
     def seg(records):
+        # An `FR` verdict grades a framework requirement line, not an application's
+        # screen: it is written by a runner over a document the framework controls, so
+        # it passes far more often than a REQ verified against a running app. Pooled
+        # into an application segment it raises that segment's first-pass rate and
+        # dilutes its escape rate, with nothing on the output to show it happened.
+        # SCHEMA.md §3 states the rule -- "it never pools with the others" -- and this
+        # is where it is applied. Tested by tests/regression/run.sh tf_020.
         d = defaultdict(list)
         for r in records:
-            key = "unclassified" if r.get("project_type_inferred") else r.get("project_type", "app")
+            if r.get("req_class") == "FR":
+                key = "framework-requirement"
+            else:
+                key = "unclassified" if r.get("project_type_inferred") else r.get("project_type", "app")
             d[key].append(r)
         return d
 
@@ -1031,6 +1334,10 @@ def analyse(repos):
 
     out = {"per_repo": per_repo, "tainted_reqs": sorted("%s:%s" % x for x in tainted if x[1]),
            "live": {}, "backfilled": {}, "pooled": {},
+           # what a `run-void` took out of every figure above, and why (SCHEMA.md §2.7)
+           "runs_voided_n": voided_runs,
+           "runs_voided": void_reasons,
+           "run_voids_orphaned_n": void_orphans,
            "misses": analyse_misses(misses),
            "phases": analyse_phases(runs)}
 
@@ -1069,10 +1376,12 @@ def analyse(repos):
     # ---- poolable metrics: runs, cadence, tokens. Exempt from both separations.
     build_runs = [r for r in runs if r.get("cmd") == "build-phase"]
     fix_runs = [r for r in runs if r.get("mode") == "fix"]
-    throughput = [float(r["reqs_count"]) / r["duration_s"]
-                  for r in runs if r.get("duration_s") and r.get("reqs_count")]
+    throughput = [float(r["reqs_count"]) / _dur(r)
+                  for r in runs if _dur(r) is not None and r.get("reqs_count")]
     batch = [r["reqs_count"] for r in build_runs if r.get("reqs_count") is not None]
     verified_transitions = sum(1 for g in gates if g.get("verdict") == "Verified")
+    pooled_list = [p for p in (list_price(REPO_OF.get(id(r), ""), r) for r in runs)
+                   if p is not None]
     tok = sum((s.get("input_tokens") or 0) + (s.get("output_tokens") or 0) for s in sessions)
     days = {c.get("ts", "")[:10] for c in commits if c.get("ts")}
     out["pooled"] = {
@@ -1086,7 +1395,16 @@ def analyse(repos):
         "tokens_total": tok,
         "tokens_per_verified_req": round(float(tok) / verified_transitions, 1)
                                    if verified_transitions >= MIN_N and tok else None,
-        "cost_usd": None,  # never estimated — see SCHEMA.md §4
+        "cost_usd": None,  # what was BILLED is never estimated — see SCHEMA.md §4
+        # What the same work costs at list price. A price, not a bill (SCHEMA.md §2.5b), and the
+        # only money-shaped headline that works on a subscription — which is most of this
+        # framework's runs. Summed over the runs that carry it, with that count published, so a
+        # figure built on half the runs cannot be read as if it covered all of them.
+        "list_usd_total": round(sum(pooled_list), 4),
+        "list_usd_records": len(pooled_list),
+        "list_usd_per_verified_req": (
+            round(sum(pooled_list) / verified_transitions, 4)
+            if verified_transitions >= MIN_N and len(pooled_list) >= MIN_N else None),
         "commits": len(commits),
         "commit_duplicates_collapsed": commit_dupes,
         "session_duplicates_collapsed": session_dupes,
@@ -1173,6 +1491,20 @@ def print_report(a, repos):
         print("        across project_type or across live/backfilled would produce a")
         print("        number that cannot be defended. See SCHEMA.md §6.")
         print("")
+    if a.get("runs_voided_n"):
+        print("  %d run record(s) VOIDED — named by a run-void record as wrong, so they are"
+              % a["runs_voided_n"])
+        print("  in no figure above. Both records stay on the stream; nothing was deleted:")
+        for line in a.get("runs_voided", [])[:6]:
+            print("    " + line)
+        if len(a.get("runs_voided", [])) > 6:
+            print("    ... and %d more" % (len(a["runs_voided"]) - 6))
+        print("")
+    if a.get("run_voids_orphaned_n"):
+        print("  %d run-void record(s) name a run that is not on this stream — the void was"
+              % a["run_voids_orphaned_n"])
+        print("  written against a record that never arrived. Nothing was excluded for them.")
+        print("")
     if a["tainted_reqs"]:
         print("  %d REQ(s) excluded from the LIVE first-pass rate because they carry"
               % len(a["tainted_reqs"]))
@@ -1193,8 +1525,14 @@ def print_report(a, repos):
     print("  REQ throughput      : %s REQs/hour (median across runs)" %
           (p["throughput_median_reqs_per_hour"] if p["throughput_median_reqs_per_hour"] is not None else "insufficient data"))
     print("  sessions / tokens   : %d sessions, %s total tokens" % (p["sessions"], "{:,}".format(p["tokens_total"])))
-    print("  tokens per Verified : %s   (cost in USD is NEVER estimated — SCHEMA.md §4)" %
+    print("  tokens per Verified : %s   (what you were BILLED is never estimated — SCHEMA.md §4)" %
           (p["tokens_per_verified_req"] if p["tokens_per_verified_req"] is not None else "insufficient data"))
+    if p.get("list_usd_records"):
+        print("  list price          : $%s over %d priced run(s) — the published rate applied to"
+              % (p["list_usd_total"], p["list_usd_records"]))
+        print("                        the tokens actually measured. A price, not a bill.")
+        if p.get("list_usd_per_verified_req") is not None:
+            print("  list $ per Verified : $%s" % p["list_usd_per_verified_req"])
     print("  commit cadence      : %s commits/active day (%d commits over %d days)" %
           (p["commits_per_active_day"] if p["commits_per_active_day"] is not None else "—",
            p["commits"], p["active_days"]))
@@ -1243,6 +1581,15 @@ def print_phases(p, W):
     print("-" * W)
     print("  %d live run record(s). Token-window coverage: %s"
           % (p["runs_live"], "  ".join("%s=%d" % kv for kv in p["scope_coverage"].items())))
+    if any(p.get(k) for k in ("duration_impossible_n", "duration_absent_n", "duration_recomputed_n")):
+        print("  duration: %d of %d record(s) usable"
+              % (p.get("duration_measured_n", 0), p["runs_live"])
+              + (", %d impossible (start after end, discarded)" % p["duration_impossible_n"]
+                 if p.get("duration_impossible_n") else "")
+              + (", %d record no elapsed time" % p["duration_absent_n"]
+                 if p.get("duration_absent_n") else "")
+              + (", %d taken from the timestamps over a stored figure that disagreed"
+                 % p["duration_recomputed_n"] if p.get("duration_recomputed_n") else ""))
     print("  A window is only as good as its scope: 'tree' saw the subagents, 'main'")
     print("  did not look, 'none'/absent measured nothing at all and is excluded from")
     print("  every token figure below rather than averaged in as a zero.")
@@ -1323,8 +1670,57 @@ def print_phases(p, W):
         for h, c in m["cost_usd_by_harness"].items():
             print("     cost (%s)  : $%s over %d record(s) — MEASURED, never pooled "
                   "across harness" % (h, c["usd"], c["records"]))
-        if m["reqs_touched_total"] or m["files_written_total"]:
-            bm = m.get("by_mode") or {}
+        bmodes = m.get("billing_modes") or {}
+        if bmodes:
+            print("     paid for by      : " +
+                  " · ".join("%s %d" % (k, v) for k, v in bmodes.items()))
+            if m.get("list_usd_records"):
+                print("     list price       : $%s over %d run(s) — the published rate applied to"
+                      % (m["list_usd"], m["list_usd_records"]))
+                print("                        the tokens on the record, worked out HERE and never")
+                print("                        stored. A price, not a bill: it is what makes a")
+                print("                        subscription run comparable with a metered one.")
+                if m.get("list_usd_unpriced_n"):
+                    print("                        %d run(s) had no rate for their model and are"
+                          % m["list_usd_unpriced_n"])
+                    print("                        outside it — never priced at zero.")
+            if m.get("money_records"):
+                print("     money billed     : $%s over %d metered run(s). Only a metered run is"
+                      % (m["money_usd"], m["money_records"]))
+                print("                        money billed; a subscription's zero is a flat fee")
+                print("                        already paid, a local model has no bill (§2.5b).")
+            if m.get("plan_allowance_records"):
+                print("     plan allowance   : $%s used over %d run(s) on a monthly plan. This is"
+                      % (m["plan_allowance_usd"], m["plan_allowance_records"]))
+                print("                        the provider's own meter against a PER-MODEL")
+                print("                        allowance, not an invoice — and it is what runs out")
+                print("                        and sends a tier to its fallback.")
+                for mod, v in (m.get("plan_allowance_by_model") or {}).items():
+                    print("         %-30s $%s of allowance" % (mod, v))
+            if m.get("money_mixed_usd"):
+                print("     also billed      : $%s on %d run(s) whose window mixed billing modes —"
+                      % (m["money_mixed_usd"], m["money_mixed_records"]))
+                print("                        real money, but not separable from the part a")
+                print("                        subscription had already paid for.")
+            for mod, c in (m.get("models") or {}).items():
+                bits = []
+                if c.get("list_usd"):
+                    bits.append("list $%s" % c["list_usd"])
+                sp = (m.get("spend_by_model") or {}).get(mod)
+                if sp:
+                    bits.append("billed $%s" % sp["usd"])
+                if bits:
+                    print("         %-30s %s" % (mod, " · ".join(bits)))
+            un = m.get("spend_unattributed") or {}
+            if un.get("records"):
+                print("         %-30s billed $%-8s over %d run(s) — the window ran several"
+                      % ("(not attributed)", un["usd"], un["records"]))
+                print("             models, and one window's dollars are not split by token share.")
+        # `bm` used to be assigned inside `if m["reqs_touched_total"] or m["files_written_total"]:`
+        # and read outside it, so --phases crashed with UnboundLocalError on any phase that
+        # touched no REQ and wrote no file — which is every metrics-report and every render.
+        # MISS-TechieFlow-20260910-03.
+        bm = m.get("by_mode") or {}
         if len(bm) > 1:
             print("     by mode          : (in the order they ran)")
             for mode, v in bm.items():
@@ -1407,6 +1803,15 @@ def print_misses(m, W):
         print("     tokens to apply the corrections       : %s (n=%d)"
               % (m["review_tokens_correct_mean"] if m["review_tokens_correct_mean"] is not None
                  else "insufficient data", m["review_tokens_correct_n"]))
+    if m.get("misses_voided_n"):
+        print("  withdrawn           : %d miss(es) named by a miss-void, in no figure above:" % m["misses_voided_n"])
+        for line in m["misses_voided"][:6]:
+            print("     " + line)
+        if m["misses_voided_n"] > 6:
+            print("     ... and %d more" % (m["misses_voided_n"] - 6))
+    if m.get("miss_voids_orphaned_n"):
+        print("     ⚠ %d miss-void record(s) name no miss on this stream — nothing was excluded for them"
+              % m["miss_voids_orphaned_n"])
     if m["orphan_amends"]:
         print("     ⚠ %d miss-amend record(s) name no known miss, or a field outside the"
               % m["orphan_amends"])
@@ -1453,6 +1858,15 @@ def print_misses(m, W):
         print("           Claude Code carries cost_usd:null permanently and is NEVER")
         print("           priced from a rate card here (SCHEMA.md §4). Real dollars come from")
         print("           OpenCode runs; token counts are the honest figure everywhere else.")
+    if m.get("cost_list_usd_per_miss") is not None:
+        print("        list price per miss : $%s  (%d record(s)) — the repair's tokens at the"
+              % (m["cost_list_usd_per_miss"], m["cost_list_usd_records"]))
+        print("        published rate. Works on every harness, and is a price, not a bill.")
+    if m.get("cost_usd_excluded_not_money_n"):
+        print("        %d fix record(s) measured a cost that is NOT money — a subscription's"
+              % m["cost_usd_excluded_not_money_n"])
+        print("        zero or a local model's absent bill — and are outside that figure")
+        print("        rather than averaged in as free repairs (SCHEMA.md §2.5b).")
     print("     shared (apportioned): %d fix records — equal division, NOT a measurement"
           % m["cost_shared_n"])
     print("        tokens out per miss : %s   (n=%d priced)" %