loki-mode 8.0.0 → 8.0.2

package/README.md

@@ -239,6 +239,46 @@ This needs Bun on your PATH (the SDK loop runs on the Bun runtime). `loki doctor
 
 **With a coding-agent CLI.** The classic path, and still the default: Loki drives a separate CLI (Claude Code is the recommended one) plus a couple of common tools on your PATH.
 
+**With a different model or provider.** Loki is not tied to Anthropic. Anything
+that speaks the Anthropic Messages API works: OpenRouter, Ollama, LiteLLM, vLLM,
+or your own gateway. Point `ANTHROPIC_BASE_URL` at the endpoint and name the
+model with `LOKI_MODEL_OVERRIDE`:
+
+```bash
+# OpenRouter (hundreds of models, one key)
+export ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
+export ANTHROPIC_API_KEY=sk-or-...
+export LOKI_MODEL_OVERRIDE=<model-id-from-openrouter.ai/models>
+loki start prd.md
+
+# Ollama, fully local (no API key, no per-token cost)
+export ANTHROPIC_BASE_URL=http://localhost:11434/v1
+export LOKI_MODEL_OVERRIDE=<model you have pulled, e.g. the output of `ollama list`>
+loki start prd.md
+
+# LiteLLM / vLLM / any self-hosted gateway
+export ANTHROPIC_BASE_URL=https://your-gateway.internal/v1
+export ANTHROPIC_API_KEY=...
+export LOKI_MODEL_OVERRIDE=<whatever your gateway calls the model>
+loki start prd.md
+```
+
+**Set both variables.** `LOKI_MODEL_OVERRIDE` is what makes the alt-provider
+path work: without it Loki keeps asking for `opus` / `sonnet` / `haiku`, which
+only Anthropic resolves, and most providers reject those names outright. A
+proxy that maps the aliases for you (LiteLLM can) is the one exception.
+
+Model IDs are not listed here on purpose -- OpenRouter's catalogue changes every
+week, and a stale ID in a README is a failure you would hit at runtime. Take the
+exact string from your provider's own model list.
+
+Both routes honor these variables identically -- the bundled-SDK path and the
+Claude Code CLI path -- and `loki doctor` reports the endpoint it detected plus a
+warning if the model override is missing.
+
+The quality gates, the completion council, and the Evidence Receipt do not care
+which model produced the code. They check what was actually built.
+
 Either way, run `loki doctor` any time and it tells you exactly what is present and what is missing, with a copy-pasteable install command for each gap.
 
 ```bash
