loki-mode 8.92.0 → 8.93.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.92.0
+# Loki Mode v8.93.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.92.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v8.93.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-8.92.0
+8.93.0

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "8.92.0"
+__version__ = "8.93.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.92.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="8.93.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=E465E6ADABBF4BDF64756E2164756E21
+//# debugId=232EF166A0E3908D64756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "8.92.0",
+  "version": "8.93.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.92.0",
+  "version": "8.93.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/model-advisor.py

@@ -0,0 +1,495 @@
+#!/usr/bin/env python3
+"""Would a cheaper model have done this job, and what would it have saved.
+
+WHY THIS EXISTS. This project has one order-of-magnitude finding from its own
+benchmark work: on SWE-bench verified, MiniMax M2.5 (open weights) scored 75.8
+against Claude Opus 4.6's 75.6, at $36.64 against $275.76 -- roughly 7.5x
+cheaper for equal-or-better quality. Separately, the HARNESS was worth about
+3.4 points on an identical model. Nothing in the product surfaces any of that
+to an operator deciding what to run. estimate-run.py answers "what will this
+cost on the model I am already using". Nothing answers "should I be using a
+different model at all".
+
+WHAT SEPARATION MAKES THIS HONEST. Two things are kept strictly apart, and
+conflating them is the failure mode this tool exists to avoid:
+
+  RATE, which we can compute. The pricing table gives USD per Mtok. Replaying
+  THIS workspace's observed token vector through another model's rates is
+  arithmetic, and the resulting ratio is a fact about prices.
+
+  QUALITY, which we cannot compute. Whether the cheaper model would have
+  produced the same result on YOUR workload is not something any cost record
+  can answer. The SWE-bench figures above are reported as a CITED EXTERNAL
+  BENCHMARK with the numbers attached, on a different workload, and they never
+  rank a candidate, never weight a recommendation, and are never phrased as a
+  promise. A ranking driven by a benchmark we did not run on your task would be
+  exactly the fabricated authority this repo has spent thirteen surfaces
+  removing.
+
+THE HONESTY RULES, inherited from the cost lineage (v8.51.0 - v8.54.0, where a
+single missing measurement became four different renderings of "$0.00"):
+
+  1. NO MEASURED BASIS MEANS NO RECOMMENDATION. Not a smaller saving, not a
+     zero -- no number at all, and the output says why. A projected saving with
+     no history behind it is an invented fact, and it is worse than an invented
+     past cost because it invites a switch.
+  2. Every projection is labelled ESTIMATE with the count of records it rests
+     on. A basis of one is stated as a basis of one.
+  3. A CHEAPER RATE IS NOT A CHEAPER RUN. Token counts differ between models: a
+     weaker model can need more iterations, longer outputs, more retries, and
+     the saving assumes comparable token usage. We cannot verify that
+     assumption from cost records alone, and the output says so in the output
+     itself, not only in this docstring.
+  4. A model absent from the pricing table reads "unpriced". Never $0, never
+     omitted silently, and never ranked -- an unpriced model with no ratio
+     cannot be claimed to be cheaper.
+
+HOW THE RATIO IS COMPUTED, and why not the obvious way. The naive form is
+candidate_input_rate / incumbent_input_rate. That is wrong here: output tokens
+cost 5x input, cache reads a tenth, and the mix varies enormously between
+workloads. So the observed token vector from the measured records is replayed
+through BOTH models' full rate cards:
+
+    ratio = modelled_candidate / modelled_incumbent
+
+then the saving scales the RECORDED cost, not the modelled one:
+
+    projected_candidate_usd = recorded_usd * ratio
+
+The ratio is dimensionless, so it cancels drift between the table and what was
+actually billed -- and sonnet is on intro pricing through 2026-08-31 per the
+table's own _source note, so that drift is real today. The saving therefore
+stays anchored to a measured number rather than to a price-card reconstruction.
+
+If the modelled incumbent cost is zero (records carry cost but no tokens), the
+ratio is undefined and we say so rather than falling back to an input-only
+ratio, which would quietly answer a different question.
+
+Usage:
+    python3 tools/model-advisor.py [WORKSPACE] [--json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import os
+import sys
+
+# ponytail: bytecode writing off before any file-based loader, so a probe that
+# mutates and restores a file cannot be served a stale .pyc of the pre-mutation
+# source.
+sys.dont_write_bytecode = True
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.dirname(_HERE)
+_LIB = os.path.join(_REPO_ROOT, "autonomy", "lib")
+if _LIB not in sys.path:
+    sys.path.insert(0, _LIB)
+
+# THE single definition of "measured". Restating it is how the honesty rule
+# drifts; the four surfaces that once rendered an unmeasured run as "$0.00"
+# each had their own idea of what counted.
+from efficiency_cost import record_is_measured  # noqa: E402
+
+# One reader of .loki/metrics/efficiency/ -- it already skips malformed records
+# rather than defaulting them to zero. cost-summary.py and estimate-run.py load
+# it exactly this way; a third copy would drift the same way a second predicate
+# would.
+_ia_spec = importlib.util.spec_from_file_location(
+    "iteration_attribution", os.path.join(_LIB, "iteration_attribution.py"))
+_ia = importlib.util.module_from_spec(_ia_spec)
+_ia_spec.loader.exec_module(_ia)
+
+# Alias-keyed: {"pricing": {"sonnet": {"input": 3.0, "output": 15.0,
+# "cache_read": 0.3, "cache_write": 3.75}}}, USD per 1M tokens. NOT the schema
+# of benchmarks/bench/prices.json (models.<x>.input_per_mtok), so this reads
+# the file directly rather than routing through price_from_tokens.
+PRICING_PATH = os.path.join(
+    _REPO_ROOT, "loki-ts", "data", "model-pricing.json")
+
+# Record token field -> pricing rate field. cache_creation is billed at the
+# write rate, which is 1.25x input and NOT the same as fresh input.
+_TOKEN_TO_RATE = (
+    ("input_tokens", "input"),
+    ("output_tokens", "output"),
+    ("cache_read_tokens", "cache_read"),
+    ("cache_creation_tokens", "cache_write"),
+)
+
+# A cited EXTERNAL benchmark on an EXTERNAL workload. Reported verbatim with
+# its numbers so a reader can weigh it; never an input to the ranking, which is
+# ordered purely by computed rate. See module docstring.
+SWEBENCH_CITATION = {
+    "benchmark": "SWE-bench verified",
+    "workload": "SWE-bench verified issues -- NOT this workspace's workload",
+    "results": [
+        {"model": "MiniMax M2.5 (open weights)", "score": 75.8,
+         "cost_usd": 36.64},
+        {"model": "Claude Opus 4.6", "score": 75.6, "cost_usd": 275.76},
+    ],
+    "harness_effect": (
+        "the harness itself was worth about 3.4 points on an identical model"),
+    "caveat": (
+        "equal-or-better score at roughly 7.5x lower cost ON THAT BENCHMARK. "
+        "It is not a measurement of your workload and does not predict that a "
+        "cheaper model would complete YOUR task"),
+}
+
+
+def _num(v):
+    """Non-bool int/float, else None. Never coerces junk to 0."""
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        return None
+    return v
+
+
+def load_pricing(path=None):
+    """Return the alias -> rates map, or {} when unreadable.
+
+    A missing table means we cannot quote any rate, which is an honest null:
+    every model then reads unpriced and no ratio is offered.
+    """
+    try:
+        with open(path or PRICING_PATH, encoding="utf-8") as handle:
+            data = json.load(handle)
+    except Exception:
+        return {}
+    pricing = data.get("pricing") if isinstance(data, dict) else None
+    return pricing if isinstance(pricing, dict) else {}
+
+
+def modelled_cost(tokens, rates):
+    """Replay an observed token vector through one model's full rate card.
+
+    Returns USD, or None when the model has no usable rates -- unpriced, which
+    must never render as 0. Rates are per 1M tokens.
+    """
+    if not isinstance(rates, dict):
+        return None
+    total = 0.0
+    priced_any = False
+    for tok_key, rate_key in _TOKEN_TO_RATE:
+        rate = _num(rates.get(rate_key))
+        if rate is None:
+            continue
+        priced_any = True
+        total += (tokens.get(tok_key, 0) / 1_000_000.0) * rate
+    # A table entry naming the model but carrying no numeric rate prices
+    # nothing. That is unpriced, not free.
+    return total if priced_any else None
+
+
+def advise(workspace=".", pricing_path=None):
+    """Build the advice dict. Pure derivation from measured records."""
+    loki_dir = os.path.join(workspace, ".loki")
+    recs = _ia._iteration_records(loki_dir)
+
+    found = len(recs)
+    measured = 0
+    priced = 0
+    recorded_usd = 0.0
+    tokens = {key: 0 for key, _ in _TOKEN_TO_RATE}
+    by_model_cost = {}
+
+    for rec in recs:
+        if not record_is_measured(rec):
+            # EXCLUDED, not summed as zero. An unmeasured iteration averaged in
+            # as 0 is indistinguishable from a real measurement of 0.
+            continue
+        measured += 1
+        usd = _num(rec.get("cost_usd"))
+        # Measured on tokens but carrying no cost is real for token accounting
+        # and useless as a COST basis. Real costs are stored raw (0.018719), so
+        # a sub-cent charge is 0.0001 and never exactly 0; an exact zero is a
+        # reliable unpriced signal. estimate-run.py draws the same line.
+        if usd is None or usd == 0:
+            continue
+        priced += 1
+        recorded_usd += float(usd)
+        for key, _ in _TOKEN_TO_RATE:
+            tokens[key] += _num(rec.get(key)) or 0
+        name = str(rec.get("model") or "").strip()
+        by_model_cost[name] = by_model_cost.get(name, 0.0) + float(usd)
+
+    pricing = load_pricing(pricing_path)
+
+    # THE INCUMBENT. Not collect_efficiency()'s last-non-empty-seen model:
+    # across mixed history that names whichever model happened to be recorded
+    # last, which is not the model the spend belongs to. Dominant by COST
+    # share, with the mix always reported.
+    incumbent = None
+    if by_model_cost:
+        named = {k: v for k, v in by_model_cost.items() if k}
+        if named:
+            incumbent = max(named, key=lambda k: named[k])
+    mixed = len([k for k in by_model_cost if k]) > 1
+
+    incumbent_rates = pricing.get(incumbent) if incumbent else None
+    incumbent_modelled = modelled_cost(tokens, incumbent_rates)
+
+    out = {
+        "workspace": os.path.abspath(workspace),
+        "label": "ESTIMATE",
+        "iterations_found": found,
+        "iterations_measured": measured,
+        "iterations_priced": priced,
+        "basis_count": priced,
+        "has_basis": priced > 0,
+        "single_point_basis": priced == 1,
+        "incumbent_model": incumbent,
+        "incumbent_priced": incumbent_rates is not None,
+        "incumbent_recorded_cost_usd": (
+            round(recorded_usd, 4) if priced else None),
+        "observed_tokens": dict(tokens) if priced else None,
+        "basis_models": sorted(k for k in by_model_cost if k),
+        "mixed_basis_models": mixed,
+        "candidates": [],
+        "best_candidate": None,
+        "swebench_citation": SWEBENCH_CITATION,
+        "assumption_verified": False,
+        "notes": [],
+    }
+
+    n = out["notes"]
+
+    # ---- THE HONESTY GUARD -------------------------------------------------
+    # No priced history means no basis, so there is no recommendation and no
+    # number. Softening this into a 0.0 saving, or into a rate-only ranking
+    # dressed as advice, is the "unmeasured becomes free" defect pointed at a
+    # purchasing decision.
+    if not out["has_basis"]:
+        out["incumbent_recorded_cost_usd"] = None
+        if found == 0:
+            n.append(
+                "NO BASIS: no iteration records in this workspace. There is no "
+                "measured history to compare models against, so no saving is "
+                "projected (not $0.00) and no model is recommended")
+        else:
+            n.append(
+                "NO BASIS: no measured, priced iteration among %d record(s). "
+                "There is no measured history to compare models against, so no "
+                "saving is projected (not $0.00) and no model is recommended"
+                % found)
+            if measured > priced:
+                n.append(
+                    "%d of %d measured record(s) carried tokens but no cost "
+                    "(unpriced): that spend is UNKNOWN rather than zero, so it "
+                    "cannot form a basis" % (measured - priced, measured))
+        n.append(
+            "run an iteration with cost recording enabled, then re-run this "
+            "tool")
+        return out
+    # ------------------------------------------------------------------------
+
+    n.append(
+        "ESTIMATE based on %d measured, priced iteration(s) of %d found -- "
+        "not a guarantee" % (priced, found))
+    if priced == 1:
+        n.append(
+            "the basis is a SINGLE data point: one observation extrapolated, "
+            "not a distribution")
+    if priced < found:
+        n.append(
+            "PARTIAL: %d of %d record(s) did not inform this comparison "
+            "(unmeasured or unpriced), and were excluded rather than counted "
+            "as zero" % (found - priced, found))
+    if mixed:
+        n.append(
+            "the basis MIXES models (%s): the incumbent below is the one with "
+            "the largest share of recorded cost, and a single ratio across "
+            "different price points may not transfer to either"
+            % ", ".join(out["basis_models"]))
+
+    if incumbent is None:
+        n.append(
+            "the priced records name no model: the incumbent is unknown, so no "
+            "rate ratio can be computed and no saving is projected")
+        return out
+
+    if incumbent_rates is None:
+        n.append(
+            "no price listed for the incumbent %s in the pricing table: it "
+            "reads UNPRICED (not $0), and without its rates no ratio against "
+            "any candidate can be computed, so no saving is projected"
+            % incumbent)
+        return out
+
+    if not incumbent_modelled:
+        # Cost recorded but no tokens (or all rates zero): the ratio's
+        # denominator is zero. Falling back to an input-rate-only ratio here
+        # would silently answer a different question.
+        n.append(
+            "the measured records carry cost but no usable token counts, so "
+            "the incumbent's modelled cost is zero and every ratio would be "
+            "undefined: no saving is projected")
+        return out
+
+    # ---- CANDIDATES --------------------------------------------------------
+    # Ordered purely by computed rate ratio. The SWE-bench citation is attached
+    # to the report as external context and deliberately does NOT rank anything.
+    for name in sorted(pricing):
+        if name == incumbent:
+            continue
+        cand_modelled = modelled_cost(tokens, pricing.get(name))
+        if cand_modelled is None:
+            # Named in the table but with no usable rate: unpriced, so it is
+            # listed as unpriced and carries no ratio and no saving.
+            out["candidates"].append({
+                "model": name, "priced": False, "rate_ratio": None,
+                "projected_cost_usd": None, "projected_saving_usd": None,
+                "cheaper": None,
+            })
+            continue
+        ratio = cand_modelled / incumbent_modelled
+        projected = recorded_usd * ratio
+        out["candidates"].append({
+            "model": name,
+            "priced": True,
+            "rate_ratio": round(ratio, 4),
+            "projected_cost_usd": round(projected, 4),
+            "projected_saving_usd": round(recorded_usd - projected, 4),
+            "cheaper": ratio < 1.0,
+        })
+
+    cheaper = [c for c in out["candidates"] if c["cheaper"]]
+    cheaper.sort(key=lambda c: c["rate_ratio"])
+    out["candidates"].sort(
+        key=lambda c: (c["rate_ratio"] is None, c["rate_ratio"]))
+
+    if cheaper:
+        out["best_candidate"] = cheaper[0]["model"]
+        n.append(
+            "%d cheaper-RATE candidate(s) found; cheapest is %s at %.2fx the "
+            "incumbent's rate on this workspace's observed token mix"
+            % (len(cheaper), cheaper[0]["model"], cheaper[0]["rate_ratio"]))
+    else:
+        # Already on the cheapest priced model. Saying "no cheaper candidate"
+        # is a real answer; an empty ranked list rendered as a saving of
+        # nothing is not.
+        n.append(
+            "no cheaper-rate candidate: %s is already the cheapest priced "
+            "model in the table for this token mix" % incumbent)
+
+    unpriced = [c["model"] for c in out["candidates"] if not c["priced"]]
+    if unpriced:
+        n.append(
+            "unpriced (no rate in the pricing table, so UNKNOWN and not $0, "
+            "and not ranked): %s" % ", ".join(unpriced))
+
+    # RULE 3, stated in the output and not only in the source. Every number
+    # above is a rate comparison holding tokens fixed; nothing here has
+    # measured a second model on this workload.
+    n.append(
+        "A CHEAPER RATE IS NOT A CHEAPER RUN. Every projection above replays "
+        "THIS run's observed token counts through another model's rates. Token "
+        "counts differ between models -- a different model may need more "
+        "iterations, longer outputs or more retries -- so the saving assumes "
+        "COMPARABLE TOKEN USAGE")
+    n.append(
+        "that assumption is NOT VERIFIED here: this workspace has no measured "
+        "run on any candidate model, so its real token usage is unknown. The "
+        "only way to verify it is to run the candidate and compare")
+    n.append(
+        "quality is NOT projected. The SWE-bench figures in this report are a "
+        "cited external benchmark on a different workload, not a prediction "
+        "about your task")
+    return out
+
+
+def _fmt_usd(v):
+    """UNKNOWN, never $0.00, when there is nothing to report."""
+    return "UNKNOWN" if v is None else "$%.4f" % v
+
+
+def _fmt_saving(v):
+    """A negative saving is EXTRA COST and must not read as one.
+
+    "$-1.6558" in a SAVING column is a number a reader skims as a saving with a
+    stray character. A more expensive model costs more; say that.
+    """
+    if v is None:
+        return "UNKNOWN"
+    return "$%.4f" % v if v >= 0 else "+$%.4f more" % abs(v)
+
+
+def render(adv):
+    """Human-readable report. The honesty lives here too, not only in the dict."""
+    lines = []
+    lines.append("Model cost advisor -- %s" % adv["workspace"])
+    lines.append("")
+
+    if not adv["has_basis"]:
+        lines.append("  NO BASIS: no measured, priced iteration in this workspace.")
+        lines.append("  Model used:          UNKNOWN")
+        lines.append("  Measured cost:       UNKNOWN")
+        lines.append("  Recommendation:      NONE -- there is no measured basis")
+        lines.append("  Projected saving:    UNKNOWN")
+        lines.append("  Records found: %d  measured: %d  priced: %d"
+                     % (adv["iterations_found"], adv["iterations_measured"],
+                        adv["iterations_priced"]))
+    else:
+        lines.append("  Model used:          %s%s" % (
+            adv["incumbent_model"] or "not recorded",
+            "" if adv["incumbent_priced"] else "  (UNPRICED)"))
+        lines.append("  Measured cost:       %s  (ESTIMATE basis: %d priced "
+                     "iteration(s) of %d found)" % (
+                         _fmt_usd(adv["incumbent_recorded_cost_usd"]),
+                         adv["basis_count"], adv["iterations_found"]))
+        lines.append("")
+        if adv["candidates"]:
+            lines.append("  Candidates (ESTIMATE, basis %d iteration(s)):"
+                         % adv["basis_count"])
+            lines.append("    %-16s %-10s %-12s %s"
+                         % ("MODEL", "RATE", "PROJECTED", "SAVING"))
+            for cand in adv["candidates"]:
+                if not cand["priced"]:
+                    lines.append("    %-16s %-10s %-12s %s" % (
+                        cand["model"], "unpriced", "unpriced", "unpriced"))
+                    continue
+                lines.append("    %-16s %-10s %-12s %s" % (
+                    cand["model"],
+                    "%.2fx" % cand["rate_ratio"],
+                    _fmt_usd(cand["projected_cost_usd"]),
+                    _fmt_saving(cand["projected_saving_usd"])))
+            lines.append("")
+        if adv["best_candidate"]:
+            lines.append("  Cheapest rate:       %s" % adv["best_candidate"])
+        else:
+            lines.append("  Cheapest rate:       none cheaper than the model "
+                         "already in use")
+
+    cite = adv["swebench_citation"]
+    lines.append("")
+    lines.append("  Cited external benchmark (%s) -- NOT a measurement of your "
+                 "workload:" % cite["benchmark"])
+    for row in cite["results"]:
+        lines.append("    %-30s score %.1f   cost $%.2f"
+                     % (row["model"], row["score"], row["cost_usd"]))
+    lines.append("    %s" % cite["harness_effect"])
+    lines.append("    %s" % cite["caveat"])
+
+    lines.append("")
+    for note in adv["notes"]:
+        lines.append("  - %s" % note)
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Recommend a cheaper model from this workspace's measured "
+                    "cost history, and quantify the saving.")
+    ap.add_argument("workspace", nargs="?", default=".")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    adv = advise(args.workspace)
+    print(json.dumps(adv, indent=2) if args.json else render(adv))
+    # Exit 0 either way: "no basis" is a successful, honest answer, not a tool
+    # failure. Callers read has_basis.
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/receipt-bundle.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python3
+"""Collect every receipt under a workspace into ONE verifiable audit trail.
+
+WHY THIS EXISTS. Single-receipt verification exists (autonomy/lib/
+proof-verify.py). Cross-run comparison exists (receipt-diff.py). Portable
+attestation exists (receipt-attest.py). All three answer questions about ONE
+run, or two. Nobody has to hand a compliance reviewer one run. They have to
+hand over a SEQUENCE -- every run in the workspace, and a single verdict over
+the lot.
+
+That rollup is where the laundering happens, so it is what this file is
+mostly about.
+
+THE FOUR RULES. Each one is a specific way a bundle report can claim more than
+it earned, and each is the honest direction, not the flattering one.
+
+1. THE ROLLUP IS THE WEAKEST LINK, NEVER AN AVERAGE. Nine good receipts and
+   one forged one is a FAILED bundle. Not "90% verified", not "mostly clean",
+   not a score. A percentage lets a bad run hide inside a crowd of good ones,
+   and hiding a bad run inside good ones is the entire attack this product
+   line exists to prevent. Averaging also gets EASIER to pass as the bundle
+   grows, which is exactly backwards: more runs should be harder to certify,
+   not cheaper. See rollup() -- it is four lines and it is the product.
+
+2. AN UNVERIFIABLE RECEIPT IS NEVER SILENTLY DROPPED. Absent is not clean. A
+   bundle that quietly excludes what it could not check reports a stronger
+   claim than it earned, and it does so invisibly -- the reader sees only
+   receipts that passed and cannot tell whether that is because the rest were
+   good or because the rest were omitted. So an unverifiable receipt is
+   counted, NAMED, given a reason, and it holds the rollup down to
+   UNVERIFIABLE. This is why the per-receipt state is three-valued and is NOT
+   read off verify()'s `ok` field: `ok` is False for BOTH a tampered receipt
+   and an honest receipt read from the wrong directory (proof-verify.py:706
+   says so outright -- diff_drift None makes ok False by design). Collapsing
+   those two together makes this rule unsatisfiable, because "name why" has no
+   answer when FAILED and UNVERIFIABLE are the same bucket.
+
+3. TOTAL COST SUMS ONLY MEASURED RECEIPTS, AND SAYS HOW MANY OF HOW MANY. A
+   total over 10 receipts of which 3 measured cost is not a bundle total; it
+   is a third of one wearing the label of the whole. The ratio rides with the
+   number, always. And if NOTHING measured, the total reads UNKNOWN -- never
+   $0.00, because unmeasured and free are different claims and only one of
+   them is honest. The measured/unmeasured 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 `usd` onto the
+   per-iteration `cost_usd` key. Imported twice over, restated zero times: a
+   second copy of that predicate is precisely how the honesty rule drifts.
+
+4. AN EMPTY WORKSPACE IS NOT A PASSING AUDIT. Zero receipts verified is not
+   "everything verified". Vacuous truth is the cheapest false green there is,
+   and a tool that reports EMPTY as clean can be passed by deleting the
+   evidence. So EMPTY is its own verdict with its own non-zero exit code.
+
+Nothing here re-implements verification. verify() in proof-verify.py is the
+single source of truth; this projects its result onto three states and folds
+them with min().
+
+Usage:
+    tools/receipt-bundle.py [workspace] [--json]
+
+Exit codes:
+    0  every receipt in the bundle VERIFIED
+    1  at least one receipt FAILED
+    2  nothing failed, but at least one receipt was UNVERIFIABLE
+    3  no receipts found at all -- nothing was audited
+"""
+
+import argparse
+import importlib.util
+import json
+import os
+import pathlib
+import sys
+
+# A stale .pyc for a hyphenated module loaded by path makes mutation probes
+# report FALSE failures (the probe edits the source, the loader serves the old
+# bytecode). Must be set before any loader below runs.
+sys.dont_write_bytecode = True
+
+_ROOT = pathlib.Path(__file__).resolve().parents[1]
+_LIB = _ROOT / "autonomy" / "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
+
+
+_pv = _load("proof_verify", _LIB / "proof-verify.py")
+# measured_cost() already maps the receipt's cost block onto the per-iteration
+# key names record_is_measured() expects. Reused rather than re-derived.
+_rd = _load("receipt_diff", _ROOT / "tools" / "receipt-diff.py")
+
+verify = _pv.verify
+measured_cost = _rd.measured_cost
+
+VERIFIED = "VERIFIED"
+UNVERIFIABLE = "UNVERIFIABLE"
+FAILED = "FAILED"
+EMPTY = "EMPTY"
+
+# Ordered worst-first. rollup() takes the min index, which IS the weakest-link
+# rule: one FAILED sinks any number of VERIFIED.
+_ORDER = (FAILED, UNVERIFIABLE, VERIFIED)
+
+EXIT = {VERIFIED: 0, FAILED: 1, UNVERIFIABLE: 2, EMPTY: 3}
+
+
+def rollup(states):
+    """The bundle verdict: the WEAKEST state present, never an average.
+
+    This is the whole product. One FAILED receipt among a thousand VERIFIED
+    ones makes the bundle FAILED, because a buyer handing this to a compliance
+    reviewer is claiming the SEQUENCE is sound, and a sequence containing a
+    forged run is not sound no matter what fraction it represents.
+
+    Any scoring rule -- mean, median, majority, "90% or better" -- makes a bad
+    run cheaper to hide the more good runs surround it. Empty is its own
+    verdict, not a vacuous pass (rule 4).
+    """
+    if not states:
+        return EMPTY
+    return min(states, key=_ORDER.index)
+
+
+def receipt_state(proof_path, repo_dir="."):
+    """Project one receipt onto (state, reason), keeping three states apart.
+
+    verify()'s `ok` is deliberately NOT the source here. It is False both for
+    a receipt that failed a check and for one whose checks could not run at
+    all -- and telling those apart is the entire point of rule 2. So the
+    failure signals are read individually:
+
+        a check RAN and said no      -> FAILED        (hash_ok False,
+                                                       diff_drift True,
+                                                       gpg_ok False,
+                                                       headline_consistent False)
+        a check COULD NOT RUN        -> UNVERIFIABLE  (diff_drift None, or the
+                                                       receipt would not load)
+
+    `is` comparisons are load-bearing throughout: gpg_ok is the truthy string
+    "n/a" when there is nothing to check, and `if not gpg_ok` would read that
+    as a signature failure.
+    """
+    try:
+        result = verify(str(proof_path), repo_dir)
+    except Exception as exc:  # unreadable, unparseable, wrong shape
+        # Named and counted, never dropped. This is the branch rule 2 is about.
+        return UNVERIFIABLE, "the receipt could not be loaded or verified: %s" % exc
+
+    reasons = result.get("reasons") or []
+    detail = reasons[0] if reasons else (result.get("reason") or "")
+
+    if not result.get("hash_ok"):
+        return FAILED, detail or "the recorded integrity hash does not match the receipt bytes"
+    if result.get("diff_drift") is True:
+        return FAILED, detail or "the recorded diff no longer matches the repository"
+    if result.get("gpg_ok") is False:
+        return FAILED, detail or "the gpg signature does not verify"
+    if result.get("headline_consistent") is False:
+        return FAILED, detail or "the headline disagrees with the recorded facts"
+    if result.get("diff_drift") is None:
+        return UNVERIFIABLE, detail or "the recorded diff could not be re-derived here"
+    if not result.get("ok"):
+        # verify() sank the verdict on an axis not enumerated above. Report it
+        # as FAILED with its own words rather than silently upgrading to
+        # VERIFIED -- a new check added upstream must not arrive here as a pass.
+        return FAILED, detail or "verification failed"
+    return VERIFIED, ""
+
+
+def find_receipts(workspace):
+    """Every proof.json under the workspace, sorted for a stable report.
+
+    ponytail: rglob over the whole tree rather than only .loki/proofs/*, so a
+    receipt archived elsewhere in the workspace still gets audited. Missing
+    evidence is the failure mode this file exists to prevent; over-collecting
+    is not.
+    """
+    root = pathlib.Path(workspace)
+    return sorted(p for p in root.rglob("proof.json") if p.is_file())
+
+
+def bundle(workspace, repo_dir="."):
+    """Audit every receipt under `workspace`. Pure: no writes, no network."""
+    paths = find_receipts(workspace)
+
+    receipts = []
+    total = 0.0
+    measured_n = 0
+
+    for path in paths:
+        state, reason = receipt_state(path, repo_dir)
+        entry = {
+            "path": str(path),
+            "state": state,
+            "reason": reason,
+            "cost_usd": None,
+        }
+
+        # Cost is read from the receipt regardless of verdict, but only a
+        # MEASURED cost contributes. measured_cost() returns None when the
+        # block is absent, malformed, or all-zero.
+        try:
+            cost = measured_cost(_pv._load_proof(str(path)))
+        except Exception:
+            cost = None
+        if cost is not None and cost.get("cost_usd") is not None:
+            entry["cost_usd"] = cost["cost_usd"]
+            total += cost["cost_usd"]
+            measured_n += 1
+
+        receipts.append(entry)
+
+    verdict = rollup([r["state"] for r in receipts])
+
+    # measured_n, NOT the total, decides UNKNOWN. Three receipts that each
+    # genuinely measured $0.00 is a real observation and must survive as a
+    # number; `if not total` would erase it and reintroduce the exact
+    # unmeasured-reads-as-free defect this codebase spent four releases on.
+    cost_block = {
+        "measured_receipts": measured_n,
+        "total_receipts": len(receipts),
+        "total_usd": total if measured_n else None,
+    }
+
+    unverifiable = [r for r in receipts if r["state"] != VERIFIED]
+
+    return {
+        "bundle": "loki-receipt-bundle/v1",
+        "workspace": os.path.abspath(str(workspace)),
+        "checked_from": os.path.abspath(repo_dir),
+        "receipts": receipts,
+        "counts": {
+            state: sum(1 for r in receipts if r["state"] == state)
+            for state in _ORDER
+        },
+        "cost": cost_block,
+        "not_verified": [
+            {"path": r["path"], "state": r["state"], "reason": r["reason"]}
+            for r in unverifiable
+        ],
+        "verdict": verdict,
+        "summary": _summary(verdict, receipts, cost_block),
+    }
+
+
+def _cost_line(cost):
+    """The total, always carrying its own ratio. UNKNOWN when nothing measured."""
+    if cost["total_usd"] is None:
+        return "total cost UNKNOWN (0 of %d receipts measured cost)" % (
+            cost["total_receipts"])
+    return "total cost $%.4f across %d of %d receipts measured" % (
+        cost["total_usd"], cost["measured_receipts"], cost["total_receipts"])
+
+
+def _summary(verdict, receipts, cost):
+    if verdict == EMPTY:
+        return ("EMPTY -- no receipts found under this workspace, so nothing "
+                "was audited. Zero receipts is not a passing audit.")
+    n = len(receipts)
+    bad = sum(1 for r in receipts if r["state"] == FAILED)
+    unv = sum(1 for r in receipts if r["state"] == UNVERIFIABLE)
+    if verdict == VERIFIED:
+        head = "VERIFIED -- all %d receipts verified" % n
+    elif verdict == FAILED:
+        head = ("FAILED -- %d of %d receipts FAILED verification; the bundle "
+                "is only as good as its weakest receipt" % (bad, n))
+    else:
+        head = ("UNVERIFIABLE -- %d of %d receipts could not be checked here; "
+                "nothing failed, but the bundle is not proven" % (unv, n))
+    return head + ". " + _cost_line(cost)
+
+
+def _render(report):
+    lines = ["Receipt bundle: %s" % report["workspace"], ""]
+    for r in report["receipts"]:
+        lines.append("  %-13s %s" % (r["state"], r["path"]))
+        if r["reason"]:
+            lines.append("                %s" % r["reason"])
+    if report["receipts"]:
+        lines.append("")
+    if report["not_verified"]:
+        lines.append("Not verified (%d) -- counted, never dropped:"
+                     % len(report["not_verified"]))
+        for r in report["not_verified"]:
+            lines.append("  %s [%s]" % (r["path"], r["state"]))
+            lines.append("      %s" % r["reason"])
+        lines.append("")
+    lines.append(_cost_line(report["cost"]))
+    lines.append("")
+    lines.append(report["summary"])
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Verify every receipt under a workspace as one bundle.")
+    ap.add_argument("workspace", nargs="?", default=".",
+                    help="workspace to scan for receipts (default: .)")
+    ap.add_argument("--json", action="store_true", help="emit the raw record")
+    ap.add_argument("--repo-dir", default=".",
+                    help="repository the receipts are re-checked against")
+    args = ap.parse_args(argv)
+
+    report = bundle(args.workspace, args.repo_dir)
+    print(json.dumps(report, indent=2) if args.json else _render(report))
+    return EXIT[report["verdict"]]
+
+
+if __name__ == "__main__":
+    sys.exit(main())