@techierathore/techieflow 1.0.3 → 1.1.0

package/.tfcore/utils/tf-emit.sh

@@ -19,6 +19,12 @@
 #   tf-emit.sh --amend MISS-App-20260828-01 why_missed missing-checklist-item
 #                                               # fills a field that is still null on a miss already on
 #                                               # the stream (SCHEMA.md §5.5.7). Never overwrites.
+#   tf-emit.sh --void-run build-phase 2026-09-09T11:40:00Z "the start time was guessed, not measured"
+#                                               # marks a WRONG run record as not to be counted: both
+#                                               # records stay, every figure skips it and says how many
+#                                               # and why (SCHEMA.md §2.7). Refuses if no such run.
+#   tf-emit.sh --void-miss MISS-App-20260919-01 "logged again from an earlier triage's leftovers"
+#                                               # the same for a WRONG miss (SCHEMA.md §5.5.11)
 #   tf-emit.sh --origin-of REQ-UI-014           # prints "<started> <cmd> <agent>" of the last build or fix
 #                                               # run that touched the row, nothing when there is none
 #   tf-emit.sh --where                          # prints the resolved docs/metrics dir
@@ -270,13 +276,72 @@ fi
 # patience rather than quality. Open = no miss-fix, or the latest miss-fix
 # closed with a verdict_after other than "Verified". Prints "<miss_id>
 # <miss_class>" for the most recent open miss, or nothing at all.
