loki-mode 8.89.0 → 8.91.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.89.0
+# Loki Mode v8.91.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.89.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v8.91.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-8.89.0
+8.91.0

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "8.89.0"
+__version__ = "8.91.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.89.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.91.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=C2908F5759B1B75564756E2164756E21
+//# debugId=8791DC1CFDEF673D64756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "8.89.0",
+  "version": "8.91.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.89.0",
+  "version": "8.91.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/receipt-attest.py

@@ -0,0 +1,350 @@
+#!/usr/bin/env python3
+"""Turn a receipt into a portable ATTESTATION a third party can check.
+
+WHY THIS EXISTS. `loki proof verify` answers "is this receipt good, here, in
+this workspace". That answer is not portable: it needs the original repository.
+The commercial position is being the NOTARY for the category -- verifying
+receipts, including ones this machine did not produce. A notary that needs the
+original workspace is not a notary.
+
+So this emits a compact record of WHAT WAS ACTUALLY CHECKED, and by
+construction it cannot claim more than that.
+
+THE DEFECT THIS PREVENTS. Three states exist and most systems ship two:
+
+    VERIFIED      checked, passed
+    FAILED        checked, failed
+    UNVERIFIABLE  could not be checked here, with the reason
+
+Collapsing the third into either of the first two is the whole defect. Folded
+into FAILED, an honest receipt looks forged whenever you read it from the wrong
+directory. Folded into VERIFIED -- the dangerous direction -- an unchecked axis
+acquires a credential it never earned. That is not a missing feature; it is
+laundering uncertainty into a signed-looking claim, which is strictly worse
+than issuing no attestation at all.
+
+Nothing here re-implements verification. `verify()` in autonomy/lib/
+proof-verify.py is the single source of truth (it calls verify_integrity()
+internally at line 726 and spreads its fields), and this module's only job is
+to project that result onto the three states without losing the third.
+
+Usage:
+    tools/receipt-attest.py <proof.json> [--json]
+
+Exit codes:
+    0  every scored axis was checked here and passed
+    1  at least one axis FAILED
+    2  nothing failed, but at least one axis was UNVERIFIABLE -- including a
+       receipt that could not be loaded at all
+
+An UNSIGNED receipt does not by itself sink the verdict (see _signature_axis:
+there is nothing to check, and verify() makes the same call upstream), but the
+caveat is carried on the summary line of every verdict so an exit 0 can never
+be mistaken for proof of origin.
+"""
+
+import hashlib
+import importlib.util
+import json
+import os
+import pathlib
+import sys
+
+# A stale .pyc for a hyphenated module loaded by path makes mutation probes
+# report FALSE failures (the probe edits the source, the loader serves the old
+# bytecode). Must be set before the loader below runs.
+sys.dont_write_bytecode = True
+
+_LIB = pathlib.Path(__file__).resolve().parents[1] / "autonomy" / "lib"
+_spec = importlib.util.spec_from_file_location(
+    "proof_verify", _LIB / "proof-verify.py")
+_pv = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(_pv)
+
+VERIFIED = "VERIFIED"
+FAILED = "FAILED"
+UNVERIFIABLE = "UNVERIFIABLE"
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_UNVERIFIABLE = 2
+
+
+def _tri(value, reason_if_unverifiable):
+    """Project a three-valued verifier field onto the three states.
+
+    True -> VERIFIED, False -> FAILED, None -> UNVERIFIABLE. `is` comparisons
+    are load-bearing: the verifier also uses the truthy string "n/a", and `if
+    value:` would read that as a pass.
+    """
+    if value is True:
+        return {"state": VERIFIED, "reason": ""}
+    if value is False:
+        return {"state": FAILED, "reason": ""}
+    return {"state": UNVERIFIABLE, "reason": reason_if_unverifiable}
+
+
+def _pick(reasons, *needles):
+    """First verifier reason mentioning any needle, so an UNVERIFIABLE axis
+    carries the verifier's own explanation rather than a generic one."""
+    for reason in reasons or []:
+        low = reason.lower()
+        if any(n in low for n in needles):
+            return reason
+    return ""
+
+
+def _signature_axis(proof, gpg_ok):
+    """Signature status as three states, never a boolean.
+
+    THE TRAP. _verify_gpg (proof-verify.py:477) returns "n/a" for TWO
+    different situations: no signature recorded, AND a signature recorded
+    while gpg is absent from PATH. Reading gpg_ok alone therefore reports a
+    signed receipt as "unsigned" on any machine without gpg -- the exact
+    collapse this file exists to prevent, one layer down. So presence of the
+    signature is read from the receipt itself, and only the no-signature case
+    is allowed to mean unsigned.
+
+    WHY UNSIGNED DOES NOT SINK THE VERDICT. "No signature exists" is not "a
+    check I could not run" -- there is nothing to verify, so scoring it as
+    UNVERIFIABLE would make VERIFIED unreachable for every receipt produced
+    without LOKI_PROOF_GPG_KEY, which is the default. verify() already made
+    this call upstream: its rollup is `gpg_ok in (True, "n/a")`, and it
+    surfaces the caveat as generator_trusted rather than as a failure. This
+    projects that decision instead of inventing a stricter one.
+
+    signed_uncheckable is the opposite case and IS scored: a signature is
+    recorded and we genuinely could not evaluate it. Keeping those two apart
+    is the whole point of reading the receipt rather than gpg_ok alone.
+    """
+    verification = proof.get("verification")
+    signature = (verification or {}).get("gpg_signature") if isinstance(
+        verification, dict) else None
+
+    if not signature:
+        # Stated, never scored. scored=False keeps this out of the verdict
+        # rollup while the caveat still rides along in the summary line, so an
+        # exit 0 on an unsigned receipt can never be read as "origin proven".
+        return {
+            "state": "UNSIGNED",
+            "status": "unsigned",
+            "scored": False,
+            "reason": "the receipt carries no gpg signature, so its origin "
+                      "rests on the generator that produced it, not on "
+                      "cryptographic proof",
+        }
+    if gpg_ok is True:
+        return {"state": VERIFIED, "status": "signed_valid", "scored": True,
+                "reason": ""}
+    if gpg_ok is False:
+        return {
+            "state": FAILED,
+            "status": "signed_invalid",
+            "scored": True,
+            "reason": "a gpg signature is recorded but does not verify "
+                      "against the canonical receipt bytes",
+        }
+    return {
+        "state": UNVERIFIABLE,
+        "status": "signed_uncheckable",
+        "scored": True,
+        "reason": "a gpg signature is recorded but gpg is not available "
+                  "here, so it could be neither confirmed nor refuted",
+    }
+
+
+def attest(proof_path, repo_dir="."):
+    """Build the attestation record. Pure: no writes, no network."""
+    try:
+        proof = _pv._load_proof(proof_path)
+    except _pv.ProofLoadError as exc:
+        return {
+            "attestation": "loki-receipt-attestation/v1",
+            "receipt": os.path.basename(str(proof_path)),
+            "receipt_sha256": None,
+            "checked_from": os.path.abspath(repo_dir),
+            "axes": {},
+            "signature": {
+                "state": UNVERIFIABLE,
+                "status": "unsigned",
+                "reason": "the receipt could not be loaded",
+            },
+            "verdict": UNVERIFIABLE,
+            "summary": "UNVERIFIABLE -- %s" % exc,
+        }
+
+    result = _pv.verify(proof_path, repo_dir)
+    reasons = result.get("reasons") or []
+
+    # The receipt's own identity. Hash the canonical bytes the verifier
+    # hashes (verification stripped), so an attestation is comparable across
+    # machines regardless of key ordering or whitespace in the file.
+    unsigned = dict(proof)
+    unsigned.pop("verification", None)
+    receipt_sha = hashlib.sha256(
+        _pv._canonical(unsigned).encode("utf-8")).hexdigest()
+
+    axes = {}
+
+    # Integrity: hash_ok is a plain bool from the verifier -- always checked.
+    axes["integrity"] = _tri(bool(result.get("hash_ok")), "")
+    if axes["integrity"]["state"] == FAILED:
+        axes["integrity"]["reason"] = _pick(
+            reasons, "hash mismatch", "integrity hash") or \
+            "the recorded integrity hash does not match the receipt bytes"
+
+    # Drift: the axis that genuinely cannot be checked away from the repo.
+    axes["drift"] = _tri(
+        result.get("diff_drift") is False if result.get("diff_drift") is not None
+        else None,
+        _pick(reasons, "drift unverifiable") or
+        "the recorded diff could not be re-derived here",
+    )
+    if result.get("diff_drift") is True:
+        axes["drift"] = {
+            "state": FAILED,
+            "reason": _pick(reasons, "diff drift") or
+            "the recorded diff no longer matches the repository",
+        }
+
+    # Headline consistency and cost coherence are None when not derivable.
+    axes["headline"] = _tri(
+        result.get("headline_consistent"),
+        "the receipt records no headline or no facts to re-derive it from",
+    )
+    if axes["headline"]["state"] == FAILED:
+        axes["headline"]["reason"] = _pick(reasons, "headline") or \
+            "the headline disagrees with the recorded facts"
+
+    axes["cost"] = _tri(
+        result.get("cost_coherent"),
+        "the receipt records no cost block to check for coherence",
+    )
+    if axes["cost"]["state"] == FAILED:
+        axes["cost"]["reason"] = _pick(reasons, "cost claim") or \
+            "the recorded cost contradicts itself"
+
+    # Workspace tree. Every real receipt carries one (proof-generator.py:1190
+    # writes tree_sha256 unconditionally), and verify() scores it. Dropping it
+    # here meant a receipt verify() REJECTED for tree drift still attested
+    # VERIFIED with exit 0 -- an axis silently defaulting to "passed" purely
+    # because the projection forgot it, which is the exact laundering this
+    # tool exists to prevent.
+    #
+    # tree_drift is None both when nothing was recorded and when the digest
+    # could not be recomputed, so disambiguate on the recorded value: no
+    # recorded digest is not an axis at all (nothing to check, like unsigned),
+    # while a recorded digest we could not recompute is genuinely
+    # UNVERIFIABLE.
+    recorded_tree = (result.get("tree_recheck") or {}).get("recorded")
+    if recorded_tree:
+        axes["tree"] = _tri(
+            result.get("tree_drift") is False
+            if result.get("tree_drift") is not None else None,
+            _pick(reasons, "tree unverifiable", "workspace tree unverifiable")
+            or "the receipt records a workspace tree digest, but the current "
+               "tree could not be re-derived here",
+        )
+        if result.get("tree_drift") is True:
+            axes["tree"] = {
+                "state": FAILED,
+                "reason": _pick(reasons, "workspace tree drift") or
+                "the recorded workspace tree digest no longer matches",
+            }
+
+    signature = _signature_axis(proof, result.get("gpg_ok"))
+
+    scored = dict(axes)
+    if signature.get("scored"):
+        scored["signature"] = signature
+
+    states = [a["state"] for a in scored.values()]
+    if FAILED in states:
+        verdict = FAILED
+    elif UNVERIFIABLE in states:
+        verdict = UNVERIFIABLE
+    else:
+        verdict = VERIFIED
+
+    failed = sorted(k for k, a in scored.items() if a["state"] == FAILED)
+    unchecked = sorted(k for k, a in scored.items()
+                       if a["state"] == UNVERIFIABLE)
+    passed = sorted(k for k, a in scored.items() if a["state"] == VERIFIED)
+
+    # The unsigned caveat rides on every verdict, including a passing one. An
+    # exit 0 is only honest if the thing it does NOT cover is impossible to
+    # miss on the line a human actually reads.
+    caveat = ("; receipt is UNSIGNED, so origin rests on its generator"
+              if signature["status"] == "unsigned" else "")
+
+    if verdict == FAILED:
+        summary = "FAILED -- %s did not pass here%s" % (
+            ", ".join(failed), caveat)
+    elif verdict == UNVERIFIABLE:
+        summary = "UNVERIFIABLE -- %s passed, but %s could not be checked here%s" % (
+            ", ".join(passed) or "nothing", ", ".join(unchecked), caveat)
+    else:
+        summary = "VERIFIED -- every axis checked here passed%s" % caveat
+
+    return {
+        "attestation": "loki-receipt-attestation/v1",
+        "receipt": os.path.basename(str(proof_path)),
+        "receipt_sha256": receipt_sha,
+        "checked_from": os.path.abspath(repo_dir),
+        "axes": axes,
+        "signature": signature,
+        # Carried straight from verify(): True means the facts are taken at
+        # face value because no valid signature vouches for them.
+        "generator_trusted": bool(result.get("generator_trusted")),
+        "verdict": verdict,
+        "summary": summary,
+    }
+
+
+def exit_code(record):
+    """Exit 0 ONLY when nothing failed and nothing was left unchecked.
+
+    An UNVERIFIABLE axis must not exit 0: a confident 0 is what a caller in a
+    `&&` chain reads as "attested", which would re-collapse the third state at
+    the shell boundary after this module worked to keep it separate. It gets
+    its own code rather than sharing 1, so a consumer can distinguish "this
+    receipt is bad" (1) from "fetch the repo and re-run" (2).
+    """
+    if record.get("verdict") == FAILED:
+        return EXIT_FAILED
+    if record.get("verdict") == UNVERIFIABLE:
+        return EXIT_UNVERIFIABLE
+    return EXIT_OK
+
+
+def render(record):
+    lines = [record["summary"], ""]
+    lines.append("receipt      %s" % record["receipt"])
+    lines.append("sha256       %s" % (record["receipt_sha256"] or "unknown"))
+    lines.append("checked from %s" % record["checked_from"])
+    lines.append("")
+    for name, axis in record["axes"].items():
+        lines.append("%-10s %s" % (name, axis["state"]))
+        if axis.get("reason"):
+            lines.append("           %s" % axis["reason"])
+    sig = record["signature"]
+    lines.append("%-10s %s (%s)" % ("signature", sig["state"], sig["status"]))
+    if sig.get("reason"):
+        lines.append("           %s" % sig["reason"])
+    return "\n".join(lines)
+
+
+def main(argv):
+    args = [a for a in argv[1:] if a != "--json"]
+    as_json = "--json" in argv[1:]
+    if len(args) != 1:
+        sys.stderr.write("usage: receipt-attest.py <proof.json> [--json]\n")
+        return 64
+    record = attest(args[0])
+    print(json.dumps(record, indent=2, sort_keys=True) if as_json
+          else render(record))
+    return exit_code(record)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/tools/tool-index.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""List the tools that ship with loki, and say which ones a user can reach.
+
+WHY THIS EXISTS. Eleven tools live under tools/ and NONE of them appears in
+`loki help`. Every one was built, tested, packaged -- and left undiscoverable.
+That is the same shape this repo has now paid for seven times: auto-detection
+sat unwired from v5.0.0 to v8.64.0; the receipt's own `--human` explanation
+shipped in v8.73.0 and reached no CLI path until v8.84.0; `preflight.sh` was
+released in v8.87.0 into a directory that is not in package.json `files[]`, so
+no npm user could run it at all.
+
+A capability nobody can find is worth exactly as much as one that does not
+exist. This is the cheapest possible fix for that class: a single honest index.
+
+THE HONESTY RULES, which this repo has spent 13+ surfaces establishing and
+which apply to an index just as much as to a cost figure:
+
+  - A tool with no description reads "(no description)", never an invented one.
+    Guessing a summary from a filename is fabrication; the reader cannot tell a
+    guess from a fact, so the guess is worse than the gap.
+
+  - SHIPPED status is derived from package.json `files[]`, the same source npm
+    uses. A tool present in the repo but absent from the tarball is reported as
+    NOT SHIPPED rather than silently listed alongside the reachable ones. That
+    is exactly the v8.87.0 defect, and an index that hid it would have helped
+    the release lie.
+
+  - An empty tools/ directory says so and exits non-zero. Zero tools is not a
+    successful listing.
+
+Reads the filesystem only. Starts nothing, spends nothing, contacts nothing.
+"""
+
+import argparse
+import ast
+import json
+import os
+import sys
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_ROOT = os.path.dirname(_HERE)
+
+NO_DESC = "(no description)"
+
+
+def _first_sentence(text):
+    """First line of a docstring or header block, trimmed.
+
+    Deliberately does NOT reflow or summarise: the author's own first line is
+    reported verbatim, so nothing here can invent a claim the tool does not make.
+    """
+    for raw in (text or "").splitlines():
+        line = raw.strip()
+        if line:
+            return line if len(line) <= 100 else line[:97] + "..."
+    return ""
+
+
+def describe(path):
+    """Pull a one-line description from a tool, or report its absence.
+
+    Python: the module docstring, parsed rather than regexed, so a `#` inside a
+    string literal cannot be mistaken for a comment.
+    Shell: the first comment block under the shebang.
+    """
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            src = fh.read()
+    except OSError:
+        return NO_DESC
+
+    if path.endswith(".py"):
+        try:
+            doc = ast.get_docstring(ast.parse(src))
+        except SyntaxError:
+            doc = None
+        return _first_sentence(doc) or NO_DESC
+
+    lines = []
+    for raw in src.splitlines():
+        if raw.startswith("#!"):
+            continue
+        if raw.startswith("#"):
+            lines.append(raw.lstrip("#").strip())
+            continue
+        if lines:
+            break
+        if raw.strip():
+            break
+    return _first_sentence("\n".join(lines)) or NO_DESC
+
+
+def _files_globs():
+    """The `files[]` entries from package.json, or None when unreadable.
+
+    None means UNKNOWN, never "nothing ships": an unreadable manifest is an
+    absent measurement, and reporting every tool as unshipped on that basis
+    would be its own fabrication.
+    """
+    try:
+        with open(os.path.join(_ROOT, "package.json"), encoding="utf-8") as fh:
+            return json.load(fh).get("files") or []
+    except (OSError, ValueError):
+        return None
+
+
+def ships(rel, globs):
+    """True/False/None -- shipped, not shipped, or manifest unknown."""
+    if globs is None:
+        return None
+    for entry in globs:
+        if rel == entry:
+            return True
+        if entry.endswith("/") and rel.startswith(entry):
+            return True
+    return False
+
+
+def collect(tools_dir=None):
+    tools_dir = tools_dir or os.path.join(_ROOT, "tools")
+    globs = _files_globs()
+    out = []
+    try:
+        names = sorted(os.listdir(tools_dir))
+    except OSError:
+        return out
+    for name in names:
+        if not (name.endswith(".py") or name.endswith(".sh")):
+            continue
+        full = os.path.join(tools_dir, name)
+        if not os.path.isfile(full):
+            continue
+        out.append({
+            "name": name,
+            "path": "tools/" + name,
+            "description": describe(full),
+            "shipped": ships("tools/" + name, globs),
+        })
+    return out
+
+
+def render(rows):
+    lines = ["loki tools", ""]
+    width = max([len(r["name"]) for r in rows] + [4])
+    for r in rows:
+        if r["shipped"] is True:
+            mark = "     "
+        elif r["shipped"] is False:
+            mark = "[dev]"
+        else:
+            mark = "[ ? ]"
+        lines.append("  %s %-*s  %s" % (mark, width, r["name"], r["description"]))
+    lines.append("")
+    unshipped = [r["name"] for r in rows if r["shipped"] is False]
+    if unshipped:
+        lines.append("[dev] = present in this checkout but NOT in the npm package")
+        lines.append("       (not in package.json files[]): " + ", ".join(unshipped))
+    if any(r["shipped"] is None for r in rows):
+        lines.append("[ ? ] = package.json could not be read, so shipping is UNKNOWN")
+    lines.append("Run one with: python3 tools/<name>   (this index reads files only)")
+    return "\n".join(lines)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description="List loki's bundled tools.")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--tools-dir", default=None)
+    args = ap.parse_args(argv)
+
+    rows = collect(args.tools_dir)
+    if not rows:
+        # Zero tools is not a successful listing.
+        msg = "no tools found under tools/ -- nothing to list"
+        if args.json:
+            print(json.dumps({"tools": [], "error": msg}, indent=2))
+        else:
+            print(msg, file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps({"tools": rows, "count": len(rows)}, indent=2))
+    else:
+        print(render(rows))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())