loki-mode 8.5.2 → 8.6.0

package/autonomy/verify.sh

@@ -39,12 +39,23 @@
 #   2  BLOCKED
 #   3  verifier error (could not complete; never silently passes)
 #
-# NOTE on exit-code divergence from the spec: spec Section 1.1 lists
-# 0=VERIFIED, 1=BLOCKED, 2=CONCERNS, 3=error (BLOCKED and CONCERNS swapped
-# vs this implementation). This module follows the explicit BUILD TASK
-# ordering (0/1/2 = VERIFIED/CONCERNS/BLOCKED). A human must reconcile the
-# two before the GitHub App (Phase 2) consumes exit codes. The divergence is
-# surfaced in `loki verify --help`.
+# EXIT-CODE ORDERING, RECONCILED. An early draft spec listed
+# 0=VERIFIED, 1=BLOCKED, 2=CONCERNS, and this header used to say a human must
+# reconcile the two before the GitHub App consumed exit codes. That is now
+# done, in favor of THIS implementation: 0/1/2/3 =
+# VERIFIED/CONCERNS/BLOCKED/error.
+#
+# Why this ordering wins. The code is authoritative and always has been
+# (VERIFY_EXIT_* below), `loki verify --help` documents it, and
+# wiki/CLI-Reference.md documents it. The draft spec that said otherwise is not
+# in this repository and has no consumers. Renumbering working code to match an
+# absent document would break every existing caller to satisfy nothing.
+#
+# It is also the ordering an integrator expects: severity rises with the code,
+# so `[ $rc -ge 2 ]` means "at least blocked". The reverse would make 1 more
+# severe than 2, which no one guesses correctly.
+#
+# See docs/exit-codes.md for the exit codes of every command.
 
 set -uo pipefail
 