+# --- list the open misses whose deficient artifact is a document ----------
+# `*amend-docs` is the command that edits a BRD, an Architecture or a mockup, so it is
+# the only command that can close a miss whose artifact is one of those -- and it had no
+# way to find them. Every other close path works off a checklist row the verifier touched,
+# which a BRD edit never is, so a document miss stayed open forever (TF-016: twelve
+# finished TfLens items showed as outstanding for up to two weeks).
+#
+#   tf-emit.sh --open-misses <App> [--artifact-class doc]
+#
+# Prints one line per open miss: "<miss_id> <artifact> <what>". Open means no miss-fix
+# carries verdict_after Verified, the same test --open-miss applies.
+if [[ "$1" == "--open-misses" ]]; then
+  OMAPP="${2:-}"; OMCLASS=""
+  [[ "${3:-}" == "--artifact-class" ]] && OMCLASS="${4:-}"
+  TF_OMAPP="$OMAPP" TF_OMCLASS="$OMCLASS" python3 - "$MET_DIR/misses.jsonl" 2>"$TF_ERR" <<'PY2' || true
+import json, os, sys
+DOC = {"brd", "architecture", "uidesign", "checklist", "devguide"}
+app, klass = os.environ.get("TF_OMAPP") or "", os.environ.get("TF_OMCLASS") or ""
+opened, fixes, voided = [], {}, set()
+try:
+    with open(sys.argv[1], encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                r = json.loads(line)
+            except Exception:
+                continue
+            if r.get("kind") == "miss":
+                opened.append(r)
+            elif r.get("kind") == "miss-void":
+                voided.add(r.get("miss_id"))
+            elif r.get("kind") == "miss-fix":
+                mid = r.get("miss_id")
+                if mid:
+                    prev = fixes.get(mid)
+                    if prev is None or (r.get("ts") or "") >= (prev.get("ts") or ""):
+                        fixes[mid] = r
+except FileNotFoundError:
+    pass
+for r in opened:
+    if r.get("miss_id") in voided:
+        continue
+    if app and r.get("app") and r.get("app") != app:
+        continue
+    art = r.get("artifact") or ""
+    if klass == "doc" and art not in DOC:
+        continue
+    if klass and klass != "doc" and art != klass:
+        continue
+    fix = fixes.get(r.get("miss_id"))
+    if fix is not None and fix.get("verdict_after") == "Verified":
+        continue
+    print("%s %s %s" % (r.get("miss_id"), art or "-", (r.get("what") or "")[:110]))
+PY2
+  exit 0
+fi
+
 if [[ "$1" == "--open-miss" ]]; then
   REQ="$2"
   [[ -n "$REQ" ]] || exit 0
   python3 - "$MET_DIR/misses.jsonl" "$REQ" 2>"$TF_ERR" <<'PY' || true
 import json, sys
 path, req = sys.argv[1], sys.argv[2]
-opened, fixes = [], {}
+opened, fixes, voided = [], {}, set()
 try:
     with open(path, encoding="utf-8") as fh:
         for line in fh:
@@ -289,6 +354,8 @@ try:
                 continue
             if r.get("kind") == "miss" and r.get("req_id") == req:
                 opened.append(r)
+            elif r.get("kind") == "miss-void":
+                voided.add(r.get("miss_id"))
             elif r.get("kind") == "miss-fix":
                 mid = r.get("miss_id")
                 if mid:
@@ -298,6 +365,8 @@ try:
 except FileNotFoundError:
     pass
 for r in reversed(opened):                     # most recent first
+    if r.get("miss_id") in voided:
+        continue
     fix = fixes.get(r.get("miss_id"))
     if fix is None or fix.get("verdict_after") != "Verified":
         print("%s %s" % (r.get("miss_id"), r.get("miss_class") or "other"))
@@ -344,9 +413,19 @@ AMENDABLE = {
     # still make later, so a miss logged before the field existed can be sorted now.
     "sort": ("spec", "unsaid", "weak-check", "ignored"),
 }
-if fld not in AMENDABLE:
+    # `what` is the miss's own sentence, and it is FREE TEXT -- the one field here that
+    # is not a closed vocabulary. It is allowed because the protection was never the
+    # vocabulary: an amend may only fill a field that is still null and can never
+    # overwrite one that is set (below), so free text cannot rewrite a fact, only
+    # supply one that was missing. Validated as non-empty text instead.
+    # MISS-TechieFlow-20260909-02; tests/regression/run.sh tf_018.
+AMENDABLE_TEXT = ("what",)
+if fld not in AMENDABLE and fld not in AMENDABLE_TEXT:
     print("REFUSED %s is not an amendable field (SCHEMA.md §5.5.7)" % fld); raise SystemExit(0)
-if val not in AMENDABLE[fld]:
+if fld in AMENDABLE_TEXT:
+    if not isinstance(val, str) or not val.strip():
+        print("REFUSED %s must be a non-empty sentence" % fld); raise SystemExit(0)
+elif val not in AMENDABLE[fld]:
     print("REFUSED %r is not in the closed vocabulary for %s" % (val, fld)); raise SystemExit(0)
 
 parent, current = None, None
@@ -389,8 +468,116 @@ PY
   exit 0
 fi
 
+# --- write helper: withdraw a miss that should never have been written -----
+# SCHEMA.md §5.5.11 — --void-run's answer for the misses stream (TrBlazeUI TF-001).
+if [[ "$1" == "--void-miss" ]]; then
+  VMID="$2"; VWHY="$3"
+  VREC="$(python3 - "$MET_DIR/misses.jsonl" "$VMID" "$VWHY" 2>"$TF_ERR" <<'PY' || true
+import json, sys
+path, mid, why = sys.argv[1], sys.argv[2], sys.argv[3]
+found, voided = False, False
+try:
+    for line in open(path, encoding="utf-8"):
+        try:
+            r = json.loads(line)
+        except Exception:
+            continue
+        if r.get("miss_id") == mid:
+            found = found or r.get("kind") == "miss"
+            voided = voided or r.get("kind") == "miss-void"
+except FileNotFoundError:
+    pass
+if not found:
+    print("REFUSED no miss record %s on this stream" % mid)
+elif voided:
+    print("REFUSED %s is already voided — one void is enough" % mid)
+elif not why.strip():
+    print("REFUSED a void needs a reason a reader can check")
+else:
+    print("OK " + json.dumps({"kind": "miss-void", "miss_id": mid, "reason": why.strip()},
+                             separators=(",", ":"), ensure_ascii=False))
+PY
+)"
+  case "$VREC" in
+    "OK "*) printf '%s' "${VREC#OK }" | bash "${BASH_SOURCE[0]}" misses
+            echo "tf-emit: voided $VMID — $VWHY" ;;
+    "REFUSED "*) echo "tf-emit: void refused — ${VREC#REFUSED }" ;;
+    *) echo "tf-emit: void could not be evaluated — nothing written" ;;
+  esac
+  exit 0
+fi
+
+# --- write helper: mark a run record as not to be counted -----------------
+# SCHEMA.md §2.7. The same doctrine as --amend, one stream over: a run record that
+# is WRONG cannot be edited or deleted, because the stream is append-only and the
+# evidence that it happened is worth keeping. So the correction is another record.
+#
+#   tf-emit.sh --void-run <cmd> <started> "<why it is wrong>"
+#
+# It names the run by its own `cmd` and `started` — the pair every run record
+# carries and the key the readers already use — and every figure then skips it,
+# with the count and the reasons printed. A void that names no run on this stream
+# is refused: it would be a claim about nothing. It is deliberately NOT a delete:
+# both records stay, and a reader can see what was corrected and why.
+if [[ "$1" == "--void-run" ]]; then
+  VCMD="$2"; VSTART="$3"; VWHY="$4"
+  if [[ -z "$VCMD" || -z "$VSTART" || -z "$VWHY" ]]; then
+    echo "tf-emit: --void-run needs <cmd> <started> \"<reason>\""
+    exit 0
+  fi
+  VREC="$(python3 - "$MET_DIR/runs.jsonl" "$VCMD" "$VSTART" "$VWHY" 2>"$TF_ERR" <<'PY' || true
+import json, sys
+path, cmd, started, why = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
+target, voided, app = None, False, None
+try:
+    with open(path, encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                r = json.loads(line)
+            except Exception:
+                continue
+            if r.get("cmd") == cmd and r.get("started") == started:
+                if r.get("kind") == "run-void":
+                    voided = True
+                elif r.get("kind", "run") == "run":
+                    target = r
+                    app = r.get("app")
+except FileNotFoundError:
+    pass
+
+if target is None:
+    print("REFUSED no run record %s started %s on this stream" % (cmd, started)); raise SystemExit(0)
+if voided:
+    print("REFUSED %s started %s is already voided — one void is enough" % (cmd, started)); raise SystemExit(0)
+if not why.strip():
+    print("REFUSED a void needs a reason a reader can check"); raise SystemExit(0)
+
+print("OK " + json.dumps({"kind": "run-void", "app": app, "cmd": cmd,
+                          "started": started, "reason": why.strip()},
+                         separators=(",", ":"), ensure_ascii=False))
+PY
+)"
+  case "$VREC" in
+    "OK "*) printf '%s' "${VREC#OK }" | bash "${BASH_SOURCE[0]}" runs
+            echo "tf-emit: voided $VCMD started $VSTART — $VWHY"
+            echo "         both records stay on the stream; every figure now skips the run and says so" ;;
+    "REFUSED "*) echo "tf-emit: void refused — ${VREC#REFUSED }" ;;
+    *) echo "tf-emit: void could not be evaluated — nothing written" ;;
+  esac
+  exit 0
+fi
+
 # --- append path ----------------------------------------------------------
 STREAM="$1"
