loki-mode 8.95.0 → 8.97.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.95.0
+# Loki Mode v8.97.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.95.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v8.97.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-8.95.0
+8.97.0

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "8.95.0"
+__version__ = "8.97.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.95.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.97.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=FD5A9EB9795BBFB164756E2164756E21
+//# debugId=B171B033D661F73464756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "8.95.0",
+  "version": "8.97.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.95.0",
+  "version": "8.97.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-history.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Track agent cost across MANY runs and report the trend.
+
+cost-guard.py gates ONE run against a ceiling. receipt-diff.py compares TWO
+runs. Neither answers the question a team actually asks at the end of a month:
+is our agent spend trending up? That needs a durable history, so this appends
+one line per run to a JSONL file and reports over the whole series.
+
+THE FIVE PROPERTIES THAT MAKE THE TREND WORTH BELIEVING:
+
+1. AN UNMEASURED RUN IS NEVER RECORDED AS 0. It is appended with usd=null and
+   excluded from the trend. Recording zero would drag the median down and
+   understate real spend -- the exact "$0.00 means free" lie this repo spent
+   thirteen surfaces removing. Whether a number counts as measured is
+   record_is_measured() in autonomy/lib/efficiency_cost.py, imported and never
+   restated; 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.
+
+   RECORD-NULL rather than REFUSE, deliberately. Refusing is cost-guard.py's
+   job and it already does it, per run, with an exit code. Here the history IS
+   the product, and a refused append leaves no trace: a month with four broken
+   instrumentation runs would look identical to a month with eight clean ones.
+   The null row is countable, so the report can say "12 runs, 8 measured" and
+   the operator can see the measurement gap instead of inferring it from a
+   short file.
+
+2. A TREND FROM ONE POINT IS NOT A TREND. Fewer than 2 measured runs reads
+   INSUFFICIENT DATA. "Flat" is a claim about change over time and one
+   observation cannot support it.
+
+3. APPEND IS ATOMIC PER LINE. See _append().
+
+4. A CORRUPT LINE IS COUNTED AND REPORTED, never silently skipped. A history
+   that quietly drops rows reports a cleaner trend than reality, and drops them
+   most often when something upstream is broken -- precisely when the number
+   matters.
+
+5. AN EMPTY HISTORY IS NOT A FLAT TREND. It exits non-zero. Zero runs is an
+   absent measurement, not evidence of stability.
+
+Usage:
+  tools/cost-history.py record [workspace] [--file .loki/cost-history.jsonl]
+  tools/cost-history.py report [--file ...] [--json]
+
+Exit: 0 report produced / run recorded, 1 nothing to report (empty or no
+measured runs), 2 cannot record.
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+
+_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, NOTHING, CANNOT = 0, 1, 2
+
+DEFAULT_FILE = os.path.join(".loki", "cost-history.jsonl")
+
+# Below this the two halves are the same number to the cent, and calling that
+# a direction is noise dressed as signal.
+FLAT_PCT = 5.0
+
+
+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.
+    """
+    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 _append(path, entry):
+    """Append ONE newline-terminated line with ONE write() call, in "a" mode.
+
+    WHY THAT IS SUFFICIENT HERE, rather than the usual write-temp-and-rename.
+    POSIX gives an O_APPEND write a seek-to-end that cannot be interleaved, so
+    concurrent appenders cannot overwrite each other, and a line small enough
+    to land in a single write is not torn between two of them. Rename-based
+    atomicity would be strictly WORSE for this file: it rewrites the whole
+    history every time, which turns a crash into the loss of every prior run
+    instead of a partial final line.
+
+    That partial final line is the residual risk and it is handled rather than
+    prevented: a torn or truncated row is COUNTED as corrupt by load() and
+    named in the report. This is why the newline terminator is load-bearing --
+    it is what makes a complete row distinguishable from a truncated one.
+
+    ponytail: no locking. O_APPEND is the lock. Add one only if this ever needs
+    to write multi-line entries, which would break the single-write property.
+    """
+    parent = os.path.dirname(os.path.abspath(path))
+    if parent:
+        os.makedirs(parent, exist_ok=True)
+    line = json.dumps(entry, sort_keys=True) + "\n"
+    with open(path, "a", encoding="utf-8") as handle:
+        handle.write(line)
+
+
+def load(path):
+    """Read the history. Returns (entries, corrupt_count).
+
+    A line that is not JSON, or is JSON but not an object, is corrupt and
+    COUNTED. It is never dropped on the floor.
+    """
+    entries, corrupt = [], 0
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            raw = handle.read()
+    except OSError:
+        return None, 0
+    for line in raw.splitlines():
+        if not line.strip():
+            continue
+        try:
+            obj = json.loads(line)
+        except ValueError:
+            corrupt += 1
+            continue
+        if not isinstance(obj, dict) or "usd" not in obj:
+            corrupt += 1
+            continue
+        entries.append(obj)
+    return entries, corrupt
+
+
+def median(values):
+    """Median of a non-empty list. Even length averages the middle pair."""
+    s = sorted(values)
+    n = len(s)
+    mid = n // 2
+    return s[mid] if n % 2 else (s[mid - 1] + s[mid]) / 2.0
+
+
+def direction(values):
+    """(label, explanation) for a series oldest to newest.
+
+    Compares the median of the older half against the median of the newer
+    half, not first-vs-last: a single expensive outlier at either end should
+    not name the trend for a whole quarter. With 2 or 3 points the halves are
+    small, so the comparison it used is always printed alongside the verdict --
+    the operator can see how thin the evidence is.
+    """
+    if len(values) < 2:
+        return "INSUFFICIENT DATA", (
+            "%d measured run(s); a trend needs at least 2. One observation "
+            "cannot show change over time, and 'flat' would be a claim."
+            % len(values))
+    half = len(values) // 2
+    older = median(values[:half])
+    newer = median(values[len(values) - half:])
+    basis = ("median of the oldest %d ($%.4f) vs the newest %d ($%.4f)"
+             % (half, older, half, newer))
+    if older == 0:
+        if newer == 0:
+            return "flat", basis + "; both zero"
+        return "rising", basis + "; percent change is undefined against zero"
+    pct = (newer - older) / older * 100.0
+    if abs(pct) < FLAT_PCT:
+        return "flat", "%s; %+.1f%%, within the %.0f%% flat band" % (
+            basis, pct, FLAT_PCT)
+    return ("rising" if pct > 0 else "falling"), "%s; %+.1f%%" % (basis, pct)
+
+
+def record(workspace, path, now=None):
+    """Append this workspace's run to the history. Returns a verdict dict."""
+    cost, model = collect_efficiency(_loki_dir(workspace))
+    usd = measured_usd(cost)
+    entry = {
+        "ts": now if now is not None else time.time(),
+        "workspace": os.path.abspath(workspace),
+        "usd": usd,          # None when unmeasured. NEVER 0 as a stand-in.
+        "measured": usd is not None,
+        "model": model or None,
+    }
+    try:
+        _append(path, entry)
+    except OSError as exc:
+        return {"status": "cannot_record", "exit_code": CANNOT,
+                "why": "could not append to %s: %s" % (path, exc),
+                "entry": None}
+    return {"status": "recorded", "exit_code": OK, "why": None,
+            "entry": entry}
+
+
+def report(path):
+    """Summarize the history. Returns a verdict dict."""
+    entries, corrupt = load(path)
+    if entries is None:
+        return {"status": "no_history", "exit_code": NOTHING,
+                "why": "no history file at %s; record a run first." % path,
+                "runs": 0, "measured": 0, "corrupt_lines": 0,
+                "costs": [], "median_usd": None,
+                "direction": "INSUFFICIENT DATA", "basis": None}
+
+    costs = [e["usd"] for e in entries
+             if e.get("measured") and _num(e.get("usd")) is not None]
+
+    if not entries:
+        # An empty file is not a flat trend. Zero runs is an absent
+        # measurement, and reporting stability from it would be a claim made
+        # out of nothing.
+        return {"status": "empty", "exit_code": NOTHING,
+                "why": "history %s is empty (%d corrupt line(s)); zero runs "
+                       "is not a flat trend." % (path, corrupt),
+                "runs": 0, "measured": 0, "corrupt_lines": corrupt,
+                "costs": [], "median_usd": None,
+                "direction": "INSUFFICIENT DATA", "basis": None}
+
+    label, basis = direction(costs)
+    return {
+        "status": "ok" if costs else "no_measured_runs",
+        "exit_code": OK if costs else NOTHING,
+        "why": None if costs else (
+            "%d run(s) recorded but none carried a measured cost; there is "
+            "nothing to trend. Unmeasured runs are kept as null, not 0."
+            % len(entries)),
+        "runs": len(entries),
+        "measured": len(costs),
+        "corrupt_lines": corrupt,
+        "costs": costs,
+        "median_usd": median(costs) if costs else None,
+        "direction": label,
+        "basis": basis,
+    }
+
+
+def render(d):
+    if d["status"] in ("no_history", "empty"):
+        return "NO TREND: %s" % d["why"]
+    if d["status"] == "cannot_record":
+        return "CANNOT RECORD: %s" % d["why"]
+    if d["status"] == "recorded":
+        e = d["entry"]
+        return ("recorded %s: %s" % (
+            e["workspace"],
+            "$%.4f" % e["usd"] if e["measured"]
+            else "UNMEASURED (stored as null, excluded from the trend)"))
+
+    lines = ["%d run(s), %d measured" % (d["runs"], d["measured"])]
+    if d["corrupt_lines"]:
+        # Named, not swallowed. A dropped row makes the trend look cleaner
+        # than reality.
+        lines.append("%d CORRUPT line(s) in the history -- counted, not "
+                     "skipped; the trend below omits them."
+                     % d["corrupt_lines"])
+    if d["status"] == "no_measured_runs":
+        lines.append("NO TREND: %s" % d["why"])
+        return "\n".join(lines)
+    lines.append("costs oldest to newest: "
+                 + ", ".join("$%.4f" % c for c in d["costs"]))
+    lines.append("median: $%.4f" % d["median_usd"])
+    lines.append("direction: %s (%s)" % (d["direction"], d["basis"]))
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Track agent cost across many runs and report the trend.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    rec = sub.add_parser("record", help="append this run's cost to the history")
+    rec.add_argument("workspace", nargs="?", default=".",
+                     help="workspace root (or its .loki dir); default .")
+    rec.add_argument("--file", default=DEFAULT_FILE,
+                     help="history JSONL (default %s)" % DEFAULT_FILE)
+
+    rep = sub.add_parser("report", help="summarize the recorded history")
+    rep.add_argument("--file", default=DEFAULT_FILE,
+                     help="history JSONL (default %s)" % DEFAULT_FILE)
+    rep.add_argument("--json", action="store_true", dest="as_json",
+                     help="emit the report as JSON")
+
+    args = ap.parse_args(argv)
+    if args.cmd == "record":
+        d = record(args.workspace, args.file)
+        print(render(d))
+    else:
+        d = report(args.file)
+        print(json.dumps(d, indent=2) if args.as_json else render(d))
+    return d["exit_code"]
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/gate-report.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Render a ci-gate verdict as CI-native output. Never invent a verdict.
+
+WHY THIS EXISTS. tools/ci-gate.py already decides correctly and exits 0/1/2.
+But in a CI run its text table lands in a collapsed log that nobody opens. The
+two surfaces an engineer actually reads are the run page ($GITHUB_STEP_SUMMARY,
+markdown) and the PR diff annotations (::error / ::warning workflow commands).
+Nothing carried our verdict to either, so the gate's most important state --
+"this policy could not be checked" -- was invisible at exactly the moment it
+mattered.
+
+    python3 tools/ci-gate.py <ws> --max-usd 5 --json \
+        | python3 tools/gate-report.py --format markdown >> "$GITHUB_STEP_SUMMARY"
+
+THE RULE THIS FILE EXISTS TO HOLD, inherited from ci-gate.py:
+
+    A POLICY THAT COULD NOT BE EVALUATED HAS NOT PASSED.
+
+A renderer is where that rule dies quietly. A table styles UNEVALUABLE like a
+minor note; an annotation layer emits ::error for failures and simply skips
+everything else. Both produce a run page with no red on it, and a reviewer
+reads absence-of-red as pass. So UNEVALUABLE renders exactly as prominently as
+FAIL, and in the github format it is a ::warning at minimum -- never silent,
+never ::notice. There is one severity map, below, and both formats read it.
+
+WHY THE EXIT CODE IS RE-EMITTED. In `ci-gate.py ... | gate-report.py` the shell
+keeps ONLY the last command's status. ci-gate's 2 is discarded by the pipe. If
+this file exited 0 for a rendered blind gate, adding a human-readable report
+would have converted a blocked merge into a green check -- the pipeline would
+be made LESS safe by the act of describing itself. So the input's own exit_code
+is re-emitted, and anything that is not a recognised verdict exits 2.
+
+WHAT IT REFUSES TO DO. It never computes a state, only relays one. A row with
+no state, or a state word this file does not recognise, is UNEVALUABLE -- the
+input did not carry a verdict, and a renderer that fills that gap with "pass"
+is manufacturing evidence. Empty stdin and malformed JSON are errors on stderr
+with exit 2, never an empty report: a report of nothing is indistinguishable
+from a clean run.
+
+Exit: mirrors the input verdict (0 pass, 1 failed, 2 unevaluable); 2 on any
+input this file could not parse.
+"""
+
+import argparse
+import json
+import sys
+
+PASS, FAIL, UNEVALUABLE = 0, 1, 2
+
+# THE ONE MAPPING. Both formats read it, so a change of severity cannot apply
+# to one surface and not the other. "notice" is reserved for PASS: an
+# unevaluable policy demoted to a notice is precisely the silent-green failure
+# this tool exists to prevent.
+_SEVERITY = {"PASS": "notice", "FAIL": "error", "UNEVALUABLE": "warning"}
+
+_EXIT = {"PASS": PASS, "FAIL": FAIL, "UNEVALUABLE": UNEVALUABLE}
+
+# ponytail: markdown emphasis is derived, not a second table to drift.
+_UNKNOWN = ("UNEVALUABLE", "state not reported by the gate: the input carried "
+            "no recognised verdict for this policy, so it has not passed")
+
+
+def _state_of(row):
+    """The row's own verdict, or UNEVALUABLE. Never a default of PASS."""
+    if not isinstance(row, dict):
+        return _UNKNOWN[0], "malformed policy entry: %r" % (row,), "?"
+    state = row.get("state")
+    policy = str(row.get("policy") or "?")
+    reason = row.get("reason")
+    reason = reason.strip() if isinstance(reason, str) and reason.strip() \
+        else "no detail reported"
+    if not isinstance(state, str) or state.upper() not in _SEVERITY:
+        return _UNKNOWN[0], "%s (was %r)" % (_UNKNOWN[1], state), policy
+    return state.upper(), reason, policy
+
+
+def _rows(verdict):
+    """Every policy row, plus a synthetic row when the gate carried none.
+
+    An empty policies list with a top-level UNEVALUABLE is ci-gate's
+    "no policy configured" verdict. Rendering an empty table there would draw a
+    header and no rows, which reads as a clean run -- the exact inversion this
+    file exists to stop.
+    """
+    policies = verdict.get("policies")
+    out = []
+    if isinstance(policies, list):
+        for row in policies:
+            out.append(_state_of(row))
+    if out:
+        return out
+    # No policy results arrived. Whatever the header claims, nothing was
+    # checked, so this row is UNEVALUABLE unconditionally -- trusting a
+    # top-level "PASS" here would render a green table built from zero
+    # evidence, which is the one thing this file must never do.
+    return [(_UNKNOWN[0], _overall_reason(verdict), "(none)")]
+
+
+def _overall_reason(verdict):
+    reason = verdict.get("reason")
+    if isinstance(reason, str) and reason.strip():
+        return reason.strip()
+    return "the gate reported no policy results and no reason"
+
+
+def _verdict_state(verdict):
+    """The overall state, never weaker than the worst row.
+
+    The header is a claim; the rows are the evidence. A body asserting PASS
+    over a FAILED or unreported row is not a pass, so the summary line is
+    reconciled against the rows here -- the same weakest-link rule ci-gate
+    applies, and the same one exit_code() applies. Reporting a green summary
+    above a red table is how a reader ends up trusting the wrong one.
+    """
+    state = verdict.get("state")
+    claimed = state.upper() if isinstance(state, str) \
+        and state.upper() in _SEVERITY else _UNKNOWN[0]
+    worst = max([_EXIT[claimed]] +
+                [_EXIT[row[0]] for row in _rows(verdict)])
+    return {v: k for k, v in _EXIT.items()}[worst]
+
+
+def render_markdown(verdict):
+    state = _verdict_state(verdict)
+    lines = ["## Merge gate: %s" % _headline(state), "",
+             "| Policy | State | Detail |", "| --- | --- | --- |"]
+    for row_state, reason, policy in _rows(verdict):
+        # Bold every non-pass. An unevaluable row must not be visually quieter
+        # than a failed one on the run page.
+        cell = row_state if row_state == "PASS" else "**%s**" % row_state
+        lines.append("| %s | %s | %s |" % (policy, cell, _cell(reason)))
+    lines.append("")
+    lines.append("%s -- %s" % (_headline(state), _overall_reason(verdict)))
+    return "\n".join(lines)
+
+
+def _headline(state):
+    if state == "PASS":
+        return "PASS"
+    if state == "FAIL":
+        return "FAIL"
+    return "UNEVALUABLE (could not be checked -- this is not a pass)"
+
+
+def _cell(text):
+    # A pipe in a reason would silently split the row into extra columns.
+    return " ".join(text.split()).replace("|", "\\|")
+
+
+def render_github(verdict, file_hint=None):
+    """Workflow commands. Non-pass rows are never silent."""
+    lines = []
+    loc = "file=%s," % file_hint if file_hint else ""
+    for row_state, reason, policy in _rows(verdict):
+        lines.append("::%s %stitle=gate: %s (%s)::%s"
+                     % (_SEVERITY[row_state], loc, policy, row_state,
+                        _annotation_text(reason)))
+    state = _verdict_state(verdict)
+    lines.append("::%s %stitle=merge gate %s::%s"
+                 % (_SEVERITY[state], loc, state,
+                    _annotation_text(_overall_reason(verdict))))
+    return "\n".join(lines)
+
+
+def _one_line(text):
+    # A raw newline would terminate the workflow command mid-message and leave
+    # the tail rendered as plain log noise.
+    return " ".join(text.split())
+
+
+def _annotation_text(text):
+    # % opens an escape sequence in a workflow-command message, and
+    # cost-guard's --max-increase-pct reasons carry literal percentages. Only
+    # the github format needs this; plain text must keep its real % sign.
+    return _one_line(text).replace("%", "%25")
+
+
+def render_text(verdict):
+    lines = ["%-10s %-12s %s" % ("POLICY", "STATE", "DETAIL")]
+    for row_state, reason, policy in _rows(verdict):
+        lines.append("%-10s %-12s %s" % (policy, row_state, _one_line(reason)))
+    lines.append("")
+    lines.append("GATE: %s -- %s" % (_headline(_verdict_state(verdict)),
+                                     _overall_reason(verdict)))
+    return "\n".join(lines)
+
+
+_FORMATS = {"markdown": render_markdown, "github": render_github,
+            "text": render_text}
+
+
+def exit_code(verdict):
+    """The input's own exit semantics. A pipe drops them; this restores them."""
+    code = verdict.get("exit_code")
+    if isinstance(code, bool) or not isinstance(code, int) \
+            or code not in (PASS, FAIL, UNEVALUABLE):
+        # No trustworthy verdict came in, so none goes out. 2 matches
+        # ci-gate's own vocabulary: to a CI job, "blind" and "broken" are the
+        # same fact and neither may merge.
+        return UNEVALUABLE
+    # Cross-check: a body claiming PASS while carrying a non-pass row is not a
+    # pass. Weakest link, same rule ci-gate uses, applied to what arrived --
+    # and the same reconciliation the rendered summary shows, so the exit code
+    # can never disagree with the report a human just read.
+    return max(code, _EXIT[_verdict_state(verdict)])
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Render a ci-gate JSON verdict as CI-native output.")
+    ap.add_argument("--format", choices=sorted(_FORMATS), default="markdown",
+                    help="markdown (step summary), github (annotations), text")
+    ap.add_argument("--file", dest="file_hint",
+                    help="path to attach to github annotations; omitted when "
+                         "not given, because an annotation on the wrong file "
+                         "is worse than none")
+    args = ap.parse_args(argv)
+
+    raw = sys.stdin.read()
+    if not raw.strip():
+        # A report of nothing looks exactly like a clean run.
+        sys.stderr.write("gate-report: empty stdin -- expected ci-gate JSON on "
+                         "stdin. Nothing to report is not a pass.\n")
+        return UNEVALUABLE
+    try:
+        verdict = json.loads(raw)
+    except ValueError as exc:
+        sys.stderr.write("gate-report: could not parse the gate verdict: %s\n"
+                         % exc)
+        return UNEVALUABLE
+    if not isinstance(verdict, dict):
+        sys.stderr.write("gate-report: expected a JSON object from ci-gate, "
+                         "got %s\n" % type(verdict).__name__)
+        return UNEVALUABLE
+
+    # Render fully before printing: a malformed body must never emit a partial
+    # report that a reader mistakes for the whole verdict.
+    if args.format == "github":
+        out = render_github(verdict, args.file_hint)
+    else:
+        out = _FORMATS[args.format](verdict)
+    code = exit_code(verdict)
+    print(out)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/model-advisor.py

