loki-mode 8.98.0 → 9.0.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.98.0
+# Loki Mode v9.0.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.98.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v9.0.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-8.98.0
+9.0.0

package/dashboard/__init__.py

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

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "8.98.0",
+  "version": "9.0.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.98.0",
+  "version": "9.0.0",
   "description": "Autonomous spec-to-product build system with a built-in trust layer (RARV-C closure loop, 8 quality gates, completion council). Ships Loki's spec-hardening, drift-detection, and deterministic PR verification commands plus the Loki MCP server.",
   "author": {
     "name": "Autonomi",

package/tools/baseline-pin.py

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

package/tools/gate-init.py

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

package/tools/run-replay.py

@@ -362,7 +362,27 @@ def main(argv=None):
     ap.add_argument("--json", action="store_true", dest="as_json")
     args = ap.parse_args(argv)
 
-    rep = build_replay(args.workspace)
+    # build_replay raises SystemExit on a no-data workspace, which bypassed
+    # --json entirely: the caller asked for machine output and got a bare text
+    # line, so `json.load(...)` crashed on the failure path -- unreadable to
+    # the exact automation this tool exists for. A structured error is still
+    # structured output; the exit code carries the verdict either way.
+    try:
+        rep = build_replay(args.workspace)
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else EXIT_NO_DATA
+        if args.as_json:
+            print(json.dumps({
+                "status": "no_data",
+                "exit_code": code,
+                "workspace": args.workspace,
+                "why": "no replayable artifacts under this workspace; "
+                       "see stderr for the specific path",
+                "iterations": [],
+                "skipped_lines": None,
+            }, indent=2))
+        return code
+
     if args.as_json:
         print(json.dumps(rep, indent=2))
     else: