loki-mode 9.21.0 → 9.22.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.21.0
+# Loki Mode v9.22.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -470,4 +470,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v9.21.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v9.22.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-9.21.0
+9.22.0

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "9.21.0"
+__version__ = "9.22.0"
 
 # Expose the control app for easy import
 try:

package/docs/OUTCOME-CANARY-EVALUATION.md

@@ -0,0 +1,65 @@
+# Outcome Canary Evaluation
+
+`outcome-canary-evaluate.py` converts consented, locally recorded canary
+observations into one deterministic aggregate verdict. It never invokes a provider,
+changes an assignment, or promotes a route.
+
+```bash
+python3 tools/outcome-canary-evaluate.py report.json observations.json \
+  --enable-evaluation --control-route safe --canary-percent 10 --json
+```
+
+Evaluation is opt-in. Without `--enable-evaluation`, the command refuses.
+
+## Observation contract
+
+The input is one `loki-outcome-canary-observations/v1` JSON object:
+
+```json
+{
+  "observations": "loki-outcome-canary-observations/v1",
+  "report_sha256": "<sha256 of the exact router report>",
+  "source_sha256": "<source_sha256 from that report>",
+  "items": [
+    {
+      "subject": "locally chosen opaque key",
+      "assignment": "control",
+      "route": "safe",
+      "accepted": true,
+      "risk": 0.1
+    }
+  ]
+}
+```
+
+Each item has exactly those five fields. Subjects must be unique and non-empty;
+`accepted` is a JSON Boolean; and `risk` is a finite number from zero through one.
+The file is capped at 5 MiB and 100,000 observations. Duplicate JSON keys are
+rejected.
+
+The evaluator hashes the exact report and observation bytes, rechecks the report's
+underlying source digest, and reruns the released deterministic canary assignment
+for every subject. A recorded arm or route that does not match that assignment
+refuses the entire evaluation. Output contains no subject keys.
+
+## Verdict policy
+
+Both arms must reach `--min-samples` (default 5). The tool computes integer accepted
+basis points and mean observed risk for each arm.
+
+- `ROLLBACK`: canary acceptance is below control, or canary mean risk exceeds
+  `--max-risk` (default 0.25).
+- `PROMOTE`: canary acceptance lift reaches `--min-lift-bps` (default 1) and canary
+  mean risk is no higher than control.
+- `HOLD`: the evidence is valid and sufficiently sampled but meets neither rule.
+
+These are offline recommendations, not routing actions. A consented operator still
+controls whether to apply any change. Malformed, drifted, mismatched, sparse, or
+unbound evidence returns `REFUSED` rather than a partial verdict.
+
+## Output and exit codes
+
+`--json` emits the aggregate arms, policy, exact evidence digests, verdict, and
+refusal reasons. The default output is a short human-readable summary. Exit 0 means
+a verdict was produced (including `ROLLBACK`), 3 means evaluation was refused, 64
+is an invocation error, and 66 is a missing input file.

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var p_=Object.create;var{getPrototypeOf:d_,defineProperty:eK,getOwnPropertyNames:c_}=Object;var l_=Object.prototype.hasOwnProperty;function i_(Z){return this[Z]}var a_,s_,n_=(Z,X,Q)=>{var Y=Z!=null&&typeof Z==="object";if(Y){var J=X?a_??=new WeakMap:s_??=new WeakMap,z=J.get(Z);if(z)return z}Q=Z!=null?p_(d_(Z)):{};let K=X||!Z||!Z.__esModule?eK(Q,"default",{value:Z,enumerable:!0}):Q;for(let $ of c_(Z))if(!l_.call(K,$))eK(K,$,{get:i_.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 o_=(Z)=>Z;function r_(Z,X){this[Z]=o_.bind(null,X)}var l0=(Z,X)=>{for(var Q in X)eK(Z,Q,{get:X[Q],enumerable:!0,configurable:!0,set:r_.bind(X,Q)})};var p=(Z,X)=>()=>(Z&&(X=Z(Z=0)),X);var t0=import.meta.require;var xO={};l0(xO,{lokiDir:()=>j0,homeLokiDir:()=>R4,findRepoRootForVersion:()=>X$,REPO_ROOT:()=>i0});import{resolve as n7,dirname as Z$}from"path";import{fileURLToPath as t_}from"url";import{existsSync as UQ}from"fs";import{homedir as e_}from"os";function Zf(){let Z=kO;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(kO,"..","..","..")}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(e_(),".loki")}var kO,i0;var H8=p(()=>{kO=Z$(t_(import.meta.url));i0=Zf()});import{readFileSync as Xf}from"fs";import{resolve as Qf,dirname as Yf}from"path";import{fileURLToPath as Jf}from"url";function h3(){if(h5!==null)return h5;let Z="9.21.0";if(typeof Z==="string"&&Z.length>0)return h5=Z,h5;try{let X=Yf(Jf(import.meta.url)),Q=X$(X);h5=Xf(Qf(Q,"VERSION"),"utf-8").trim()}catch{h5="unknown"}return h5}var h5=null;var BQ=p(()=>{H8()});var _O={};l0(_O,{runOrThrow:()=>Tf,run:()=>E0,readStreamCapped:()=>NQ,commandVersion:()=>Cf,commandExists:()=>X9,ShellError:()=>Q$,MAX_STDOUT_BYTES:()=>bO});async function NQ(Z,X=bO){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 V=$.byteLength-(z-X);J+=Y.decode($.subarray(0,V),{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 Tf(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=wf(Z),Q=await E0(["sh","-c",`command -v ${X}`],{timeoutMs:5000});if(Q.exitCode===0)return Q.stdout.trim()||null;return null}function wf(Z){if(!/^[A-Za-z0-9._/-]+$/.test(Z))throw Error(`refused to shell-escape suspect token: ${Z}`);return Z}async function Cf(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 bO=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 Ff?"":Z}var Ff,A0,F8,_0,$W0,a0,V8,Q9,h;var S6=p(()=>{Ff=(process.env.NO_COLOR??"").length>0;A0=o7("\x1B[0;31m"),F8=o7("\x1B[0;32m"),_0=o7("\x1B[1;33m"),$W0=o7("\x1B[0;34m"),a0=o7("\x1B[0;36m"),V8=o7("\x1B[1m"),Q9=o7("\x1B[2m"),h=o7("\x1B[0m")});import{existsSync as ff}from"fs";async function E7(){if(x4!==void 0)return x4;let Z="/opt/homebrew/bin/python3.12";if(ff(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 XA={};l0(XA,{runStatus:()=>Vh});import{existsSync as Y9,readFileSync as g3,readdirSync as aO,statSync as sO}from"fs";import{resolve as h8,basename as ef}from"path";import{homedir as Zh}from"os";function nO(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 oO(Z,X,Q){if(X===0)return null;let Y=Math.trunc(Z*100/X),J=Math.trunc(Z*AQ/X);if(J>AQ)J=AQ;let z=AQ-J,K=F8;if(Y>=80)K=A0;else if(Y>=50)K=_0;let $="=".repeat(Math.max(0,J))+" ".repeat(Math.max(0,z)),V=nO(Z),W=nO(X);return`  ${V8}${Q}${h} ${K}[${$}]${h} ${Y}% (${V} / ${W})`}async function Qh(){if(await X9("jq"))return!0;return process.stdout.write(`${A0}Error: jq is required but not installed.${h}
+var p_=Object.create;var{getPrototypeOf:d_,defineProperty:eK,getOwnPropertyNames:c_}=Object;var l_=Object.prototype.hasOwnProperty;function i_(Z){return this[Z]}var a_,s_,n_=(Z,X,Q)=>{var Y=Z!=null&&typeof Z==="object";if(Y){var J=X?a_??=new WeakMap:s_??=new WeakMap,z=J.get(Z);if(z)return z}Q=Z!=null?p_(d_(Z)):{};let K=X||!Z||!Z.__esModule?eK(Q,"default",{value:Z,enumerable:!0}):Q;for(let $ of c_(Z))if(!l_.call(K,$))eK(K,$,{get:i_.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 o_=(Z)=>Z;function r_(Z,X){this[Z]=o_.bind(null,X)}var l0=(Z,X)=>{for(var Q in X)eK(Z,Q,{get:X[Q],enumerable:!0,configurable:!0,set:r_.bind(X,Q)})};var p=(Z,X)=>()=>(Z&&(X=Z(Z=0)),X);var t0=import.meta.require;var xO={};l0(xO,{lokiDir:()=>j0,homeLokiDir:()=>R4,findRepoRootForVersion:()=>X$,REPO_ROOT:()=>i0});import{resolve as n7,dirname as Z$}from"path";import{fileURLToPath as t_}from"url";import{existsSync as UQ}from"fs";import{homedir as e_}from"os";function Zf(){let Z=kO;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(kO,"..","..","..")}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(e_(),".loki")}var kO,i0;var H8=p(()=>{kO=Z$(t_(import.meta.url));i0=Zf()});import{readFileSync as Xf}from"fs";import{resolve as Qf,dirname as Yf}from"path";import{fileURLToPath as Jf}from"url";function h3(){if(h5!==null)return h5;let Z="9.22.0";if(typeof Z==="string"&&Z.length>0)return h5=Z,h5;try{let X=Yf(Jf(import.meta.url)),Q=X$(X);h5=Xf(Qf(Q,"VERSION"),"utf-8").trim()}catch{h5="unknown"}return h5}var h5=null;var BQ=p(()=>{H8()});var _O={};l0(_O,{runOrThrow:()=>Tf,run:()=>E0,readStreamCapped:()=>NQ,commandVersion:()=>Cf,commandExists:()=>X9,ShellError:()=>Q$,MAX_STDOUT_BYTES:()=>bO});async function NQ(Z,X=bO){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 V=$.byteLength-(z-X);J+=Y.decode($.subarray(0,V),{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 Tf(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=wf(Z),Q=await E0(["sh","-c",`command -v ${X}`],{timeoutMs:5000});if(Q.exitCode===0)return Q.stdout.trim()||null;return null}function wf(Z){if(!/^[A-Za-z0-9._/-]+$/.test(Z))throw Error(`refused to shell-escape suspect token: ${Z}`);return Z}async function Cf(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 bO=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 Ff?"":Z}var Ff,A0,F8,_0,$W0,a0,V8,Q9,h;var S6=p(()=>{Ff=(process.env.NO_COLOR??"").length>0;A0=o7("\x1B[0;31m"),F8=o7("\x1B[0;32m"),_0=o7("\x1B[1;33m"),$W0=o7("\x1B[0;34m"),a0=o7("\x1B[0;36m"),V8=o7("\x1B[1m"),Q9=o7("\x1B[2m"),h=o7("\x1B[0m")});import{existsSync as ff}from"fs";async function E7(){if(x4!==void 0)return x4;let Z="/opt/homebrew/bin/python3.12";if(ff(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 XA={};l0(XA,{runStatus:()=>Vh});import{existsSync as Y9,readFileSync as g3,readdirSync as aO,statSync as sO}from"fs";import{resolve as h8,basename as ef}from"path";import{homedir as Zh}from"os";function nO(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 oO(Z,X,Q){if(X===0)return null;let Y=Math.trunc(Z*100/X),J=Math.trunc(Z*AQ/X);if(J>AQ)J=AQ;let z=AQ-J,K=F8;if(Y>=80)K=A0;else if(Y>=50)K=_0;let $="=".repeat(Math.max(0,J))+" ".repeat(Math.max(0,z)),V=nO(Z),W=nO(X);return`  ${V8}${Q}${h} ${K}[${$}]${h} ${Y}% (${V} / ${W})`}async function Qh(){if(await X9("jq"))return!0;return process.stdout.write(`${A0}Error: jq is required but not installed.${h}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -1236,4 +1236,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}case"start":{let{runStart:Y}=await Promise.resolve().then(() => (g_(),v_));return Y(Q)}default:return process.stderr.write(`Unknown command: ${X}
 `),process.stderr.write(m_),2}}lO();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var dV0=await pV0(Bun.argv.slice(2));process.exit(dV0);
 
-//# debugId=8B493F2C51A0A0E764756E2164756E21
+//# debugId=DE8569120D6E31F464756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "9.21.0",
+  "version": "9.22.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.21.0",
+  "version": "9.22.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/outcome-canary-evaluate.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""Evaluate source-bound canary observations without changing a route."""
+import argparse
+import hashlib
+import importlib.util
+import json
+import math
+import os
+import pathlib
+import sys
+
+OK, REFUSED, USAGE, NO_INPUT = 0, 3, 64, 66
+DOMAIN = "loki-outcome-canary-evaluation/v1"
+OBSERVATIONS = "loki-outcome-canary-observations/v1"
+MAX_BYTES = 5 * 1024 * 1024
+MAX_ITEMS = 100_000
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(USAGE, f"{self.prog}: error: {message}\n")
+
+
+class DuplicateKey(ValueError):
+    pass
+
+
+def _object(pairs):
+    out = {}
+    for key, value in pairs:
+        if key in out:
+            raise DuplicateKey(f"duplicate key: {key}")
+        out[key] = value
+    return out
+
+
+def _number(value, low, high):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    if not math.isfinite(value) or value < low or value > high:
+        return None
+    return float(value)
+
+
+def _integer(value, low, high):
+    if isinstance(value, bool) or not isinstance(value, int) or value < low or value > high:
+        return None
+    return value
+
+
+def _sha256(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def _read_json(path):
+    with open(path, "rb") as handle:
+        data = handle.read(MAX_BYTES + 1)
+    if len(data) > MAX_BYTES:
+        raise ValueError(f"input exceeds {MAX_BYTES} bytes")
+    return json.loads(data.decode("utf-8"), object_pairs_hook=_object), _sha256(data)
+
+
+def _load_planner():
+    path = pathlib.Path(__file__).with_name("outcome-canary.py")
+    spec = importlib.util.spec_from_file_location("outcome_canary", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("cannot load outcome canary planner")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _arm(items):
+    trials = len(items)
+    accepted = sum(1 for item in items if item["accepted"])
+    return {
+        "trials": trials,
+        "accepted": accepted,
+        "accepted_bps": (accepted * 10_000) // trials,
+        "mean_risk": sum(item["risk"] for item in items) / trials,
+    }
+
+
+def evaluate(report_path, observations_path, control_route, canary_percent=10.0,
+             max_risk=.25, min_samples=5, min_lift_bps=1, enable_evaluation=False):
+    """Return a deterministic aggregate verdict or an explained refusal."""
+    reasons = []
+    percent = _number(canary_percent, 0, 100)
+    ceiling = _number(max_risk, 0, 1)
+    samples = _integer(min_samples, 1, MAX_ITEMS)
+    lift = _integer(min_lift_bps, 0, 10_000)
+    if not enable_evaluation:
+        reasons.append("evaluation is opt-in; pass --enable-evaluation")
+    if not isinstance(control_route, str) or not control_route.strip():
+        reasons.append("control route must be non-empty")
+    if percent is None:
+        reasons.append("canary percent must be a finite number between 0 and 100")
+    if ceiling is None:
+        reasons.append("max risk must be a finite number between 0 and 1")
+    if samples is None:
+        reasons.append(f"min samples must be an integer between 1 and {MAX_ITEMS}")
+    if lift is None:
+        reasons.append("min lift bps must be an integer between 0 and 10000")
+
+    out = {
+        "evaluation": DOMAIN,
+        "report": os.path.abspath(report_path),
+        "report_sha256": None,
+        "source_sha256": None,
+        "observations": os.path.abspath(observations_path),
+        "observations_sha256": None,
+        "control_route": control_route,
+        "canary_route": None,
+        "canary_percent": percent,
+        "max_risk": ceiling,
+        "min_samples": samples,
+        "min_lift_bps": lift,
+        "control": None,
+        "canary": None,
+        "verdict": None,
+        "refusal_reasons": reasons,
+    }
+    try:
+        observations, observations_sha256 = _read_json(observations_path)
+        out["observations_sha256"] = observations_sha256
+    except Exception as exc:
+        out["refusal_reasons"].append(f"observations are malformed: {exc}")
+        return out
+    if not isinstance(observations, dict):
+        out["refusal_reasons"].append("observations are not a JSON object")
+        return out
+    if observations.get("observations") != OBSERVATIONS:
+        out["refusal_reasons"].append(f"observations version is not {OBSERVATIONS}")
+    items = observations.get("items")
+    if not isinstance(items, list):
+        out["refusal_reasons"].append("observations have no items list")
+        return out
+    if len(items) > MAX_ITEMS:
+        out["refusal_reasons"].append(f"observations exceed {MAX_ITEMS} items")
+        return out
+
+    try:
+        planner = _load_planner()
+        report, report_sha256, report_reasons = planner.load_report(report_path)
+    except Exception as exc:
+        out["refusal_reasons"].append(f"report is malformed: {exc}")
+        return out
+    out["report_sha256"] = report_sha256
+    out["refusal_reasons"].extend(report_reasons)
+    if report is None:
+        return out
+    out["source_sha256"] = report.get("source_sha256")
+    out["canary_route"] = report.get("selected_route")
+    if observations.get("report_sha256") != report_sha256:
+        out["refusal_reasons"].append("observations are not bound to the exact router report")
+    if observations.get("source_sha256") != report.get("source_sha256"):
+        out["refusal_reasons"].append("observations are not bound to the exact evidence source")
+
+    seen = set()
+    arms = {"control": [], "canary": []}
+    for index, item in enumerate(items):
+        label = f"item {index}"
+        if not isinstance(item, dict):
+            out["refusal_reasons"].append(f"{label} is not an object")
+            continue
+        if set(item) != {"subject", "assignment", "route", "accepted", "risk"}:
+            out["refusal_reasons"].append(f"{label} has a non-canonical shape")
+            continue
+        subject = item.get("subject")
+        assignment = item.get("assignment")
+        route = item.get("route")
+        accepted = item.get("accepted")
+        risk = _number(item.get("risk"), 0, 1)
+        if not isinstance(subject, str) or not subject.strip():
+            out["refusal_reasons"].append(f"{label} has an invalid subject")
+            continue
+        if subject in seen:
+            out["refusal_reasons"].append(f"{label} repeats a subject")
+            continue
+        seen.add(subject)
+        if assignment not in arms or not isinstance(route, str) or not isinstance(accepted, bool) or risk is None:
+            out["refusal_reasons"].append(f"{label} has invalid measured values")
+            continue
+        plan = planner.plan(report_path, subject, control_route, percent, ceiling, True)
+        if plan.get("refusal_reasons"):
+            out["refusal_reasons"].append(f"{label} cannot be rebound to a valid canary plan")
+            continue
+        if assignment != plan.get("assignment") or route != plan.get("route"):
+            out["refusal_reasons"].append(f"{label} does not match its deterministic assignment")
+            continue
+        arms[assignment].append({"accepted": accepted, "risk": risk})
+
+    if out["refusal_reasons"]:
+        return out
+    for name in ("control", "canary"):
+        if len(arms[name]) < samples:
+            out["refusal_reasons"].append(
+                f"{name} arm has {len(arms[name])} samples; requires at least {samples}"
+            )
+    if out["refusal_reasons"]:
+        return out
+
+    control = _arm(arms["control"])
+    canary = _arm(arms["canary"])
+    out["control"], out["canary"] = control, canary
+    accepted_delta = canary["accepted_bps"] - control["accepted_bps"]
+    out["accepted_delta_bps"] = accepted_delta
+    if canary["mean_risk"] > ceiling or accepted_delta < 0:
+        out["verdict"] = "ROLLBACK"
+    elif accepted_delta >= lift and canary["mean_risk"] <= control["mean_risk"]:
+        out["verdict"] = "PROMOTE"
+    else:
+        out["verdict"] = "HOLD"
+    return out
+
+
+def main(argv=None):
+    parser = Parser(prog="outcome-canary-evaluate")
+    parser.add_argument("report")
+    parser.add_argument("observations")
+    parser.add_argument("--enable-evaluation", action="store_true")
+    parser.add_argument("--control-route", required=True)
+    parser.add_argument("--canary-percent", type=float, default=10.0)
+    parser.add_argument("--max-risk", type=float, default=.25)
+    parser.add_argument("--min-samples", type=int, default=5)
+    parser.add_argument("--min-lift-bps", type=int, default=1)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    for path in (args.report, args.observations):
+        if not os.path.isfile(path):
+            print(f"outcome-canary-evaluate: no such file: {path}", file=sys.stderr)
+            return NO_INPUT
+    result = evaluate(
+        args.report, args.observations, args.control_route, args.canary_percent,
+        args.max_risk, args.min_samples, args.min_lift_bps, args.enable_evaluation,
+    )
+    if args.json:
+        print(json.dumps(result, sort_keys=True))
+    elif result["refusal_reasons"]:
+        print("Canary evaluation: REFUSED")
+        for reason in result["refusal_reasons"]:
+            print(f"  {reason}")
+    else:
+        print(f"Canary evaluation: {result['verdict']}")
+        print(
+            f"  control={result['control']['accepted']}/{result['control']['trials']} "
+            f"({result['control']['accepted_bps']} bps)"
+        )
+        print(
+            f"  canary={result['canary']['accepted']}/{result['canary']['trials']} "
+            f"({result['canary']['accepted_bps']} bps)"
+        )
+        print(f"  accepted delta: {result['accepted_delta_bps']} bps")
+        print(f"  report sha256: {result['report_sha256']}")
+        print(f"  observations sha256: {result['observations_sha256']}")
+    return REFUSED if result["refusal_reasons"] else OK
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())