@techierathore/techieflow 1.0.3 → 1.0.4

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

@@ -19,6 +19,10 @@
 #   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 --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,6 +274,61 @@ 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 = [], {}
+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-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 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
@@ -344,9 +403,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 +458,77 @@ PY
   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 ;;
@@ -399,7 +537,7 @@ 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
+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 +735,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 +827,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 +1046,97 @@ 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 may not begin before the last live `run` record ended. 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.
+_LAST_END = None
+
+
+def _last_live_end(app):
+    global _LAST_END
+    if _LAST_END is None:
+        _LAST_END = {}
+        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
+            # `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
+            a = r.get("app")
+            if a not in _LAST_END or end > _LAST_END[a][0]:
+                _LAST_END[a] = (end, r.get("cmd"), r.get("started"))
+    return _LAST_END.get(app)
+
+
+def _overlap_ok(rec):
+    """False (and the reason printed) when this run would start before the last one ended."""
+    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 = rec.get("started")
+    if not started:
+        return True
+    prev = _last_live_end(rec.get("app"))
+    if not prev:
+        return True
+    a, b = _iso_ms(started), _iso_ms(prev[0])
+    if a is not None and b is not None:
+        if a >= b:
+            return True
+    elif started >= prev[0]:        # unparseable timestamp: fall back to the string order
+        return True
+    sys.stdout.write(
+        "tf-emit: REFUSED — this run starts at %s, before the previous run for %s ended at %s "
+        "(%s started %s). The two would overlap and every total over them would be that much too "
+        "big. Use the previous run's `ended` as this one's `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, rec.get("app"), prev[0], prev[1], prev[2]))
+    return False
+
+
 def stamp_attempt(rec):
     if stream != "runs" or "attempt" in rec or rec.get("backfilled"):
         return rec
@@ -901,8 +1202,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 +1284,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 +1296,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 +1406,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,7 +1428,8 @@ _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"},
     # 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
@@ -1111,7 +1441,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 +1562,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)
@@ -1256,8 +1592,9 @@ 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-fix-close.sh

@@ -3,6 +3,15 @@
 #
 #   bash .tfcore/utils/tf-fix-close.sh <App> [--started <ISO>] [--reqs REQ-UI-009,REQ-FN-014]
 #                                            [--subagents trblazeui,builder] [--build pass|fail|not-run] [--files N]
+#   bash .tfcore/utils/tf-fix-close.sh <App> --misses MISS-App-20260901-06,MISS-App-20260830-03 \
+#                                            --fix-cmd amend-docs [--verdict Verified]
+#
+# The second form closes misses DIRECTLY, by id, with no checklist row and no verify ledger.
+# It exists because a miss whose deficient artifact is a document is fixed by *amend-docs
+# editing the BRD -- never by the verifier touching a row -- so the row-driven form above can
+# never reach it, and the miss stayed open forever (TF-016). It writes NO run record: the
+# amending command emits its own through the status gate. `fix_cmd: "amend-docs"` was already
+# legal in SCHEMA §5.5.2; only this door was missing.
 #
 # Emits, in this order, through tf-emit.sh only:
 #   1. the fix-issues run record (cmd fix-issues, mode fix, the rows touched) — first, because the
@@ -17,7 +26,7 @@ set -u
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 [[ $# -ge 1 && "$1" != "-h" && "$1" != "--help" ]] || { sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; exit 3; }
 APP="$1"; shift
-STARTED=""; REQS=""; SUBS=""; BUILD="pass"; FILES=""
+STARTED=""; REQS=""; SUBS=""; BUILD="pass"; FILES=""; MISSES=""; FIXCMD="fix-issues"; VERDICT=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --started) STARTED="${2:-}"; shift 2 ;;
@@ -25,11 +34,15 @@ while [[ $# -gt 0 ]]; do
     --subagents) SUBS="${2:-}"; shift 2 ;;
     --build) BUILD="${2:-}"; shift 2 ;;
     --files) FILES="${2:-}"; shift 2 ;;
+    --misses) MISSES="${2:-}"; shift 2 ;;
+    --fix-cmd) FIXCMD="${2:-}"; shift 2 ;;
+    --verdict) VERDICT="${2:-}"; shift 2 ;;
     *) echo "tf-fix-close: unknown argument $1" >&2; exit 3 ;;
   esac
 done
 [[ -z "$STARTED" ]] && STARTED="$(bash "$HERE/tf-phase.sh" show 2>/dev/null | sed -n 's/.*"started":"\([^"]*\)".*/\1/p')"
-TF_APP="$APP" TF_STARTED="$STARTED" TF_REQS="$REQS" TF_SUBS="$SUBS" TF_BUILD="$BUILD" TF_FILES="$FILES" TF_EMIT="$HERE/tf-emit.sh" python3 - <<'PY'
+TF_APP="$APP" TF_STARTED="$STARTED" TF_REQS="$REQS" TF_SUBS="$SUBS" TF_BUILD="$BUILD" TF_FILES="$FILES" \
+TF_MISSES="$MISSES" TF_FIXCMD="$FIXCMD" TF_VERDICT="$VERDICT" TF_EMIT="$HERE/tf-emit.sh" python3 - <<'PY'
 import datetime, json, os, subprocess
 EMIT = os.environ["TF_EMIT"]; app = os.environ["TF_APP"]; started = os.environ["TF_STARTED"]
 now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -39,6 +52,25 @@ def emit(stream, rec):
     msg = (p.stdout + p.stderr).strip(); ok = p.returncode == 0 and "refus" not in msg.lower() and "error" not in msg.lower()
     if not ok: print(f"  {stream}: not written — {msg.splitlines()[0][:160] if msg else 'no reason printed'}")
     return ok
+# --- close by miss id (the *amend-docs door) -------------------------------------------
+direct = [m.strip() for m in (os.environ.get("TF_MISSES") or "").split(",") if m.strip()]
+if direct:
+    fix_cmd = os.environ.get("TF_FIXCMD") or "amend-docs"
+    verdict = os.environ.get("TF_VERDICT") or "Verified"
+    closed = 0
+    for mid in direct:
+        fa = q("--next-fix-attempt", mid) or "1"
+        rec = {"kind": "miss-fix", "miss_id": mid, "fix_cmd": fix_cmd,
+               "fix_attempt": int(fa) if fa.isdigit() else 1,
+               "verdict_after": verdict, "reopened": False}
+        if started:
+            rec["fix_run_id"] = started
+        if emit("misses", rec):
+            closed += 1
+    print("%s: %d of %d miss-fix record(s) written (no run record — the amending command emits its own)"
+          % (fix_cmd, closed, len(direct)))
+    raise SystemExit(0)
+
 ledger = {}
 try:
     ledger = json.load(open(os.path.join("docs", ".last-verify.json"), encoding="utf-8"))