loki-mode 9.8.0 → 9.12.0

package/tools/token-tax.py

@@ -0,0 +1,375 @@
+#!/usr/bin/env python3
+"""What does verification cost in TOKENS, versus the build itself?
+
+WHY THIS EXISTS. tools/verification-tax.py measures the gate in WALL TIME and
+in how often it changed an outcome, and says in its own header that it does not
+measure token cost. docs/CAPABILITY-BACKLOG.md carries that as the open half of
+a SHIPPED-partial row ("Remaining: token cost"). This is that half.
+
+WHAT IT REPORTS, and the one thing it REFUSES.
+
+Tokens are recorded per ITERATION, in .loki/metrics/efficiency/iteration-N.json.
+Stages are recorded per STAGE, as stage_complete events carrying a name, a
+status and a duration_s. Those are the only two artifacts a run writes, and
+NEITHER attributes a token to a stage. So:
+
+    THE VERIFICATION SHARE OF TOKENS IS NOT REPORTED, BECAUSE NOTHING
+    RECORDS IT.
+
+The tempting fix is to weight each iteration's tokens by each stage's share of
+that iteration's wall clock. tools/cost-attribute.py already refused exactly
+that for dollars and named it correctly: the same invention wearing a
+defensible-looking coat, and worse than an even split precisely because a
+reader will believe it. A gate that shells out to eslint for thirty seconds
+spends no tokens; a review stage that streams three completions in ten seconds
+spends most of the iteration. Wall clock is not a token proxy.
+
+What IS measured, and is reported:
+
+  tokens per iteration      measured, unmeasured iterations excluded
+  verification stages run   counted from stage_complete, by name
+  build stages run          same, for the one stage that IS the agent
+  tokens per verification-stage-execution   the denominator is measured and
+                            the numerator is measured, but the DIVISION is
+                            only an upper bound and is labelled as one
+
+THE HONESTY RULE, which is the reason for the whole file. An iteration with no
+recorded token counts reads UNKNOWN and is EXCLUDED from every average. It is
+never averaged in as zero. Averaging absent measurements toward zero slides the
+mean toward "verification is free" -- which is the conclusion someone building
+a case for removing gates would want, reached by arithmetic rather than by
+evidence. Measured-ness is record_is_measured() in
+autonomy/lib/efficiency_cost.py, imported and never restated, fed the FOUR
+TOKEN FIELDS ONLY: a record carrying a real cost_usd and zero tokens (the shape
+codex wrote before v8.51.0) is a run whose TOKENS were never measured, and
+feeding cost_usd in would report it as "0 tokens", which is the exact lie this
+file exists to prevent.
+
+WHAT THIS IS NOT. Not a gate. A workspace whose every gate BLOCKED still exits
+0 here, because the question asked was "what did it cost", and that question
+was answered. tools/token-guard.py is the gate.
+
+Usage:
+  tools/token-tax.py [workspace] [--json]
+
+Exit: 0 reported, 2 could not check, 3 nothing to report, 64 usage error,
+66 input path missing.
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.dont_write_bytecode = True
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+# Resolved from __file__, never from the workspace argument: the workspace being
+# read is a different tree and has no autonomy/lib.
+sys.path.insert(0, os.path.join(os.path.dirname(_HERE), "autonomy", "lib"))
+
+from efficiency_cost import record_is_measured  # noqa: E402
+
+OK = 0
+COULD_NOT_CHECK = 2
+NOTHING_TO_REPORT = 3
+USAGE_ERROR = 64
+INPUT_MISSING = 66
+
+# The four token fields. cost_usd is deliberately absent; see the docstring.
+TOKEN_FIELDS = ("input_tokens", "output_tokens", "cache_read_tokens",
+                "cache_creation_tokens")
+
+# The one stage that IS the build. Every other stage emitted by
+# emit_stage_complete in autonomy/run.sh is verification or gate work.
+BUILD_STAGES = frozenset(["agent"])
+
+WHY_NO_SPLIT = (
+    "REFUSED. Tokens are recorded per ITERATION and stages are recorded per "
+    "STAGE; no artifact this repo writes attributes a token to a stage. "
+    "Weighting each iteration's tokens by a stage's share of wall clock would "
+    "look like a measurement and would not be one -- a gate shelling out to a "
+    "linter burns seconds and no tokens, while one streaming a completion "
+    "burns tokens in no time. The split becomes reportable when a writer "
+    "records per-stage usage, not before."
+)
+
+
+class _Parser(argparse.ArgumentParser):
+    """Usage errors exit 64, not argparse's default 2.
+
+    In this repo's convention 2 means "could NOT be checked" -- a real answer
+    about the subject. A mistyped flag is not that: it is an error about the
+    INVOCATION, and nothing about the subject was examined. The two call for
+    opposite responses, since retrying cannot fix a typo.
+    """
+
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        sys.stderr.write("%s: error: %s\n" % (self.prog, message))
+        raise SystemExit(USAGE_ERROR)
+
+
+def _num(v):
+    """A number as itself; None, "", or a bool as None."""
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        return None
+    return v
+
+
+def measured_tokens(rec):
+    """The four token fields summed, or None when this run never measured them.
+
+    None means UNKNOWN. The caller must not treat it as zero -- that is the
+    single property this whole file is built around.
+    """
+    if not isinstance(rec, dict):
+        return None
+    fields = {f: _num(rec.get(f)) for f in TOKEN_FIELDS}
+    if not record_is_measured(fields):
+        return None
+    # Measured, so a None in one field is a real gap inside a real measurement.
+    # Count it as 0 for summing rather than poisoning the whole record.
+    return {f: (0 if fields[f] is None else fields[f]) for f in TOKEN_FIELDS}
+
+
+def read_iterations(loki_dir):
+    """[{iteration, tokens}] for every iteration-N.json, tokens None if unmeasured.
+
+    Unreadable and non-dict records are kept with tokens=None rather than
+    dropped: a file that exists and cannot be read is an iteration that
+    happened and was not measured, which is exactly what this reports.
+    """
+    eff_dir = os.path.join(loki_dir, "metrics", "efficiency")
+    try:
+        names = sorted(os.listdir(eff_dir))
+    except OSError:
+        return []
+    out = []
+    for name in names:
+        if not (name.startswith("iteration-") and name.endswith(".json")):
+            continue
+        try:
+            n = int(name[len("iteration-"):-len(".json")])
+        except ValueError:
+            continue
+        try:
+            with open(os.path.join(eff_dir, name), "r", encoding="utf-8") as fh:
+                rec = json.load(fh)
+        except (OSError, ValueError):
+            rec = None
+        out.append({"iteration": n, "tokens": measured_tokens(rec)})
+    out.sort(key=lambda r: r["iteration"])
+    return out
+
+
+def read_stages(loki_dir):
+    """({stage: executions}, corrupt_line_count) from stage_complete events.
+
+    Corrupt lines are counted, never silently dropped: a tool that skips bad
+    lines reports a cleaner run than happened, and skips most often when
+    something upstream is broken.
+    """
+    path = os.path.join(loki_dir, "events.jsonl")
+    counts, corrupt = {}, 0
+    try:
+        fh = open(path, "r", encoding="utf-8", errors="replace")
+    except OSError:
+        return counts, corrupt
+    with fh:
+        for line in fh:
+            if not line.strip():
+                continue
+            try:
+                e = json.loads(line)
+            except ValueError:
+                corrupt += 1
+                continue
+            if not isinstance(e, dict):
+                corrupt += 1
+                continue
+            if (e.get("type") or e.get("event")) != "stage_complete":
+                continue
+            data = e.get("data") if isinstance(e.get("data"), dict) else {}
+            name = data.get("stage")
+            if name:
+                counts[str(name)] = counts.get(str(name), 0) + 1
+    return counts, corrupt
+
+
+def summarize(iterations, stages, corrupt):
+    """The report. Averages cover MEASURED iterations only, and say so."""
+    # THE EXCLUSION. One filter site, not a repeated guard: an unmeasured
+    # iteration leaves the arithmetic entirely rather than entering it as zero.
+    measured = [r for r in iterations if r["tokens"] is not None]
+    unmeasured = len(iterations) - len(measured)
+
+    totals = {f: sum(r["tokens"][f] for r in measured) for f in TOKEN_FIELDS}
+    grand = sum(totals.values()) if measured else None
+
+    verification = {k: v for k, v in stages.items() if k not in BUILD_STAGES}
+    build = {k: v for k, v in stages.items() if k in BUILD_STAGES}
+    v_execs = sum(verification.values())
+
+    # An UPPER BOUND, and labelled as one everywhere it appears: it divides ALL
+    # of a run's tokens by the verification executions, as though the build
+    # spent none. It is the largest the true figure could be, which makes it
+    # useful for bounding a claim and useless as an estimate.
+    ceiling = None
+    if grand is not None and v_execs:
+        ceiling = round(grand / v_execs, 1)
+
+    return {
+        "iterations": len(iterations),
+        "measured_iterations": len(measured),
+        "unmeasured_iterations": unmeasured,
+        "corrupt_lines": corrupt,
+        "totals": totals if measured else {f: None for f in TOKEN_FIELDS},
+        "total_tokens": grand,
+        "mean_tokens_per_measured_iteration": (
+            round(grand / len(measured), 1) if measured else None),
+        "per_iteration": [
+            {"iteration": r["iteration"],
+             "tokens": (None if r["tokens"] is None
+                        else sum(r["tokens"].values()))}
+            for r in iterations
+        ],
+        "verification_stage_executions": v_execs,
+        "verification_stages": dict(sorted(verification.items())),
+        "build_stage_executions": sum(build.values()),
+        "build_stages": dict(sorted(build.items())),
+        "verification_tokens": None,
+        "build_tokens": None,
+        "verification_token_share": None,
+        "verification_token_share_why": WHY_NO_SPLIT,
+        "tokens_per_verification_execution_upper_bound": ceiling,
+    }
+
+
+def render(s):
+    out = ["TOKEN TAX -- read from artifacts only; nothing was started and "
+           "nothing was spent.", ""]
+    out.append("  iterations         %d" % s["iterations"])
+    out.append("  measured           %d of %d"
+               % (s["measured_iterations"], s["iterations"]))
+
+    if s["measured_iterations"]:
+        out.append("  total tokens       %d" % s["total_tokens"])
+        for f in TOKEN_FIELDS:
+            out.append("    %-22s %d" % (f, s["totals"][f]))
+        out.append("  mean per measured  %.1f"
+                   % s["mean_tokens_per_measured_iteration"])
+    else:
+        out.append("  total tokens       UNKNOWN (no iteration recorded any "
+                   "token count)")
+        out.append("  mean per measured  UNKNOWN")
+
+    if s["unmeasured_iterations"]:
+        out.append("  UNMEASURED         %d iteration(s) carry no token count; "
+                   "EXCLUDED from" % s["unmeasured_iterations"])
+        out.append("                     the totals and the mean above, NOT "
+                   "counted as 0 tokens.")
+        out.append("                     The real figure is HIGHER than what "
+                   "is printed here.")
+
+    out.append("")
+    out.append("PER ITERATION")
+    out.append("-" * 60)
+    for r in s["per_iteration"]:
+        if r["tokens"] is None:
+            out.append("  iteration %-8d UNKNOWN (not measured; excluded)"
+                       % r["iteration"])
+        else:
+            out.append("  iteration %-8d %d tokens" % (r["iteration"],
+                                                       r["tokens"]))
+
+    out.append("")
+    out.append("STAGES RUN (counted, not priced)")
+    out.append("-" * 60)
+    if s["verification_stages"]:
+        for name, n in s["verification_stages"].items():
+            out.append("  verification  %-22s %d execution(s)" % (name, n))
+    else:
+        out.append("  verification  no stage_complete record -- stages not "
+                   "recorded (not 0 runs)")
+    for name, n in s["build_stages"].items():
+        out.append("  build         %-22s %d execution(s)" % (name, n))
+
+    out.append("")
+    out.append("VERIFICATION SHARE OF TOKENS")
+    out.append("-" * 60)
+    for chunk in WHY_NO_SPLIT.split(" -- "):
+        out.append("  %s" % chunk)
+    if s["tokens_per_verification_execution_upper_bound"] is not None:
+        out.append("")
+        out.append("  UPPER BOUND ONLY: %.1f tokens per verification execution "
+                   "IF the build"
+                   % s["tokens_per_verification_execution_upper_bound"])
+        out.append("  had spent none, which it did not. This bounds a claim; "
+                   "it does not estimate one.")
+
+    if s["corrupt_lines"]:
+        out.append("")
+        out.append("  CORRUPT       %d unreadable event line(s), counted not "
+                   "dropped" % s["corrupt_lines"])
+
+    out.append("")
+    if not s["measured_iterations"]:
+        out.append("  READ: token cost is UNMEASURED. No claim that "
+                   "verification is cheap or")
+        out.append("  expensive can be made from this workspace. Absence of a "
+                   "number is not a")
+        out.append("  small number.")
+    return "\n".join(out)
+
+
+def main(argv=None):
+    ap = _Parser(
+        description="Report what verification cost in TOKENS versus the "
+                    "build. Reports only; never blocks.")
+    ap.add_argument("workspace", nargs="?", default=".",
+                    help="workspace root containing .loki/ (default .)")
+    ap.add_argument("--json", action="store_true", dest="as_json",
+                    help="emit the report as JSON")
+    args = ap.parse_args(argv)
+
+    if not os.path.exists(args.workspace):
+        # 66, not COULD_NOT_CHECK. "The path you named does not exist" is a
+        # fact about the INPUT; "I could not evaluate" is a fact about the
+        # subject. A caller retrying on 2 would retry forever against a typo.
+        sys.stderr.write("token-tax: no such workspace: %s\n" % args.workspace)
+        return INPUT_MISSING
+
+    loki = args.workspace
+    if os.path.basename(os.path.normpath(loki)) != ".loki":
+        loki = os.path.join(loki, ".loki")
+    if not os.path.isdir(loki):
+        sys.stderr.write("token-tax: no .loki directory under %s; nothing to "
+                         "report\n" % args.workspace)
+        return NOTHING_TO_REPORT
+
+    try:
+        iterations = read_iterations(loki)
+        stages, corrupt = read_stages(loki)
+    except OSError as exc:
+        sys.stderr.write("token-tax: could not read %s: %s\n" % (loki, exc))
+        return COULD_NOT_CHECK
+
+    if not iterations and not stages and not corrupt:
+        sys.stderr.write("token-tax: no efficiency records and no stage "
+                         "events under %s; nothing to report\n" % loki)
+        return NOTHING_TO_REPORT
+
+    s = summarize(iterations, stages, corrupt)
+    # Records present but NONE measured is exit 0, deliberately: the question
+    # "what did this cost" was answered, and the answer is UNKNOWN. Collapsing
+    # it into NOTHING_TO_REPORT would hide the exact case this file exists for.
+    if args.as_json:
+        print(json.dumps(s, indent=2, sort_keys=True))
+    else:
+        print(render(s))
+    return OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/tool-index.py

@@ -43,6 +43,24 @@ _ROOT = os.path.dirname(_HERE)
 NO_DESC = "(no description)"
 
 
+class _Parser(argparse.ArgumentParser):
+    """Usage errors exit 64, not argparse's default 2.
+
+    In this repo's convention 2 means "could NOT be checked" -- a real
+    answer about the subject. A mistyped flag is not that: it is an error
+    about the INVOCATION, and nothing about the subject was examined. The
+    two call for opposite responses, since retrying cannot fix a typo.
+
+    argparse exits 2 for every usage error unless this is overridden, so
+    every tool needs it. tests/test_tool_exit_contract.py asserts it.
+    """
+
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        sys.stderr.write("%s: error: %s\n" % (self.prog, message))
+        raise SystemExit(64)
+
+
 def _first_sentence(text):
     """First line of a docstring or header block, trimmed.
 