+# --allow-overlap: this run really did happen while another was still open (a second machine
+# appending to the same merge=union stream is the only case that has ever come up). Without it a
+# run whose `started` precedes the previous run's `ended` is refused — see _overlap_ok below.
+TF_ALLOW_OVERLAP=0
+for _a in "$@"; do [[ "$_a" == "--allow-overlap" ]] && TF_ALLOW_OVERLAP=1; done
+export TF_ALLOW_OVERLAP
 case "$STREAM" in
   runs|gates|sessions|commits|misses) ;;
   *) _warn "unknown stream '${STREAM:-<none>}' — event dropped"; exit 0 ;;
@@ -398,8 +585,8 @@ esac
 
 # The program is captured into a variable rather than fed on stdin — a heredoc
 # on `python3 -` would REPLACE the caller's piped JSON and silently drop every event.
-TF_PROG="$(cat <<'PY'
-import json, os, sys, datetime, glob, re, time
+IFS= read -r -d '' TF_PROG <<'PY' || true   # bash 3.2 misreads a here-document inside a command substitution
+import json, os, sys, datetime, glob, re, subprocess, time
 
 met_dir, stream, root = sys.argv[1], sys.argv[2], sys.argv[3]
 dbg = os.environ.get("TF_METRICS_DEBUG")
