loki-mode 11.3.9 → 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/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/OPENCODE-PARITY-PLAN.md

@@ -0,0 +1,84 @@
+# v11.4.0 plan: beat opencode by 1-2 points in every category
+
+Founder directive (2026-10-15): close every gap an outside assessment found
+against opencode. Keep Loki autonomous. Keep the harness and internals
+(RARV-C, receipts, Seal, council) as they are, and keep Claude Code as the
+primary provider. Ship all of it as one MINOR release, v11.4.0, built in
+parallel. Under the founder's standing waiver nothing is tested.
+
+Founder clarification (2026-10-15): `loki start` is always the primary
+path. `loki chat` is an alternative surface. Every improvement in this
+release (model routes, local models, providers, agents, routing, exit codes,
+run summary, onboarding) must work through `loki start` first. Chat must hand
+off to and from `loki start` without friction: `/run` in chat starts the same
+run with the same model, provider and agents, and chat can attach to a
+running or finished `loki start` session (status, steer, diff, verify).
+
+## Scorecard target
+
+| Category | Was (Loki / opencode) | Target | Slices |
+|---|---|---|---|
+| Everyday user experience | 6 / 8 | 10 | OC-CHAT, OC-OUTPUT |
+| Installation and onboarding | 6 / 8 | 10 | OC-ONBOARD, OC-DOCS |
+| Learning curve | 5 / 8 | 10 | OC-ROUTE, OC-HELP |
+| Interactive coding and exploration | 6 / 9 | 10 | OC-CHAT |
+| Small, targeted changes | 7 / 8 | 10 | OC-EDIT |
+| Model/provider flexibility | 5 / 9 | 10 | OC-MODELS, OC-OPENCODE-E10 |
+| Local-model setup | 5 / 8 | 10 | OC-MODELS |
+| Multi-agent workflow design | 7 / 8 | 10 | OC-AGENTS |
+| Documentation consistency | 4 / 7 | 10 | OC-DOCS |
+| Predictability across commands/upgrades | 5 / 6 | 10 | OC-ROUTE, OC-EXIT, OC-PARITY-COST, OC-PARITY-ENFORCE |
+
+## Todo (one slice each, parallel, own branch `slice-OC-<KEY>`)
+
+- [x] OC-CHAT: `loki chat` opens an interactive session (the first cut
+  also opened it from bare `loki` on a TTY; that was reverted, and bare `loki`
+  stays unchanged). Plan mode is read-only and Build mode edits; `/plan`
+  and `/build` switch between them. Slash commands: /run, /quick, /edit,
+  /verify, /receipt, /model, /provider, /cost, /diff, /undo, /help, /exit.
+  `loki chat --tui` launches Claude Code's own TUI.
+- [x] OC-ROUTE: one predictable execution path. Flag-first calls, PRD files
+  and one-word starts reach the same engine as the positional form. The
+  legacy engine runs only on an explicit `--engine legacy` or
+  `LOKI_ENGINE=legacy`. `loki route <args>` prints the engine and why.
+- [x] OC-EXIT: close the three `loki verify` exit-code gaps and use one
+  exit-code contract for verify, run, quick and edit. Update
+  docs/exit-codes.md and remove the KNOWN-ISSUES entry.
+- [x] OC-MODELS: model routes over the Claude harness, so every Tier-1
+  control still works. Routes: `--model openrouter/<id>`, `ollama/<id>`,
+  `lmstudio/<id>`, `llamacpp/<id>`, `vllm/<id>`, and any
+  Anthropic-compatible base URL. `loki models` lists routes;
+  `loki models --local` discovers local runtimes.
+- [x] OC-PARITY-COST: engine10 measures cost for Codex, Cline and Aider.
+- [x] OC-PARITY-ENFORCE: engine10 enforces the budget kill, a post-iteration
+  guard scan and native sandbox flags for Codex, Cline, Aider and opencode.
+  Receipts still list `kill blocking not enforced` because the scan is post-hoc.
+- [x] OC-OPENCODE-E10: opencode becomes a supported engine10 provider.
+- [x] OC-AGENTS: configurable child agents in `.loki/agents/*.md` (model,
+  provider, tools, permissions, prompt), managed with
+  `loki agents list|new|show`. Councils and reviewers use them when present,
+  and they export to Claude Code subagents.
+- [x] OC-EDIT: `loki edit "<change>"` makes a fast single-pass edit with no
+  PR, plan or council. It shows the diff; `--verify` and `--receipt` are
+  opt-in.
+- [x] OC-ONBOARD: `loki setup` wizard and `loki doctor --fix`. Claude Code
+  first, with required and optional prerequisites stated plainly.
+- [x] OC-HELP: `loki help` shows the core verbs, `loki help all` shows the
+  full surface, and `loki help <topic>` covers topics. Mistyped commands get
+  "did you mean" suggestions, and `--json` works the same everywhere.
+- [x] OC-OUTPUT: one run summary across engines (result, cost, time,
+  receipt, next step), with `--quiet` and NO_COLOR honored.
+- [ ] OC-START-INTEGRATION (after merge): wire every feature above into
+  `loki start` (`--model <route>`, `--provider`, configured agents, unified
+  summary, exit codes, explain-route). Bare `loki` keeps its current
+  behavior and does not open chat. Seamless chat handoff: `/run` reuses the
+  chat's model, provider and agents; `loki chat --attach` joins the current
+  or last `loki start` session; the run summary's next step names
+  `loki chat --attach`.
+- [x] OC-DOCS (after merge; README, INSTALLATION, GUIDE, QUICKSTART and
+  COMPARE-OPENCODE written): README, INSTALLATION, GUIDE and a new QUICKSTART
+  agree with the code on prerequisites, the spend cap, routing and providers.
+  Add docs/COMPARE-OPENCODE.md.
+- [ ] Release: merge onto train-v11.4.0, rebuild loki-ts dist, write a full
+  CHANGELOG v11.4.0 section, run `scripts/release.sh minor --bump-only`,
+  push main, and confirm the release run.