loki-mode 8.87.0 → 8.88.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.87.0
+# Loki Mode v8.88.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.87.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v8.88.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-8.87.0
+8.88.0

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "8.87.0"
+__version__ = "8.88.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.87.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.88.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=963043D4CCDC5F7D64756E2164756E21
+//# debugId=9115B3EA38A3D81564756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "8.87.0",
+  "version": "8.88.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.87.0",
+  "version": "8.88.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/cost-guard.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""Fail a build when a run's cost regressed. A cost gate for CI.
+
+Teams gate merges on tests. This lets them gate merges on cost the same way:
+point it at a workspace, give it a ceiling or a baseline receipt, and it exits
+non-zero when the run got more expensive than the policy allows.
+
+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. Mapping absence to 0 would make this gate
+loudest -- a confident green -- at exactly the moment instrumentation broke and
+it is least entitled to speak. That is the failure this repo spent thirteen
+surfaces fixing: an unmeasured run rendered as "$0.00", which reads as free.
+Free and unmeasured are different claims and only one of them is honest. Exit 2
+keeps "no evidence" distinguishable from "evidence of compliance".
+
+Exit 0 is reachable from exactly ONE place in this file (the end of evaluate()),
+and only after a measurement was read. Everything else -- no policy given, an
+unreadable baseline, an unmeasured run, an unmeasured baseline -- is 2.
+
+Whether a number counts as measured is record_is_measured() in
+autonomy/lib/efficiency_cost.py, imported and never restated: a second copy of
+that predicate is precisely how the honesty rule drifts. Receipts store the
+figure under cost.usd while the predicate reads cost_usd, so the KEY is mapped
+here. Mapping a key name is not restating the rule.
+
+A genuinely measured $0.00 under budget PASSES. Zero is falsy, so every guard
+here is an explicit `is None` check. A falsy guard would blank a real
+observation, which is the same lie pointed the other way (hit for real in
+v8.72.0).
+
+Usage:
+  tools/cost-guard.py [workspace] --max-usd 5.00
+  tools/cost-guard.py [workspace] --baseline old/proof.json --max-increase-pct 10
+  tools/cost-guard.py [workspace] --max-usd 5.00 --json
+
+Exit: 0 within budget, 1 over budget / regressed, 2 cannot evaluate.
+
+NON-GOAL: the baseline receipt's integrity hash is not verified. A tampered
+baseline that inflates the allowed ceiling is out of scope; use
+tools/receipt-diff.py, which does verify. A baseline whose cost block is absent
+or unmeasured still exits 2 here, via the same predicate as everything else.
+
+INHERITED LIMIT, stated rather than silently owned. record_is_measured() is
+satisfied by tokens OR cost, so a record carrying real token counts but no
+cost_usd field sums to usd=0.0 with available=True, and this gate reports
+"WITHIN BUDGET: $0.0000" for a run that did cost money. Verified, not
+theoretical. It is not fixable here: requirement 3 demands that cost_usd=0.0
+WITH tokens passes, so the two shapes are identical downstream of the sum. The
+fix belongs in the pricing layer (price_from_tokens() in the same module exists
+because tools do report tokens without a native cost), not in a second copy of
+the honesty predicate. This gate is exactly as honest as its measurement
+source, which is the correct coupling.
+"""
+
+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
+
+
+def _num(v):
+    """A number as itself; None, "", or a bool as None."""
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        return None
+    return v
+
+
+def measured_usd(cost):
+    """The USD figure from a cost block, or None when it was never measured.
+
+    `available` is NOT trusted on its own: a real receipt shipped
+    available=true with every field zero (v8.52.0), so the flag is a claim and
+    the VALUES are the evidence. record_is_measured reads per-iteration key
+    names, hence usd -> cost_usd.
+    """
+    if not isinstance(cost, dict):
+        return None
+    rec = {
+        "cost_usd": _num(cost.get("usd")),
+        "input_tokens": _num(cost.get("input_tokens")),
+        "output_tokens": _num(cost.get("output_tokens")),
+        "cache_read_tokens": _num(cost.get("cache_read_tokens")),
+        "cache_creation_tokens": _num(cost.get("cache_creation_tokens")),
+    }
+    if not record_is_measured(rec):
+        return None
+    return _num(rec["cost_usd"])
+
+
+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,
+            "actual_usd": None, "baseline_usd": None, "reason": None}
+
+
+def evaluate(workspace, max_usd=None, baseline_path=None,
+             max_increase_pct=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.
+    """
+    if max_usd is None and max_increase_pct is None:
+        return _cannot(
+            "no budget policy given: pass --max-usd and/or --baseline with "
+            "--max-increase-pct. A gate with no policy checks nothing, and "
+            "must not report a pass for it.")
+
+    if baseline_path and max_increase_pct is None:
+        # A HALF-HONORED policy must not report a full pass. Without this,
+        # `--max-usd 5 --baseline old.json` never opens the baseline and can
+        # exit 0 having silently ignored half of what the operator asked for.
+        return _cannot(
+            "--baseline %s was given without --max-increase-pct, so the "
+            "baseline would be silently ignored. Refusing to report a pass "
+            "for a policy only half applied." % baseline_path)
+
+    cost, _model = collect_efficiency(_loki_dir(workspace))
+    actual = measured_usd(cost)
+    if actual is None:
+        # THE POINT OF THIS FILE. Absence is not compliance.
+        return _cannot(
+            "cost is UNMEASURED for %s -- no efficiency record carried an "
+            "observed cost or 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)
+
+    breaches = []
+
+    if max_usd is not None:
+        # Compared at the precision this gate REPORTS (4dp), not at binary
+        # float precision. Summed per-iteration costs land a few ulps over a
+        # round ceiling ($0.1+$0.2 > $0.30 is True in binary), which fails a
+        # run that is exactly at its budget and prints "$0.3000 exceeds the
+        # ceiling $0.3000 by $0.0000" -- a breach of nothing.
+        if round(actual - max_usd, 4) > 0:
+            breaches.append(
+                "cost $%.4f exceeds the ceiling $%.4f by $%.4f (%.1f%% over)"
+                % (actual, max_usd, actual - max_usd,
+                   ((actual - max_usd) / max_usd * 100.0) if max_usd else 0.0))
+
+    baseline = None
+    if max_increase_pct is not None:
+        if not baseline_path:
+            return _cannot(
+                "--max-increase-pct needs --baseline <proof.json>: a "
+                "percentage increase has nothing to increase from.")
+        try:
+            with open(baseline_path, "r", encoding="utf-8") as handle:
+                proof = json.load(handle)
+        except Exception as exc:
+            return _cannot("baseline unreadable (%s): %s"
+                           % (baseline_path, exc))
+        baseline = measured_usd(
+            proof.get("cost") if isinstance(proof, dict) else None)
+        if baseline is None:
+            return _cannot(
+                "baseline receipt %s records no measured cost, so no increase "
+                "against it is a real number." % baseline_path)
+
+        rise = actual - baseline
+        if baseline == 0:
+            # Evaluable -- both sides ARE measured -- so not a 2. A percentage
+            # of zero is undefined, so the absolute rise is what gets named.
+            if rise > 0:
+                breaches.append(
+                    "cost rose from a measured $0.0000 baseline to $%.4f "
+                    "(+$%.4f); percent increase is undefined against zero, so "
+                    "any rise breaches" % (actual, rise))
+        else:
+            # Rounded to the precision this gate REPORTS. Binary floats put
+            # $1.00 -> $1.10 at 10.000000000000009%, so an exact `>` fails a
+            # run that is exactly at its allowance and then prints "10.0% over
+            # the allowed 10.0%" -- a verdict its own message contradicts.
+            pct = round(rise / baseline * 100.0, 6)
+            if pct > max_increase_pct:
+                breaches.append(
+                    "cost rose %.1f%% ($%.4f -> $%.4f, +$%.4f), over the "
+                    "allowed %.1f%%"
+                    % (pct, baseline, actual, rise, max_increase_pct))
+
+    if breaches:
+        return {"status": "over_budget", "exit_code": OVER,
+                "actual_usd": actual, "baseline_usd": baseline,
+                "reason": "; ".join(breaches), "why": None}
+
+    return {"status": "within_budget", "exit_code": OK, "actual_usd": actual,
+            "baseline_usd": baseline, "reason": None, "why": None}
+
+
+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 cost $%.4f" % d["actual_usd"]
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Fail CI when a run's cost regressed past a budget policy.")
+    ap.add_argument("workspace", nargs="?", default=".",
+                    help="workspace root (or its .loki dir); default .")
+    ap.add_argument("--max-usd", type=float, help="absolute USD ceiling")
+    ap.add_argument("--baseline", help="baseline proof.json to compare against")
+    ap.add_argument("--max-increase-pct", type=float,
+                    help="allowed %% increase over the baseline's cost")
+    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_usd, args.baseline,
+                 args.max_increase_pct)
+    print(json.dumps(d, indent=2) if args.as_json else render(d))
+    return d["exit_code"]
+
+
+if __name__ == "__main__":
+    sys.exit(main())