llm-relay 0.84.0 → 0.84.1

package/README.md

@@ -65,10 +65,17 @@ at login.
 ## Learn more
 
 - [docs/reference.md](docs/reference.md) — full reference: config, routing, pools, offload,
-  repair, CLI, endpoints, and every caveat.
+  repair, CLI, endpoints, and every caveat. It opens with a table of contents.
+- [docs/architecture.md](docs/architecture.md) — a map of the code, for a person who wants to
+  change it.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — how to set up, how to prove a change, and how to report a
+  problem without leaking a credential.
 - [docs/subagent-routing.md](docs/subagent-routing.md) — offload design and wire evidence.
 - [docs/pool-failover.md](docs/pool-failover.md) — how failover and health tracking behave.
 - [docs/capability-sources.md](docs/capability-sources.md) — where capability scores come from.
 - [docs/project-goals.md](docs/project-goals.md) — what this project is and is not.
 
-`llm-relay help` lists the main commands. [CLAUDE.md](CLAUDE.md) maps the source for contributors.
+`llm-relay help` lists the main commands. To contribute, start at
+[CONTRIBUTING.md](CONTRIBUTING.md) and [docs/architecture.md](docs/architecture.md).
+[CLAUDE.md](CLAUDE.md) holds the same source map in full detail, written for an AI coding
+assistant.

package/dist/availability.d.ts

