opencode-zen-freex 0.2.16 → 0.2.18

package/MAINTAINING.md

@@ -173,6 +173,12 @@ bun run capture            # writes it
 bun run check:gate         # did that fix it
 ```
 
+`bun test` reads the tree; a running gateway does not. Magpie's plugin host
+imports the plugin once, when it starts, and no `magpie plugin` subcommand
+reloads it — pointing a gateway at this tree does not make it watch the tree, so
+a change to be measured through a live gateway needs that gateway restarted
+first.
+
 `check:gate` is the one that matters. It asks each generation twice, because the
 plugin sends two shapes and Zen does not answer them alike:
 
@@ -304,6 +310,22 @@ it. Rewriting the parameters as well looks tidier and breaks the agent.
 **Replacing the wording with something of your own.** That is what 0.1.5 and
 earlier did, and it is a guaranteed refusal.
 
+**Leaving out a call the agent has no tool for.** A call whose name folded onto
+no declared tool was dropped from the reply with a note in its text, and a reply
+whose every call was dropped ended as a plain `stop`. An autonomous host reads
+that as an answer: DeepSeek Harness ended 16 of the 19 such turns one user
+measured and the model never saw an error it could correct
+(`magpie-community/plugins#209`; upstream made the same change in its 0.1.11).
+The name now goes on as the model wrote it — same name, same id, same arguments,
+a tool-call finish — and the host answers it with its own unknown-tool error,
+which is the correction signal. A name two declared tools fold to is still never
+guessed: it goes on as called. Only a call with **no name** is left out now, and
+`droppedNote` says so. Measured 2026-10-18 through a local magpie pointed at
+this tree, `deepseek-v4.1-flash-free`, declaring `pwsh` and calling `bash`:
+before, `200` + `finish_reason: "stop"` + the note; after, `200` + `tool_calls`
++ `bash` carrying its id. Do not put the drop back to "protect" a host —
+answering is the host's to do, and a silent `stop` is the failure this replaced.
+
 **Merging a tool call's frames over its id.** The route puts `"id": null` on
 the continuation frames of a call whose first frame named it (measured
 2026-10-17 on `deepseek-v4.1-flash-free`), and a host that keys a tool result
@@ -315,6 +337,17 @@ invented one. Both live in `tool-response.mjs` — the merge's keep, and
 `ensureCallIDs` at the two places a call is published — and `stream.mjs`'s
 collapse reads the same rule.
 
+Both of those places publish the **chat** shape only. A Responses or Messages
+reply whose call carries no id of its own is handed on as it stands — no id, no
+`call_id` — and both protocols require the field. Measured 2026-10-18, no free
+model is served on either route: the tier's own `/models` listed none,
+`muse-spark-1.3-contributor-free` answered 410 `ModelDeprecated` and the four
+Messages models answered "Model is unavailable". So the gap is real but not
+reachable today, and the sentence above — every published call leaves with a
+non-empty id — is chat's. A free model on either route puts it back in scope,
+and then the id has to be minted once per call across its added, done and
+terminal copies, the way the dropped ones already are.
+
 **Trusting one observation.** The gate is not steady: it moved more than once in
 a day while this was being worked out, and identical requests were answered both
 ways minutes apart. Anything measured once is not a fact. Measure it three times,

package/README.md

@@ -64,8 +64,8 @@ bun run capture             # 确认差异后才写入
 
 发往 `https://opencode.ai/inference/v1`，按每个模型原生协议走（Chat Completions / Responses / Anthropic Messages），流式与普通 JSON 都支持。
 
