loki-mode 11.3.9 → 11.5.1

package/docs/spec-first-intent.md

@@ -26,3 +26,32 @@ A spec that does not parse exits 2 before any run state is created, naming the f
 ## Unchanged without the flags
 
 Without `--spec` or `--spec-first`, `loki plan` stays on its existing route, `loki start` behaves as before, and the plan and implement briefs are byte-identical (pinned by golden fixtures in `loki-ts/tests/engine10/fixtures`).
+
+## Requirement-to-check map (REQTRACE)
+
+File: `.loki/state/requirements-map.json`. Written after verification, before the run summary. Read-only view: `loki plan --requirements` (add `--json` for the raw file). Code: `loki-ts/src/features/contract.ts`; tests: `loki-ts/tests/features/contract.test.ts`.
+
+```json
+{"version":1,"revision":"<git sha at write time, or \"unknown\">","requirements":[
+  {"id":"R1","text":"...","checks":["<check id>"],"status":"covered","method":"explicit"}
+]}
+```
+
+- `status` is `covered` only when at least one check that actually ran and passed maps to the requirement. `checks` lists only those passing checks. A failed, flaky, not_run or pending check never covers.
+- `method` is `explicit` when the requirement carries its own link to checks, `heuristic` otherwise. An uncovered requirement with no link is `heuristic` with `checks: []`.
+- Ids `R1..Rn` are assigned in source order. At most 40 requirements are taken from PRD text.
+- The file is never written when there is no requirement source, and a write failure never fails a run.
+
+Requirements and checks come from existing extractors, with no second parser:
+
+| Run | Requirements | Checks that ran | Link |
+|---|---|---|---|
+| Bun runner (`loki start`, default) | `.loki/checklist/checklist.json` items | that item's `verification[]` entries, id `<item id>:<type>:<n>`; `passed === true` counts | explicit, by construction |
+| engine10 with `--spec` | acceptance criteria of the spec snapshot (`spec_file.ts` parseSpec) | `test.result` events of the run, id = check name (`runner:path`) | explicit if the criterion ends with `[check: id1, id2]`, else heuristic |
+| engine10 text or PRD task | units from `autonomy/lib/requirements_contract.py` `extract_bound_requirement_units`; needs 2 or more units | same `test.result` events | heuristic |
+
+Heuristic rule: a passing check matches when it shares at least 2 significant words (4 or more letters, minus a small stop list; all of them when the requirement has only one) with the check id plus command. It is a hint, not proof, which is why `method` is recorded.
+
+Surfaces: the run summary next-step line reads `N requirement(s) uncovered, see: loki plan --requirements` when `N > 0`, inside the 8-line cap (engine10 `withNextLine` / `formatRunSummary`, and `autonomy/lib/run-summary.sh` for the bash summary). The JSON summary adds `requirements_uncovered` only when `N > 0`.
+
+Known gaps: the legacy bash engine (`autonomy/run.sh` without Bun) does not write the map; its summary only reads one if present. Heuristic matching is word overlap only and can both miss and over-claim, so use explicit `[check: id]` links for requirements that matter.

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): 190
 
 ## 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 |
