@cohortapp/agent-sdk 2.9.1 → 2.10.0

package/lib/channels/inbox-item.mjs

@@ -106,6 +106,10 @@ export function yamlScalar(s) {
  *                        unless ev already carries an explicit inbox `id`.
  *   - service            ev.channel (the inbox dir + classifier "service").
  *   - channel            friendly label (ev.channel_label) else channel_id else channel.
+ *                        DISPLAY ONLY — `dm/casey`, `task/<title>`, `doc/<name>`.
+ *                        Never an address. The send path (scripts/daemon/deliver)
+ *                        used to fall back to it when `channel_id` was blank, which
+ *                        is how a board reply came to be posted to a task's title.
  *   - channel_id         native chat id (ev.source.chatId || ev.channel_id).
  *   - sender             ev.from.name || ev.from.id.
  *   - sender_privilege   ev.sender_privilege (resolved upstream) || "unknown".

package/lib/comms/send-gate.mjs

@@ -101,6 +101,25 @@ export const BANNED_OPENERS = Object.freeze([
  */
 const COHORT_ID = /^(?:[a-z][a-z0-9]{14,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
 
+/**
+ * A Cohort recipient that is an ENTITY THREAD rather than a room:
+ * `task:<id>` / `file:<id>` / `decision:<id>`, minted by
+ * `scripts/daemon/deliver.mjs#cohortReplyRoute` for the surfaces that have no
+ * channel (a board item's comments, a doc's comments, a decision's thread).
+ *
+ * These are as internal as a channel id — more so, since hq resolves them
+ * org-scoped — but the colon fails {@link COHORT_ID}, so without this every
+ * board reply classified EXTERNAL: `failPolicy` flipped to fail-CLOSED for the
+ * whole board lane, and every `recipient_class: external` information-barrier
+ * rule started applying to internal board chatter. The prefix set is CLOSED and
+ * the id half is still shape-checked, so nothing that is not one of our own
+ * entity handles is laundered into "internal" by adding a colon.
+ *
+ * `file:` also carries the opaque `fileKey` of a chat attachment, which is not
+ * cuid-shaped, so the id half only has to be a non-empty token with no `@`.
+ */
+const COHORT_ENTITY_REF = /^(?:task|file|decision):[^\s@:][^\s@]*$/;
+
 /** One-shot guard so the org-recipient warning is not emitted per message. */
 let _warnedExternalOrgRecipient = false;
 
@@ -146,7 +165,10 @@ export function classifyRecipient(channel, recipient, internalDomains = []) {
       // anything else on this channel (an email address handed to the org mailer)
       // still falls through to the domain test below, so a genuinely external
       // address is NOT laundered into "internal" by arriving on this channel.
-      if (COHORT_ID.test(r)) return "internal";
+      // A room (a channel/member id) or an entity thread (`task:<id>` …) — both
+      // are rows inside the org the agent belongs to. See COHORT_ENTITY_REF for
+      // what the second form cost while it fell through to "external".
+      if (COHORT_ID.test(r) || COHORT_ENTITY_REF.test(r)) return "internal";
       break;
     case "slack":
     case "telegram":

package/lib/comms/send-gate.test.mjs

@@ -570,6 +570,30 @@ describe("classifyRecipient", () => {
     );
   });
 
+  // REGRESSION — the SAME defect one shape further on. `deliver.mjs` answers a
+  // roomless surface on its entity thread and addresses it `task:<id>` /
+  // `file:<id>` / `decision:<id>`. The colon fails COHORT_ID, so every board,
+  // doc and decision reply classified EXTERNAL — fail-CLOSED policy faults for
+  // the whole board lane, and `recipient_class: external` barrier rules applied
+  // to internal board chatter. The module printed its own warning about it on
+  // every process.
+  it("classifies Cohort ENTITY threads as internal — a board reply is not an outsider", () => {
+    assert.equal(classifyRecipient("cohort", "task:cmrlw2l3600e9hh8n10hprdrd"), "internal");
+    assert.equal(classifyRecipient("cohort", "file:cmsspqi9500dmo401gg51ntz7"), "internal");
+    assert.equal(classifyRecipient("cohort", "decision:cmdec0000000000000000000"), "internal");
+    // The chat-attachment fileKey is opaque, not cuid-shaped.
+    assert.equal(classifyRecipient("cohort", "file:fk_abc123"), "internal");
+    assert.equal(classifyRecipient("cohort-org", "task:cmrlw2l3600e9hh8n10hprdrd"), "internal");
+  });
+
+  it("the entity-ref prefix set is CLOSED — it is not a colon wildcard", () => {
+    // Otherwise "internal" becomes a thing anyone can claim by adding a colon.
+    assert.equal(classifyRecipient("cohort", "mailto:someone@external.com"), "external");
+    assert.equal(classifyRecipient("cohort", "approval:aprv_journey_msopegu4"), "external");
+    assert.equal(classifyRecipient("cohort", "task:"), "external");
+    assert.equal(classifyRecipient("cohort", "task:someone@external.com"), "external");
+  });
+
   it("does NOT launder a genuinely external address arriving on the org channel", () => {
     // The whole point of scoping the case to id-shaped recipients: an email or
     // a phone number handed to an org surface must still be external, or the

package/lib/model-router/economics.mjs

@@ -160,16 +160,64 @@ function buildLadder(band, pct, spent, cap) {
 const TIER_ORDER = ["frontier", "default", "fast", "cheap"];
 const TIER_RANK = Object.freeze({ frontier: 0, default: 1, fast: 2, cheap: 3 });
 
+// Providers whose whole line is cheap-tier by construction — the ladder's bottom
+// rung. Matched on the ref's PROVIDER segment ("deepseek/deepseek-v4-flash"),
+// which is a far stronger signal than any substring of the model name.
+//
+// STRUCK 2026-08-13: this block used to justify the `xai` entry by saying that
+// without it "degradeChain must ... fail open and treat it as un-degradable".
+// That inverted the design. degradeChain's filter KEEPS a null tier on purpose
+// (`tier == null || TIER_RANK[tier] >= TIER_RANK.fast`) — failing open is the
+// intended safety property, pinned by the "an unrecognised ref stays null so
+// degradeChain fails OPEN" test, not a hazard to be designed away. An unknown
+// xAI row was already kept, and is still kept.
+//
+// The honest reason `xai` is listed: inferTier is the layer's public answer to
+// "how expensive is this ref", exported via `_internals` and read by the tests
+// and by anything that later wants to RANK rather than merely filter. Getting a
+// $0.20/MTok row filed on the $1/$5 Haiku rung is wrong as an answer even while
+// degradeChain cannot act on the difference. Refresh alongside the catalog.
+const CHEAP_PROVIDERS = new Set(["deepseek", "moonshot", "qwen", "xai"]);
+
+// Model-name fragments that mark a cheap-tier row when the ref carries no
+// provider segment (a hand-written chain member like "kimi-k2.6").
+const CHEAP_HINTS = ["cheap", "deepseek", "kimi", "glm", "qwen", "grok"];
+
 // Heuristic tier inference from a literal ref when no alias tag is present. Keeps
 // degradeChain useful for chains built from raw "provider/model" refs.
+//
+// ORDER MATTERS, and it changed (2026-08-13): the cheap check now runs BEFORE
+// the fast check. It used to run after, so every cheap-provider row whose model
+// name happened to end in "flash" — deepseek/deepseek-v4-flash ($0.14/$0.28, the
+// cheapest row in the bundled catalog) and qwen/qwen3.5-flash ($0.10/$0.40) —
+// was classified as the Haiku-class "fast" rung ($1/$5), a ~7x mis-read of the
+// ladder's own bottom rung.
+//
+// SCOPE OF THE FIX — STRUCK 2026-08-13: the original note here claimed the bug
+// "did mis-rank the 'keep the single cheapest member' safety net". It could not
+// have. That branch runs only when `kept` is EMPTY, i.e. when every non-sentinel
+// member classified frontier/default — and a member classified fast OR cheap is
+// never dropped, so it can never be one of the members the safety net sorts.
+// Verified by exhausting degradeChain over cheap/fast/frontier chains at bands
+// 100/125/150 under both orderings: byte-identical output.
+//
+// So this reorder changes NO routing today. It is a fix to the CLASSIFIER's
+// answer, not to a live routing defect: degradeChain only asks "is this member
+// frontier/default?", collapsing fast, cheap and null into one keep-bucket. The
+// distinction is kept correct because inferTier is exported via `_internals` as
+// this layer's tier oracle, and the next caller to RANK on it (rather than
+// filter) would silently inherit the 7x error. Do not re-order it back on the
+// grounds that "no test on behaviour fails" — that is the point being recorded.
 function inferTier(member) {
   const alias = typeof member === "object" && member ? member.alias : null;
   if (alias && TIER_RANK[alias] != null) return alias;
   const ref = String((member && member.ref) || member || "").toLowerCase();
   if (ref.includes("opus")) return "frontier";
   if (ref.includes("sonnet")) return "default";
+  const provider = ref.includes("/") ? ref.split("/")[0] : null;
+  if (provider && CHEAP_PROVIDERS.has(provider)) return "cheap";
+  if (CHEAP_HINTS.some((h) => ref.includes(h))) return "cheap";
   if (ref.includes("haiku") || ref.includes("flash") || ref.includes("mini")) return "fast";
-  if (ref.includes("cheap") || ref.includes("deepseek") || ref.includes("kimi") || ref.includes("glm") || ref.includes("qwen")) return "cheap";
   return null;
 }
 
@@ -489,6 +537,10 @@ function emitPinOverridden(sessionKey, live, reason, deps) {
 // grep, summarisation) to a Haiku-Explore subagent so the main loop's cache
 // survives. The shape mirrors Claude Code's `--agents` JSON (name → { model,
 // description }).
+// The fast tier was re-verified against the vendor docs on 2026-08-13 and did
+// NOT move when opus/sonnet went to -5: claude-haiku-4-5 is still current, so
+// this id is deliberately unchanged. It rides `claude --agents`, so the bare
+// (undated) alias is intentional — the CLI resolves it to the current build.
 const HAIKU_EXPLORE = Object.freeze({
   "Haiku-Explore": {
     model: "claude-haiku-4-5",

package/lib/model-router/economics.test.mjs

@@ -178,6 +178,82 @@ test("degradeChain: de-dupes refs that collapse onto the same model", () => {
   assert.equal(out.length, 1);
 });
 
+// ---------------------------------------------------------------------------
+// inferTier — the untagged-ref heuristic behind degradeChain
+// ---------------------------------------------------------------------------
+
+const { inferTier } = _internals;
+
+test("inferTier: a cheap PROVIDER beats a 'flash'-shaped model name", () => {
+  // The regression this locks: the fast check (haiku|flash|mini) used to run
+  // BEFORE the cheap check, so the two cheapest rows in the bundled catalog were
+  // filed on the Haiku rung — deepseek-v4-flash is $0.14/$0.28 against Haiku's
+  // $1/$5, a ~7x mis-read of the ladder's own bottom rung.
+  assert.equal(inferTier({ ref: "deepseek/deepseek-v4-flash" }), "cheap");
+  assert.equal(inferTier({ ref: "qwen/qwen3.5-flash" }), "cheap");
+  // …while a genuinely fast-tier Anthropic row is untouched.
+  assert.equal(inferTier({ ref: "anthropic/claude-haiku-4-5" }), "fast");
+  assert.equal(inferTier({ ref: "anthropic/claude-opus-5" }), "frontier");
+  assert.equal(inferTier({ ref: "anthropic/claude-sonnet-5" }), "default");
+});
+
+test("inferTier: every cheap provider the economics layer NAMES is classified", () => {
+  // economics.mjs has always claimed deepseek/kimi/glm/qwen as the cheap tier;
+  // xai/grok is added so the classifier is ready the moment a Grok row lands
+  // (an agent can add one today via catalog_overrides — see model-router.test.mjs).
+  for (const ref of [
+    "deepseek/deepseek-v4-flash",
+    "moonshot/kimi-k2.6",
+    "qwen/qwen3-coder-plus",
+    "xai/grok-4-fast",
+    "zhipu/glm-5",
+    "kimi-k2.6",   // bare, no provider segment
+    "grok-4-fast", // bare, no provider segment
+  ]) {
+    assert.equal(inferTier({ ref }), "cheap", `${ref} should classify as cheap-tier`);
+  }
+});
+
+test("inferTier: a cheap provider's WHOLE line is cheap, not just its famous model", () => {
+  // The model-name hints ("kimi", "grok", "glm") would carry the refs above on
+  // their own, which makes them a trap: the next model each of these providers
+  // ships will not be called "grok-4" or "kimi-k2". The provider segment is the
+  // durable signal, so these refs — none of which contain a hint word — are the
+  // ones that actually hold CHEAP_PROVIDERS in place.
+  assert.equal(inferTier({ ref: "xai/sonic-2" }), "cheap");
+  assert.equal(inferTier({ ref: "moonshot/k3-preview" }), "cheap");
+  assert.equal(inferTier({ ref: "deepseek/v5" }), "cheap");
+});
+
+test("inferTier: an unrecognised ref stays null so degradeChain fails OPEN", () => {
+  // A model we cannot classify must be KEPT, never dropped: a budget heuristic
+  // that silently deletes candidates it doesn't recognise strands the caller
+  // with an empty chain. Asserted against a MIXED chain on purpose — with an
+  // unknown row alone, the "keep the single cheapest" safety net returns it
+  // either way, so a fail-closed filter would slip through unnoticed.
+  assert.equal(inferTier({ ref: "acme/some-new-model" }), null);
+  const out = degradeChain(
+    [{ ref: "anthropic/claude-opus-5" }, { ref: "acme/some-new-model" }],
+    150,
+    {}
+  );
+  assert.deepEqual(
+    out.map((m) => m.ref),
+    ["acme/some-new-model"],
+    "frontier dropped, the unclassifiable row survives"
+  );
+});
+
+test("degradeChain: a cheap third-party row survives band 150 alongside fast rows", () => {
+  const chain = [
+    { ref: "anthropic/claude-opus-5" },
+    { ref: "anthropic/claude-haiku-4-5" },
+    { ref: "xai/grok-4-fast" },
+  ];
+  const out = degradeChain(chain, 150, {}).map((m) => m.ref);
+  assert.deepEqual(out, ["anthropic/claude-haiku-4-5", "xai/grok-4-fast"]);
+});
+
 // ---------------------------------------------------------------------------
 // batchLaneFor — classify deferrable vs realtime
 // ---------------------------------------------------------------------------

package/lib/model-router/resolve.mjs

@@ -831,10 +831,25 @@ function forceAnthropicDecision(catalog, req, { now, opts, audit, tried = [], re
   if (!row) {
     // No catalog at all — degrade to a synthetic chosen so the caller still has
     // a usable model flag (stock `claude` defaults to its account model).
+    // Ids current as of 2026-08-13; see pickAnthropicRow's provenance block.
+    // No succession fallback is needed here precisely BECAUSE there is no
+    // catalog to miss: this id goes straight onto `claude --model`, so it must
+    // be the id we actually want the CLI to run.
+    // REACHABILITY (2026-08-13): pickAnthropicRow returns null only when the
+    // catalog holds no available anthropic row at all, which on a real install
+    // means the bundled YAML failed to load. In production the 4-x rows always
+    // win before this point, so do NOT cite this branch as proof the SDK emits
+    // -5 ids — the only caller that reaches it today is the empty-catalog test.
+    // STRUCK (2026-08-13): `ref` was hardcoded to the sonnet ref even when `id`
+    // resolved to opus, so a critical/thinking request produced the pair
+    // {model: opus, ref: sonnet} — and `ref` is what feeds cacheAffinityKey and
+    // chain[0].ref, i.e. the pin and the audit trail both named the wrong model.
+    const syntheticId =
+      req.needs_thinking || req.priority === "critical" ? "claude-opus-5" : "claude-sonnet-5";
     const synthetic = {
       provider: "anthropic",
-      id: req.needs_thinking || req.priority === "critical" ? "claude-opus-4-8" : "claude-sonnet-4-6",
-      ref: "anthropic/claude-sonnet-4-6",
+      id: syntheticId,
+      ref: `anthropic/${syntheticId}`,
       status: "available",
       auth_env: null,
       endpoints: {},
@@ -951,13 +966,51 @@ function noRouteDecision(req, { now, opts, audit, tried, explainSkips, lane }) {
  * Pick the best available Anthropic row from the catalog for a request:
  * frontier (opus) for thinking/critical, else the default workhorse (sonnet),
  * else any available anthropic row.
+ *
+ * ⚠ READ FIRST: THE -5 REFS BELOW ARE INERT ON THIS TREE. lookupModel misses
+ * every one of them, because lib/model-router/catalog/anthropic.yaml still
+ * carries only 4-x rows, so the succession tail is what actually answers and
+ * `spawnArgs.modelFlag` (= row.id, see modelFlagFor above) puts
+ * `claude-sonnet-4-6` / `claude-opus-4-8` on `claude --model` for every request
+ * that reaches this safety net — which, with no config/model-routing.yaml in the
+ * repo, is every request on the no-v2-config path. Adding the two -5 rows to
+ * that YAML is the step that makes this list mean what it says; it has NOT been
+ * done. Do not read the ordering below as evidence the SDK runs -5 models.
+ *
+ * MODEL IDS — PROVENANCE AND WHY THE LEGACY REFS ARE STILL HERE (2026-08-13):
+ * the current Anthropic ids are claude-opus-5 / claude-sonnet-5 /
+ * claude-haiku-4-5-20251001 (verified against the vendor docs on 2026-08-13;
+ * the fast tier did not move). They lead each list. The claude-*-4-x refs
+ * BELOW them are not leftovers — they are the succession fallback, and they
+ * must stay until lib/model-router/catalog/anthropic.yaml carries -5 rows:
+ * lookupModel() is an EXACT byRef hit with no `replaced_by` chasing, so a ref
+ * the catalog does not have simply returns null. Listing only the -5 refs
+ * today would silently drop this safety net through to "any available
+ * anthropic row" — an unordered `models.find()` that would hand critical work
+ * whatever row happens to sit first in the file. That silent downgrade is the
+ * exact failure this ordered list exists to prevent.
+ *
+ * REFRESH: this list is the LAST-RESORT floor (kill switch / no config /
+ * nothing survived the gates), not the routing table. The routing table is the
+ * catalog + the config `aliases:`; refresh those first (see the provenance
+ * block in lib/model-router.mjs). When -5 rows land in the bundled catalog,
+ * DELETE the 4-x entries here — do not let this list accumulate a model
+ * museum, or the "best available" ordering stops meaning anything.
  */
 function pickAnthropicRow(catalog, req) {
   if (!catalog) return null;
   const wantFrontier = req.needs_thinking || req.priority === "critical" || req.agent_role === "regulatory";
   const order = wantFrontier
-    ? ["anthropic/claude-opus-4-8", "anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5"]
-    : ["anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5", "anthropic/claude-opus-4-8"];
+    ? [
+        "anthropic/claude-opus-5", "anthropic/claude-opus-4-8",
+        "anthropic/claude-sonnet-5", "anthropic/claude-sonnet-4-6",
+        "anthropic/claude-haiku-4-5",
+      ]
+    : [
+        "anthropic/claude-sonnet-5", "anthropic/claude-sonnet-4-6",
+        "anthropic/claude-haiku-4-5",
+        "anthropic/claude-opus-5", "anthropic/claude-opus-4-8",
+      ];
   for (const ref of order) {
     const row = lookupModel(catalog, ref);
     if (row && row.status === "available") {

package/lib/model-router.mjs

@@ -8,15 +8,22 @@
  * existing Claude-CLI-on-Max-subscription behaviour is preserved verbatim.
  *
  * Why this exists:
- *   - Anthropic Sonnet 4.6 / Opus 4.7 are still the quality ceiling for
+ *   - The Anthropic frontier/workhorse pair is still the quality ceiling for
  *     agent loops, but background work (classification, log triage,
- *     scheduled summaries) does NOT need them.
+ *     scheduled summaries) does NOT need it. (STRUCK 2026-08-13: this line
+ *     used to name "Sonnet 4.6 / Opus 4.7" as the ceiling. Naming versions in
+ *     a rationale paragraph is how a docblock rots — the CURRENT pair is
+ *     recorded in exactly one place now, ANTHROPIC_DEFAULT.models below, with
+ *     its provenance and refresh path.)
  *   - Moonshot exposes a native `/anthropic` Messages endpoint, so
  *     Kimi K2.6 is a literal drop-in for Claude Code — no router,
  *     no translation, no tool-use degradation.
- *   - Qwen3-Coder via OpenRouter is one router-hop away and significantly
- *     cheaper; usable for agents that don't need extended-thinking or
- *     parallel tool calls.
+ *   - Qwen is one hop away and significantly cheaper; usable for agents that
+ *     don't need extended-thinking or parallel tool calls. (A v1 config can
+ *     reach it through any OpenAI-compat gateway, which is what the v1 tests
+ *     model; the v2 bundled catalog reaches it on DashScope and marks it
+ *     harness.session:false — Qwen is a direct/batch lane model there, not a
+ *     session host.)
  *
  * What this is NOT:
  *   - Not a wire-format translator. We rely on the backend speaking
@@ -90,6 +97,67 @@ try {
 // Anthropic-only fallback so existing agents keep working unchanged.
 // ---------------------------------------------------------------------------
 
+/**
+ * MODEL IDS — PROVENANCE AND REFRESH PATH  (last refreshed 2026-08-13)
+ * ────────────────────────────────────────────────────────────────────
+ * WHERE THIS LIST CAME FROM: the Anthropic model list was verified against the
+ * vendor docs on 2026-08-13 (context7 → Anthropic model reference). Current at
+ * that date: claude-opus-5 (frontier, 1M ctx, 128k out, $5/$25 per MTok),
+ * claude-sonnet-5 (workhorse), claude-haiku-4-5-20251001 (fast/classifier —
+ * still current, deliberately NOT bumped). Two more exist and are deliberately
+ * absent from this map: claude-fable-5 ($10/$50, long-running agents — a cost
+ * decision, not a default) and claude-mythos-5 (restricted to Project
+ * Glasswing — must never be offered as a general option).
+ *
+ * HOW THE NEXT PERSON REFRESHES IT — in order of preference, and note that the
+ * first two need NO code change and NO release, which is the whole point:
+ *
+ *   1. v2 (schema_version: 2) agents: the CATALOG is the source of truth, not
+ *      this file. Add/replace rows in lib/model-router/catalog/<provider>.yaml
+ *      (ships with the SDK) or, without touching the SDK at all, patch them
+ *      per-agent via `catalog_overrides:` in config/model-routing.yaml — that
+ *      layer outranks the bundled rows (see catalog.mjs's authority merge) and
+ *      can even introduce a provider the SDK does not bundle. Then repoint the
+ *      `aliases:` (frontier/default/fast/cheap) at the new refs.
+ *   2. v1 agents: declare `backends.anthropic.models` in
+ *      config/model-routing.yaml. normaliseConfig only injects the map below
+ *      when `backends.anthropic` is ABSENT, so a config-declared map wins
+ *      outright — no PR, no build.
+ *   3. Editing the map below is the LAST resort: it is the floor for an agent
+ *      with no routing config at all.
+ *
+ * WHY THE STALE IDS HERE WERE SURVIVABLE (and so went unnoticed for a release):
+ * for `transport: "anthropic-cli"` — the default, keychain-OAuth path — THIS
+ * FILE'S modelFlagFor() sends the version-agnostic shorthand
+ * "opus"/"sonnet"/"haiku" and lets Anthropic resolve the current version, so a
+ * stale id in the map below did not reach the wire. It DID reach
+ * `resolved.model`, which is what the cost ledger, telemetry and session records
+ * store; a stale id there mis-prices and mis-attributes work. That is the damage
+ * this refresh repairs ON THE v1 PATH.
+ *
+ * ── DO NOT GENERALISE THAT TO THE ROUTER. THE v2 LANE IS STILL STALE. ────────
+ * NARROWED 2026-08-13, because the sentence above reads as a router-wide
+ * reassurance and is false as one. Two different functions are called
+ * `modelFlagFor`:
+ *   - this file's (v1)  — maps tier → "opus"/"sonnet"/"haiku" shorthand, and
+ *     only for the four known tiers; an unrecognised `request.tier` falls
+ *     through to `return resolved.model`, the literal id.
+ *   - resolve.mjs's (v2, line ~468) — `return row.id`, ALWAYS the literal
+ *     catalog id. spawn.mjs then does `args.push("--model", String(modelFlag))`.
+ * So on the v2 lane the catalog id IS the wire value, and the SHIPPED catalog
+ * (lib/model-router/catalog/anthropic.yaml) still carries only 4-x rows.
+ * Measured on this tree, with no routing config present — the default state,
+ * since the repo ships no config/model-routing.yaml at all:
+ *     ordinary session   → claude --model claude-sonnet-4-6
+ *     critical/thinking  → claude --model claude-opus-4-8
+ * The -5 ids added to resolve.mjs's pickAnthropicRow preference list are
+ * therefore INERT in production: lookupModel misses them against the bundled
+ * catalog and the ordered succession tail answers with the 4-x row. They become
+ * live the moment anthropic.yaml gains `claude-opus-5` / `claude-sonnet-5` rows,
+ * which is the one remaining step of this refresh and is NOT done. Until then,
+ * "the agent-sdk uses the latest Anthropic models" is true of the v1 floor only.
+ * See the guard test "the SHIPPED catalog is what decides the wire value".
+ */
 const ANTHROPIC_DEFAULT = Object.freeze({
   transport: "anthropic-cli", // special: do nothing (current behaviour)
   base_url: "https://api.anthropic.com",
@@ -102,11 +170,30 @@ const ANTHROPIC_DEFAULT = Object.freeze({
     "parallel_tools",
     "long_context_1m",
   ],
-  pricing: { input_per_m: 3.0, output_per_m: 15.0 }, // Sonnet 4.6 ballpark
+  // $/MTok. STRUCK "Sonnet 4.6 ballpark" (2026-08-13): these figures are
+  // LINE-INHERITED from Sonnet 4.6's list price and are NOT vendor-confirmed for
+  // Sonnet 5 — only Opus 5 ($5/$25) was confirmed in the 2026-08-13 sweep. The
+  // v2 lane does not use this at all (it prices from the catalog row's `cost`
+  // block, with its own cost_provenance stamp).
+  //
+  // NARROWED 2026-08-13: an earlier version of this note opened "$/MTok for the
+  // `default` tier", which implies a per-tier price. THERE IS NO PER-TIER PRICE
+  // ON THE v1 LANE. `resolveBackend` returns `pricing: backend.pricing` — this
+  // one block — for every tier, and `estimateCost` multiplies by it regardless
+  // of which model was chosen. So premium work is billed at the WORKHORSE rate:
+  // with premium now claude-opus-5 at a confirmed $5/$25, every v1 opus estimate
+  // is low by ~1.7x on both input and output, and always was (Opus 4.7 was
+  // dearer than $3/$15 too). Refreshing the ids did not touch this and did not
+  // cause it. Fixing it means per-tier pricing in the backend shape — a schema
+  // change with config-compat consequences, deliberately not smuggled into an
+  // id refresh. Until then, treat v1 `estimateCost` as a floor, not a bill.
+  pricing: { input_per_m: 3.0, output_per_m: 15.0 },
   models: {
     classifier: "claude-haiku-4-5-20251001",
-    default: "claude-sonnet-4-6",
-    premium: "claude-opus-4-7",
+    default: "claude-sonnet-5",
+    premium: "claude-opus-5",
+    // Current as of 2026-08-13 — the fast tier did NOT move when opus/sonnet
+    // did. Do not "helpfully" bump this to a -5 id that does not exist.
     fast: "claude-haiku-4-5-20251001",
   },
 });