@@ -597,15 +784,41 @@ def enrich(rec):
     if rec.get("kind") == "run" and isinstance(rec.get("ended"), str):
         t_end, t_now = _iso_ms(rec["ended"]), _iso_ms(NOW)
         t_start = _iso_ms(rec["started"]) if isinstance(rec.get("started"), str) else None
-        if t_end is not None and t_now is not None and (t_end > t_now + 60_000 or (t_start is not None and t_end < t_start)):
-            sys.stdout.write("tf-emit: ended %s is not a measurement (it lies %s); set to now, %s\n"
-                             % (rec["ended"], "in the future" if t_end > t_now else "before started", NOW))
+        # Two different faults, and they must not share a remedy.
+        #
+        # (a) `ended` a little in the future: `started` is still trustworthy, so clamp to
+        #     now and re-derive (MISS-TechieFlow-20260905-11, a day-1 run wrote 17:05 at 16:40).
+        # (b) `ended` BEFORE `started`: the record contradicts itself and there is no way to
+        #     tell which of the two is wrong, so it carries NO duration at all. Deriving one
+        #     from the surviving timestamp invents a figure -- a TechieBlog record started
+        #     2026-08-22 would have been "measured" at 1,515,038 seconds on the day it was
+        #     re-emitted. An honest gap beats a plausible number: SCHEMA §2.5.
+        if t_end is not None and t_now is not None and t_start is not None and t_end < t_start:
+            sys.stdout.write("tf-emit: ended %s precedes started %s; the record contradicts "
+                             "itself, so no duration is stored\n" % (rec["ended"], rec["started"]))
+            rec["ended"] = NOW
+            rec.pop("duration_s", None)
+            rec["duration_unmeasured"] = "ended-before-started"
+        elif t_end is not None and t_now is not None and t_end > t_now + 60_000:
+            sys.stdout.write("tf-emit: ended %s is not a measurement (it lies in the future); "
+                             "set to now, %s\n" % (rec["ended"], NOW))
             rec["ended"] = NOW
             if t_start is not None and "duration_s" in rec:
                 rec["duration_s"] = max(0, (t_now - t_start) // 1000)
+        elif t_end is not None and t_start is not None and isinstance(rec.get("duration_s"), (int, float)):
+            # A supplied duration that bears no relation to its own timestamps. Thirteen of
+            # TechieBlog's fourteen impossible records hid here, storing a plausible round
+            # number (3600, 2700, 1800, 900, 600) that nothing downstream could question --
+            # only the ONE record that stored the negative arithmetic was ever detectable.
+            span = (t_end - t_start) // 1000
+            if abs(span - rec["duration_s"]) > 1:
+                sys.stdout.write("tf-emit: duration_s %s disagrees with started/ended (%ss); "
+                                 "using the timestamps\n" % (rec["duration_s"], span))
+                rec["duration_s"] = span
     # A run record that omits duration_s gets it from started and ended (the devguide and
     # refresh-status records of 2026-09-06 had none; MISS-TechieFlow-20260906-10).
-    if rec.get("kind") == "run" and "duration_s" not in rec and rec.get("started") and rec.get("ended"):
+    if rec.get("kind") == "run" and "duration_s" not in rec and rec.get("started") and rec.get("ended") \
+            and not rec.get("duration_unmeasured"):
         try:
             rec["duration_s"] = max(0, (_iso_ms(rec["ended"]) - _iso_ms(rec["started"])) // 1000)
         except Exception:
@@ -663,6 +876,52 @@ def _routing():
 
 ROUTING = _routing()
 
+# --- how a model is paid for (SCHEMA.md §2.5b, added 2026-09-10) -----------
+# One cost column cannot mean three things at once. A run on a flat-fee subscription records
+# zero marginal dollars, a run on a metered API key records real money, and a run on a local
+# model records zero because there is no bill — and until this field existed a reader could
+# not tell those three zeroes apart, so every "what did it cost" figure quietly averaged real
+# spending with free runs. The answer is resolved by tf-model-pick.sh, which reads OpenCode's
+# own auth.json and model catalog, so it is looked up and never declared by an agent — the
+# same rule as `harness` (§1) and `origin_model` (§5.5.1).
+_BILLING_CACHE = {}
+
+
+def _billing(model, harness):
+    key = (model, harness)
+    if key not in _BILLING_CACHE:
+        mode, source = "unknown", "none"
+        pick = os.path.join(root, ".tfcore", "utils", "tf-model-pick.sh")
+        if model and os.path.isfile(pick):
+            try:
+                out = subprocess.run(["bash", pick, "billing", model, harness or "claude"],
+                                     capture_output=True, text=True, timeout=20,
+                                     env=dict(os.environ, TF_PROJECT_DIR=root))
+                parts = (out.stdout or "").strip().split("\t")
+                if parts and parts[0] in ("subscription", "plan", "metered", "local", "unknown"):
+                    mode = parts[0]
+                    source = parts[1] if len(parts) > 1 else "tf-model-pick"
+            except Exception:
+                pass
+        _BILLING_CACHE[key] = (mode, source)
+    return _BILLING_CACHE[key]
+
+
+def _was_limited(model, harness, at_epoch):
+    """Did this run start while the tier's own model was parked? Then it is a deliberate
+    fallback, not routing drift, and `routed:false` should not be read as one."""
+    pick = os.path.join(root, ".tfcore", "utils", "tf-model-pick.sh")
+    if not model or not os.path.isfile(pick) or at_epoch is None:
+        return False
+    try:
+        out = subprocess.run(["bash", pick, "was-limited", harness or "claude", model, str(int(at_epoch))],
+                             capture_output=True, text=True, timeout=20,
+                             env=dict(os.environ, TF_PROJECT_DIR=root))
+        return out.returncode == 0
+    except Exception:
+        return False
+
+
 def _iso_ms(s):
     try:
         return int(datetime.datetime.strptime(
@@ -836,6 +1095,104 @@ def _prior_runs():
             pass
     return _PRIOR_RUNS
 
+# --- a run may not start before the last one finished (FR-72, 2026-09-10) --
+# `--void-run` (§2.7) gave a way to CORRECT a run record written with a start time nobody
+# measured. Nothing refused one, so the same mistake happened twice more the day the correction
+# mechanism shipped — two records whose `started` preceded the previous record's `ended`, one by
+# 42 minutes and one by nearly three hours, each silently adding that overlap to every total
+# (MISS-TechieFlow-20260910-04, sorted `ignored`: it was written down and not followed).
+#
+# A stream is append-only, so the only place to stop it is before the write. The rule: for one
+# app, a live `run` record's window may not OVERLAP another live `run` record's window. It is the
+# windows that are compared, not the order of writing: a command that chains another one inside
+# itself -- *build-phase chaining *verify -- finishes last but did its own first segment before the
+# inner run started, and comparing against the newest record alone meant that segment could never be
+# recorded at all (TfLens TF-040, 80 minutes and five builder clusters on no record). Two windows
+# that merely touch at a boundary do not overlap. Voided and backfilled records are ignored, which
+# is what makes the void-then-re-emit flow work. Records with no `started` are untouched.
+#
+# The one legitimate overlap is two machines appending to the same merge=union stream, so
+# `--allow-overlap` exists and the refusal message names it. It is deliberately a flag and not a
+# fallback: the mistake this refuses is easy to make and invisible afterwards.
+_LIVE = None
+
+
+def _live_windows(app):
+    """[(started, ended, cmd)] of every live run record for this app, oldest first."""
+    global _LIVE
+    if _LIVE is None:
+        _LIVE = {}
+        voided = set()
+        rows = []
+        try:
+            with open(os.path.join(met_dir, "runs.jsonl"), encoding="utf-8") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        r = json.loads(line)
+                    except Exception:
+                        continue
+                    if r.get("kind") == "run-void":
+                        voided.add((r.get("app"), r.get("cmd"), r.get("started")))
+                    elif r.get("kind", "run") == "run" and not r.get("backfilled"):
+                        rows.append(r)
+        except Exception:
+            pass
+        for r in rows:
+            if (r.get("app"), r.get("cmd"), r.get("started")) in voided:
+                continue
+            start = r.get("started")
+            if not start:
+                continue
+            # `ended` ONLY. `ts` is when the record was WRITTEN, not when the run finished, so
+            # falling back to it would make every historical record emitted today look like an
+            # overlap with the record written a second ago. A run with no `ended` has no window
+            # and constrains nothing.
+            #
+            # And only a record whose window is COHERENT: a self-contradicting one (ended before
+            # started) has its `ended` replaced with the write time by the check above, and
+            # marked by a null `duration_s`. That placeholder is not a measurement, so it must
+            # not become a boundary — it would block every later record for the same app.
+            if not isinstance(r.get("duration_s"), (int, float)):
+                continue
+            end = r.get("ended")
+            if not end:
+                continue
+            _LIVE.setdefault(r.get("app"), []).append((start, end, r.get("cmd")))
+    return _LIVE.get(app, [])
+
+
+def _overlap_ok(rec):
+    """False (and the reason printed) when this run's window overlaps a live one's."""
+    if stream != "runs" or rec.get("kind", "run") != "run" or rec.get("backfilled"):
+        return True
+    if os.environ.get("TF_ALLOW_OVERLAP") == "1":
+        return True
+    started, ended = rec.get("started"), rec.get("ended")
+    if not started:
+        return True
+    def key(v):
+        k = _iso_ms(v)
+        return k if k is not None else v      # unparseable: compare as strings, as before
+    s, e = key(started), key(ended or started)
+    for (ps, pe, pcmd) in _live_windows(rec.get("app")):
+        a, b = key(ps), key(pe)
+        if type(a) is not type(s) or type(b) is not type(e):
+            continue
+        if s < b and a < e:                   # windows that only touch at a boundary are fine
+            sys.stdout.write(
+                "tf-emit: REFUSED — this run (%s to %s) overlaps the %s run of %s already on the "
+                "stream (%s to %s). Every total over the two would be that much too big. Record the "
+                "part that did not overlap -- a command that chained another one records its own "
+                "segment before the inner run started -- or pass --allow-overlap if they really did "
+                "run at the same time (a second machine on the same stream). Nothing was appended.\n"
+                % (started, ended or "now", pcmd, rec.get("app"), ps, pe))
+            return False
+    return True
+
+
 def stamp_attempt(rec):
     if stream != "runs" or "attempt" in rec or rec.get("backfilled"):
         return rec
@@ -901,8 +1258,21 @@ def enrich_run(rec):
                 rec["tokens_out_subagents"] = win.get("sub_out", 0)
                 if rec.get("tier_model") and rec.get("model"):
                     rec["routed"] = rec["model"] == rec["tier_model"]
+                # What a cost figure from this window MEANS. Several models in one window may
+                # be paid for differently — a fallback from a subscription to a metered key is
+                # exactly that case — so a mixed window says so rather than picking a winner.
+                modes = {_billing(m, HARNESS)[0] for m in models} or {_billing(rec.get("model"), HARNESS)[0]}
+                rec["billing_mode"] = modes.pop() if len(modes) == 1 else "mixed"
+                rec["cost_source"] = "opencode-db" if HARNESS == "opencode" else "none"
+                # `routed:false` because the tier model was out of quota is a different fact from
+                # `routed:false` because something drifted. Only the first names a model here.
+                tm = rec.get("tier_model")
+                if tm and rec.get("model") and rec["model"] != tm and _was_limited(tm, HARNESS, t0 / 1000.0):
+                    rec["fallback_from"] = tm
             else:
                 rec["tokens_scope"] = "none"
+                rec["billing_mode"] = _billing(rec.get("tier_model"), HARNESS)[0]
+                rec["cost_source"] = "none"
     except Exception as e:
         warn("run enrichment failed (%s) — record kept unenriched" % e)
     return rec
@@ -970,7 +1340,7 @@ def _runs_by_start():
     return _RUNS_BY_START
 
 _COST_FIELDS = ("tokens_in", "tokens_out", "tokens_cache_read", "tokens_cache_write",
-                "cost_usd", "tokens_scope", "model")
+                "cost_usd", "tokens_scope", "model", "billing_mode", "cost_source")
 
 # Kept identical to the --amend branch above. Two doors, ONE enforcement: an
 # agent that hand-writes a miss-amend record onto the stream faces the same
@@ -982,13 +1352,21 @@ _AMENDABLE = {
                    "dependency-not-declared", "instruction-ignored", "other"),
     "sort": ("spec", "unsaid", "weak-check", "ignored"),
 }
+_AMENDABLE_TEXT = ("what",)   # free text, guarded by the never-overwrite rule (see --amend)
 
 def _amend_ok(rec):
     """True when this miss-amend may be appended. Returning False DROPS it —
     an invalid amend writes nothing rather than landing as a record the reader
     then has to defend itself against."""
     mid, fld, val = rec.get("miss_id"), rec.get("field"), rec.get("value")
-    if fld not in _AMENDABLE or val not in _AMENDABLE[fld] or not mid:
+    if not mid:
+        warn("amend refused — no miss_id")
+        return False
+    if fld in _AMENDABLE_TEXT:
+        if not isinstance(val, str) or not val.strip():
+            warn("amend refused — %s must be a non-empty sentence" % fld)
+            return False
+    elif fld not in _AMENDABLE or val not in _AMENDABLE[fld]:
         warn("amend refused — %r/%r outside the §5.5.7 allowlist" % (fld, val))
         return False
     parent, current = None, None
@@ -1084,12 +1462,19 @@ _ALLOWED = {
                       "subagents", "files_written", "build_result", "tier", "tier_model", "model", "models",
                       "routed", "tokens_in", "tokens_out", "tokens_cache_read", "tokens_cache_write",
                       "cost_usd", "tokens_scope", "attempt", "subagent_runs", "tokens_out_subagents",
-                      "model_tokens_out", "session_id", "usage_start_event_ts", "usage_end_event_ts"},
+                      "model_tokens_out", "session_id", "usage_start_event_ts", "usage_end_event_ts",
+                      "billing_mode", "cost_source", "fallback_from"},
+    # A correction, not a deletion: it names a run record that is wrong by the pair every
+    # run carries (`cmd` + `started`) and says why, so every figure can skip it while the
+    # record itself stays where it is. Written by --void-run, which refuses one that names
+    # no run. SCHEMA.md §2.7; tests/regression/run.sh tf_void.
+    ("runs", "run-void"): {"cmd", "started", "reason"},
     ("gates", "gate"): {"run_id", "req_id", "req_class", "attempt", "verdict", "gate", "gates_run",
                         "failure_class", "prior_verdict", "proof", "escaped", "phase", "result", "detail", "at",
                         "tier", "tier_model", "model", "models", "tokens_in", "tokens_out", "tokens_cache_read",
                         "tokens_cache_write", "cost_usd", "tokens_scope", "model_tokens_out", "routed",
-                        "subagent_runs", "tokens_out_subagents", "session_id"},
+                        "subagent_runs", "tokens_out_subagents", "session_id",
+                        "billing_mode", "cost_source", "fallback_from"},
     ("sessions", "session"): {"session_id", "model", "duration_s", "input_tokens", "output_tokens",
                               "cache_read_tokens", "cache_creation_tokens", "cost_usd", "children_sessions"},
     ("commits", "commit"): {"sha", "files", "insertions", "deletions", "subject_prefix", "branch"},
