opencode-harness-kit 0.2.1 → 0.3.4

package/docs/KNOWN-LIMITS.md

@@ -84,14 +84,193 @@ session's:
 | `config` | Yes, but it runs once at startup. |
 | `provider` | Can add or override models in the catalog, not the active session. |
 
-So `router.ts` does two things instead of the obvious third: at startup it
-moves to the next healthy profile, and when a request fails it tells the agent
-plainly that a new session is the fix. It does not pretend to retry.
+So `router.ts` does three things instead of the obvious fourth: at startup it
+moves a lane to the next rung of its own chain, when the session's own model
+is spent it moves to the next profile in the fallback queue, and when a
+request fails it tells the agent plainly that a new session is the fix. It
+does not pretend to retry.
 
 The gap is real and tracked upstream. Provider issue #42977 asks Zen for a
 `scope` field and a remaining-quota figure on 429 responses, precisely because
 a client cannot currently tell a short quota window from a permanent block.
 
+## A copied plugin loads and does nothing
+
+The bundle finds `profiles/`, `prompts/`, `retention.yml` and `lanes.json` by
+walking up from its own file. A symlink resolves to the real path, so a
+symlinked plugin finds the kit's data. A **copy** does not: it looks beside
+itself, finds nothing, and every profile lookup fails.
+
+The failure is silent in the worst way. The plugin loads, its hooks are
+registered, and nothing complains - but there is no guard, no pruning, no
+lane failover and no telemetry. The session looks entirely normal and is
+entirely unguarded. It was found by instrumenting the config hook, which
+reported `no profile named "fleet-safe"` and nothing else.
+
+`oc-harness install` symlinks the plugin rather than copying it, and
+`oc-harness verify` now checks that the link still resolves to a bundle whose
+data root is intact.
+
+## An agent markdown file replaces the config entry, not the other way round
+
+This is the one that decides where a model can live, and it was measured
+against OpenCode 1.19 rather than read off the docs.
+
+Two behaviours, both silent:
+
+- An agent file whose name matches a config entry **replaces that entry
+  wholesale**. A file saying `model: opencode/beam-free` beat a config entry
+  saying `model: opencode/minimax-m3.1-flash-free`.
+- An agent file **with no `model:` line** makes the agent inherit the model of
+  the agent that called it, not the model the config declares for it. A lane
+  configured for one model and defined by a file without a model ran on the
+  parent's model, and the config still looked correct.
+
+The reproduction needs the plugin out of the way, because the kit's own
+`config` hook re-pins the model:
+
+```
+$ opencode run --pure --agent build "..."
+```
+
+With `--pure`, the file's model wins. Without it, the plugin re-pins the model
+to the lane's own - but the file's `prompt` and `description` still win
+either way, so a shadowing file still takes the lane's instructions away.
+
+So this kit keeps the model in the generated config and the prompt body in
+`prompts/`, referenced with `{file:...}`. `oc-harness verify` fails when an
+installed agent file shadows a lane, and `oc-harness install` removes the agent
+files an earlier version of this kit left behind.
+
+There are **four** directories a shadow can hide in, and opencode reads all
+four: `agent/` and `agents/`, in the config dir and in `.opencode/`. When the
+same name is in both `agent/` and `agents/`, the plural directory wins. A
+checker that only looked at `agents/` missed half of them.
+
+The reference also has to be absolute or start with `~`: a relative
+`{file:./prompts/x.md}` is silently ignored, and a lane with no instructions
+still runs.
+
+## A request is one assistant message, and the counter used to count three
+
+The lane counter decides which of the ten lanes earn their place, so it has to
+count the way the work happens.
+
+`opencode` emits `message.updated` several times for a single assistant
+message: once when the message is created, once per streaming update, and
+once when it completes. A counter that wrote a record per event reported three
+requests for every request made. The record now carries the message id and the
+reader merges on it, so one assistant message is one request.
+
+The `chat.message` hook looked like the natural place to count a request
+before the model answered, so that a call that never came back still counted.
+It cannot: on OpenCode 1.19 its `agent` field is `undefined`, so it cannot
+attribute a request to a lane at all. It is not used for this, because a
+second counter that cannot be correlated with the first double-counts every
+request.
+
+The file is also found by **walking up** from the working directory. The plugin
+writes it to the project root, and reading `process.cwd()` alone reported
+"never used" for every lane whenever the command was run from a subdirectory.
+
+## The free tier cannot read a PDF, an audio file or a video
+
+Three capabilities the catalogue advertises are not reachable, and no lane
+claims them:
+
+- **PDF.** The provider's endpoint rejects the request before the model sees
+  it: `content part type "file" is not supported; only text and image_url
+  are`. A model asked about the PDF instead suggests running `pdftotext`.
+- **Audio and video.** OpenCode 1.19 refuses to read a binary file at all:
+  `Cannot read binary file: ...m4a`. The attachment never reaches the model,
+  which then answers as if it had heard nothing.
+
+So a document is extracted locally and the **text** reaches the `doc` lane.
+MiMo publishes audio input and is in the fleet for its image reading, not its
+audio.
+
+## One model hangs on a file attachment, and only on an attachment
+
+`nemotron-3.5-super-vl-free` is the catalogue's vision-language model, and a
+live call with an image never returned: three attempts, 350 seconds, no
+answer. It also hung on a plain `.txt` attached to the prompt.
+
+It does **not** hang on a tool read. The `sweep` lane on Super VL answered a
+`grep` sweep in 4.2 seconds average over three requests, with no trouble at
+all. The rule is therefore narrower than "Super VL is broken": never hand it a
+file as an attachment. On a plain prompt it is the fastest reasoning-off route
+on the tier, and it is the only model that publishes a `none` effort level,
+which makes "reasoning off" a job of its own.
+
+The same call on MiniMax answered in 7 seconds and read the text out of the
+image correctly.
+
+## One shared reserve, sized by the narrowest lane
+
+`compaction.reserved` is a single number for the whole config, and a fleet
+mixes a 1M model with 200k models. Sizing it by the widest model reserves
+125,829 tokens and leaves every 200k lane with 74,000 usable, which is where
+the lane stops working. It is therefore sized by the **narrowest** lane:
+
+| profile | narrowest lane | input cap | reserved | prune at |
+|---|---|---|---|---|
+| `fleet-safe` | DeepSeek V4.1 / GLM 5.3 | 200,000 | 24,000 | 176,000 |
+| `fleet-all` | Big Pickle | 160,000 | 19,200 | 140,800 |
+
+The cost is that a lane with a wide window gets a thinner buffer than it would
+like. That is the right direction to be wrong in: a buffer that is too small
+means compaction happens a little earlier, and a buffer that is too large
+means a lane cannot work at all.
+
+## Ten lanes is at the edge of what a selector can carry
+
+The catalogue of eleven production harnesses in the source study
+(arXiv:2609.00006) tops out at seven agent entries — OpenCode's own four
+named agents plus three hidden utility ones. Claude Code ships three, Codex
+two, OpenHands four, Mistral Vibe one delegable profile.
+
+The guidance that decides the number is explicit: a flat catalogue forces the
+planner to select one-of-N at every turn, and selection accuracy degrades as N
+grows. The measured figures are for tool catalogues — 7-85% accuracy drops as
+a catalogue expands, and Anthropic's own deferred tool search lifting Opus 4.5
+from 79.5% to 88.1% selection accuracy by narrowing the choice to 3-5 options
+— and no corpus system measures agent count the same way.
+
+Ten lanes sits at the boundary rather than past it, and the reason it is
+tolerable is that the descriptions do not overlap: each lane names a different
+job, and the failure mode of a large catalogue is similar descriptions, not
+many descriptions. `oc-harness lanes` counts the requests so the fleet can be
+cut to what earns its place, rather than defended on principle.
+
+## Measuring a lane takes a delegation, not a flag
+
+`opencode run --agent <lane>` only runs a **primary** agent. Handed a
+subagent lane, it silently falls back to the default agent, and the run
+succeeds - so the measurement appears to work and says nothing.
+
+A subagent lane is exercised by delegating to it from a primary one:
+
+```
+opencode run --agent build "Use the task tool with subagent_type=reviewer to ..."
+```
+
+The `plan` and `build` lanes are primary, so they are run directly with
+`--agent`. The other eight are delegated to.
+
+## A model that inherits the caller's model is not a model at all
+
+A lane whose model is spent should move down its own chain, and a fleet has
+ten models, so one dead route must not take the other nine down with it.
+
+The first version of the router replaced the **whole profile** when the
+session's own model was spent, which set every lane of the fallback profile
+onto one model and left the other five lanes pointing at routes that were also
+spent. The docstring on that function promised the opposite. A fleet now keeps
+its lanes: the session model moves, each lane moves down its own chain, and
+the router publishes the model it chose so the effort hook pins the session to
+that one rather than back to the base model that is spent.
+
+
 ## Retry on 429 is deliberately not attempted
 
 Zen free routes return `429 FreeUsageLimitError`, and #42977 documents models
