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

package/VERSION

@@ -1 +1 @@
-8.93.0
+8.95.0

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "8.93.0"
+__version__ = "8.95.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.93.0";if(typeof Z==="string"&&Z.length>0)return h5=Z,h5;try{let X=Xf(Qf(import.meta.url)),Q=X$(X);h5=e_(Zf(Q,"VERSION"),"utf-8").trim()}catch{h5="unknown"}return h5}var h5=null;var BQ=p(()=>{H8()});var bO={};l0(bO,{runOrThrow:()=>jf,run:()=>E0,readStreamCapped:()=>NQ,commandVersion:()=>Tf,commandExists:()=>X9,ShellError:()=>Q$,MAX_STDOUT_BYTES:()=>yO});async function NQ(Z,X=yO){let Q=Z.getReader(),Y=new TextDecoder,J="",z=0;try{while(z<X){let{done:K,value:$}=await Q.read();if(K)break;if(!$)continue;if(z+=$.byteLength,z>X){let W=$.byteLength-(z-X);J+=Y.decode($.subarray(0,W),{stream:!0});break}J+=Y.decode($,{stream:!0})}J+=Y.decode()}finally{try{await Q.cancel()}catch{}Q.releaseLock()}return J}async function E0(Z,X={}){let Q=Bun.spawn({cmd:[...Z],stdout:"pipe",stderr:"pipe",env:X.env?{...process.env,...X.env}:process.env,cwd:X.cwd}),Y,J;if(X.timeoutMs&&X.timeoutMs>0)Y=setTimeout(()=>{try{Q.kill("SIGTERM")}catch{}J=setTimeout(()=>{try{Q.kill("SIGKILL")}catch{}},2000)},X.timeoutMs);try{let[z,K,$]=await Promise.all([NQ(Q.stdout),new Response(Q.stderr).text(),Q.exited]);return{stdout:z,stderr:K,exitCode:$}}finally{if(Y)clearTimeout(Y);if(J)clearTimeout(J)}}async function jf(Z,X={}){let Q=await E0(Z,X);if(Q.exitCode!==0)throw new Q$(`command failed (${Q.exitCode}): ${Z.join(" ")}`,Q.exitCode,Q.stdout,Q.stderr);return Q}async function X9(Z){let X=Mf(Z),Q=await E0(["sh","-c",`command -v ${X}`],{timeoutMs:5000});if(Q.exitCode===0)return Q.stdout.trim()||null;return null}function Mf(Z){if(!/^[A-Za-z0-9._/-]+$/.test(Z))throw Error(`refused to shell-escape suspect token: ${Z}`);return Z}async function Tf(Z,X="--version"){if(!await X9(Z))return null;let Y=await E0([Z,X],{timeoutMs:5000});if(Y.exitCode!==0)return null;return((Y.stdout||Y.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var yO=16777216,Q$;var x9=p(()=>{Q$=class Q$ extends Error{message;exitCode;stdout;stderr;constructor(Z,X,Q,Y){super(Z);this.message=Z;this.exitCode=X;this.stdout=Q;this.stderr=Y;this.name="ShellError"}}});function o7(Z){return wf?"":Z}var wf,L0,F8,p0,zV0,a0,W8,Q9,v;var S6=p(()=>{wf=(process.env.NO_COLOR??"").length>0;L0=o7("\x1B[0;31m"),F8=o7("\x1B[0;32m"),p0=o7("\x1B[1;33m"),zV0=o7("\x1B[0;34m"),a0=o7("\x1B[0;36m"),W8=o7("\x1B[1m"),Q9=o7("\x1B[2m"),v=o7("\x1B[0m")});import{existsSync as bf}from"fs";async function E7(){if(x4!==void 0)return x4;let Z="/opt/homebrew/bin/python3.12";if(bf(Z))return x4=Z,Z;let X=await X9("python3.12");if(X)return x4=X,X;let Q=await X9("python3");return x4=Q,Q}async function Y7(Z,X={}){let Q=await E7();if(!Q)return{stdout:"",stderr:"python3 not found",exitCode:127};return E0([Q,"-c",Z],X)}var x4;var r7=p(()=>{x9()});var ZL={};l0(ZL,{runStatus:()=>Kh});import{existsSync as Y9,readFileSync as g3,readdirSync as iO,statSync as aO}from"fs";import{resolve as h8,basename as rf}from"path";import{homedir as tf}from"os";function sO(Z){let X=Math.trunc(Z);if(X>=1e6)return`${(Math.trunc(X/1e6*10)/10).toFixed(1)}M`;if(X>=1000)return`${(Math.trunc(X/1000*10)/10).toFixed(1)}K`;return String(X)}function nO(Z,X,Q){if(X===0)return null;let Y=Math.trunc(Z*100/X),J=Math.trunc(Z*LQ/X);if(J>LQ)J=LQ;let z=LQ-J,K=F8;if(Y>=80)K=L0;else if(Y>=50)K=p0;let $="=".repeat(Math.max(0,J))+" ".repeat(Math.max(0,z)),W=sO(Z),V=sO(X);return`  ${W8}${Q}${v} ${K}[${$}]${v} ${Y}% (${W} / ${V})`}async function Zh(){if(await X9("jq"))return!0;return process.stdout.write(`${L0}Error: jq is required but not installed.${v}
+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}
 `),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=232EF166A0E3908D64756E2164756E21
+//# debugId=FD5A9EB9795BBFB164756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "8.93.0",
+  "version": "8.95.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.93.0",
+  "version": "8.95.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

@@ -334,11 +334,50 @@ def render(record):
     return "\n".join(lines)
 
 
+_USAGE = """usage: receipt-attest.py <proof.json> [--json]
+
+Turn a receipt into a portable ATTESTATION a third party can check without the
+original workspace.
+
+  --json    emit the attestation record as JSON
+  --help    show this message
+
+States, which are never collapsed into one another:
+  VERIFIED      the axis was checked and passed
+  FAILED        the axis was checked and failed
+  UNVERIFIABLE  the axis could NOT be checked here, with the reason
+
+Exit: 0 all scored axes verified, 1 something FAILED, 2 something was
+UNVERIFIABLE, 64 usage error.
+"""
+
+
 def main(argv):
-    args = [a for a in argv[1:] if a != "--json"]
-    as_json = "--json" in argv[1:]
+    rest = argv[1:]
+
+    # --help must print usage, NOT be read as a filename. It previously fell
+    # through to the positional slot and produced
+    # "UNVERIFIABLE -- proof file not found: --help", which is a verification
+    # verdict about a file the user never named: a fabricated answer to a
+    # question they did not ask.
+    if "--help" in rest or "-h" in rest:
+        sys.stdout.write(_USAGE)
+        return 0
+
+    as_json = "--json" in rest
+    args = [a for a in rest if a != "--json"]
+
+    # An unrecognized flag is an ERROR, never a path. Treating "--jsonn" as a
+    # proof file reports UNVERIFIABLE for a typo, which reads as a finding
+    # about the receipt rather than about the command line.
+    unknown = [a for a in args if a.startswith("-")]
+    if unknown:
+        sys.stderr.write("unknown option(s): %s\n" % " ".join(unknown))
+        sys.stderr.write(_USAGE)
+        return 64
+
     if len(args) != 1:
-        sys.stderr.write("usage: receipt-attest.py <proof.json> [--json]\n")
+        sys.stderr.write(_USAGE)
         return 64
     record = attest(args[0])
     print(json.dumps(record, indent=2, sort_keys=True) if as_json

package/tools/run-replay.py

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+"""Reconstruct what a completed run actually did, iteration by iteration.
+
+WHY. Unit cases prove the RULE. Only the recorded artifact proves the CASE.
+A run leaves a flight recorder behind -- .loki/events.jsonl plus the
+per-iteration efficiency records -- and until now reading it back meant either
+hand-parsing JSONL or running scripts/measure-run.sh, which renders ONE
+aggregate stage table for the whole run. An aggregate cannot answer the
+questions that matter after a bad run: did cost climb between iterations, did
+the same gate fail twice, which iteration was the slow one.
+
+This reads ONLY what a run already wrote. It starts nothing, spends nothing,
+and never contacts a provider. Replay is free.
+
+Usage:
+  tools/run-replay.py [workspace]      # default: .
+  tools/run-replay.py --json [ws]      # machine-readable
+
+THE HONESTY RULES, which are the point of this tool:
+
+  1. A truncated or unparseable line is COUNTED and REPORTED, never silently
+     dropped. measure-run.sh skips bad lines by design, so a corrupt tail
+     disappears without a trace and the replay reports a cleaner run than
+     happened. A replay that quietly loses data is worse than no replay.
+  2. An unmeasured cost reads UNKNOWN, never $0.00 -- via the single shared
+     record_is_measured() from autonomy/lib/efficiency_cost.py. Free and
+     unmeasured are different claims and only one of them is honest.
+  3. A stage that never emitted stage_complete reads "not recorded", NOT 0s.
+     0s reads as "instant", which is a different claim. Note a genuine
+     duration_s of 0 is real data (fast gates emit it) and is preserved.
+  4. An empty or missing events.jsonl says so and exits non-zero. An
+     empty-but-successful-looking replay certifies a run that never happened.
+"""
+
+import argparse
+import json
+import os
+import sys
+
+sys.dont_write_bytecode = True
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.dirname(_HERE)
+# Resolved from __file__, never from the workspace argument: the workspace
+# being replayed is a different tree and has no autonomy/lib.
+sys.path.insert(0, os.path.join(_REPO_ROOT, "autonomy", "lib"))
+
+from efficiency_cost import record_is_measured  # noqa: E402
+
+EXIT_NO_DATA = 66  # matches the missing-workspace convention in measure-run.sh
+
+
+def _load_events(path):
+    """Return (events, skipped_line_count).
+
+    Every line that does not parse into a dict is counted. The count is the
+    deliverable, not a debug aid: it is the only evidence that the replay is
+    reading a whole recording.
+    """
+    events = []
+    skipped = 0
+    with open(path, errors="replace") as fh:
+        for line in fh:
+            if not line.strip():
+                continue
+            try:
+                e = json.loads(line)
+            except Exception:
+                # MUTATION PROBE TARGET. The increment below is the probe's
+                # find-string and must stay the ONLY compound-assignment
+                # spelling of it in this file -- which is why the sibling
+                # branch writes the increment out longhand, and why this
+                # comment does not quote it. A probe whose find-string is
+                # ambiguous hits whichever copy comes first (here, a comment)
+                # and reports MUTATION SURVIVED, which is indistinguishable
+                # from a test that checks nothing.
+                skipped += 1
+                continue
+            if not isinstance(e, dict):
+                # A bare JSON scalar parses fine but is not a record.
+                skipped = skipped + 1
+                continue
+            events.append(e)
+    return events, skipped
+
+
+def _iter_key(value):
+    """Iteration number as an int, or None when unusable."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    try:
+        return int(str(value).strip())
+    except Exception:
+        return None
+
+
+def _read_cost(workspace, iteration):
+    """Per-iteration cost dict, or None when nothing was measured.
+
+    Read per FILE, not via collect_efficiency(): that sums the whole directory
+    into one aggregate, which cannot answer "did cost climb between
+    iterations". record_is_measured() is the shared rule and is applied here
+    unchanged -- a second copy of that predicate is how the honesty rule
+    drifts.
+    """
+    path = os.path.join(
+        workspace, ".loki", "metrics", "efficiency",
+        "iteration-%d.json" % iteration,
+    )
+    try:
+        with open(path) as fh:
+            rec = json.load(fh)
+    except Exception:
+        return None
+    if not isinstance(rec, dict) or not record_is_measured(rec):
+        return None
+    return {
+        "usd": float(rec.get("cost_usd") or 0.0),
+        "input_tokens": int(rec.get("input_tokens") or 0),
+        "output_tokens": int(rec.get("output_tokens") or 0),
+        "cache_read_tokens": int(rec.get("cache_read_tokens") or 0),
+        "cache_creation_tokens": int(rec.get("cache_creation_tokens") or 0),
+        "model": str(rec.get("model") or "") or None,
+    }
+
+
+def build_replay(workspace):
+    """Reconstruct the run. Returns a dict, or raises SystemExit on no data."""
+    events_path = os.path.join(workspace, ".loki", "events.jsonl")
+    if not os.path.isfile(events_path):
+        print("no events at %s -- pass the workspace directory of a "
+              "completed run" % events_path, file=sys.stderr)
+        raise SystemExit(EXIT_NO_DATA)
+
+    events, skipped = _load_events(events_path)
+
+    # An events file that exists but yields nothing usable is a no-data run.
+    # The skipped count still gets reported: a FULLY corrupt file is the worst
+    # case of the bug rule 1 guards, so it must never exit silently.
+    if not events:
+        print("events.jsonl at %s has no parseable records "
+              "(%d unparseable line(s) skipped) -- nothing to replay"
+              % (events_path, skipped), file=sys.stderr)
+        raise SystemExit(EXIT_NO_DATA)
+
+    # stages[iteration][stage] = {"duration_s": .., "status": ..}
+    stages = {}
+    iteration_status = {}
+    for e in events:
+        etype = e.get("type") or e.get("event")
+        data = e.get("data") if isinstance(e.get("data"), dict) else {}
+        if etype == "stage_complete":
+            it = _iter_key(data.get("iteration"))
+            name = data.get("stage")
+            secs = data.get("duration_s")
+            if it is None or not name:
+                continue
+            # isinstance guard, not truthiness: duration_s of 0 is REAL data
+            # from a fast gate. Filtering on falsy would convert a genuine 0
+            # into "not recorded" and break the absent-stage rule the other
+            # way round.
+            if isinstance(secs, bool) or not isinstance(secs, (int, float)):
+                continue
+            stages.setdefault(it, {})[str(name)] = {
+                "duration_s": float(secs),
+                "status": str(data.get("status") or "unknown"),
+            }
+        elif etype == "iteration_complete":
+            it = _iter_key(data.get("iteration"))
+            if it is not None:
+                iteration_status[it] = str(data.get("status") or "unknown")
+
+    # An events.jsonl truncated at a LINE BOUNDARY -- what a killed run
+    # leaves -- parses cleanly, so skipped_lines is 0 and the recording looks
+    # whole while a whole iteration is missing. The efficiency records are a
+    # second, independent witness to which iterations existed; without them
+    # the missing iteration's cost silently vanishes from the total and from
+    # "largest cost contributor", with no signal at all. A killed run is
+    # exactly the case this tool exists for.
+    numbers = set(stages) | set(iteration_status)
+    try:
+        for name in os.listdir(os.path.join(
+                workspace, ".loki", "metrics", "efficiency")):
+            if name.startswith("iteration-") and name.endswith(".json"):
+                n = _iter_key(name[len("iteration-"):-len(".json")])
+                if n is not None:
+                    numbers.add(n)
+    except Exception:
+        pass
+    numbers = sorted(numbers)
+    if not numbers:
+        print("no iteration or stage records in %s "
+              "(%d unparseable line(s) skipped) -- nothing to replay"
+              % (events_path, skipped), file=sys.stderr)
+        raise SystemExit(EXIT_NO_DATA)
+
+    # The stage vocabulary is the union actually observed, never a hardcoded
+    # list: a fixed list rots, and would claim stages were missing on runs
+    # that never had them.
+    all_stages = sorted({s for per in stages.values() for s in per})
+
+    iterations = []
+    prev_cost = None
+    prev_failed = set()
+    for n in numbers:
+        seen = stages.get(n, {})
+        cost = _read_cost(workspace, n)
+        failed = {s for s, v in seen.items() if v["status"] == "fail"}
+
+        # Only comparable when BOTH ends were measured. A delta against an
+        # unmeasured neighbour is a fabricated comparison.
+        delta = None
+        if cost is not None and prev_cost is not None:
+            delta = round(cost["usd"] - prev_cost["usd"], 6)
+
+        iterations.append({
+            "iteration": n,
+            "status": iteration_status.get(n),
+            "stages": {
+                s: (seen[s] if s in seen else None) for s in all_stages
+            },
+            "stages_not_recorded": [s for s in all_stages if s not in seen],
+            "cost": cost,
+            "cost_delta_usd": delta,
+            "cost_comparable": cost is not None and prev_cost is not None,
+            "gates_failed": sorted(failed),
+            "gates_failed_again": sorted(failed & prev_failed),
+        })
+        # NOT `cost if cost is not None else prev_cost`: carrying the last
+        # measured value across an unmeasured gap makes measured/unmeasured/
+        # measured compare iteration 3 against iteration 1 while labelling it
+        # "vs previous iteration". That is a fabricated comparison wearing a
+        # true-sounding label.
+        prev_cost = cost
+        prev_failed = failed
+
+    # Slowest stage overall, summed across iterations that recorded it.
+    totals = {}
+    for it in iterations:
+        for s, v in it["stages"].items():
+            if v is not None:
+                totals[s] = totals.get(s, 0.0) + v["duration_s"]
+    slowest = None
+    if totals:
+        name = max(totals, key=lambda k: totals[k])
+        slowest = {"stage": name, "total_s": round(totals[name], 1)}
+
+    measured = [it for it in iterations if it["cost"] is not None]
+    largest = None
+    if measured:
+        top = max(measured, key=lambda it: it["cost"]["usd"])
+        largest = {
+            "iteration": top["iteration"],
+            "usd": round(top["cost"]["usd"], 6),
+            "measured_iterations": len(measured),
+            "total_iterations": len(iterations),
+        }
+
+    return {
+        "workspace": os.path.abspath(workspace),
+        "read_only": True,
+        "skipped_lines": skipped,
+        "iterations": iterations,
+        "slowest_stage": slowest,
+        "largest_cost_contributor": largest,
+        "total_cost_usd": (
+            round(sum(it["cost"]["usd"] for it in measured), 6)
+            if measured else None
+        ),
+    }
+
+
+def _fmt_cost(cost):
+    if cost is None:
+        return "cost not recorded"
+    return "$%.4f  in %d / out %d / cache-read %d tok%s" % (
+        cost["usd"], cost["input_tokens"], cost["output_tokens"],
+        cost["cache_read_tokens"],
+        ("  [%s]" % cost["model"]) if cost["model"] else "",
+    )
+
+
+def render(rep):
+    out = []
+    out.append("RUN REPLAY -- reconstructed from artifacts only.")
+    out.append("Nothing was started and nothing was spent; this reads "
+               ".loki/ and exits.")
+    out.append("  workspace: %s" % rep["workspace"])
+    if rep["skipped_lines"]:
+        out.append("  UNPARSEABLE LINES SKIPPED: %d "
+                   "(counted, not dropped -- this replay is reading an "
+                   "incomplete recording)" % rep["skipped_lines"])
+    else:
+        out.append("  unparseable lines skipped: 0 (whole recording read)")
+    out.append("")
+
+    for i, it in enumerate(rep["iterations"]):
+        head = "ITERATION %d" % it["iteration"]
+        if it["status"]:
+            head += "  [%s]" % it["status"]
+        out.append(head)
+        out.append("-" * 60)
+        for name, v in it["stages"].items():
+            if v is None:
+                out.append("  %-24s not recorded" % name)
+            else:
+                out.append("  %-24s %6.0fs   %s"
+                           % (name, v["duration_s"], v["status"]))
+        out.append("  %-24s %s" % ("cost", _fmt_cost(it["cost"])))
+        if it["cost_delta_usd"] is not None:
+            direction = "climbed" if it["cost_delta_usd"] > 0 else "fell"
+            out.append("  %-24s %s $%+.4f vs previous iteration"
+                       % ("change", direction, it["cost_delta_usd"]))
+        elif it["cost"] is None:
+            out.append("  %-24s cannot compare, cost not recorded"
+                       % "change")
+        elif i > 0:
+            out.append("  %-24s cannot compare, previous iteration's cost "
+                       "not recorded" % "change")
+        if it["gates_failed"]:
+            out.append("  %-24s %s" % ("gates failed",
+                                       ", ".join(it["gates_failed"])))
+        if it["gates_failed_again"]:
+            out.append("  %-24s %s  <-- failed in the previous iteration too"
+                       % ("REPEAT FAILURE",
+                          ", ".join(it["gates_failed_again"])))
+        out.append("")
+
+    out.append("=" * 60)
+    if rep["slowest_stage"]:
+        out.append("slowest stage overall : %s (%.0fs across the run)"
+                   % (rep["slowest_stage"]["stage"],
+                      rep["slowest_stage"]["total_s"]))
+    else:
+        out.append("slowest stage overall : no stage durations recorded")
+
+    lg = rep["largest_cost_contributor"]
+    if lg is None:
+        out.append("largest cost          : cost not recorded for any "
+                   "iteration")
+    else:
+        out.append("largest cost          : iteration %d at $%.4f"
+                   % (lg["iteration"], lg["usd"]))
+        if lg["measured_iterations"] < lg["total_iterations"]:
+            # A claim over a subset must say it is a claim over a subset.
+            out.append("                        (largest among the %d of %d "
+                       "iterations that recorded cost)"
+                       % (lg["measured_iterations"], lg["total_iterations"]))
+        out.append("total measured cost   : $%.4f" % rep["total_cost_usd"])
+    return "\n".join(out)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        description="Replay a completed run from its artifacts. Reads only; "
+                    "starts nothing, spends nothing.")
+    ap.add_argument("workspace", nargs="?", default=".")
+    ap.add_argument("--json", action="store_true", dest="as_json")
+    args = ap.parse_args(argv)
+
+    rep = build_replay(args.workspace)
+    if args.as_json:
+        print(json.dumps(rep, indent=2))
+    else:
+        print(render(rep))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())