@@ -1099,8 +1484,11 @@ _ALLOWED = {
                          "what", "sort"},
     ("misses", "miss-fix"): {"miss_id", "req_id", "fix_run_id", "fix_cmd", "fix_attempt", "verdict_after",
                              "reopened", "cost_attribution", "tokens_in", "tokens_out", "tokens_cache_read",
-                             "tokens_cache_write", "cost_usd", "tokens_scope", "model"},
+                             "tokens_cache_write", "cost_usd", "tokens_scope", "model",
+                             "billing_mode", "cost_source"},
     ("misses", "miss-amend"): {"miss_id", "field", "value"},
+    # a miss that should never have been written, withdrawn by --void-miss (SCHEMA.md §5.5.11)
+    ("misses", "miss-void"): {"miss_id", "reason"},
     # an owner review of a phase's output (FR-36, built 2026-09-06): how many corrections were
     # given, what producing the reviewed output cost, what applying the corrections cost. The two
     # costs are copied from the runs named by reviewed_run_id and correction_run_id (their `started`).
@@ -1111,7 +1499,8 @@ _ALLOWED = {
 # Fields the emitter derives for runs/gates: a caller's value is discarded.
 _DERIVED = ("harness", "tier", "tier_model", "model", "models", "model_tokens_out", "routed",
             "tokens_in", "tokens_out", "tokens_cache_read", "tokens_cache_write", "cost_usd",
-            "tokens_scope", "subagent_runs", "tokens_out_subagents")
+            "tokens_scope", "subagent_runs", "tokens_out_subagents",
+            "billing_mode", "cost_source", "fallback_from")
 
 
 def _shape_ok(rec):