@@ -113,9 +292,15 @@ From one install's 20-day history, free model slots turned over in days:
 | `nemotron-3-ultra-free` | 3 days |
 | `muse-spark-1.3-contributor-free` | still running at 20 days |
 
+The tier turned over again since: four of this kit's five original profiles
+(`space-bunny-free`, `x-preview-f-free`, `deepseek-v4-flash-free`,
+`muse-spark-1.3-contributor-free`) were all withdrawn within a month of
+shipping, and the default profile pointed at a model that no longer existed.
+
 Zen states free models are available "for a limited time" with no date. Treat
 profiles as perishable: run `oc-harness doctor`, which re-checks each profile
-against live metadata and reports drift.
+against live metadata and reports drift, and which also reports a lane whose
+whole chain has left the catalogue.
 
 ## A model-driven compressor is not assumed to work
 

package/docs/RESEARCH.md

@@ -146,9 +146,10 @@ unfalsified. `eval` now prints the figure as `PROJECTION` with `measured: no`,
 and `baseline` reports per-model-per-variant medians so the claim becomes real
 once the tiering has actually been running.
 
-## Why Space Bunny Free is the default
+## Why the default is a fleet
 
-Scanning free models on OpenCode Zen for context, effort, and privacy together:
+Scanning free models on OpenCode Zen for context, effort, and privacy
+together, in the tier of 2026-10-07:
 
 | model | context | effort levels | retention |
 |---|---|---|---|
