loki-mode 9.20.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.20.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.20.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.20.0
+9.22.0

package/autonomy/loki

@@ -2021,6 +2021,8 @@ cmd_start() {
     local mirofish_bg=false
     local mirofish_disabled=false
     local no_plan=false  # v6.81.1: --no-plan opts out of auto-plan display
+    local repo_depth="full"          # repository targets default to full verification
+    local repo_depth_explicit=""     # "" | "fast" | "full" -- what the operator asked for
     local remote_url="${LOKI_REMOTE_URL:-}"   # --remote: submit to a deployed cluster
 
     # v6.84.0: unified entry point -- explicit mode overrides + issue-mode args
@@ -2092,6 +2094,10 @@ cmd_start() {
                 echo "  --mirofish-bg         Run MiroFish pipeline in background"
                 echo "  --no-mirofish         Disable MiroFish even if env var is set"
                 echo "  --no-plan             Skip auto-shown PRD analysis at startup"
+                echo "  --fast                REPO mode: capped lightweight pass, gates reduced"
+                echo "                        (no council verdict; alias --repo-fast)"
+                echo "  --full                REPO mode: explicit full verification, the default"
+                echo "                        (wins over --fast; alias --repo-full)"
                 echo "  --brief \"TEXT\"        Zero-config fast first run from a one-line brief"
                 echo "  --yes, -y             Skip confirmation prompts (auto-confirm)"
                 echo "  --quiet               Suppress [INFO]/[STEP]; warnings and errors still print"
@@ -2445,6 +2451,22 @@ cmd_start() {
                 no_plan=true
                 shift
                 ;;
+            --fast|--repo-fast)
+                # Fail closed on a conflict, same doctrine as --isolation below:
+                # never silently downgrade to weaker verification than asked for.
+                # --full wins regardless of order, so `--fast --full` and
+                # `--full --fast` both keep the gates ON.
+                if [ "$repo_depth_explicit" != "full" ]; then
+                    repo_depth="fast"
+                    repo_depth_explicit="fast"
+                fi
+                shift
+                ;;
+            --full|--repo-full)
+                repo_depth="full"
+                repo_depth_explicit="full"
+                shift
+                ;;
             --brief)
                 # R7: explicit one-line brief (escape hatch for single-word
                 # briefs that detect_arg_type would otherwise treat as a PRD
