@animalabs/connectome-host 0.7.3 → 0.8.0

package/CONTRIBUTING.md

@@ -43,7 +43,7 @@ plus, when applicable, **Not verified**, **Out of scope**, and
 - **Tests accompany behavior changes.** Review scrutinizes test substance,
   not mere presence — a test that can't fail on the unfixed code will be
   called out.
-- **Changelog entry** under `## Unreleased` for anything behavior-affecting
+- **Changelog fragment** in `changelog.d/` for anything behavior-affecting
   (see below).
 
 Conventional-commit-style titles (`feat(recipe): …`, `fix(subagent): …`) are
@@ -80,33 +80,61 @@ that don't fail on unfixed code, or with claims the branch itself disproves.
 
 ## Changelog
 
-`CHANGELOG.md` keeps a standing `## Unreleased` section with
-`### Breaking` / `### Added` / `### Changed` / `### Fixed` subsections
-(loosely [Keep a Changelog](https://keepachangelog.com/)).
-
-- **The entry lands with the change** — same commit, or at least the same
+Changelog entries land as **fragment files** in
+[`changelog.d/`](changelog.d/) — one file per change — and are folded into
+`CHANGELOG.md` (loosely [Keep a Changelog](https://keepachangelog.com/)) at
+release time. One file per change is what keeps concurrent work from
+conflicting: when every PR edited the same `## Unreleased` section, any PR
+that outlived another merge hit a conflict in `CHANGELOG.md`; distinct files
+never do.
+
+- **Format:** `changelog.d/<slug>.<breaking|added|changed|fixed>.md`, a flat
+  file directly in `changelog.d/`, containing one or more markdown bullets
+  (`- …`) written exactly as they should appear in `CHANGELOG.md`:
+  continuation lines indent two spaces, nested bullets are fine, headings
+  and horizontal rules are refused (even indented — a heading inside a
+  fragment would corrupt the section structure). The slug just has to be
+  unique among pending fragments and filesystem-safe — the PR number works,
+  and so does the branch name with `/` replaced by `-`
+  (`100-prose-routing.added.md`, `fix-retry-backoff.fixed.md`). The release
+  script scans the directory fail-closed: a subdirectory, an unrecognized
+  category suffix, or any other stray file aborts the release rather than
+  silently stranding an entry.
+
+- **The fragment lands with the change** — same commit, or at least the same
   PR. This binds direct pushes to `main` just as much as PRs. On PRs, CI
-  enforces it softly: touching `src/` without touching `CHANGELOG.md` fails
-  the `changelog` check unless the `no-changelog` label is applied.
+  enforces it softly: touching `src/` without adding a fragment (or editing
+  `CHANGELOG.md`) fails the `changelog` check unless the `no-changelog`
+  label is applied.
 - **What needs an entry:** anything an operator, recipe author, or module
   developer would notice — behavior, config/recipe schema, CLI, tool
   surfaces, defaults. Internal refactors, test-only, and docs-only changes
   don't.
-- **Breaking entries are audience-scoped.** Name the audience in the heading
-  (`### Breaking (recipe authors only)`) and cover: **who needs to act**,
+- **Breaking entries are audience-scoped.** Open the bullet by naming who
+  needs to act (`- **Recipe authors:** …`) and cover: **who needs to act**,
   **migration**, and **unchanged** (what readers might fear broke but
   didn't). The fleet recipe-path entry in `CHANGELOG.md` is the canonical
   example of the format.
+- **Editing `## Unreleased` in `CHANGELOG.md` directly still works** and is
+  merged with the fragments at release time — it remains the right place to
+  restructure pending entries, and the escape hatch for anything the
+  fragment format can't express (e.g. an audience-qualified
+  `### Breaking (recipe authors only)` heading, which `breaking` fragments
+  will then join). Keep one `## Unreleased` heading — the release script
+  refuses more than one, since only the first is ever cut.
 - **Releases** (maintainers): `npm version <patch|minor|major>` does the
-  whole cut — the `version` hook retitles `Unreleased` to
-  `## X.Y.Z — YYYY-MM-DD` (keeping a fresh `Unreleased` above it, and
-  refusing to release when there are no entries), then npm commits and tags.
-  `git push --follow-tags` triggers CI, which refuses a tag with no matching
-  changelog section, publishes `@animalabs/connectome-host` to npm, and
-  creates the GitHub release with that section as its notes. The two release
-  jobs are independent: some consumers run github-clone checkouts, so
-  release notes must exist even when npm publish fails. Version bumps are a
-  maintainer release-time action, not part of feature PRs.
+  whole cut — the `version` hook folds the pending fragments plus any
+  entries filed directly under `Unreleased` into `## X.Y.Z — YYYY-MM-DD`
+  (subsections emitted in `### Breaking` / `### Added` / `### Changed` /
+  `### Fixed` order), deletes the consumed fragments, keeps a fresh empty
+  `Unreleased` above, and refuses to release when there is nothing to
+  release; npm then commits and tags. `git push --follow-tags` triggers CI,
+  which refuses a tag with no matching changelog section, publishes
+  `@animalabs/connectome-host` to npm, and creates the GitHub release with
+  that section as its notes. The two release jobs are independent: some
+  consumers run github-clone checkouts, so release notes must exist even
+  when npm publish fails. Version bumps are a maintainer release-time
+  action, not part of feature PRs.
 
 ## Building and testing
 

package/HEADLESS-FLEET-PLAN.md

@@ -223,12 +223,34 @@ One JSON object per line. All events include `type`; most include `ts` (epoch ms
 {"type":"text","content":"Please resummarize last week"}
 {"type":"command","command":"/status"}
 {"type":"shutdown","graceful":true}
+{"type":"panel-request","op":"settings","params":{"agent":"clerk"},"corrId":"panel-1"}
 ```
 
 - `subscribe` is idempotent. Typically sent once right after connection. Supports simple glob (`tool:*`, `inference:*`).
 - `text` produces an `external-message` event with `source: 'headless'` — same effect as user typing into the child's own TUI.
 - `command` routes through the child's `commands.ts` handler exactly as if typed locally.
 - `shutdown` sets `graceful`; child completes in-flight inference, then exits. `graceful: false` is equivalent to SIGTERM.
+- `panel-request` runs one operator-panel operation in the child via the shared
+  `runPanelOp` dispatcher (`src/web/panel-data.ts`) — the same code the WebUI
+  host runs for its own process, so parent and child views of any panel can
+  never drift. Ops: `mcpl`, `settings`, `settings-update`, `settings-reset`,
+  `settings-cancel-transition`, `pins`, `pin-add`, `pin-remove`, `health`,
+  `context-makeup`, `context-coverage`, `context-curve`, `context-preview`,
+  `context-maintenance`, `debug-context`. The child answers with a single
+  `panel-response`:
+
+  ```json
+  {"type":"panel-response","op":"settings","corrId":"panel-1","ok":true,"data":{...}}
+  {"type":"panel-response","op":"settings","corrId":"panel-1","ok":false,"error":"Agent not found: x","status":404}
+  ```
+
+  `status` is HTTP-ish so the parent's `?scope=<child>` proxy routes
+  (`/debug/context/*`, `/healthz`) can answer faithfully. `panel-response`
+  (like the other request/response snapshots) bypasses the subscription
+  filter. Parent-side, `FleetModule.requestPanel()` wraps the corrId
+  bookkeeping in a promise and never rejects — unreachable children resolve
+  `{ok:false,status:502}`, silence resolves `{ok:false,status:504}` after the
+  timeout (default 30s).
 
 ### Connection lifecycle
 

package/README.md

@@ -118,16 +118,52 @@ device-code flow if needed. No `OPENAI_API_KEY` is used for this provider. Use
 warns if the service reports that it fell back to Standard; Fast mode consumes
 subscription credits at a higher rate when applied.
 
+### OpenAI-compatible endpoints (Ollama, vLLM, Together, Groq, NanoGPT, ...)
+
+Any server speaking the OpenAI chat-completions API works through the generic
+`openai-compatible` provider — the recipe names the endpoint and the model:
+
+```json
+{
+  "agent": {
+    "provider": "openai-compatible",
+    "baseUrl": "http://localhost:11434/v1",
+    "model": "qwen3:32b",
+    "systemPrompt": "You are a helpful assistant."
+  }
+}
+```
+
+The API key is read from `OPENAI_COMPATIBLE_API_KEY` only — deliberately no
+`OPENAI_API_KEY` fallback: `baseUrl` is recipe-controlled, and a real OpenAI
+credential must never be sent silently to an arbitrary endpoint. Local
+servers usually need none. `agent.model` is required —
+there is no default model for an arbitrary endpoint. Tool calls use the
+standard `tool_calls` format, so the endpoint must support function calling
+for tool-using recipes. Provider-side prompt caching and cache accounting
+depend on what the endpoint reports.
+
 ## What it provides
 
 - **Web UI**: browser operator console (`modules.webui`) — live chat with full interiority (thinking, tool calls, streaming), agent/fleet tree, context makeup + compression coverage, call ledger with cache verdicts and billing-grade costs, health/ops alerts, Chronicle branch tree, lessons, MCPL config, workspace files; scoped read-only observer access via device keys
 - **TUI + readline modes**: OpenTUI interactive terminal or `--no-tui` for pipes/CI
 - **Subagent forking** (opt-in, `modules.subagents`): Spawn/fork parallel agents with fleet tree view (Tab to toggle)
-- **Persistent lessons** (opt-in, `modules.lessons`): Knowledge store with confidence scores and tags. Automatic retrieval-injection of lessons into context (`modules.retrieval`) is a separate opt-in — it adds per-turn context churn and Haiku calls, so enable it only for agents that actually curate a lesson library
+- **Persistent lessons** (opt-in, `modules.lessons`): Knowledge store with confidence scores and tags. Automatic retrieval-injection of lessons into context (`modules.retrieval`) is a separate opt-in — it adds per-turn context churn and retrieval-model calls, so enable it only for agents that actually curate a lesson library
 - **Time-travel**: Chronicle-backed undo/redo, named checkpoints, branch exploration
 - **Session management**: Isolated sessions with auto-naming
 - **MCPL support**: Connect any MCP/MCPL server; wake subscriptions for selective event triggering
 - **File products**: Write reports and documents, materialize to disk
+- **Shared instructions** (opt-in, `modules.instructions`): a living instructions document (CLAUDE.md analogue) kept in a workspace mount and injected into every agent's context on every turn — the resident agent and all ephemeral subagents. Edits take effect on the next turn; nothing is persisted to history. Defaults: path `instructions/AGENTS.md`, `position: "system"`, 32 KiB cap (reads are bounded to the cap); a missing file is fail-open (no injection, warn once), while a path naming a nonexistent mount fails at recipe load — including on the implicit default workspace (`input` + `products`), whose mount set can never satisfy the default path, so declare an `instructions` mount explicitly. **Who edits, and how it propagates**: the module reads *disk*; agent `workspace--write`/`edit` land in Chronicle and reach disk only on an `autoMaterialize: true` mount — validation therefore requires it on a read-write instructions mount. On a read-only mount the flow reverses: human/deploy edits to disk reach the injection, but not `workspace--read` (which serves Chronicle) — prefer routing human feedback through conversation and letting the agent make the edit. Symlinks that lead outside the mount are rejected (realpath containment), never injected. **Cache note**: at `position: "system"` the block lives in every agent's prompt-cache prefix, so each edit is a fleet-wide cache cold start on the next turn — curate in batches, or use `afterUser` for cache-cheap, lower-salience injection. Compared to **lessons** (`modules.lessons`): lessons are a structured, confidence-scored store with model-driven retrieval; instructions are one free-form curated document, always present verbatim
+
+For `openai-responses` and `openai-codex`, an object-valued
+`modules.retrieval` can set `reasoningEffort` (`none`, `minimal`, `low`,
+`medium`, `high`, `xhigh`, or `max`) independently of the primary agent.
+Retrieval calls are independent one-shot requests, so there is no separate
+retrieval reasoning-context setting. When `reasoningEffort` is configured,
+`model` must also be set explicitly: the historical retrieval default is a
+Claude model and cannot be sent through an OpenAI adapter. Anthropic/Claude
+uses different native thinking controls and does not accept this OpenAI-shaped
+option.
 
 ## Prerequisites
 
@@ -146,6 +182,7 @@ npm install
 |----------|---------|-------------|
 | `ANTHROPIC_API_KEY` | (required) | Anthropic API key |
 | `OPENAI_API_KEY` | — | OpenAI Platform key for `openai-responses` recipes |
+| `OPENAI_COMPATIBLE_API_KEY` | — | Key for `openai-compatible` recipes (no `OPENAI_API_KEY` fallback by design); omit for local servers |
 | `CODEX_BINARY` | `codex` | Codex CLI executable for `openai-codex` subscription auth |
 | `CODEX_HOME` | `~/.codex` | Codex credential/config directory |
 | `CODEX_BASE_URL` | ChatGPT Codex backend | Optional subscription transport override |
@@ -175,6 +212,7 @@ non-loopback binds require basic-auth credentials. Build the SPA bundle once wit
 - Ops alerts (compression quarantine, refusal streaks, inference-exhausted) render as persistent banner rows
 - Usage panel: per-agent costs and a billing-grade call ledger with cache verdicts
 - `/curve` — compression-curve visualization; `/healthz` — liveness JSON for doctor/fleet tooling
+- `/debug/retrieval/view` — operator-only per-run lesson selection viewer (see `docs/retrieval-traces.md`)
 - Read-only observer access via Ed25519 device keys with per-grant scopes (see `docs/webui-deployment.md`)
 
 For SPA development: `cd web && bun run dev` proxies the Vite dev server onto a

package/bun.lock

@@ -1,14 +1,14 @@
 {
   "lockfileVersion": 1,
-  "configVersion": 1,
+  "configVersion": 0,
   "workspaces": {
     "": {
-      "name": "connectome-host",
+      "name": "@animalabs/connectome-host",
       "dependencies": {
-        "@animalabs/agent-framework": "^0.7.0",
-        "@animalabs/chronicle": "^0.2.0",
-        "@animalabs/context-manager": "^0.6.0",
-        "@animalabs/membrane": "^0.5.75",
+        "@animalabs/agent-framework": "^0.12.0",
+        "@animalabs/chronicle": "^0.3.0",
+        "@animalabs/context-manager": "^0.6.3",
+        "@animalabs/membrane": "^0.5.82",
         "@opentui/core": "^0.1.82",
       },
       "devDependencies": {
@@ -19,13 +19,13 @@
     },
   },
   "packages": {
-    "@animalabs/agent-framework": ["@animalabs/agent-framework@0.7.0", "", { "dependencies": { "@animalabs/chronicle": "^0.2.2", "@animalabs/context-manager": "^0.6.0", "@animalabs/membrane": "^0.5.75", "chokidar": "^4.0.3", "discord.js": "^14.25.1", "ws": "^8.18.0" }, "bin": { "agent-framework-mcp": "dist/src/api/mcp-server.js", "agent-framework-recover": "dist/src/recovery/recover-cli.js" } }, "sha512-9FRQsCPaCZuZe0pyj+xq2NvdbSWQxRvdgO8nojVezpysaJL+w/Ba9tahGaOK7ZP12ZqnX3Q88wlttsXY+A47Gw=="],
+    "@animalabs/agent-framework": ["@animalabs/agent-framework@0.12.0", "", { "dependencies": { "@animalabs/chronicle": "^0.3.0", "@animalabs/context-manager": "^0.6.0", "@animalabs/membrane": "^0.5.78", "chokidar": "^4.0.3", "discord.js": "^14.25.1", "ws": "^8.18.0" }, "bin": { "agent-framework-mcp": "dist/src/api/mcp-server.js", "agent-framework-recover": "dist/src/recovery/recover-cli.js" } }, "sha512-Yj0E4vA+kqMxp8LzVT1DBBppwBtPaaweOCloO47pAbJemLzLsJoCD1O9GOYjZ75LLfvGenzLgg1fWo0wXkMJ1w=="],
 
-    "@animalabs/chronicle": ["@animalabs/chronicle@0.2.1", "", { "optionalDependencies": { "@animalabs/chronicle-darwin-arm64": "0.2.1", "@animalabs/chronicle-darwin-x64": "0.2.1", "@animalabs/chronicle-linux-arm64-gnu": "0.2.1", "@animalabs/chronicle-linux-x64-gnu": "0.2.1", "@animalabs/chronicle-win32-x64-msvc": "0.2.1" } }, "sha512-rDFc069yfi7BQUusgsXBwBdqljUWLByXSYaTF40AP+tonBh0No3eF9VzKTSy1I8DYg/jAUHIKtVdKDGsVMVubw=="],
+    "@animalabs/chronicle": ["@animalabs/chronicle@0.3.0", "", {}, "sha512-6BBJ9pWb8AnuHTNJTU07Y6Wut3IvdgWFxsy05IdlWcEnR5W23dlaBlaeJq7gDc7TwX05HfsDC+QZFEc69G+s4Q=="],
 
-    "@animalabs/context-manager": ["@animalabs/context-manager@0.6.0", "", { "dependencies": { "@animalabs/chronicle": "^0.2.6", "@animalabs/membrane": "^0.5.69" } }, "sha512-X8PKvHouS0dXt6faHeMyI2FehgyFKPT3vBaqM7QN6o/O/3I5pU8UX+WR1nsixfgw+la83lDC+OHn+lPe1A7DVg=="],
+    "@animalabs/context-manager": ["@animalabs/context-manager@0.6.3", "", { "dependencies": { "@animalabs/chronicle": "^0.3.0", "@animalabs/membrane": "^0.5.69" } }, "sha512-zh60LgZxXzBbGrLpDHBAfGSPSL/H8mxz8nSWLOSh4pjiTOYbD0o0BjAM8CFz4LiaOIXnuSCbRoiv5UKsnrKwDw=="],
 
-    "@animalabs/membrane": ["@animalabs/membrane@0.5.75", "", { "dependencies": { "@anthropic-ai/sdk": "^0.52.0" } }, "sha512-eWtkrbQQga8UWDMH4VzPfZzcwYQLwngUcQ2tMeuERMBJ6WkXQzSJkcQVjM3ZvexvytnLsFTMOATvT58Igl9JuA=="],
+    "@animalabs/membrane": ["@animalabs/membrane@0.5.82", "", { "dependencies": { "@anthropic-ai/sdk": "^0.52.0" } }, "sha512-kCI3s/HXnXBPVcYCXIZfsdJBLRj77j5QyA9Hor1mC/nyD35D7e7N/VgR9awxqdGGWgIvgpjs6owXbGMk5t1pQA=="],
 
     "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.52.0", "", { "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-d4c+fg+xy9e46c8+YnrrgIQR45CZlAi7PwdzIfDXDM6ACxEZli1/fxhURsq30ZpMZy6LvSkr41jGq5aF5TD7rQ=="],
 
@@ -37,7 +37,7 @@
 
     "@discordjs/formatters": ["@discordjs/formatters@0.6.2", "", { "dependencies": { "discord-api-types": "^0.38.33" } }, "sha512-y4UPwWhH6vChKRkGdMB4odasUbHOUwy7KL+OVwF86PvT6QVOwElx+TiI1/6kcmcEe+g5YRXJFiXSXUdabqZOvQ=="],
 
-    "@discordjs/rest": ["@discordjs/rest@2.6.1", "", { "dependencies": { "@discordjs/collection": "^2.1.1", "@discordjs/util": "^1.2.0", "@sapphire/async-queue": "^1.5.3", "@sapphire/snowflake": "^3.5.5", "@vladfrangu/async_event_emitter": "^2.4.6", "discord-api-types": "^0.38.40", "magic-bytes.js": "^1.13.0", "tslib": "^2.6.3", "undici": "6.24.1" } }, "sha512-wwQdgjeaoYFiaG+atbqx6aJDpqW7JHAo0HrQkBTbYzM3/PJ3GweQIpgElNcGZ26DCUOXMyawYd0YF7vtr+fZXg=="],
+    "@discordjs/rest": ["@discordjs/rest@2.6.3", "", { "dependencies": { "@discordjs/collection": "^2.1.1", "@discordjs/util": "^1.2.0", "@sapphire/async-queue": "^1.5.3", "@sapphire/snowflake": "^3.5.5", "@vladfrangu/async_event_emitter": "^2.4.6", "discord-api-types": "^0.38.50", "magic-bytes.js": "^1.13.0", "tslib": "^2.6.3", "undici": "^6.27.0" } }, "sha512-wvOylxNYJkwKjctS/Mn5GP1w9r3/rzyH+ThD1JlAca6zEdlHs8QWBBUQJpU5Q+W6DoIj/Ljh1IPlZs7hTU+UAg=="],
 
     "@discordjs/util": ["@discordjs/util@1.2.0", "", { "dependencies": { "discord-api-types": "^0.38.33" } }, "sha512-3LKP7F2+atl9vJFhaBjn4nOaSWahZ/yWjOvA4e5pnXkt2qyXRCHLxoBQy81GFtLGCq7K9lPm9R517M1U+/90Qg=="],
 
@@ -117,23 +117,23 @@
 
     "@sapphire/shapeshift": ["@sapphire/shapeshift@4.0.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "lodash": "^4.17.21" } }, "sha512-d9dUmWVA7MMiKobL3VpLF8P2aeanRTu6ypG2OIaEv/ZHH/SUQ2iHOVyi5wAPjQ+HmnMuL0whK9ez8I/raWbtIg=="],
 
-    "@sapphire/snowflake": ["@sapphire/snowflake@3.5.3", "", {}, "sha512-jjmJywLAFoWeBi1W7994zZyiNWPIiqRRNAmSERxyg93xRGzNYvGjlZ0gR6x0F4gPRi2+0O6S71kOZYyr3cxaIQ=="],
+    "@sapphire/snowflake": ["@sapphire/snowflake@3.5.5", "", {}, "sha512-xzvBr1Q1c4lCe7i6sRnrofxeO1QTP/LKQ6A6qy0iB4x5yfiSfARMEQEghojzTNALDTcv8En04qYNIco9/K9eZQ=="],
 
     "@tokenizer/token": ["@tokenizer/token@0.3.0", "", {}, "sha512-OvjF+z51L3ov0OyAU0duzsYuvO01PH7x4t6DJx+guahgTnBHkhJdG7soQeTSFLWN3efnHyibZ4Z8l2EuWwJN3A=="],
 
     "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
 
-    "@types/node": ["@types/node@22.19.19", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-dyh/xO2Fh5bYrfWaaqGrRQQGkNdmYw6AmaAUvYeUMNTWQtvb796ikLdmTchRmOlOiIJ1TDXfWgVx1QkUlQ6Hew=="],
+    "@types/node": ["@types/node@22.20.1", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-EANqOCF9QFyra+4pfxUcX9STKJpCLjMbObVzljIJomAWSnuSIEAvyzEU53GaajbXJEgdh0iEcPL+DGvpUd4k1Q=="],
 
     "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
 
     "@vladfrangu/async_event_emitter": ["@vladfrangu/async_event_emitter@2.4.7", "", {}, "sha512-Xfe6rpCTxSxfbswi/W/Pz7zp1WWSNn4A0eW4mLkQUewCrXXtMj31lCg+iQyTkh/CkusZSq9eDflu7tjEDXUY6g=="],
 
-    "@webgpu/types": ["@webgpu/types@0.1.70", "", {}, "sha512-LFiNHHKMvmAEvwVew3JLJmTdShhbdwRFSImUshGhE2mGE8ybQzIo63l5uRp+YKnNx+8Qno8Kf6gN+DKMreIJCA=="],
+    "@webgpu/types": ["@webgpu/types@0.1.71", "", {}, "sha512-mMy8/ODcKhab808co15eW+yN+HgXoQxRQHTiBV9Mrvl1r0ufnid7YOcI+gi4eUWSWl9ezD6TW2KXccrL8HCh2A=="],
 
     "abort-controller": ["abort-controller@3.0.0", "", { "dependencies": { "event-target-shim": "^5.0.0" } }, "sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg=="],
 
-    "ansi-regex": ["ansi-regex@6.2.2", "", {}, "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg=="],
+    "ansi-regex": ["ansi-regex@6.3.0", "", {}, "sha512-WpDfL7NO6j7tH88IDBNVdUJxDh9nmCteAVW9dsep846XdwF4naCBK+/tGLX3KJgcpgMRXCFlTM2hKGoK9FsdrQ=="],
 
     "any-base": ["any-base@1.1.0", "", {}, "sha512-uMgjozySS8adZZYePpaWs8cxB9/kdzmpX6SgJZ+wbz1K5eYk5QMYDVJaZKhxyIHUdnnJkfR7SVgStgH7LkGUyg=="],
 
@@ -163,9 +163,9 @@
 
     "diff": ["diff@8.0.2", "", {}, "sha512-sSuxWU5j5SR9QQji/o2qMvqRNYRDOcBTgsJ/DeCf4iSN4gW+gNMXM7wFIP+fdXZxoNiAnHUTGjCr+TSWXdRDKg=="],
 
-    "discord-api-types": ["discord-api-types@0.38.48", "", {}, "sha512-WFUE/2o0lBlLeCQonQ+Pu2RqHAqbytBJ2RlXR91gzk05InSS6k9ShzzLYoymrA4c2oRgRKGE7/VqQJNNdGWSxQ=="],
+    "discord-api-types": ["discord-api-types@0.38.53", "", {}, "sha512-HL1zz/UuZ+bbJjA/X8Kbxx9gk8v9rJAbTeWRNYKmIdjwJ7EovjlHgoJTxcLpATfNJ+AonOtMdy3Y5MVIJAAd/A=="],
 
-    "discord.js": ["discord.js@14.26.4", "", { "dependencies": { "@discordjs/builders": "^1.14.1", "@discordjs/collection": "1.5.3", "@discordjs/formatters": "^0.6.2", "@discordjs/rest": "^2.6.1", "@discordjs/util": "^1.2.0", "@discordjs/ws": "^1.2.3", "@sapphire/snowflake": "3.5.3", "discord-api-types": "^0.38.40", "fast-deep-equal": "3.1.3", "lodash.snakecase": "4.1.1", "magic-bytes.js": "^1.13.0", "tslib": "^2.6.3", "undici": "6.24.1" } }, "sha512-4oBp8tc6Kf8IDBwAHhbsMaAqx1b5fob9SNasZT7V6yyyUydoO5i5fGuX7TmvRtR+q/WgKRnRViRoAWnG7fNyvA=="],
+    "discord.js": ["discord.js@14.27.0", "", { "dependencies": { "@discordjs/builders": "^1.14.1", "@discordjs/collection": "1.5.3", "@discordjs/formatters": "^0.6.2", "@discordjs/rest": "^2.6.2", "@discordjs/util": "^1.2.0", "@discordjs/ws": "^1.2.3", "@sapphire/snowflake": "3.5.5", "discord-api-types": "^0.38.49", "fast-deep-equal": "3.1.3", "lodash.snakecase": "4.1.1", "magic-bytes.js": "^1.13.0", "tslib": "^2.6.3", "undici": "^6.27.0" } }, "sha512-qHbFlFG2N7y3LjPySYsL6A1+BnX6bkTVgo842EX0CqVPk/KTMwZkojPHEXKsQUpWZNyz5BISNHK1cPpQw0+m4A=="],
 
     "emoji-regex": ["emoji-regex@10.6.0", "", {}, "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A=="],
 
@@ -195,11 +195,11 @@
 
     "lodash.snakecase": ["lodash.snakecase@4.1.1", "", {}, "sha512-QZ1d4xoBHYUeuouhEq3lk3Uq7ldgyFXGBhg04+oRLnIz8o9T65Eh+8YdroUwn846zchkA9yDsDl5CVVaV2nqYw=="],
 
-    "magic-bytes.js": ["magic-bytes.js@1.13.0", "", {}, "sha512-afO2mnxW7GDTXMm5/AoN1WuOcdoKhtgXjIvHmobqTD1grNplhGdv3PFOyjCVmrnOZBIT/gD/koDKpYG+0mvHcg=="],
+    "magic-bytes.js": ["magic-bytes.js@1.13.1", "", {}, "sha512-x5sn4UX2k5gCWlcfmoFwG4TPie8+dctESyqOBdhB5p6MsgWXdBKGmt9nXPObj/JI50TTL928lc5Yt1WntMn1bw=="],
 
-    "marked": ["marked@17.0.1", "", { "bin": { "marked": "bin/marked.js" } }, "sha512-boeBdiS0ghpWcSwoNm/jJBwdpFaMnZWRzjA6SkUMYb40SVaN1x7mmfGKp0jvexGcx+7y2La5zRZsYFZI6Qpypg=="],
+    "marked": ["marked@17.0.1", "", { "bin": "bin/marked.js" }, "sha512-boeBdiS0ghpWcSwoNm/jJBwdpFaMnZWRzjA6SkUMYb40SVaN1x7mmfGKp0jvexGcx+7y2La5zRZsYFZI6Qpypg=="],
 
-    "mime": ["mime@3.0.0", "", { "bin": { "mime": "cli.js" } }, "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A=="],
+    "mime": ["mime@3.0.0", "", { "bin": "cli.js" }, "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A=="],
 
     "omggif": ["omggif@1.0.10", "", {}, "sha512-LMJTtvgc/nugXj0Vcrrs68Mn2D1r0zf630VNtqtpI1FEO7e+O9FP4gqs9AcnBaSEeoHIPm28u6qgPR0oyEpGSw=="],
 
@@ -213,9 +213,9 @@
 
     "peek-readable": ["peek-readable@4.1.0", "", {}, "sha512-ZI3LnwUv5nOGbQzD9c2iDG6toheuXSZP5esSHBjopsXH4dg19soufvpUGA3uohi5anFtGb2lhAVdHzH6R/Evvg=="],
 
-    "pixelmatch": ["pixelmatch@5.3.0", "", { "dependencies": { "pngjs": "^6.0.0" }, "bin": { "pixelmatch": "bin/pixelmatch" } }, "sha512-o8mkY4E/+LNUf6LzX96ht6k6CEDi65k9G2rjMtBe9Oo+VPKSvl+0GKHuH/AlG+GA5LPG/i5hrekkxUc3s2HU+Q=="],
+    "pixelmatch": ["pixelmatch@5.3.0", "", { "dependencies": { "pngjs": "^6.0.0" }, "bin": "bin/pixelmatch" }, "sha512-o8mkY4E/+LNUf6LzX96ht6k6CEDi65k9G2rjMtBe9Oo+VPKSvl+0GKHuH/AlG+GA5LPG/i5hrekkxUc3s2HU+Q=="],
 
-    "planck": ["planck@1.5.0", "", { "peerDependencies": { "stage-js": "^1.0.0-alpha.12" } }, "sha512-dlvqJE+FscZgrGUXJ5ybd0o5bvZ5XXyZNbm08xGsXp9WjXeAyWSFT6n9s/1PQcUBo4546fDXA5RMA4wbDyZw6g=="],
+    "planck": ["planck@1.4.2", "", { "peerDependencies": { "stage-js": "^1.0.0-alpha.12" } }, "sha512-mNbhnV3g8X2rwGxzcesjmN8BDA6qfXgQxXVMkWau9MCRlQY0RLNEkyHlVp6yFy/X6qrzAXyNONCnZ1cGDLrNew=="],
 
     "pngjs": ["pngjs@7.0.0", "", {}, "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow=="],
 
@@ -229,11 +229,11 @@
 
     "safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
 
-    "sax": ["sax@1.6.0", "", {}, "sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA=="],
+    "sax": ["sax@1.6.1", "", {}, "sha512-42tBVwLWnaQvW5zc4HbZrTuWccECCZfBi92FDuwtqxasH+JbPB3/FOKb1m222K42R4WxuxzzMsTswfzgtSu64Q=="],
 
     "simple-xml-to-json": ["simple-xml-to-json@1.2.7", "", {}, "sha512-mz9VXphOxQWX3eQ/uXCtm6upltoN0DLx8Zb5T4TFC4FHB7S9FDPGre8CfLWqPWQQH/GrQYd2AXhhVM5LDpYx6Q=="],
 
-    "stage-js": ["stage-js@1.0.2", "", {}, "sha512-EWTRBYlg7Qv9wGUao99/PfRe3KaiQqWmgSvTOXvaWnu1Jk/q/vV8yJVu6bi/3EqDZeMVnCPAjheba6OFc5k1GQ=="],
+    "stage-js": ["stage-js@1.0.1", "", {}, "sha512-cz14aPp/wY0s3bkb/B93BPP5ZAEhgBbRmAT3CCDqert8eCAqIpQ0RB2zpK8Ksxf+Pisl5oTzvPHtL4CVzzeHcw=="],
 
     "string-width": ["string-width@7.2.0", "", { "dependencies": { "emoji-regex": "^10.3.0", "get-east-asian-width": "^1.0.0", "strip-ansi": "^7.1.0" } }, "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ=="],
 
@@ -255,7 +255,7 @@
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
-    "undici": ["undici@6.24.1", "", {}, "sha512-sC+b0tB1whOCzbtlx20fx3WgCXwkW627p4EA9uM+/tNNPkSS+eSEld6pAs9nDv7WbY1UUljBMYPtu9BCOrCWKA=="],
+    "undici": ["undici@6.28.0", "", {}, "sha512-LIY910g9TI13YS95lrMFrs8Rm/u/irgHeTWoKCoteeJ04CUJ92eEfj0rVn+7VKMPBpUPiUoBKfhNyLI23EE/KA=="],
 
     "undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
 
@@ -263,7 +263,7 @@
 
     "web-tree-sitter": ["web-tree-sitter@0.25.10", "", { "peerDependencies": { "@types/emscripten": "^1.40.0" }, "optionalPeers": ["@types/emscripten"] }, "sha512-Y09sF44/13XvgVKgO2cNDw5rGk6s26MgoZPXLESvMXeefBf7i6/73eFurre0IsTW6E14Y0ArIzhUMmjoc7xyzA=="],
 
-    "ws": ["ws@8.21.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g=="],
+    "ws": ["ws@8.21.3", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw=="],
 
     "xml-parse-from-string": ["xml-parse-from-string@1.0.1", "", {}, "sha512-ErcKwJTF54uRzzNMXq2X5sMIy88zJvfN2DmdoQvy7PAFJ+tPRU6ydWuOKNMyfmOjdyBQTFREi60s0Y0SyI0G0g=="],
 
@@ -275,14 +275,10 @@
 
     "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
 
-    "@animalabs/agent-framework/@animalabs/chronicle": ["@animalabs/chronicle@0.2.6", "", { "optionalDependencies": { "@animalabs/chronicle-darwin-arm64": "0.2.6", "@animalabs/chronicle-darwin-x64": "0.2.6", "@animalabs/chronicle-linux-arm64-gnu": "0.2.6", "@animalabs/chronicle-linux-x64-gnu": "0.2.6", "@animalabs/chronicle-win32-x64-msvc": "0.2.6" } }, "sha512-+gbt2GR4SP8MnKxeqkJZf6oZn339fLiBtk6GHyBD/gHQ4e4eFqBpTaTd5eKycKBws0xWGcOqyiJFH4IdBkweUA=="],
-
-    "@animalabs/context-manager/@animalabs/chronicle": ["@animalabs/chronicle@0.2.6", "", { "optionalDependencies": { "@animalabs/chronicle-darwin-arm64": "0.2.6", "@animalabs/chronicle-darwin-x64": "0.2.6", "@animalabs/chronicle-linux-arm64-gnu": "0.2.6", "@animalabs/chronicle-linux-x64-gnu": "0.2.6", "@animalabs/chronicle-win32-x64-msvc": "0.2.6" } }, "sha512-+gbt2GR4SP8MnKxeqkJZf6oZn339fLiBtk6GHyBD/gHQ4e4eFqBpTaTd5eKycKBws0xWGcOqyiJFH4IdBkweUA=="],
+    "@animalabs/context-manager/@animalabs/membrane": ["@animalabs/membrane@0.5.80", "", { "dependencies": { "@anthropic-ai/sdk": "^0.52.0" } }, "sha512-D4xEij+J/3sJo2ZKFyjAeb0VuJl3QmygzEmi44J0nDNtmJSpUPYMJMaSid/ABj3dIs5EyXds/Ltr4qqyQ2DRTw=="],
 
     "@discordjs/rest/@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
 
-    "@discordjs/rest/@sapphire/snowflake": ["@sapphire/snowflake@3.5.5", "", {}, "sha512-xzvBr1Q1c4lCe7i6sRnrofxeO1QTP/LKQ6A6qy0iB4x5yfiSfARMEQEghojzTNALDTcv8En04qYNIco9/K9eZQ=="],
-
     "@discordjs/ws/@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
 
     "image-q/@types/node": ["@types/node@16.9.1", "", {}, "sha512-QpLcX9ZSsq3YYUUnD3nFDY8H7wctAhQj/TFKL8Ya8v5fMm3CFXxo8zStsLAl780ltoYoo1WvKUVGBQK+1ifr7g=="],

package/changelog.d/README.md

@@ -0,0 +1,28 @@
+# Pending changelog fragments
+
+One file per change, so concurrent branches never conflict the way shared
+`CHANGELOG.md` edits do. At release time `npm version` folds every fragment
+here into the new version section of `CHANGELOG.md` and deletes it.
+
+**Name:** `<slug>.<breaking|added|changed|fixed>.md`, as a flat file directly
+in this directory. The slug just has to be unique among pending fragments and
+filesystem-safe: the PR number works, and so does the branch name with `/`
+replaced by `-` (`100-prose-routing.added.md`, `fix-retry-backoff.fixed.md`). The
+release script refuses subdirectories and any other stray file here, so a
+misplaced entry fails the release loudly instead of being left out.
+
+**Content:** one or more markdown bullets, exactly as they should appear in
+`CHANGELOG.md`. Continuation lines indent two spaces (nested bullets are
+fine); headings and horizontal rules are refused even when indented, since a
+heading inside a fragment would corrupt the section structure:
+
+
+```markdown
+- Recipes accept `agent.proseRouting: "disabled"` for tool-only external
+  publication (#100). Continuation lines indent two spaces.
+```
+
+Breaking fragments open by naming who needs to act:
+`- **Recipe authors:** …`.
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md#changelog) for what needs an entry.

package/docs/AGENT-ONBOARDING.md

@@ -274,7 +274,7 @@ workloads whose cache is normally reused within five minutes.
 
 **`subagents`/`lessons`/`retrieval` are NOT part of the standard recipe.**
 All three are opt-in. RetrievalModule in particular injects context-dependent
-content into every compile (and spends two Haiku calls per turn), so it must
+content into every compile (and spends up to two configured retrieval-model calls), so it must
 be an explicit opt-in for agents that actually curate a lesson library.
 Current host code defaults all three to off, but keep the explicit `false`
 entries in the recipe anyway — older host checkouts treated these as opt-out,

package/docs/debug-context-api.md

@@ -75,8 +75,8 @@ The trade-off is fidelity: the default response **omits the dynamically
 gathered injections** (lessons, retrieval results, MCPL `beforeInference`
 context), because gathering those is *not* free or transparent:
 
-- module `gatherContext` can run inference — e.g. the retrieval module makes
-  Haiku calls, which cost tokens and add latency;
+- module `gatherContext` can run inference — e.g. the retrieval module makes configured model calls, which cost tokens and add
+  latency;
 - MCPL `beforeInference` hooks are arbitrary RPCs to external servers with
   side effects, and a preview never sends the paired `afterInference`, which
   can leave a stateful server half-open.

package/docs/retrieval-traces.md

@@ -0,0 +1,173 @@
+# Retrieval Traces
+
+The retrieval module can record a bounded, per-run explanation of automatic
+lesson selection. The trace shows which concepts the selector returned, which
+lessons matched mechanically, which candidates survived relevance filtering,
+and the exact lesson block injected into the next compile.
+
+Tracing is diagnostic. It does not change selection, trigger an extra model
+call, or claim access to hidden chain-of-thought.
+
+## Prerequisites
+
+Enable lessons, retrieval, and the Web UI in the recipe:
+
+```json
+{
+  "modules": {
+    "lessons": true,
+    "retrieval": {
+      "model": "gpt-5.4-mini",
+      "maxInjected": 5,
+      "reasoningEffort": "high"
+    },
+    "webui": {
+      "host": "127.0.0.1",
+      "port": 7340,
+      "basicAuth": {
+        "username": "${WEBUI_USER}",
+        "password": "${WEBUI_PASS}"
+      }
+    }
+  }
+}
+```
+
+`reasoningEffort` accepts `none`, `minimal`, `low`, `medium`, `high`, `xhigh`,
+or `max`. It is optional, applies to both retrieval calls, and does not inherit
+the primary agent's reasoning setting. This field is supported only when
+`agent.provider` is `openai-responses` or `openai-codex`; Anthropic/Claude uses
+separate native thinking controls and is rejected here rather than receiving an
+invalid OpenAI-shaped request.
+
+Retrieval remains opt-in and requires the lessons module. Depending on the
+candidate count, one turn can use one selector call plus an optional relevance
+call.
+
+## Operator viewer
+
+Open:
+
+```text
+http://127.0.0.1:7340/debug/retrieval/view
+```
+
+The viewer highlights selected lessons, lists all mechanically matched
+candidates and their match provenance, summarizes the relevance decision, and
+keeps the retained trace JSON behind a diagnostic disclosure. Each run is
+labeled with the invoking agent name. Separate Host processes retain separate
+trace stores and viewers; the endpoint does not aggregate fleet children.
+
+## JSON endpoint
+
+```text
+GET /debug/retrieval[?limit=20][&includeInputs=1]
+```
+
+| Parameter | Default | Meaning |
+|---|---:|---|
+| `limit` | `20` | Newest traces to return, clamped to `1..100`. |
+| `includeInputs` | off | Exact recent conversation and model-stage inputs are included only when the value is the literal `1`. |
+
+Example envelope:
+
+```json
+{
+  "schemaVersion": 1,
+  "enabled": true,
+  "includeInputs": false,
+  "traces": []
+}
+```
+
+Each trace can include:
+
+- configured model and request-level reasoning parameters;
+- recent-context hash, message count, and available message IDs;
+- selector prompt, raw returned text, normalized provider blocks, parsed
+  concepts, and parse mode;
+- every mechanical candidate, lesson snapshot, and content/tag match reason;
+- relevance-call output or the reason validation was skipped;
+- final relevant and injected lesson IDs, exact lesson snapshots, injection
+  namespace/position, and rendered `## Retrieved Knowledge` block;
+- cache-hit provenance, outcome, duration, and errors.
+
+Opaque or redacted reasoning blocks are retained only as provider-returned
+content blocks. The trace does not decrypt them or present them as hidden
+chain-of-thought. Each lesson snapshot is a point-in-time copy of every
+`Lesson` field: `id`, `content`, `confidence`, `tags`, `evidence`, `created`,
+`updated`, `deprecated`, and optional `deprecationReason`.
+
+If retrieval is disabled, the endpoint returns `enabled: false` and an empty
+trace list.
+
+## Authentication and privacy
+
+Both routes require password-derived operator authentication, including on a
+loopback bind. Web UI Basic Auth must be configured; the routes accept either
+direct valid Basic Auth or a full session created by password sign-in. A
+loopback-only Web UI without configured credentials returns `401` for these two
+routes, while other Web UI routes retain their historical loopback behavior.
+Read-only observer cookies are rejected even when they carry the `debug` scope.
+
+Exact recent conversation and stage inputs are omitted by default because they
+can contain private text. Use `includeInputs=1` deliberately; values such as
+`true` or `yes` do not enable disclosure. Lesson contents, selector output,
+candidate provenance, and the final injected block remain visible in the
+default trace because they are the subject of the diagnostic.
+
+Every response from either retrieval route uses `Cache-Control: no-store`,
+including authentication failures, not-yet-bound responses, and internal
+errors.
+
+## Retention and failure behavior
+
+The retrieval module retains at most the newest 100 traces and, by default, at
+most 8 MiB of UTF-8 encoded trace JSON in process memory. The limits are
+enforced after every active trace mutation. When the byte budget is reached,
+the oldest traces are evicted until both limits are satisfied. Traces are not
+written to Chronicle and disappear when the Host restarts. Cache provenance is
+rewritten when a referenced source is evicted or truncated, while each
+cache-hit trace keeps its own complete selected-lesson snapshots when they fit
+within the budget.
+
+If one trace alone exceeds the byte budget, it is replaced with a small record
+whose `truncation.kind` is `tombstone` and whose reason and original encoded
+size make clear that the detailed payload is unavailable. Tombstones are never
+presented as exact traces. Payloads that fit remain complete.
+
+Trace recording is fail-open: metadata collection and serialization failures
+must not block retrieval or the primary inference. Arbitrary provider blocks
+and request-level provider parameters are converted to JSON-safe snapshots
+before they are exposed. Their retained representations bound recursion depth,
+total nodes, array items, object keys,
+individual strings, and aggregate string bytes. When a bound applies, the
+stage's `responseContentTruncation` records the explicit reason and active
+limits. Cycles, BigInts, nonfinite numbers, and unreadable properties remain
+safe to serialize using explicit unavailable-value records.
+
+Viewing an existing trace is read-only. Retrieval itself still performs its
+normal model calls and lesson lookup when the agent gathers context.
+
+## Response codes
+
+| Status | Meaning |
+|---:|---|
+| `200` | Viewer or trace response returned. |
+| `401` | Missing operator authentication, including observer-only sessions. |
+| `500` | Retrieval Trace listing failed; the response remains noncacheable. |
+| `503` | Host application has not bound to the Web UI yet. |
+
+## Troubleshooting
+
+- `enabled: false`: enable both `modules.lessons` and `modules.retrieval`, then
+  restart with the updated recipe.
+- Empty `traces`: no retrieval run has completed or started since this Host
+  process began.
+- Many candidates but few selected lessons: the relevance stage is filtering
+  mechanical keyword matches. `maxInjected` is a ceiling, not a quota.
+- `sourceTraceEvicted: true`: a cache hit refers to a run older than the
+  in-memory retention window; the exact selected lesson snapshots remain on the
+  cache-hit trace.
+- `sourceTraceTruncated: true`: the referenced source is retained only as a
+  tombstone; inspect the complete snapshots on the cache-hit trace itself.

package/docs/webui-deployment.md

@@ -160,7 +160,8 @@ Query params:
 - `agent=<name>` — defaults to the recipe's root agent
 - `injections=1` — opt into full fidelity: gather the dynamic injections too.
   **Not transparent** — this can run inference (e.g. the retrieval module's
-  Haiku calls cost tokens) and fires MCPL `beforeInference` hooks (whose paired
+  configured model calls cost tokens) and fires MCPL `beforeInference` hooks
+  (whose paired
   `afterInference` is never sent, so a stateful server may be left half-open).
 - `pretty=1` — pretty-print the JSON