loki-mode 8.99.0 → 9.1.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 v8.99.0
+# Loki Mode v9.1.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
 
 ---
 
-**v8.99.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v9.1.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-8.99.0
+9.1.0

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "8.99.0"
+__version__ = "9.1.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="8.99.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.1.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=AB32002F01ECEFDE64756E2164756E21
+//# debugId=0282E3F3DE141D2464756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "8.99.0",
+  "version": "9.1.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": "8.99.0",
+  "version": "9.1.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/baseline-pin.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""Pin one run as THE cost baseline, then resolve it later.
+
+cost-guard.py compares against a baseline receipt, but somebody has to hand-pick
+that file and keep it fresh. There is no way to say "the current main is the
+reference" and have every later PR compare against it. This is that:
+
+    tools/baseline-pin.py set <workspace>     # pin the newest receipt there
+    tools/baseline-pin.py show                # what is pinned, and is it intact
+    tools/baseline-pin.py path                # the proof path, for --baseline
+
+    tools/cost-guard.py . --max-increase-pct 10 \\
+        --baseline "$(tools/baseline-pin.py path)"
+
+WHAT MAKES A PIN WORTH TRUSTING, and why each one is a refusal rather than a
+warning:
+
+1. NEVER PIN AN UNVERIFIABLE OR UNMEASURED RUN. A baseline nobody can verify
+   makes every later comparison meaningless -- the percentage is computed
+   against a number that may have been typed in. A baseline with no measured
+   cost makes every percentage undefined. Both refuse, with DIFFERENT messages,
+   because the operator's next move differs: one means re-run the build, the
+   other means fix instrumentation. Integrity is checked FIRST: a receipt that
+   fails it has no trustworthy cost to report, so "no measured cost" would be
+   the wrong diagnosis to hand back.
+
+   Neither predicate is restated here. Integrity is verify_integrity() from
+   autonomy/lib/proof-verify.py; measurement is measured_usd() from
+   cost-guard.py, which already maps the receipt's cost.usd onto the
+   record_is_measured() key name. A second copy of either is how the rule
+   drifts.
+
+2. A PIN RECORDS WHAT IT PINNED, not just a path. The receipt's hash, the cost
+   observed at pin time, and when. A path alone silently follows a file that
+   can be edited afterwards, so "the baseline" would mean whatever that file
+   says today.
+
+   The hash is over the RAW FILE BYTES, deliberately not the canonical
+   verification-stripped digest the receipt hashes itself with. That digest is
+   blind to any edit confined to the verification block -- swap the whole block
+   and it is unchanged. For pinning, the question is "did this file change",
+   and a reordered or re-signed file IS a changed file.
+
+3. show DETECTS DRIFT SINCE PINNING and says so loudly, and `path` REFUSES to
+   emit a drifted baseline. A stale baseline that quietly drifts is worse than
+   none: composed into --baseline "$(...)" it poisons the comparison while
+   still looking like a green gate.
+
+Exit: 0 fine, 1 refused / drifted / no pin. Never an empty success.
+"""
+
+import argparse
+import glob
+import hashlib
+import importlib.util
+import json
+import os
+import sys
+import time
+
+sys.dont_write_bytecode = True
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_LIB = os.path.join(os.path.dirname(_HERE), "autonomy", "lib")
+sys.path.insert(0, _LIB)
+
+
+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
+
+
+# Hyphenated filenames, so both need the loader dance rather than an import.
+_pv = _load("proof_verify", os.path.join(_LIB, "proof-verify.py"))
+_cg = _load("cost_guard", os.path.join(_HERE, "cost-guard.py"))
+
+OK, REFUSED = 0, 1
+DEFAULT_FILE = os.path.join(".loki", "baseline.json")
+
+
+def _file_sha256(path):
+    with open(path, "rb") as handle:
+        return hashlib.sha256(handle.read()).hexdigest()
+
+
+def newest_receipt(workspace):
+    """The most recent proof.json under a workspace, or None.
+
+    Same convention as ci-gate.py: accept a workspace root or its .loki dir.
+    """
+    root = os.path.normpath(workspace)
+    if os.path.basename(root) == ".loki":
+        root = os.path.dirname(root) or "."
+    found = glob.glob(os.path.join(root, ".loki", "proofs", "*", "proof.json"))
+    return max(found, key=os.path.getmtime) if found else None
+
+
+class Refused(Exception):
+    """A refusal carrying the reason the operator needs to act on."""
+
+
+def build_pin(workspace):
+    """The pin record for a workspace, or raise Refused explaining why not."""
+    proof_path = newest_receipt(workspace)
+    if proof_path is None:
+        raise Refused(
+            "no receipt under %s/.loki/proofs/*/proof.json, so there is no run "
+            "to pin. Run a build first." % os.path.normpath(workspace))
+
+    try:
+        proof = _pv._load_proof(proof_path)
+    except Exception as exc:
+        raise Refused("receipt %s could not be read: %s" % (proof_path, exc))
+
+    verdict = _pv.verify_integrity(proof)
+    if not verdict["ok"]:
+        raise Refused(
+            "receipt %s FAILED integrity verification, so it must not become a "
+            "baseline: every later comparison would be against a number nobody "
+            "can verify.\n  %s"
+            % (proof_path,
+               "\n  ".join(verdict["reasons"] or [verdict["reason"]])))
+
+    usd = _cg.measured_usd(proof.get("cost"))
+    if usd is None:
+        raise Refused(
+            "receipt %s records NO MEASURED COST, so it must not become a "
+            "baseline: a percentage increase against an unmeasured number is "
+            "undefined. Unmeasured is not $0.00. Fix the cost instrumentation "
+            "for that run, then pin it." % proof_path)
+
+    return {
+        "pin": "loki-cost-baseline/v1",
+        "proof_path": os.path.abspath(proof_path),
+        "receipt_sha256": _file_sha256(proof_path),
+        "cost_usd": usd,
+        "pinned_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+    }
+
+
+def read_pin(pin_file):
+    """The pin record, or raise Refused. Never an empty success."""
+    if not os.path.exists(pin_file):
+        raise Refused(
+            "no baseline pinned (%s does not exist). Pin one with: "
+            "tools/baseline-pin.py set <workspace>" % pin_file)
+    try:
+        with open(pin_file, "r", encoding="utf-8") as handle:
+            rec = json.load(handle)
+    except Exception as exc:
+        raise Refused("pin file %s is unreadable: %s" % (pin_file, exc))
+    if not isinstance(rec, dict) or not rec.get("proof_path"):
+        raise Refused("pin file %s records no proof_path" % pin_file)
+    return rec
+
+
+def check_pin(rec):
+    """Re-hash the pinned receipt. Returns (state, detail).
+
+    state is "intact", "changed", or "missing".
+    """
+    path = rec["proof_path"]
+    if not os.path.exists(path):
+        return "missing", "the pinned receipt no longer exists at %s" % path
+    now = _file_sha256(path)
+    if now != rec.get("receipt_sha256"):
+        return "changed", (
+            "the pinned receipt CHANGED since it was pinned: %s\n  pinned "
+            "sha256 %s\n  current sha256 %s\n  This baseline no longer "
+            "describes the run it was pinned from. Re-pin it deliberately, or "
+            "every comparison against it is against an unknown."
+            % (path, rec.get("receipt_sha256"), now))
+    return "intact", "receipt unchanged since pinning"
+
+
+def main(argv):
+    ap = argparse.ArgumentParser(
+        description="Pin a run as the cost baseline, then resolve it later.")
+    sub = ap.add_subparsers(dest="cmd")
+
+    p_set = sub.add_parser("set", help="pin the newest receipt in a workspace")
+    p_set.add_argument("workspace")
+    p_set.add_argument("--file", default=DEFAULT_FILE)
+
+    p_show = sub.add_parser("show", help="what is pinned, and is it intact")
+    p_show.add_argument("--file", default=DEFAULT_FILE)
+    p_show.add_argument("--json", action="store_true")
+
+    p_path = sub.add_parser("path", help="the pinned proof path, for --baseline")
+    p_path.add_argument("--file", default=DEFAULT_FILE)
+
+    args = ap.parse_args(argv)
+    if not args.cmd:
+        ap.print_help(sys.stderr)
+        return REFUSED
+
+    if args.cmd == "set":
+        try:
+            rec = build_pin(args.workspace)
+        except Refused as exc:
+            sys.stderr.write("REFUSED TO PIN: %s\n" % exc)
+            return REFUSED
+        parent = os.path.dirname(os.path.abspath(args.file))
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(args.file, "w", encoding="utf-8") as handle:
+            json.dump(rec, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        sys.stderr.write(
+            "PINNED %s\n  cost $%.4f  sha256 %s\n  written to %s\n"
+            % (rec["proof_path"], rec["cost_usd"], rec["receipt_sha256"],
+               args.file))
+        return OK
+
+    try:
+        rec = read_pin(args.file)
+    except Refused as exc:
+        sys.stderr.write("NO BASELINE: %s\n" % exc)
+        return REFUSED
+
+    state, detail = check_pin(rec)
+
+    if args.cmd == "path":
+        if state != "intact":
+            sys.stderr.write("REFUSING TO EMIT BASELINE: %s\n" % detail)
+            return REFUSED
+        # ONLY the path on stdout, so this composes into --baseline "$(...)".
+        sys.stdout.write("%s\n" % rec["proof_path"])
+        return OK
+
+    if getattr(args, "json", False):
+        out = dict(rec)
+        out["state"] = state
+        out["detail"] = detail
+        sys.stdout.write(json.dumps(out, indent=2, sort_keys=True) + "\n")
+    else:
+        sys.stdout.write(
+            "baseline: %s\n  pinned at %s\n  cost at pin $%.4f\n"
+            % (rec["proof_path"], rec.get("pinned_at", "unknown"),
+               rec.get("cost_usd") or 0.0))
+    if state != "intact":
+        sys.stderr.write("BASELINE %s: %s\n" % (state.upper(), detail))
+        return REFUSED
+    sys.stderr.write("baseline INTACT: %s\n" % detail)
+    return OK
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/tools/gate-init.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""Generate the policy file and CI snippet that turn the cost gate on.
+
+WHY THIS EXISTS. The chain already works: policy-load.py validates a policy
+file, ci-gate.py enforces it, gate-report.py renders the verdict where an
+engineer will see it. Adopting it does not. A team has to hand-write a JSON
+file against a schema documented only in a validator's source, work out that
+`--as-args` is the flag that joins the first tool to the second, and compose
+three commands in the right order. That is several required steps before any
+value, which is the highest-severity adoption defect this project recognises:
+a gate nobody turns on enforces exactly as much as no gate at all.
+
+So: one command that writes the file and prints the snippet.
+
+    python3 tools/gate-init.py . --out .loki-policy.json --print-workflow
+
+THE RULE THIS FILE EXISTS TO HOLD, and the reason it is not a template dump:
+
+    NEVER INVENT A CEILING.
+
+A generator's whole appeal is that it fills in the blanks, and a cost ceiling
+is the one blank it must refuse to fill from nothing. A plausible-looking
+$5.00 in a generated file is worse than an empty one: the operator commits it,
+CI goes green, and the number enforced is one nobody chose and nobody can
+defend when it starts blocking merges. The green is the problem -- it reads as
+"reviewed and within budget" when it means "arbitrary". This repo has paid for
+that shape repeatedly, most recently a tarball assertion that passed on "6 or
+more" of 6 patterns: a check reporting a pass without having checked.
+
+So a ceiling is emitted ONLY when measured runs exist to derive it from, and
+the derivation is stated in the output. With no measured history the `max_usd`
+key is ABSENT and the operator is told, on stderr, that they must choose one.
+
+WHY ABSENT AND NOT null, WHICH IS WHAT YOU WOULD REACH FOR FIRST. Verified by
+running policy-load.py on all four candidates:
+
+    {"max_usd": null, ...}          rejected: "max_usd must be a number"
+    {"_note": "...", ...}           rejected: unknown policy key
+    {"require_receipt": false}      rejected: "enforces nothing"
+    {"require_receipt": true}       loads, exit 0
+
+JSON has no comments and policy-load rejects unknown keys, so the "you must
+choose a ceiling" note CANNOT live in the file. It goes to stderr and into the
+printed snippet, where it is at least as visible and cannot break the loader.
+The receipt requirement carries the file on its own so the emitted policy still
+enforces something rather than tripping policy-load's own vacuity check.
+
+WHY IT RUNS policy-load ON ITS OWN OUTPUT. A generator that emits a file the
+loader rejects is worse than one that emits nothing: the operator has a
+committed artifact, a passing generator, and a broken gate. Self-validation is
+a subprocess call to the real validator, never a re-implementation of its rules
+here -- a second copy of the schema is how the two drift apart, and the copy
+that drifts is always the one nobody runs.
+
+WHAT IT REFUSES TO DO. It never overwrites an existing policy without --force:
+that file is reviewed, committed, and possibly a LOWER ceiling than this tool
+would derive, so silently replacing it is a destructive act that reads as a
+routine re-run. It never writes into .github/ -- that directory is live, and a
+snippet this tool has never executed has no business landing in a real
+workflow. The snippet is labelled as a starting point for that reason.
+
+Exit: 0 policy written and validated; 1 refused (existing file, or the
+generated policy failed its own validation); 2 cannot write.
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+
+OK, REFUSED, CANNOT = 0, 1, 2
+
+DEFAULT_OUT = ".loki-policy.json"
+
+# Headroom over observed spend. A ceiling at the median blocks half of all
+# normal runs, which trains the team to bypass the gate -- the failure mode a
+# too-tight budget shares with a too-loose one is that it stops being obeyed.
+HEADROOM = 2.0
+
+# ponytail: reuse cost-history's loader and median rather than re-reading
+# JSONL here. Its honesty rules (unmeasured is null and excluded, corrupt lines
+# are counted) are the ones this derivation needs, and a second reader is how
+# they drift.
+sys.path.insert(0, _HERE)
+
+
+def _load_cost_history():
+    """cost-history.py as a module, despite the hyphen in its name."""
+    import importlib.util
+
+    sys.dont_write_bytecode = True
+    path = os.path.join(_HERE, "cost-history.py")
+    spec = importlib.util.spec_from_file_location("cost_history", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def measured_costs(workspace, history_file=None):
+    """Every measured USD figure in this workspace's history, oldest first.
+
+    Rows recorded as unmeasured carry usd=null and are EXCLUDED, never read as
+    0. A workspace whose every run failed to measure has no basis for a
+    ceiling, and averaging zeros into one would produce a $0.00 ceiling that
+    blocks every future run while looking like a real budget.
+    """
+    ch = _load_cost_history()
+    path = history_file or os.path.join(workspace, ch.DEFAULT_FILE)
+    entries, corrupt = ch.load(path)
+    if entries is None:
+        return [], 0, path
+    costs = [e["usd"] for e in entries
+             if e.get("measured") and ch._num(e.get("usd")) is not None]
+    return costs, corrupt, path
+
+
+def derive(costs):
+    """(ceiling, basis) from measured runs, or (None, why-not).
+
+    Returns None for the ceiling whenever there is nothing to derive it from.
+    That None is the product: it is what stops a number with no basis being
+    written into a file someone will commit.
+    """
+    if not costs:
+        return None, ("no measured runs in this workspace's cost history")
+    ch = _load_cost_history()
+    med = ch.median(costs)
+    if med <= 0:
+        # Every measured run summed to zero. Present records, no spend: that is
+        # a measurement gap wearing a number's clothes, and a $0.00 ceiling
+        # derived from it would block every run that ever does real work.
+        return None, ("%d measured run(s) but their median is $%.4f; a ceiling "
+                      "of zero would block every run that does real work"
+                      % (len(costs), med))
+    ceiling = round(med * HEADROOM, 2)
+    basis = ("median of %d measured run(s) = $%.4f, times %.1fx headroom"
+             % (len(costs), med, HEADROOM))
+    return ceiling, basis
+
+
+def build_policy(ceiling):
+    """The policy dict. max_usd is ABSENT, never null, when unset.
+
+    require_receipt is always true: it is the one policy that needs no measured
+    history to justify, and without it a ceiling-less policy would imply no
+    ci-gate flags at all -- which policy-load correctly rejects as a gate with
+    nothing to check.
+    """
+    policy = {"require_receipt": True}
+    if ceiling is not None:
+        policy["max_usd"] = ceiling
+    return policy
+
+
+def validate(path):
+    """Run the REAL loader on the generated file. Returns (ok, message)."""
+    proc = subprocess.run(
+        [sys.executable, os.path.join(_HERE, "policy-load.py"),
+         "--file", path, "--as-args"],
+        capture_output=True, text=True)
+    if proc.returncode != 0:
+        return False, (proc.stderr.strip() or
+                       "policy-load exited %d with no message" % proc.returncode)
+    return True, proc.stdout.strip()
+
+
+def workflow_snippet(out_path):
+    """A starting point, NOT a tested workflow. Labelled as such in the text.
+
+    This tool has never run this YAML. Calling it verified would be the same
+    manufactured confidence the gate itself exists to prevent, one layer up.
+    """
+    return """# STARTING POINT -- NOT TESTED. This tool generated this snippet but has
+# never executed it. Review it, adapt the checkout/setup steps to your repo,
+# and run it once on a branch before trusting it to block a merge.
+#
+# Add to a job in .github/workflows/<your-workflow>.yml:
+
+      - name: Cost gate
+        run: |
+          python3 tools/ci-gate.py . --json \\
+              $(python3 tools/policy-load.py --file {out} --as-args) \\
+            | python3 tools/gate-report.py --format github
+""".format(out=out_path)
+
+
+def generate(workspace, out_path, force=False, history_file=None):
+    """Write the policy. Returns a verdict dict; never overwrites silently."""
+    if os.path.exists(out_path) and not force:
+        return {"status": "exists", "exit_code": REFUSED,
+                "why": ("refusing to overwrite existing policy file %s -- it is "
+                        "reviewed and committed, and may hold a lower ceiling "
+                        "than this tool would derive. Re-run with --force to "
+                        "replace it." % out_path),
+                "policy": None, "ceiling": None, "basis": None,
+                "out": out_path}
+
+    costs, corrupt, hist_path = measured_costs(workspace, history_file)
+    ceiling, basis = derive(costs)
+    policy = build_policy(ceiling)
+
+    try:
+        parent = os.path.dirname(os.path.abspath(out_path))
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(out_path, "w", encoding="utf-8") as handle:
+            handle.write(json.dumps(policy, indent=2, sort_keys=True) + "\n")
+    except OSError as exc:
+        return {"status": "cannot_write", "exit_code": CANNOT,
+                "why": "could not write %s: %s" % (out_path, exc),
+                "policy": policy, "ceiling": ceiling, "basis": basis,
+                "out": out_path}
+
+    ok, message = validate(out_path)
+    if not ok:
+        # Generated and rejected by the real loader. Non-zero, loudly: a
+        # committed file the gate cannot load is a gate that never runs.
+        return {"status": "invalid", "exit_code": REFUSED,
+                "why": ("the generated policy failed policy-load.py: %s" % message),
+                "policy": policy, "ceiling": ceiling, "basis": basis,
+                "out": out_path}
+
+    return {"status": "written", "exit_code": OK, "why": None,
+            "policy": policy, "ceiling": ceiling, "basis": basis,
+            "out": out_path, "ci_gate_args": message,
+            "history_file": hist_path, "measured_runs": len(costs),
+            "corrupt_lines": corrupt}
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Generate a ci-gate policy file and the CI snippet that "
+                    "enforces it.")
+    ap.add_argument("workspace", nargs="?", default=".",
+                    help="workspace to derive a ceiling from; default .")
+    ap.add_argument("--out", default=DEFAULT_OUT,
+                    help="policy file to write; default %s" % DEFAULT_OUT)
+    ap.add_argument("--force", action="store_true",
+                    help="overwrite an existing policy file")
+    ap.add_argument("--print-workflow", action="store_true",
+                    dest="print_workflow",
+                    help="also print a starting-point CI snippet")
+    ap.add_argument("--history-file", default=None,
+                    help="cost history JSONL; default <workspace>/.loki/cost-history.jsonl")
+    ap.add_argument("--json", action="store_true", dest="as_json",
+                    help="emit the verdict as JSON")
+    args = ap.parse_args(argv)
+
+    verdict = generate(args.workspace, args.out, force=args.force,
+                       history_file=args.history_file)
+
+    if args.as_json:
+        print(json.dumps(verdict, indent=2, sort_keys=True))
+    elif verdict["exit_code"] != OK:
+        print("gate-init: %s" % verdict["why"], file=sys.stderr)
+    else:
+        print("wrote %s" % verdict["out"])
+        print(json.dumps(verdict["policy"], indent=2, sort_keys=True))
+        if verdict["ceiling"] is not None:
+            print("\nmax_usd = %s, derived from: %s"
+                  % (verdict["ceiling"], verdict["basis"]))
+        print("\nvalidated by policy-load.py; ci-gate args: %s"
+              % verdict.get("ci_gate_args", ""))
+
+    # OUTSIDE the format branch, deliberately. Under --json this note used to
+    # vanish entirely: the operator got "ceiling": null and a basis string that
+    # reads as a diagnostic field rather than an instruction, and a policy
+    # enforcing less than it appears to. A machine-readable format is a reason
+    # to render the warning differently, never a reason to drop it -- that is
+    # the same "looks configured, enforces nothing" shape the whole chain
+    # exists to prevent. stderr keeps stdout valid JSON for a pipe.
+    if verdict["exit_code"] == OK and verdict["ceiling"] is None:
+        print("\nNO CEILING WAS SET: %s." % verdict["basis"], file=sys.stderr)
+        print("The max_usd key is ABSENT rather than guessed. You must "
+              "choose a ceiling and add it, for example:\n"
+              '    "max_usd": 5.00\n'
+              "Record some runs first (python3 tools/cost-history.py "
+              "record <workspace>) and re-run with --force to derive one "
+              "from measured spend.", file=sys.stderr)
+
+    if args.print_workflow and verdict["exit_code"] == OK:
+        print()
+        print(workflow_snippet(verdict["out"]))
+
+    return verdict["exit_code"]
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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())