loki-mode 11.3.8 → 11.4.2

package/docs/environment-variables.md

@@ -23,7 +23,7 @@ with nowhere to look them up.
 |---|---|---|
 | `LOKI_PRD_FILE` | none | Path to a spec file, as an alternative to the positional argument. |
 | `LOKI_MAX_ITERATIONS` | `1000` | Hard cap on iterations. Reaching it is a deterministic terminal failure, not a success. Also in `config schema`. |
-| `LOKI_BUDGET_LIMIT` | `100.00` | Spend cap in USD. Breaching it **pauses** the run (writes `.loki/PAUSE` and saves state); it never kills work or discards a deliverable. Remove `.loki/PAUSE` to resume, or raise the cap. Set to `""` for no cap. A warning is logged at 80%. |
+| `LOKI_BUDGET_LIMIT` | `100.00` | Spend cap in USD on the previous loop (the Loki 10 engine uses `--max-cost`, `budgets.per_run` or a default of $100 only when `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is set; none on a subscription). Also enforced by kill on codex, cline, aider and opencode in the Loki 10 engine. Breaching it **pauses** the run (writes `.loki/PAUSE` and saves state); it never kills work or discards a deliverable. Remove `.loki/PAUSE` to resume, or raise the cap. Set to `""` for no cap. A warning is logged at 80%. |
 | `LOKI_MAX_DURATION` | unset (no cap) | Wall-clock cap in seconds. Stops cleanly at the next iteration boundary with a `max_duration_reached` terminal status. `loki start --max-duration` also accepts `90m` / `2h`. |
 | `LOKI_AUTO_CONFIRM` | unset | `true`/`false` to control prompts. Takes precedence over `CI`. |
 | `LOKI_CONFIG_DUMP` | `0` | `1` prints the resolved configuration and exits **without starting a run or spending anything**. |
@@ -40,7 +40,14 @@ interact and why hitting one is a failure rather than a success.
 | `LOKI_PROVIDER` | `claude` | `claude`, `cline`, `codex`, `aider`, or `opencode`. |
 | `LOKI_SESSION_MODEL` | `medium` | The capability tier for the run: `small`, `medium`, or `high`. See below. |
 | `LOKI_MAX_TIER` | unlimited | Caps model tier, so a run cannot escalate past what you are willing to pay for. |
-| `LOKI_MODEL_OVERRIDE` | unset | Overrides the resolved model outright. |
+| `LOKI_MODEL_OVERRIDE` | unset | Overrides the resolved model outright. A route spec (`ollama/<id>`) works too. |
+| `LOKI_MODEL_ROUTE` | unset | `<kind>/<id>` with kind `openrouter`, `ollama`, `lmstudio`, `llamacpp`, `vllm` or `custom`. Routes the Claude harness to that endpoint; `loki models` lists them, `loki models --local` discovers local runtimes. |
+| `LOKI_MODEL_BASE_URL` | unset | Base URL for a `custom/<id>` route (required for `custom`). |
+| `LOKI_MODEL_API_KEY` | unset | Token for a `custom/<id>` route (optional). OpenRouter reads `OPENROUTER_API_KEY`. |
+| `LOKI_OPENCODE_MODEL` | unset | `provider/model` id passed to opencode (for example `openrouter/deepseek/deepseek-v3.2`). Also `LOKI_OPENCODE_FLAGS` and `LOKI_OPENCODE_CLI`. |
+| `LOKI_EDIT_MODEL` | unset | Model for `loki edit`. |
+| `LOKI_ENGINE` | unset | `legacy` forces the previous loop; the `--engine` flag wins over it. |
+| `LOKI_SUMMARY_JSON` | unset | `1` prints the end-of-run summary as one JSON line on the previous loop. |
 | `LOKI_TIER` | `oss` | **Not a model setting.** The open-core licensing seam. Leave it unset. |
 | `LOKI_ALLOW_CLAUDE_SIDECALLS` | unset | `1` (exactly) lets PRD enrichment, done recognition, the council voters, the USAGE.md refresh and the quickstart intent check prompt the `claude` CLI under a non-claude provider; `loki doctor --airgap` then reports that as required egress to Anthropic. |
 

package/docs/exit-codes.md

@@ -22,7 +22,10 @@ is the part most likely to surprise a script author.
 | 0 | The run completed |
 | nonzero | Something went wrong |
 
-There is no finer signal. A gate that needs to tell "failed the quality gate"
+Usage errors are distinct from run outcomes: `loki start` with an unknown
+option exits 64, and `loki quick` with no task description exits 64 (they were
+1 and 2). A missing provider CLI still exits 2 before any spend. There is no
+finer run-outcome signal. A gate that needs to tell "failed the quality gate"
 from "crashed" must opt into the durable contract below.
 
 ### With `LOKI_DURABLE_STATE=1` (the platform contract)
@@ -56,6 +59,7 @@ identically; a parity test asserts they agree status for status.
 |---|---|
 | 0 | The run completed and its diff did not weaken the tests |
 | 3 | The diff weakened the tests (a skip marker added in a test file, a test runner config changed, or an existing test file deleted or renamed). The receipt headline is NOT VERIFIED and names what was weakened, for example `NOT VERIFIED (tests weakened: skip added in sum.test.js)` |
+| 64 | Usage error: no task description |
 | other nonzero | The run itself failed; this code is passed through unchanged |
 
 `loki quick` has no `--json` flag; its structured result is `loki why --json`, schema: `schemas/why-result.schema.json` (`state.lastExitCode` carries the ladder above).
@@ -72,8 +76,9 @@ headline caused by unproven gates alone also keeps exit 0. The signal is the
 |---|---|
 | 0 | VERIFIED |
 | 1 | CONCERNS (findings below the block threshold, or inconclusive evidence) |
-| 2 | BLOCKED (findings at or above the block threshold) |
-| 3 | Verifier error: it could not complete, and never silently passes |
+| 2 | BLOCKED (findings at or above the block threshold), or not a git directory |
+| 3 | Verifier error: it could not complete, and never silently passes (also an empty diff) |
+| 64 | Usage error: unknown option or unexpected argument |
 
 `loki verify` has no `--json` flag. `loki status --json` schema: `schemas/status-result.schema.json`.
 
@@ -142,19 +147,21 @@ An early draft spec listed `1=BLOCKED, 2=CONCERNS`. That ordering was rejected:
 it is not used anywhere, it has no consumers, and it inverts the
 severity-rises-with-the-code rule that every other command follows.
 
-### Known gaps
+### Contract enforced from v11.4.0
 
-The table above is the target. On the current release, three inputs do not
-return what it implies. Measured on this checkout:
+This is a deliberate contract change for the 11.4.0 minor release. Three inputs
+that used to return a misleading code now return the table's value:
 
-| Input | Command | Exit today | Target |
+| Input | Command | Exit | Note |
 |---|---|---|---|
-| Empty diff (a git repo with no changes vs base) | `loki verify` | 1 (CONCERNS) | 3 |
-| Not a git directory | `loki verify` | 1 (CONCERNS) | 2 |
-| Unknown flag | `loki verify --no-such-flag` | 3 | 64 |
+| Empty diff (a repo with no changes vs base) | `loki verify` | 3 | Nothing to check is a verifier error, never a pass. VERDICT line still reads CONCERNS. |
+| Not a git directory | `loki verify` | 2 | Could not check. VERDICT line still reads CONCERNS. |
+| Unknown option or unexpected argument | `loki verify --no-such-flag` | 64 | Usage error, as in `proof verify`. |
 
-The gap is tracked as the pending moat case P2.verify-exit-contract in
-`tests/moat/pending.txt`.
+A real finding keeps precedence: an empty diff that also carries a below-threshold
+finding (for example spec drift) still exits 1, and a blocking finding still exits 2.
+CI gates that tested `[ $rc -eq 1 ]` for these inputs must move to `[ $rc -ne 0 ]`.
+The moat case `P2.verify-exit-contract` is no longer pending and is enforced.
 
 ### `loki verify --fast`
 
@@ -346,3 +353,13 @@ esac
 Do not read an exit code through a pipe. `$?` after a pipeline reports the last
 stage, so `loki verify | tee log` gives you `tee`'s status and always looks
 successful. Use `${PIPESTATUS[0]}` in bash, or capture first and test after.
+
+## `loki edit`
+
+One provider pass, no loop.
+
+| Code | Meaning |
+|---|---|
+| 0 | Edit done (or nothing to change, or `--dry-run` plan printed) |
+| 1 | Provider pass failed, or `--verify` failed (nothing is committed) |
+| 2 | Usage or setup error (no change text, not a git repo, claude or python3 missing, unsupported provider) |

package/docs/v10/CLI-MODERN.md

@@ -6,12 +6,12 @@ Classes: KEEP-MODERN (v10-native or engine-neutral), UPDATE (live but needs mode
 
 ## Counts
 
-- KEEP-MODERN: 64
+- KEEP-MODERN: 69
 - UPDATE: 22
-- DROP-LEGACY: 31
+- DROP-LEGACY: 32
 - DELETE: 14
-- Total rows: 131
-- Registry paths (commands and nested subcommands): 181
+- Total rows: 137
+- Registry paths (commands and nested subcommands): 188
 
 ## Commands
 
@@ -45,6 +45,11 @@ Classes: KEEP-MODERN (v10-native or engine-neutral), UPDATE (live but needs mode
 | completion (hidden) | loki-ts/src/cli.ts | KEEP-MODERN | Hidden plumbing; completions install themselves |
 | __complete (hidden) | loki-ts/src/cli.ts | KEEP-MODERN | Hidden plumbing for generated completions |
 | help | autonomy/loki | KEEP-MODERN | Core |
+| chat | autonomy/loki | KEEP-MODERN | Provider-neutral conversational verb |
+| edit | autonomy/loki | KEEP-MODERN | Provider-neutral single-edit verb |
+| diff | autonomy/loki | KEEP-MODERN | Passes extra args to git diff |
+| models | autonomy/loki | KEEP-MODERN | Provider-neutral model tiers |
+| setup | autonomy/loki | KEEP-MODERN | Onboarding gate |
 | quick | autonomy/loki | UPDATE | Routes to the v10 lean path by default |
 | quickstart | autonomy/loki | KEEP-MODERN | Onboarding path |
 | init | autonomy/loki | UPDATE | Templates predate v10 |
@@ -129,6 +134,7 @@ Classes: KEEP-MODERN (v10-native or engine-neutral), UPDATE (live but needs mode
 | cleanup | autonomy/loki | DROP-LEGACY | Legacy run.sh orphans |
 | state | autonomy/loki | DROP-LEGACY | Legacy engine |
 | agent | autonomy/loki | DROP-LEGACY | Legacy engine |
+| agents | autonomy/loki | DROP-LEGACY | Legacy engine |
 | trigger | autonomy/loki | DROP-LEGACY | Legacy engine |
 | failover | autonomy/loki | DROP-LEGACY | Legacy engine |
 | reset | autonomy/loki | DROP-LEGACY | Legacy engine |

package/docs/v10/FAILURE-CLASSES.md

@@ -771,13 +771,13 @@ L0 review rule (ENGINE-LAWS.md L0): a fix that adds an `if` or a regex about the
 
 ## FC-90 Deleting the token env vars left the user's gh login and git credential helpers reachable (GH-KEYRING)
 - User saw: nothing yet (found by audit). With GH_TOKEN, GITHUB_TOKEN, GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN and SSH_AUTH_SOCK removed, `gh auth token` exited 0 and `gh api user` returned the user's login on the founder machine, and git held `osxkeychain` plus `!gh auth git-credential` helpers over an HTTPS origin.
-- Law: P9 (agent and test code never holds the user's credential) is a property of every credential store a child can reach, not of the env vars alone; one shared mechanism builds the withheld env, so no env builder can delete a subset and call it token-free.
+- Law: a child spawned by the harness must not reach the user's GitHub credential by default or by accident, through any store the child's env can resolve (env vars, gh config and keyring, git credential helpers), not through the env vars alone; one shared mechanism builds the withheld env, so no env builder can delete a subset and call it token-free. This is not a sandbox.
 - Cause (measured): tokenFreeEnv (util/safe_git.ts) and plainTestEnv (util/check_result.ts) only deleted the vars. gh then falls back to GH_CONFIG_DIR/hosts.yml and the OS keyring, and git calls its configured helpers on an HTTPS push. withholdGithubTokens already closed this for the worker, but only for the worker env. Measured with gh: GH_CONFIG_DIR alone leaves `gh auth token` exit 0 (keyring); a sentinel token alone makes `gh auth status` fail but a named-account read (`gh auth token --user`) still reads hosts.yml; both together close it.
 - Mechanism: util/credential_env.ts hardenCredentialEnv is the one function: the 4 vars become a non-working sentinel, GH_CONFIG_DIR is a per-process empty mode-700 directory, credential.helper is reset through GIT_CONFIG_COUNT/KEY/VALUE appended after existing entries (the user's gitconfig is never edited and identity survives), GIT_TERMINAL_PROMPT=0 and GCM_INTERACTIVE=never. tokenFreeEnv (so plainTestEnv, safeGitEnv) and withholdGithubTokens both call it; the LOKI_ALLOW_AGENT_GITHUB_TOKEN opt-out stays in withholdGithubTokens only, test envs are always hardened. The empty dir is made once per process (not per call), under LOKI_RUN_TMP when it is a real directory, else the OS temp dir, and removed by exact path at exit (the old per-call scoped dirs leaked).
 - Siblings swept: withholdGithubTokens (now shared), tokenFreeEnv callers (attempts, wall_snapshot, verify_pr, start), plainTestEnv callers (wall, verify, load_owner), the worker assertion (sentinel prefix now exported from credential_env.ts), and the bash route (_loki_withhold_github_tokens at autonomy/run.sh main() already sets the sentinel, a scoped GH_CONFIG_DIR, the helper reset and an EXIT trap removal). Raw `process.env` spawns elsewhere inherit an already-withheld process env (runner after autonomous.ts withholdGithubTokens, worker after supervisor.ts) and are policed by full_env_spawn_guard.
 - Fixture: tests/util/fc90_credential_env.test.ts (a fake HOME with a planted gh hosts.yml and a planted global git credential helper, each with a positive control on the raw env; red on the old tokenFreeEnv, red when the GH_CONFIG_DIR line, the credential.helper reset or the sentinel is removed; plus a count of loki-gh-config-* dirs in an isolated TMPDIR before and after).
 - CI note (fix-forward, cc8e17512 red on ubuntu): the named-account control `gh auth token --user` returned empty on gh for Linux because a flat hosts.yml is not read by a named lookup there (the multi-account `users:` shape is), while the default `gh auth token` reads only the flat one on the same gh. The fixture now probes the installed gh with each shape in a scratch home, plants the one that works in a separate named home, and skips the named-account test (control and hardened assertion together) when no shape works. Verified on ubuntu:24.04 with gh 2.102.0.
-- Residual: SSH keys under ~/.ssh and GIT_SSH_COMMAND are closed only for the worker env (withholdGithubTokens), not for plainTestEnv; a test command can still `ssh` with the user's default keys.
+- Residual: code running as the same user can unset the variables and call gh or git directly (or read the keyring itself); this closes default and accidental reach, it is not a sandbox. A parent GIT_CONFIG_PARAMETERS helper is neutralised by appending the reset last. SSH keys under ~/.ssh and GIT_SSH_COMMAND are closed only for the worker env (withholdGithubTokens), not for plainTestEnv; a test command can still `ssh` with the user's default keys.
 
 ## FC-88 The release gate repeated the Tests workflow's typecheck and bun suite on the same tree (WF-GATE-DEDUP)
 - User saw: every release waited 6m40s in release.yml's gate step "Bun typecheck + test (protect published loki-ts dist)" (run 37859034694, v11.3.4) for work the Tests workflow had already finished green on the same tree, or on the bump-only parent (FC-70).

package/docs/v10/GUIDE.md

@@ -1,6 +1,6 @@
 # Loki 10 engine guide
 
-Default: Loki 10 engine for `loki "<task>"`, `loki owner/repo#N` and `loki quick "<task>"`. `loki legacy` and LOKI_ENGINE were removed in 11.0.0. <!-- loki10-default -->
+Default: Loki 10 engine for `loki start`, `loki "<task>"`, `loki owner/repo#N` and `loki quick "<task>"`. `loki legacy` was removed in 11.0.0; the previous loop runs only on an explicit `--engine legacy` or `LOKI_ENGINE=legacy` (see Routing). <!-- loki10-default -->
 
 Loki 10 is the rewritten engine (docs/v10/ENGINE.md). Since the D48 flip it
 runs `loki "<task>"`, `loki owner/repo#N` (issue mode) and `loki quick
@@ -12,29 +12,77 @@ newest entry in .loki/runs/ is a v10 run newer than the newest legacy proof
 it runs the v10 verify, otherwise the legacy verify. If bun is missing or
 LOKI_PROVIDER is unsupported, the default mode falls back to the bash path
 and prints one stderr line saying why. In 11.0.0 (LEGACY-ZERO W1-01) `loki
-legacy` was removed (it exits 2 with a removal message) and LOKI_ENGINE is no
-longer read; any value is ignored.
+legacy` was removed (it exits 2 with a removal message). From 11.4.0
+`--engine legacy|engine10` and LOKI_ENGINE select the engine explicitly (see
+Routing below).
 
-`loki start owner/repo#N`, `loki start <issue URL>` and `loki start "<multi-word
-task>"` run Loki 10, the same as `loki owner/repo#N` and `loki "<task>"`. A PRD
-file, a flag-first call (`loki start --simple prd.md`) and a one-word start still
-run on the previous bash loop (autonomy/run.sh), and so does the opencode
-provider, until FC38-SWEEP ports them. `loki legacy` and LOKI_ENGINE remain
-removed. The previous loop is being removed (see docs/v10/LEGACY-REMOVAL.md).
+## Routing
+
+Argument order and input form never change the engine. Flags are normalized
+before the routing decision, so these all run on Loki 10:
+
+```
+loki start prd.md              loki start --no-pr prd.md
+loki start owner/repo#123      loki start --provider codex owner/repo#123
+loki start "fix the login bug" loki start --no-pr "fix the login bug"
+loki start fixit               loki quick -v "fix the login bug"
+```
+
+A PRD file, an issue ref or URL, a multi-word task and a one-word brief take
+the same path. `-v` means `--verbose`, `--budget` and `--budget-limit` mean
+`--max-cost`, and `--yes`, `-y`, `--no-plan`, `--no-mirofish` and
+`--no-dashboard` are accepted and ignored. A PRD file path that does not exist
+exits 2 with "PRD file not found".
+
+The previous loop (autonomy/run.sh) runs only when:
+
+1. you pass `--engine legacy` or set `LOKI_ENGINE=legacy` (`--engine engine10`
+   forces Loki 10 and refuses a flag it cannot honor; the flag wins over the
+   variable), or
+2. the call carries a flag Loki 10 does not support (for example `--simple`,
+   `--complex`, `--parallel`, `--github`, `--sandbox`, `--max-iterations`).
+   Only that call goes to the previous loop, and one stderr line names the flag
+   and the engine chosen, or
+3. LOKI_PROVIDER (or `--provider`) names a provider Loki 10 has no invoker
+   for (anything but claude, codex, cline, aider, opencode), or bun is missing, or the
+   PRD is larger than 100000 bytes. One stderr line says why.
+
+`loki <word>` with a single bare word stays the command namespace (`loki doctor`),
+so use `loki start <word>` for a one-word brief. A first argument starting with
+`-` followed by a multi-word task or an issue ref (`loki --no-pr "fix it now"`)
+runs on Loki 10 like the positional form.
+
+### See the route without running
+
+```
+loki route start prd.md
+loki route quick "fix the login redirect loop" --json
+loki start --simple prd.md --explain-route
+```
+
+`loki route [start|quick] <same args>` and `--explain-route` on start or quick
+print the engine, provider, model, input type and the reason, then exit 0
+without running anything. `--json` prints one JSON object with the keys
+`engine`, `provider`, `model`, `input_type`, `input`, `reason`.
 
 Some pieces named in this guide are still being built. Each one below says
 so plainly instead of describing a finished feature.
 
 ## Quickstart
 
-Put the task first, as a quoted multi-word string, so bin/loki's router
-sends it to the v10 engine. A one-word argument that is not an issue ref,
-or any first argument starting with `-`, stays on the legacy engine.
+`loki start` is the primary path. Give it a PRD file, an issue ref, a task in
+quotes or a one-word brief. Flags may come before or after it; the engine is
+the same (see Routing).
 
 ```
-loki "fix the login redirect loop" --no-pr
+loki start prd.md
+loki start "fix the login redirect loop" --no-pr
 ```
 
+`loki "<task>"` and `loki owner/repo#N` are shorthand for the same run.
+`loki chat` is an interactive alternative that can start and join these runs
+(see Chat below).
+
 `loki quick "<task>"` is the small-task entry. It runs the same engine
 without opening a pull request (the legacy quick never opened one), and the
 engine's own sizing picks the lean path for a small task: Plan and Wall are
@@ -42,16 +90,16 @@ skipped and implement runs on your run's own model, like a raw session.
 `LOKI_E10_CASCADE=1` opts in to the cheaper sonnet start (it prints and
 records the downgrade); a repeated test failure always escalates up, never
 down (Engine Law L1).
-`loki quick --help` and a flag-first `loki quick -v "<task>"` stay on the
-legacy quick.
+`loki quick --help` prints the help; `loki quick -v "<task>"` runs on Loki 10 with
+`--verbose`.
 
 ```
 loki quick "fix the login redirect loop"
 ```
 
 If bun is not installed, or LOKI_PROVIDER names a provider the v10 engine
-has no invoker for (anything but claude, codex, cline, aider), these entry
-points fall back to the legacy engine instead of failing.
+has no invoker for (anything but claude, codex, cline, aider, opencode), these entry
+points fall back to the legacy engine with a one-line notice instead of failing.
 
 Issue refs work the same way:
 
@@ -74,14 +122,19 @@ Flags, from the engine's own `--help`:
   from 480s to 1800s (`loki-ts/src/engine10/types.ts`).
 - `--provider <name>`: pick the coding provider for this run. See the
   provider table below.
-- `--max-cost <usd>`: per-run cost cap in dollars. Without the flag the cap is
-  `budgets.per_run` in the repo's `loki.yaml` (for example
-  `budgets:` then `  per_run: 5`), else the default of $20.00. The flag wins over
-  the file. The start line shows the cap in force, for example
-  `... previous engine), cap $20.00 (default)`. Once priced cost reaches the cap
-  the running stage is stopped, no later stage starts, and the run ends
-  BUDGET_STOP with exit code 3. Sessions with no provider price never count
-  toward the cap.
+- `--max-cost <usd>`: per-run cost cap in dollars (`--budget` and
+  `--budget-limit` are aliases). Order of precedence: the flag, then
+  `budgets.per_run` in the repo's `loki.yaml` (for example `budgets:` then
+  `  per_run: 5`), then the default. The default is $100.00 when
+  `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is set, and no dollar cap on a
+  subscription login (usage then counts against your plan limits). Source:
+  `loki-ts/src/e10ext/budget_cap.ts`. The start line shows the cap in force,
+  for example `cap $100.00 (default)` or `no dollar cap (subscription)`. Once
+  priced cost reaches the cap the running stage is stopped, no later stage
+  starts, and the run ends BUDGET_STOP with exit code 3. Sessions with no
+  provider price never count toward the cap. On the previous loop the same cap
+  is `LOKI_BUDGET_LIMIT` (default 100.00 USD; set it to an empty string for
+  unlimited), and a breach pauses the run instead of killing it.
 
 `--no-pr`, `--deep` and `--provider` are parsed by the supervisor
 (`loki-ts/src/engine10/supervisor.ts`) and take effect on a real run.
@@ -99,9 +152,117 @@ verify, seal) and then, in the supervisor, the pr stage, ending in the
 Slack is not part of the v10 engine surface (no command, no notification
 hook) and is in progress, tracked with the other wave 3 items.
 
+## Small changes: loki edit
+
+`loki edit` is the lightest path: one Claude pass on the current repo with no
+PRD, plan, council, PR, receipt or branch switch. It prints the diff stat, the
+diff, and one line with cost and elapsed time.
+
+```
+loki edit "rename fooBar to foo_bar"
+loki edit src/foo.ts "rename X to Y"
+loki edit --verify --commit src/a.ts "add null checks"
+loki edit --dry-run "describe the change"
+```
+
+- `--verify` runs the fast verifier on the result.
+- `--receipt` writes an unsigned receipt to `.loki/edit-receipts/`.
+- `--commit` commits only the files the pass touched, by name; skipped when
+  verify failed.
+- `--dry-run` plans only (plan permission mode); nothing changes.
+- `LOKI_EDIT_MODEL` overrides the model. Claude provider only for now.
+
+Use `loki edit` for a single pass, `loki quick "<task>"` for a small task with
+a verify loop, and `loki start` for anything that needs a plan, verification
+and a sealed receipt. Exit codes: 0 done, 1 provider or verify failure, 2
+usage or setup error ([exit-codes.md](../exit-codes.md)).
+
+## Custom agents
+
+Define child agents as markdown with YAML frontmatter in `.loki/agents/<name>.md`
+(project) or `~/.config/loki/agents/<name>.md` (user). A project agent wins
+over a user agent of the same name. The body is the system prompt.
+
+Frontmatter keys: `name` (must equal the file name without `.md`),
+`description` (required), `model`, `provider` (`claude` by default; `codex`,
+`cline`, `aider` or `opencode`), `tools` (allow list), `deny` (deny list) and
+`permission` (`plan` default, `edit` or `full`).
+
+```
+loki agents list
+loki agents new reviewer          # reviewer, planner and tester copy shipped examples
+loki agents show reviewer
+loki agents export --claude       # writes .claude/agents/ (add --user for ~/.claude/agents)
+```
+
+`permission: plan` exports as Claude Code `disallowedTools` Edit, Write,
+NotebookEdit and Bash. Council reviewers pick up a matching agent: one named
+`reviewer`, `tester` or `security` replaces the council-v2 reviewer prompt and
+model for the matching roles (`code_quality_reviewer` and
+`requirements_verifier` use `reviewer`; `test_auditor` uses `tester`;
+`devils_advocate` uses `security`, then `reviewer`). With no agents configured
+nothing changes. `loki agent` (singular) is the unchanged built-in agent-type
+command.
+
+## Chat (interactive alternative)
+
+`loki start` stays the primary path. `loki chat` is an interactive session for
+exploring and small steps, and it hands off to and from `loki start`.
+
+- Start with `loki chat` (needs a TTY; for one-shot tasks use `loki quick`).
+  Bare `loki` does not open chat.
+- The session starts in Plan mode (read-only); `/plan` and `/build` switch
+  modes and the prompt shows `loki[plan]>` or `loki[build]>`. Plan mode is
+  enforced for Claude (`--permission-mode plan`); other providers get a
+  prompt-level read-only instruction.
+- Slash commands: `/plan`, `/build`, `/run <prd|brief>`, `/quick <task>`,
+  `/edit <change>`, `/verify`, `/receipt`, `/cost`, `/diff`, `/undo`,
+  `/model <id>`, `/provider <name>`, `/help`, `/exit`.
+- `/run` starts a normal `loki start` run with the chat's model and provider.
+- `loki chat --attach` joins a running or the last `loki start` session, with
+  `/status`, `/steer`, `/diff`, `/verify`, `/receipt` and `/stop`.
+- `loki chat --tui` launches the full Claude Code TUI with the Loki system
+  prompt appended.
+
+## Setup, doctor and config
+
+```
+loki setup            # wizard: tools, Claude login, provider, model route, spend cap
+loki setup --yes      # non-interactive defaults
+loki setup --check    # report only
+loki doctor --fix     # create state dirs and a default config; prints exact commands for the rest
+loki config list      # also: get <key>, set <key> <value>, path
+```
+
+`loki setup` flags: `--provider claude|codex|cline|aider|opencode`,
+`--model`, `--budget USD` and `--global`. `loki doctor --fix` never installs
+system packages and never runs sudo. Prerequisites are in
+[INSTALLATION.md](../INSTALLATION.md).
+
+## Exit codes
+
+One contract, enforced from 11.4.0 (details in [exit-codes.md](../exit-codes.md)).
+`loki verify` exits 0 VERIFIED, 1 CONCERNS, 2 BLOCKED or not a git directory,
+3 verifier error or empty diff, 64 usage error. Usage errors from `loki quick`
+and `loki start` are also 64. CI gates should use `loki verify || fail`, not
+`[ $rc -eq 1 ]`, and treat any code of 2 or higher as worse than CONCERNS. This
+is a breaking change for scripts that tested rc==1 on an empty diff or a
+non-git directory.
+
 ## The summary
 
-A finished run prints the start line, then one label per line (Outcome,
+Every run on both engines also ends with one unified block: `Result:`
+(verified, done-unverified, failed or stopped), `Files:` (N changed, +ins
+-del), `Cost:` (`$X.XX`, marked `(estimated)` when not provider-reported,
+`not measured` when unknown), `Elapsed:`, `Receipt:` (path, when one exists)
+and one `next:` line naming the suggested command (`loki diff`, `loki verify`,
+`loki undo`, `loki status`, `loki doctor`, or `loki chat --attach`). Pass
+`--quiet` to print only this block and `--json` to add a `summary` object to
+the JSON output. `NO_COLOR=1` disables color, which is also off when stdout is
+not a TTY. On the previous loop, `LOKI_SUMMARY_JSON=1` prints the summary as
+one JSON line, and its cost is always an estimate from the context tracker.
+
+A finished engine10 run prints the start line, then one label per line (Outcome,
 PR, Receipt, NOT PROVEN, Cost, Time; a Reason line is added for any
 outcome other than VERIFIED or ALREADY_SATISFIED). The quiet default stays
 within 8 lines. The block below is the older 5-line form; the labels are the
@@ -221,18 +382,82 @@ receipt with no signing key configured (or a key that failed to load) reads
 
 ## Provider table
 
-| Provider | Cost measured | Kill blocking enforced |
-|----------|----------------|--------------------------|
-| claude   | yes            | yes                      |
-| codex    | no             | no                       |
-| cline    | no             | no                       |
-| aider    | no             | no                       |
-| opencode | not supported  | n/a                      |
+| Provider | Cost measured | Spend cap enforced | Guardrail scan | Kill blocking enforced |
+|----------|---------------|--------------------|----------------|------------------------|
+| claude   | yes (provider-reported) | yes | native | yes |
+| codex    | yes (parsed or estimated) | yes | yes | no |
+| cline    | yes (parsed or estimated) | yes | yes | no |
+| aider    | yes (reported or estimated) | yes | yes | no |
+| opencode | no | no (cost not measured); wall clock limit still applies | yes | no |
+
+Claude Code is the default and the only Tier-1 provider; the others are
+optional. Select one with `--provider <name>` or `LOKI_PROVIDER`.
+
+### Cost and the spend cap on non-Claude providers
+
+For codex, cline and aider, engine10 reads token usage from the CLI output
+(aider's `Cost: $X session` line is used as-is). If the CLI prints no usage,
+cost is estimated from prompt and response sizes (about 4 characters per
+token) with the built-in price table (`loki-ts/src/providers/price_table.ts`).
+A model not in the table prices at a mid-range default of $2 per 1M input
+tokens and $10 per 1M output tokens. Estimated figures carry `estimated: true`
+and `cost_basis` (`provider-tokens` or `size-estimate`) on the `cost` event in
+`events.jsonl`, and the efficiency record has `cost_source: "estimated"`.
+Estimates are approximate. The cap in `--max-cost` applies unchanged. A run
+with no prompt and no output stays `not measured`, never `$0.00`.
+
+### Guardrails on non-Claude providers
+
+With codex, cline, aider or opencode, engine10 enforces the wall-clock limit
+and `BUDGET_LIMIT` (for example `BUDGET_LIMIT=5 loki start prd.md`) by killing
+the process group. After each iteration it scans the diff and reverts and
+fails the iteration on mass deletion of tracked files, `.git/config` changes,
+new git hooks, and symlinks or paths outside the project (a `guard.violation`
+event). Native flags are used where the CLI has them: codex runs with
+`--sandbox workspace-write`, aider with `--no-auto-commits`. Cline and
+opencode have no sandbox flag. The scan is post-hoc rather than inline, so
+receipts still list `kill blocking not enforced` for these providers.
+
+For opencode, a run's Cost line reads `not measured` and the NOT PROVEN line
+adds the literal entry `kill blocking not enforced`
+(`loki-ts/src/engine10/stages/seal.ts`). opencode is a supported
+engine10 provider (`loki-ts/src/runner/provider_opencode.ts`): install it with
+`npm install -g opencode-ai` and select it with `--provider opencode`. It runs
+`opencode run --auto` non-interactively, takes a `provider/model` id from
+`LOKI_OPENCODE_MODEL` (for example `openrouter/deepseek/deepseek-v3.2`; unset
+uses opencode's own default), passes extra flags from `LOKI_OPENCODE_FLAGS`,
+and honors `LOKI_OPENCODE_CLI` for the binary path. `LOKI_HOST_GUARD=1` is
+incompatible with non-Claude providers.
+
+### Model routes and local models
+
+To run OpenRouter or a local model through the Claude harness, so every
+Tier-1 control (cost, kill blocking, receipts) still applies, set
+`LOKI_MODEL_ROUTE=<kind>/<id>` before `loki start`. Selection is by
+environment variable; `loki start` has no `--model` flag.
+
+```
+LOKI_MODEL_ROUTE=ollama/qwen3-coder loki start prd.md
+LOKI_MODEL_ROUTE=openrouter/deepseek/deepseek-v3.2 loki start "fix the login bug"
+```
+
+| Kind | Base URL | Token |
+|------|----------|-------|
+| `openrouter/<id>` | https://openrouter.ai/api | `OPENROUTER_API_KEY` |
+| `ollama/<id>` | http://localhost:11434 | none |
+| `lmstudio/<id>` | http://localhost:1234 | none |
+| `llamacpp/<id>` | http://localhost:8080 | none |
+| `vllm/<id>` | http://localhost:8000 | none |
+| `custom/<id>` | `LOKI_MODEL_BASE_URL` (required) | `LOKI_MODEL_API_KEY` (optional) |
+
+A route spec in `LOKI_MODEL_OVERRIDE` works too. The route environment
+applies to the Claude child process only; the token is never exported into
+your shell, put on a command line, or logged. Plain Claude ids (`opus`,
+`sonnet`, `claude-*`) behave as before.
 
-For codex, cline and aider, a run's Cost line reads `not measured` and the
-NOT PROVEN line adds the literal entry `kill blocking not enforced`
-(`loki-ts/src/engine10/stages/seal.ts`). opencode is not one of engine10's
-provider names (`claude`, `codex`, `cline`, `aider`); it is not supported.
+`loki models` lists the routes. `loki models --local` probes Ollama, LM
+Studio, llama.cpp and vLLM on their default ports (1s timeout each) and prints
+ready-to-paste values. Both accept `--json`.
 
 ## Model routing
 
@@ -321,10 +546,11 @@ runs on the B9 corpus, and it can emit shape defaults from those runs
 
 ## After the flip
 
-D48 made v10 the default for `loki "<task>"`, `loki owner/repo#N` and
-`loki quick "<task>"`. 11.0.0 removed the engine switch: `loki legacy` exits
-2 with a removal message and LOKI_ENGINE is ignored. PRD-file starts
-(`loki start ./prd.md`), the opencode provider, and the no-bun
-fallback still run on the previous bash loop until FC38-SWEEP ports them; they are tracked in
-docs/v10/LEGACY-REMOVAL.md. The marked line near the top of this file and of
-README.md's Loki 10 section records the current state.
+D48 made v10 the default for `loki start`, `loki "<task>"`,
+`loki owner/repo#N` and `loki quick "<task>"`. 11.0.0 removed `loki legacy`
+(it exits 2 with a removal message). From 11.4.0, `--engine legacy|engine10`
+and `LOKI_ENGINE` select the engine explicitly, and PRD-file starts, flag-first
+calls, one-word briefs and the opencode provider run on Loki 10 (see Routing).
+The previous bash loop runs only in the cases listed under Routing. The marked
+line near the top of this file and of README.md's Loki 10 section records the
+current state.