@@ -1231,7 +1620,12 @@ lines = []
 for rec in records:
     if not _shape_ok(rec):
         continue
-    out = enrich_miss(enrich_run(stamp_attempt(enrich(rec))))
+    # enrich() first, because it is what fills `app` when the caller left it out — the overlap
+    # rule is per app and would otherwise compare a named run against an unnamed one.
+    base = enrich(rec)
+    if not _overlap_ok(base):
+        continue
+    out = enrich_miss(enrich_run(stamp_attempt(base)))
     if out is None:                 # a refused miss-amend (§5.5.7) — dropped, never appended
         continue
     line = json.dumps(out, separators=(",", ":"), ensure_ascii=False)
@@ -1252,12 +1646,12 @@ except Exception as e:
     warn("append failed (%s) — event dropped" % e)
     raise SystemExit(0)
 PY
-)"
 python3 -c "$TF_PROG" "$MET_DIR" "$STREAM" "$ROOT" 2>"$TF_ERR"
 
 # The readable miss list beside the record (FR-31, Session 5 2026-09-07): after any write to the
-# misses stream, docs/<App>-Misses.md and its HTML are rebuilt from the stream, so the file is
-# never older than the record. Best effort, like everything else here.
+# misses stream, docs/<App>-Misses.md is rebuilt from the stream, so the file is never older than
+# the record. Markdown only — the miss log is an agent document and is never rendered to HTML
+# (owner, 2026-09-08). Best effort, like everything else here.
 if [[ "$STREAM" == "misses" ]]; then
   python3 "$(dirname "${BASH_SOURCE[0]}")/tf-misses-md.py" --root "$ROOT" --quiet 2>"$TF_ERR" || true
 fi

package/.tfcore/utils/tf-feedback.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# tf-feedback.sh — the state of every entry in this project's upstream feedback files, and the
+# one way to mark an entry closed once its fix has been re-checked here (2026-09-11).
+#
+#   bash .tfcore/utils/tf-feedback.sh <App>                     every entry: open, fixed upstream, closed
+#   bash .tfcore/utils/tf-feedback.sh <App> --waiting           fixed upstream, not yet re-checked here
+#   bash .tfcore/utils/tf-feedback.sh <App> --close <ID> "<what you ran and what it showed>"
+#
+# Details: tf_feedback.py. Writes nothing except the one closing line --close adds.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+command -v python3 >/dev/null 2>&1 || { echo "tf-feedback: python3 is required" >&2; exit 2; }
+exec python3 "$HERE/tf_feedback.py" "$@"