-- **宿主的工具不会被丢**：Zen 调 OpenCode 工具名时，按大小写与 `_`/`-` 对上唯一匹配的宿主工具（`bash`↔`Bash`、`todowrite`↔`todo_write`）；对不上就略去并在正文说明。工具仍在宿主执行，调用一律带非空 id。
-- **只借 OpenCode 的样子**：请求头、User-Agent、工具必须同属一代（`bash`/`glob`/`grep`/`read` 是 1.x，`shell`/`read` 是 2.x）；宿主缺的 `required` 工具由插件补发描述（背后没有实现，正文注明），宿主自带的 User-Agent 原样透传。
+- **对不上的名字照样交给宿主**：Zen 调 OpenCode 工具名时，按大小写与 `_`/`-` 对上唯一匹配的宿主工具（`bash`↔`Bash`、`todowrite`↔`todo_write`）；对不上或有歧义时**不猜也不丢**，按模型写的名字、原样的 id 与参数送达宿主，由宿主回它自己的"没有这个工具"，模型据此改名重来。只有**没有名字**的调用会被略去，并在正文说明。工具仍在宿主执行，调用一律带非空 id。
+- **只借 OpenCode 的样子**：请求头、User-Agent、工具必须同属一代（`bash`/`glob`/`grep`/`read` 是 1.x，`shell`/`read` 是 2.x）；宿主缺的 `required` 工具由插件补发描述（背后没有实现，描述里注明别调它），宿主自带的 User-Agent 原样透传。
 - **请求头是刻意挑出的最小集合**：`content-type`、`accept`、`user-agent`、`x-opencode-project`、`x-opencode-session(-id)`（同一 id）、`x-opencode-client: cli`、`authorization: Bearer public`（走 Messages 时 `x-api-key: public` + `anthropic-version`；`anthropic-beta` 这个头插件自己从不设置：只在宿主已经发了的时候原样透传）。**不要加别的头**：两个各自无害的组合起来也会被拒——单试一个得不出结论。
 - **会话 id** 按会话首条消息生成并记住，同一会话各轮共用；宿主的 id 形状合法就原样传。
 - **提前掐断的流**：有内容且无未完成调用 → 按普通回答收尾并注明截断，再问会续；否则请求失败，错误写明回复 id 与已收字节。Messages / Responses 被截断同样失败。

package/limits.mjs

