@techierathore/techieflow 1.0.2 → 1.0.4

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
@@ -34,6 +34,7 @@ import re
 import subprocess
 import sys
 from collections import Counter, defaultdict, OrderedDict
+from datetime import datetime
 
 STREAMS = ("runs", "gates", "sessions", "commits", "misses")
 VERDICTS = ("Verified", "Needs re-verify", "FAIL", "Blocked", "Implemented", "Done (pre-existing)")
@@ -52,20 +53,155 @@ 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"}
+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",
                    "dependency-not-declared", "instruction-ignored", "other"),
+    "sort": ("spec", "unsaid", "weak-check", "ignored"),
 }
+# The four-question sort in words, for the report (SCHEMA.md §5.5.10).
+SORT_WORDS = {"spec": "the app's spec did not say it", "unsaid": "the framework never said it",
+              "weak-check": "the check was too weak", "ignored": "said and ignored"}
 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)
@@ -94,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.
 
@@ -206,6 +378,7 @@ def analyse_misses(misses):
     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"]
+    reviews = [m for m in misses if m.get("kind") == "review"]
 
     # ---- fold amendments into their parents BEFORE anything is counted (§5.5.7).
     # An amend completes a field the miss left null; it can never overwrite one, so
@@ -221,11 +394,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,
@@ -235,8 +411,10 @@ def analyse_misses(misses):
     # reported separately — never silently, and never backfilled with a value
     # nobody assessed at the time.
     def _eligible(rec, field):
+        # A record written after the field existed, or one that carries it anyway (an older
+        # record completed by an amend is sorted, whatever its date; Session 5, 2026-09-07).
         since = FIELD_SINCE.get(field)
-        return not since or (rec.get("ts") or "") >= since
+        return not since or (rec.get("ts") or "") >= since or bool(rec.get(field))
 
     # Latest fix per miss decides open/closed; a fix naming no known miss is an orphan.
     known = {m.get("miss_id") for m in opened}
@@ -349,13 +527,36 @@ def analyse_misses(misses):
     sole_tokens, sole_priced_n = tok(sole)
     shared_priced = [f for f in shared if f.get("tokens_out") is not None]
 
-    # Dollars exist ONLY where a harness measured them. Claude Code and Codex carry
+    # 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"]
 
+    # Owner reviews (§5.5.9): how many corrections each phase's output needed, and what
+    # producing it and correcting it cost. Token means divide by the records that carry the
+    # figure (§5.5.8), never by all of them.
+    def _mean(key):
+        xs = [r[key] for r in reviews if isinstance(r.get(key), (int, float))]
+        return (round(float(sum(xs)) / len(xs), 1) if len(xs) >= MIN_N else None), len(xs)
+    tp, tp_n = _mean("tokens_produce")
+    tc, tc_n = _mean("tokens_correct")
+
     return {
         "misses_total": len(opened),
         "miss_fixes_total": len(fixes),
@@ -381,6 +582,22 @@ def analyse_misses(misses):
                                    if m.get("found_by") in ("owner", "production")
                                    and not m.get("why_missed")
                                    and _eligible(m, "why_missed")),
+        # Whose gap (§5.5.10, FR-32): the four-question sort. Same denominator rule as
+        # why_missed — records that carry it, out of records that could have.
+        "sort_n": sum(1 for m in opened if m.get("sort")),
+        "sort_eligible": sum(1 for m in opened if _eligible(m, "sort")),
+        "sort_predates_field": sum(1 for m in opened if not _eligible(m, "sort")),
+        "sort": OrderedDict(
+            sorted(Counter(m["sort"] for m in opened if m.get("sort")).items(),
+                   key=lambda kv: (-kv[1], kv[0]))),
+        # Owner reviews (§5.5.9)
+        "reviews_n": len(reviews),
+        "review_corrections": sum(r["corrections"] for r in reviews if isinstance(r.get("corrections"), int)),
+        "reviews_by_phase": OrderedDict(
+            sorted(Counter(r.get("phase") or "?" for r in reviews).items(),
+                   key=lambda kv: (-kv[1], kv[0]))),
+        "review_tokens_produce_mean": tp, "review_tokens_produce_n": tp_n,
+        "review_tokens_correct_mean": tc, "review_tokens_correct_n": tc_n,
         "class_distribution": OrderedDict(
             sorted(Counter(m.get("miss_class") or "?" for m in opened).items(),
                    key=lambda kv: (-kv[1], kv[0]))),
