loki-mode 7.129.5 → 8.0.1

package/README.md

@@ -15,7 +15,7 @@ _The free, source-available autonomous coding agent by [Autonomi](https://www.au
 
 [Website](https://www.autonomi.dev/) | [Documentation](wiki/Home.md) | [Installation](docs/INSTALLATION.md) | [Changelog](CHANGELOG.md) | [Purple Lab -- deprecated v7.44.0](#purple-lab)
 
-**Current release: v7.121.5**
+**Current release: v8.0.0**
 
 </div>
 
@@ -25,19 +25,63 @@ _The free, source-available autonomous coding agent by [Autonomi](https://www.au
 
 ---
 
+## The Evidence Receipt: don't trust the agent, check it
+
+Every coding agent tells you it finished. Loki hands you something you can
+check yourself.
+
+Each run writes a receipt to `.loki/proofs/<run_id>/` that separates
+**deterministic FACTS** (the git diff with base and head SHAs plus a
+`diff_sha256`, the test command and its exit code, the build command and its
+exit code, each gate verdict) from **AI ASSESSMENTS** (the council verdict,
+labeled as judgment, never as proof). The headline is computed from the facts
+alone:
+
+| Headline | Means |
+|---|---|
+| VERIFIED | tests ran a real command and exited 0, diff non-empty, nothing skipped |
+| VERIFIED WITH GAPS | each gap listed by name |
+| NOT VERIFIED | a check ran and failed |
+
+```bash
+loki proof list            # every receipt from this project
+loki proof show <id>       # the facts, the assessments, and the headline
+loki proof verify <id>     # re-hash the receipt and re-derive the diff
+```
+
+`loki proof verify` exits 0 clean, 1 on tamper or drift. Receipts are attached
+to pull requests automatically (`LOKI_PROVEN_PR=0` to opt out), so a reviewer
+sees the evidence next to the code.
+
+**What the receipt does NOT claim.** On the unsigned path the generator is
+trusted: someone who rewrites both the facts and the headline into a mutually
+consistent lie and recomputes the hash will still pass verification. That is
+defense-in-depth, not non-forgeability, and neutral non-forgeability needs the
+signed record. We tested for exactly this and locked the limitation into the
+suite (`tests/test-proof-forgery-defense.sh`), and in v7.111.0 we removed our
+own earlier "non-forgeable" claim once we found it was false on that path. An
+honest boundary you can verify beats a marketing claim you cannot.
+
+To close that gap, sign your receipts: `export LOKI_PROOF_GPG_KEY=<key-id>` and
+every receipt carries a detached GPG signature that any third party with your
+public key can verify offline. See [docs/SIGNED-RECEIPTS.md](docs/SIGNED-RECEIPTS.md).
+
 ## Why Loki Mode?
 
-- **Spec-driven, autonomous, with a built-in trust layer** -- Hand Loki a spec, walk away, come back to working code with tests. The full RARV-C closure loop (Reason - Act - Reflect - Verify - Close) runs until the work is actually done, not just attempted. The verified-completion evidence gate (`skills/quality-gates.md`) refuses any "done" claim on an empty git diff against the run-start commit, and blocks completion when tests run red, so "complete" means proven, not promised.
+- **Spec-driven, autonomous, with a built-in trust layer** -- Hand Loki a spec, walk away, come back to working code with tests. The full RARV-C closure loop (Reason - Act - Reflect - Verify - Close) runs until the work is actually done, not just attempted. The verified-completion evidence gate (`skills/quality-gates.md`) refuses any "done" claim on an empty git diff against the run-start commit, blocks completion when tests run red, and (v8.0.0) also blocks when a serveable app is confirmed unhealthy (runtime-boot axis, opt out `LOKI_EVIDENCE_BOOT_GATE=0`) or a credential is detected in the changed files (secret-leak axis, opt out `LOKI_EVIDENCE_SECRET_GATE=0`), so "complete" means proven, not promised.
 - **A checklist verifier that is honest, not brittle** -- Each completion checklist item is checked deterministically before the completion council will accept "done". The verifier speaks extended regex (`grep -E`) so real LLM-emitted patterns match instead of erroring, and it is runner-agnostic: it runs the project's own declared test command rather than assuming a fixed runner. Crucially, a check that cannot be established is reported as inconclusive (pending), never as a false pass and never as a false failure. `rc == 0` alone is not a pass; a test check goes green only on a real "N passed" signal from the runner (v7.121.x).
 - **Production quality built in** -- 8 quality gates (`skills/quality-gates.md`), blind 3-reviewer code review (`run.sh:run_code_review()`), anti-sycophancy checks
 - **Standalone verification: `loki verify`** -- Run Loki's deterministic gates (build, tests, static analysis, secret scan, dependency audit) against any branch or PR diff, including code written by other agents or humans. CI-ready exit codes (0 VERIFIED, 1 CONCERNS, 2 BLOCKED), machine-readable evidence at `.loki/verify/evidence.json`. Inconclusive evidence is never reported as VERIFIED (v7.27.0).
-- **Living spec and pre-build interrogation** -- `loki spec` locks a spec and detects drift deterministically (`spec.lock`, `drift-report.json`, and a `SPEC_DRIFT` finding in `loki verify` with CI exit codes), so you can tell when the build diverges from what was agreed. `loki grill` runs a Devil's-Advocate interrogation of the spec before you build, surfacing gaps and contradictions early (v7.28.0).
+- **Living spec and pre-build interrogation** -- `loki spec` locks a spec and detects drift deterministically (`spec.lock`, `drift-report.json`, and a `SPEC_DRIFT` finding in `loki verify` with CI exit codes), so you can tell when the build diverges from what was agreed. For an OpenAPI/GraphQL/Postman contract it locks one requirement per operation with a per-operation hash, so a single changed response schema drifts exactly that operationId (v8.0.0). `loki grill` runs a Devil's-Advocate interrogation of the spec before you build, surfacing gaps and contradictions early (v7.28.0).
 - **Mid-flight model switching** -- switch the model a live run uses from the dashboard (applies at the next iteration, current run only). A Fable tier lever exists in the CLI, dashboard, and override paths, but Claude Fable 5 is not yet available at the API, so selecting Fable currently collapses to Opus at every dispatch chokepoint and the `loki plan` quote reflects Opus accordingly. For every model lever (session pin, mid-flight override, architect pass) and every `LOKI_MAX_TIER` path, the `loki plan` quote, the dashboard's reported model, and the actual dispatched model agree, with the ceiling enforced (v7.31.0; Fable-to-Opus collapse v7.39.1).
 - **A calmer CLI** -- the help surface is ~20 grouped workflow entries instead of a 70-command wall; merged commands live on as aliases that forward byte-identically with a one-line stderr pointer, so no script breaks (v7.31.0).
 - **Guided first build: `loki quickstart`** -- four quick questions (setup check, one-line idea, template pick, plan review) and your build starts; pressing Enter through every step builds the sample Todo app. The plan step quotes the real cost/time estimate before anything is spent, and `loki demo` now confirms its estimate the same way. If no AI provider CLI is installed, Loki offers to install Claude Code (consent-gated, interactive terminals only) (v7.29.0).
 - **Live App Preview** -- The dashboard embeds the locally-running app in an iframe so you can interact with it immediately during a build. Use `loki preview` (alias `loki open`) to print the URL and open it in your browser. Local-first: no hosted service, no vendor lock (v7.24.0).
 - **Compose-first fullstack** -- When a spec needs more than one service (web + database + cache) Loki generates a 12-factor `docker-compose.yml` with healthchecks, `depends_on` wiring, env-var config, and a `.env.example`. The Live App Preview surfaces the web service URL (not a database port), and health reflects the web service's Docker healthcheck so a crashed app shows as crashed even when the database stays up. Single-service apps stay on a plain run command. All local-first, no hosted service (v7.26.0).
 - **Intelligent `loki start`** -- For interactive foreground runs the dashboard auto-opens in the browser (cross-platform; skipped in CI, SSH-without-TTY, and piped runs; opt out with `LOKI_NO_AUTO_OPEN=1`). The completion summary shows "Your app is live at <url>" so you know exactly where to try what Loki just built. The autonomous loop passes Claude Code's `--effort`, `--max-budget-usd`, and `--fallback-model` on every iteration (each gated on CLI support and individual opt-out env vars) for better long-run unattended execution (v7.25.0).
+- **Confidence is not evidence** -- When the agent's self-reported confidence spikes to near-certainty, Loki forces an EXTRA verification pass before accepting a stop, rather than taking the claim at face value. Strictly additive: high confidence makes the engine look harder, never less hard, and it can never skip or satisfy a gate (v8.0.0, opt out `LOKI_CONFIDENCE_SPIKE=0`).
+- **Goals it can actually measure** -- A goal with no checkable success condition ("make it fast") gives the loop no gradient: every iteration can claim progress and none can be verified. Loki flags an un-measurable goal up front and asks for a threshold, a metric, or a concrete artifact. Advisory only, and never rewrites your goal (v8.0.0, opt out `LOKI_GOAL_SCORING=0`).
+- **Stops paying for failures that cannot succeed** -- A positively-identified permanent failure (bad credentials, unknown model, exhausted quota) exits immediately instead of burning the retry budget on guaranteed-identical failures. Fail-safe: an unrecognized error still retries exactly as before, and rate limits are never treated as permanent (v8.0.0, opt out `LOKI_SMART_RETRY=0`).
 - **Cross-project memory** -- Episodic/semantic/procedural memory with vector search; knowledge learned on one project surfaces on the next (v5.15.0+, see `memory/engine.py`)
 - **Self-hosted and private** -- Your keys, your infrastructure, no data leaves your network
 - **Legacy system healing** -- `loki modernize heal` archaeology/stabilize/isolate/modernize/validate phases (v6.67.0, see `skills/healing.md`)
@@ -182,7 +226,60 @@ loki init my-app --template simple-todo-app    # scaffold a starter PRD
 cd my-app && loki start prd.md                 # autonomous build from the spec
 ```
 
-One thing to know first: Loki drives a separate coding-agent CLI (Claude Code is the recommended one) and needs it plus a couple of common tools on your PATH. Run `loki doctor` any time and it tells you exactly what is present and what is missing, with a copy-pasteable install command for each gap.
+One thing to know first: Loki needs a model to drive. There are two ways to give it one.
+
+**Without a separate CLI (v8).** The Claude Agent SDK ships inside Loki, so an API key alone is enough:
+
+```bash
+export ANTHROPIC_API_KEY=sk-...               # or ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL
+LOKI_SDK_MODE=full loki start prd.md          # runs the loop and the judges through the bundled SDK
+```
+
+This needs Bun on your PATH (the SDK loop runs on the Bun runtime). `loki doctor` reports `Bundled Claude Agent SDK is usable -- no separate CLI needed` when that path is genuinely ready, and stays on the normal blocker otherwise: it checks that the SDK's platform binary is actually extracted, that credentials are present, and that the SDK loop is really the route your next run will take. It will not tell you that you are ready and then fail the build.
+
+**With a coding-agent CLI.** The classic path, and still the default: Loki drives a separate CLI (Claude Code is the recommended one) plus a couple of common tools on your PATH.
+
+**With a different model or provider.** Loki is not tied to Anthropic. Anything
+that speaks the Anthropic Messages API works: OpenRouter, Ollama, LiteLLM, vLLM,
+or your own gateway. Point `ANTHROPIC_BASE_URL` at the endpoint and name the
+model with `LOKI_MODEL_OVERRIDE`:
+
+```bash
+# OpenRouter (hundreds of models, one key)
+export ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
+export ANTHROPIC_API_KEY=sk-or-...
+export LOKI_MODEL_OVERRIDE=<model-id-from-openrouter.ai/models>
+loki start prd.md
+
+# Ollama, fully local (no API key, no per-token cost)
+export ANTHROPIC_BASE_URL=http://localhost:11434/v1
+export LOKI_MODEL_OVERRIDE=<model you have pulled, e.g. the output of `ollama list`>
+loki start prd.md
+
+# LiteLLM / vLLM / any self-hosted gateway
+export ANTHROPIC_BASE_URL=https://your-gateway.internal/v1
+export ANTHROPIC_API_KEY=...
+export LOKI_MODEL_OVERRIDE=<whatever your gateway calls the model>
+loki start prd.md
+```
+
+**Set both variables.** `LOKI_MODEL_OVERRIDE` is what makes the alt-provider
+path work: without it Loki keeps asking for `opus` / `sonnet` / `haiku`, which
+only Anthropic resolves, and most providers reject those names outright. A
+proxy that maps the aliases for you (LiteLLM can) is the one exception.
+
+Model IDs are not listed here on purpose -- OpenRouter's catalogue changes every
+week, and a stale ID in a README is a failure you would hit at runtime. Take the
+exact string from your provider's own model list.
+
+Both routes honor these variables identically -- the bundled-SDK path and the
+Claude Code CLI path -- and `loki doctor` reports the endpoint it detected plus a
+warning if the model override is missing.
+
+The quality gates, the completion council, and the Evidence Receipt do not care
+which model produced the code. They check what was actually built.
+
+Either way, run `loki doctor` any time and it tells you exactly what is present and what is missing, with a copy-pasteable install command for each gap.
 
 ```bash
 loki doctor                                    # check your setup before the first build
@@ -315,7 +412,7 @@ A "spec" is whatever you hand `loki start`. Loki auto-detects the format and nor
 |--------|---------|-------|
 | Markdown PRD | `loki start ./prd.md` | Canonical form. Headings become section anchors. |
 | JSON spec | `loki start ./spec.json` | Free-form JSON; keys surfaced to agents. |
-| YAML spec | `loki start ./openapi.yaml` | OpenAPI / AsyncAPI / plain YAML all accepted. |
+| YAML spec | `loki start ./openapi.yaml` | OpenAPI / AsyncAPI / plain YAML all accepted. An OpenAPI/GraphQL/Postman contract expands into a per-operation build checklist (one item per operationId/field/request) so no operation is lost to prompt truncation (v8.0.0). |
 | Plain text brief | `loki start ./brief.txt` | One-paragraph briefs work; complexity auto-detects to "simple". |
 | GitHub issue URL | `loki start https://github.com/owner/repo/issues/42` | Title + body + labels become the spec. |
 | GitHub shorthand | `loki start owner/repo#42` | Same as above, shorter. |
@@ -482,7 +579,9 @@ Status legend: "E2E-verified" means we run real spec-to-code builds on it oursel
 | `loki stop` | Stop execution |
 | `loki modernize heal <path>` | Legacy system healing (archaeology, stabilize, isolate, modernize, validate -- v6.67.0; was: `loki heal`) |
 | `loki pause` / `resume` | Pause/resume after current session |
+| `loki steer "<note>"` | Nudge a running build with a directive (writes `.loki/HUMAN_INPUT.md`; the loop reads it when `LOKI_PROMPT_INJECTION=1`) (v8.0.0) |
 | `loki status` | Show current status |
+| `loki why` | Explain the last outcome; on a stalled run names the real stall reason (proactive stuck-detector + convergence signal) and suggests `loki steer` (v8.0.0) |
 | `loki cockpit` | Live multi-repo status as an inline terminal image (Kitty/iTerm2/WezTerm/Ghostty); text + dashboard fallback elsewhere (v7.126.0) |
 | `loki dashboard` | Open web dashboard |
 | `loki preview` | Print running app URL and open in browser (Live App Preview, v7.24.0; was: `loki open`) |
@@ -503,6 +602,20 @@ Status legend: "E2E-verified" means we run real spec-to-code builds on it oursel
 
 Run `loki --help` for all options. Full reference: [CLI Reference](wiki/CLI-Reference.md) | Config: [config.example.yaml](autonomy/config.example.yaml)
 
+### Configuration file
+
+Pass a config file to `loki start` with `--config <path>` (aliases: `--env-file`, `--vars`), or set `LOKI_CONFIG_FILE`. The format is detected from the extension or content: `.yaml`/`.yml`, `.json`, or `.env` (flat `LOKI_*=value` lines). Values resolve by precedence: a CLI flag beats an ambient env var, which beats the `--config` file, which beats built-in defaults. Never inline a secret; reference an env var with `${VAR}` and the loader expands it at load time (an unset reference is skipped with a warning, and a raw-looking secret literal is flagged). Generate a starter with `loki config example`.
+
+```bash
+# config.yaml
+dashboard:
+  port: 9000
+github:
+  token: ${GITHUB_TOKEN}   # expanded from the environment, never stored inline
+
+loki start --config config.yaml ./prd.md
+```
+
 ---
 
 <details>
@@ -517,6 +630,9 @@ Loki Mode's accuracy and autonomy behaviors are default-on. Each is an opt-out e
 | `LOKI_AUTO_DOCS` | `true` | Generates the `.loki/docs/` suite before the documentation gate scores it (bounded: once per run when docs are missing, and again only when >10 commits stale). Set `false` to opt out. |
 | `LOKI_CAVEMAN` | `1` (on) | Output-token compressor for free-form generation only (never trust-gate subcalls). Set `0` to opt out. |
 | `LOKI_CAVEMAN_LEVEL` | inferred | Compression level for the compressor. Auto-inferred per invocation from the run's RARV tier; set explicitly (`lite` / `full` / `ultra`) to override the inference. |
+| `LOKI_CONFIDENCE_SPIKE` | `1` (on) | Forces one EXTRA verification pass when the agent's self-reported confidence spikes, instead of trusting the claim. Strictly additive -- it can never skip a gate. Set `0` to opt out; tune with `LOKI_CONFIDENCE_SPIKE_DELTA` (default `40`) and `LOKI_CONFIDENCE_SPIKE_MIN` (default `90`). |
+| `LOKI_GOAL_SCORING` | `1` (on) | Flags a goal with no measurable success condition and asks for a threshold, metric, or concrete artifact. Advisory only -- never blocks a build or rewrites the goal. Set `0` to opt out. |
+| `LOKI_SMART_RETRY` | `1` (on) | Stops early on a positively-identified permanent failure (bad credentials, unknown model, exhausted quota) rather than burning retries. Unrecognized errors and rate limits still retry as before. Set `0` to retry every failure. |
 
 This is a subset. See the [wiki](wiki/Home.md) for the full env-var reference and the RARV-C closure knobs (`LOKI_INJECT_FINDINGS`, `LOKI_OVERRIDE_COUNCIL`, `LOKI_AUTO_LEARNINGS`, `LOKI_HANDOFF_MD`).
 
@@ -639,7 +755,3 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 **[Autonomi](https://www.autonomi.dev/)** | **[Documentation](wiki/Home.md)** | **[Changelog](CHANGELOG.md)** | **[Comparisons](references/competitive-analysis.md)**
 
 </div>
-
-## Star History
-
-[![Star History Chart](https://api.star-history.com/chart?repos=asklokesh/loki-mode&type=timeline&legend=bottom-right)](https://www.star-history.com/?repos=asklokesh%2Floki-mode&type=timeline&legend=bottom-right)

package/SKILL.md

@@ -3,18 +3,20 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v7.129.5
+# Loki Mode v8.0.1
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
-**Spec in, verified product out.** Spec-driven: a "spec" is whatever describes the work -- a Markdown PRD, a GitHub issue, an OpenAPI doc, a Jira ticket (a PRD is one form of spec). The differentiator is the trust layer: Loki does not call work done until it is verified. The RARV-C closure loop, 8 quality gates, the completion council, and the verified-completion evidence gate must all clear before completion is accepted.
+**Spec in, verified product out.** Spec-driven: a "spec" is whatever describes the work -- a Markdown PRD, a GitHub issue, an OpenAPI doc, a Jira ticket (a PRD is one form of spec). The differentiator is the trust layer: Loki does not call work done until it is verified. The RARV-C closure loop, 8 quality gates, the completion council, and the verified-completion evidence gate must all clear before completion is accepted. The evidence gate blocks on empty-diff, red tests, an unhealthy serveable app (runtime-boot axis, `LOKI_EVIDENCE_BOOT_GATE=0` to opt out), and a leaked credential in the changed files (secret-leak axis, `LOKI_EVIDENCE_SECRET_GATE=0` to opt out) -- v8.0.0.
 
 **Evidence Receipt (verify it yourself).** Every run writes a receipt to `.loki/proofs/<run_id>/` (opt out with `LOKI_PROOF=0`) that separates deterministic FACTS (git diff with base/head SHAs and a `diff_sha256`, the test command + exit code, the build command + exit code, each gate verdict) from AI ASSESSMENTS (the council verdict, labeled judgment not proof). The headline is computed only from the facts: VERIFIED (tests ran a real command and exited 0, diff non-empty, nothing skipped), VERIFIED WITH GAPS (each gap listed by name), or NOT VERIFIED (a check ran and failed). Inspect and re-check with `loki proof list|show <id>|verify <id>` (aliased `loki receipt`); `loki proof verify` re-hashes the receipt (tamper) and re-derives the diff from the recorded base SHA against the live repo (drift), exiting 0 clean / 1 tamper-or-drift. This is honesty-of-done, not a claim that the code is bug-free.
 
-**Provider-agnostic (stable since v5.0.0):** runs on Claude/Codex/Cline/Aider with abstract model tiers and degraded mode for non-Claude providers; no vendor lock-in. Gemini deprecated v7.5.18. See `skills/providers.md`. **Current track (v7.7.x):** LSP grounding as first-class agent tool (v7.7.0-v7.7.9; lsp_get_diagnostics actually-returns-diagnostics regression fix v7.7.14), provider_source cli (v7.7.11-v7.7.12 bash/bun parity), Docker/bash-3.2 robustness (v7.7.13), audit chain cross-file verification fix (v7.7.15), Phase 1 RARV-C closure (real provider judges, gate-failure flock, synthetic PRD e2e, status `--json`).
+**Provider-agnostic (stable since v5.0.0):** runs on Claude/Codex/Cline/Aider with abstract model tiers and degraded mode for non-Claude providers; no vendor lock-in. Gemini deprecated v7.5.18. See `skills/providers.md`. **Current track (v8.0.0):** the Anthropic Agent SDK route (see below), spec-mode expansion for OpenAPI/GraphQL/Postman contracts, the runtime-boot and secret-leak evidence axes, and `loki steer` / `loki why` for mid-run control. Earlier tracks: LSP grounding as a first-class agent tool (v7.7.x) and Phase 1 RARV-C closure (real provider judges, gate-failure flock, synthetic PRD e2e, status `--json`).
 
 **Runtime migration:** Bash-to-Bun migration. Read-only commands (`version`, `status`, `stats`, `doctor`, `provider show/list`, `memory list/index`) flow through Bun runtime via `bin/loki` since v7.3.0. Every other command remains on the Bash runtime (`autonomy/loki`). Rollback: `LOKI_LEGACY_BASH=1`. See `UPGRADING.md` and `docs/architecture/ADR-001-runtime-migration.md`.
 
+**Anthropic Agent SDK route (v8.0.0, opt-in, default-off):** a claude-binary-free path where the RARV loop runs on `@anthropic-ai/claude-agent-sdk` `query()` and judges run on the raw `@anthropic-ai/sdk`. One operator switch `LOKI_SDK_MODE` (`off` default / `judges` / `full`), mirrored byte-for-byte in bash (`autonomy/lib/sdk-mode.sh`) and TypeScript (`loki-ts/src/runner/sdk_mode.ts`). Unset = byte-identical to the claude-CLI route. See `references/sdk-mode.md`.
+
 ---
 
 ## PRIORITY 1: Load Context (Every Turn)
@@ -203,7 +205,7 @@ claude --dangerously-skip-permissions
 # Unified `loki start` -- one command, auto-detected mode
 loki start                                   # no arg: analyze current dir, auto-generate spec
 loki start ./prd.md                          # PRD mode (.md/.json/.txt/.yaml) -- a PRD is one form of spec
-loki start ./openapi.yaml                    # SPEC mode (OpenAPI doc treated as the spec)
+loki start ./openapi.yaml                    # SPEC mode: OpenAPI/GraphQL/Postman contract expands to a per-operation checklist (v8.0.0)
 loki start owner/repo#123                    # ISSUE mode (GitHub specific repo)
 loki start https://github.com/o/r/issues/42  # ISSUE mode (GitHub URL)
 loki start 123                               # ISSUE mode (GitHub issue in current repo)
@@ -250,7 +252,9 @@ When running with `autonomy/run.sh`, you can intervene:
 | Method | Effect |
 |--------|--------|
 | `touch .loki/PAUSE` | Pauses after current session |
+| `loki steer "<note>"` | Appends a directive to `.loki/HUMAN_INPUT.md` (needs `LOKI_PROMPT_INJECTION=1`); v8.0.0 |
 | `echo "instructions" > .loki/HUMAN_INPUT.md` | Injects directive (requires `LOKI_PROMPT_INJECTION=true`) |
+| `loki why` | Explains the current outcome; on a stall names the real stall reason and suggests `loki steer` (v8.0.0) |
 | `touch .loki/STOP` | Stops immediately |
 | Ctrl+C (once) | Pauses, shows options |
 | Ctrl+C (twice) | Exits immediately |
@@ -352,6 +356,58 @@ Two completion-trust features extend the verification gates. Full details in `sk
 - **Held-out spec evals:** ~25% of checklist items (deterministic `sha256(id)` order, `N >= 4`) are reserved into `.loki/checklist/held-out.json` and excluded from the build prompt feed; the completion council blocks if a held-out item fails. Opt out with `LOKI_HELDOUT_GATE=0`. Honest limit: this guards the prompt feed, not a sandbox; the reservation file is on disk and an agent with filesystem access can read it.
 - **Inconclusive-baseline disclosure:** when the evidence gate cannot establish a diff baseline (`no_git_repo` / `no_run_start_sha`) it writes `.loki/state/evidence-inconclusive.json` and `COMPLETION.txt` carries an honest "not independently verified" line. It never blocks non-git projects; red tests still block.
 
+## Harness intelligence (v8.0.0)
+
+Four measured-harness disciplines layered onto the existing trust core. None of
+them can weaken a gate: each either adds verification or saves budget on work
+that cannot succeed.
+
+| Env Var | Default | Effect |
+|---------|---------|--------|
+| `LOKI_CONFIDENCE_SPIKE=0` | on | Disable the confidence-spike re-check |
+| `LOKI_CONFIDENCE_SPIKE_DELTA` | `40` | Confidence jump (points) that counts as a spike |
+| `LOKI_CONFIDENCE_SPIKE_MIN` | `90` | Absolute level that counts as a spike on first arrival |
+| `LOKI_GOAL_SCORING=0` | on | Disable the goal-measurability advisory |
+| `LOKI_SMART_RETRY=0` | on | Retry every failure, including non-retryable ones |
+
+- **Prompt-cache discipline.** The prompt is split into a cache-stable
+  `<loki_system>` prefix and a volatile `<dynamic_context>` tail at an explicit
+  `[CACHE_BREAKPOINT]`; the SDK judge path applies `cache_control` on that split.
+  Any new always-on instruction belongs in the prefix, or it busts the cache
+  every iteration.
+- **Confidence-spike re-check.** A jump to near-maximal self-reported confidence
+  forces ONE extra verification before the done-signal valve force-stops a run.
+  Strictly additive: a spike can only ADD a verification pass, never skip,
+  shorten, or satisfy a gate. It cannot delay the stagnation valve, and the
+  delay is one-shot, so a repeatedly-spiking run cannot postpone the valve
+  indefinitely.
+- **Hill-climbable goal scoring.** A `COMPLETION_PROMISE` with no measurable
+  target (no number, comparator, named metric, or verifiable artifact) gets a
+  prompt advisory asking for a checkable success condition. Advisory only: it
+  never blocks a build and never rewrites the goal. Suppressed for an absent
+  goal and in perpetual mode, where open-endedness is the chosen configuration.
+  Byte-mirrored across the bash and TypeScript routes.
+- **Smart retry.** A positively-identified permanent failure (bad credentials,
+  unknown model, exhausted quota) stops early instead of burning the retry
+  budget on guaranteed-identical failures. Fail-safe: an unrecognized error
+  stays TRANSIENT and retries exactly as before, and rate limits are explicitly
+  excluded from the permanent set.
+
+## Operational observability (v8.0.0)
+
+- **SDK capability-degradation event.** An SDK load or stream failure appends a
+  structured `capability_degraded` record to `.loki/events.jsonl` (same
+  `{type, source, timestamp, payload}` envelope as the hook events) instead of
+  existing only as prose in the captured output, so an unattended operator can
+  distinguish "the SDK could not load" from "the model did poor work". The
+  record states `fail_closed: true` rather than leaving it to be assumed. No env
+  var: this is signal an operator always wants.
+- **Time to first preview.** `.loki/app-runner/first-preview.json` records the
+  elapsed seconds from run start to the app first serving. Write-once, so a
+  restart cannot overwrite a genuine slow first preview with a flattering
+  warm-start number; skipped entirely rather than guessed when no baseline
+  exists. Bash route only (app-runner integration lives there).
+
 ## First-run UX (v7.29.0)
 
 - **`loki quickstart`:** guided 4-step first build (setup check, one-line idea, offline template match, plan review with real estimator figures); Enter-through-everything builds the sample Todo app; non-TTY/CI exits 2 with an automation hint.
@@ -389,6 +445,11 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 | Managed Agents (memory mirror) | v7.2.0 | Opt-in via `LOKI_MANAGED_AGENTS` -- see Managed Agents section |
 | Bun runtime (Phase 1) | v7.3.0 | Read-only commands routed through `bin/loki`; `LOKI_LEGACY_BASH=1` to revert |
 | Phase 1 RARV-C closure | v7.5.x | Findings injection, real judges, auto-learnings, handoff.md |
+| Anthropic SDK route | v8.0.0 | Opt-in, default-off; one switch `LOKI_SDK_MODE` -- see `references/sdk-mode.md` |
+| Harness intelligence | v8.0.0 | Prompt-cache discipline, confidence-spike re-check, goal scoring, smart retry |
+| SDK degradation event | v8.0.0 | Structured `capability_degraded` record on `.loki/events.jsonl` |
+| Time to first preview | v8.0.0 | `.loki/app-runner/first-preview.json`, write-once (bash route) |
+| Opt-in build analytics | v8.0.0 | `build_verified` event behind a strict second gate, allowlist-only fields |
 
 ## Planned / In-Progress Features
 
@@ -408,4 +469,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.129.5 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v8.0.1 | [Autonomi](https://www.autonomi.dev/) flagship product | ~410 lines core**

package/VERSION

@@ -1 +1 @@
-7.129.5
+8.0.1

package/autonomy/app-runner.sh

@@ -142,6 +142,43 @@ _write_health() {
 {"ok": ${ok}, "checked_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"}
 HEALTH_EOF
     mv "$tmp_file" "$_APP_RUNNER_DIR/health.json"
+
+    # TIME TO FIRST PREVIEW (write-once).
+    #
+    # The single number that most predicts whether someone keeps using a
+    # spec-to-product builder is how long they wait before seeing their app
+    # actually running. Everything else -- gates, councils, receipts -- is
+    # invisible until there is something on screen. We had `started_at` (when
+    # the runner launched the app) and `checked_at` (when a probe ran), but no
+    # anchor to the START OF THE RUN, so the number a user actually feels
+    # could not be derived from what we stored.
+    #
+    # Recorded ONLY on the first transition to healthy: the elapsed seconds
+    # from run start to the app first serving. Write-once by the -f guard, so
+    # a later restart cannot overwrite the genuine first-preview time with a
+    # warm-start number that flatters the metric.
+    #
+    # Baseline is the runner's EXISTING _LOKI_RUN_START_EPOCH (exported at
+    # run.sh:20014) -- deliberately reusing it rather than adding a second
+    # start-time variable that could drift out of agreement with the first.
+    # Absent (a direct app-runner call outside a run), this is skipped entirely
+    # rather than guessed: a fabricated baseline is worse than no measurement.
+    if [ "$ok" = "true" ] \
+       && [ ! -f "$_APP_RUNNER_DIR/first-preview.json" ] \
+       && [ -n "${_LOKI_RUN_START_EPOCH:-}" ]; then
+        local _now_epoch _elapsed
+        _now_epoch="$(date +%s 2>/dev/null || echo 0)"
+        _elapsed=$(( _now_epoch - _LOKI_RUN_START_EPOCH ))
+        # Negative or absurd values mean a bad baseline (clock change, stale
+        # export). Record nothing rather than a number nobody can trust.
+        if [ "$_elapsed" -ge 0 ] && [ "$_elapsed" -lt 86400 ]; then
+            local _fp_tmp="$_APP_RUNNER_DIR/first-preview.json.tmp.$$"
+            cat > "$_fp_tmp" << FIRSTPREVIEW_EOF
+{"seconds_to_first_preview": ${_elapsed}, "at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"}
+FIRSTPREVIEW_EOF
+            mv "$_fp_tmp" "$_APP_RUNNER_DIR/first-preview.json" 2>/dev/null || rm -f "$_fp_tmp"
+        fi
+    fi
 }
 
 # L5 fix (PID-file reuse race): capture a disambiguating identity token for a