@@ -162,7 +180,7 @@ def render(rows):
 
 
 def main(argv=None):
-    ap = argparse.ArgumentParser(description="List loki's bundled tools.")
+    ap = _Parser(description="List loki's bundled tools.")
     ap.add_argument("--json", action="store_true")
     ap.add_argument("--tools-dir", default=None)
     args = ap.parse_args(argv)

package/tools/verification-tax.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""What does verification COST, and how often does it change the answer?
+
+WHY THIS EXISTS. tools/gate-log.py made verdicts durable and tools/gate-trend.py
+says whether the gate is improving or going blind. Both answer questions about
+the gate's OUTPUT. Neither answers what the gate costs to run, and that is now
+the load-bearing question: verification here is adaptive scaffolding whose
+mandated trajectory is toward near-zero overhead, applied selectively where
+calibrated confidence is low and bypassed where it is high.
+
+Neither half of that mandate can be validated without a baseline. "Make it
+cheaper" needs a current cost. "Bypass it where confidence is high" needs to
+know how often running it changed an outcome at all -- because a gate that never
+changes an outcome is pure tax, and a gate that frequently does is buying
+something real. This file computes both from the log that already exists.
+
+WHAT THIS IS NOT. It is not a gate. It never blocks, never returns a
+merge-blocking exit code, and adds no new artifact format. It reads a log
+written by other tools and reports two numbers. Verification machinery is
+exactly what this must not become; it exists to make the existing machinery
+measurable so it can be shrunk or skipped.
+
+THE HONESTY RULE THIS INHERITS. A missing duration is not a duration of zero.
+Entries that carry no timing are counted and reported as UNTIMED rather than
+folded into the average as zeros, because averaging an absent measurement toward
+zero manufactures exactly the "verification is already free" conclusion this
+tool exists to test. An empty log reports NO DATA, never "0.0s, looks cheap".
+"""
+
+import argparse
+import json
+import os
+import sys
+
+# The repo-wide exit convention, enforced by tests/test_tool_exit_contract.py.
+# COULD_NOT_CHECK was 4 here, which is not in the convention at all: a CI
+# caller branching on 2 would have read "could not check" as an unrecognised
+# code and fallen through to its default arm.
+OK = 0
+COULD_NOT_CHECK = 2
+NO_DATA = 3
+USAGE_ERROR = 64
+INPUT_MISSING = 66
+
+# Keys a duration may plausibly appear under. The verify evidence doc carries
+# run_started_at/run_completed_at; a future writer may record an explicit
+# duration. Accept either rather than mandating one shape.
+DURATION_KEYS = ("duration_s", "duration_seconds", "elapsed_s")
+START_KEYS = ("run_started_at", "started_at")
+END_KEYS = ("run_completed_at", "completed_at", "ended_at")
+
+# A verdict that blocks. Anything here means the gate CHANGED the outcome:
+# without it the change would have proceeded.
+BLOCKING = {"BLOCKED", "FAIL", "FAILED", "BLOCK"}
+
+
+def _parse_iso(value):
+    """Return epoch seconds, or None. None means unknown, never zero."""
+    if not isinstance(value, str) or not value:
+        return None
+    import datetime
+    text = value.strip().replace("Z", "+00:00")
+    try:
+        return datetime.datetime.fromisoformat(text).timestamp()
+    except (ValueError, TypeError):
+        return None
+
+
+def _first(mapping, keys):
+    for key in keys:
+        if key in mapping and mapping[key] is not None:
+            return mapping[key]
+    return None
+
+
+def duration_of(entry):
+    """Seconds this verification took, or None if the entry never recorded it.
+
+    Checked in two ways because two writers exist: an explicit duration field,
+    or a start/end pair as the verify evidence document carries. A negative or
+    non-numeric result is discarded as unknown rather than trusted.
+    """
+    verdict = entry.get("verdict")
+    sources = [entry]
+    if isinstance(verdict, dict):
+        sources.append(verdict)
+        produced = verdict.get("produced_by")
+        if isinstance(produced, dict):
+            sources.append(produced)
+
+    for src in sources:
+        if not isinstance(src, dict):
+            continue
+        explicit = _first(src, DURATION_KEYS)
+        if isinstance(explicit, (int, float)) and explicit >= 0:
+            return float(explicit)
+
+    for src in sources:
+        if not isinstance(src, dict):
+            continue
+        start = _parse_iso(_first(src, START_KEYS))
+        end = _parse_iso(_first(src, END_KEYS))
+        if start is not None and end is not None and end >= start:
+            return end - start
+    return None
+
+
+def verdict_string(entry):
+    """The verdict label, wherever this writer happened to put it."""
+    verdict = entry.get("verdict")
+    if isinstance(verdict, str):
+        return verdict.upper()
+    if isinstance(verdict, dict):
+        for key in ("verdict", "status", "result"):
+            value = verdict.get(key)
+            if isinstance(value, str):
+                return value.upper()
+    category = entry.get("category")
+    return category.upper() if isinstance(category, str) else ""
+
+
+def changed_outcome(entry):
+    """Did running the gate change what would otherwise have happened?
+
+    Only a blocking verdict changes an outcome. A pass means the change would
+    have shipped either way, so the time spent verifying bought information but
+    not a different result. This is the hit rate that justifies the tax.
+    """
+    return verdict_string(entry) in BLOCKING
+
+
+def read_log(path):
+    """Every line. Corrupt lines counted, never silently dropped."""
+    entries, corrupt = [], 0
+    with open(path, "r", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except ValueError:
+                corrupt += 1
+                continue
+            if isinstance(obj, dict):
+                entries.append(obj)
+            else:
+                corrupt += 1
+    return entries, corrupt
+
+
+def summarize(entries, corrupt):
+    """Two numbers and the honesty around them.
+
+    total_s and mean_s are computed over TIMED entries only, and untimed is
+    reported alongside so a reader can see how much of the log the average
+    actually covers. An average over 2 of 200 runs is not a baseline.
+    """
+    timed = [d for d in (duration_of(e) for e in entries) if d is not None]
+    changed = sum(1 for e in entries if changed_outcome(e))
+    total = len(entries)
+    return {
+        "runs": total,
+        "timed": len(timed),
+        "untimed": total - len(timed),
+        "corrupt": corrupt,
+        "total_s": round(sum(timed), 3) if timed else None,
+        "mean_s": round(sum(timed) / len(timed), 3) if timed else None,
+        "max_s": round(max(timed), 3) if timed else None,
+        "changed_outcome": changed,
+        "hit_rate": round(changed / total, 4) if total else None,
+    }
+
+
+def render(summary):
+    lines = ["VERIFICATION TAX", ""]
+    runs = summary["runs"]
+    lines.append("  runs logged        %d" % runs)
+
+    if summary["timed"]:
+        lines.append("  timed              %d of %d" % (summary["timed"], runs))
+        lines.append("  total time         %.1fs" % summary["total_s"])
+        lines.append("  mean per run       %.2fs" % summary["mean_s"])
+        lines.append("  slowest run        %.2fs" % summary["max_s"])
+    else:
+        lines.append("  timed              0 of %d" % runs)
+        lines.append("  total time         UNKNOWN (no entry carried timing)")
+        lines.append("  mean per run       UNKNOWN")
+
+    if summary["untimed"]:
+        lines.append("  UNTIMED            %d run(s) carry no duration; excluded"
+                     % summary["untimed"])
+        lines.append("                     from the averages above, NOT counted as 0s")
+
+    lines.append("")
+    if summary["hit_rate"] is None:
+        lines.append("  outcome changed    UNKNOWN")
+    else:
+        lines.append("  outcome changed    %d of %d runs (%.1f%%)" % (
+            summary["changed_outcome"], runs, summary["hit_rate"] * 100))
+        lines.append("                     a pass would have shipped anyway; only a")
+        lines.append("                     block changed what happened")
+
+    if summary["corrupt"]:
+        lines.append("")
+        lines.append("  CORRUPT            %d unreadable line(s), counted not dropped"
+                     % summary["corrupt"])
+
+    lines.append("")
+    if summary["timed"] and summary["hit_rate"] == 0:
+        lines.append("  READ: every logged run passed. On this sample the tax bought")
+        lines.append("  information but changed no outcome -- the case for applying it")
+        lines.append("  selectively rather than universally.")
+    elif not summary["timed"]:
+        lines.append("  READ: cost is UNMEASURED. No claim that verification is cheap")
+        lines.append("  or expensive can be made from this log until writers record")
+        lines.append("  timing. Absence of a number is not a small number.")
+    return "\n".join(lines)
+
+
+class _Parser(argparse.ArgumentParser):
+    """Usage errors exit 64, not argparse's default 2.
+
+    In this repo's convention 2 means "could NOT be checked" -- a real
+    answer about the subject. A mistyped flag is not that; it is an error
+    about the INVOCATION, and reporting it as 2 tells a CI caller that the
+    axis was evaluated and found unevaluable, when in fact nothing was
+    examined at all.
+
+    argparse defaults to 2 for every usage error, so a tool that does not
+    override this silently emits the wrong code. This one did: `--bogus`
+    exited 2 and a missing positional exited 2.
+    """
+
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        sys.stderr.write("%s: error: %s\n" % (self.prog, message))
+        raise SystemExit(USAGE_ERROR)
+
+
+def main(argv=None):
+    parser = _Parser(
+        description="Measure what verification costs and how often it "
+                    "changed an outcome. Reports only; never blocks.")
+    parser.add_argument("log", help="JSONL log (e.g. from tools/gate-log.py)")
+    parser.add_argument("--json", action="store_true",
+                        help="emit the summary as JSON")
+    args = parser.parse_args(argv)
+
+    if not os.path.exists(args.log):
+        # 66, not COULD_NOT_CHECK. "The path you named does not exist" is a
+        # fact about the INPUT; "I could not evaluate" is a fact about the
+        # subject. A caller retrying on 2 would retry forever against a
+        # typo, while 66 says the argument itself is wrong.
+        sys.stderr.write("verification-tax: no such log: %s\n" % args.log)
+        return INPUT_MISSING
+    try:
+        entries, corrupt = read_log(args.log)
+    except OSError as exc:
+        sys.stderr.write("verification-tax: could not read %s: %s\n"
+                         % (args.log, exc))
+        return COULD_NOT_CHECK
+
+    if not entries and not corrupt:
+        sys.stderr.write("verification-tax: log is empty; NO DATA\n")
+        return NO_DATA
+
+    summary = summarize(entries, corrupt)
+    if args.json:
+        sys.stdout.write(json.dumps(summary, sort_keys=True, indent=2) + "\n")
+    else:
+        sys.stdout.write(render(summary) + "\n")
+    return OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())