opencode-harness-kit 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -12,6 +12,77 @@ is not happening.
 
 ---
 
+## [0.6.3] — 2026-10-23
+
+Nothing here changes the runtime. The plugin, the CLI and `dist/` are
+byte-for-byte what 0.6.2 shipped; this release is the front page and the
+packaging metadata catching up with decisions already made.
+
+### Removed
+
+- **The demo media is gone from the repository.** `docs/demo/pitch.mp4`
+  (12.5 MB) and `docs/demo-loop.gif` are deleted, and the README no longer
+  embeds them. The recording lives on in the private
+  [`pham-canh/video`](https://github.com/pham-canh/video) repo. Two reasons
+  it had to leave this one: the `.mp4` was never shipped by npm (`files`
+  covers `docs/*.md` only), so the README rendered on npmjs.com carried a
+  `<video>` tag whose source could not exist — a 404 embed on the public
+  page; and a repo whose pitch is "the metadata is the truth" was weighting
+  its own checkout with twelve megabytes nobody could watch.
+
+### Fixed
+
+- **The lockfile answered for a version two releases behind.**
+  `package-lock.json` still said `0.5.8` while `package.json` said `0.6.2`,
+  and carried a `peerDependencies` block the manifest no longer has. Both are
+  synced now, by hand rather than a regenerating `npm install`, so the locked
+  dependency versions are untouched.
+
+## [0.6.2] — 2026-10-23
+
+Published. Tag `v0.6.2`.
+
+### Fixed
+
+- **Transient catalogue errors stopped benching live routes.** When
+  `oc-harness doctor` or the router asked models.dev and the request failed
+  for a reason other than "this model is withdrawn" — a timeout, a rate
+  limit, a network blip — the failure was percolating into the route health
+  as if the model itself were dead, and a live route got benched on evidence
+  that was about the network, not the model. The distinction now matters:
+  transient errors are retried and reported as transient; only a confirmed
+  `status: "deprecated"` out of the catalogue marks a route unhealthy.
+
+## [0.6.1] — 2026-10-23
+
+Published. Tag `v0.6.1`.
+
+### Added
+
+- **A `flint-40b-free` profile, published with its retention verdict.** A
+  same-size free model beside the fleet's usual rungs, and the tenth free
+  model in the default fleet needed a lane to run in, so the build assigns
+  it.
+
+### Fixed
+
+- **The fleet no longer routes through a withdrawn model.**
+  `minimax-m3.1-flash-free` was marked deprecated in the catalogue while the
+  default fleet still carried it in a lane; `flint-40b-free` takes its place
+  in the default chains.
+
+- **`use` and `install` write their files atomically.** The config and the
+  health file are now written to a sibling temp file and renamed, so a
+  `install` interrupted mid-write can no longer leave a half-written config
+  behind. (A failure found its way through this when the code called
+  `renameSync` it had never imported; the import is there now.)
+
+- **A publish job re-run against an already-published tag is green**, not a
+  red crash on E409.
+
+- **eval's `padEnd` did not coerce its arguments to strings**, and died on a
+  numeric task id.
+
 ## [0.6.0] — 2026-10-22
 
 Published. The tag is what cut it: `git tag v0.6.0 && git push origin

package/README.md

@@ -3,18 +3,6 @@
 [![CI](https://github.com/pham-canh/opencode-harness-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/pham-canh/opencode-harness-kit/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/opencode-harness-kit.svg)](https://www.npmjs.com/package/opencode-harness-kit)
 
-<p align="center">
-  <video src="docs/demo/pitch.mp4" width="720" controls></video>
-</p>
-
-*Four minutes forty-seven seconds, recorded live from a real terminal and
-narrated — every command on screen is typed and executed while the camera
-runs. The voiceover is in [`video/`](video/), along with what it took to
-record it and the two mistakes that cost the most time.*
-
-*It was recorded against an earlier version of the kit: the numbers it names
-are the ones from then, and the ones below are the ones now.*
-
 A harness kit for [OpenCode](https://opencode.ai) that is **model-agnostic by
 construction**. Switching models is a data edit, not a code change.
 
@@ -22,10 +10,6 @@ construction**. Switching models is a data edit, not a code change.
 npx -y opencode-harness-kit init    # pick a free model, then install + verify
 ```
 
-<p align="center">
-  <img src="docs/demo-loop.gif" width="760" alt="oc-harness list showing the model-agnostic profiles, then oc-harness verify reporting a consistent install">
-</p>
-
 then restart opencode. That is the whole quickstart. No npm account needed on
 your side — `npx` only downloads the published kit. Prefer git? The same three
 steps from a checkout (see [Install](#install)):

package/bin/oc-harness.mjs

@@ -45,6 +45,7 @@ import {
 } from "../src/profile.js"
 import { generateConfig, globalInstructionsPath, utilityModel, withMemoryPlugin, canAddMemoryPlugin, kitVersion, MEMORY_PLUGIN } from "../src/config.js"
 import { ruleNames, BASH_RULES, WRITE_RULES } from "../src/rules.js"
+import { readHealth, unhealthyRoutes, writeHealth } from "../src/health.js"
 import { planEffort } from "../src/effort.js"
 import { findTelemetryFiles, readLaneUsage, averageMs } from "../src/lane-usage.js"
 import { researchModels, isWithdrawn, pruneWithdrawnChains } from "../src/research.js"
@@ -489,6 +490,46 @@ function projectRoot() {
  * one in the plural one, and a checker that only looks at `agents/` misses
  * half of them.
  */
+/**
+ * The health records whose model the catalogue lists again.
+ *
+ * Issue #9: a route recorded as withdrawn carried the quota's day-long
+ * window, so a pulled model was retried once a day, forever. The withdrawn
+ * window fixed the expiry half; this is the other half. A record whose
+ * model has COME BACK to the catalogue - back on the tier, or no longer
+ * flagged as withdrawn in it - describes a route that works again right
+ * now, and every hour the record still stands, the profile's config hook
+ * benches a live route and sends the lane to a rung down its chain.
+ *
+ * The clear is conservative in the way the health file itself is: a model
+ * that is IN the catalogue and not flagged withdrawn in it is trusted as
+ * returned. A model the fetch never saw stays recorded - a network error
+ * must not un-bench a route.
+ *
+ * @param {string} dir the project root the health file lives under
+ * @param {any} catalog the live model catalogue, or null
+ * @returns {string[]} the route keys that were cleared
+ */
+function clearRecoveredRoutes(dir, catalog) {
+  if (!catalog || typeof catalog !== "object") return []
+  const routes = unhealthyRoutes(dir)
+  const recovered = []
+  for (const key of Object.keys(routes)) {
+    const slash = key.indexOf("/")
+    // A key without its provider half was never written by the router.
+    if (slash < 1) continue
+    const provider = key.slice(0, slash)
+    const model = key.slice(slash + 1)
+    const record = catalog?.[provider]?.models?.[model]
+    if (record && !isWithdrawn(record)) recovered.push(key)
+  }
+  if (!recovered.length) return []
+  const health = readHealth(dir)
+  for (const key of recovered) delete health.unhealthy?.[key]
+  writeHealth(dir, health)
+  return recovered
+}
+
 function agentDirs() {
   const project = projectRoot()
   return [
@@ -876,6 +917,9 @@ async function cmdAuto() {
   try {
     // 1. The catalogue. A model that was withdrawn has to be caught before
     //    it is used, and the profile files are the only place that lives.
+    //    The same fetch feeds the health cleanup and the use step below;
+    //    offline, it stays null and both of those stand down with it.
+    let refreshed = { changed: [], gone: [], same: [], skipped: [], catalog: null }
     if (flag("--offline")) {
       steps.push({ step: "refresh", status: "skipped", detail: "--offline" })
     } else {
@@ -884,7 +928,7 @@ async function cmdAuto() {
       // profile that could not be read used to vanish from the report - and
       // the report said "ok": true while a profile was never checked against
       // the live catalogue.
-      const refreshed = await cmdRefreshAll()
+      refreshed = await cmdRefreshAll()
       for (const g of refreshed.gone) {
         problems.push(`profile ${g} is no longer in the live catalogue`)
       }
@@ -901,14 +945,35 @@ async function cmdAuto() {
       })
     }
 
+    // 1.5. The health file. A record whose model the catalogue lists again
+    //     describes a route that works, and the profile's config hook benches
+    //     a live route while it stands. This step runs with the same fetch the
+    //     refresh made, so it costs nothing extra. A `--offline` doctor skips
+    //     it with the refresh it belongs to: a catalogue that was not read
+    //     must not be trusted to un-bench anything.
+    const recovered = clearRecoveredRoutes(projectRoot(), refreshed.catalog)
+    if (recovered.length) {
+      for (const key of recovered) console.log(`  ${green("+")} ${key} is in the live catalogue again; the spent record was cleared`)
+      steps.push({
+        step: "health",
+        status: "ok",
+        detail: `${recovered.length} spent record(s) cleared`,
+      })
+    }
+
     // 2. The behavioural layer: the plugin link, the prompts, the skills, the
     //    global rules. Without them the config means nothing.
     await cmdInstall()
     steps.push({ step: "install", status: "ok" })
 
-    // 3. The config, recompiled from the profile.
-    await cmdUse(id)
-    steps.push({ step: "use", status: "ok", detail: id })
+    // 3. The config, recompiled from the profile - against the SAME catalogue
+    //    fetch, so the step does not pull models.dev a second time.
+    const used = await cmdUse(id, refreshed.catalog, { wantJson, report: { problems } })
+    if (used === "refused") {
+      steps.push({ step: "use", status: "failed", detail: id })
+    } else {
+      steps.push({ step: "use", status: "ok", detail: id })
+    }
 
     // 4. The check that says whether all of that worked.
     const verifyProblems = cmdVerify()
@@ -1452,7 +1517,28 @@ function memorySpec() {
   return MEMORY_PLUGIN
 }
 
-async function cmdUse(id) {
+/**
+ * Install a profile's config.
+ *
+ * @param {string} id
+ * @param {any} [catalog] a catalogue an earlier step already fetched
+ * @param {{ wantJson?: boolean, report?: { problems: string[] } | null }} [sink]
+ *   where a refusal goes instead of `fail()`. The one caller that runs with
+ *   an calmed stdout is `auto --json`: a script reads its report, the report
+ *   names the refusal as a problem, and the run still gets to print the
+ *   report. Channels an exit here and the report is never printed, which is
+ *   exactly the bug the JSON report exists to prevent.
+ */
+async function cmdUse(id, catalog = null, sink = {}) {
+  const wantJson = sink.wantJson === true
+  /** Refuse: issue the message the way the caller's stdout wants it said. */
+  const refuse = (msg) => {
+    if (sink.report) {
+      sink.report.problems.push(msg)
+      return false
+    }
+    fail(msg, wantJson)
+  }
   if (!id) fail("usage: oc-harness use <profile> [--print] [--yes]")
   let p = null
   try {
@@ -1507,6 +1593,76 @@ async function cmdUse(id) {
     console.error(msg + "  Continuing: there is no terminal to ask.\n")
   }
 
+  // The live catalogue, checked at install time because the profile that gets
+  // installed is a promise about what will serve tomorrow.
+  //
+  // Issue #11: `use` used to install a profile without reading the catalogue
+  // at all, so the first run of the harness was the first thing that knew a
+  // lane's model was gone. The profile's file was written, the header said
+  // every lane was healthy, and the harness said so by failing.
+  //
+  // - A dead BASE model ends the install: the profile has nothing to fall
+  //   back to, and writing a config that fails on the session's first token
+  //   is the bug, not the fix.
+  // - Dead rungs are pruned IN MEMORY before the config is compiled, so the
+  //   written config runs on what the catalogue still serves. The profile
+  //   file on disk keeps the rung until `oc-harness refresh` makes the fix
+  //   durable - an install must not rewrite the package's own data.
+  // - A lane with no rung left fails the install: a lane with no model is
+  //   not a lane, and the profile's author has to name the replacement.
+  //
+  // Fail-open: a catalogue that cannot be read is a warning, not a refusal.
+  // Refusing installs on a flaky network takes the tool away from the
+  // machine that needs to build offline, and `--offline` says that out loud.
+  if (!catalog && !flag("--offline")) {
+    try {
+      catalog = await fetchCatalog()
+    } catch (err) {
+      console.error(
+        yellow(
+          `  could not check the live catalogue (${err instanceof Error ? err.message : String(err)}). Install continues with the profile as it ships.`,
+        ),
+      )
+    }
+  }
+  if (catalog) {
+    const models = catalog?.[p.provider]?.models ?? {}
+    const record = models[p.model]
+    if (!record || isWithdrawn(record)) {
+      if (!refuse(
+        `profile ${id}'s base model ${p.provider}/${p.model} is no longer in the live catalogue.` +
+          ` Pick another profile: oc-harness list <no-args>`,
+      )) return "refused"
+    }
+    // The prune is silent until it has something to say. Its costs are the
+    // output below: the rungs it dropped and the one route that moved, and
+    // the way to make both durable.
+    const prune = pruneWithdrawnChains(p, catalog, p.provider)
+    if (prune.emptied.length) {
+      const lanes = prune.emptied.map((lane) => {
+        const rm = prune.lanes.find((l) => l.lane === lane)
+        return `${lane} (its models were: ${rm?.removed.join(", ")})`
+      })
+      if (!refuse(
+        `profile ${id}: every rung of the ${prune.emptied.join(", ")} lane is no longer in the live catalogue.` +
+          ` No model can serve that lane, so the profile needs a replacement before it installs.`,
+      )) return "refused"
+    }
+    if (prune.pruned.length || prune.utilityMoved) {
+      const drops = []
+      for (const lane of prune.lanes) drops.push(`lane ${lane.lane}: ${lane.from.join(" -> ")} becomes ${lane.to.join(" -> ")}`)
+      if (prune.fallback) drops.push(`fallback: ${prune.fallback.removed.join(", ")} dropped`)
+      if (prune.utilityMoved) drops.push(`the utility route moved to ${p.utility.model}`)
+      console.error(
+        yellow(
+          `  the live catalogue no longer serves ${prune.pruned.join(", ")}: the config this run compiled drops them.` +
+            ` Run oc-harness refresh to make the fix durable in the profile file itself.`,
+        ) +
+          `\n    ${drops.join("\n    ")}`,
+      )
+    }
+  }
+
   const base = readConfigJson()
   // `--memory` turns on the memory plugin. The kit does not implement memory
   // - a local vector store with embeddings, a web UI and auto-capture is a
@@ -1833,7 +1989,10 @@ async function cmdRefreshAll() {
   // dropped, so a caller that silences the human output - `auto --json` -
   // never saw them: a withdrawn model or a profile that was never checked
   // against the catalogue went into a report that said everything was fine.
-  return { changed, gone, same, skipped }
+  // The catalogue itself comes back with the report: `doctor` runs the
+  // refresh as its opening step, and the steps that follow it check against
+  // the same fetch instead of pulling models.dev twice.
+  return { changed, gone, same, skipped, catalog }
 }
 
 /**

package/dist/health.d.ts

@@ -7,6 +7,13 @@ export type SpentEntry = {
      * the pattern that matched
      */
     reason: string;
+    /**
+     * why the route was written off.
+     * `withdrawn` entries expire on the catalogue's clock, not the quota's:
+     * a rate limit resets at 00:00 UTC, a pulled model does not. Entries
+     * written before the field existed behave as `spent`.
+     */
+    class?: ("spent" | "withdrawn");
 };
 export type Health = {
     unhealthy: Record<string, SpentEntry>;
@@ -21,6 +28,14 @@ export type Health = {
  * @returns {number}
  */
 export declare function spentWindowMs(): number;
+/**
+ * The window, in milliseconds, a route recorded as withdrawn is honoured for.
+ *
+ * Read at call time, like `spentWindowMs`.
+ *
+ * @returns {number}
+ */
+export declare function withdrawnWindowMs(): number;
 /**
  * Whether a recorded route is still spent.
  *

package/dist/index.js

@@ -1935,6 +1935,7 @@ function utilityModel(p) {
 import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync as renameSync2, unlinkSync, writeFileSync } from "node:fs";
 import { join as join7 } from "node:path";
 var DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1e3;
+var DEFAULT_WITHDRAWN_WINDOW_MS = 30 * 24 * 60 * 60 * 1e3;
 function spentWindowMs() {
   const raw = process.env.HARNESS_SPENT_WINDOW_HOURS;
   if (!raw) return DEFAULT_WINDOW_MS;
@@ -1942,6 +1943,13 @@ function spentWindowMs() {
   if (!Number.isFinite(hours) || hours <= 0) return DEFAULT_WINDOW_MS;
   return hours * 60 * 60 * 1e3;
 }
+function withdrawnWindowMs() {
+  const raw = process.env.HARNESS_WITHDRAWN_WINDOW_HOURS;
+  if (!raw) return DEFAULT_WITHDRAWN_WINDOW_MS;
+  const hours = Number(raw);
+  if (!Number.isFinite(hours) || hours <= 0) return DEFAULT_WITHDRAWN_WINDOW_MS;
+  return hours * 60 * 60 * 1e3;
+}
 function isSpent(entry, now = Date.now()) {
   if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
   const at = (
@@ -1951,7 +1959,11 @@ function isSpent(entry, now = Date.now()) {
   if (typeof at !== "string") return true;
   const when = Date.parse(at);
   if (Number.isNaN(when)) return true;
-  return now - when <= spentWindowMs();
+  const kind = (
+    /** @type {any} */
+    entry.class
+  );
+  return now - when <= (kind === "withdrawn" ? withdrawnWindowMs() : spentWindowMs());
 }
 function liveUnhealthy(health, now = Date.now()) {
   const out = {};
@@ -2018,18 +2030,18 @@ var SPENT = [
   /rate[_ -]?limit/i,
   /\b429\b/,
   /quota (?:exceeded|exhausted)/i,
-  /overloaded_error/i,
-  // A withdrawn model, named in the error. The words have to sit next to
-  // each other - "model minimax-m3.1-flash-free not found", "model_not_found",
-  // "ModelNotFound" - because the text this runs against is the provider's
-  // own error and that can be a whole response body. The old pattern ran
-  // over the entire event, where a body that mentioned a model in one place
-  // and "not found" in another read as a withdrawn model: a live route
-  // written off by a coincidence.
+  /overloaded_error/i
+];
+var WITHDRAWN = [
   /\bmodel[\W_]*not[\W_]*found\b/i,
   /\bmodel\b[\w.:/-]*(?:\s+[\w.:/-]+){0,2}\s+not found\b/i,
   /no available provider/i
 ];
+var TRANSIENT = [
+  /\b502\b|\b503\b|\b529\b/,
+  /bad gateway/i,
+  /\bupstream\b/
+];
 function errorText(err) {
   if (err == null) return "";
   if (typeof err === "string") return err;
@@ -2059,7 +2071,12 @@ function errorText(err) {
 function classifyError(err) {
   const text = errorText(err);
   if (!text) return null;
-  for (const p of SPENT) if (p.test(text)) return p.source;
+  for (const p of SPENT)
+    if (p.test(text)) return { kind: "spent", reason: p.source };
+  for (const p of WITHDRAWN)
+    if (p.test(text)) return { kind: "withdrawn", reason: p.source };
+  for (const p of TRANSIENT)
+    if (p.test(text)) return { kind: "transient", reason: p.source };
   return null;
 }
 function errorOf(e) {
@@ -2175,14 +2192,21 @@ var RouterPlugin = async ({ worktree, directory }) => {
       }
       const err = errorOf(e);
       if (!err) return;
-      const reason = classifyError(err);
-      if (!reason) return;
+      const verdict = classifyError(err);
+      if (!verdict) return;
       const sessionID = sessionIdOf(e);
       const key = seen ?? (sessionID ? sessionRoutes.get(sessionID) : void 0) ?? configuredRoute ?? lastRoute;
       if (!key) return;
+      if (verdict.kind === "transient") return;
       const health = readHealth(project);
       if (unhealthyRoutes(project)[key]) return;
-      health.unhealthy[key] = { at: (/* @__PURE__ */ new Date()).toISOString(), reason };
+      health.unhealthy[key] = {
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        reason: verdict.reason,
+        // The class decides the window the entry expires under. A model the
+        // provider pulled is not back at 00:00 UTC, whichever the quota says.
+        class: verdict.kind
+      };
       writeHealth(project, health);
       failedSessions++;
     },

package/dist/router.d.ts

@@ -1,3 +1,19 @@
 import type { Plugin } from "./plugin.js";
+/**
+ * Which of the three classes a provider error belongs to.
+ *
+ * The classes decide what happens to the health file: `spent` is recorded
+ * under the quota's window, `withdrawn` under the catalogue's, and
+ * `transient` is not recorded at all. Exported so a test can feed an error
+ * straight through the classifier instead of inventing an event to carry
+ * it.
+ *
+ * @param {any} err
+ * @returns {{ kind: "spent" | "withdrawn" | "transient", reason: string } | null}
+ */
+export declare function classifyError(err: any): {
+    kind: "spent" | "withdrawn" | "transient";
+    reason: string;
+} | null;
 export declare const RouterPlugin: Plugin;
 export default RouterPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-harness-kit",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Harness kit for OpenCode: capability profiles, a fleet of job lanes with one free model each, role-based reasoning effort, context pruning, and measured baselines.",
   "license": "MIT",
   "homepage": "https://github.com/pham-canh/opencode-harness-kit#readme",

package/src/health.js

@@ -19,6 +19,10 @@ import { join } from "node:path"
  * @typedef {object} SpentEntry
  * @property {string} at when the route was recorded as spent
  * @property {string} reason the pattern that matched
+ * @property {("spent"|"withdrawn")} [class] why the route was written off.
+ *   `withdrawn` entries expire on the catalogue's clock, not the quota's:
+ *   a rate limit resets at 00:00 UTC, a pulled model does not. Entries
+ *   written before the field existed behave as `spent`.
  */
 
 /**
@@ -42,6 +46,20 @@ import { join } from "node:path"
  */
 const DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000
 
+/**
+ * How long a route recorded as WITHDRAWN is honoured for, by default.
+ *
+ * A rate limit resets at 00:00 UTC. A withdrawal does not: the provider
+ * pulled the model, and no number of days' sleep brings it back. Treating
+ * both with the one window meant a model that had left the catalogue was
+ * retried once a day, forever, and every lane that named it first paid a
+ * failed request before falling through.
+ *
+ * Thirty days is the scale the toolkit's catalogue turns on - free tiers
+ * rotate monthly - and HARNESS_WITHDRAWN_WINDOW_HOURS overrides it.
+ */
+const DEFAULT_WITHDRAWN_WINDOW_MS = 30 * 24 * 60 * 60 * 1000
+
 /**
  * The window, in milliseconds, a recorded spent route is honoured for.
  *
@@ -61,6 +79,21 @@ export function spentWindowMs() {
   return hours * 60 * 60 * 1000
 }
 
+/**
+ * The window, in milliseconds, a route recorded as withdrawn is honoured for.
+ *
+ * Read at call time, like `spentWindowMs`.
+ *
+ * @returns {number}
+ */
+export function withdrawnWindowMs() {
+  const raw = process.env.HARNESS_WITHDRAWN_WINDOW_HOURS
+  if (!raw) return DEFAULT_WITHDRAWN_WINDOW_MS
+  const hours = Number(raw)
+  if (!Number.isFinite(hours) || hours <= 0) return DEFAULT_WITHDRAWN_WINDOW_MS
+  return hours * 60 * 60 * 1000
+}
+
 /**
  * Whether a recorded route is still spent.
  *
@@ -79,7 +112,12 @@ export function isSpent(entry, now = Date.now()) {
   if (typeof at !== "string") return true
   const when = Date.parse(at)
   if (Number.isNaN(when)) return true
-  return now - when <= spentWindowMs()
+  // The window the entry was written under. An entry that carries no class
+  // was written by an older version of the kit, or by a hand, and gets the
+  // quota's window: the quota resets, which is the assumption every entry
+  // used to carry.
+  const kind = /** @type {any} */ (entry).class
+  return now - when <= (kind === "withdrawn" ? withdrawnWindowMs() : spentWindowMs())
 }
 
 /**

package/src/router.ts

@@ -36,25 +36,53 @@ import {
   resolveRoles,
 } from "./profile.js"
 
-/** Patterns that mean "this route is spent", not "this request was bad". */
+/**
+ * Patterns that mean "this route is spent", not "this request was bad": the
+ * provider's quota for the free tier ran out. The quota resets, which is why
+ * these expire on the day's window.
+ */
 const SPENT = [
   /FreeUsageLimitError/i,
   /rate[_ -]?limit/i,
   /\b429\b/,
   /quota (?:exceeded|exhausted)/i,
   /overloaded_error/i,
-  // A withdrawn model, named in the error. The words have to sit next to
-  // each other - "model minimax-m3.1-flash-free not found", "model_not_found",
-  // "ModelNotFound" - because the text this runs against is the provider's
-  // own error and that can be a whole response body. The old pattern ran
-  // over the entire event, where a body that mentioned a model in one place
-  // and "not found" in another read as a withdrawn model: a live route
-  // written off by a coincidence.
+]
+
+/**
+ * Patterns that mean "this model is gone": the provider pulled it.
+ *
+ * The words have to sit next to each other - "model minimax-m3.1-flash-free
+ * not found", "model_not_found", "ModelNotFound" - because the text this
+ * runs against is the provider's own error and that can be a whole response
+ * body. The old pattern ran over the entire event, where a body that
+ * mentioned a model in one place and "not found" in another read as a
+ * withdrawn model: a live route written off by a coincidence.
+ *
+ * These get their own class and their own window: no number of days' sleep
+ * returns a pulled model, so benching one for 24h retried a death once a
+ * day, forever.
+ */
+const WITHDRAWN = [
   /\bmodel[\W_]*not[\W_]*found\b/i,
   /\bmodel\b[\w.:/-]*(?:\s+[\w.:/-]+){0,2}\s+not found\b/i,
   /no available provider/i,
 ]
 
+/**
+ * Patterns that mean "this request could not be answered" - the host was at
+ * capacity, a gateway hiccuped - and nothing about the ROUTE is worse.
+ *
+ * Benching a route for one of these benches a model that answered minutes
+ * later. They are not spent, not withdrawn, and they record nothing: the
+ * next request tries the same route again.
+ */
+const TRANSIENT = [
+  /\b502\b|\b503\b|\b529\b/,
+  /bad gateway/i,
+  /\bupstream\b/,
+]
+
 /**
  * The text of a provider error, and nothing else.
  *
@@ -99,15 +127,26 @@ function errorText(err: any): string {
 }
 
 /**
- * Whether a provider error means the route is spent.
+ * Which of the three classes a provider error belongs to.
+ *
+ * The classes decide what happens to the health file: `spent` is recorded
+ * under the quota's window, `withdrawn` under the catalogue's, and
+ * `transient` is not recorded at all. Exported so a test can feed an error
+ * straight through the classifier instead of inventing an event to carry
+ * it.
  *
  * @param {any} err
- * @returns {string | null} the pattern that matched
+ * @returns {{ kind: "spent" | "withdrawn" | "transient", reason: string } | null}
  */
-function classifyError(err: any): string | null {
+export function classifyError(err: any): { kind: "spent" | "withdrawn" | "transient"; reason: string } | null {
   const text = errorText(err)
   if (!text) return null
-  for (const p of SPENT) if (p.test(text)) return p.source
+  for (const p of SPENT)
+    if (p.test(text)) return { kind: "spent", reason: p.source }
+  for (const p of WITHDRAWN)
+    if (p.test(text)) return { kind: "withdrawn", reason: p.source }
+  for (const p of TRANSIENT)
+    if (p.test(text)) return { kind: "transient", reason: p.source }
   return null
 }
 
@@ -352,8 +391,8 @@ export const RouterPlugin: Plugin = async ({ worktree, directory }) => {
       // anything about the route.
       const err = errorOf(e)
       if (!err) return
-      const reason = classifyError(err)
-      if (!reason) return
+      const verdict = classifyError(err)
+      if (!verdict) return
 
       // The route the failure belongs to: the event's own, else the route
       // this session was last seen on, else the route it was configured
@@ -367,9 +406,27 @@ export const RouterPlugin: Plugin = async ({ worktree, directory }) => {
         lastRoute
       if (!key) return
 
+      // A transient failure is the host failing to answer one request, not
+      // the route becoming unusable. Nothing is written, so the next request
+      // tries the same rung again - benching the route under the quota's
+      // window is how a capacity blip cost a model a day.
+      //
+      // ("Advances to the next rung inside the same request" is not on the
+      // table: `chat.params` carries only temperature and sampling, the model
+      // on `chat.message` is read-only, and `config` has already run. What a
+      // transient verdict buys - and what this buys - is a route that is
+      // still live when the next request arrives.)
+      if (verdict.kind === "transient") return
+
       const health = readHealth(project)
       if (unhealthyRoutes(project)[key]) return // already recorded, do not spam
-      health.unhealthy[key] = { at: new Date().toISOString(), reason }
+      health.unhealthy[key] = {
+        at: new Date().toISOString(),
+        reason: verdict.reason,
+        // The class decides the window the entry expires under. A model the
+        // provider pulled is not back at 00:00 UTC, whichever the quota says.
+        class: verdict.kind,
+      }
       writeHealth(project, health)
       failedSessions++
     },