@@ -171,6 +172,27 @@ coverage and no public identity. Zero-retention and a `max` effort tier were
 judged worth those risks; that judgement is a default, not a fact, and
 `oc-harness use` makes reversing it one flag.
 
+**That default did not survive the month.** Four of those five models were
+withdrawn, including the one the default profile named. The tier of
+2026-10-19 has ten free models with ten different strengths, and no single
+one of them is best at everything: on the first pass of measurements Beam
+answered in 4-6 seconds, GLM took 16-27 and was the careful one, and Nemotron
+Super VL was the only model publishing a `none` effort level. The default
+became a **fleet** — ten jobs, ten models, one session — with a privacy
+ceiling rather than a single model. The reasoning and the measurements are in
+[`ROUTING.md`](ROUTING.md); the source study of the eleven production
+harnesses is in the section above.
+
+**The first fleet's numbers were wrong, and measuring it again is what found
+out.** Re-measured on 2026-10-20, lane by lane, over live calls: GLM is
+4.4-5.8 seconds and not 16-27 (the old figure came from a much larger
+prompt); MiMo reads an image in 19.2 seconds and not 8; and Nemotron Super VL
+does **not** hang on a tool read, only on a file attached to the prompt, which
+means the sweep lane is sound. The measurement also showed the safe fleet
+giving up more than it needed to: two lanes were on a model the ceiling had
+forced them onto rather than the best one available for that job. The numbers,
+and what changed because of them, are in [`ROUTING.md`](ROUTING.md).
+
 ## How the privacy list was assembled
 
 From the Privacy section of the OpenCode Zen docs, which states a general