@@ -1810,6 +1821,7 @@ verify_emit_evidence() {
     _VERIFY_GATES="$_VERIFY_GATES_FILE" \
     _V_VERDICT="$VERIFY_VERDICT" \
     _V_EXIT="$VERIFY_EXIT" \
+    _V_JSON_STDOUT="${VERIFY_JSON:-0}" \
     _V_SCHEMA="$VERIFY_SCHEMA_VERSION" \
     _V_TOOLVER="$tool_version" \
     _V_REPO="$repo_name" \
@@ -1833,7 +1845,7 @@ verify_emit_evidence() {
     _V_SCOPE_MAX_FILES="${VERIFY_SCOPE_MAX_FILES:-}" \
     _V_SCOPE_MAX_NET="${VERIFY_SCOPE_MAX_NET_LINES:-}" \
     python3 - <<'PYEOF'
-import json, os, hashlib
+import json, os, hashlib, sys
 
 out_dir = os.environ["_VERIFY_OUT_DIR"]
 findings_file = os.environ["_VERIFY_FINDINGS"]
@@ -1959,6 +1971,27 @@ with open(ev_path, "w") as f:
     json.dump(doc, f, indent=2)
     f.write("\n")
 
+# --json emits the SAME document to stdout. Deliberately the same `doc` rather
+# than a second serializer: two writers of one contract drift, and the drift
+# shows up as a caller trusting a field the file no longer has. The evidence
+# file is still written either way, so --json adds a pipe without removing the
+# artifact.
+#
+# Written to FD 3, not stdout. The caller redirects this function's stdout to
+# /dev/null (it emits progress chatter the human path does not want), so a
+# plain stdout write here is discarded. FD 3 is opened by the caller only under
+# --json and routed to the real stdout.
+if os.environ.get("_V_JSON_STDOUT") == "1":
+    try:
+        with os.fdopen(os.dup(3), "w") as _jf:
+            _jf.write(json.dumps(doc, indent=2) + "\n")
+    except OSError:
+        # FD 3 not open: --json was requested but the caller did not wire it.
+        # Fail loudly rather than exit 0 having emitted nothing, which would
+        # look to a pipeline like a verify that produced an empty document.
+        sys.stderr.write("verify: --json requested but FD 3 is not open\n")
+        raise SystemExit(3)
+
 # ----- Markdown report -----
 def sev_rank(s):
     return {"Critical": 0, "High": 1, "Medium": 2, "Low": 3, "Info": 4}.get(s, 5)
@@ -2050,6 +2083,11 @@ OPTIONS:
                        Default: critical,high  (one notch looser than the
                        Loki build loop, which also blocks on medium).
     --no-llm           Accepted for forward-compat; LLM is already off in MVP.
+    --json             Emit the evidence document to stdout so it can be piped
+                       (`loki verify --json | jq .verdict`). The same document
+                       is still written to <out>/evidence.json. The human
+                       VERDICT banner moves to stderr so stdout stays valid
+                       JSON. The verdict and exit code are unchanged.
     --explain          Print a one-screen, skeptic-legible trust proof: every
                        gate that ran, its status, the runner/scanner that
                        produced the evidence, whether it is reproducible, plus
@@ -2093,16 +2131,16 @@ VERDICT MODEL:
     Uncommitted working-tree changes are not verified; commit them first. An
     empty diff yields CONCERNS (nothing to verify), never VERIFIED.
 
-EXIT CODES (this implementation):
+EXIT CODES:
     0  VERIFIED
     1  CONCERNS
     2  BLOCKED
     3  verifier error (could not complete; never silently passes)
 
-    NOTE: the verification spec (Section 1.1) lists 1=BLOCKED, 2=CONCERNS.
-    This implementation follows the build-task ordering (1=CONCERNS,
-    2=BLOCKED). A human must reconcile the two before the GitHub App consumes
-    these codes.
+    Severity rises with the code, so `[ $rc -ge 2 ]` means "at least blocked".
+    An early draft spec listed 1=BLOCKED, 2=CONCERNS; that ordering was
+    rejected and is not used anywhere. See docs/exit-codes.md for every
+    command's codes.
 
 OUTPUT:
     <out>/evidence.json   consolidated machine-readable evidence (schema 1.0)
@@ -2620,6 +2658,8 @@ verify_main() {
     # verify does NOT re-run gates: it reads a prior evidence.json and fails
     # closed if the repo has drifted since that evidence was graded.
     VERIFY_CHECK_FRESH=0
+    # Opt-in machine-readable stdout (--json). Default 0 = exactly today.
+    VERIFY_JSON=0
 
     # Fail-closed defaults. These globals are read at the end of this function
     # (the VERDICT banner and the function return code). verify_compute_verdict()
@@ -2644,6 +2684,16 @@ verify_main() {
                 block_on="$(printf '%s' "${2:-}" | tr '[:upper:]' '[:lower:]')"; shift 2 ;;
             --no-llm)
                 shift ;;
+            --json)
+                # Emit the evidence document to STDOUT so a caller can pipe it.
+                # The same document is still written to <out>/evidence.json --
+                # this adds a pipe, it does not move the artifact.
+                #
+                # Implies --quiet-banner: stdout must be JSON and nothing else,
+                # or `loki verify --json | jq` breaks on the human banner. The
+                # banner still goes to stderr, so an operator watching a
+                # terminal loses nothing.
+                VERIFY_JSON=1; shift ;;
             --explain)
                 # Render a one-screen, skeptic-legible trust proof: every gate
                 # that ran, its status, the runner/scanner that produced the
@@ -2793,10 +2843,21 @@ verify_main() {
 
     completed_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 
-    verify_emit_evidence "$out_dir" "$started_at" "$completed_at" "$block_on" >/dev/null || {
-        _verify_err "failed to emit evidence document"
-        return $VERIFY_EXIT_ERROR
-    }
+    # stdout is discarded (the emitter's own chatter is not wanted on the human
+    # path). Under --json, FD 3 is opened onto the REAL stdout so the emitter
+    # can write the evidence document there while everything else stays
+    # suppressed -- that is what keeps `loki verify --json | jq` parseable.
+    if [ "${VERIFY_JSON:-0}" = "1" ]; then
+        verify_emit_evidence "$out_dir" "$started_at" "$completed_at" "$block_on" 3>&1 >/dev/null || {
+            _verify_err "failed to emit evidence document"
+            return $VERIFY_EXIT_ERROR
+        }
+    else
+        verify_emit_evidence "$out_dir" "$started_at" "$completed_at" "$block_on" >/dev/null || {
+            _verify_err "failed to emit evidence document"
+            return $VERIFY_EXIT_ERROR
+        }
+    fi
 
     # Opt-in (--hosted): fold the embedded Autonomi Verify engine's verdict
     # fields into the just-written evidence.json. Fully additive and fail-open:
@@ -2814,9 +2875,14 @@ verify_main() {
         _verify_render_explain "$started_at" "$completed_at" "$VERIFY_VERDICT"
     fi
 
-    printf 'VERDICT: %s\n' "$VERIFY_VERDICT"
-    printf 'Evidence: %s/evidence.json\n' "$out_dir"
-    printf 'Report:   %s/report.md\n' "$out_dir"
+    # Under --json stdout carries the evidence document alone, so the human
+    # banner is redirected to stderr rather than dropped: an operator watching a
+    # terminal still sees the verdict, and `| jq` still parses.
+    _v_banner_fd=1
+    [ "${VERIFY_JSON:-0}" = "1" ] && _v_banner_fd=2
+    printf 'VERDICT: %s\n' "$VERIFY_VERDICT" >&$_v_banner_fd
+    printf 'Evidence: %s/evidence.json\n' "$out_dir" >&$_v_banner_fd
+    printf 'Report:   %s/report.md\n' "$out_dir" >&$_v_banner_fd
     # --hosted only: surface the enrichment in human output so the extra signal
     # is visible without parsing JSON. Printed solely when a fold succeeded;
     # the default path never sets VERIFY_HOSTED_SUMMARY, so it stays byte-identical.

package/completions/_loki

@@ -153,6 +153,7 @@ function _loki_commands {
         'memory:Memory commands'
         'compound:Knowledge compounding commands'
         'checkpoint:Snapshot and restore session state'
+        'cp:Snapshot and restore session state (alias of checkpoint)'
         'council:Completion council commands'
         'dogfood:Self-development statistics'
         'projects:Project registry commands'

package/completions/loki.bash

@@ -5,7 +5,7 @@ _loki_completion() {
     _init_completion || return
 
     # Main subcommands (must match autonomy/loki main case statement)
-    local main_commands="start quick monitor demo tour welcome init stop pause resume steer status next ship dashboard web serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise secrets cockpit secure own doctor watchdog audit metrics syslog onboard share proof explain plan report cost kpis stats test ci watch telemetry agent context ctx code run export review optimize heal modernize migrate cluster worktree wt trigger failover remote deploy docker mcp magic assets analyze compliance crash open otel preview quickstart rc rollback self-update sentrux setup-skill spec state template trust trust-metrics ultracode update verify voice why wiki bench cleanup logs grill docs cp version completions help"
+    local main_commands="start quick monitor demo tour welcome init stop pause resume steer status next ship dashboard web serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise secrets cockpit secure own handoff doctor watchdog audit metrics syslog onboard share proof receipt explain plan report cost kpis stats test ci watch telemetry agent context ctx code run export review optimize heal modernize migrate cluster worktree wt trigger failover remote deploy docker mcp magic assets analyze compliance crash open otel preview quickstart rc rollback self-update sentrux setup-skill spec state template trust trust-metrics ultracode update verify voice why wiki bench cleanup logs grill docs cp version completions help"
 
     # 1. If we are on the first argument (subcommand)
     if [[ $cword -eq 1 ]]; then

package/dashboard/__init__.py

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

package/docs/EVALUATING.md

@@ -154,6 +154,34 @@ expose something the CLI does not. If a competitor does ship output
 verification, this test is how we would find out, and the claim above would be
 corrected rather than defended.
 
+## 7. Headless latency, five trials per tool
+
+Same task, same machine, artifact verified by content, five trials each:
+
+| CLI | Success | Median | Range |
+| --- | --- | --- | --- |
+| opencode 1.18.9 | 5/5 | 11s | 4s to 265s |
+| codex-cli 0.146.0 | 4/5 | 69s | 48s to 80s (one 300s timeout) |
+
+**Read the range, not just the median.** opencode's first trial took 265
+seconds and the next four took 4 to 12. A new user experiences the 265, not the
+11. Reporting only the median would hide the thing they will actually feel.
+
+**The timeout is kept in.** Dropping codex's one failure would turn 4-of-5 into
+an implied 5-of-5 and overstate reliability.
+
+**Five trials, not one, and that is the point.** An earlier single-shot run of
+this same codex command timed out, and publishing it would have recorded
+"codex: timeout" as a fact about a competitor when the identical command
+completed in 51 seconds minutes later. The spread is the finding.
+
+**What this does not measure.** One trivial file-creation task is not a proxy
+for build quality, multi-iteration work, or brownfield capability. It measures
+headless invocation latency and nothing else. aider, Claude Code and
+cursor-agent have not been run on this task; Devin and Replit Agent ship no
+local CLI. Cost is not compared: codex ran on a free tier and opencode's
+per-call cost was not recorded.
+
 ---
 
 ## What we do not have

package/docs/PRIVACY.md

@@ -114,10 +114,33 @@ it sits below the base telemetry gate, every telemetry opt-out (`loki telemetry
 off` / `LOKI_TELEMETRY=off` / `DO_NOT_TRACK=1`) also disables it -- opt-out
 always wins.
 
+### 5. First-run blocker (anonymous, STRICT opt-in, default OFF)
+
+A `first_run_blocked` event naming which CLASS of dependency stopped a first
+run, sent at most ONCE per install. It sits behind the same strict second
+opt-in as build-outcome analytics above (`LOKI_ANALYTICS=on`), so it is off by
+default even with telemetry enabled.
+
+It exists because we could see that a first run was ATTEMPTED and nothing about
+whether it succeeded, which made "why does a trial not convert" unanswerable.
+A real example we found and fixed: on a machine with no AI provider CLI, one
+route ended with a dead end instead of pointing at `loki tour` (which needs no
+provider, no key and no spend). Nobody could see that happening.
+
+The ONLY field is `blocker`, clamped to this fixed enum:
+
+    no_provider | node | python3 | jq | git | curl | disk | skill_symlink | other
+
+Anything not on that list becomes `other`. It is deliberately coarse: `node` is
+enough to act on, and a version string or an install path would be a leak. It
+NEVER sends paths, versions, hostnames, spec text, or command lines -- a test
+(`tests/test-first-run-blocked-signal.sh`) feeds a filesystem path through the
+real emitter and fails the build if anything but `other` reaches the payload.
+
 This document and the first-run notice describe ALL paths. The model is unified:
 opt-out always wins and disables everything; crash reporting and usage telemetry
-opt in together (default ON for individuals); build-outcome analytics needs its
-own explicit second opt-in on top (default OFF).
+opt in together (default ON for individuals); build-outcome analytics and the
+first-run blocker each need an explicit second opt-in on top (default OFF).
 
 ## What is collected (the whitelist)
 

package/docs/air-gapped.md

@@ -0,0 +1,91 @@
+# Running without egress
+
+If your code cannot leave your network, most of this category is unavailable to
+you regardless of what the sales conversation suggests.
+
+## Where the tools actually stand
+
+Verified from vendor documentation, 2026-07-31:
+
+| Tool | Air-gapped |
+|---|---|
+| Devin | **No.** Single-tenant VPC via AWS PrivateLink, customer-managed KMS, a federal docs tree -- but "Devin's brain... always resides within Cognition's Cloud." |
+| Cursor | No. Cloud service; embeddings are uploaded (obfuscated and encrypted). |
+| Claude Code | Partly. Runs against Bedrock / Vertex / Foundry in your own cloud, so data residency is yours -- but a model endpoint is still required. |
+| Lovable, Replit, Emergent | No. Browser products on their infrastructure. |
+| opencode | Structurally yes (MIT, self-hostable) -- but no SOC2, SSO, audit logs, or support. |
+
+Devin's is the strongest enterprise packaging in the category and it still
+cannot run disconnected. That is a structural property of a hosted control
+plane, not an oversight.
+
+## What we measured
+
+Executed 2026-07-31 with outbound HTTP forced through an unroutable proxy --
+not a flag, not an assumption. Every one of these returned a real result with
+egress severed:
+
+| Command | Result |
+|---|---|
+| `loki version` | works |
+| `loki doctor --json` | works |
+| `loki plan <spec> --json` | works -- full cost and complexity estimate |
+| `loki proof list` | works |
+| `loki proof verify <id>` | works, and correctly reported `tree_drift: true` |
+| `loki heal <repo> --assess --json` | works -- maturity, ranked targets, runtime |
+
+The whole evaluate-before-you-buy path runs disconnected. You can assess a
+legacy codebase, estimate what a build would cost, and verify an existing
+receipt without a single packet leaving the machine.
+
+`loki proof verify` deserves emphasis: an auditor can re-check a receipt against
+the repository offline and get a genuine verdict, including detecting drift.
+That is the property competitors' dashboard-bound verification cannot have.
+
+## The one required egress, stated plainly
+
+```sh
+loki doctor --airgap
+```
+
+prints the egress inventory. Today it reports exactly one REQUIRED point:
+
+```
+REQUIRED  model inference -> https://api.anthropic.com
+          Set ANTHROPIC_BASE_URL to an in-network gateway, or switch to a
+          local-weights provider.
+optional  telemetry  [off]  disable: loki telemetry off (default off)
+```
+
+**We cannot run a build with no model at all.** Nobody can. What we can do is
+let you point at a model you host: set `ANTHROPIC_BASE_URL` to an in-network
+gateway, or run a provider with local weights. The engine abstracts over CLIs
+rather than over one vendor's API.
+
+Telemetry is off by default and every opt-out wins (`DO_NOT_TRACK=1`,
+`LOKI_TELEMETRY=off`, `~/.loki/config`). The adoption instrumentation added in
+v8.6.0 requires a second explicit opt-in on top of that -- see
+[PRIVACY.md](./PRIVACY.md).
+
+## Why `unknown` is the right answer offline
+
+`loki heal --assess` reports `dependency_staleness: unknown` and always will
+without a network call. We know your manifest pins lodash 3.x; we do not know
+what is current upstream, and we will not guess.
+
+That refusal is what makes the assessment trustworthy inside a disconnected
+network. A tool that fabricates a staleness number offline is more dangerous
+than one that declines.
+
+## Honest limits
+
+- **A model endpoint is required.** If you have no model at all -- not local,
+  not in-network -- we cannot build anything, and neither can anyone else.
+- **The five mutating healing phases need a provider.** Only `--assess` is
+  genuinely zero-dependency.
+- **Not measured here:** a full disconnected build against a local-weights
+  provider. The commands above were measured; that one was not, and this page
+  does not claim it.
+
+See [Kubernetes air-gapped install](../deploy/helm/README.md) for the
+cluster-side path.

package/docs/brownfield.md

@@ -0,0 +1,120 @@
+# Working on a codebase you already have
+
+Most of this category is built for starting from nothing. If you already have a
+repository -- especially a large, private, awkward one -- your options narrow
+fast.
+
+## Where the tools actually stand
+
+Verified from vendor documentation, 2026-07-31:
+
+| Tool | Existing repository |
+|---|---|
+| Lovable | **Cannot import one.** "You can only export from Lovable to GitHub"; two-way sync begins only after Lovable creates the repo. |
+| Replit Agent | Imports GitHub (public and private), Figma, ZIP -- into Replit's environment. |
+| Cursor | Indexes your repo; embeddings are uploaded, obfuscated and encrypted. |
+| Devin | Indexes the repo, plus YAML blueprints producing snapshots each session boots from. |
+| Loki | Runs in place, where the code already is. |
+
+That last row is the whole difference, and it is not a preference. For a private
+monorepo with internal dependencies and submodules, "upload it to our
+environment" is often not a thing anyone is permitted to do.
+
+**Credit where it is due:** Devin has the strongest documented modernization
+story of the four -- named playbooks for COBOL, Java upgrades, and
+SAS-to-PySpark. If you want a vendor-run modernization program, look at them
+seriously. What follows is what we do differently, not a claim that they are
+bad at this.
+
+## Start here: a read-only assessment that costs nothing
+
+```sh
+loki heal ./your-repo --assess --json
+```
+
+No provider call, no API key, no spend, no writes. It reports:
+
+- a **maturity level** with the reason stated (for example: "No test/spec files
+  detected: changes are unguarded")
+- **ranked targets** with blast-radius reasoning per file ("isolated (no inbound
+  imports -> low blast radius), 12 LOC")
+- **debt signals**: test ratio, TODO density
+- **the runtime it declares**: Node engine constraint, dependency count, and the
+  frameworks actually present in the manifest
+- **dependency lock status**
+
+This is the honest opening move: you learn where to start before committing to
+anything.
+
+### What it deliberately does not tell you
+
+`dependency_staleness` reports `unknown`, always, offline. We know your manifest
+pins lodash 3.x; we do not know what is current upstream without a network call,
+and we will not guess. That refusal is the same reason the assessment works
+inside an air-gapped network at all.
+
+## The healing phases
+
+```sh
+loki heal ./your-repo --phase archaeology   # map dependencies, catalog friction
+loki heal ./your-repo --phase stabilize     # add observability and tests, no behavior change
+loki heal ./your-repo --phase isolate       # adapter boundaries between components
+loki heal ./your-repo --phase modernize     # replace one component at a time, behind adapters
+loki heal ./your-repo --phase validate      # prove behavioral equivalence against the baseline
+```
+
+These call a provider and cost money. `--assess` does not.
+
+## Behavioral equivalence is the part worth arguing about
+
+Every tool in this category will tell you it preserved your business logic.
+Devin's COBOL page says it preserves "critical functionality." What none of them
+document is a *procedure* for proving it.
+
+That is the axis we build on:
+
+- **characterization tests** capture what the system does today, quirks
+  included, before anything is modernized
+- **friction classification** distinguishes accidental mess from load-bearing
+  weirdness -- the 30-second sleep that looks stupid and is actually a race-
+  condition fix nobody documented
+- **a backward-compatibility auditor** blocks removal of unclassified friction
+- **the validate phase** checks behavior against the recorded baseline
+
+Then the [Evidence Receipt](../README.md#the-evidence-receipt-dont-trust-the-agent-check-it)
+records what was proven and what was not, bound to the specific diff.
+
+"We prove behavior is unchanged" is a stronger claim than "we preserve business
+logic," and it is the one you can check.
+
+The full procedure -- what each phase does, what the friction taxonomy
+distinguishes, and where the safety gates sit -- is in
+[skills/healing.md](../skills/healing.md), with the research it draws on in
+[references/legacy-healing-patterns.md](../references/legacy-healing-patterns.md).
+
+### The friction question, concretely
+
+The hardest part of a legacy migration is not translating syntax. It is telling
+the difference between:
+
+- a `sleep 30` that is genuinely dead weight, and
+- a `sleep 30` that is the only thing preventing a race condition nobody wrote
+  down, whose author left in 2019
+
+Delete the second and the system breaks in production, weeks later, in a way
+nobody connects to the migration. This is why the auditor blocks removal of
+*unclassified* friction: not because the friction is sacred, but because
+"we do not know what this does yet" is a real state that deserves a name
+instead of a guess.
+
+## Honest scope
+
+- **Measured and working:** `--assess` on real repositories, verified by
+  execution.
+- **Implemented, not measured here:** the five mutating phases need a provider
+  and real spend; this page does not claim an end-to-end benchmark we have not
+  published.
+- **We do not do COBOL.** If your problem is a mainframe, we are not your
+  answer today.
+- **Your code stays put.** Nothing is uploaded to us -- there is no "us" in the
+  data path. See [cost controls](./cost-controls.md) for how spend is bounded.

package/docs/cost-controls.md

@@ -0,0 +1,88 @@
+# Cost controls
+
+You set the ceiling. We stop at it, and the receipt tells you where the money
+went.
+
+## Why this page exists
+
+"I paid for the AI's own mistakes" is one of the sharpest complaints in this
+category, and it is worth being precise about how our model differs.
+
+Most competitors sell credits. Lovable has already addressed the objection
+directly -- their "Try to fix" button does not consume credits, and their
+troubleshooting docs push you toward reverting or replanning instead of
+retrying the same prompt. That is a good policy and we are not claiming to have
+invented a better one.
+
+**Our model is different in kind: you bring your own provider credentials.** We
+never bill you, because we are never in the payment path. What we owe you
+instead is a hard ceiling and an honest account of what was spent -- which is
+what this page describes.
+
+## The three caps
+
+They bound different things, and a run that stalls needs all three.
+
+| Cap | Bounds | Default |
+|---|---|---|
+| `LOKI_BUDGET_LIMIT` | Total spend, in USD | unset (no cap) |
+| `LOKI_MAX_ITERATIONS` | Number of iterations | 1000 |
+| `LOKI_MAX_DURATION` | Wall-clock time | unset (no cap) |
+
+```sh
+LOKI_BUDGET_LIMIT=25 loki start ./prd.md
+loki start ./prd.md --max-duration 90m
+loki config set budget 25
+```
+
+**Why three and not one.** Spend and iterations both assume forward progress. A
+run that *stalls* -- a hung provider call, a wedged subprocess -- burns hours
+while spending almost nothing and completing no iteration, so neither of those
+breakers ever trips. The wall-clock cap is the one that catches it. We added it
+after a run burned $34 reaching an external timeout.
+
+## Hitting a cap is a FAILURE, not a success
+
+This is the part that matters for anyone automating against us.
+
+All three caps produce a **terminal failure**: exit 20 under
+`LOKI_DURABLE_STATE=1`, with a distinct status (`budget_exceeded`,
+`max_iterations_reached`, `max_duration_reached`) so the receipt and `loki why`
+can tell you *which* ceiling you hit and therefore which one to raise.
+
+`budget_exceeded` used to exit **0**, on the reasoning that a human would raise
+the cap and resume. That is true at a terminal and false inside a Kubernetes
+Job, where there is no human: the Job went Complete, the pipeline went green,
+and an incomplete build looked finished. Exit 0 now means the work is finished
+or a person deliberately stopped it -- never that we ran out of money mid-task.
+
+See [exit codes](./exit-codes.md) for the full contract.
+
+## Preview the cost before spending anything
+
+```sh
+loki plan ./prd.md --json
+```
+
+Reports complexity, estimated iterations, token usage and cost **without
+executing**. No provider call, no spend. `LOKI_CONFIG_DUMP=1 loki start ./prd.md`
+prints the resolved configuration and exits, so you can confirm your caps are
+actually set before a real run.
+
+## What you are charged for, stated plainly
+
+Every iteration calls your provider, including iterations spent re-running
+after a quality gate fails. **We do not exempt our own gate failures from your
+budget**, and pretending otherwise would be dishonest -- those calls really do
+consume your tokens.
+
+What we do instead:
+
+- the caps above bound the total, so a doom loop has a hard ceiling
+- the Evidence Receipt records iteration count and cost, so a re-run is visible
+  rather than buried
+- reaching a cap reports as a failure with the reason named, so you know whether
+  to raise the ceiling or narrow the spec
+
+If a run cost more than you expected, `loki proof show <id>` tells you where it
+went.