@@ -1,5 +1,5 @@
 /**
- * Availability ladders — spec §5.1-5.3 of docs/quota-metering-spec-2026-08-16.md.
+ * Availability ladders — spec §5.1-5.3 of docs/history/quota-metering-spec-2026-08-16.md.
  *
  * `remaining` and `resetsAt` are resolved per (scope, axis, period) through fixed rungs, and
  * staleness is handled HERE, at read time, as a pure function of the caller's clock — never by a

package/dist/backend.d.ts

@@ -29,7 +29,7 @@ export declare class DialectUnparseableError extends Error {
  * fine. It is a config decision, so it is carried as a LOCAL failure — the walk must not fail over
  * (re-asking N models to produce the same refused action) and the deployment must not be charged,
  * the same rule under which a hard cap "never registers on the breaker — it is config, not
- * health". See docs/dialect-rescue-destructive-refusal-2026-08-24.md.
+ * health". See docs/history/dialect-rescue-destructive-refusal-2026-08-24.md.
  */
 export declare class DialectDestructiveError extends Error {
     readonly dialect: string;

package/dist/circuit-breaker.d.ts

@@ -186,7 +186,7 @@ export declare const UNMEASURED_STABILITY = 50;
  * ladder: a `Retry-After`, a 429 escalation and a 402 all still win where they applied before.
  *
  * Pure, so it is pinned directly rather than through the breaker's state machine.
- * Evidence: `docs/latency-demotion-regression-2026-08-30.md` §3.
+ * Evidence: `docs/history/latency-demotion-regression-2026-08-30.md` §3.
  */
 export declare function failureCooldown(elapsedMs: number): {
     ms: number;

package/dist/cli.d.ts

@@ -403,7 +403,7 @@ export declare function renderCommand(invoke: {
  * ⚠ `--probe` spawns lane commands as an explicit operator action — same precedent as
  * `pools --probe` sending real completions. The request path reads the cached manifest and never
  * spawns anything; outside it the only OTHER spawn site is the relay's background lane cadence
- * (owner decision 2026-08-29, docs/quota-reprobe-design-2026-08-29.md). Without `--probe` this
+ * (owner decision 2026-08-29, docs/history/quota-reprobe-design-2026-08-29.md). Without `--probe` this
  * just prints the cache.
  */
 export declare function runLanes(): Promise<void>;

package/dist/config-types.d.ts

@@ -98,7 +98,7 @@ export type ThoughtSignatureMode = "none" | "sentinel";
  *    `thinking: {type:"disabled"}` — DeepSeek's thinking mode requires the prior turn's
  *    `reasoning_content` to be replayed on a multi-turn conversation (HTTP 400 otherwise), and
  *    this relay deliberately holds no store to round-trip it (see
- *    docs/deepseek-responses-truncation-2026-09-09.md), so the default must not think.
+ *    docs/history/deepseek-responses-truncation-2026-09-09.md), so the default must not think.
  */
 export type ReasoningMode = "none" | "deepseek";
 /**
@@ -126,7 +126,7 @@ export interface ProviderCompatConfig {
  *
  * OpenCode Zen's contributor SKUs — Muse Spark 1.3 included — answer HTTP 500 on
  * `/chat/completions` and on Zen's Anthropic-shaped `/messages`, and 200 only on `/responses`
- * (measured 2026-09-04, `docs/muse-spark-1.3-opencode-zen-2026-09-04.md` rows 3 and 6-8). A third
+ * (measured 2026-09-04, `docs/history/muse-spark-1.3-opencode-zen-2026-09-04.md` rows 3 and 6-8). A third
  * `Kind` value for this would touch roughly 55 `kind === "openai"` sites across 19 files (same
  * doc, §3 route B); this narrower option forks only the request/response builders `src/backend.ts`
  * selects on, leaving discovery, catalog and key-check paths unchanged. Declaring it on an
@@ -329,7 +329,7 @@ export interface Routing {
     latency?: LatencyDemotionConfig;
     /**
      * Hedged attempts (owner proposal + decisions 2026-08-30,
-     * docs/hedged-attempts-design-2026-08-30.md §7). **Default ON**, and confined to deployments
+     * docs/history/hedged-attempts-design-2026-08-30.md §7). **Default ON**, and confined to deployments
      * `assessCost()` calls FREE.
      *
      * ⚠ This is the FIRST behaviour here that does not merely reorder — it DUPLICATES a request onto
@@ -366,7 +366,7 @@ export interface Routing {
     pacing?: PacingConfig;
     /**
      * Post-commit CRAWL abort (backlog item 18, built 2026-09-09 after
-     * `docs/post-commit-stall-measurement-2026-09-09.md` measured that both Claude Code and Codex
+     * `docs/history/post-commit-stall-measurement-2026-09-09.md` measured that both Claude Code and Codex
      * retry a stream that goes bad after content has already arrived — Claude Code once, downgraded
      * to non-streaming; Codex up to five times, staying streaming). A silent stall after commit is
      * already caught by `withStallWatchdog` at `stallTimeoutMs`; this catches the case nothing else
@@ -381,7 +381,7 @@ export interface Routing {
     crawl?: CrawlWatchdogConfig;
     /**
      * Background lane re-probing (owner decision 2026-08-29,
-     * docs/quota-reprobe-design-2026-08-29.md): keeping lane metadata fresh is the relay's own
+     * docs/history/quota-reprobe-design-2026-08-29.md): keeping lane metadata fresh is the relay's own
      * job, the way the ping loop already does for HTTP. **Default ON** — catalog probes are
      * metadata commands that spend no quota, and quota probes fire only for buckets carrying an
      * ACTIVE recorded death (an alive lane is re-tested by real use for free). Boolean shorthand
@@ -391,7 +391,7 @@ export interface Routing {
     laneProbe?: LaneProbeSettings;
     /**
      * The automatic dispatch lane WALK (owner request 2026-09-06,
-     * docs/dispatch-lane-walk-design-2026-09-06.md). **Default ON.**
+     * docs/history/dispatch-lane-walk-design-2026-09-06.md). **Default ON.**
      *
      * Before it, `dispatch` ran ONE lane and reported a failure when that lane was slow; the calling
      * agent then picked the next lane by hand, which is the friction the owner reported. With it,
@@ -495,7 +495,7 @@ export interface LatencyDemotionConfig {
 /**
  * `routing.hedge` — start the NEXT candidate beside a slow in-flight attempt, instead of after it
  * (owner proposal 2026-08-30; the four decisions are in
- * `docs/hedged-attempts-design-2026-08-30.md` §7).
+ * `docs/history/hedged-attempts-design-2026-08-30.md` §7).
  *
  * **Default ON, free deployments only.** That is owner decision D1, taken against the
  * recommendation of off-by-default. `assessCost()` treats an UNKNOWN price as paid, so the rule is
@@ -876,7 +876,7 @@ export interface DispatchWalkSettings {
      * answer-mode call. Default 600000 (10 minutes).
      *
      * ⚠ Two floors because the two modes are two different populations
-     * (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §3): an answer-mode call is one HTTP round trip
+     * (`docs/history/dispatch-giveup-diagnosis-2026-09-10.md` §3): an answer-mode call is one HTTP round trip
      * that answers in seconds, while an agent-mode lane runs a whole tool loop for minutes. One floor
      * fitted to both stopped every real agent task on `free-pool` at 90 s, because a burst of short
      * answer-mode calls had set the lane's p80 to 39.5 s. Like `attemptMs` it is an operator budget,
@@ -977,7 +977,7 @@ export interface McpSettings {
 /**
  * Default `routing.mcp.blockingWaitMs` — 25 minutes.
  *
- * Measured and documented 2026-09-17 (`docs/mcp-host-timeouts-2026-09-17.md`): Claude Code's
+ * Measured and documented 2026-09-17 (`docs/history/mcp-host-timeouts-2026-09-17.md`): Claude Code's
  * wall-clock tool limit (`MCP_TOOL_TIMEOUT`) defaults to about 28 hours, and a 240 s call succeeded
  * headless with and without progress. Its stdio idle timeout is 30 minutes, and the documentation
  * says a progress notification resets it. The default stays under 30 minutes so the call survives
@@ -993,7 +993,7 @@ export declare const DEFAULT_MCP_BLOCKING_WAIT_MS = 1500000;
  * somewhere between 45 s and 100 s, and Codex's code-mode `exec` tool yields its script at 31.0 s
  * with empty output ("Script running with cell ID N / Wall time 31.0 seconds"). The 2026-09-10
  * transcript sweep counted 29 of 266 first Codex dispatch calls that lost their job id that way
- * while this default was 40 s (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §8). 25 s sits under
+ * while this default was 40 s (`docs/history/dispatch-giveup-diagnosis-2026-09-10.md` §8). 25 s sits under
  * both. The tool description names the config key rather than this figure, so an operator override
  * never leaves the text stale.
  */

package/dist/config.d.ts

@@ -48,7 +48,7 @@ export declare function resolveThoughtSignatureMode(p: {
  * labelled provider fact in `src/` only while config can override it. DeepSeek's own API states its
  * thinking/reasoning vocabulary (thinking ON by default; `thinking: {type:"disabled"}` /
  * `reasoning_effort: low|high|max`; first-party evidence in
- * docs/deepseek-responses-truncation-2026-09-09.md), so `api.deepseek.com` defaults to `"deepseek"`
+ * docs/history/deepseek-responses-truncation-2026-09-09.md), so `api.deepseek.com` defaults to `"deepseek"`
  * and every other host to `"none"`. An explicit `compat.reasoning` wins in BOTH directions —
  * `"none"` on deepseek, `"deepseek"` on anything else.
  */

package/dist/dispatch-lane-stats.d.ts

@@ -29,7 +29,7 @@ export type DispatchLaneStatus = (typeof DISPATCH_LANE_STATUSES)[number];
  * ⚠ It keys the lane-stats window since 2026-09-10, because the two are different populations: a
  * burst of short answer-mode calls set `free-pool`'s p80 to 39.5 s, and that one shared window then
  * cut every agent-mode task on the same lane at the 90 s floor
- * (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §3). One `as const` array, the type indexed from
+ * (`docs/history/dispatch-giveup-diagnosis-2026-09-10.md` §3). One `as const` array, the type indexed from
  * it and the parser validating against it — the closed-union rule.
  */
 export declare const DISPATCH_MODES: readonly ["agent", "answer"];

package/dist/dispatch.d.ts

@@ -251,7 +251,7 @@ export interface DispatchLane {
          *
          * ⚠ It exists because an abandoned run leaves no duration sample, so a window fed only by runs
          * that finished inside the budget can never show that the lane needed longer — the floor lock
-         * measured on 2026-09-10 (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §3b). Each abandonment
+         * measured on 2026-09-10 (`docs/history/dispatch-giveup-diagnosis-2026-09-10.md` §3b). Each abandonment
          * doubles the next budget, capped at `MAX_ATTEMPT_BUDGET_MS`; one success resets the count.
          */
         raisedBy?: number;
@@ -393,7 +393,7 @@ export interface DispatchOptions {
      * WHO is asking, when that changes what can run. `"mcp"` is the `llm-relay mcp` server: it runs
      * lanes itself and has no `Agent` tool, so a pass-through relay rung — one that forwards the
      * caller's own Anthropic credential — can never run there. It comes back `unreachable`, never as a
-     * lane the walk tries and fails in 0 s (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §4).
+     * lane the walk tries and fails in 0 s (`docs/history/dispatch-giveup-diagnosis-2026-09-10.md` §4).
      * Absent ⇒ exactly the behaviour before this existed.
      */
     requester?: "mcp";
@@ -407,7 +407,7 @@ export interface DispatchOptions {
      * instead of the ladder. Validated against the configured providers and pools: an unknown spec
      * yields no lane and a reason. `dispatch` could not name a model before 2026-09-10, so agents that
      * had to use DeepSeek wrote their own HTTP calls to the relay
-     * (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §7).
+     * (`docs/history/dispatch-giveup-diagnosis-2026-09-10.md` §7).
      */
     model?: string;
 }

package/dist/hedge-trigger.d.ts

@@ -12,7 +12,7 @@
  * ⚠ **Hedging DUPLICATES, it does not reorder** — the first behaviour in this relay that does. The
  * `CLAUDE.md` invariant reads *"Acting on counts is optional, always announced, and may only
  * reorder"*, so the duplication is bounded three ways, all of them owner decisions recorded in
- * `docs/hedged-attempts-design-2026-08-30.md` §7: it is confined to deployments `assessCost()`
+ * `docs/history/hedged-attempts-design-2026-08-30.md` §7: it is confined to deployments `assessCost()`
  * calls FREE (D1), the loser is aborted the moment a winner commits, and the response announces it.
  *
  * WHY IT EXISTS. Measured 2026-08-30: `nim/deepseek-ai/deepseek-v4-flash-0731` hung on 43

package/dist/lane-cadence.d.ts

@@ -1,7 +1,7 @@
 /**
  * The background lane cadence — the relay's own re-probe loop for `cli` lanes.
  *
- * Owner decision 2026-08-29 (docs/quota-reprobe-design-2026-08-29.md): keeping lane metadata
+ * Owner decision 2026-08-29 (docs/history/quota-reprobe-design-2026-08-29.md): keeping lane metadata
  * fresh is the relay's job, the way `PingLoop` already keeps HTTP health fresh — not a host
  * scheduled task's, and never the nightly maintenance run's (that belongs to another repo).
  * This closes the property the backlog demanded: a recorded quota death either expires on a

package/dist/lane-manifest.d.ts

@@ -5,7 +5,7 @@
  * validated it. Measured 2026-08-08: the ladder handed an agent
  * `agy --model claude-opus-5 --effort medium`, in which BOTH halves were wrong independently —
  * AGY serves no Claude 5 at all, and `--effort` is rejected outright for its Claude models. The
- * lane looked healthy and completed nothing. See docs/lane-discovery.md.
+ * lane looked healthy and completed nothing. See docs/history/lane-discovery.md.
  *
  * ⚠ A model the vendor does not serve is `not-servable` — an EXISTENCE fact, so the rung is
  * REMOVED, not demoted. `target-facts.ts` already draws that line: `allowance-exhausted` demotes

package/dist/lane-probe.d.ts

@@ -2,7 +2,7 @@ import type { Config } from "./config-types.js";
 /**
  * `llm-relay lanes --probe` — ask each `cli` lane's own tool what it serves.
  *
- * ⚠ The spawn boundary (amended by owner decision 2026-08-29, docs/quota-reprobe-design-2026-08-29.md):
+ * ⚠ The spawn boundary (amended by owner decision 2026-08-29, docs/history/quota-reprobe-design-2026-08-29.md):
  * the REQUEST PATH never runs a `cli` lane's command — a lane's quota is client-bound, it runs its
  * own tool loop, and it returns only final text, so a relay that shelled out mid-request could
  * never return the `tool_use` blocks an HTTP turn owes its caller. Outside the request path there
@@ -11,7 +11,7 @@ import type { Config } from "./config-types.js";
  * metadata polling is the relay's job, exactly as the ping loop already does for HTTP. Nothing
  * here is reachable from `handle()`, and the request path reads only the CACHED manifest.
  *
- * Discovery is not symmetric (docs/lane-discovery.md):
+ * Discovery is not symmetric (docs/history/lane-discovery.md):
  *   codex — `codex debug models` returns JSON including per-model `supported_reasoning_levels`,
  *           so both the id and the effort argument are validated with no API call spent.
  *   agy   — `agy models` returns `id<TAB>label` and states nothing about flags, so its argument

package/dist/latency-demotion.d.ts

@@ -69,7 +69,7 @@
  * succeeding, inside a window every deployment passes through on its way to being measured.
  * ⚠ A request sample with NO token count therefore reaches NEITHER statistic. That is deliberate:
  * it is a generation of unknown length, so it is not normalisable and not what `p95Ms` describes.
- * Evidence: `docs/latency-demotion-regression-2026-08-30.md`.
+ * Evidence: `docs/history/latency-demotion-regression-2026-08-30.md`.
  *
  * ⚠ **NO breaker cooldown is registered, and that is the design, not an omission.** Quota demotion
  * can register one because its evidence STATES a `resetsAt`. Latency states no reset, and this

package/dist/mcp/lane-runner.d.ts

@@ -719,7 +719,7 @@ export interface CwdCheck {
  * is offered, not imposed; that is the operator's call to make in config, not this file's.
  *
  * ⚠ **The containment test resolves BOTH sides with `path.resolve` before comparing** (closed
- * 2026-09-03, docs/audit-findings-2026-09-03.md finding 1 / DR-002). Without it a literal `..`
+ * 2026-09-03, docs/history/audit-findings-2026-09-03.md finding 1 / DR-002). Without it a literal `..`
  * segment in `cwd` — a raw string a caller sends verbatim, never normalized — satisfied a bare
  * `startsWith` prefix test while `existsSync`/`statSync` above had already resolved `..` at the
  * OS level against the REAL, escaped directory: `allowedRoots: ["C:/allowed"]` admitted

package/dist/mcp/protocol.d.ts

@@ -9,7 +9,7 @@
  *
  * ⚠ The known cost, stated so it is not rediscovered: hand-rolling means owning a spec that moves.
  * The mitigation is that this file implements only the stable core. Extensions (Tasks, Apps,
- * sampling) are deliberately absent — see `docs/mcp-dispatch-prior-art-2026-08-30.md` §3.1, which
+ * sampling) are deliberately absent — see `docs/history/mcp-dispatch-prior-art-2026-08-30.md` §3.1, which
  * measured that no client ships Tasks support today.
  *
  * TRANSPORT. MCP stdio framing is one JSON message per line. A message therefore must not contain

package/dist/mcp/readonly-boundary.d.ts

@@ -22,7 +22,7 @@ export type ReadOnlyVerdict = {
  * Containment is tested on RESOLVED paths with a separator boundary, never a bare `startsWith`:
  * `C:/caller/tree-other` shares a prefix with `C:/caller/tree` and is not inside it, and a literal
  * `..` segment resolves at the OS level before the comparison — the `checkCwd` defect closed
- * 2026-09-03 (docs/audit-findings-2026-09-03.md finding 1 / DR-002), applied here in the direction
+ * 2026-09-03 (docs/history/audit-findings-2026-09-03.md finding 1 / DR-002), applied here in the direction
  * where getting it wrong would WRONGLY PERMIT a mutation.
  *
  * Answer mode is always allowed: `startLane` skips the cwd/spawn path entirely for a `relay` rung

package/dist/mcp/server.d.ts

@@ -175,7 +175,7 @@ export declare const LANE_LADDER_PARTIAL_ADVICE: string;
  * ⚠ The stopped lane did not fail on its own: the walk stopped it because it showed no activity the
  * relay could see. So "every dispatch lane has now been tried" is false there, and would end the
  * caller's use of dispatch for a task the lane might still finish
- * (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §5). A NAMED lane is never stopped for idleness,
+ * (`docs/history/dispatch-giveup-diagnosis-2026-09-10.md` §5). A NAMED lane is never stopped for idleness,
  * so this names the call that lets it run to its own timeout.
  */
 export declare function laneStoppedAdvice(laneId: string): string;
@@ -191,7 +191,7 @@ export declare const IDLE_POLL_MS = 15000;
  * MCP clients (`initialize` `clientInfo.name`) measured to survive a long tool call, so `dispatch`
  * may wait for the answer the way the host's own subagent does, up to `routing.mcp.blockingWaitMs`.
  *
- * Measured 2026-09-17 (`docs/mcp-host-timeouts-2026-09-17.md`): Claude Code 2.1.237 (`claude-code`)
+ * Measured 2026-09-17 (`docs/history/mcp-host-timeouts-2026-09-17.md`): Claude Code 2.1.237 (`claude-code`)
  * completed a 240 s tool call headless, with and without progress. Two hosts are deliberately NOT
  * here: the Claude desktop chat client (`claude-ai`) cancelled at exactly 60 s, and Codex runs a
  * call inside a code-mode `exec` that yields at 31 s. An unknown client keeps `maxWaitMs`.
@@ -359,7 +359,7 @@ export declare class McpDispatchServer {
      * streak of `LANE_UNRELIABLE_STREAK` own failures or more, or marked `failing`. Stopping a lane
      * that may still answer in order to reach those trades an answer for a near-certain failure —
      * measured 2026-09-10, when the walk stopped `free-pool` to try lanes that had answered 0 of 12,
-     * 0 of 34 and 0 of 21 runs (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §1). A lane with no
+     * 0 of 34 and 0 of 21 runs (`docs/history/dispatch-giveup-diagnosis-2026-09-10.md` §1). A lane with no
      * record counts as reliable: unmeasured is no opinion, never a failure.
      */
     private stopWithheld;
@@ -445,7 +445,7 @@ export declare class McpDispatchServer {
      * The quota death an AGY lane stated only in AGY's own log (`agy-quota-log.ts`). AGY retries a
      * spent quota in silence, so a lane stopped by the walk or by its own timeout printed nothing, and
      * the death reached the relay only when a run happened to last its whole length
-     * (`docs/dispatch-giveup-diagnosis-2026-09-10.md` §4). Undefined unless the lane is AGY, names its
+     * (`docs/history/dispatch-giveup-diagnosis-2026-09-10.md` §4). Undefined unless the lane is AGY, names its
      * model, and the log is provably this run's — `agyQuotaStatement` refuses everything else.
      */
     private agyLogReport;

package/dist/process-safety-net.d.ts

@@ -10,7 +10,7 @@
  * the same reasoning as an unset `${ENV}` disabling one provider instead of aborting startup.
  *
  * Design (fork-validated in freellmapi's process-safety-net, adopted 2026-08-13 — see
- * docs/freellmapi-adoption-review-2026-08-13.md §1.3): swallow ONLY a closed allowlist of
+ * docs/history/freellmapi-adoption-review-2026-08-13.md §1.3): swallow ONLY a closed allowlist of
  * transport error codes plus a short list of Node/undici-authored message shapes, and
  * preserve Node's default fail-fast exit(1) for everything else, so genuine bugs still crash
  * loudly. The classifier is a pure function so it is unit-testable without touching global

package/dist/responses-request.d.ts

@@ -10,7 +10,7 @@ import type { ReasoningMode } from "./config-types.js";
  * A TUNABLE DEFAULT, never a provider figure — the provenance invariant this whole module already
  * follows. Until 2026-09-09 this module substituted llm-bridge's flat 1024 here UNCONDITIONALLY,
  * even for an `openai`-kind target's outbound Chat body, where the field is genuinely optional.
- * Measured against DeepSeek (docs/deepseek-responses-truncation-2026-09-09.md): 20 of 68 captured
+ * Measured against DeepSeek (docs/history/deepseek-responses-truncation-2026-09-09.md): 20 of 68 captured
  * upstream answers ended `finish_reason: "length"` at EXACTLY `completion_tokens: 1024` — the
  * relay's own invented cap, not anything the caller or the provider asked for — and every one of
  * the 44 emitted `response.completed` events still carried `"status":"completed"`, so a cap

package/dist/stream-commit.d.ts

@@ -105,7 +105,7 @@ export type FrontProtocol = "anthropic-messages" | "chat" | "responses";
  * passthrough condition — `openai`-kind means translated on the Anthropic front, while on the
  * OpenAI front only `openai`-kind PLUS `chat` is a passthrough. The two spellings never disagreed:
  * a truth table over all six reachable combinations is in
- * `docs/reviews/clone-07-clone-26-evidence-2026-09-05.md`, and `test/stream-commit.test.ts` pins
+ * `docs/history/reviews/clone-07-clone-26-evidence-2026-09-05.md`, and `test/stream-commit.test.ts` pins
  * every row. Naming it once is what stops a fifth call site inventing a seventh row, because a new
  * front or a new protocol currently has two places to get right and no compiler help.
  */

package/dist/stream-pipeline.d.ts

@@ -37,7 +37,7 @@ export declare function withStallWatchdog(response: Response, controller: AbortC
  * Calibrated 2026-09-09, on the `latency-demotion.ts` precedent: 4 x `DEFAULT_LATENCY_MS_PER_TOKEN`
  * (250 ms/token, itself measured over 68 real requests on 2026-08-30 — see that file's own
  * comment). A crawl abort hands the client a failure it must retry — measured in
- * `docs/post-commit-stall-measurement-2026-09-09.md`: Claude Code retries once, downgraded to a
+ * `docs/history/post-commit-stall-measurement-2026-09-09.md`: Claude Code retries once, downgraded to a
  * NON-STREAMING request; Codex retries up to five times, staying streaming, in all four measured
  * cells — so the bar must sit far above the demotion threshold, or a deployment merely slow enough
  * to be latency-demoted would also be aborted mid-response. 250 ms/token is itself ~3.5x the

package/dist/tool-dialects.d.ts

@@ -31,7 +31,7 @@ interface SchemaLike {
  * upstream. An in-band error is provenance `upstream` by default and therefore retriable, which
  * would let a streamed pre-commit refusal reroll onto the next candidate while the buffered lanes
  * treat the same refusal as terminal — two paths, one policy. See
- * docs/dialect-rescue-destructive-refusal-2026-08-24.md §3.
+ * docs/history/dialect-rescue-destructive-refusal-2026-08-24.md §3.
  */
 export declare const DIALECT_REFUSED_DESTRUCTIVE_CODE = "tool_dialect_refused_destructive";
 /**

package/docs/README.md

@@ -0,0 +1,43 @@
+# Documentation index
+
+Start with the row that matches what you want to do.
+
+| You want | Read |
+|---|---|
+| To install and run the relay | [`QUICKSTART.md`](QUICKSTART.md) |
+| Every option, endpoint and caveat | [`reference.md`](reference.md) |
+| To understand the code before changing it | [`architecture.md`](architecture.md) |
+| To submit a change | [`../CONTRIBUTING.md`](../CONTRIBUTING.md) |
+| To know what this project is, and is not | [`project-goals.md`](project-goals.md) |
+| The convictions that settle a design question | [`project-philosophy.md`](project-philosophy.md) |
+| What is still open | [`backlog.md`](backlog.md) |
+
+## Subject documents
+
+Each of these covers one subject in depth. Read one when you work on that subject.
+
+| Document | Subject |
+|---|---|
+| [`pool-failover.md`](pool-failover.md) | how failover, health and circuit breaking behave |
+| [`pool-eligibility.md`](pool-eligibility.md) | which deployments a pool may admit, and why |
+| [`subagent-routing.md`](subagent-routing.md) | offload design, and the wire evidence behind it |
+| [`host-adaptive-dispatch.md`](host-adaptive-dispatch.md) | how dispatch adapts to the calling host |
+| [`offload-agentic-capability.md`](offload-agentic-capability.md) | what an offloaded agent lane can and cannot do |
+| [`capability-sources.md`](capability-sources.md) | where capability scores come from |
+| [`tool-call-dialect-leak.md`](tool-call-dialect-leak.md) | how a host leaks a tool call as plain text |
+| [`delegate-gate.md`](delegate-gate.md) | the quality gate over a diff an agent lane returned |
+
+## Data files
+
+| File | Holds |
+|---|---|
+| `tier-data.json` | the synced capability snapshot. Regenerate with `npm run sync:tiers`. |
+| `dashboard-bundle-inventory.json` | the published dashboard bundle inventory |
+| `dashboard-package-baseline.json` | the package-size ceiling the gate checks |
+
+## Other directories
+
+- [`history/`](history/) — dated records: design notes, audits and lap closeouts. These are
+  **evidence, not documentation**. Read [`history/README.md`](history/README.md) first.
+- [`../CLAUDE.md`](../CLAUDE.md) — the full source map, written for an AI coding assistant. It
+  states the reason behind each rule. Read [`architecture.md`](architecture.md) first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-relay",
-  "version": "0.84.0",
+  "version": "0.84.1",
   "description": "Loopback bidirectional Anthropic/OpenAI API proxy with tool-call validation and multi-provider routing.",
   "type": "module",
   "engines": {

package/scripts/install-skill.mjs

@@ -240,6 +240,7 @@ try {
     join("references", "direct-routing.md"),
     join("references", "dispatch-lanes.md"),
     join("references", "operations.md"),
+    join("references", "lane-field-notes.md"),
   ];
   for (const relativePath of skillFiles) {
     const sourcePath = join(skillSourceDir, relativePath);

package/skills/llm-relay/SKILL.md

@@ -161,6 +161,10 @@ Do not read every reference by default.
   read [references/dispatch-lanes.md](references/dispatch-lanes.md).
 - For health commands, control authorization, failures, pool-walk headers, eligibility
   interpretation, or safety invariants, read [references/operations.md](references/operations.md).
+- Before you dispatch a packet, write a brief, judge a lane's output, run several lanes at once, or
+  diagnose a lost job, read [references/lane-field-notes.md](references/lane-field-notes.md). It
+  holds the measured traps: the CLI-rung reply envelope, lost job ids, restarts that kill lanes,
+  the concurrency cap, what each lane can carry, and why a brief's wording is not a boundary.
 
 The CLI's `help`, `dispatch_lanes`, and live status commands are authoritative for current
 configuration and quota. Do not copy a dated lane roster from prose.

package/skills/llm-relay/references/lane-field-notes.md

@@ -0,0 +1,202 @@
+# Lane field notes — measured behaviour of llm-relay dispatch and its lanes
+
+Every note here was MEASURED on this machine, with its date. They moved out of the machine-wide
+backlog on 2026-09-17 (owner instruction: llm-relay-specific instructions belong with the llm-relay
+skill, not in a shared to-do file). Each note is REFERENCE, not work: it is deleted when it becomes
+untrue, never because something shipped. A defect in llm-relay itself belongs in
+`C:\Code\llm-relay\docs\backlog.md` in product terms.
+
+Ask the live tools first. `dispatch_lanes` and `llm-relay dispatch` carry the current lane record
+and quota; never copy a dated roster out of prose.
+
+## 1. Reading a dispatch reply
+
+- **A `cli` rung's reply body is NOT the lane's answer (2026-09-16).** A `relay` rung such as
+  `free-pool` returns the raw answer. A `cli` rung such as `agy-gemini` returns its harness's own
+  record — `{"conversation_id":…,"status":"SUCCESS","response":"<the real answer>",
+  "duration_seconds":…,"usage":{…}}` — so the answer sits inside `response`. Code that binds the
+  body to a schema fails on exactly the calls the ladder sent to a CLI rung, and the failure looks
+  like a bad lane. Measured in audit-tools, 2026-09-16: 28 of 62 sweep calls lost, 19 to this
+  envelope. (llm-relay packet M1 will unwrap it in the relay and announce an `unwrapped:` line;
+  until that release, unwrap it yourself.)
+- **A `SUCCESS` status is not an answer (2026-09-16, owner decided not to fix this in the relay).**
+  A `posttooluse-typecheck.mjs` dispatch (job-0021) returned `"status":"SUCCESS"` around 40 repeated
+  lines of "Waiting for test execution to complete." and no work product. Read the content by hand.
+- **A completed job can carry no usable answer (2026-09-07 and 2026-09-09).** Agent-mode jobs
+  exited after 302 s and 623 s with the single words `Now` and `Let`, and their worktrees were
+  clean. Job `job-0005` exited 0 after 765 s and returned `I`. A review job completed after 813 s
+  with a completion claim and no findings. Treat a terminal status as evidence of TERMINATION only,
+  then inspect the answer and the worktree. None of these outcomes proves a provider quota is
+  spent.
+- **`status: "running"` after a long `waitMs` is normal (2026-09-16).** The server clamps `waitMs`
+  to `routing.mcp.maxWaitMs`. Poll `dispatch_status`, then `dispatch_result`. In audit-tools 9 of
+  62 calls were lost by treating this as a fault.
+- **Map a lane's verdict table to the file by HEADING, never by row number (2026-09-10).** A
+  read-only lane numbered 74 backlog entries out of file order (one moved from row 20 to row 8),
+  so its row numbers would have deleted the wrong entries. Re-derive rows with a script and match
+  each verdict by its heading text.
+
+## 2. Waits, restarts and lost jobs
+
+- **A large `waitMs` loses the job id (2026-09-06).** `waitMs: 180000` returned `Error: Request
+  timed out` with no job id, so the lane could not be polled, resumed or cancelled. The same task
+  at `waitMs: 40000` returned `job-0001` at once and finished in 145 s. Leave `waitMs` unset.
+- **Codex's code-mode `exec` gives up on a tool call at 31.0 s (2026-09-10).** It returns "Wall
+  time 31.0 seconds" with empty output, so a longer MCP call loses its answer: 29 of 266 first
+  Codex `dispatch` calls, 2026-09-07 to 2026-09-10. Keep every MCP call from a Codex host under
+  30 s. llm-relay blocks 25 s by default since v0.81.0 and then hands back a job id.
+  Since v0.83.x the server waits longer only for hosts measured to survive it: Claude Code with a
+  progress token gets the answer in one call, Claude Desktop gets 50 s, every other host keeps the
+  ceiling (llm-relay `docs/history/mcp-host-timeouts-2026-09-17.md`).
+- **An MCP server restart KILLS every lane it was running (2026-09-06, re-measured 2026-09-17).**
+  The old symptom — `unknown jobId` for every job, numbering restarted at `job-0001`, nothing on
+  disk — is fixed: the running-job journal reports each such job as `killed` (v0.80.0) and the job
+  archive keeps finished jobs and the id counter across restarts (v0.82.0). The WORK is still
+  lost: 14 of 83 archived jobs on 2026-09-17 were `killed`, 11 of them `agy-gemini`. Give every
+  lane its own worktree, because that directory is the only record of what a killed lane did, and
+  dispatch a killed job again.
+- **One `llm-relay mcp` process can outlive a release (2026-09-10).** The Claude desktop app keeps
+  one MCP connection across its sessions, so after a global reinstall that connection runs the old
+  code until the app restarts. Since v0.81.0 a reply from a process older than the installed
+  package says so.
+- **A session that hits its usage limit mid-turn loses every in-flight job (2026-09-04).** Three
+  `relay` subagents lost their lane jobs when the limit hit: the MCP connection was replaced, job
+  ids restarted at `job-0001`, and each agent saw `Request timed out` then `Connection closed`.
+  Keep the job handles in the main session rather than in subagents, and re-dispatch after the
+  reset.
+- **An unrunnable lane is not a quota verdict (2026-09-09).** `Lane "anthropic" cannot be run from
+  here: it is a relay target (anthropic) with no cliLane template configured` means no answer was
+  produced. It says nothing about any account's quota. Keep the exact error.
+
+## 3. Lane capacity and concurrency
+
+- **Cap concurrent lanes at three or four; seven died together (2026-09-06).** Five
+  `opencode-muse-spark` and two `agy-gemini` lanes all hit the 2100 s timeout at the same moment,
+  exit 124, empty output, four packets lost — one had written 348 lines. Three lanes ran
+  comfortably afterwards. The relay does not cap this; the caller must.
+  - The tell is SIMULTANEITY. One silent lane is a lane problem; a cohort dying at the same
+    elapsed second is a load problem.
+  - The usual cause is asking every lane to run the full repository gate. Give a lane its TARGETED
+    suites plus lint, and keep the full gate for the orchestrating session.
+  - The orchestrator's own gate runs count toward the same budget: a cohort of only three lanes
+    also died together at 1800 s while the orchestrating session ran five full gates. Pause
+    dispatching while you verify, or drop to two lanes.
+  - A killed lane holds its worktree directory open, so `git worktree remove` reports "Permission
+    denied" although git DOES unregister the worktree. Believe `git worktree list`, not the
+    filesystem.
+  - A gate step that reaches the network flakes under this load: `npm audit` returned an error
+    payload while three lanes ran. Rerun such a step alone before believing it.
+- **Two concurrent Muse Spark lanes starve, not only three (2026-09-09).** Two packets dispatched
+  together ran to the 2100 s timeout with empty output and no file written; single lanes finish in
+  minutes. Its rungs carry `maxConcurrent: 1` since llm-relay v0.78.0; keep it that way.
+
+## 4. What each lane can carry
+
+- **`opencode-muse-spark`** carries a whole implementation packet ALONE (101–998 s, 2026-09-09),
+  and starves as a second or third concurrent lane. Always pass `cwd`. Keep the task text under
+  4,096 characters and put a long brief in a file: a longer task makes the MCP server fall back to
+  its start-time config snapshot. It runs as the `relay-lane` OpenCode agent.
+  ⚠ Headless OpenCode auto-rejects every permission set to `ask`, and the global default sets
+  `edit` and `bash` to `ask`, so without that agent a lane can read but cannot edit or run a suite,
+  and the failure looks like a model failure (measured 2026-09-04: `permission requested: edit …;
+  auto-rejecting`). A lane dispatched with no `cwd` had every READ rejected as
+  `external_directory`. The agent lives in `~/.config/opencode/opencode.json`; a repository-level
+  `opencode.json` merges over it, and `agent=<name>` on the run's `stream` lines in
+  `~/.local/share/opencode/log/opencode.log` is the only proof of which agent ran.
+  ⚠ The agent did not end the zero-output mode (2026-09-04/05): with everything correct, two lanes
+  ran 918 s and 895 s and wrote zero bytes. Read-only recon on this lane is 35–70 s, so no file
+  change in the worktree after about five minutes is the signal to cancel and re-dispatch.
+- **`agy-gemini`** is the steady CLI lane: 24 of 24 answered at a 240 s median on 2026-09-06, and
+  it carried packets at 348–561 s. It ran two lanes in one worktree (authoring plus a read-only
+  review) without interference.
+  ⚠ It obeys an absolute path written INSIDE the brief over the `cwd` you passed, even when the
+  task says not to (2026-09-06). Never write an absolute worktree path into a shared brief, or
+  regenerate the brief per lane. Before concluding a lane produced nothing, look where its brief
+  pointed.
+- **`agy-claude-opus`** drops the stream on long outputs (2026-09-04/05): `The stream was
+  interrupted` after a report summary, and `There was a network issue connecting to the server`
+  after 490 s. Split the work into packets and run them on `agy-gemini`.
+- **Codex Spark** reads its whole usage window and writes nothing (2026-09-09, twice): 193k and
+  477k tokens, every test file read whole, then "You've hit your usage limit". A preamble limiting
+  reads changed nothing. Give it a review of a bounded diff, or nothing.
+- **A shape that scored 10/10 yesterday is not a cure (2026-09-06).** Three `opencode-muse-spark`
+  lanes using the exact shape recorded as reliable the day before wrote nothing in 25 minutes while
+  `dispatch_status` said `running` and ten `opencode.exe` processes sat at about 500 MB each. Read
+  `dispatch_lanes` before choosing a lane; the same day it read 72 calls / 6 timed out / median
+  616 s for Muse Spark against 24 / 24 ok / median 240 s for `agy-gemini`.
+
+## 5. Writing a brief, and trusting what comes back
+
+- **A brief's wording is NOT a boundary (2026-09-06, measured twice).** A lane told to AUDIT a
+  closeout spent 19 minutes writing its own `closeout-input.json` into a live repository root, with
+  a fabricated verification section. Five later lanes each opened with "Do NOT edit any file.
+  Report findings only"; one still ran suites in the shared tree, wrote to the repository root,
+  performed the repository's own closeout ceremony, and an untracked deliverable of the
+  orchestrating session vanished at the same minute. The controls that DO work: give every writing
+  lane its own worktree, use `mode: "answer"` when the lane needs no file access, use
+  `readOnly: true` for an agent lane (llm-relay binds the lane's own read-only tool flags since
+  v0.82.0), commit an in-progress deliverable before dispatching into the same tree, and run
+  `git status --porcelain` after EVERY lane returns or is cancelled. A cancelled lane leaves its
+  files behind exactly like a completed one.
+- **A brief that says "never print the key" does not stop a lane writing the key (2026-09-09).** A
+  capture lane put `export DEEPSEEK_API_KEY="sk-…"` into a scratch `start-relay.sh`. Tell the lane
+  to read a secret from the environment at run time and never copy the value into a file, and grep
+  every scratch launcher for `sk-` before running it or passing it on.
+- **Ask a lane to EXTRACT, not to give a VERDICT (2026-09-06).** A free-pool lane given a rubric
+  and asked for `clear`/`defective` answered `clear` for all 97 records: a rubric whose rules
+  mostly say "this is not a defect" pushes a weak model to the null answer, and the output looks
+  well formed. The same job as an extraction — list the terms a cold reader cannot resolve, rate
+  0–10 — did not collapse. Always check a lane's label DISTRIBUTION before using its labels.
+- **Well-formed output can still be wrong, and that is the version that gets believed
+  (2026-09-06).** A lane produced 120 clean records in the requested shape; against a hand-labelled
+  overlap its best agreement was 64%, while answering "clear" every time scored 73%. Never fold
+  lane labels into a count, a training set or a conclusion without measuring agreement on a
+  hand-labelled overlap, and always against the always-answer-the-majority baseline.
+- **A lane that returns one large JSON object at the end returns NOTHING when it stops early
+  (2026-09-06, three lanes lost).** Have the lane append one JSON line per record as it works, and
+  slice the job to about 40 records rather than 100.
+- **Free lanes cannot do open-ended reconnaissance here (2026-09-05, 7 of 7 packets fabricated).**
+  They CAN review a concrete diff against a stated claim, and they carry a mechanical rewrite with
+  a stated rule. The test is whether the output can be checked by running or reading something
+  specific.
+
+## 6. Hooks, keys and the daemon
+
+- **A relay lane loads NO global hook (2026-09-17).** `dispatch` launches each Claude lane with
+  `CLAUDE_CONFIG_DIR=~/.llm-relay-claude`, so the lane reads `~/.llm-relay-claude/settings.json`
+  and never `~/.claude/settings.json`. A global hook guards the orchestrator's own tool calls only.
+  Codex, OpenCode and AGY lanes have no hook surface at all; for them the orchestrator-side
+  `dispatch-cwd-guard.mjs` and the lane's own worktree are the only controls.
+- **Provider API keys are NOT environment variables on this machine (2026-09-09).** `llm-relay
+  keys` prints an `Env var` column, which is the NAME the relay looks for, not proof the variable
+  exists: `NVIDIA_API_KEY` is empty in every scope while the same key reads `VALID`, because the
+  secret lives DPAPI-wrapped in `~/.llm-relay/keystore.json`. A direct `curl` therefore sends an
+  empty bearer, and NVIDIA answers HTTP 500 with a Rust `axum::Extension` message that reads like a
+  provider fault. Probe through the relay instead: `POST http://127.0.0.1:8791/v1/messages` with
+  `"model": "<provider>/<model id>"`. A public `/v1/models` answer proves nothing about a key.
+- **A provider timeout turns a slow model into a fake "not servable" (2026-09-09).** With `nim` at
+  `timeoutMs: 100000`, a 32-token probe of `deepseek-ai/deepseek-v4-flash-0731` returned HTTP 504
+  at 100.03 s, while its sibling answered 200 after 81.6 s for two output tokens; the same Flash
+  model had answered in 38 s on 2026-08-27. A 504 at the configured timeout is evidence about the
+  QUEUE. Raise `providers.<name>.timeoutMs` and probe again before recording a model as dead.
+  `firstByteTimeoutMs` (v0.78.0) fails over fast when nothing arrives at all, while a slow body
+  still runs to its end.
+- **The daemon reads `config.json` ONCE at start.** A rung or provider edit is invisible until the
+  daemon restarts — confirmed live: after a rung edit the `agy.exe` command line still carried the
+  old `--model`, and a re-probe after a timeout raise timed out again at exactly the old value.
+  Each `llm-relay mcp` process loads the file once too, so a host restart is needed for it as well.
+  `GET /telemetry` carries `config.changedOnDisk`, and `routing show|get`, `config show|get` and
+  `offload status` print a notice when the running relay has not loaded an edit. Restart: stop the
+  node process running `dist\cli.js` with no subcommand (`llm-relay stop` since v0.78.0), then
+  relaunch `wscript.exe "…\Startup\llm-relay.vbs"`; verify with `GET /telemetry` and
+  `llm-relay dispatch --tier high`.
+- **A pool request to DeepSeek runs with thinking ON, which spends output tokens on reasoning
+  (2026-09-09, causes since addressed).** Two authorized paid calls to `deepseek/deepseek-v4-pro`
+  returned HTTP 200 and `max_tokens` with zero final text. llm-relay forwards the caller's thinking
+  control since 2026-09-10 and `dispatch` takes a `model` argument since v0.81.0. For a pool
+  request, give a large `max_tokens` or send `thinking: {"type": "disabled"}`.
+- **Codex Desktop cannot reach a relay pool through a collaboration child (2026-08-31).** With a
+  ChatGPT account the launcher validates `pool/medium` against the parent account before contacting
+  llm-relay and fails with HTTP 400 `The 'pool/medium' model is not supported when using Codex with
+  a ChatGPT account.` Use the MCP `dispatch` tool there. Generated agent files stay valid for
+  clients that honour custom providers.