@@ -2839,27 +2861,50 @@ cmd_start() {
     # synthesized brief that bounds the work to ONE high-value improvement
     # instead of "build out the whole project".
     #
-    # Deliberately does NOT call set_ttfv_lightweight_profile: that helper
-    # turns the council and the code-review phase OFF, and the whole point of
-    # this entry point is to hand back VERIFIED evidence. Scope is bounded by
-    # the brief text, not by disabling the gates that check the work. The run
-    # keeps full depth, so it reports LOKI_TTFV=repo -- the same honest
-    # full-depth signal the no-arg path uses.
+    # The DEFAULT and `--full` deliberately do NOT call
+    # set_ttfv_lightweight_profile: that helper turns the council and the
+    # code-review phase OFF, and the whole point of this entry point is to hand
+    # back VERIFIED evidence. Scope is bounded by the brief text, not by
+    # disabling the gates that check the work. Those runs keep full depth and
+    # report LOKI_TTFV=repo -- the same honest full-depth signal the no-arg path
+    # uses.
+    #
+    # `--fast` is the opt-in exception: it applies the SAME lightweight profile
+    # the brief path uses (capped iterations, council off, simple tier, heavy
+    # phases off) and reports LOKI_TTFV=repo-fast, a distinct signal so the
+    # end-of-run wording in run.sh cannot claim council verdicts that never ran.
     if [ "$detected_type" = "repo" ]; then
         local version
         version=$(get_version)
+        # Same cap the brief sub-path reads, so "fast" means one thing.
+        local _repo_max_iter="${LOKI_MAX_ITERATIONS:-3}"
         mkdir -p "$LOKI_DIR" 2>/dev/null || true
         find "$LOKI_DIR" -maxdepth 1 -name 'repo-prd-*.md' -mtime +1 -delete 2>/dev/null || true
         local repo_prd="$LOKI_DIR/repo-prd-$$.md"
-        synthesize_repo_prd "$repo_prd"
+        synthesize_repo_prd "$repo_prd" "$repo_depth"
         prd_file="$repo_prd"
 
+        if [ "$repo_depth" = "fast" ]; then
+            set_ttfv_lightweight_profile "$_repo_max_iter"
+            export LOKI_TTFV=repo-fast
+            no_plan=true
+        fi
+
         echo -e "${BOLD}Loki Mode v$version - Repo improvement${NC}"
         echo ""
         echo -e "${CYAN}Repo:${NC} $LOKI_REPO_TARGET"
-        echo -e "${DIM}Loki will inspect this project, pick one high-value improvement,${NC}"
-        echo -e "${DIM}implement it, test it, and produce verified evidence.${NC}"
-        echo -e "${DIM}Full depth: quality gates and completion council stay ON.${NC}"
+        if [ "$repo_depth" = "fast" ]; then
+            echo -e "${DIM}Loki will inspect this project, pick one high-value improvement,${NC}"
+            echo -e "${DIM}implement it, and test it.${NC}"
+            echo -e "${DIM}Fast pass: $_repo_max_iter iterations max, simple tier, council and${NC}"
+            echo -e "${DIM}heavy phases OFF. Reduced gates: you get measured run evidence${NC}"
+            echo -e "${DIM}(diffs, cost, time), NOT a council-verified verdict.${NC}"
+            echo -e "${DIM}Run full verification with: loki start \"$LOKI_REPO_TARGET\" --full${NC}"
+        else
+            echo -e "${DIM}Loki will inspect this project, pick one high-value improvement,${NC}"
+            echo -e "${DIM}implement it, test it, and produce verified evidence.${NC}"
+            echo -e "${DIM}Full depth: quality gates and completion council stay ON.${NC}"
+        fi
         echo -e "${DIM}Scope it yourself instead with: loki start \"<what you want>\".${NC}"
         echo ""
     fi
@@ -15070,8 +15115,16 @@ BRIEFEOF
 # Build a bounded input for `loki start <repo-directory>`. This intentionally
 # contains no caller-controlled path: repository identity comes from cwd, while
 # the task remains stable, reviewable, and safe to render into a prompt.
+#
+# The trailing Mode line is the only variable part, and it must match what the
+# run actually does: a fast pass runs with the council off, so a PRD telling the
+# agent it is under "full verification" would be a false claim in the prompt
+# itself. The body stays a quoted heredoc (no expansion, nothing injectable);
+# the Mode line is appended from a fixed string chosen by a validated depth.
+# Usage: synthesize_repo_prd <output_file> [full|fast]
 synthesize_repo_prd() {
     local out_file="$1"
+    local depth="${2:-full}"
     mkdir -p "$(dirname "$out_file")" 2>/dev/null || true
     cat > "$out_file" <<'REPOEOF'
 # Existing Repository Improvement
@@ -15091,9 +15144,17 @@ Select one small, high-value user-facing improvement and implement it completely
 - Reuse the repository's established architecture and dependencies.
 - Keep the change easy to review and roll back.
 - Do not claim deployment, adoption, or customer value without evidence.
-
-**Mode:** Existing repository improvement (full verification)
 REPOEOF
+    if [ "$depth" = "fast" ]; then
+        printf '%s\n' \
+            "- This is a fast, capped pass. Keep the change small enough to finish and prove." \
+            "" \
+            "**Mode:** Existing repository improvement (fast pass, reduced gates)." \
+            "The completion council and heavy review phases are OFF on this run." \
+            "Do not describe the result as council-verified or fully verified." >> "$out_file"
+    else
+        printf '\n**Mode:** Existing repository improvement (full verification)\n' >> "$out_file"
+    fi
 }
 
 # Quick mode - lightweight single-task execution

package/autonomy/run.sh

@@ -7784,9 +7784,14 @@ print_ttfv_next_steps() {
     echo "============================================================"
     echo ""
     echo "  What I did:"
-    if [ "$mode" = "brief" ]; then
+    if [ "$mode" = "brief" ] || [ "$mode" = "repo-fast" ]; then
+        if [ "$mode" = "repo-fast" ]; then
+            echo "    - Inspected your repository on a fast, lightweight first"
+            echo "      pass (council off, simple tier, capped iterations)."
+        else
         echo "    - Worked from your one-line brief on a fast, lightweight first"
         echo "      pass (council off, simple tier, capped iterations)."
+        fi
         echo "    - Generated a proof-of-run (diffs, cost, time)."
     else
         echo "    - Analyzed your codebase and generated a PRD, then ran a full"
@@ -7808,7 +7813,7 @@ print_ttfv_next_steps() {
         echo "    loki proof list"
     fi
     echo ""
-    if [ "$mode" = "brief" ]; then
+    if [ "$mode" = "brief" ] || [ "$mode" = "repo-fast" ]; then
         echo "  Go deeper (full RARV-C depth, council-gated):"
         echo "    loki start                 # continue / harden this project"
         echo "    loki start ./prd.md        # build from a full PRD"

package/bin/loki

@@ -276,6 +276,7 @@ _loki_start_needs_bash() {
     for a in "$@"; do
         case "$a" in
             --parallel|--bg|--background|--github|--api|--sandbox \
+            |--fast|--repo-fast|--full|--repo-full \
             |--bmad-project|--openspec \
             |--mirofish|--mirofish-docker|--mirofish-rounds|--mirofish-timeout|--mirofish-bg \
             |--issue|--dry-run|--no-start|--output|--worktree|-w|--pr|--ship|--detach|-d)

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "9.20.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/docs/OUTCOME-CANARY.md

@@ -0,0 +1,61 @@
+# Outcome Canary
+
+`python3 tools/outcome-canary.py report.json --enable-canary --subject <key> --control-route <name>`
+plans a reversible canary split between the route an [outcome router](./OUTCOME-ROUTER.md)
+report selected and an operator-named control. It is a planner: it never invokes or
+switches a provider, never weakens a gate, and writes nothing.
+
+The canary is opt-in. Without `--enable-canary` it refuses, so a plan can never be
+produced by accident.
+
+## Evidence it demands
+
+The tool refuses unless the evidence stands up on its own terms:
+
+- the report parses, is a `loki-outcome-router/v1` object, and carries `source`,
+  a 64-hex `source_sha256`, and a `candidates` list
+- the recorded source file still exists and still hashes to `source_sha256`, so a
+  plan cannot rest on trials that changed after they were measured
+- the exact router-report bytes are hashed as `report_sha256`; that digest is
+  emitted in the plan and participates in assignment, so a report edited after
+  review cannot reuse the prior plan binding
+- the report selected a primary route, the control route is present, both are
+  `eligible`, and the two differ
+- `trials` and `mean_risk` on both routes are strictly valid numbers: booleans,
+  `NaN`, and `Infinity` are rejected, not coerced
+- both routes have equal trial counts, so the two arms rest on matched evidence
+- neither route's mean risk exceeds `--max-risk` (default `.25`)
+- `--canary-percent` (default `10`) is a finite number from 0 to 100
+
+Every failed check is reported in `refusal_reasons`; the plan is refused as a whole
+rather than partially applied.
+
+## Assignment
+
+Assignment is deterministic and needs no stored state. The tool hashes a
+NUL-joined, domain-separated string of `loki-outcome-canary/v1`, the subject, the
+router-report digest, the source digest, the primary route, the control route, and the percentage, then takes
+that sha256 modulo 10000 against the percentage. The same subject and the same
+evidence always land in the same arm, in any process; different subjects spread
+across arms. Because the digest includes the evidence, changing the trials
+reshuffles the split rather than silently carrying an old assignment forward.
+
+Percent 0 assigns every subject to control and percent 100 assigns every subject to
+the canary, which is what makes the rollback a real command rather than a promise.
+
+## Rollback
+
+A plan always carries `reversible: true` and a `rollback` object naming the control
+route, its effect, and the exact command that assigns control to everyone:
+
+```
+python3 tools/outcome-canary.py report.json --enable-canary \
+  --subject <key> --control-route <name> --canary-percent 0
+```
+
+## Output and exit codes
+
+`--json` emits the whole plan for automation; the default is human-readable. Exit 0
+means a plan exists, 3 means the evidence or policy cannot support one (including a
+missing `--enable-canary`, and a source that drifted), 64 is an invocation error,
+and 66 is a missing report file or a report whose evidence source is gone.

package/docs/OUTCOME-ROUTER.md

@@ -0,0 +1,7 @@
+# Outcome Router
+
+`python3 tools/outcome-router.py trials.jsonl` recommends a route only from measured local trials. Each JSONL row records `route`, strict-boolean `accepted`, non-negative `cost_usd`, positive `duration_minutes`, `risk` from 0 to 1, and optional string `verifier`.
+
+The advisor first rejects routes above the risk ceiling, with sparse evidence, or without an accepted outcome. It then ranks eligible routes by the harmonic mean of accepted outcomes per dollar and per minute, penalized by mean risk. Invalid input poisons eligibility instead of disappearing from the evidence basis. It never invokes or switches a provider and never weakens a gate.
+
+Use `--json` for automation, `--min-trials` and `--max-risk` for evidence policy, and `--risk-weight` to tune the risk penalty. Exit 0 means a recommendation exists, 3 means the evidence cannot support one, 64 is 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.20.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=AF141439B5D0532864756E2164756E21
+//# debugId=DE8569120D6E31F464756E2164756E21

package/mcp/__init__.py

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "9.20.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.20.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())

package/tools/outcome-canary.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""Plan a reversible canary split between two measured routes, or refuse."""
+import argparse, hashlib, json, math, os, sys
+
+OK, REFUSED, USAGE, NO_INPUT = 0, 3, 64, 66
+REPORT = "loki-outcome-router/v1"
+DOMAIN = "loki-outcome-canary/v1"
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(USAGE, f"{self.prog}: error: {message}\n")
+
+def _number(value, low, high=None):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        return None
+    if value < low or (high is not None and value > high):
+        return None
+    return float(value)
+
+def _count(value):
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        return None
+    return value
+
+def sha256_file(path):
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+def evidence_digest(subject, report_sha256, source_sha256, primary, control, percent):
+    # NUL-joined so a route name containing a separator cannot collide with another split.
+    parts = [DOMAIN, subject, report_sha256, source_sha256, primary, control, f"{percent:.6f}"]
+    return hashlib.sha256("\x00".join(parts).encode("utf-8")).hexdigest()
+
+def assign(digest, percent):
+    return "canary" if int(digest, 16) % 10000 < round(percent * 100) else "control"
+
+def load_report(path):
+    """Return (report, report_sha256, refusal_reasons) from one exact byte read."""
+    with open(path, "rb") as handle:
+        report_bytes = handle.read()
+    report_sha256 = hashlib.sha256(report_bytes).hexdigest()
+    report = json.loads(report_bytes.decode("utf-8"))
+    reasons = []
+    if not isinstance(report, dict):
+        return None, report_sha256, ["report is not a JSON object"]
+    if report.get("report") != REPORT:
+        reasons.append(f"report version is not {REPORT}")
+    source = report.get("source")
+    if not isinstance(source, str) or not source.strip():
+        reasons.append("report has no source path")
+    source_sha256 = report.get("source_sha256")
+    if not isinstance(source_sha256, str) or len(source_sha256) != 64 or any(c not in "0123456789abcdef" for c in source_sha256):
+        reasons.append("report has no valid source_sha256")
+    if not isinstance(report.get("candidates"), list):
+        reasons.append("report has no candidates")
+    return report, report_sha256, reasons
+
+def candidate(report, name):
+    for row in report.get("candidates") or []:
+        if isinstance(row, dict) and row.get("route") == name:
+            return row
+    return None
+
+def plan(report_path, subject, control_route, canary_percent=10.0, max_risk=.25, enable_canary=False):
+    """Build a canary plan or an explained refusal. Reads only; writes nothing."""
+    reasons = []
+    if not isinstance(subject, str) or not subject.strip():
+        reasons.append("subject must be non-empty")
+    if not isinstance(control_route, str) or not control_route.strip():
+        reasons.append("control route must be non-empty")
+    if not enable_canary:
+        reasons.append("canary is opt-in; pass --enable-canary")
+    try:
+        report, report_sha256, schema_reasons = load_report(report_path)
+    except Exception as exc:
+        return {"plan": DOMAIN, "report": os.path.abspath(report_path), "report_sha256": None,
+                "assignment": None,
+                "refusal_reasons": reasons + [f"report is malformed: {exc}"]}
+    reasons += schema_reasons
+    if report is None:
+        return {"plan": DOMAIN, "report": os.path.abspath(report_path),
+                "report_sha256": report_sha256, "assignment": None,
+                "refusal_reasons": reasons}
+
+    source = report.get("source") if isinstance(report.get("source"), str) else None
+    source_sha256 = report.get("source_sha256")
+    source_missing = False
+    if source and not schema_reasons:
+        if not os.path.isfile(source):
+            source_missing = True
+            reasons.append(f"evidence source is absent: {source}")
+        elif sha256_file(source) != source_sha256:
+            reasons.append("evidence source has drifted from the report digest")
+
+    primary = report.get("selected_route")
+    if not isinstance(primary, str) or not primary.strip():
+        reasons.append("report selected no primary route")
+        primary = None
+    rows = {"primary": candidate(report, primary) if primary else None,
+            "control": candidate(report, control_route)}
+    for role, row in rows.items():
+        name = primary if role == "primary" else control_route
+        if row is None:
+            reasons.append(f"{role} route {name!r} is absent from the report")
+        elif row.get("eligible") is not True:
+            reasons.append(f"{role} route {name!r} is not eligible on measured evidence")
+    if primary is not None and primary == control_route:
+        reasons.append("primary and control must differ")
+
+    percent = _number(canary_percent, 0, 100)
+    if percent is None:
+        reasons.append("canary percent must be a finite number between 0 and 100")
+    ceiling = _number(max_risk, 0, 1)
+    if ceiling is None:
+        reasons.append("max risk must be a finite number between 0 and 1")
+
+    trials = {}
+    for role, row in rows.items():
+        if row is None:
+            continue
+        name = row.get("route")
+        risk = _number(row.get("mean_risk"), 0, 1)
+        count = _count(row.get("trials"))
+        if risk is None or count is None:
+            reasons.append(f"{role} route {name!r} has invalid measured values")
+            continue
+        trials[role] = count
+        if ceiling is not None and risk > ceiling:
+            reasons.append(f"{role} route {name!r} mean risk {risk:.6f} exceeds {ceiling:.6f}")
+    if len(trials) == 2 and trials["primary"] != trials["control"]:
+        reasons.append(f"evidence is unmatched: {trials['primary']} primary trials vs {trials['control']} control trials")
+
+    out = {"plan": DOMAIN, "report": os.path.abspath(report_path),
+           "report_sha256": report_sha256, "report_version": report.get("report"),
+           "source": source, "source_sha256": source_sha256, "source_missing": source_missing,
+           "primary_route": primary, "control_route": control_route,
+           "canary_percent": percent, "max_risk": ceiling, "subject": subject,
+           "assignment": None, "evidence_digest": None, "reversible": True,
+           "rollback": None, "refusal_reasons": reasons}
+    if reasons:
+        return out
+    digest = evidence_digest(subject, report_sha256, source_sha256, primary, control_route, percent)
+    out["evidence_digest"] = digest
+    out["assignment"] = assign(digest, percent)
+    out["route"] = primary if out["assignment"] == "canary" else control_route
+    out["rollback"] = {
+        "assignment": "control", "route": control_route, "reversible": True,
+        "effect": "every subject is assigned the control route",
+        "command": f"python3 tools/outcome-canary.py {report_path} --enable-canary "
+                   f"--subject {subject} --control-route {control_route} --canary-percent 0"}
+    return out
+
+def main(argv=None):
+    p = Parser(prog="outcome-canary")
+    p.add_argument("report")
+    p.add_argument("--enable-canary", action="store_true")
+    p.add_argument("--subject", required=True)
+    p.add_argument("--control-route", required=True)
+    p.add_argument("--canary-percent", type=float, default=10.0)
+    p.add_argument("--max-risk", type=float, default=.25)
+    p.add_argument("--json", action="store_true")
+    a = p.parse_args(argv)
+    if not a.subject.strip() or not a.control_route.strip():
+        p.error("subject and control route must be non-empty")
+    if _number(a.canary_percent, 0, 100) is None or _number(a.max_risk, 0, 1) is None:
+        p.error("invalid policy threshold")
+    if not os.path.isfile(a.report):
+        print(f"outcome-canary: no such report: {a.report}", file=sys.stderr)
+        return NO_INPUT
+    result = plan(a.report, a.subject, a.control_route, a.canary_percent, a.max_risk, a.enable_canary)
+    if result.get("source_missing"):
+        if a.json: print(json.dumps(result, sort_keys=True))
+        else: print(f"outcome-canary: evidence source is absent: {result['source']}", file=sys.stderr)
+        return NO_INPUT
+    if a.json:
+        print(json.dumps(result, sort_keys=True))
+    elif result["refusal_reasons"]:
+        print("Canary plan: REFUSED")
+        for reason in result["refusal_reasons"]:
+            print(f"  {reason}")
+    else:
+        print(f"Canary plan: {result['assignment']} -> {result['route']}")
+        print(f"  primary={result['primary_route']} control={result['control_route']} percent={result['canary_percent']:.6f}")
+        print(f"  report sha256: {result['report_sha256']}")
+        print(f"  evidence digest: {result['evidence_digest']}")
+        print(f"  reversible: {result['reversible']}; rollback assigns {result['rollback']['assignment']}")
+        print(f"  rollback: {result['rollback']['command']}")
+    return REFUSED if result["refusal_reasons"] else OK
+
+if __name__ == "__main__": raise SystemExit(main())

package/tools/outcome-router.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Recommend a route from measured accepted-outcome efficiency, or refuse."""
+import argparse, hashlib, json, math, os, sys
+
+OK, NO_ELIGIBLE, USAGE, NO_INPUT = 0, 3, 64, 66
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        self.exit(USAGE, f"{self.prog}: error: {message}\n")
+
+def _number(value, low, high=None, strict=False):
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        return None
+    if value < low or (strict and value == low) or (high is not None and value > high):
+        return None
+    return float(value)
+
+def route(path, min_trials=3, max_risk=.25, risk_weight=1.0):
+    groups, invalid = {}, []
+    with open(path, encoding="utf-8") as handle:
+        for line_no, line in enumerate(handle, 1):
+            try:
+                row = json.loads(line)
+                name = row.get("route") if isinstance(row, dict) else None
+                cost = _number(row.get("cost_usd"), 0) if isinstance(row, dict) else None
+                mins = _number(row.get("duration_minutes"), 0, strict=True) if isinstance(row, dict) else None
+                risk = _number(row.get("risk"), 0, 1) if isinstance(row, dict) else None
+                accepted = row.get("accepted") if isinstance(row, dict) else None
+                verifier = row.get("verifier", "") if isinstance(row, dict) else ""
+                if not isinstance(name, str) or not name.strip() or type(accepted) is not bool or cost is None or mins is None or risk is None or not isinstance(verifier, str):
+                    raise ValueError("invalid route observation schema")
+                groups.setdefault(name, []).append((accepted, cost, mins, risk))
+            except Exception as exc:
+                invalid.append({"line": line_no, "reason": str(exc)})
+    candidates = []
+    for name in sorted(groups):
+        rows = groups[name]; n = len(rows); accepted = sum(x[0] for x in rows)
+        cost = sum(x[1] for x in rows); mins = sum(x[2] for x in rows)
+        mean_risk = sum(x[3] for x in rows) / n
+        reasons = []
+        if invalid: reasons.append("input contains invalid observations")
+        if n < min_trials: reasons.append(f"needs {min_trials} trials; has {n}")
+        if accepted == 0: reasons.append("has no accepted outcome")
+        if mean_risk > max_risk: reasons.append(f"mean risk {mean_risk:.6f} exceeds {max_risk:.6f}")
+        per_dollar = accepted / max(cost, 1e-9)
+        per_minute = accepted / mins
+        harmonic = 2 * per_dollar * per_minute / (per_dollar + per_minute) if accepted else 0.0
+        score = harmonic * max(0.0, 1.0 - risk_weight * mean_risk)
+        candidates.append({"route": name, "trials": n, "accepted": accepted,
+            "cost_usd": cost, "duration_minutes": mins, "mean_risk": mean_risk,
+            "accepted_per_dollar": per_dollar, "accepted_per_minute": per_minute,
+            "score": score, "eligible": not reasons, "refusal_reasons": reasons})
+    eligible = sorted((c for c in candidates if c["eligible"]), key=lambda c: (-c["score"], c["route"]))
+    with open(path, "rb") as source_handle:
+        source_sha256 = hashlib.sha256(source_handle.read()).hexdigest()
+    return {"report": "loki-outcome-router/v1", "source": os.path.abspath(path),
+            "source_sha256": source_sha256,
+            "policy": {"min_trials": min_trials, "max_risk": max_risk,
+                       "risk_weight": risk_weight},
+            "selected_route": eligible[0]["route"] if eligible else None,
+            "invalid_observations": invalid, "candidates": candidates,
+            "formula": "harmonic(accepted/USD, accepted/minute) * max(0, 1-risk_weight*mean_risk)"}
+
+def main(argv=None):
+    p = Parser(); p.add_argument("path"); p.add_argument("--json", action="store_true")
+    p.add_argument("--min-trials", type=int, default=3); p.add_argument("--max-risk", type=float, default=.25)
+    p.add_argument("--risk-weight", type=float, default=1.0); a = p.parse_args(argv)
+    if a.min_trials < 1 or not math.isfinite(a.max_risk) or not 0 <= a.max_risk <= 1 or not math.isfinite(a.risk_weight) or a.risk_weight < 0: p.error("invalid threshold")
+    if not os.path.isfile(a.path): print(f"outcome-router: no such file: {a.path}", file=sys.stderr); return NO_INPUT
+    report = route(a.path, a.min_trials, a.max_risk, a.risk_weight)
+    if a.json: print(json.dumps(report, sort_keys=True))
+    else:
+        print("Outcome route: " + (report["selected_route"] or "REFUSED"))
+        for c in report["candidates"]:
+            print(f"  {c['route']}: score={c['score']:.6f} trials={c['trials']} accepted={c['accepted']} " + ("eligible" if c['eligible'] else "; ".join(c['refusal_reasons'])))
+        if report["invalid_observations"]: print(f"  invalid observations: {len(report['invalid_observations'])}")
+    return OK if report["selected_route"] else NO_ELIGIBLE
+
+if __name__ == "__main__": raise SystemExit(main())