@@ -178,7 +184,7 @@ Classes: KEEP-MODERN (v10-native or engine-neutral), UPDATE (live but needs mode
 - preview: 1
 - projects: 8
 - proof: 6
-- provider: 3
+- provider: 2
 - quick: 1
 - resume: 1
 - rollback: 2

package/docs/v10/ENGINE.md

@@ -252,6 +252,38 @@ Every claim below comes from reading main at 84c22568. I edited no files.
 - **Green:** all five assertions hold against the sandbox repo.
 - **Deps:** E-23, E-32, E-36.
 
+### Recovery of an interrupted run
+
+Code: `resumeMain`, `findInterrupted`, `resumePublish`, `startRecovery` in `loki-ts/src/util/run_outputs.ts`, `phaseOf` in `events.ts`, `runOwnerAlive` in `util/run_pid.ts`, the push-skip in `autonomy/lib/engine10-push.sh`, `loki resume` in `autonomy/loki`. Tests: the RECOVERY block in `loki-ts/tests/engine10/pr.test.ts` and the recovery block in `tests/test-engine10-push.sh`.
+
+An interrupted run has an `events.jsonl` with neither `run.completed` nor `pr.opened`, and a `run.pid` that does not name a live process with the recorded start time. A run owned by a live supervisor is never resumed. The phase comes from the event log only (`phaseOf`):
+
+| Phase     | Meaning                                                     | Recoverable |
+|-----------|-------------------------------------------------------------|-------------|
+| implement | no `stage.completed` for implement                          | No (reported) |
+| verify    | implement completed, no `receipt.sealed`                    | No (reported) |
+| publish   | `receipt.sealed` present, no `pr.opened` or `run.completed` | Yes |
+| done      | `pr.opened` or `run.completed` present                      | Nothing to do |
+
+`loki resume [run-id]`, and `loki start "<same task>"` when the newest interrupted run is in the publish phase, its recorded intake task equals the new task and `--no-pr` is absent, resume the publish phase and print `resumed phase: publish (run <id>); receipt reused; PR <url>`.
+
+- The sealed receipt is reused: no second `receipt.json`, no second `receipt.sealed` event. Resume never reseals.
+- Events appended: `run.resumed`, `pr.opened`, `run.completed` (with `resumed: true` and the not-proven note "publish phase resumed after an interruption"), then the log seal.
+- Push is skipped when the remote branch is already at the local commit (GitHub: `gh api .../git/ref/heads/<branch>`; local bare origin: `git ls-remote`). A newer commit is a new revision and is pushed.
+- PR creation checks `gh pr list --head <branch> --state open` first and reuses an open PR, so any number of publish attempts yields one PR.
+
+For implement and verify, `loki resume` prints the phase, whether branch `loki/<run-id>` holds preserved work, and exits 4. `loki start` prints a one-line note and starts a new run. `LOKI_NO_RESUME=1` disables the `loki start` check.
+
+Exit codes of `loki-ts engine10 resume`: 0 resumed, 3 no interrupted run, 4 phase reported but not auto-resumable, 5 publish attempted and failed (the run stays resumable), 2 not in a git repository or no origin.
+
+Honest limits:
+- implement and verify keep stage outputs in the worker's memory; the stage machine cannot skip completed stages. Work committed on `loki/<run-id>` is preserved but the run is not continued.
+- A crash between `gh pr create` returning and `pr.opened` being recorded is recovered by the open-PR lookup, provided GitHub lists the PR by then.
+- A crash after the commit status call but before `run.completed` sets the same status again.
+- GitLab origins (`engine10-push-gitlab.sh`) are unchanged; push-skip and PR reuse are verified for the GitHub and local-bare paths only.
+- The legacy bash loop (`autonomy/run.sh`) keeps its own iteration-level resume.
+- Deep verify (a detached child spawned after `pr.opened`) is not re-spawned on resume.
+
 ### BOARD rows
 
 The notes start with the requested "Source: ENGINE.md 23:00Z cut." and then add dependencies, following the 21:50Z rows. If you want the notes to be only that sentence, drop the dependency part.

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.

package/loki-ts/data/model-pricing.json

@@ -2,6 +2,7 @@
   "$schema_version": 1,
   "_comment": "Rolling pricing table consumed by loki-ts/src/runner/budget.ts. Update this file when Anthropic / OpenAI / others publish new prices; no code change required. Pricing is USD per 1 million tokens. Aliases (opus/sonnet/haiku) point to the latest model of that family per providers/model_catalog.json.",
   "_updated": "2026-10-08",
+  "default_max_cost_usd": 100,
   "_source": "https://platform.claude.com/docs/en/about-claude/pricing (docs.anthropic.com/en/docs/about-claude/pricing 301-redirects there), read 2026-10-08. Per MTok. fable=Claude Fable 5.1 $10/$50, cache read $0.25 (0.025x), 5m write $12.50, 1h write $20. opus=Claude Opus 5.5 $4/$20, cache read $0.20 (0.05x), 5m write $5, 1h write $8. sonnet=Claude Sonnet 5.5 $2/$10, cache read $0.10 (0.05x), 5m write $2.50, 1h write $4. haiku alias row prices as its catalog target claude-haiku-5-5 (providers/model_catalog.json cli_aliases), so it equals that row including over_100k; Haiku 4.5 ($1/$5) is no longer an alias target. claude-haiku-5-5 (exact id, same as the haiku alias): $0.10/$0.50, read $0.01, 5m $0.125, 1h $0.20 up to 100,000 prompt tokens; over_100k $0.50/$2.50, read $0.05, 5m $0.625, 1h $1. Fields: cache_write is the 5m write rate (legacy readers); cache_write_5m and cache_write_1h are the explicit tiers. Multipliers: 5m write 1.25x, 1h write 2x, read 0.1x (0.05x on Opus 5.5 and Sonnet 5.5, 0.025x on Fable 5.1). OpenAI rows (gpt-5.3-codex, gpt-5.6-sol/terra/luna): https://developers.openai.com/api/docs/pricing, read 2026-10-08, Standard tier, short context (up to 272K); cached input is the cache_read field; OpenAI bills no cache write, cache_write is a 1.25x placeholder.",
   "pricing": {
     "fable": {