loki-mode 9.0.0 → 9.2.0

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v9.0.0
+# Loki Mode v9.2.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -469,4 +469,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v9.0.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v9.2.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-9.0.0
+9.2.0

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "9.0.0"
+__version__ = "9.2.0"
 
 # Expose the control app for easy import
 try:

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var m_=Object.create;var{getPrototypeOf:u_,defineProperty:eK,getOwnPropertyNames:p_}=Object;var d_=Object.prototype.hasOwnProperty;function c_(Z){return this[Z]}var l_,i_,a_=(Z,X,Q)=>{var Y=Z!=null&&typeof Z==="object";if(Y){var J=X?l_??=new WeakMap:i_??=new WeakMap,z=J.get(Z);if(z)return z}Q=Z!=null?m_(u_(Z)):{};let K=X||!Z||!Z.__esModule?eK(Q,"default",{value:Z,enumerable:!0}):Q;for(let $ of p_(Z))if(!d_.call(K,$))eK(K,$,{get:c_.bind(Z,$),enumerable:!0});if(Y)J.set(Z,K);return K};var HQ=(Z,X)=>()=>(X||Z((X={exports:{}}).exports,X),X.exports);var s_=(Z)=>Z;function n_(Z,X){this[Z]=s_.bind(null,X)}var l0=(Z,X)=>{for(var Q in X)eK(Z,Q,{get:X[Q],enumerable:!0,configurable:!0,set:n_.bind(X,Q)})};var p=(Z,X)=>()=>(Z&&(X=Z(Z=0)),X);var e0=import.meta.require;var kO={};l0(kO,{lokiDir:()=>j0,homeLokiDir:()=>R4,findRepoRootForVersion:()=>X$,REPO_ROOT:()=>i0});import{resolve as n7,dirname as Z$}from"path";import{fileURLToPath as o_}from"url";import{existsSync as UQ}from"fs";import{homedir as r_}from"os";function t_(){let Z=RO;for(let X=0;X<6;X++){if(UQ(n7(Z,"VERSION"))&&UQ(n7(Z,"autonomy/run.sh")))return Z;let Q=Z$(Z);if(Q===Z)break;Z=Q}return n7(RO,"..","..","..")}function X$(Z){let X=Z;for(let Q=0;Q<6;Q++){if(UQ(n7(X,"VERSION"))&&UQ(n7(X,"autonomy/run.sh")))return X;let Y=Z$(X);if(Y===X)break;X=Y}return n7(Z,"..","..","..")}function j0(){return process.env.LOKI_DIR??n7(process.cwd(),".loki")}function R4(){return n7(r_(),".loki")}var RO,i0;var H8=p(()=>{RO=Z$(o_(import.meta.url));i0=t_()});import{readFileSync as e_}from"fs";import{resolve as Zf,dirname as Xf}from"path";import{fileURLToPath as Qf}from"url";function h3(){if(h5!==null)return h5;let Z="9.0.0";if(typeof Z==="string"&&Z.length>0)return h5=Z,h5;try{let X=Xf(Qf(import.meta.url)),Q=X$(X);h5=e_(Zf(Q,"VERSION"),"utf-8").trim()}catch{h5="unknown"}return h5}var h5=null;var BQ=p(()=>{H8()});var bO={};l0(bO,{runOrThrow:()=>jf,run:()=>E0,readStreamCapped:()=>NQ,commandVersion:()=>Tf,commandExists:()=>X9,ShellError:()=>Q$,MAX_STDOUT_BYTES:()=>yO});async function NQ(Z,X=yO){let Q=Z.getReader(),Y=new TextDecoder,J="",z=0;try{while(z<X){let{done:K,value:$}=await Q.read();if(K)break;if(!$)continue;if(z+=$.byteLength,z>X){let W=$.byteLength-(z-X);J+=Y.decode($.subarray(0,W),{stream:!0});break}J+=Y.decode($,{stream:!0})}J+=Y.decode()}finally{try{await Q.cancel()}catch{}Q.releaseLock()}return J}async function E0(Z,X={}){let Q=Bun.spawn({cmd:[...Z],stdout:"pipe",stderr:"pipe",env:X.env?{...process.env,...X.env}:process.env,cwd:X.cwd}),Y,J;if(X.timeoutMs&&X.timeoutMs>0)Y=setTimeout(()=>{try{Q.kill("SIGTERM")}catch{}J=setTimeout(()=>{try{Q.kill("SIGKILL")}catch{}},2000)},X.timeoutMs);try{let[z,K,$]=await Promise.all([NQ(Q.stdout),new Response(Q.stderr).text(),Q.exited]);return{stdout:z,stderr:K,exitCode:$}}finally{if(Y)clearTimeout(Y);if(J)clearTimeout(J)}}async function jf(Z,X={}){let Q=await E0(Z,X);if(Q.exitCode!==0)throw new Q$(`command failed (${Q.exitCode}): ${Z.join(" ")}`,Q.exitCode,Q.stdout,Q.stderr);return Q}async function X9(Z){let X=Mf(Z),Q=await E0(["sh","-c",`command -v ${X}`],{timeoutMs:5000});if(Q.exitCode===0)return Q.stdout.trim()||null;return null}function Mf(Z){if(!/^[A-Za-z0-9._/-]+$/.test(Z))throw Error(`refused to shell-escape suspect token: ${Z}`);return Z}async function Tf(Z,X="--version"){if(!await X9(Z))return null;let Y=await E0([Z,X],{timeoutMs:5000});if(Y.exitCode!==0)return null;return((Y.stdout||Y.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var yO=16777216,Q$;var x9=p(()=>{Q$=class Q$ extends Error{message;exitCode;stdout;stderr;constructor(Z,X,Q,Y){super(Z);this.message=Z;this.exitCode=X;this.stdout=Q;this.stderr=Y;this.name="ShellError"}}});function o7(Z){return wf?"":Z}var wf,L0,F8,p0,zV0,a0,W8,Q9,v;var S6=p(()=>{wf=(process.env.NO_COLOR??"").length>0;L0=o7("\x1B[0;31m"),F8=o7("\x1B[0;32m"),p0=o7("\x1B[1;33m"),zV0=o7("\x1B[0;34m"),a0=o7("\x1B[0;36m"),W8=o7("\x1B[1m"),Q9=o7("\x1B[2m"),v=o7("\x1B[0m")});import{existsSync as bf}from"fs";async function E7(){if(x4!==void 0)return x4;let Z="/opt/homebrew/bin/python3.12";if(bf(Z))return x4=Z,Z;let X=await X9("python3.12");if(X)return x4=X,X;let Q=await X9("python3");return x4=Q,Q}async function Y7(Z,X={}){let Q=await E7();if(!Q)return{stdout:"",stderr:"python3 not found",exitCode:127};return E0([Q,"-c",Z],X)}var x4;var r7=p(()=>{x9()});var ZL={};l0(ZL,{runStatus:()=>Kh});import{existsSync as Y9,readFileSync as g3,readdirSync as iO,statSync as aO}from"fs";import{resolve as h8,basename as rf}from"path";import{homedir as tf}from"os";function sO(Z){let X=Math.trunc(Z);if(X>=1e6)return`${(Math.trunc(X/1e6*10)/10).toFixed(1)}M`;if(X>=1000)return`${(Math.trunc(X/1000*10)/10).toFixed(1)}K`;return String(X)}function nO(Z,X,Q){if(X===0)return null;let Y=Math.trunc(Z*100/X),J=Math.trunc(Z*LQ/X);if(J>LQ)J=LQ;let z=LQ-J,K=F8;if(Y>=80)K=L0;else if(Y>=50)K=p0;let $="=".repeat(Math.max(0,J))+" ".repeat(Math.max(0,z)),W=sO(Z),V=sO(X);return`  ${W8}${Q}${v} ${K}[${$}]${v} ${Y}% (${W} / ${V})`}async function Zh(){if(await X9("jq"))return!0;return process.stdout.write(`${L0}Error: jq is required but not installed.${v}
+var m_=Object.create;var{getPrototypeOf:u_,defineProperty:eK,getOwnPropertyNames:p_}=Object;var d_=Object.prototype.hasOwnProperty;function c_(Z){return this[Z]}var l_,i_,a_=(Z,X,Q)=>{var Y=Z!=null&&typeof Z==="object";if(Y){var J=X?l_??=new WeakMap:i_??=new WeakMap,z=J.get(Z);if(z)return z}Q=Z!=null?m_(u_(Z)):{};let K=X||!Z||!Z.__esModule?eK(Q,"default",{value:Z,enumerable:!0}):Q;for(let $ of p_(Z))if(!d_.call(K,$))eK(K,$,{get:c_.bind(Z,$),enumerable:!0});if(Y)J.set(Z,K);return K};var HQ=(Z,X)=>()=>(X||Z((X={exports:{}}).exports,X),X.exports);var s_=(Z)=>Z;function n_(Z,X){this[Z]=s_.bind(null,X)}var l0=(Z,X)=>{for(var Q in X)eK(Z,Q,{get:X[Q],enumerable:!0,configurable:!0,set:n_.bind(X,Q)})};var p=(Z,X)=>()=>(Z&&(X=Z(Z=0)),X);var e0=import.meta.require;var kO={};l0(kO,{lokiDir:()=>j0,homeLokiDir:()=>R4,findRepoRootForVersion:()=>X$,REPO_ROOT:()=>i0});import{resolve as n7,dirname as Z$}from"path";import{fileURLToPath as o_}from"url";import{existsSync as UQ}from"fs";import{homedir as r_}from"os";function t_(){let Z=RO;for(let X=0;X<6;X++){if(UQ(n7(Z,"VERSION"))&&UQ(n7(Z,"autonomy/run.sh")))return Z;let Q=Z$(Z);if(Q===Z)break;Z=Q}return n7(RO,"..","..","..")}function X$(Z){let X=Z;for(let Q=0;Q<6;Q++){if(UQ(n7(X,"VERSION"))&&UQ(n7(X,"autonomy/run.sh")))return X;let Y=Z$(X);if(Y===X)break;X=Y}return n7(Z,"..","..","..")}function j0(){return process.env.LOKI_DIR??n7(process.cwd(),".loki")}function R4(){return n7(r_(),".loki")}var RO,i0;var H8=p(()=>{RO=Z$(o_(import.meta.url));i0=t_()});import{readFileSync as e_}from"fs";import{resolve as Zf,dirname as Xf}from"path";import{fileURLToPath as Qf}from"url";function h3(){if(h5!==null)return h5;let Z="9.2.0";if(typeof Z==="string"&&Z.length>0)return h5=Z,h5;try{let X=Xf(Qf(import.meta.url)),Q=X$(X);h5=e_(Zf(Q,"VERSION"),"utf-8").trim()}catch{h5="unknown"}return h5}var h5=null;var BQ=p(()=>{H8()});var bO={};l0(bO,{runOrThrow:()=>jf,run:()=>E0,readStreamCapped:()=>NQ,commandVersion:()=>Tf,commandExists:()=>X9,ShellError:()=>Q$,MAX_STDOUT_BYTES:()=>yO});async function NQ(Z,X=yO){let Q=Z.getReader(),Y=new TextDecoder,J="",z=0;try{while(z<X){let{done:K,value:$}=await Q.read();if(K)break;if(!$)continue;if(z+=$.byteLength,z>X){let W=$.byteLength-(z-X);J+=Y.decode($.subarray(0,W),{stream:!0});break}J+=Y.decode($,{stream:!0})}J+=Y.decode()}finally{try{await Q.cancel()}catch{}Q.releaseLock()}return J}async function E0(Z,X={}){let Q=Bun.spawn({cmd:[...Z],stdout:"pipe",stderr:"pipe",env:X.env?{...process.env,...X.env}:process.env,cwd:X.cwd}),Y,J;if(X.timeoutMs&&X.timeoutMs>0)Y=setTimeout(()=>{try{Q.kill("SIGTERM")}catch{}J=setTimeout(()=>{try{Q.kill("SIGKILL")}catch{}},2000)},X.timeoutMs);try{let[z,K,$]=await Promise.all([NQ(Q.stdout),new Response(Q.stderr).text(),Q.exited]);return{stdout:z,stderr:K,exitCode:$}}finally{if(Y)clearTimeout(Y);if(J)clearTimeout(J)}}async function jf(Z,X={}){let Q=await E0(Z,X);if(Q.exitCode!==0)throw new Q$(`command failed (${Q.exitCode}): ${Z.join(" ")}`,Q.exitCode,Q.stdout,Q.stderr);return Q}async function X9(Z){let X=Mf(Z),Q=await E0(["sh","-c",`command -v ${X}`],{timeoutMs:5000});if(Q.exitCode===0)return Q.stdout.trim()||null;return null}function Mf(Z){if(!/^[A-Za-z0-9._/-]+$/.test(Z))throw Error(`refused to shell-escape suspect token: ${Z}`);return Z}async function Tf(Z,X="--version"){if(!await X9(Z))return null;let Y=await E0([Z,X],{timeoutMs:5000});if(Y.exitCode!==0)return null;return((Y.stdout||Y.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var yO=16777216,Q$;var x9=p(()=>{Q$=class Q$ extends Error{message;exitCode;stdout;stderr;constructor(Z,X,Q,Y){super(Z);this.message=Z;this.exitCode=X;this.stdout=Q;this.stderr=Y;this.name="ShellError"}}});function o7(Z){return wf?"":Z}var wf,L0,F8,p0,zV0,a0,W8,Q9,v;var S6=p(()=>{wf=(process.env.NO_COLOR??"").length>0;L0=o7("\x1B[0;31m"),F8=o7("\x1B[0;32m"),p0=o7("\x1B[1;33m"),zV0=o7("\x1B[0;34m"),a0=o7("\x1B[0;36m"),W8=o7("\x1B[1m"),Q9=o7("\x1B[2m"),v=o7("\x1B[0m")});import{existsSync as bf}from"fs";async function E7(){if(x4!==void 0)return x4;let Z="/opt/homebrew/bin/python3.12";if(bf(Z))return x4=Z,Z;let X=await X9("python3.12");if(X)return x4=X,X;let Q=await X9("python3");return x4=Q,Q}async function Y7(Z,X={}){let Q=await E7();if(!Q)return{stdout:"",stderr:"python3 not found",exitCode:127};return E0([Q,"-c",Z],X)}var x4;var r7=p(()=>{x9()});var ZL={};l0(ZL,{runStatus:()=>Kh});import{existsSync as Y9,readFileSync as g3,readdirSync as iO,statSync as aO}from"fs";import{resolve as h8,basename as rf}from"path";import{homedir as tf}from"os";function sO(Z){let X=Math.trunc(Z);if(X>=1e6)return`${(Math.trunc(X/1e6*10)/10).toFixed(1)}M`;if(X>=1000)return`${(Math.trunc(X/1000*10)/10).toFixed(1)}K`;return String(X)}function nO(Z,X,Q){if(X===0)return null;let Y=Math.trunc(Z*100/X),J=Math.trunc(Z*LQ/X);if(J>LQ)J=LQ;let z=LQ-J,K=F8;if(Y>=80)K=L0;else if(Y>=50)K=p0;let $="=".repeat(Math.max(0,J))+" ".repeat(Math.max(0,z)),W=sO(Z),V=sO(X);return`  ${W8}${Q}${v} ${K}[${$}]${v} ${Y}% (${W} / ${V})`}async function Zh(){if(await X9("jq"))return!0;return process.stdout.write(`${L0}Error: jq is required but not installed.${v}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -1232,4 +1232,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}case"start":{let{runStart:Y}=await Promise.resolve().then(() => (h_(),f_));return Y(Q)}default:return process.stderr.write(`Unknown command: ${X}
 `),process.stderr.write(v_),2}}cO();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var uW0=await mW0(Bun.argv.slice(2));process.exit(uW0);
 
-//# debugId=4F7AB0182556BEE964756E2164756E21
+//# debugId=F7F47FC30C33C44064756E2164756E21

package/mcp/__init__.py

@@ -75,4 +75,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '9.0.0'
+__version__ = '9.2.0'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "9.0.0",
+  "version": "9.2.0",
   "description": "Loki Mode by Autonomi. Autonomous spec-to-product system: takes a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief to a deployed app via the RARV-C closure loop with 8 quality gates. Provider-agnostic (Claude Code, OpenAI Codex, Cline, Aider).",
   "keywords": [
     "agent",

package/plugins/loki-mode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "loki-mode",
   "displayName": "Loki Mode",
-  "version": "9.0.0",
+  "version": "9.2.0",
   "description": "Autonomous spec-to-product build system with a built-in trust layer (RARV-C closure loop, 8 quality gates, completion council). Ships Loki's spec-hardening, drift-detection, and deterministic PR verification commands plus the Loki MCP server.",
   "author": {
     "name": "Autonomi",

package/tools/estimate-run.py

@@ -332,13 +332,25 @@ def main(argv=None):
     ap.add_argument("--json", action="store_true")
     args = ap.parse_args(argv)
 
+    # A workspace that does not EXIST is not the same fact as one with no cost
+    # history, and exit 0 collapsed them. preflight.sh consumes this tool, so a
+    # mistyped or unmounted path silently became "no basis to project from"
+    # instead of an error. Same defect fixed in model-advisor.py in v8.96.0;
+    # tests/test_tool_exit_contract.py now catches the class rather than the
+    # instance.
+    if not os.path.isdir(args.workspace):
+        sys.stderr.write(
+            "cannot estimate: workspace does not exist: %s\n" % args.workspace)
+        return 66
+
     est = estimate(args.workspace, args.iterations)
     if args.json:
         print(json.dumps(est, indent=2))
     else:
         print(render(est))
-    # Exit 0 either way: "no basis" is a successful, honest answer, not a tool
-    # failure. Callers read has_basis.
+    # Exit 0 for a REAL workspace with no basis: that is a successful, honest
+    # answer rather than a tool failure, and the output says so. Callers read
+    # has_basis.
     return 0
 
 

package/tools/receipt-find.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""Find the receipts an auditor actually needs, out of a workspace full of them.
+
+WHY THIS EXISTS. receipt-bundle.py verifies EVERY receipt under a workspace and
+rolls them into one verdict. That is the right artifact to hand a compliance
+reviewer, and the wrong one to work from. An auditor with three hundred runs is
+not asking "is the archive sound"; they are asking "which run cost $40", "which
+ones did not verify", "what has happened since the incident on the 12th".
+Nothing queried receipts. This does, and the whole design problem is that a
+filter is a claim about what it did NOT return.
+
+THE RULES. Each is a specific way a result set can claim more than it earned.
+
+1. AN UNMEASURED COST MATCHES NO NUMERIC FILTER, IN EITHER DIRECTION. A receipt
+   that never recorded cost is not "under $5" and it is not "over $5" -- the
+   comparison is undefined, and answering it either way invents a measurement.
+   Treating unmeasured as 0.0 is the exact lie the cost-honesty line exists to
+   prevent (v8.51.0-v8.54.0 fixed it on four surfaces); it would make every
+   unmeasured run answer "cheapest in the archive". So unmeasured receipts are
+   EXCLUDED from a cost filter and the exclusion is COUNTED and REPORTED. An
+   auditor who asked for runs over $5 must be told the filter could not
+   consider N of them, or they will read the result as exhaustive.
+
+   The predicate is record_is_measured() in autonomy/lib/efficiency_cost.py,
+   reached through receipt-diff.py's measured_cost(), which already maps the
+   receipt's `cost.usd` onto the per-iteration `cost_usd` key it expects. A
+   second copy of that predicate is how the honesty rule drifts, so there is
+   not one here.
+
+   Measured is necessary but NOT sufficient for a cost comparison:
+   record_is_measured is true when ANY of five fields is non-zero, so a receipt
+   with tokens but a null `usd` is honestly measured and still has no dollar
+   figure. Both conditions are required -- see _usd().
+
+2. ZERO MATCHES IS A RESULT; ZERO RECEIPTS IS NOT THE SAME FACT. "The filter
+   ran and nothing qualified" and "there was nothing to search" look identical
+   in a list of zero lines, and they mean opposite things: one is a clean
+   answer, the other is a broken invocation pointed at the wrong directory.
+   They get different summaries and different exit codes.
+
+3. A MALFORMED RECEIPT IS COUNTED AND NAMED, NEVER SILENTLY SKIPPED. A search
+   that drops what it cannot read reports a tidier archive than exists, and
+   does it invisibly -- the reader sees only files that parsed and cannot tell
+   whether the rest were irrelevant or unreadable. Same rule as the bundle's:
+   absent is not clean.
+
+4. A BAD --since IS REJECTED, NOT GUESSED. An unparseable date that silently
+   matches everything (or nothing) returns a result set with no relation to the
+   question asked, and looks exactly like a correct one.
+
+5. FILTERS ARE AND, AND THE OUTPUT SAYS WHICH WERE APPLIED. A result set with
+   no visible filter line can be pasted anywhere and read as "all receipts".
+
+Usage:
+    tools/receipt-find.py [workspace] [--min-usd N] [--max-usd N]
+                          [--failed-only] [--since YYYY-MM-DD] [--json]
+
+Exit codes:
+    0  at least one receipt matched
+    1  receipts were searched, none matched (a valid result, not an error)
+    3  no receipts found at all -- nothing was searched
+    2  usage error (argparse; e.g. an unparseable --since)
+"""
+
+import argparse
+import datetime
+import importlib.util
+import json
+import pathlib
+import sys
+
+# A stale .pyc can mask a mutation and turn a real probe into a false
+# "MUTATION SURVIVED", since invalidation is mtime+size and a restore is
+# byte-identical. Set before the loader below runs.
+sys.dont_write_bytecode = True
+
+_ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+
+def _load(name, path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+# measured_cost() reuses record_is_measured() AND maps cost.usd -> cost_usd.
+# Both halves of rule 1 already live there; this file must not restate either.
+_rd = _load("receipt_diff", _ROOT / "tools" / "receipt-diff.py")
+measured_cost = _rd.measured_cost
+
+# The headline a receipt carries when the run did not verify. "VERIFIED WITH
+# GAPS" is deliberately NOT failed -- it verified, with recorded gaps -- and a
+# receipt with no headline at all is not silently treated as fine: it is
+# UNKNOWN, reported in its own bucket, and never matched by --failed-only,
+# because "we cannot tell" must not read as "it passed".
+FAILED_HEADLINE = "NOT VERIFIED"
+
+
+def _usd(proof):
+    """The receipt's cost in dollars, or None when there is no such number.
+
+    None means the comparison is UNDEFINED, and every caller must skip rather
+    than substitute a value. Returning 0.0 here would make an unmeasured run
+    the cheapest in the archive and match every --max-usd -- rule 1, and the
+    single place it is decided.
+    """
+    rec = measured_cost(proof)
+    if rec is None:
+        return None
+    return rec.get("cost_usd")
+
+
+def _headline(proof):
+    honesty = proof.get("honesty")
+    if not isinstance(honesty, dict):
+        return None
+    h = honesty.get("headline")
+    return h if isinstance(h, str) and h else None
+
+
+def _date(proof):
+    """The receipt's UTC date as YYYY-MM-DD, or None.
+
+    Sliced, not parsed. generated_at ends in "Z", which datetime.fromisoformat
+    rejects before Python 3.11, and this tool must behave identically on both
+    interpreters. ISO dates compare correctly as strings, so a slice is both
+    the portable answer and the smaller one.
+    """
+    v = proof.get("generated_at")
+    if not isinstance(v, str) or len(v) < 10:
+        return None
+    d = v[:10]
+    try:
+        datetime.date.fromisoformat(d)
+    except ValueError:
+        return None
+    return d
+
+
+def find_receipts(workspace):
+    """Every proof.json under the workspace, sorted for a stable report.
+
+    ponytail: same rglob as receipt-bundle.find_receipts, so a receipt archived
+    outside .loki/proofs/ is still findable. Deliberately not imported --
+    receipt-bundle loads proof-verify and runs git per receipt, and this tool
+    reads JSON only.
+    """
+    root = pathlib.Path(workspace)
+    if not root.is_dir():
+        return []
+    return sorted(p for p in root.rglob("proof.json") if p.is_file())
+
+
+def search(workspace, min_usd=None, max_usd=None, failed_only=False,
+           since=None):
+    """Filter receipts under `workspace`. Pure: no writes, no network.
+
+    Filters AND together (rule 5). A receipt excluded by the cost filter for
+    being unmeasured is counted in `excluded_unmeasured` -- but only when a
+    cost filter was actually applied, since without one nothing excluded it and
+    reporting an exclusion would imply a filter it never faced.
+    """
+    cost_filtered = min_usd is not None or max_usd is not None
+    paths = find_receipts(workspace)
+
+    matches = []
+    malformed = []
+    excluded_unmeasured = 0
+
+    for path in paths:
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                proof = json.load(f)
+            if not isinstance(proof, dict):
+                raise ValueError("receipt is not a JSON object")
+        except Exception as exc:
+            # Rule 3: counted and named, with the reason. Never skipped.
+            malformed.append({"path": str(path), "reason": str(exc)})
+            continue
+
+        why = []
+
+        if cost_filtered:
+            usd = _usd(proof)
+            if usd is None:
+                # Rule 1: undefined in BOTH directions. Not below, not above.
+                excluded_unmeasured += 1
+                continue
+            if min_usd is not None and usd < min_usd:
+                continue
+            if max_usd is not None and usd > max_usd:
+                continue
+            why.append("cost.usd=%s" % usd)
+
+        headline = _headline(proof)
+        if failed_only:
+            if headline != FAILED_HEADLINE:
+                continue
+            why.append("honesty.headline=%s" % headline)
+
+        date = _date(proof)
+        if since is not None:
+            if date is None or date < since:
+                continue
+            why.append("generated_at=%s" % date)
+
+        matches.append({
+            "path": str(path),
+            "matched": why,
+            "cost_usd": _usd(proof),
+            "headline": headline,
+            "date": date,
+        })
+
+    return {
+        "report": "loki-receipt-find/v1",
+        "workspace": str(workspace),
+        "filters": _filters(min_usd, max_usd, failed_only, since),
+        "matches": matches,
+        "match_count": len(matches),
+        "scanned": len(paths),
+        "malformed": malformed,
+        "malformed_count": len(malformed),
+        "excluded_unmeasured": excluded_unmeasured,
+        "summary": _summary(len(paths), len(matches), len(malformed),
+                            excluded_unmeasured,
+                            _filters(min_usd, max_usd, failed_only, since)),
+    }
+
+
+def _filters(min_usd, max_usd, failed_only, since):
+    """The applied filters, in the order they are applied.
+
+    `is not None`, never truthiness: --min-usd 0 is a real filter, and reading
+    it as "no filter" would make the output line state something untrue.
+    """
+    f = []
+    if min_usd is not None:
+        f.append("min-usd=%s" % min_usd)
+    if max_usd is not None:
+        f.append("max-usd=%s" % max_usd)
+    if failed_only:
+        f.append("failed-only")
+    if since is not None:
+        f.append("since=%s" % since)
+    return f
+
+
+def _summary(scanned, matched, malformed, excluded, filters):
+    applied = ", ".join(filters) if filters else "none (no filter applied)"
+    if scanned == 0:
+        return ("NO RECEIPTS -- no proof.json found under this workspace, so "
+                "nothing was searched. This is not the same as zero matches.")
+    if matched == 0:
+        # "found", not "searched": a malformed receipt is FOUND and counted,
+        # and the malformed line below says it was NOT searched. Saying
+        # "searched" here would contradict it in the same sentence.
+        head = ("NO MATCHES -- %d receipt(s) found, none matched. The "
+                "filter ran; the archive is not empty." % scanned)
+    else:
+        head = "%d of %d receipt(s) matched." % (matched, scanned)
+    head += " Filters applied: %s." % applied
+    if excluded:
+        head += (" %d receipt(s) EXCLUDED from the cost filter: cost was never "
+                 "measured, so it is neither above nor below the threshold."
+                 % excluded)
+    if malformed:
+        head += (" %d receipt(s) could not be read and were NOT searched."
+                 % malformed)
+    return head
+
+
+def _render(report):
+    lines = []
+    for m in report["matches"]:
+        lines.append("%s  [%s]" % (m["path"], ", ".join(m["matched"]) or "-"))
+    for bad in report["malformed"]:
+        lines.append("MALFORMED %s  (%s)" % (bad["path"], bad["reason"]))
+    lines.append("")
+    lines.append(report["summary"])
+    return "\n".join(lines)
+
+
+def _since(value):
+    """Rule 4: an unparseable --since is rejected, never guessed."""
+    try:
+        return datetime.date.fromisoformat(value).isoformat()
+    except ValueError:
+        raise argparse.ArgumentTypeError(
+            "not a YYYY-MM-DD date: %r. A date that cannot be parsed would "
+            "silently match everything or nothing." % value)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Find receipts under a workspace by measurable criteria.")
+    ap.add_argument("workspace", nargs="?", default=".",
+                    help="workspace to search for receipts (default: .)")
+    ap.add_argument("--min-usd", type=float, default=None,
+                    help="only receipts whose measured cost is >= N")
+    ap.add_argument("--max-usd", type=float, default=None,
+                    help="only receipts whose measured cost is <= N")
+    ap.add_argument("--failed-only", action="store_true",
+                    help='only receipts whose headline is "%s"'
+                         % FAILED_HEADLINE)
+    ap.add_argument("--since", type=_since, default=None,
+                    metavar="YYYY-MM-DD",
+                    help="only receipts generated on or after this UTC date")
+    ap.add_argument("--json", action="store_true",
+                    help="emit the full report as JSON")
+    args = ap.parse_args(argv)
+
+    report = search(args.workspace, min_usd=args.min_usd,
+                    max_usd=args.max_usd, failed_only=args.failed_only,
+                    since=args.since)
+
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(_render(report))
+
+    if report["scanned"] == 0:
+        return 3
+    return 0 if report["match_count"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/token-guard.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""Fail a build when a run's TOKEN usage regressed. A token gate for CI.
+
+tools/cost-guard.py gates on dollars. Dollars are a derived unit: they depend
+on a per-provider price table that changes under you, so a fixed dollar
+ceiling silently LOOSENS the moment a cheaper model is swapped in and tightens
+on a dearer one, without the work having changed at all. Tokens are the
+provider-independent unit of work actually done. Nothing gated on them.
+
+THE RULE THAT MAKES IT A GATE RATHER THAN DECORATION:
+
+    UNMEASURED IS NOT WITHIN BUDGET. Exit 2, never 0.
+
+A gate's exit code is a merge decision, and "we did not measure" carries zero
+information about budget compliance. Exit 0 is reachable from exactly ONE
+place in this file (the end of evaluate()), and only downstream of a real
+measurement. No policy, no records, unmeasured tokens: all 2.
+
+WHICH FIELDS COUNT AS MEASURED, and why it is not cost-guard's five.
+Whether a number is measured is record_is_measured() in
+autonomy/lib/efficiency_cost.py, imported and never restated. But that
+predicate is satisfied by cost OR tokens, and this gate is about tokens, so it
+is fed the FOUR TOKEN FIELDS ONLY. Feeding it cost_usd as well would be a hole
+in this specific gate: a record carrying a real cost and no usage (the exact
+shape codex wrote before v8.51.0) makes collect_efficiency return
+available=True with integer-zero token counts, and this gate would report
+"WITHIN BUDGET: 0 output tokens" for a run whose tokens were never recorded.
+Verified, not theoretical. Choosing which fields to ask about is not a second
+copy of the rule; the rule itself stays in one place.
+
+CACHED READS ARE NOT FRESH INPUT, and conflating them is the defect to avoid.
+This repo measured a single call at 10,651,759 cache-read tokens against
+34,729 output tokens: a ratio near 300 to 1. A "total" dominated by cache
+reads is a CONTEXT signal, and it moves when the prompt prefix or the cache
+hit rate changes, not when the agent does more work. So:
+
+  --max-output-tokens  the WORK signal. Output tokens alone: what the model
+                       actually generated. Reach for this by default.
+  --max-total-tokens   the CONTEXT+work signal. Sums the four fields named in
+                       TOTAL_FIELDS, cache reads included, which is what makes
+                       it big. The exact field list is PRINTED with the
+                       verdict, on pass, on fail and in JSON, because a total
+                       whose definition is not stated is not evidence.
+
+Both may be given; each is judged on its own number and either can breach.
+
+A genuinely measured ZERO under budget PASSES. Zero is falsy, so every guard
+here is an explicit `is None` check -- on the measurement AND on the policy
+arguments, since `--max-output-tokens 0` is a legitimate (harsh) policy and a
+falsy check would read it as no policy at all.
+
+Usage:
+  tools/token-guard.py [workspace] --max-output-tokens 200000
+  tools/token-guard.py [workspace] --max-total-tokens 5000000
+  tools/token-guard.py [workspace] --max-output-tokens 200000 --json
+
+Exit: 0 within budget, 1 over budget, 2 cannot evaluate.
+"""
+
+import argparse
+import json
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.join(os.path.dirname(_HERE), "autonomy", "lib"))
+
+from efficiency_cost import collect_efficiency, record_is_measured  # noqa: E402
+
+OK, OVER, CANNOT = 0, 1, 2
+
+# The four fields --max-total-tokens sums, and the SAME tuple the printed
+# definition is built from. One constant so the number and its stated meaning
+# cannot drift apart: a total that sums something other than what it claims is
+# the dishonesty this flag is most exposed to.
+TOTAL_FIELDS = ("input_tokens", "output_tokens", "cache_read_tokens",
+                "cache_creation_tokens")
+
+# Measured-ness for a TOKEN gate. cost_usd is deliberately absent; see the
+# module docstring.
+MEASURED_FIELDS = TOTAL_FIELDS
+
+TOTAL_DEFINITION = "total = " + " + ".join(TOTAL_FIELDS)
+
+
+def _num(v):
+    """A number as itself; None, "", or a bool as None.
+
+    The bool exclusion is defence in depth ONLY, and does not reach the CLI
+    path: collect_efficiency() runs _to_int() over every field first, so a
+    JSON `true` is already an int 1 by the time it arrives here. Stated
+    because an untrue claim of bool-safety is worse than a known gap; the fix
+    belongs in _to_int(), upstream. This guard still holds for a cost block
+    handed to measured_tokens() directly.
+    """
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        return None
+    return v
+
+
+def measured_tokens(cost):
+    """{field: value} for the four token fields, or None when unmeasured.
+
+    None means the run's tokens were never observed. It is NOT zero, and the
+    caller must not treat it as zero.
+    """
+    if not isinstance(cost, dict):
+        return None
+    rec = {field: _num(cost.get(field)) for field in MEASURED_FIELDS}
+    if not record_is_measured(rec):
+        return None
+    # Measured, so a None from a partially-written record is a real absence in
+    # a real measurement; count it as 0 for summing rather than poisoning the
+    # arithmetic.
+    return {field: (0 if rec[field] is None else rec[field])
+            for field in MEASURED_FIELDS}
+
+
+def _loki_dir(workspace):
+    """Accept either a workspace root or a .loki dir; collect_ wants .loki."""
+    if os.path.basename(os.path.normpath(workspace)) == ".loki":
+        return workspace
+    return os.path.join(workspace, ".loki")
+
+
+def _cannot(why):
+    return {"status": "cannot_evaluate", "exit_code": CANNOT, "why": why,
+            "output_tokens": None, "total_tokens": None, "tokens": None,
+            "total_definition": TOTAL_DEFINITION, "reason": None}
+
+
+def evaluate(workspace, max_output_tokens=None, max_total_tokens=None):
+    """Decide the gate. Returns a dict carrying exit_code and the numbers.
+
+    Every early return is CANNOT (2). The single exit-0 return is at the very
+    bottom, downstream of a measurement.
+    """
+    # `is None`, not falsy: --max-output-tokens 0 is a real policy.
+    if max_output_tokens is None and max_total_tokens is None:
+        return _cannot(
+            "no token policy given: pass --max-output-tokens and/or "
+            "--max-total-tokens. A gate with no policy checks nothing, and "
+            "must not report a pass for it.")
+
+    cost, _model = collect_efficiency(_loki_dir(workspace))
+    tokens = measured_tokens(cost)
+    if tokens is None:
+        # THE POINT OF THIS FILE. Absence is not compliance.
+        return _cannot(
+            "tokens are UNMEASURED for %s -- no efficiency record carried an "
+            "observed token count. Unmeasured is not within budget: this gate "
+            "cannot say whether the run complied, so it reports no verdict "
+            "rather than a green one." % workspace)
+
+    output = tokens["output_tokens"]
+    total = sum(tokens[field] for field in TOTAL_FIELDS)
+
+    breaches = []
+    # Tokens are integers, so a strict `>` is exact. No float tolerance: there
+    # is no binary-representation slop to absorb, and a tolerance here would
+    # silently widen the ceiling the operator asked for.
+    if max_output_tokens is not None and output > max_output_tokens:
+        breaches.append(
+            "output tokens %d exceed the ceiling %d by %d (%.1f%% over)"
+            % (output, max_output_tokens, output - max_output_tokens,
+               ((output - max_output_tokens) / max_output_tokens * 100.0)
+               if max_output_tokens else 0.0))
+
+    if max_total_tokens is not None and total > max_total_tokens:
+        breaches.append(
+            "total tokens %d exceed the ceiling %d by %d (%.1f%% over) [%s]"
+            % (total, max_total_tokens, total - max_total_tokens,
+               ((total - max_total_tokens) / max_total_tokens * 100.0)
+               if max_total_tokens else 0.0, TOTAL_DEFINITION))
+
+    verdict = {"output_tokens": output, "total_tokens": total,
+               "tokens": dict(tokens), "total_definition": TOTAL_DEFINITION,
+               "why": None}
+    if breaches:
+        verdict.update({"status": "over_budget", "exit_code": OVER,
+                        "reason": "; ".join(breaches)})
+        return verdict
+    verdict.update({"status": "within_budget", "exit_code": OK,
+                    "reason": None})
+    return verdict
+
+
+def render(d):
+    if d["status"] == "cannot_evaluate":
+        return "CANNOT EVALUATE: %s" % d["why"]
+    if d["status"] == "over_budget":
+        return "OVER BUDGET: %s" % d["reason"]
+    return ("WITHIN BUDGET: measured %d output tokens, %d total tokens [%s]"
+            % (d["output_tokens"], d["total_tokens"], d["total_definition"]))
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Fail CI when a run's token usage regressed past a "
+                    "budget policy.")
+    ap.add_argument("workspace", nargs="?", default=".",
+                    help="workspace root (or its .loki dir); default .")
+    ap.add_argument("--max-output-tokens", type=int,
+                    help="ceiling on output tokens alone (the work signal)")
+    ap.add_argument("--max-total-tokens", type=int,
+                    help="ceiling on %s (cache reads dominate this)"
+                         % TOTAL_DEFINITION)
+    ap.add_argument("--json", action="store_true", dest="as_json",
+                    help="emit the verdict as JSON")
+    args = ap.parse_args(argv)
+
+    d = evaluate(args.workspace, args.max_output_tokens, args.max_total_tokens)
+    print(json.dumps(d, indent=2) if args.as_json else render(d))
+    return d["exit_code"]
+
+
+if __name__ == "__main__":
+    sys.exit(main())