@@ -471,7 +471,13 @@ export function limitOverrides(
     // catalogue never made, feeding the staleness compare and the raise-only
     // check with a number nobody declared.
     const declaredValue = declared && Object.hasOwn(declared, axis) ? declared[axis] : undefined;
-    const entry = record?.[axis];
+    // Own property, the same rule as the two lines around it. Read through the
+    // prototype, an axis the record merely inherits — from a table built with
+    // `Object.create`, or from a polluted `Object.prototype` — read exactly like
+    // a measurement: it passed the guard below, because the guard is about the
+    // declaration and not about the record, and it then took an override past
+    // the staleness check and past the raise-only rule.
+    const entry = record && Object.hasOwn(record, axis) ? record[axis] : undefined;
     // Only the axes a refusal names have a live form — a window and a
     // completion ceiling. An input axis is answered from the table alone: the
     // refusals this route sends name the window that bounds it, never an input

package/models.mjs

@@ -32,17 +32,55 @@ function sdkProtocol(npm) {
   if (npm?.includes("openai-compatible")) return "chat";
 }
 
+// Whether a value the catalogue wrote is a description of a model, as opposed to
+// a row it could not fill in. `null` is the shape the catalogue uses for the
+// latter, and an array is the same fact: `typeof []` is `"object"`, but the
+// catalogue writes one row per model and a list is not a row — every axis a
+// description carries is absent from it, so reading one as a description reads
+// nothing as something.
+//
+// The same test, by rule, as `provider.mjs`'s own `describesModel` — each file
+// keeps its own name for it, and this comment is where the two names are tied
+// together. The reader there decides whether a row may stand in for a model, and
+// the two sides deciding differently about one row is a model whose fate depends
+// on which file looked at it. This one is this file's own — the two are kept in
+// step by their comments and their tests, not by a shared export, so neither
+// file's public surface grows for the other's sake.
+//
+// Exported nowhere, deliberately: a test asks about the rule through the models
+// it produces, which is the thing the rule is for.
+function isDescription(row) {
+  return typeof row === "object" && row !== null && !Array.isArray(row);
+}
+
 // Set, and not merely present: the catalogue writes both a missing date and an
 // explicit null, and neither retires a model. A blank string is not a date
 // either — see `isSet` below, which is the same rule stated for the two axes
 // the retirement checks read.
 const hasValue = (value) => value !== null && value !== undefined;
 
+// Whether what the catalogue wrote is a container — a list, an object, a
+// function — rather than the single value these fields are. A status is a word
+// and a date is a date; `["2026-01-01"]` is neither, and `String` writes a list
+// as one non-empty string, so a field nobody filled in passed the "does it say
+// something" test below and retired a model: it left the offered list with
+// nothing in the table and nothing in a note to say why, which is the silent
+// loss every shape rule in this file exists to prevent. `typeof null` is
+// `"object"`, so the null `hasValue` refuses on its own account is refused here
+// as well.
+const isContainer = (value) => typeof value === "object" || typeof value === "function";
+
 // A status has to say something to be one. The catalogue writes an empty string
 // as well as a null, and either one used to stand in front of the `lifecycle`
 // that does retire the model, so a model retired through `lifecycle` kept being
 // offered. A status that is set — "active" included — is still read as itself.
-const isSet = (value) => hasValue(value) && String(value).trim() !== "";
+//
+// The shape of what was written is part of "says something": a list or an object
+// is not a status and not a date, and reading one as either is how a field that
+// states nothing retired a model. `hasValue` is left as it is — "was anything
+// written here at all" and "does what was written say something" are two rules,
+// and only this one is about the shape of the answer.
+const isSet = (value) => hasValue(value) && !isContainer(value) && String(value).trim() !== "";
 
 // A status ends a model when it says the model is gone: "retired" and
 // "disabled" are endings. "deprecated" is not one — it says the catalogue
@@ -104,7 +142,27 @@ function protocolFor(id, model, raw, provider, protocols) {
   // name, and `protocols["__proto__"]` would be an inherited protocol nobody
   // wrote. What the docs actually say about an id is an own property or nothing.
   if (Object.hasOwn(protocols, id)) return protocols[id];
-  if (raw) return sdkProtocol(model.provider?.npm ?? provider.npm);
+  // The catalogue resolving to no protocol is not the same fact for both of the
+  // branches below, and they are read in that order for it.
+  //
+  // A catalogue entry whose package maps to no protocol is one this plugin
+  // cannot ask as the catalogue describes it — the "half-described" id, where
+  // the entry exists and its `npm` names a package `SDK` has never heard of.
+  // That is the same hole the `-free` fallback exists for, and it used to be the
+  // one shape the fallback could not reach: the entry was there, so `raw` was
+  // truthy, so the fallback was skipped and the id was dropped silently — while
+  // the very same id with no catalogue entry at all was offered.
+  //
+  // An id whose protocol *was* resolved — by the docs, to a name inside
+  // `PROTOCOLS` that this plugin has no SDK for, `systemone` above all — is a
+  // different fact and never falls through to the guess: the docs have said
+  // what this id speaks, and it is not something this plugin asks. That name
+  // comes back from the lookup above, so it never reaches this branch at all;
+  // what a package that maps to nothing answers is `undefined`, which is what
+  // keeps "no protocol could be read here" apart from "this id is not one this
+  // plugin asks".
+  const catalogProtocol = raw ? sdkProtocol(model.provider?.npm ?? provider.npm) : undefined;
+  if (catalogProtocol !== undefined) return catalogProtocol;
   if (listedFree(id)) return sdkProtocol(provider.npm) ?? "chat";
   return undefined;
 }
@@ -128,8 +186,15 @@ const usable = (value) => Number.isSafeInteger(value) && value > 0;
 // evidence for — each level only contributing axes it can actually state.
 function limitFor(id, declared) {
   const limit = { context: 32768, output: 4096 };
-  for (const [axis, value] of Object.entries(declared ?? {})) if (usable(value)) limit[axis] = value;
-  for (const [axis, value] of Object.entries(limitOverrides(id, declared))) limit[axis] = value;
+  // An axis map has to be one, by the same rule the row is read by. `limit` is
+  // an object of named axes, and `Object.entries` reads a list as its indices:
+  // a row whose `limit` was `[111, 222]` handed the host
+  // `{0: 111, 1: 222, context: 32768, output: 4096}` — axes no catalogue named,
+  // on the one object a host plans a prompt from. The evidence lookup is handed
+  // the same map, so neither level can read an axis off a shape that has none.
+  const axes = isDescription(declared) ? declared : {};
+  for (const [axis, value] of Object.entries(axes)) if (usable(value)) limit[axis] = value;
+  for (const [axis, value] of Object.entries(limitOverrides(id, axes))) limit[axis] = value;
   return limit;
 }
 
@@ -148,15 +213,47 @@ export function buildModels(ids, provider, protocols, baseURL) {
     // describes. An id with no entry here is one the catalogue has not caught up
     // with, which the `-free` rule below is for.
     const catalogue = provider.models ?? {};
-    const raw = Object.hasOwn(catalogue, id) ? catalogue[id] : undefined;
+    // ...and an entry that is not a description describes nothing either, so it
+    // is left unresolved exactly like a missing one instead of being carried out
+    // of this loop as a description. `null` is the shape the catalogue writes
+    // for a row it could not fill in, and a list is the same fact one step
+    // harder to see — see `isDescription` above, which is the rule both sides of
+    // the tree read a row by. Such a row is read as a description by everything
+    // downstream of here too: `provider.mjs` reads `.cost` off
+    // `metadata.models[id]` on the partial-catalogue path, where a `null` is a
+    // TypeError thrown out of a hook a host is waiting on. One dirty row
+    // upstream must not be the whole list: a model is not a thing worth failing
+    // discovery over, and the `-free` name is already this file's rule for an id
+    // the catalogue cannot speak for.
+    //
+    // Skipped rather than reported, and the difference matters: a report would
+    // need a sink on this path, and the only sinks in this tree are
+    // limits.mjs's, which are about limits. What a skipped row costs is a model
+    // the catalogue itself could not describe — no protocol, no limits, no
+    // capabilities — and the models that are described are still offered, which
+    // is the outcome this file exists for. A row this malformed is also visible
+    // where it is made: it is the catalogue's own data, upstream of discovery.
+    const listed = Object.hasOwn(catalogue, id) ? catalogue[id] : undefined;
+    const raw = isDescription(listed) ? listed : undefined;
     const model = raw ?? {};
     const protocol = protocolFor(id, model, raw, provider, protocols);
     if (!isFree(id, model) || !Object.hasOwn(SDK, protocol)) continue;
     const input = model.modalities?.input ?? ["text"];
     const output = model.modalities?.output ?? ["text"];
-    const efforts = (model.reasoning_options ?? [])
-      .filter((option) => option.type === "effort")
-      .flatMap((option) => option.values ?? []);
+    // The efforts a model offers, from the list the catalogue writes them in.
+    // `?? []` covers a list the catalogue left out and nothing else, and this is
+    // the one place in the loop where a wrong shape does not read as a wrong
+    // value but ends the whole call: `.filter` is not a function on an object or
+    // a string, and `option.type` on a `null` element is a TypeError — either one
+    // threw out of `buildModels`, so one dirty row upstream took discovery down
+    // with it, which is the failure the row rule above exists to prevent. A list
+    // that is not a list, and an element that is not a description, are read as
+    // no efforts: the model is still offered, without the variants nobody could
+    // state.
+    const options = Array.isArray(model.reasoning_options) ? model.reasoning_options : [];
+    const efforts = options
+      .filter((option) => isDescription(option) && option.type === "effort")
+      .flatMap((option) => (Array.isArray(option.values) ? option.values : []));
     result[id] = {
       id,
       providerID: PROVIDER,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-zen-freex",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "OpenCode Zen's free models, for hosts that are not OpenCode: the public credential, automatic discovery and native streaming protocols",
   "type": "module",
   "main": "./index.mjs",

package/provider.mjs

@@ -20,8 +20,19 @@ export const CATALOG = "https://models.opencode.ai/api.json";
 const DOCS =
   "https://raw.githubusercontent.com/anomalyco/opencode/dev/services/www/src/docs/content/console/models.mdx";
 const PATHS = { chat: "/chat/completions", responses: "/responses", anthropic: "/messages" };
-// Which generation to present when the host says nothing that tells us: the
-// one opencode-ai publishes as latest.
+// Which generation to present when the host's tools name neither one: a floor,
+// and not a claim about what opencode-ai publishes as latest. What it publishes
+// as latest is 2.x, and `fingerprint.json` captures it — the profile whose
+// channel is `latest`, opencode 2.0.29 — so a comment saying this constant is
+// "the latest generation" would be the one thing here that is not true.
+//
+// It stays 1.x because a default is only reached when nothing identified the
+// host, and 1.x is the generation with more to say for it in that case: its
+// `required` set is the wider one, `normalizeTools` can stand in for every name
+// in it, and `bash`/`glob`/`grep`/`read` are the names a host that never sent
+// `shell` still carries. The floor is what a request falls back to, so it is
+// the generation a body is likeliest to already agree with — not the newest one
+// opencode-ai ships, which only a host that says so should be presented as.
 const DEFAULT_GENERATION = "1.x";
 // Said only of a tool this plugin added, which the agent has no such tool for.
 // It has to be phrased as being about that one tool: a blanket "these tools are
@@ -193,6 +204,47 @@ function httpURL(value) {
   return url.href.replace(/\/+$/, "");
 }
 
+// Whether a catalogue's row for an id is a description of a model at all. The
+// shape rule lives in one place because two readings depend on it — what the
+// catalogue says about an id, and what this plugin kept for it — and a row read
+// as a description by one of them and not the other is a model that disappears
+// without anything saying so.
+//
+// An array is not one, though `typeof []` is `"object"`: the catalogue writes a
+// row per model and never a list, so a list there is a row it could not fill in,
+// the same fact as `null`. `models.mjs` reads a row as a description by the same
+// test; the two must agree.
+function describesModel(row) {
+  return typeof row === "object" && row !== null && !Array.isArray(row);
+}
+
+// Give a model map an entry under an id that came from upstream, as an own
+// property whatever that id is. `map[id] = value` is not enough: for the id
+// `"__proto__"` a plain write is the prototype setter, so the entry is not
+// stored at all and the map's prototype is what changes — the one write here
+// whose id is not this package's to trust. An id may name a model, and it may
+// not reach past the map to do it.
+function own(map, id, value) {
+  if (id === "__proto__") {
+    return Object.defineProperty(map, id, {
+      value,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    });
+  }
+  map[id] = value;
+  return map;
+}
+
+// The catalogue's own row for an id, or `undefined` when the catalogue has none
+// under that name. Own properties only, for the reason the preservation loop
+// states: `models?.["toString"]` is the prototype's function, and reading it as
+// a description of a model invents one nothing described.
+function catalogueRow(metadata, id) {
+  return Object.hasOwn(metadata.models ?? {}, id) ? metadata.models[id] : undefined;
+}
+
 function requirePublic(auth) {
   if (auth?.type !== "api" || auth.key !== "public") {
     throw new Error(
@@ -237,6 +289,10 @@ function normalizeTools(body, protocol) {
   // it carries say which: `shell` is 2.x, `bash` is 1.x. Names move far less
   // often than descriptions do, so this survives a rewording that a pinned
   // User-Agent would not.
+  //
+  // Neither name being there is not the same as 1.x being there: the fallback
+  // is the floor described on DEFAULT_GENERATION, and it decides the names this
+  // loop then fills in as well as the User-Agent `agentForRequest` composes.
   const generation = generationOf(body.tools) ?? DEFAULT_GENERATION;
   // Through `profileFor`, not `PROFILES[generation]`: a capture that holds one
   // generation leaves the other key absent, and the direct read fails below on
@@ -283,10 +339,12 @@ function normalizeTools(body, protocol) {
       continue;
     }
     filled.push(name);
-    // A tool added here has nothing behind it: the agent has no such tool and
-    // a call to it is dropped. Describing it as OpenCode describes it is what
-    // Zen asks for, and it also makes the model want to call it, so the note
-    // goes after the opening Zen reads and before the closing it does not.
+    // A tool added here has nothing behind it: the agent has no such tool, so a
+    // call to it goes to the agent as called and comes back as the agent's own
+    // unknown-tool error, which the model corrects. Describing it as OpenCode
+    // describes it is what Zen asks for, and that description also makes the
+    // model want to call it, so the note goes after the opening Zen reads and
+    // before the closing it does not.
     body.tools.push(shapeOf({ ...spoken, description: `${spoken.description}\n\n${PLACEHOLDER}` }, protocol));
   }
   return { declared, filled, generation };
@@ -421,20 +479,50 @@ export function sessionID(headers, body) {
   }
   if (typeof body.metadata?.session_id === "string") signal ??= body.metadata.session_id;
   if (realSessionID(signal)) return signal;
-  if (!signal) {
-    const messages = body.messages ?? body.input;
-    const first = Array.isArray(messages)
-      ? messages.find((message) => message.role === "user")?.content
-      : messages;
+  const messages = body.messages ?? body.input;
+  const first = Array.isArray(messages)
+    ? messages.find((message) => message.role === "user")?.content
+    : messages;
+  // A host signal is the conversation's own name for itself, so it is the key
+  // on its own and nothing else is folded in beside it: a host that carries a
+  // signal may open a later turn with a shortened history, and keyed by the
+  // opening too, the same conversation would answer a new id the moment its
+  // first message moved. It is also what keeps two conversations that happen to
+  // open with the same words — "hi", a template prompt — in separate Zen
+  // sessions rather than one, and the only thing that can: a host that sends no
+  // signal at all is keyed by its opening below, and two such hosts with one
+  // opening are one key. That limit is pinned in session.test.mjs.
+  //
+  // `first === ""` is separated from `first === undefined` because an empty
+  // opening is a conversation with nothing to key by, which a host signal still
+  // names, while no user message at all is a body with nothing to key by. Read
+  // by truthiness — as `!first` read both — the two are one branch, and the
+  // signal is spent before either can be told from the other.
+  if (signal !== undefined) {
+    const named = createHash("sha256").update(`ses\0${signal}`).digest("hex");
+    return kept(named);
+  }
+  // An empty opening has nothing to key a conversation by, and one cannot be
+  // invented: two of them are indistinguishable from a single one, so any key
+  // derived here would either be shared by unrelated conversations — one Zen
+  // session, with its affinity and its quota — or differ again on the next
+  // turn. Not sharing is the half worth keeping, so this answer is minted per
+  // call exactly as the unnamed case below is.
+  if (first === "" || first === undefined) {
     // Nothing names this conversation: no session header, no metadata, and no
     // user message to key one by. There is no identity to keep for the next
     // turn, so this one gets an id of its own rather than being folded into
     // whichever conversation happened to arrive first — but it is still an id
     // of OpenCode's shape, because that shape is what the tier checks.
-    if (!first) return opencodeID("ses", true);
-    signal = JSON.stringify(first);
+    return opencodeID("ses", true);
   }
-  const key = createHash("sha256").update(`ses\0${signal}`).digest("hex");
+  return kept(createHash("sha256").update(`ses\0${JSON.stringify(first)}`).digest("hex"));
+}
+
+// The id kept for a key, minted on first sight and reused while the key stays
+// in the map. Every caller that names a conversation goes through here, so the
+// eviction of the oldest entry is written once rather than at each key.
+function kept(key) {
   let session = SESSIONS.get(key);
   if (session) {
     SESSIONS.delete(key);
@@ -464,7 +552,92 @@ async function server(_input, options = {}) {
   // a 15 s timeout each on every request that names a model it doesn't know.
   let listedAt = 0;
 
-  async function discover(signal) {
+  // The discovery in flight, and who is waiting for it. Nineteen of the twenty
+  // requests a host makes name a model already known, so this exists for the
+  // ones that do not: without it two of them arriving together both read the
+  // listing, the catalogue and the docs — six upstream reads for one answer —
+  // and then race to write `known`, `metadata` and `protocols`, so which of the
+  // two survives is whichever settled last. One flight, one write.
+  let inflight = null;
+  // What every caller's lease travels on: the reads end when the last caller
+  // waiting for them has gone, and not before. A host that walks away from one
+  // request is still a host, so one caller's abandonment must not cancel an
+  // answer another is still waiting for.
+  const leases = new Set();
+  const interior = new AbortController();
+
+  // This caller's own way out, and its membership of the flight. Resolved when
+  // the caller's own signal aborts; an already-aborted one — for which no
+  // listener fires — ends the lease here rather than holding it for ever.
+  function leased(outward) {
+    const passing = new AbortController();
+    const end = () => passing.abort(outward?.reason ?? new DOMException("Aborted", "AbortError"));
+    if (outward?.aborted) end();
+    else outward?.addEventListener("abort", end, { once: true });
+    leases.add(passing);
+    passing.signal.addEventListener(
+      "abort",
+      () => {
+        leases.delete(passing);
+        if (!leases.size) interior.abort();
+      },
+      { once: true },
+    );
+    return passing.signal;
+  }
+
+  // A caller's wait for a discovery, told which signal says it has given up: a
+  // caller that walks away hears about it from its own abort rather than
+  // inheriting whoever started the flight's, and the flight itself carries on
+  // for the callers still waiting for it.
+  function waiting(signal, named) {
+    return Promise.race([
+      named,
+      new Promise((_, reject) => {
+        const end = () => reject(signal.reason);
+        if (signal.aborted) end();
+        else signal.addEventListener("abort", end, { once: true });
+      }),
+    ]);
+  }
+
+  // The discovery one caller waits for. Every caller takes a lease, the ones
+  // joining a flight included, so giving up is the caller's own.
+  function shared(observed) {
+    const mine = leased(observed);
+    // A flight that has already answered is not one to join: its result
+    // predates this caller's question, which is what the caller is asking
+    // again. `inflight` is kept rather than cleared, so this is the same test
+    // as "is it still running" and does not race the settle below.
+    if (inflight && !inflight.settled) return waiting(mine, inflight.named);
+    const named = reading(interior.signal);
+    const flight = { named, settled: false };
+    inflight = flight;
+    const settled = () => {
+      flight.settled = true;
+    };
+    named.then(settled, settled);
+    return waiting(mine, named);
+  }
+
+  // The one gate in front of the reads, and the reason it is here rather than
+  // at each caller: every path that can start a discovery goes through this
+  // function — a request for a model the last list did not have, the `models()`
+  // hook a host calls when it opens its model chooser, and `refresh()` — so a
+  // budget stated once cannot be spent by one path and bypassed by another. The
+  // hook used to call the reads directly, and every open of the chooser was a
+  // full round of discovery however recently the last one ran.
+  //
+  // A failed ask sets `listedAt` too (see `reading`), so a host whose listing
+  // cannot be read waits out the same interval as one whose listing can.
+  //
+  // `force` is for the one caller that is asking on purpose: `refresh()`.
+  async function discover(signal, { force = false } = {}) {
+    if (!force && Date.now() - listedAt < RELIST_AFTER) return known;
+    return shared(signal);
+  }
+
+  async function reading(signal) {
     const headers = { authorization: "Bearer public", "x-opencode-client": "cli" };
     const [listing, catalog, docs] = await Promise.allSettled([
       readRemote(`${baseURL}/models`, true, headers, signal),
@@ -495,9 +668,58 @@ async function server(_input, options = {}) {
     const discovered = buildModels(ids, metadata, protocols, baseURL);
     if (partial) {
       // Preserve previously verified models only while they remain in the live catalog.
+      //
+      // "The catalogue describes it" is read here as it is read in models.mjs:
+      // a row that is not a description describes nothing, whatever it is. The
+      // catalogue writes `null` for a row it could not fill in, and `null` is
+      // falsy, so the truthiness this used to test happened to answer the same
+      // way for that one shape — but `"junk"` and `7` are not descriptions
+      // either and are truthy, and they were read as if they were.
+      //
+      // An array is named as well as an object, because `typeof []` is
+      // `"object"` and the row shape the catalogue must never write is exactly
+      // the one a bare `typeof` check waves through: read as a description, the
+      // model it describes is not kept, which is a model silently disappearing
+      // for a catalogue row that could not be filled in.
+      //
+      // A row that is not a description is the same fact as no row at all:
+      // `buildModels` has already resolved the id without it (through the docs,
+      // or the `-free` rule), so what is preserved here is a model this plugin
+      // verified before, and holding it back because the catalogue wrote a row
+      // it could not fill in would be the same silent disappearance the `-free`
+      // rule exists to prevent.
+      //
+      // The entry kept is read as an object for the same reason: `known` only
+      // ever holds maps this plugin built, so anything else there is a shape
+      // this loop cannot reason about, and keeping it would carry it onward as
+      // a model. Judged rather than assumed, because the cost of being wrong is
+      // paid by a host on a hook it is waiting for.
+      //
+      // All three reads are own-property reads (`Object.hasOwn`), the same rule
+      // models.mjs and limits.mjs read their maps by. `known`, `protocols`,
+      // `discovered` and the catalogue's own map are all plain objects keyed by
+      // ids that arrived from upstream, so a name that is not a key at all —
+      // `toString` and the rest of `Object.prototype` — reads as a *value*
+      // through the prototype chain: `protocols["toString"]` is a function, so
+      // `!protocols[id]` was false and the entry was skipped for an id no
+      // catalogue ever described. What is under a name nobody wrote is what the
+      // prototype has, and it belongs to no model.
+      //
+      // `buildModels` skips `"__proto__"` before any of this, so the write below
+      // is unreachable for that id today. It is written safely anyway: this
+      // branch's job is to put a model in the map, and a `map[id] = value` for
+      // that id is the prototype setter rather than a write — a guard in another
+      // module is not the place this write's safety is decided.
       for (const id of ids) {
-        if (!discovered[id] && !metadata.models?.[id] && !protocols[id] && known[id]) {
-          discovered[id] = known[id];
+        const kept = known[id];
+        if (
+          !Object.hasOwn(discovered, id) &&
+          !describesModel(catalogueRow(metadata, id)) &&
+          !Object.hasOwn(protocols, id) &&
+          Object.hasOwn(known, id) &&
+          describesModel(kept)
+        ) {
+          own(discovered, id, kept);
         }
       }
       // Deliberately not said as fallen back. Zen's own list was read, and what
@@ -648,9 +870,24 @@ async function server(_input, options = {}) {
       async models(provider, { auth } = {}) {
         if (!auth) return provider.models;
         requirePublic(auth);
+        // Asked without a signal, and deliberately: the hook has none to give,
+        // and passing `undefined` on as one would read as a caller that cancels
+        // nothing — `leased` takes it as "no way out", which is what this call
+        // has. Whether it reads at all is `discover()`'s decision, so a host
+        // that opens its model chooser twice in a minute is given the list read
+        // the first time instead of a second round of upstream reads.
         return discover();
       },
     },
+    // Read the list again now, whatever RELIST_AFTER says: the way for a host
+    // (and for a test) to ask for the listing on purpose, rather than having to
+    // spend a request on a model the last list did not have to get one. It
+    // skips the budget and nothing else — it goes through the same single
+    // flight, so a refresh asked for while a discovery is already running waits
+    // for that answer instead of reading beside it.
+    async refresh() {
+      return discover(undefined, { force: true });
+    },
     async "chat.headers"(input, output) {
       if (![PROVIDER, `${PROVIDER}-plugin`].includes(input.model?.providerID) || !input.sessionID)
         return;