@@ -180,6 +202,17 @@ not named in the exception list and so fall under the general policy. Those two
 are marked in `retention.yml` as inferred rather than quoted, because the
 distinction matters if you are handling someone else's code.
 
+Both of those models have since been withdrawn, and `retention.yml` was
+rewritten against the page on 2026-10-19 to match the tier that exists now:
+seven new entries, four dead models dropped, and every value quoted rather
+than inferred.
+
+The tier of 2026-10-19 needed a third value. `beam-free` does not train on
+prompts but "retains them for 30 days for safety reasons", which is neither
+"keeps nothing" nor "may train". Calling that zero-retention would have been
+the same kind of claim the file exists to prevent, so `retained` was added and
+the fleet's ceiling can be set to either side of it.
+
 ## What the ecosystem already covers
 
 Checked before writing any of the above, so the kit composes instead of
@@ -199,12 +232,54 @@ duplicating:
 The gap is the seam between a provider catalog and a config file. That is what
 this kit is for.
 
+## How many lanes a fleet can carry
+
+The fleet question was not answered by taste. Six sources, and what each one
+says:
+
+| source | what it says |
+|---|---|
+| arXiv:2609.00006, eleven production harnesses | The largest agent catalogue in the corpus is OpenCode's own, four named agents plus three hidden utility ones. Claude Code ships three, Codex two, OpenHands four, Mistral Vibe one delegable profile. **No harness in the corpus ships ten.** |
+| The same paper, Recommendation 12 | "Stay single-agent until you can point to a concrete breadth-first exploration phase where parallel context isolation clearly beats serial search." The evidence cited: multi-agent systems use ~15x more tokens than a chat baseline, and "most coding tasks involve fewer truly parallelizable tasks than research". |
+| The same paper, §7.2 | Per-agent specialization is "keyed on agent profile rather than on model generation" — the corpus keeps the agent catalogue small and expresses model differences as a *field*, not as more agents. |
+| LangChain's multi-agent guide | The explicit threshold: a system prompt enumerating the agents is right for "small, static agent lists (< 10 agents)"; above ten, agent discovery has to become a tool. |
+| `agentpatterns.ai`, on tool catalogues | Selection accuracy degrades as the catalogue grows: 7-85% drops as a tool catalogue expands, and Anthropic's own deferred tool search lifts Opus 4.5 from 79.5% to 88.1% selection accuracy by narrowing the choice to 3-5 options. |
+| `code-yeongyu/oh-my-openagent` (70k★, an OpenCode plugin) | The real counter-example, and the closest precedent: **four curated agents and ten categories**, each with its own ordered model chain, where the main agent picks a category and never a model name. It works because the categories are jobs, not models. |
+
+What they add up to: ten lanes sits at the edge rather than past it, and the
+reason it is tolerable is that the descriptions do not overlap. The failure
+mode of a large catalogue is similar descriptions, not many descriptions.
+
+So the fleet is built the way `omo` builds it — a job per lane, a chain per
+lane — and the number is treated as a hypothesis rather than a constant.
+`oc-harness lanes` counts the requests, and a lane nobody uses is cut.
+
+The other thing the sources settled is where the model lives. OpenCode's Task
+tool takes a free-string `subagent_type` and no model parameter, so the only
+way to put a different model behind a delegation is to define an agent with
+that model. `agent.<lane>` in the generated config does that, and it is also
+the only place the model can live without an agent markdown file shadowing it
+and quietly replacing it.
+
 ## Sources
 
 - arXiv:2609.00006 — Harness Engineering, eleven-harness source study
 - `https://opencode.ai/docs/zen/` — pricing, retention, free-tier terms