@@ -484,10 +484,21 @@ def main(argv=None):
     ap.add_argument("--json", action="store_true")
     args = ap.parse_args(argv)
 
+    # A workspace that does not EXIST is not the same fact as a workspace with
+    # no cost history, and exit 0 collapsed them. A CI job doing
+    # `model-advisor.py "$WS" && ...` on a mistyped or unmounted path saw green
+    # and carried on. Every sibling tool distinguishes these (run-replay 66,
+    # cost-guard 2, receipt-bundle 3); this one did not.
+    if not os.path.isdir(args.workspace):
+        sys.stderr.write(
+            "cannot advise: workspace does not exist: %s\n" % args.workspace)
+        return 66
+
     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.
+    # Exit 0 for a real workspace with no basis: that IS a successful, honest
+    # answer rather than a tool failure, and the output says so in words.
+    # Callers read has_basis.
     return 0
 
 

package/tools/policy-load.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Merge policy as a version-controlled FILE, not a CI flag nobody reviews.
+
+WHY THIS EXISTS. tools/ci-gate.py takes its policy as CLI flags: --max-usd,
+--require-receipt. That works exactly once, in one job, on one machine. The
+ceiling lives in YAML nobody diffs, it cannot be reviewed in a PR, and two
+repos in the same org drift apart with nobody able to name the moment it
+happened. Lowering a ceiling should look like a code change, because it is one.
+
+So: put the policy in a file, load it here, and hand ci-gate its flags.
+
+    python3 tools/ci-gate.py $(python3 tools/policy-load.py --as-args)
+
+THAT COMPOSITION IS WHY EVERY FAILURE HERE IS LOUD. This tool's stdout becomes
+another gate's argv. A loader that shrugs at bad input does not produce a weak
+policy, it produces a gate invoked with NOTHING TO ENFORCE, which ci-gate's own
+docstring calls a vacuously-green gate: worse than no gate, because it is
+trusted. This repo has paid for that shape four times (four detectors missing
+from the package, a deferred dist check, a tarball assertion passing on "6 or
+more" of 6). Every one was a check reporting a pass without having checked.
+
+Hence four rules, each of which is one way to be silently unenforced:
+
+  UNKNOWN KEY IS AN ERROR. "max_usd_" is not "max_usd". Skipping it leaves an
+  operator certain a ceiling is enforced while nothing is. The misspelling is
+  invisible precisely because the file still looks like a policy. Named, not
+  counted: "1 unknown key" does not tell you which line to fix.
+
+  EMPTY OR ABSENT IS AN ERROR, not an empty policy. An empty policy enforces
+  nothing while looking configured. And "implies no flags" is the same hole one
+  level up: {"require_receipt": false} is valid JSON, has a key, and expands to
+  an empty argv. So the test is what the policy ENFORCES, not what it contains.
+
+  VALUES ARE VALIDATED, NOT JUST KEYS. A ceiling of -1 passes every run. So
+  does NaN, which json.loads accepts as a bare literal and which loses every
+  comparison it appears in -- an unenforceable ceiling that reads as a number.
+  So does True, which is an int in Python and floats to 1.0.
+
+  MALFORMED JSON REPORTS THE PARSE ERROR AND THE PATH, never a partial policy.
+
+Exit 0 only when a non-empty, fully-valid policy loaded and implies at least
+one flag. Diagnostics go to stderr, always: anything on stdout gets word-split
+straight into ci-gate's argv.
+
+Usage:
+  tools/policy-load.py [--file .loki-policy.json] [--json] [--as-args]
+"""
+
+import argparse
+import json
+import math
+import sys
+
+DEFAULT_FILE = ".loki-policy.json"
+
+# The entire schema. Two keys, because ci-gate enforces exactly two policies.
+# `workspace` is per-invocation and not a policy (and a path with a space would
+# silently split under $(...)); `json` is an output format. Neither belongs here.
+KNOWN_KEYS = ("max_usd", "require_receipt")
+
+
+class PolicyError(Exception):
+    """A policy that must not be handed to a gate."""
+
+
+def _check_max_usd(value):
+    # bool is a subclass of int: `true` would otherwise become a $1.00 ceiling.
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return "max_usd must be a number, got {!r}".format(value)
+    # NaN and Infinity are bare literals json.loads accepts. NaN loses every
+    # comparison, so a NaN ceiling never trips while looking like a number.
+    # isfinite raises OverflowError on a 400-digit int literal; that already
+    # fails closed, but a traceback is a worse message than a named reason.
+    try:
+        finite = math.isfinite(value)
+    except OverflowError:
+        finite = False
+    if not finite:
+        return "max_usd must be a finite number, got {!r}".format(value)
+    if value < 0:
+        return "max_usd must not be negative, got {!r}".format(value)
+    return None
+
+
+def _check_require_receipt(value):
+    # "true" is a string and is truthy; it is not a boolean policy.
+    if not isinstance(value, bool):
+        return "require_receipt must be true or false, got {!r}".format(value)
+    return None
+
+
+VALIDATORS = {
+    "max_usd": _check_max_usd,
+    "require_receipt": _check_require_receipt,
+}
+
+
+def load(path):
+    """Return a validated policy dict, or raise PolicyError naming the problem."""
+    try:
+        with open(path, encoding="utf-8") as handle:
+            raw = handle.read()
+    except FileNotFoundError:
+        raise PolicyError(
+            "no policy file at {}: a gate with no policy enforces nothing".format(path))
+    except OSError as exc:
+        raise PolicyError("cannot read {}: {}".format(path, exc))
+
+    if not raw.strip():
+        raise PolicyError(
+            "policy file is empty: {} -- an empty policy enforces nothing "
+            "while looking configured".format(path))
+
+    try:
+        policy = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise PolicyError("malformed JSON in {}: {}".format(path, exc))
+
+    if not isinstance(policy, dict):
+        raise PolicyError(
+            "policy in {} must be a JSON object, got {}".format(
+                path, type(policy).__name__))
+
+    # Named, sorted, and ALL of them: fixing one misspelling at a time across
+    # three re-runs is how the third one gets abandoned.
+    unknown = sorted(k for k in policy if k not in KNOWN_KEYS)
+    if unknown:
+        raise PolicyError(
+            "unknown policy key(s) in {}: {} -- known keys are: {}".format(
+                path, ", ".join(unknown), ", ".join(KNOWN_KEYS)))
+
+    # Iterate KNOWN_KEYS, not policy.items(): indexing VALIDATORS by a key
+    # straight from the file makes an unknown key a KeyError traceback instead
+    # of the named message above. That still exits non-zero, so the check looks
+    # tested while the operator gets a stack trace naming only the first typo.
+    problems = [msg for key in KNOWN_KEYS if key in policy
+                for msg in [VALIDATORS[key](policy[key])] if msg]
+    if problems:
+        raise PolicyError("invalid policy in {}: {}".format(path, "; ".join(problems)))
+
+    if not policy:
+        raise PolicyError(
+            "policy in {} is empty: a gate driven by an empty policy enforces "
+            "nothing while looking configured".format(path))
+
+    return policy
+
+
+def as_args(policy):
+    """The ci-gate flags this policy implies."""
+    args = []
+    if "max_usd" in policy:
+        args += ["--max-usd", repr(float(policy["max_usd"]))]
+    if policy.get("require_receipt"):
+        args.append("--require-receipt")
+    return args
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Load and validate a merge policy file for ci-gate.py.")
+    ap.add_argument("--file", default=DEFAULT_FILE,
+                    help="policy file to load; default {}".format(DEFAULT_FILE))
+    ap.add_argument("--json", action="store_true", dest="as_json",
+                    help="emit the validated policy as JSON")
+    ap.add_argument("--as-args", action="store_true", dest="args_only",
+                    help="emit the ci-gate flags this policy implies")
+    args = ap.parse_args(argv)
+
+    try:
+        policy = load(args.file)
+        flags = as_args(policy)
+        # require_receipt:false is valid, non-empty, and enforces NOTHING. Let
+        # it exit 0 and `ci-gate $(...)` runs with an empty argv -- the same
+        # vacuously-green gate this file exists to prevent, one level up.
+        if not flags:
+            raise PolicyError(
+                "policy in {} enforces nothing: it implies no ci-gate flags, so "
+                "the gate would run with nothing to check".format(args.file))
+    except PolicyError as exc:
+        print("policy-load: {}".format(exc), file=sys.stderr)
+        return 1
+
+    if args.args_only:
+        print(" ".join(flags))
+    elif args.as_json:
+        print(json.dumps(policy, indent=2, sort_keys=True))
+    else:
+        for key in sorted(policy):
+            print("{} = {}".format(key, json.dumps(policy[key])))
+        print("ci-gate args: {}".format(" ".join(flags)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/signing-status.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""Can this machine produce SIGNED receipts? Prove it, do not assume it.
+
+WHY THIS EXISTS. An unsigned Evidence Receipt proves INTEGRITY but not ORIGIN.
+The hash says the bytes were not tampered with; it says nothing about who
+produced them, and anyone can generate a receipt with a valid hash. Origin is
+the part a third party is actually buying. GPG signing closes that gap and has
+shipped since the proof generator learned LOKI_PROOF_GPG_KEY -- default OFF,
+undiscoverable, and silent when broken.
+
+Silent is the dangerous word. autonomy/lib/proof-generator.py:_gpg_detached_sign
+swallows EVERY failure and returns None: missing key, expired key, revoked key,
+a passphrase this environment cannot supply. Signing is best-effort by design so
+a gpg problem never blocks proof emission. The cost of that design is that a
+user who set LOKI_PROOF_GPG_KEY, believes receipts are signed, and has a broken
+key gets UNSIGNED receipts forever with no error anywhere. This tool is the only
+place that failure becomes visible.
+
+So the bar here is higher than "gpg is installed and a key id is set". That
+sentence is compatible with every one of the failures above. The only honest
+evidence that this machine can sign is a real detached-sign of a real payload
+followed by a real verify of the resulting signature -- with the SAME argv the
+receipt pipeline uses, or the round trip predicts nothing about the pipeline.
+
+FOUR STATES, NEVER A BOOLEAN. Collapsing these sends a user to debug the wrong
+thing, which for a security control is worse than saying nothing:
+
+    ok              round trip signed AND verified. Receipts carry origin.
+    broken          configured, and signing FAILED. Receipts silently unsigned.
+    not_configured  gpg works, LOKI_PROOF_GPG_KEY unset. Nothing is wrong.
+    gpg_absent      no gpg on PATH. Signing is impossible until installed.
+
+KEY MATERIAL NEVER LEAVES. A key ID is an identifier and is safe to print.
+Secret key bytes and passphrases are not, and gpg writes diagnostics to stderr
+that can quote them. Raw gpg stderr is therefore NEVER printed: it is
+classified into a known reason and only the classification is emitted. No
+--export path is invoked anywhere in this file. Requirement and implementation
+are the same line: print the reason, not the transcript.
+
+Read-only against the keyring: no key is created, deleted, imported, or
+modified. The round trip signs a scratch file in a temp dir that is removed
+afterwards, and uses the caller's real GNUPGHOME because the question being
+answered is whether the REAL keyring can sign.
+"""
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+# The payload is arbitrary: the round trip proves the KEY works, not that any
+# particular bytes are special. Fixed and tiny so a signature is fast.
+_SCRATCH_PAYLOAD = b"loki-signing-status round-trip probe\n"
+
+_TIMEOUT = 30
+
+# Ordered: the first match wins, so the more specific pattern precedes the
+# general one. Left side is matched against LOWERCASED gpg stderr; right side is
+# what the user is told. Never the raw stderr -- see the module docstring.
+_REASONS = (
+    ("no secret key", "no secret key for that key id in this keyring"),
+    ("secret key not available", "no secret key for that key id in this keyring"),
+    ("no default secret key", "no secret key for that key id in this keyring"),
+    ("unusable secret key", "the secret key is unusable (expired or revoked)"),
+    ("key has expired", "the key has expired"),
+    ("expired", "the key has expired"),
+    ("has been revoked", "the key has been revoked"),
+    ("revoked", "the key has been revoked"),
+    ("bad passphrase", "the passphrase was rejected"),
+    ("passphrase", "the key needs a passphrase this environment cannot supply"),
+    ("pinentry", "the key needs a passphrase this environment cannot supply"),
+    ("inappropriate ioctl", "the key needs a passphrase this environment cannot supply"),
+    ("no such file", "the key id does not resolve to a key in this keyring"),
+    ("not found", "the key id does not resolve to a key in this keyring"),
+)
+
+
+def _classify(stderr, fallback):
+    """Map gpg stderr onto a known reason. NEVER returns the stderr itself.
+
+    Anything unrecognized degrades to a generic fallback rather than leaking the
+    transcript, because the unrecognized case is exactly the one whose contents
+    cannot be predicted -- and therefore the one most likely to quote key
+    material or a passphrase prompt.
+    """
+    low = (stderr or "").lower()
+    for needle, reason in _REASONS:
+        if needle in low:
+            return reason
+    return fallback
+
+
+def _round_trip(key_id):
+    """Sign a scratch payload with key_id and verify the signature.
+
+    Returns (True, None) when the signature verified, else (False, reason).
+
+    The argv MUST mirror autonomy/lib/proof-generator.py:_gpg_detached_sign and
+    autonomy/lib/proof-verify.py:_verify_gpg. A round trip that signs some other
+    way can succeed while the receipt pipeline still emits unsigned, which would
+    make this tool confidently wrong in the one direction that matters.
+    """
+    tmp = tempfile.mkdtemp(prefix="loki-signing-status-")
+    try:
+        data_path = os.path.join(tmp, "payload.bin")
+        with open(data_path, "wb") as fh:
+            fh.write(_SCRATCH_PAYLOAD)
+
+        try:
+            signed = subprocess.run(
+                ["gpg", "--batch", "--yes", "--armor", "--detach-sign",
+                 "--local-user", key_id, "--output", "-"],
+                input=_SCRATCH_PAYLOAD, capture_output=True, timeout=_TIMEOUT,
+            )
+        except subprocess.TimeoutExpired:
+            # --batch should make gpg fail rather than prompt, but a wedged
+            # agent or a pinentry that ignores batch mode hangs instead. Never
+            # let this tool hang: a timeout IS a signing failure.
+            return False, "gpg timed out (a passphrase prompt is the usual cause)"
+        except OSError as exc:
+            return False, "gpg could not be executed (%s)" % type(exc).__name__
+
+        if signed.returncode != 0 or not signed.stdout:
+            stderr = signed.stderr.decode("utf-8", errors="replace")
+            return False, _classify(stderr, "gpg refused to sign with that key")
+
+        sig_path = os.path.join(tmp, "payload.sig")
+        with open(sig_path, "wb") as fh:
+            fh.write(signed.stdout)
+
+        try:
+            checked = subprocess.run(
+                ["gpg", "--verify", sig_path, data_path],
+                capture_output=True, timeout=_TIMEOUT,
+            )
+        except subprocess.TimeoutExpired:
+            return False, "gpg timed out verifying its own signature"
+        except OSError as exc:
+            return False, "gpg could not be executed (%s)" % type(exc).__name__
+
+        if checked.returncode != 0:
+            # gpg produced bytes that gpg itself will not accept. A naive
+            # "signing worked, we got output" check calls this state OK.
+            stderr = checked.stderr.decode("utf-8", errors="replace")
+            return False, _classify(
+                stderr, "gpg produced a signature it could not verify")
+
+        return True, None
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def evaluate(env=None):
+    """Resolve the signing state. Returns a JSON-safe dict.
+
+    Pure with respect to the keyring: reads it, changes nothing.
+    """
+    env = os.environ if env is None else env
+    gpg_path = shutil.which("gpg")
+    key_id = (env.get("LOKI_PROOF_GPG_KEY") or "").strip()
+
+    result = {
+        "gpg_installed": gpg_path is not None,
+        "gpg_path": gpg_path,
+        "key_id_set": bool(key_id),
+        # A key ID is an identifier, not key material: safe to echo back so the
+        # user can see WHICH key was tried.
+        "key_id": key_id or None,
+        "round_trip_verified": False,
+    }
+
+    if gpg_path is None:
+        result["status"] = "gpg_absent"
+        result["reason"] = "gpg is not on PATH"
+        result["next_command"] = "brew install gnupg   # or: apt-get install gnupg"
+        return result
+
+    if not key_id:
+        result["status"] = "not_configured"
+        result["reason"] = "LOKI_PROOF_GPG_KEY is not set"
+        result["next_command"] = (
+            "gpg --list-secret-keys --keyid-format=long   "
+            "# then: export LOKI_PROOF_GPG_KEY=<key-id>")
+        return result
+
+    verified, reason = _round_trip(key_id)
+    result["round_trip_verified"] = verified
+
+    # The single load-bearing line in this file. "ok" is reachable ONLY through
+    # a completed sign-and-verify round trip; every other path is a failure with
+    # a reason. Deriving status from gpg_installed and key_id_set instead would
+    # report ok for an expired key, which is the exact lie this tool exists to
+    # prevent.
+    result["status"] = "ok" if verified else "broken"
+
+    if verified:
+        result["reason"] = None
+        result["next_command"] = None
+    else:
+        result["reason"] = reason
+        result["next_command"] = (
+            "gpg --list-secret-keys --keyid-format=long   "
+            "# confirm %s is present and usable" % key_id)
+    return result
+
+
+# Exit codes are distinct per state so a caller can branch without parsing.
+# 0 means, and only means, a round trip completed.
+_EXIT = {"ok": 0, "broken": 1, "not_configured": 2, "gpg_absent": 3}
+
+_HEADLINE = {
+    "ok": "SIGNED    receipts from this machine carry a verifiable origin",
+    "broken": "BROKEN    receipts are being emitted UNSIGNED, silently",
+    "not_configured": "UNSIGNED  receipts prove integrity but NOT origin",
+    "gpg_absent": "UNSIGNED  signing is unavailable on this machine",
+}
+
+
+def render(result):
+    """Human-readable report. Contains no gpg transcript, by construction."""
+    status = result["status"]
+    lines = ["Receipt signing: %s" % _HEADLINE[status], ""]
+
+    lines.append("  gpg installed:      %s" % (
+        result["gpg_path"] if result["gpg_installed"] else "NO"))
+    lines.append("  LOKI_PROOF_GPG_KEY: %s" % (
+        result["key_id"] if result["key_id_set"] else "not set"))
+    lines.append("  sign+verify proof:  %s" % (
+        "PASS (round trip completed)" if result["round_trip_verified"]
+        else "not proven"))
+
+    if result.get("reason"):
+        lines += ["", "  Why: %s" % result["reason"]]
+
+    if status == "broken":
+        lines += [
+            "",
+            "  A key is configured but cannot sign. The proof generator treats",
+            "  signing as best-effort and swallows this failure, so receipts",
+            "  keep emitting UNSIGNED with no error. Nothing else reports it.",
+        ]
+    elif status == "not_configured":
+        lines += [
+            "",
+            "  Nothing is broken. Signing is opt-in and off. Turn it on to prove",
+            "  a receipt came from you and not merely that its bytes are intact.",
+        ]
+
+    if result.get("next_command"):
+        lines += ["", "  Next: %s" % result["next_command"]]
+
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        description="Report whether this machine can produce SIGNED receipts.")
+    parser.add_argument("--json", action="store_true",
+                        help="emit the result as JSON")
+    args = parser.parse_args(argv)
+
+    result = evaluate()
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        print(render(result))
+    return _EXIT[result["status"]]
+
+
+if __name__ == "__main__":
+    sys.exit(main())