@@ -429,6 +646,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),
     }
 
 
@@ -455,7 +678,7 @@ def analyse_phases(runs):
          confident fan-out figures largely composed of runs that could not have
          seen a subagent. Tree-scope only, with the exclusion printed.
 
-      3. DOLLARS.  Never pooled across harness (SCHEMA.md §4). Claude and Codex
+      3. DOLLARS.  Never pooled across harness (SCHEMA.md §4). Claude
          carry cost_usd:null permanently; a sum over mixed records under-reports
          silently. Reported per harness or not at all.
 
@@ -464,6 +687,41 @@ def analyse_phases(runs):
     when someone asks how it was measured."""
     live = [r for r in runs if r.get("kind", "run") == "run" and not r.get("backfilled")]
 
+    # A run that carries both ends but no `duration_s` was silently worth ZERO TIME here,
+    # while its tokens still counted — so a phase's total time was a sum over some of its
+    # runs and its tokens a sum over others (found 2026-09-07: the reset's own 13 runs
+    # reported 16h49m, because 6 of them predate the field and the true figure is ~55h).
+    # Deriving it is arithmetic on two recorded facts, not a guess, so it is done — and
+    # counted, so the report can say how many of its minutes were derived rather than read.
+    # `ended` itself may be absent on an older record; SCHEMA.md's own rule is that `ended`
+    # IS the moment the record was written, which is exactly what `ts` holds.
+    def _secs(a, b):
+        try:
+            fmt = "%Y-%m-%dT%H:%M:%SZ"
+            return int((datetime.strptime(b, fmt) - datetime.strptime(a, fmt)).total_seconds())
+        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 _dur(r) is not None or not r.get("started"):
+            continue
+        end = r.get("ended") or r.get("ts")
+        if not end:
+            continue
+        d = _secs(r["started"], end)
+        if d is not None and d >= 0:
+            r["duration_s"] = d
+            r["duration_derived"] = "ended" if r.get("ended") else "ts"
+            derived_n += 1
+
     def scope_of(r):
         return r.get("tokens_scope") or "absent"
 
@@ -481,16 +739,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:
@@ -517,12 +787,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] = {
@@ -532,6 +832,10 @@ def analyse_phases(runs):
                 "median": median(durs),
                 "max": max(durs) if durs else None,
                 "n": len(durs),
+                # how many of those minutes were computed from the record's own two
+                # timestamps because the record predates `duration_s` — arithmetic on
+                # recorded facts, but the reader is told rather than left to assume.
+                "derived_n": sum(1 for r in rs if r.get("duration_derived")),
             },
             "share_of_duration": pct(sum(durs), grand_dur),
             "tokens_measured_n": len(priced),
@@ -549,6 +853,27 @@ def analyse_phases(runs):
                 key=lambda kv: (-kv[1]["tokens_out"], kv[0]))),
             "harnesses": OrderedDict(sorted(Counter(r.get("harness") or "?" for r in rs).items())),
             "modes": OrderedDict(sorted(Counter(r.get("mode") or "—" for r in rs).items())),
+            # A phase run in named modes (a reset's sessions, a build's fresh/fix passes)
+            # is several different jobs under one `cmd`. The per-mode split says which,
+            # in the order they happened. Same denominators as the phase above: a run
+            # with no computable window contributes no tokens, never a zero.
+            "by_mode": OrderedDict(
+                (mode, {
+                    "runs": len([r for r in rs if (r.get("mode") or "—") == mode]),
+                    "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)),
+                    "tokens_unmeasured_n": len([r for r in rs
+                                                if (r.get("mode") or "—") == mode and not has_tokens(r)]),
+                    "files_written": sum(r.get("files_written") or 0
+                                         for r in rs if (r.get("mode") or "—") == mode),
+                    "first_started": min((r.get("started") or "" for r in rs
+                                          if (r.get("mode") or "—") == mode), default=""),
+                })
+                for mode in sorted({(r.get("mode") or "—") for r in rs},
+                                   key=lambda m: min((r.get("started") or "" for r in rs
+                                                      if (r.get("mode") or "—") == m), default=""))),
             "build_result": OrderedDict(sorted(Counter(r.get("build_result") or "—" for r in rs).items())),
             "reqs_touched_total": sum(r.get("reqs_count") or 0 for r in rs),
             "files_written_total": sum(r.get("files_written") or 0 for r in rs),
@@ -580,6 +905,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 {
@@ -587,6 +942,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 "
@@ -879,10 +1240,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"))
@@ -890,6 +1256,11 @@ 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],
@@ -910,39 +1281,73 @@ 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
 
     live = [g for g in gates if not g.get("backfilled")]
     back = [g for g in gates if g.get("backfilled")]
 
+    # `attempt` is DEFINED by §3.1 as 1 + the number of prior live gate records for the same
+    # requirement in the same app — a count over this very stream, not a judgement. A record
+    # that omits it was therefore being read as "no attempt", which drops it out of the
+    # first-pass rate and reports 0% for a set of records that all passed on their first and
+    # only verdict (found 2026-09-07 on the framework's own requirement lines). Derived here,
+    # in stream order, for records that lack it. A record that carries one is never touched.
+    _seen = {}
+    for g in sorted(live, key=lambda r: (r.get("ts") or "", r.get("run_id") or "")):
+        key = (g.get("app"), g.get("req_id"))
+        _seen[key] = _seen.get(key, 0) + 1
+        if g.get("attempt") is None:
+            g["attempt"] = _seen[key]
+            g["attempt_derived"] = True
+
     # REQs with ANY backfilled record are excluded from the live first-pass rate:
     # their live `attempt` numbering restarts at 1 (SCHEMA.md §3.1).
-    tainted = {g.get("req_id") for g in back}
+    # A requirement is keyed by (app, req_id): REQ-UI-001 exists in every project, so a rollup that
+    # keyed on req_id alone counted TfLens's and TechieBlog's as one requirement and its first-pass
+    # rate was wrong (MISS-TechieFlow-20260907-03, Session 5).
+    def rk(r):
+        return (r.get("app"), r.get("req_id"))
+
+    tainted = {rk(g) for g in back}
 
-    out = {"per_repo": per_repo, "tainted_reqs": sorted(x for x in tainted if x),
+    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)}
 
     for label, bucket in (("live", live), ("backfilled", back)):
         for ptype, recs in sorted(seg(bucket).items()):
-            eligible = [r for r in recs if label == "backfilled" or r.get("req_id") not in tainted]
-            reqs = {r.get("req_id") for r in eligible}
-            first_pass = {r.get("req_id") for r in eligible
+            eligible = [r for r in recs if label == "backfilled" or rk(r) not in tainted]
+            reqs = {rk(r) for r in eligible}
+            first_pass = {rk(r) for r in eligible
                           if r.get("attempt") == 1 and r.get("verdict") == "Verified"}
             failures = [r for r in recs if r.get("verdict") not in ("Verified", "Done (pre-existing)")]
             dist = Counter(r.get("gate") or "unattributed" for r in failures)
-            escaped_reqs = {r.get("req_id") for r in recs if r.get("gate") == "escaped"}
-            failed_reqs = {r.get("req_id") for r in failures}
+            escaped_reqs = {rk(r) for r in recs if r.get("gate") == "escaped"}
+            failed_reqs = {rk(r) for r in failures}
             out[label][ptype] = {
                 "records": len(recs),
                 "reqs_scored": len(reqs),
                 "reqs_excluded_backfill_taint":
-                    len({r.get("req_id") for r in recs if r.get("req_id") in tainted})
+                    len({rk(r) for r in recs if rk(r) in tainted})
                     if label == "live" else 0,
                 "first_pass_n": len(first_pass),
                 "first_pass_rate": pct(len(first_pass), len(reqs)) if len(reqs) >= MIN_N else "insufficient data (n=%d)" % len(reqs),
@@ -963,10 +1368,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"] = {
@@ -980,7 +1387,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,
@@ -1067,6 +1483,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"]))
@@ -1087,8 +1517,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"]))
@@ -1137,6 +1573,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.")
@@ -1154,8 +1599,9 @@ def print_phases(p, W):
     for cmd, m in p["phases"].items():
         print("  [%s]  %d run(s)" % (cmd, m["runs"]))
         d = m["duration_s"]
-        print("     wall clock       : total %s · median %s · max %s   (n=%d timed)"
-              % (_hms(d["total"]), _hms(d["median"]), _hms(d["max"]), d["n"]))
+        print("     wall clock       : total %s · median %s · max %s   (n=%d timed%s)"
+              % (_hms(d["total"]), _hms(d["median"]), _hms(d["max"]), d["n"],
+                 ", %d derived from the record's own timestamps" % d["derived_n"] if d.get("derived_n") else ""))
         t = m["tokens"]
         print("     tokens           : out %s · in %s · cache-read %s · cache-write %s"
               % (_k(t["out"]), _k(t["in"]), _k(t["cache_read"]), _k(t["cache_write"])))
@@ -1216,8 +1662,65 @@ 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"]:
-            print("     work             : %d REQ touch(es) · %d file(s) written"
+        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():
+                unm = ("  [%d unmeasured]" % v["tokens_unmeasured_n"]) if v["tokens_unmeasured_n"] else ""
+                print("         %-22s %2d run(s)  %8s  %8s out  %3d file(s)%s"
+                      % (mode, v["runs"], _hms(v["duration_s"]), _k(v["tokens_out"]),
+                         v["files_written"], unm))
+        print("     work             : %d REQ touch(es) · %d file(s) written"
                   % (m["reqs_touched_total"], m["files_written_total"]))
         print("")
 
@@ -1225,7 +1728,7 @@ def print_phases(p, W):
 def print_misses(m, W):
     """The §5.5 block. Two exclusions are printed with the figures they bound —
     an exclusion the reader cannot see is indistinguishable from a bug."""
-    if not m["misses_total"] and not m["miss_fixes_total"]:
+    if not m["misses_total"] and not m["miss_fixes_total"] and not m.get("reviews_n"):
         return
     print("")
     print("-" * W)
@@ -1269,9 +1772,29 @@ def print_misses(m, W):
               % m["escapes_missing_why"])
         print("       nothing recorded why. That is the most valuable record in the stream.")
         print("       Complete it: tf-emit.sh --amend <miss_id> why_missed <value>  (§5.5.7)")
+    # whose gap — the four-question sort (§5.5.10). Its own denominator, like why_missed.
+    if m.get("sort"):
+        print("  whose gap           : (%d of %d misses sorted)" % (m["sort_n"], m["sort_eligible"]))
+        for k, n in m["sort"].items():
+            print("      %-12s %4d  %-5s %s" % (k, n, pct(n, m["sort_n"]), SORT_WORDS.get(k, "")))
+    if m.get("sort_predates_field"):
+        print("     %d miss(es) predate the sort field (added %s); sort them with"
+              % (m["sort_predates_field"], FIELD_SINCE["sort"]))
+        print("     tf-emit.sh --amend <miss_id> sort <spec|unsaid|weak-check|ignored>")
     if m["amendments_applied"]:
         print("  amendments folded   : %d field(s) completed by miss-amend records (§5.5.7)"
               % m["amendments_applied"])
+    # owner reviews (§5.5.9): corrections per reviewed phase, and the two costs
+    if m.get("reviews_n"):
+        print("  owner reviews       : %d review(s), %d correction(s) given — "
+              % (m["reviews_n"], m["review_corrections"])
+              + "  ".join("%s=%d" % kv for kv in m["reviews_by_phase"].items()))
+        print("     tokens to produce the reviewed output : %s (n=%d)"
+              % (m["review_tokens_produce_mean"] if m["review_tokens_produce_mean"] is not None
+                 else "insufficient data", m["review_tokens_produce_n"]))
+        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["orphan_amends"]:
         print("     ⚠ %d miss-amend record(s) name no known miss, or a field outside the"
               % m["orphan_amends"])
@@ -1315,9 +1838,18 @@ def print_misses(m, W):
     else:
         print("        USD per miss        : no measured dollars (%d priced records)"
               % m["cost_usd_records"])
-        print("           Claude Code and Codex carry cost_usd:null permanently and are NEVER")
+        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)" %