-- `https://opencode.ai/config.json` — the resolved config schema for 1.18.35
-- `@opencode-ai/plugin@1.18.35` `dist/index.d.ts` — the hook surface (the
-  version actually installed; re-check against it after any plugin bump)
+- `https://opencode.ai/config.json` — the resolved config schema
+- `@opencode-ai/plugin` `dist/index.d.ts` — the hook surface (the version
+  actually installed; re-check against it after any plugin bump)
 - `https://models.dev/api.json` — provider and model metadata
 - `anomalyco/opencode` issue #42977 — free-route 429 behaviour
+- `https://docs.langchain.com/oss/python/langchain/multi-agent/subagents` —
+  the agent-catalogue threshold
+- `https://github.com/1lucascb/agentpatterns.ai` — selection accuracy against
+  catalogue size
+- `https://github.com/code-yeongyu/oh-my-openagent` — a fleet of categories
+  with per-category model chains, in OpenCode
+- OpenCode 1.19.0, measured: agent-file precedence, the four directories it
+  reads agents from, `{file:...}` resolution, binary-file refusal, the
+  `chat.message` hook's missing `agent` field, how many times
+  `message.updated` fires per message, and a two-model delegation inside one
+  session
+- The live free tier, measured 2026-10-20: one request per lane on both
+  fleets, ten lanes on each, through real delegations

package/docs/ROUTING.md

