loki-mode 9.2.0 → 9.4.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 v9.2.0
+# Loki Mode v9.4.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
 
 ---
 
-**v9.2.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v9.4.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-9.2.0
+9.4.0

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "9.2.0"
+__version__ = "9.4.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="9.2.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.4.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=F7F47FC30C33C44064756E2164756E21
+//# debugId=232D7DEBCB9B9EB464756E2164756E21

package/mcp/__init__.py

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

package/package.json

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

package/tools/cost-attribute.py

@@ -0,0 +1,394 @@
+#!/usr/bin/env python3
+"""Where did a run's cost and time actually GO, stage by stage.
+
+run-replay.py reconstructs a run along the ITERATION axis: what happened in
+iteration 3, did cost climb, did a gate fail twice. That is the right axis for
+debugging one bad run and the wrong axis for the question a team asks after
+paying the bill, which is about STAGES: is the money going to the agent, or to
+code review, or to a doc-generation step nobody reads.
+
+This reads only what a run already wrote -- .loki/events.jsonl and
+.loki/metrics/efficiency/iteration-*.json. It starts nothing and spends
+nothing.
+
+THE REFUSAL THAT IS THE WHOLE POINT OF THIS TOOL:
+
+    THERE IS NO PER-STAGE COST IN THE ARTIFACTS, SO NONE IS REPORTED.
+
+A stage_complete record carries a stage name, a duration and an iteration. An
+efficiency record carries dollars for a whole ITERATION. Nothing anywhere
+attributes a dollar to a stage. So the per-stage cost column here is a
+sentence, not a number.
+
+The tempting fix is not even dividing the iteration's cost evenly across its
+stages -- that is obviously invented and nobody would ship it. The tempting
+fix is weighting by duration: cost_usd * (stage_seconds / iteration_seconds).
+That is the SAME invention wearing a defensible-looking coat, and it is worse
+precisely because a reader will believe it. A stage that burns thirty seconds
+of wall clock spawning a linter costs nothing in tokens; a stage that spends
+ten seconds streaming a huge completion costs most of the iteration. Wall
+clock is not a cost proxy, and presenting it as one manufactures a fact the
+run never recorded.
+
+So the axes are reported separately and honestly:
+
+  TIME per stage      measured, summed over the iterations that recorded it
+  COST per iteration  measured, with unmeasured iterations EXCLUDED
+  the largest contributor is named on each axis, and labelled with which one
+
+THE OTHER HONESTY RULES, each of which this repo has paid for:
+
+  1. An iteration with no efficiency record reads "cost not recorded" and is
+     EXCLUDED from the total. Never summed as 0. A run of four iterations
+     where two were never measured must not report the two measured ones as
+     the whole bill -- so the total says how many of how many it covers.
+  2. A stage that never emitted stage_complete reads "not recorded", never
+     0s. 0s reads as "instant", a different claim. A genuine duration_s of 0
+     from a fast gate IS real data and survives as 0.
+  3. A corrupt event line is COUNTED and reported. A tool that silently skips
+     bad lines reports a cleaner run than happened, and drops them most often
+     when something upstream is broken.
+  4. Empty or missing events exits non-zero, EVEN IF the efficiency records
+     survived. An empty-looking report certifies a run that never happened,
+     and a cost table printed under the heading "cost attribution" when the
+     stage axis was never read over-claims its own subject.
+
+Usage:
+  tools/cost-attribute.py [workspace] [--json]
+
+Exit: 0 report produced, 3 events present but nothing parseable to attribute,
+66 no events file at all, 64 usage error.
+"""
+
+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 read 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
+
+OK, NOTHING_TO_CHECK, USAGE, NO_INPUT = 0, 3, 64, 66
+
+
+class _Parser(argparse.ArgumentParser):
+    """argparse exits 2 on a usage error, and 2 here means "could not check".
+
+    Those are opposite facts. "You typed the flag wrong" and "the instrument
+    is blind" must not share an exit code, because a CI job branching on 2
+    would treat a typo as a broken measurement and carry on.
+    """
+
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        print("%s: error: %s" % (self.prog, message), file=sys.stderr)
+        raise SystemExit(USAGE)
+
+
+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 load_events(path):
+    """Return (events, corrupt_line_count).
+
+    The count is a deliverable, not a debug aid: it is the only evidence that
+    this report is reading a whole recording.
+    """
+    events = []
+    corrupt = 0
+    with open(path, errors="replace") as fh:
+        for line in fh:
+            if not line.strip():
+                continue
+            try:
+                e = json.loads(line)
+            except Exception:
+                corrupt += 1
+                continue
+            if not isinstance(e, dict):
+                # A bare JSON scalar parses fine but is not a record.
+                corrupt = corrupt + 1
+                continue
+            events.append(e)
+    return events, corrupt
+
+
+def iteration_cost(workspace, iteration):
+    """One iteration's measured USD, or None when it was never measured.
+
+    Read per FILE rather than via collect_efficiency(), which sums the whole
+    directory into one aggregate and so cannot say WHICH iterations were
+    measured. record_is_measured() is the single shared rule and is applied
+    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
+    usd = rec.get("cost_usd")
+    if isinstance(usd, bool) or not isinstance(usd, (int, float)):
+        # Tokens were measured but no dollar figure was priced. That is a
+        # measured run with an unmeasured COST, and this tool sums dollars.
+        return None
+    return float(usd)
+
+
+def attribute(workspace):
+    """Build the attribution report. Returns (report dict, exit code)."""
+    events_path = os.path.join(workspace, ".loki", "events.jsonl")
+    if not os.path.isfile(events_path):
+        return {
+            "status": "no_events",
+            "workspace": os.path.abspath(workspace),
+            "why": "no events at %s -- pass the workspace directory of a "
+                   "completed run" % events_path,
+        }, NO_INPUT
+
+    events, corrupt = load_events(events_path)
+
+    # stage_seconds[stage] = [durations...]; iterations that recorded it.
+    stage_seconds = {}
+    stage_iterations = {}
+    seen_iterations = set()
+    for e in events:
+        data = e.get("data") if isinstance(e.get("data"), dict) else {}
+        it = _iter_key(data.get("iteration"))
+        if it is not None:
+            seen_iterations.add(it)
+        if (e.get("type") or e.get("event")) != "stage_complete":
+            continue
+        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 turn 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
+        stage_seconds.setdefault(str(name), []).append(float(secs))
+        stage_iterations.setdefault(str(name), set()).add(it)
+
+    # The efficiency directory is a SECOND, independent witness to which
+    # iterations existed. An events.jsonl truncated at a line boundary parses
+    # clean, so the corrupt count is 0 while a whole iteration is missing.
+    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:
+                    seen_iterations.add(n)
+    except Exception:
+        pass
+
+    # Keyed on PARSEABLE EVENTS, not on the union with the efficiency scan.
+    # Those records are a second witness to which iterations existed, and they
+    # are deliberately NOT enough to call this a report: the deliverable here
+    # is the STAGE axis, and stage records live only in events.jsonl. A
+    # workspace whose events file is empty or entirely corrupt, but whose
+    # efficiency records survive, would otherwise print a confident cost table
+    # under the heading "cost attribution" while the thing being attributed TO
+    # was never read. That is a report over-claiming its own subject, and it
+    # exits non-zero instead. cost-history.py and run-replay.py remain the
+    # right tools when only the cost axis is wanted.
+    if not events:
+        return {
+            "status": "nothing_to_attribute",
+            "workspace": os.path.abspath(workspace),
+            "corrupt_lines": corrupt,
+            "why": "%s has no parseable event records (%d corrupt line(s) "
+                   "counted) -- there is no stage axis to attribute to, so "
+                   "no attribution is reported even if efficiency records "
+                   "survived" % (events_path, corrupt),
+        }, NOTHING_TO_CHECK
+
+    stages = []
+    for name in sorted(stage_seconds):
+        secs = stage_seconds[name]
+        stages.append({
+            "stage": name,
+            "total_s": round(sum(secs), 1),
+            "iterations_recorded": len(stage_iterations[name]),
+            "recorded": True,
+        })
+
+    # Costs, per iteration. An unmeasured one carries None and is kept in the
+    # list so the report can say how much of the run the total covers.
+    per_iteration = []
+    for n in sorted(seen_iterations):
+        per_iteration.append({"iteration": n,
+                              "usd": iteration_cost(workspace, n)})
+
+    costs = [it["usd"] for it in per_iteration if it["usd"] is not None]
+    # `if costs else` would be a falsy test on the LIST, which is correct
+    # (an empty list is the only falsy list) -- but spelled explicitly so a
+    # later edit cannot quietly turn it into a test on the SUM, where a
+    # genuine total of 0.0 would flip to UNKNOWN.
+    total = round(sum(costs), 6) if len(costs) > 0 else None
+
+    slowest = None
+    if stages:
+        top = max(stages, key=lambda s: s["total_s"])
+        slowest = {"stage": top["stage"], "total_s": top["total_s"]}
+
+    # `if measured_iters`, not `if costs`: a run measured at exactly $0.00 is
+    # real data and still has a largest contributor. A falsy check would drop
+    # it, which is the measured-zero rule failing in the other direction. The
+    # list is also the SAME sequence `costs` came from, so this cannot be
+    # non-empty while that generator is empty.
+    measured_iters = [it for it in per_iteration if it["usd"] is not None]
+    priciest = None
+    if measured_iters:
+        top = max(measured_iters, key=lambda it: it["usd"])
+        priciest = {"iteration": top["iteration"], "usd": round(top["usd"], 6)}
+
+    return {
+        "status": "ok",
+        "workspace": os.path.abspath(workspace),
+        "read_only": True,
+        "corrupt_lines": corrupt,
+        "stages": stages,
+        "per_iteration_cost": per_iteration,
+        "measured_iterations": len(costs),
+        "total_iterations": len(per_iteration),
+        "total_measured_usd": total,
+        "slowest_stage": slowest,
+        "largest_cost_iteration": priciest,
+        "cost_per_stage": None,
+        "cost_per_stage_why": (
+            "REFUSED. events.jsonl records a stage's DURATION and the "
+            "efficiency records price a whole ITERATION; no artifact "
+            "attributes a dollar to a stage. Splitting the iteration cost by "
+            "each stage's share of wall clock would look like a measurement "
+            "and would not be one -- wall clock is not a token proxy. Time "
+            "per stage below is measured; cost per stage was never recorded."
+        ),
+    }, OK
+
+
+def render(rep):
+    if rep["status"] == "no_events":
+        return "NO DATA: %s" % rep["why"]
+    if rep["status"] == "nothing_to_attribute":
+        return "NOTHING TO ATTRIBUTE: %s" % rep["why"]
+
+    out = ["COST ATTRIBUTION -- read from artifacts only; nothing was started "
+           "and nothing was spent.",
+           "  workspace: %s" % rep["workspace"]]
+    if rep["corrupt_lines"]:
+        out.append("  CORRUPT LINES: %d (counted, not dropped -- this report "
+                   "is reading an incomplete recording)"
+                   % rep["corrupt_lines"])
+    else:
+        out.append("  corrupt lines: 0 (whole recording read)")
+    out.append("")
+
+    out.append("TIME PER STAGE (measured)")
+    out.append("-" * 60)
+    if rep["stages"]:
+        for s in rep["stages"]:
+            out.append("  %-24s %8.1fs   over %d iteration(s)"
+                       % (s["stage"], s["total_s"], s["iterations_recorded"]))
+    else:
+        out.append("  no stage emitted stage_complete -- stage timing not "
+                   "recorded for this run (not 0s, which would mean instant)")
+    out.append("")
+
+    out.append("COST PER ITERATION (measured)")
+    out.append("-" * 60)
+    for it in rep["per_iteration_cost"]:
+        if it["usd"] is None:
+            out.append("  iteration %-14d cost not recorded  (excluded from "
+                       "the total)" % it["iteration"])
+        else:
+            out.append("  iteration %-14d $%.4f" % (it["iteration"], it["usd"]))
+    out.append("")
+
+    out.append("COST PER STAGE")
+    out.append("-" * 60)
+    for chunk in rep["cost_per_stage_why"].split(" -- "):
+        out.append("  %s" % chunk)
+    out.append("")
+
+    out.append("=" * 60)
+    if rep["slowest_stage"]:
+        out.append("largest time contributor : %s (%.1fs across the run)"
+                   % (rep["slowest_stage"]["stage"],
+                      rep["slowest_stage"]["total_s"]))
+    else:
+        out.append("largest time contributor : not recorded, no stage "
+                   "durations in this run")
+
+    if rep["total_measured_usd"] is None:
+        out.append("largest cost contributor : cost not recorded for any of "
+                   "the %d iteration(s)" % rep["total_iterations"])
+        out.append("total measured cost      : UNKNOWN (0 of %d iterations "
+                   "measured; unmeasured is not free)"
+                   % rep["total_iterations"])
+    else:
+        out.append("largest cost contributor : iteration %d at $%.4f"
+                   % (rep["largest_cost_iteration"]["iteration"],
+                      rep["largest_cost_iteration"]["usd"]))
+        out.append("total measured cost      : $%.4f  (%d of %d iterations "
+                   "measured)"
+                   % (rep["total_measured_usd"], rep["measured_iterations"],
+                      rep["total_iterations"]))
+        if rep["measured_iterations"] < rep["total_iterations"]:
+            # A claim over a subset must say it is a claim over a subset.
+            out.append("                           the %d unmeasured "
+                       "iteration(s) are excluded, not counted as free, so "
+                       "the real bill is HIGHER than this."
+                       % (rep["total_iterations"]
+                          - rep["measured_iterations"]))
+    return "\n".join(out)
+
+
+def main(argv=None):
+    ap = _Parser(
+        description="Attribute a run's cost and time to where they went, "
+                    "per stage. Reads only; starts nothing, spends nothing.")
+    ap.add_argument("workspace", nargs="?", default=".",
+                    help="workspace root containing .loki/ (default .)")
+    ap.add_argument("--json", action="store_true", dest="as_json",
+                    help="emit the report as JSON")
+    args = ap.parse_args(argv)
+
+    rep, code = attribute(args.workspace)
+    if args.as_json:
+        # A structured error is still structured output. The caller asked for
+        # machine-readable and must not get a bare text line on the failure
+        # path; the exit code carries the verdict either way.
+        print(json.dumps(rep, indent=2))
+    else:
+        print(render(rep), file=sys.stderr if code else sys.stdout)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())