package/docs/v10/METRICS.md

@@ -611,3 +611,9 @@ the same hidden checks; wall_ratio = mean loki wall / mean raw wall; 95% percent
 ## Release latency metric (WF-2MIN-3)
 
 Definition: seconds from the Release run's dispatch/push event to the `+ loki-mode@<version>` line of the `npm publish` step in the `release` job. Baseline run 37869841774: 2m46s (gate/required-ci 30s, release 68s, publish-npm 64s). Target: under 2m. npm registry lag is NOT part of this metric; the non-blocking `npm-visible` job records it separately in its job summary (`npm registry lag: ... visible after Ns`, or `NPM-LAG-TIMEOUT`). Post-Release Smoke polls for visibility itself (up to 15 min).
+
+| Version | Release run | Push SHA | Run created (UTC) | `+ loki-mode@` line (UTC) | Dispatch to publish | npm-visible done (UTC) | Registry lag (separate) | Target met |
+|---|---|---|---|---|---|---|---|---|
+| 11.3.8 | 37875150528 | 80989fdf0 | 02:33:37Z | 02:35:20Z | 1m43s | 02:39:49Z | ~4m29s | yes (under 2m) |
+
+Source: `gh run view 37875150528 --log` (release job "Publish the verified tarball (no rebuild)" printed `+ loki-mode@11.3.8` at 2026-10-09T02:35:20Z), `gh run view 37875150528 --json createdAt` = 02:33:37Z; npm next = 11.3.8 at 436s after push. CTO steering smoke on 11.3.8: PASS (trivial-sum VERIFIED, $0.07, 27s). Prior run 11.3.7 (pre WF-2MIN-3) was 2m32s.