@@ -715,7 +755,3 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 **[Autonomi](https://www.autonomi.dev/)** | **[Documentation](wiki/Home.md)** | **[Changelog](CHANGELOG.md)** | **[Comparisons](references/competitive-analysis.md)**
 
 </div>
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/chart?repos=asklokesh/loki-mode&type=timeline&legend=bottom-right)](https://www.star-history.com/?repos=asklokesh%2Floki-mode&type=timeline&legend=bottom-right)

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v8.0.0
+# Loki Mode v8.0.2
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -469,4 +469,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v8.0.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**
+**v8.0.2 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-8.0.0
+8.0.2

package/autonomy/lib/proof-generator.py

@@ -766,12 +766,58 @@ def _diff_sha256(files_changed):
 
 
 def _git_diffstat(target_dir, include_diffs):
-    """Return the final worktree diff relative to this iteration's base."""
-    return collect_workspace_diff(
-        target_dir,
-        os.environ.get("_LOKI_ITER_START_SHA", "").strip(),
-        include_diffs,
-    )
+    """Return the final worktree diff relative to the RUN's base.
+
+    The receipt is a run-level document, so its diff stat must span the WHOLE
+    run. This previously passed _LOKI_ITER_START_SHA -- the per-ITERATION
+    baseline -- so a multi-iteration run attested only to the changes since its
+    last iteration. Measured on a real 2-commit run: 850 insertions + 76
+    deletions reported where the run actually produced 1300 insertions.
+
+    That matters more than an ordinary display bug: the returned object flows
+    into _diff_sha256, the receipt's integrity hash, which is written on EVERY
+    run. A verifier recomputing it therefore attests to the understated stat,
+    and the receipt is exactly the artifact users are told to trust. (Detached
+    GPG signing is a separate opt-in layer gated on LOKI_PROOF_GPG_KEY and
+    default OFF; when enabled it signs these same bytes, but the integrity hash
+    is the always-on path.)
+
+    Order of preference:
+      1. _LOKI_RUN_START_SHA -- the run's own baseline (run.sh exports it).
+      2. The empty tree -- correct for a GREENFIELD run (a repo with no commits
+         at start), where "everything that now exists" IS the run's output and
+         there is no earlier commit to diff against.
+      3. Empty string -- let workspace_diff apply its own fallbacks.
+    """
+    base = os.environ.get("_LOKI_RUN_START_SHA", "").strip()
+    if not base:
+        # Greenfield: no baseline commit existed when the run started.
+        base = _empty_tree_sha(target_dir)
+    files_changed, diffs = collect_workspace_diff(target_dir, base, include_diffs)
+    # Return the base too. git_facts records base_sha NEXT TO diff and
+    # diff_sha256; if they disagree the signed receipt is internally
+    # inconsistent and a verifier recomputing the diff from base_sha gets a
+    # different answer than the one that was signed.
+    return files_changed, diffs, base
+
+
+def _empty_tree_sha(repo_dir):
+    """The canonical empty-tree object, or "" when git is unavailable.
+
+    Diffing against this yields "everything that currently exists", which is the
+    truthful baseline for a run that started from a repo with no commits.
+    """
+    try:
+        out = subprocess.run(
+            ["git", "hash-object", "-t", "tree", os.devnull],
+            cwd=repo_dir,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except Exception:
+        return ""
+    return out.stdout.strip() if out.returncode == 0 else ""
 
 
 def _collect_iterations(loki_dir):
@@ -908,7 +954,7 @@ def _build_proof(args, loki_dir, target_dir, repo_root):
     provider_name = args.provider or os.environ.get("PROVIDER_NAME") or "claude"
     model = _collect_model(loki_dir, model_from_eff)
 
-    files_changed, diffs = _git_diffstat(target_dir, args.include_diffs)
+    files_changed, diffs, diff_base_sha = _git_diffstat(target_dir, args.include_diffs)
     iterations = _collect_iterations(loki_dir)
     spec = _collect_spec(loki_dir, target_dir)
     council = _collect_council(loki_dir)
@@ -944,7 +990,8 @@ def _build_proof(args, loki_dir, target_dir, repo_root):
     # recompute the hash. True non-forgeability requires the neutral signed record
     # (service-held key). See proof-verify.py verify() docstring.
     git_facts = {
-        "base_sha": os.environ.get("_LOKI_ITER_START_SHA", "").strip(),
+        # Must be the SAME base the diff above was computed against.
+        "base_sha": diff_base_sha,
         "head_sha": _git_head_sha(target_dir),
         "diff": files_changed,
         "diff_sha256": _diff_sha256(files_changed),

package/autonomy/lib/proof-verify.py

@@ -113,11 +113,26 @@ def _is_git_repo(repo_dir):
 
 
 def _rev_resolvable(repo_dir, ref):
-    """True iff `ref` resolves to a commit in repo_dir."""
+    """True iff `ref` names something in repo_dir that a diff can be taken from.
+
+    Accepts a COMMIT or a TREE. The tree case is load-bearing: a greenfield run
+    starts in a repo with no commits, so the generator records the EMPTY TREE
+    (4b825dc6...) as its baseline -- "everything that now exists". That object
+    is a tree, not a commit, so a commit-only check rejects it and the verifier
+    reports "base ref unresolvable" for a perfectly genuine proof.
+
+    `git diff <empty-tree>` works fine, so the diff really is re-derivable; only
+    the resolvability probe was too narrow. This does NOT loosen the forgery
+    defense -- an unknown or fabricated SHA still resolves as neither and is
+    still rejected.
+    """
     if not ref:
         return False
-    out = _git(repo_dir, ["rev-parse", "--verify", "--quiet", str(ref) + "^{commit}"])
-    return bool(out and out.strip())
+    for kind in ("commit", "tree"):
+        out = _git(repo_dir, ["rev-parse", "--verify", "--quiet", "%s^{%s}" % (ref, kind)])
+        if out and out.strip():
+            return True
+    return False
 
 
 def _numstat(repo_dir, base, head):

package/autonomy/lib/workspace_diff.py

@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import os
 import subprocess
 
 
@@ -74,6 +75,22 @@ def collect_workspace_diff(repo_dir, base, include_diffs=False):
     comparison = base or "HEAD~1"
     raw = _git(repo_dir, ["diff", "--no-renames", "--numstat", "-z", comparison, "--"])
     if raw is None:
+        # HEAD~1 is unusable (single-commit or empty repo). Fall back to the
+        # EMPTY TREE, not to a bare "HEAD".
+        #
+        # A bare "HEAD" compares HEAD to the working tree, so it sees only
+        # UNCOMMITTED changes and silently drops everything the run committed.
+        # Measured on a real greenfield run: bare HEAD reported 5 files where
+        # the truth was 9. The empty tree yields "everything that now exists",
+        # which is the correct answer when no earlier commit exists to diff
+        # against -- and it agrees with HEAD~1 on runs where both are valid.
+        empty_tree = _git(repo_dir, ["hash-object", "-t", "tree", os.devnull])
+        if empty_tree:
+            comparison = empty_tree.strip()
+            raw = _git(repo_dir, ["diff", "--no-renames", "--numstat", "-z", comparison, "--"])
+    if raw is None:
+        # Last resort: worktree-only. Undercounts a run that committed its work,
+        # so it is reached only when even the empty-tree diff failed.
         comparison = "HEAD"
         raw = _git(repo_dir, ["diff", "--no-renames", "--numstat", "-z", comparison, "--"])
     if raw is None:

package/autonomy/loki

@@ -3896,6 +3896,8 @@ WHYJSON
     _LOKI_WHY_LAST_ERROR="$loki_dir/state/LAST_ERROR.json" \
     _LOKI_WHY_UNCERTAINTY="$loki_dir/signals/UNCERTAINTY_ESCALATION" \
     _LOKI_WHY_CONVERGENCE="$loki_dir/council/convergence.log" \
+    _LOKI_WHY_GATE="$loki_dir/signals/GATE_ESCALATION.json" \
+    _LOKI_WHY_TARGET="${TARGET_DIR:-$(dirname "$loki_dir")}" \
     _LOKI_WHY_HANDOFFS="$loki_dir/memory/handoffs" python3 - <<'WHYTXT'
 import json, os, glob
 def load(p):
@@ -3953,6 +3955,11 @@ GUIDE = {
                 "If no build is active it likely crashed; in durable mode (LOKI_DURABLE_STATE=1) a restart resumes, else loki start re-runs."),
     "exited": ("The build process exited mid-iteration (likely a crash, kill, or empty provider output).",
                "Read .loki/logs/ for the last error; if nothing is running it crashed -- re-run with loki start, or loki resume in durable mode."),
+    # A real terminal state that had no entry, so `loki why` answered the one
+    # question it exists to answer with "No diagnosis mapping for this status".
+    "inconclusive_spec_contradiction": (
+        "Loki could not reconcile parts of the spec, so it stopped rather than guess.",
+        "The specific contradictions are in .loki/assumptions/ledger.md -- resolve them in the spec, then re-run."),
 }
 meaning, action = GUIDE.get(status, ("No diagnosis mapping for this status; see the raw fields below.",
                                      "Check loki status and .loki/logs/ for detail."))
@@ -3979,13 +3986,66 @@ if iters is not None:
     print(f"  Iterations  : {iters}")
 if comp.get("branch"):
     print(f"  Branch      : {comp['branch']}{comp_label}")
-if comp.get("files_changed") is not None:
-    print(f"  Changes     : {comp.get('files_changed',0)} files (+{comp.get('insertions',0)}/-{comp.get('deletions',0)}){comp_label}")
+_fc = comp.get("files_changed")
+if _fc is not None:
+    if _fc == 0:
+        # A recorded 0 is NOT trustworthy on its own: a greenfield run whose
+        # baseline never resolved records 0 while having committed real work.
+        # Saying "0 files" flatly told users nothing was built on a run that
+        # produced 9 files and 1300 insertions. Re-derive from git, and only
+        # claim zero when git agrees.
+        _real = None
+        try:
+            import subprocess as _sp
+            _tgt = os.environ.get("_LOKI_WHY_TARGET") or "."
+            _base = (comp.get("start_sha") or "").strip()
+            if not _base or _base == "HEAD":
+                _base = _sp.run(["git", "-C", _tgt, "hash-object", "-t", "tree", os.devnull],
+                                capture_output=True, text=True, timeout=10).stdout.strip()
+            if _base:
+                _o = _sp.run(["git", "-C", _tgt, "diff", "--shortstat", f"{_base}..HEAD",
+                              "--", ".", ":(exclude).loki/"],
+                             capture_output=True, text=True, timeout=15).stdout.strip()
+                if _o:
+                    _real = _o
+        except Exception:
+            _real = None
+        if _real:
+            print(f"  Changes     : {_real}  (re-derived; the run record said 0)")
+        else:
+            print(f"  Changes     : none recorded (the run did not resolve a baseline)")
+    else:
+        print(f"  Changes     : {_fc} files (+{comp.get('insertions',0)}/-{comp.get('deletions',0)}){comp_label}")
 if comp.get("pr_url"):
     print(f"  PR          : {comp['pr_url']}{comp_label}")
+
+# Name the gate that actually stopped the run. Without this the user is told to
+# "resume", which the run's own pause notice warns will stop at the same gate.
+_gate = load(os.environ.get("_LOKI_WHY_GATE", "")) or {}
+_gname = str(_gate.get("gate", "") or "").strip()
+if _gname:
+    _gc, _gt = _gate.get("count"), _gate.get("threshold")
+    _detail = f"{_gname} (failed {_gc} times, threshold {_gt})" if isinstance(_gc, int) and isinstance(_gt, int) else _gname
+    print(f"  Blocked by  : {_detail}")
+
 print()
 print(f"  What happened: {meaning}")
-print(f"  What to do   : {action}")
+if _gname:
+    print(f"  What to do   : Read the {_gname} findings and fix what they name, then resume.")
+    print(f"                 Resuming unchanged will stop at the same gate again.")
+    _art = str(_gate.get("latest_artifact", "") or "")
+    if _art:
+        # Make the pointer relative to the workspace. The recorded value is an
+        # absolute path from the machine that ran the build -- on the preserved
+        # run it names a /var/folders temp dir that no longer exists, so the one
+        # actionable pointer in the whole notice led nowhere. Anchor on
+        # ".loki/" so it works even when the run happened elsewhere.
+        _i = _art.find(".loki/")
+        if _i != -1:
+            _art = _art[_i:]
+        print(f"                 Findings: {_art}")
+else:
+    print(f"  What to do   : {action}")
 
 # RUN-25 iter 22b/iter 23 (Wave D #6): when a run is PAUSED / live and actually
 # STUCK, name the REAL stall reason instead of the generic "resume". The runner
@@ -11025,6 +11085,13 @@ except Exception:
         fi
     else
         echo -e "  ${YELLOW}WARN${NC}  Bun not found -- 'loki cockpit' uses the text summary + browser dashboard (install bun for the inline-image frame)"
+        # Report the protocol line here too. Without it doctor's Cockpit section
+        # is asymmetric: the bun branch prints BOTH "Inline-image protocol" and
+        # "Render path", the no-bun branch printed only "Render path". A user
+        # reading doctor on a machine without bun could not tell whether the
+        # inline-image path was unsupported by their terminal or simply never
+        # probed. Naming the reason keeps the section self-explanatory.
+        echo -e "  ${DIM}  --  ${NC}  Inline-image protocol: not probed (needs bun to run the cockpit renderer)"
         echo -e "  ${DIM}  --  ${NC}  Render path: text + browser dashboard"
     fi
     echo ""

package/autonomy/run.sh

@@ -2830,6 +2830,30 @@ _loki_check_workspace_writable() {
 # is missing, when LOKI_SKIP_NET_PREFLIGHT=1, when ANTHROPIC_BASE_URL is set (alt
 # provider endpoint we cannot assume), or for any provider whose endpoint we do
 # not know. It NEVER blocks the build.
+# Alt-provider guard: ANTHROPIC_BASE_URL routes Loki at a non-Anthropic endpoint
+# (OpenRouter, Ollama, LiteLLM, vLLM, self-hosted). The tier aliases Loki resolves
+# by default -- opus / sonnet / haiku -- are Anthropic-only names, and most
+# alt-providers reject them outright, so the run dies at the FIRST model call with
+# a provider-side error that is hard to trace back to the missing override.
+#
+# LOKI_MODEL_OVERRIDE is what makes that path work (providers/claude.sh:520 and
+# loki-ts/src/runner/providers.ts:328 both apply it only when BOTH vars are set).
+# `loki doctor` already warns on this, but doctor is opt-in and the run is not.
+#
+# NON-FATAL by design: a mapping proxy (LiteLLM can do this) legitimately resolves
+# the aliases server-side, so this is a warning and never a block. Emitted once per
+# run, and silent unless an alt endpoint is actually configured.
+_loki_warn_alt_provider_model_alias() {
+    [ -n "${ANTHROPIC_BASE_URL:-}" ] || return 0
+    [ -z "${LOKI_MODEL_OVERRIDE:-}" ] || return 0
+    log_warn "ANTHROPIC_BASE_URL is set (${ANTHROPIC_BASE_URL}) but LOKI_MODEL_OVERRIDE is not."
+    log_warn "  Loki will ask for the Anthropic tier aliases (opus/sonnet/haiku), which most"
+    log_warn "  alt-providers do not serve. Set the exact model id your endpoint expects:"
+    log_warn "    export LOKI_MODEL_OVERRIDE=<model-id>   # e.g. from 'ollama list' or your provider's model page"
+    log_warn "  Ignore this if your gateway maps those aliases for you (LiteLLM can)."
+    return 0
+}
+
 _loki_check_network_reachable() {
     local provider="${1:-claude}"
     [ "${LOKI_SKIP_NET_PREFLIGHT:-}" = "1" ] && return 0
@@ -2874,6 +2898,7 @@ validate_api_keys() {
     if ! _loki_check_network_reachable "$provider"; then
         return 1
     fi
+    _loki_warn_alt_provider_model_alias
 
     # Zero-friction auth preflight for LOCAL runs (must run BEFORE the early
     # return below, which exits for non-Docker/K8s envs). When claude is the
@@ -3889,6 +3914,33 @@ notify_rate_limit() {
 # written even when desktop notifications are disabled. emit_completion_summary
 # below is the wrapper that writes the files AND (gated) fires the desktop ping.
 #===============================================================================
+# Read the gate escalation signal into one human line, or print nothing.
+# Shared by COMPLETION.txt's per-outcome guidance and PAUSED.md so the two never
+# disagree about why a run stopped. Best-effort: a missing or corrupt signal
+# yields an empty string, and the caller degrades to generic guidance.
+_loki_summary_gate_reason() {
+    local loki_dir="${1:-${TARGET_DIR:-.}/.loki}"
+    [ -s "$loki_dir/signals/GATE_ESCALATION.json" ] || return 0
+    _LOKI_GR_FILE="$loki_dir/signals/GATE_ESCALATION.json" python3 -c '
+import json, os, sys
+try:
+    d = json.load(open(os.environ["_LOKI_GR_FILE"]))
+except Exception:
+    sys.exit(0)
+if not isinstance(d, dict):
+    sys.exit(0)
+gate = str(d.get("gate", "") or "").strip()
+if not gate:
+    sys.exit(0)
+count = d.get("count")
+thr = d.get("threshold")
+if isinstance(count, int) and isinstance(thr, int):
+    print("%s (failed %d times, threshold %d)" % (gate, count, thr))
+else:
+    print(gate)
+' 2>/dev/null || true
+}
+
 build_completion_summary() {
     local outcome="${1:-complete}"
     local loki_dir="${TARGET_DIR:-.}/.loki"
@@ -3944,7 +3996,30 @@ except Exception:
         fi
         review_cmd="git diff ${start_sha}..HEAD -- . ':(exclude).loki/'"
     else
-        review_cmd="git diff HEAD -- . ':(exclude).loki/'"
+        # No baseline SHA. This is the GREENFIELD case: the run started in a repo
+        # with no commits, so `git rev-parse --verify HEAD` correctly produced
+        # nothing (see the start-sha capture). Everything the run built is new.
+        #
+        # Without this branch the counts stayed at zero and a user was told
+        # "files_changed: 0" about a run that had produced real, committed,
+        # working code -- observed on a PRD benchmark that built 4 files and
+        # passed 28/28 of its own tests, yet reported 0. Diff against the empty
+        # tree so the summary reports what was actually created.
+        local _empty_tree
+        _empty_tree="$( (cd "${TARGET_DIR:-.}" && git hash-object -t tree /dev/null) 2>/dev/null || true )"
+        if [ -n "$_empty_tree" ] && (cd "${TARGET_DIR:-.}" && git rev-parse --verify HEAD >/dev/null 2>&1); then
+            diff_stat="$( (cd "${TARGET_DIR:-.}" && git diff --stat "${_empty_tree}..HEAD" "${_summary_pathspec[@]}") 2>/dev/null || true )"
+            local _shortstat_new
+            _shortstat_new="$( (cd "${TARGET_DIR:-.}" && git diff --shortstat "${_empty_tree}..HEAD" "${_summary_pathspec[@]}") 2>/dev/null || true )"
+            if [ -n "$_shortstat_new" ]; then
+                files_changed="$(printf '%s\n' "$_shortstat_new" | grep -oE '[0-9]+ file' | grep -oE '[0-9]+' | head -1)"
+                insertions="$(printf '%s\n' "$_shortstat_new" | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' | head -1)"
+                deletions="$(printf '%s\n' "$_shortstat_new" | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' | head -1)"
+            fi
+            review_cmd="git diff ${_empty_tree}..HEAD -- . ':(exclude).loki/'"
+        else
+            review_cmd="git diff HEAD -- . ':(exclude).loki/'"
+        fi
     fi
     [ -z "$files_changed" ] && files_changed=0
     [ -z "$insertions" ] && insertions=0
@@ -4073,6 +4148,52 @@ except Exception:
                 esac
                 ;;
         esac
+
+        # Per-outcome next step. Deliberately NOT nested inside the
+        # files_changed==0 case above: a run that stops for a gate reason has
+        # usually built plenty, and that is exactly the run whose user most needs
+        # to be told what to do. Keying this on an empty diff would silence it
+        # for the case that motivated it.
+        #
+        # Measured on the PRD benchmark: outcome=intervention with 9 files built
+        # and 28/28 tests passing produced NO guidance at all, because the old
+        # block covered only complete|max_iterations.
+        case "$outcome" in
+            intervention)
+                echo ""
+                echo "Loki stopped and needs a decision from you."
+                _cs_gate="$(_loki_summary_gate_reason "$loki_dir")"
+                if [ -n "$_cs_gate" ]; then
+                    echo "  Blocked by: $_cs_gate"
+                    echo "  The findings say exactly what to change. Fix those, then resume:"
+                else
+                    echo "  See .loki/PAUSED.md for the reason and .loki/CONTINUITY.md for context."
+                    echo "  Resume with:"
+                fi
+                echo "    rm .loki/PAUSE        # resume this run"
+                echo "    touch .loki/STOP      # end it instead"
+                echo "  Resuming without addressing the finding will stop at the same gate again."
+                ;;
+            failed)
+                echo ""
+                echo "The run failed. What went wrong:"
+                echo "  loki why              # the classified cause, in one line"
+                echo "  .loki/logs/           # the full session log"
+                echo "Anything already committed is listed above and is yours to keep or discard."
+                ;;
+            stopped|force_stopped)
+                echo ""
+                echo "The run was stopped before it finished."
+                echo "Work committed up to that point is listed above. To continue from here:"
+                echo "  loki start <your spec>   # a fresh run over the current tree"
+                ;;
+            inconclusive_spec_contradiction)
+                echo ""
+                echo "Loki could not reconcile parts of the spec, so it stopped rather than"
+                echo "guess. The specific contradictions are in .loki/assumptions/ledger.md."
+                echo "Resolve those in the spec, then re-run."
+                ;;
+        esac
     } > "$loki_dir/COMPLETION.txt" 2>/dev/null || true
 
     # ---- Durable machine-readable file: .loki/state/completion.json -----------
@@ -20065,7 +20186,17 @@ except Exception:
     fi
 
     if [ "${ITERATION_COUNT:-0}" -eq 0 ] || [ ! -s "$_start_sha_file" ]; then
-        (cd "${TARGET_DIR:-.}" && git rev-parse HEAD 2>/dev/null) > "$_start_sha_file" 2>/dev/null || true
+        # --verify is load-bearing. In a repo with NO commits yet (every
+        # greenfield build: git init, nothing committed), plain
+        # `git rev-parse HEAD` exits 128 but still prints the literal string
+        # "HEAD" ON STDOUT -- so 2>/dev/null does NOT suppress it and the
+        # unresolved ref name gets captured as the start SHA. Every downstream
+        # diff then becomes `git diff HEAD..HEAD`, which is ALWAYS empty: the
+        # completion council blocks with reason "empty_diff" and can never see
+        # the work, so it can never vote done and the run burns to the cap.
+        # `--verify` resolves-or-fails, emitting nothing on failure, which
+        # leaves the file empty and lets consumers apply their no-baseline path.
+        (cd "${TARGET_DIR:-.}" && git rev-parse --verify HEAD 2>/dev/null) > "$_start_sha_file" 2>/dev/null || true
     fi
     _LOKI_RUN_START_SHA="$(cat "$_start_sha_file" 2>/dev/null || echo "")"
     export _LOKI_RUN_START_SHA
@@ -20474,7 +20605,11 @@ except Exception as exc:
         # v7.6.4 B-3a fix: capture iteration-start git SHA so auto_capture_episode
         # can diff against this baseline (not just HEAD, which is empty after
         # loki's per-iteration auto-commit makes the new files HEAD).
-        _LOKI_ITER_START_SHA=$(cd "${TARGET_DIR:-.}" && git rev-parse HEAD 2>/dev/null || echo "")
+        # --verify: without it, a no-commits-yet repo makes `git rev-parse HEAD`
+        # print the literal "HEAD" on STDOUT while exiting 128, so the
+        # `|| echo ""` fallback never fires and the unresolved ref name is
+        # captured as a baseline. See the start-sha capture above.
+        _LOKI_ITER_START_SHA=$(cd "${TARGET_DIR:-.}" && git rev-parse --verify HEAD 2>/dev/null || echo "")
         export _LOKI_ITER_START_SHA
         _LOKI_ITER_START_TREE=$(_loki_snapshot_workspace_tree "${TARGET_DIR:-.}" 2>/dev/null || echo "")
         export _LOKI_ITER_START_TREE
@@ -22925,6 +23060,46 @@ Current state is saved. You can inspect:
 - `.loki/logs/` - Session logs
 EOF
 
+    # Say WHY it paused. The block above is static boilerplate: a user who comes
+    # back to a paused run learns how to resume but not what stopped it, and has
+    # to go spelunking in .loki/signals to find out. Observed on a PRD benchmark
+    # where a gate escalation paused a run that had produced 9 files and 28
+    # passing tests -- the pause was correct, the report told them nothing.
+    # Best-effort and append-only: never let a formatting failure block a pause.
+    {
+        _pause_reason_file="$loki_dir/signals/GATE_ESCALATION"
+        if [ -s "$_pause_reason_file" ]; then
+            printf '\n## Why this paused\n\n'
+            printf 'A quality gate stayed blocked across repeated attempts, so Loki stopped\n'
+            printf 'rather than keep spending on a loop that was not converging.\n\n'
+            _esc_gate="$(python3 -c 'import json,sys
+try:
+    d = json.load(open(sys.argv[1]))
+    print("%s (failed %s times, threshold %s)" % (d.get("gate","?"), d.get("count","?"), d.get("threshold","?")))
+except Exception:
+    print("")' "$loki_dir/signals/GATE_ESCALATION.json" 2>/dev/null || true)"
+            [ -n "$_esc_gate" ] && printf -- '- Gate: %s\n' "$_esc_gate"
+            _esc_art="$(python3 -c 'import json,sys
+try:
+    print(json.load(open(sys.argv[1])).get("latest_artifact","") or "")
+except Exception:
+    print("")' "$loki_dir/signals/GATE_ESCALATION.json" 2>/dev/null || true)"
+            [ -n "$_esc_art" ] && printf -- '- Findings: %s\n' "$_esc_art"
+            printf '\nRead the findings, fix what they name, then resume. Resuming without a\nchange will most likely stop at the same gate again.\n'
+        fi
+        # What DID get built, so a paused run never reads as "nothing happened".
+        _pause_head="$( (cd "${TARGET_DIR:-.}" && git rev-parse --verify HEAD) 2>/dev/null || true )"
+        if [ -n "$_pause_head" ]; then
+            _pause_base="$( (cd "${TARGET_DIR:-.}" && git hash-object -t tree /dev/null) 2>/dev/null || true )"
+            [ -s "$loki_dir/state/start-sha" ] && _pause_base="$(cat "$loki_dir/state/start-sha" 2>/dev/null)"
+            _pause_stat="$( (cd "${TARGET_DIR:-.}" && git diff --shortstat "${_pause_base}..HEAD" -- . ':(exclude).loki/') 2>/dev/null || true )"
+            if [ -n "$_pause_stat" ]; then
+                printf '\n## What was built before the pause\n\n%s\n' "$_pause_stat"
+                printf '\nReview it with:\n  git diff %s..HEAD -- . ":(exclude).loki/"\n' "$_pause_base"
+            fi
+        fi
+    } >> "$loki_dir/PAUSED.md" 2>/dev/null || true
+
     # Wait for resume signal (unified: file removal, keyboard, or STOP)
     while [ "$PAUSED" = "true" ]; do
         # Check for stop signal

package/dashboard/__init__.py

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

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var k_=Object.create;var{getPrototypeOf:x_,defineProperty:oK,getOwnPropertyNames:S_}=Object;var y_=Object.prototype.hasOwnProperty;function b_(Z){return this[Z]}var __,f_,h_=(Z,X,Q)=>{var Y=Z!=null&&typeof Z==="object";if(Y){var J=X?__??=new WeakMap:f_??=new WeakMap,z=J.get(Z);if(z)return z}Q=Z!=null?k_(x_(Z)):{};let K=X||!Z||!Z.__esModule?oK(Q,"default",{value:Z,enumerable:!0}):Q;for(let $ of S_(Z))if(!y_.call(K,$))oK(K,$,{get:b_.bind(Z,$),enumerable:!0});if(Y)J.set(Z,K);return K};var VQ=(Z,X)=>()=>(X||Z((X={exports:{}}).exports,X),X.exports);var v_=(Z)=>Z;function g_(Z,X){this[Z]=v_.bind(null,X)}var c0=(Z,X)=>{for(var Q in X)oK(Z,Q,{get:X[Q],enumerable:!0,configurable:!0,set:g_.bind(X,Q)})};var p=(Z,X)=>()=>(Z&&(X=Z(Z=0)),X);var t0=import.meta.require;var EO={};c0(EO,{lokiDir:()=>j0,homeLokiDir:()=>I4,findRepoRootForVersion:()=>tK,REPO_ROOT:()=>Q8});import{resolve as s7,dirname as rK}from"path";import{fileURLToPath as m_}from"url";import{existsSync as qQ}from"fs";import{homedir as u_}from"os";function p_(){let Z=DO;for(let X=0;X<6;X++){if(qQ(s7(Z,"VERSION"))&&qQ(s7(Z,"autonomy/run.sh")))return Z;let Q=rK(Z);if(Q===Z)break;Z=Q}return s7(DO,"..","..","..")}function tK(Z){let X=Z;for(let Q=0;Q<6;Q++){if(qQ(s7(X,"VERSION"))&&qQ(s7(X,"autonomy/run.sh")))return X;let Y=rK(X);if(Y===X)break;X=Y}return s7(Z,"..","..","..")}function j0(){return process.env.LOKI_DIR??s7(process.cwd(),".loki")}function I4(){return s7(u_(),".loki")}var DO,Q8;var G8=p(()=>{DO=rK(m_(import.meta.url));Q8=p_()});import{readFileSync as d_}from"fs";import{resolve as c_,dirname as l_}from"path";import{fileURLToPath as i_}from"url";function _3(){if(f5!==null)return f5;let Z="8.0.0";if(typeof Z==="string"&&Z.length>0)return f5=Z,f5;try{let X=l_(i_(import.meta.url)),Q=tK(X);f5=d_(c_(Q,"VERSION"),"utf-8").trim()}catch{f5="unknown"}return f5}var f5=null;var GQ=p(()=>{G8()});var kO={};c0(kO,{runOrThrow:()=>Wf,run:()=>D0,readStreamCapped:()=>HQ,commandVersion:()=>qf,commandExists:()=>H9,ShellError:()=>eK,MAX_STDOUT_BYTES:()=>RO});async function HQ(Z,X=RO){let Q=Z.getReader(),Y=new TextDecoder,J="",z=0;try{while(z<X){let{done:K,value:$}=await Q.read();if(K)break;if(!$)continue;if(z+=$.byteLength,z>X){let W=$.byteLength-(z-X);J+=Y.decode($.subarray(0,W),{stream:!0});break}J+=Y.decode($,{stream:!0})}J+=Y.decode()}finally{try{await Q.cancel()}catch{}Q.releaseLock()}return J}async function D0(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([HQ(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 Wf(Z,X={}){let Q=await D0(Z,X);if(Q.exitCode!==0)throw new eK(`command failed (${Q.exitCode}): ${Z.join(" ")}`,Q.exitCode,Q.stdout,Q.stderr);return Q}async function H9(Z){let X=Vf(Z),Q=await D0(["sh","-c",`command -v ${X}`],{timeoutMs:5000});if(Q.exitCode===0)return Q.stdout.trim()||null;return null}function Vf(Z){if(!/^[A-Za-z0-9._/-]+$/.test(Z))throw Error(`refused to shell-escape suspect token: ${Z}`);return Z}async function qf(Z,X="--version"){if(!await H9(Z))return null;let Y=await D0([Z,X],{timeoutMs:5000});if(Y.exitCode!==0)return null;return((Y.stdout||Y.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var RO=16777216,eK;var k9=p(()=>{eK=class eK 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 n7(Z){return Gf?"":Z}var Gf,M0,k8,l0,gW0,a0,H8,X9,g;var S6=p(()=>{Gf=(process.env.NO_COLOR??"").length>0;M0=n7("\x1B[0;31m"),k8=n7("\x1B[0;32m"),l0=n7("\x1B[1;33m"),gW0=n7("\x1B[0;34m"),a0=n7("\x1B[0;36m"),H8=n7("\x1B[1m"),X9=n7("\x1B[2m"),g=n7("\x1B[0m")});import{existsSync as wf}from"fs";async function F7(){if(R4!==void 0)return R4;let Z="/opt/homebrew/bin/python3.12";if(wf(Z))return R4=Z,Z;let X=await H9("python3.12");if(X)return R4=X,X;let Q=await H9("python3");return R4=Q,Q}async function D7(Z,X={}){let Q=await F7();if(!Q)return{stdout:"",stderr:"python3 not found",exitCode:127};return D0([Q,"-c",Z],X)}var R4;var o7=p(()=>{k9()});var oO={};c0(oO,{runStatus:()=>of});import{existsSync as Q9,readFileSync as h3,readdirSync as pO,statSync as dO}from"fs";import{resolve as h8,basename as mf}from"path";import{homedir as uf}from"os";function cO(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 lO(Z,X,Q){if(X===0)return null;let Y=Math.trunc(Z*100/X),J=Math.trunc(Z*BQ/X);if(J>BQ)J=BQ;let z=BQ-J,K=k8;if(Y>=80)K=M0;else if(Y>=50)K=l0;let $="=".repeat(Math.max(0,J))+" ".repeat(Math.max(0,z)),W=cO(Z),V=cO(X);return`  ${H8}${Q}${g} ${K}[${$}]${g} ${Y}% (${W} / ${V})`}async function df(){if(await H9("jq"))return!0;return process.stdout.write(`${M0}Error: jq is required but not installed.${g}
+var k_=Object.create;var{getPrototypeOf:x_,defineProperty:oK,getOwnPropertyNames:S_}=Object;var y_=Object.prototype.hasOwnProperty;function b_(Z){return this[Z]}var __,f_,h_=(Z,X,Q)=>{var Y=Z!=null&&typeof Z==="object";if(Y){var J=X?__??=new WeakMap:f_??=new WeakMap,z=J.get(Z);if(z)return z}Q=Z!=null?k_(x_(Z)):{};let K=X||!Z||!Z.__esModule?oK(Q,"default",{value:Z,enumerable:!0}):Q;for(let $ of S_(Z))if(!y_.call(K,$))oK(K,$,{get:b_.bind(Z,$),enumerable:!0});if(Y)J.set(Z,K);return K};var VQ=(Z,X)=>()=>(X||Z((X={exports:{}}).exports,X),X.exports);var v_=(Z)=>Z;function g_(Z,X){this[Z]=v_.bind(null,X)}var c0=(Z,X)=>{for(var Q in X)oK(Z,Q,{get:X[Q],enumerable:!0,configurable:!0,set:g_.bind(X,Q)})};var p=(Z,X)=>()=>(Z&&(X=Z(Z=0)),X);var t0=import.meta.require;var EO={};c0(EO,{lokiDir:()=>j0,homeLokiDir:()=>I4,findRepoRootForVersion:()=>tK,REPO_ROOT:()=>Q8});import{resolve as s7,dirname as rK}from"path";import{fileURLToPath as m_}from"url";import{existsSync as qQ}from"fs";import{homedir as u_}from"os";function p_(){let Z=DO;for(let X=0;X<6;X++){if(qQ(s7(Z,"VERSION"))&&qQ(s7(Z,"autonomy/run.sh")))return Z;let Q=rK(Z);if(Q===Z)break;Z=Q}return s7(DO,"..","..","..")}function tK(Z){let X=Z;for(let Q=0;Q<6;Q++){if(qQ(s7(X,"VERSION"))&&qQ(s7(X,"autonomy/run.sh")))return X;let Y=rK(X);if(Y===X)break;X=Y}return s7(Z,"..","..","..")}function j0(){return process.env.LOKI_DIR??s7(process.cwd(),".loki")}function I4(){return s7(u_(),".loki")}var DO,Q8;var G8=p(()=>{DO=rK(m_(import.meta.url));Q8=p_()});import{readFileSync as d_}from"fs";import{resolve as c_,dirname as l_}from"path";import{fileURLToPath as i_}from"url";function _3(){if(f5!==null)return f5;let Z="8.0.2";if(typeof Z==="string"&&Z.length>0)return f5=Z,f5;try{let X=l_(i_(import.meta.url)),Q=tK(X);f5=d_(c_(Q,"VERSION"),"utf-8").trim()}catch{f5="unknown"}return f5}var f5=null;var GQ=p(()=>{G8()});var kO={};c0(kO,{runOrThrow:()=>Wf,run:()=>D0,readStreamCapped:()=>HQ,commandVersion:()=>qf,commandExists:()=>H9,ShellError:()=>eK,MAX_STDOUT_BYTES:()=>RO});async function HQ(Z,X=RO){let Q=Z.getReader(),Y=new TextDecoder,J="",z=0;try{while(z<X){let{done:K,value:$}=await Q.read();if(K)break;if(!$)continue;if(z+=$.byteLength,z>X){let W=$.byteLength-(z-X);J+=Y.decode($.subarray(0,W),{stream:!0});break}J+=Y.decode($,{stream:!0})}J+=Y.decode()}finally{try{await Q.cancel()}catch{}Q.releaseLock()}return J}async function D0(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([HQ(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 Wf(Z,X={}){let Q=await D0(Z,X);if(Q.exitCode!==0)throw new eK(`command failed (${Q.exitCode}): ${Z.join(" ")}`,Q.exitCode,Q.stdout,Q.stderr);return Q}async function H9(Z){let X=Vf(Z),Q=await D0(["sh","-c",`command -v ${X}`],{timeoutMs:5000});if(Q.exitCode===0)return Q.stdout.trim()||null;return null}function Vf(Z){if(!/^[A-Za-z0-9._/-]+$/.test(Z))throw Error(`refused to shell-escape suspect token: ${Z}`);return Z}async function qf(Z,X="--version"){if(!await H9(Z))return null;let Y=await D0([Z,X],{timeoutMs:5000});if(Y.exitCode!==0)return null;return((Y.stdout||Y.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var RO=16777216,eK;var k9=p(()=>{eK=class eK 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 n7(Z){return Gf?"":Z}var Gf,M0,k8,l0,gW0,a0,H8,X9,g;var S6=p(()=>{Gf=(process.env.NO_COLOR??"").length>0;M0=n7("\x1B[0;31m"),k8=n7("\x1B[0;32m"),l0=n7("\x1B[1;33m"),gW0=n7("\x1B[0;34m"),a0=n7("\x1B[0;36m"),H8=n7("\x1B[1m"),X9=n7("\x1B[2m"),g=n7("\x1B[0m")});import{existsSync as wf}from"fs";async function F7(){if(R4!==void 0)return R4;let Z="/opt/homebrew/bin/python3.12";if(wf(Z))return R4=Z,Z;let X=await H9("python3.12");if(X)return R4=X,X;let Q=await H9("python3");return R4=Q,Q}async function D7(Z,X={}){let Q=await F7();if(!Q)return{stdout:"",stderr:"python3 not found",exitCode:127};return D0([Q,"-c",Z],X)}var R4;var o7=p(()=>{k9()});var oO={};c0(oO,{runStatus:()=>of});import{existsSync as Q9,readFileSync as h3,readdirSync as pO,statSync as dO}from"fs";import{resolve as h8,basename as mf}from"path";import{homedir as uf}from"os";function cO(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 lO(Z,X,Q){if(X===0)return null;let Y=Math.trunc(Z*100/X),J=Math.trunc(Z*BQ/X);if(J>BQ)J=BQ;let z=BQ-J,K=k8;if(Y>=80)K=M0;else if(Y>=50)K=l0;let $="=".repeat(Math.max(0,J))+" ".repeat(Math.max(0,z)),W=cO(Z),V=cO(X);return`  ${H8}${Q}${g} ${K}[${$}]${g} ${Y}% (${W} / ${V})`}async function df(){if(await H9("jq"))return!0;return process.stdout.write(`${M0}Error: jq is required but not installed.${g}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -1203,4 +1203,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}case"start":{let{runStart:Y}=await Promise.resolve().then(() => (I_(),E_));return Y(Q)}default:return process.stderr.write(`Unknown command: ${X}
 `),process.stderr.write(P_),2}}mO();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var TW0=await MW0(Bun.argv.slice(2));process.exit(TW0);
 
-//# debugId=95E883C64E57C32964756E2164756E21
+//# debugId=0B4A1F7E210B77BE64756E2164756E21

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '8.0.0'
+__version__ = '8.0.2'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "description": "Loki Mode by Autonomi. Autonomous spec-to-product system: takes a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief to a deployed app via the RARV-C closure loop with 8 quality gates. Provider-agnostic (Claude Code, OpenAI Codex, Cline, Aider).",
   "keywords": [
     "agent",

package/plugins/loki-mode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "loki-mode",
   "displayName": "Loki Mode",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "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/skills/providers.md

@@ -31,6 +31,48 @@ export LOKI_PROVIDER=claude  # or codex, cline, aider
 loki start --provider cline ./prd.md
 ```
 
+## Any Model, Any Provider (ANTHROPIC_BASE_URL)
+
+Independent of the four CLI providers below. Loki speaks the Anthropic Messages
+API, so ANY endpoint that implements it works: OpenRouter, Ollama, LiteLLM,
+vLLM, or a self-hosted gateway. Nothing needs installing.
+
+```bash
+export ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1   # or http://localhost:11434/v1
+export ANTHROPIC_API_KEY=...                             # omit for a keyless local Ollama
+export LOKI_MODEL_OVERRIDE=<exact model id from your provider>
+loki start prd.md
+```
+
+**BOTH variables are required.** The override at `providers/claude.sh:520` fires
+only when `ANTHROPIC_BASE_URL` AND `LOKI_MODEL_OVERRIDE` are both set. With only
+the base URL, Loki keeps resolving the tier aliases `opus` / `sonnet` / `haiku`,
+which only Anthropic serves -- most providers reject them and the run dies at the
+first model call. (A proxy that maps the aliases, such as LiteLLM, is the
+exception.) `loki doctor` warns on exactly this condition.
+
+Implementation, byte-mirrored across both routes -- edit BOTH or the parity
+fixtures diverge:
+
+| Route | Site |
+|---|---|
+| bash | `providers/claude.sh:520`, `autonomy/run.sh:693` |
+| Bun  | `loki-ts/src/runner/providers.ts:328` |
+| doctor | `loki-ts/src/commands/doctor.ts:652` |
+
+`ANTHROPIC_BASE_URL` is passed through unchanged; Loki never rewrites it.
+
+**No model IDs are listed here deliberately.** Alt-provider catalogues change
+weekly, and a stale ID in documentation becomes a runtime failure for the user.
+Read the exact string from the provider (`ollama list`, OpenRouter's model page,
+your gateway's config). For the same reason `LOKI_MODEL_OVERRIDE` is NOT
+validated against an allowlist -- any string the provider accepts is passed
+straight through.
+
+Quality gates, the completion council, and the Evidence Receipt are all
+model-agnostic: they assert on the artifact that was built, not on which model
+built it. A cheaper or local model gets the same verification as Opus.
+
 ## Claude Code (Default, Full Features)
 
 **Best for:** All use cases. Full autonomous capability.