@@ -0,0 +1,254 @@
+# Routing: ten jobs, ten free models
+
+The fleet is the point of this kit. One session, ten lanes, ten models, and a
+human who never switches a model by hand.
+
+This page records what the lanes are, which model serves each one, and the
+measurements behind those choices. Everything in the tables below was measured
+against the live tier on **2026-10-20** with OpenCode **1.19.0**, and is
+reproducible with `oc-harness doctor` and `oc-harness lanes`.
+
+## The lanes
+
+A **lane** is a job. `lanes.json` says what each job is for and nothing about
+models. A profile says which lanes it enables and which model serves each one.
+
+| lane | job | model in `fleet-all` | model in `fleet-safe` |
+|---|---|---|---|
+| `build` | write and verify the change | minimax-m3.1-flash-free | minimax-m3.1-flash-free |
+| `plan` | turn a request into a plan | beam-free | deepseek-v4.1-flash-free |
+| `reviewer` | read a change in two passes | nemotron-3-ultra-free | glm-5.3-flash-free |
+| `locate` | find where something lives | nemotron-3.5-lightning-free | deepseek-v4.1-flash-free |
+| `verify` | run the project's checks | big-pickle | deepseek-v4.1-flash-free |
+| `vision` | read an image or a screenshot | mimo-v2.6-flash-free | minimax-m3.1-flash-free |
+| `doc` | read a long document or a spec | glm-5.3-flash-free | glm-5.3-flash-free |
+| `schema` | produce JSON or a JSON schema | deepseek-v4.1-flash-free | deepseek-v4.1-flash-free |
+| `sweep` | sweep a lot of code mechanically | nemotron-3.5-super-vl-free | longcat-2.5-preview-free |
+| `longform` | read a megabyte, or write alternatives | longcat-2.5-preview-free | longcat-2.5-preview-free |
+
+`fleet-all` gives every lane the model built for it: ten jobs, ten models,
+one to one. `fleet-safe` is the same fleet under a zero-retention ceiling.
+
+**Six of the ten lanes run on a second-choice model under that ceiling**:
+plan, reviewer, locate, verify, vision and sweep. That is the price of the
+ceiling, and it is worth paying only when the model that takes over is the
+best one available *for that job*, which is why the two fleets order their
+chains differently (see below).
+
+## Measured, per lane
+
+Every number here is a live call, not a catalog reading. A **request** is one
+assistant message, which is one round trip to the provider; a lane that makes
+three tool calls makes three requests. `avg ms` covers the requests that
+finished.
+
+`fleet-all`, 2026-10-20:
+
+| lane | model | requests | avg ms | max ms |
+|---|---|---|---|---|
+| `build` | minimax-m3.1-flash-free | 21 | 10104 | 34478 |
+| `plan` | beam-free | 7 | 2624 | 4186 |
+| `reviewer` | nemotron-3-ultra-free | 2 | 4716 | 5376 |
+| `locate` | nemotron-3.5-lightning-free | 4 | 3680 | 5523 |
+| `verify` | big-pickle | 2 | 6546 | 7964 |
+| `vision` | mimo-v2.6-flash-free | 2 | 19167 | 23813 |
+| `doc` | glm-5.3-flash-free | 2 | 5421 | 7620 |
+| `schema` | deepseek-v4.1-flash-free | 1 | 3390 | 3390 |
+| `sweep` | nemotron-3.5-super-vl-free | 3 | 4221 | 4951 |
+| `longform` | longcat-2.5-preview-free | 2 | 9382 | 11572 |
+
+`fleet-safe`, 2026-10-20:
+
+| lane | model | requests | avg ms | max ms |
+|---|---|---|---|---|
+| `build` | minimax-m3.1-flash-free | 42 | 8210 | 42459 |
+| `plan` | deepseek-v4.1-flash-free | 6 | 5106 | 7057 |
+| `reviewer` | glm-5.3-flash-free | 2 | 5757 | 7982 |
+| `locate` | deepseek-v4.1-flash-free | 5 | 3612 | 4380 |
+| `verify` | deepseek-v4.1-flash-free | 2 | 3376 | 3997 |
+| `vision` | minimax-m3.1-flash-free | 2 | 7735 | 12190 |
+| `doc` | glm-5.3-flash-free | 7 | 4372 | 11921 |
+| `schema` | deepseek-v4.1-flash-free | 1 | 5195 | 5195 |
+| `sweep` | longcat-2.5-preview-free | 2 | 7291 | 7477 |
+| `longform` | longcat-2.5-preview-free | 2 | 13177 | 13709 |
+
+The `build` rows are not comparable with the others: they include the turns
+that did the delegating, so they count the work of the other nine lanes. A
+one-line `build` reply on its own measured **3130 ms** and **21137 ms** on a
+cold start.
+
+**What the safe ceiling costs, measured rather than assumed.** Planning is the
+lane that pays: 2624 ms on Beam against 5106 ms on DeepSeek, about twice the
+wait. Reviewing barely pays at all: 4716 ms on Nemotron 3 Ultra against 5757
+ms on GLM. Locating and verifying get *faster*, because DeepSeek publishes a
+`low` effort level and Big Pickle publishes none at all.
+
+And one lane gets faster rather than slower. MiMo reads an image in 19.2 s;
+MiniMax reads the same image in 7.7 s. The unrestricted fleet put `vision` on
+the slower model because MiMo is the tier's dedicated image reader, and under
+the ceiling `vision` moves to MiniMax - which turns out to be the better
+choice anyway.
+
+## What each model is for
+
+| model | measured | why it owns that lane |
+|---|---|---|
+| minimax-m3.1-flash-free | 3.1 s for a one-line reply, 512k output cap, reads an image in 7.7 s | The widest output cap on the tier and a stable tool call, so the lane that writes code fits, and it is also the fastest measured image reader. |
+| beam-free | **2.6 s average over 7 requests, the fastest on the tier**, 1M context, structured output | Planning is a reading-and-reasoning job with a long context and a structured answer. Nothing else on the tier does it faster. |
+| nemotron-3-ultra-free | 4.7 s average, but **34 s on a cold first request** | The largest open MoE available, which is what a two-pass review needs. The cold start is worth knowing about before blaming the route. |
+| nemotron-3.5-lightning-free | 3.7 s average over 4 requests, 5.5 s at worst, no selectable effort | No effort level, so it spends nothing on reasoning, and it can emit a file larger than 128k tokens. |
+| big-pickle | 6.5 s average over 2 requests, structured output, no effort levels, no images | Stable, and it answers in a shape a program can read. |
+| mimo-v2.6-flash-free | **19.2 s average with an image**, 23.8 s at worst - the slowest lane on the tier | It reads images correctly, which is the job. It publishes audio input too, and that path is unreachable (see below). |
+| glm-5.3-flash-free | 4.4-5.8 s, structured output, 3 effort levels | Careful and quick enough. A previous measurement put it at 16-27 s on a larger prompt; on the work a lane actually does it is five seconds. |
+| deepseek-v4.1-flash-free | 3.4-5.2 s, structured output, reasoning + agentic coding | The natural lane for JSON a program has to parse, and the best all-rounder inside a zero-retention ceiling. |
+| nemotron-3.5-super-vl-free | 4.2 s average over 3 requests, **the only model publishing a `none` effort level** | A lane that turns reasoning off entirely is a job of its own, and no other model can do it. |
+| longcat-2.5-preview-free | 9.4-13.2 s, 1M context, reads images, temperature on | The long-context lane. A preview endpoint: it can be withdrawn without a rename. |
+
+## What the tier cannot do
+
+Three capabilities the catalog advertises are not reachable, and no lane claims
+them:
+
+- **No free model reads a PDF.** The provider's endpoint rejects it before the
+  model sees it: `content part type "file" is not supported; only text and
+  image_url are`. OpenCode 1.19 also refuses to read a binary file at all -
+  `Cannot read binary file`. A document is therefore extracted locally
+  (`pdftotext`, or a library) and the **text** is what reaches the `doc` lane.
+  The `doc` prompt says so, and asks for the text rather than the path.
+- **No free model receives audio or video.** The same binary-file refusal
+  applies. MiMo publishes audio input and MiMo-V2.6-Flash is in the fleet for
+  its image reading, not its audio.
+- **`nemotron-3.5-super-vl-free` hangs on a file ATTACHMENT, and only on an
+  attachment.** A live call with an image never returned: three attempts, 350
+  seconds, no answer. It also hung on a plain `.txt` attached to the prompt.
+  It does **not** hang on a tool read: the `sweep` lane on Super VL answered a
+  `grep` sweep in 4.2 s average over three requests, with no trouble at all.
+  So the model is usable, and the rule is narrower than "Super VL is broken":
+  never hand it a file as an attachment, and it is the reasoning-off lane.
+
+## The chains
+
+A lane's model is a chain, not a pin. Free routes get withdrawn in days - four
+of this kit's five original profiles were dead within a month - so every lane
+lists the models that could serve it, best first.
+
+```
+build   minimax-m3.1-flash-free → deepseek-v4.1-flash-free → longcat-2.5-preview-free
+plan    beam-free               → deepseek-v4.1-flash-free → longcat-2.5-preview-free
+...
+```
+
+A chain is ordered **inside its own profile's ceiling**, not globally. That is
+the one thing the first version of the safe fleet got wrong: it inherited the
+unrestricted fleet's order, so bumping into the zero-retention ceiling dropped
+every lane onto whatever rung happened to be third. Two lanes were genuinely
+mis-served by that:
+
+- `locate` asked for `low` effort and landed on a model that publishes no
+  effort levels at all, so the request was dropped on the floor. It now lands
+  on DeepSeek, which publishes `low`, and measures 3612 ms.
+- `vision` landed on the same model, at 9-13 s, when MiniMax reads the same
+  image in 7.7 s.
+
+The ceiling is also the **privacy lever**. A profile declares a `maxRetention`
+ceiling, and a lane takes the first rung at or below it:
+
+```
+fleet-safe   maxRetention: zero-retention   → every lane lands on a zero-retention model
+fleet-all    maxRetention: may-train        → every lane lands on the model built for it
+```
+
+That is why one fleet file can be honest about privacy and still cover ten
+jobs: the ceiling changes which rung wins, not which jobs exist. A chain may
+not name a model above its own profile's ceiling at all, not even as a later
+rung - a chain that could reach a training provider is a chain whose failover
+would break the promise the profile makes. A test enforces that.
+
+`oc-harness doctor` reports a lane whose whole chain has left the catalogue,
+which is a lane with no model at all - something no amount of `refresh` on the
+base profile would reveal.
+
+### What the safe fleet gives up
+
+`sweep` is the one lane that loses its reason to exist under the ceiling.
+Super VL is the only model on the tier that publishes a `none` effort level,
+so "reasoning off" is a job of its own; and Super VL is a may-train provider,
+so the ceiling excludes it. Under `fleet-safe` the lane falls back to
+LongCat, which publishes no effort levels at all, and it is a second `locate`
+with a 1M context window. The lane is kept, because `oc-harness lanes` should
+decide that from measurements rather than from a guess - but the docs say out
+loud that the capability is gone.
+
+## Measuring, and cutting
+
+Ten lanes is a hypothesis. The only way to know which of them earn their place
+is to count the requests:
+
+```
+$ oc-harness lanes
+
+  lane            reqs     avg ms  model
+  ----------------------------------------------------------------
+  plan                7       2624  beam-free
+  build              21      10104  minimax-m3.1-flash-free
+  reviewer            2       4716  nemotron-3-ultra-free
+  ...
+  8 lane(s) were never used    cut candidates, not defects
+```
+
+A lane that is never used is a description the model reads on every turn and a
+free model doing nothing. Cut it from the profile's `roles`, and the lane
+leaves the config with it.
+
+The counter reads `.space/telemetry.jsonl` in the project, written by the
+plugin: one record per assistant message, with the lane, the model and the
+duration. Two things about it are worth knowing, because both were wrong at
+some point and both change the number:
+
+- **A request is one assistant message.** `opencode` emits `message.updated`
+  several times per message, so a counter that read every event reported three
+  requests for every request made. The record carries the message id and the
+  reader merges on it.
+- **The file is found by walking up from the working directory.** The plugin
+  writes it to the project root; reading `process.cwd()` alone reported "never
+  used" for every lane whenever the command was run from a subdirectory.
+
+## Why the model lives in the config
+
+An agent file of the same name replaces the config entry wholesale, and a file
+with no `model:` line makes the agent inherit the caller's model. Both were
+observed on OpenCode 1.19, with the plugin out of the way (`--pure`):
+
+```
+agent file:  model: opencode/beam-free
+config:      agent.build.model: opencode/minimax-m3.1-flash-free
+result:      the agent file's model wins
+```
+
+So the lanes live in `agent.<lane>` in the generated config, their prompt
+bodies live in `prompts/` and are referenced with `{file:...}`, and
+`oc-harness verify` fails when an installed agent file shadows a lane.
+
+The path in that reference has to be absolute or start with `~`. A relative
+path is silently ignored, and a lane with no instructions still runs, which is
+the worst of both.
+
+`verify` scans four directories, because opencode reads four: `agent/` and
+`agents/`, in the config dir and in `.opencode/`. A shadow in the singular
+directory is exactly as dangerous as one in the plural one.
+
+## What the fleet costs
+
+- **Ten descriptions in the model's context.** Every lane's name and
+  description is read on every turn. The descriptions are deliberately
+  non-overlapping, because overlapping ones are what breaks selection: the
+  measured failure is a model choosing the wrong lane.
+- **One extra model call per hand-off.** A delegated lane is a fresh context
+  window and a fresh request. Delegating a one-line lookup costs more than
+  doing it.
+- **A shared reserve.** `compaction.reserved` is one number for the whole
+  config, so it is sized by the **narrowest** lane: 24,000 tokens for
+  `fleet-safe`, whose narrowest lane has a 200k window, and 19,200 for
+  `fleet-all`, whose narrowest lane is Big Pickle at a 160k input cap.
+  Sizing it by the widest model instead would reserve 125,829 tokens and
+  leave every 200k lane with 74k usable.