@1aboveio/skills 0.10.0

package/skills/engineering/harness-runtime/model-catalog.mjs

@@ -0,0 +1,787 @@
+// model-catalog — canonical harness-runtime read/write helper for the banked model catalog.
+//
+// The catalog (references/model-catalog.md) is the per-harness user-level JSON where
+// pre-flight banks human-confirmed model classifications (family · `tiers`, a map
+// from effort to the tier the model reaches there, in that harness's own id
+// vocabulary) so later runs read them instead of re-asking. Since auto-pruning landed, every
+// pre-flight read is also a WRITE (bump `lastSeenAt` on discovered entries, prune
+// entries unseen for more than PRUNE_AFTER_DAYS) — exactly the hand-rolled
+// read-modify-write on a load-bearing artifact that run-state.mjs exists to avoid
+// on the manifest. This script single-sources the prune predicate and the two
+// write paths (maintenance sync at read, classification bank at confirmation).
+//
+//   node model-catalog.mjs read                          # print JSON (exit 3 if absent — normal; alias: list)
+//   node model-catalog.mjs path                          # print the resolved file path
+//   node model-catalog.mjs points [<id>]                 # list banked operating points
+//                                                        #   ({effort, tier, slotEligible}, strongest
+//                                                        #   first). slotEligible is wired to
+//                                                        #   SLOT_ELIGIBLE_TIERS so a scoped-coder is
+//                                                        #   MARKED, never hidden — see operatingPoints.
+//   node model-catalog.mjs sync --seen <id,id,...>       # bump lastSeenAt for the discovered ids,
+//                                                        #   prune stale entries, print {bumped, pruned}
+//   node model-catalog.mjs bank <entryJson>              # upsert a classification by id (sets
+//                                                        #   confirmedAt + lastSeenAt; creates the file)
+//
+//   --harness <name> resolve the file to that harness's own catalog location
+//                    (claude-code | codex | pi — one catalog PER HARNESS, never shared:
+//                    model-catalog.md "Location"); writes guard against the file's own
+//                    `harness` stamp so a codex catalog can't absorb claude-code entries.
+//                    Default: claude-code (~/.claude/model-catalog.json).
+//   --file <path>    operate on an explicit catalog path (overrides --harness; for
+//                    harnesses this script has no location mapping for)
+//   --today <date>   pin the date (YYYY-MM-DD; default: system clock; for deterministic tests)
+//   --stdin          read <entryJson> from stdin instead of argv
+//
+//   node model-catalog.mjs tiers --seen <id,id,...> [--harness <h>]
+//                                                        # PREFER THIS at pre-flight step 2: composes
+//                                                        #   banked -> cross-harness -> seed with the
+//                                                        #   precedence guaranteed, returning one decided
+//                                                        #   answer per model plus seedDisagreements.
+//                                                        #   The three arms below exist for isolation.
+//   node model-catalog.mjs cross-harness --seen <id,id,...> [--harness <h>]
+//                                                        # rule 5: tier pre-fills from the OTHER
+//                                                        #   harnesses' catalogs, restricted to this
+//                                                        #   run's discovered ids. Prose-only until
+//                                                        #   2026-07-20 despite OUTRANKING the seed.
+//   node model-catalog.mjs bank-from-seed <id> [--harness <h>]
+//                                                        # bank a confirmed seed-backed proposal via
+//                                                        #   entryFromSeedConfirmation (fresh confirmedAt,
+//                                                        #   this harness's tiers) instead of hand-writing
+//                                                        #   the entry JSON.
+//   node model-catalog.mjs help                           # the command list
+//   node model-catalog.mjs seed                          # print the team seed (read-only; exit 3 if absent)
+//   node model-catalog.mjs seed-proposals --seen <id,id,...> [--harness <h>]
+//                                                        # {proposals, suppressed} — seed-backed pre-fills
+//                                                        #   for THIS run's discovered ids only (rule 3) and
+//                                                        #   only where this harness's own catalog has banked
+//                                                        #   nothing (rule 7 precedence, per MODEL); each
+//                                                        #   carries its citation. `suppressed` names what
+//                                                        #   the catalog outranked, flagging `disagrees`
+//                                                        #   where the seed has gone stale.
+//
+//   --seed-file <path> operate on an explicit seed path (default: the shipped
+//                      references/model-catalog-seed.json beside this module)
+//
+// Absence is NORMAL (model-catalog.md "Location"): `read`/`sync` exit 3 so the
+// caller classifies from discovery-source evidence; only `bank` creates the file.
+//
+// The seed (references/model-catalog-seed.json, model-catalog.md rule 7) is a
+// SEPARATE, READ-ONLY file — evidence, not truth, the same epistemic class as
+// rule 5 (cross-harness) and rule 6 (benchmark). Neither `bank` nor `sync` ever
+// accepts the seed as a write target (see refuseIfSeedWrite below): a seed write
+// would let a machine guess masquerade as a human confirmation, which is the one
+// thing `bank` exists to prevent.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// model-catalog.md rule 4: an entry unseen for MORE THAN this many days is pruned.
+export const PRUNE_AFTER_DAYS = 60
+
+// Freshness on the OTHER axis. PRUNE_AFTER_DAYS watches `lastSeenAt` (availability
+// recency — has the model been discovered lately). This watches `confirmedAt`
+// (classification recency — how old is the human judgment). A model discovered every
+// day never prunes, yet its tier can be frozen for weeks: grok-4.5 stayed
+// `deep-reasoner` (confirmed 2026-07-19) while the seed had demoted it to
+// `balanced-coder`. An entry whose classification is older than this is FLAGGED
+// `staleClassification` at pre-flight — surfaced for re-confirmation, never
+// auto-changed (unlike prune, which acts).
+export const CLASSIFY_STALE_AFTER_DAYS = 30
+
+// Capability bands, top to bottom. Every name describes what a model IS — never
+// where it sits in a list, never when it shipped; both renames below were cases of
+// a name drifting off that rule (rationale on LEGACY_TIERS). Note `deep-reasoner`
+// does not by itself separate its band from `frontier` (frontier models reason
+// deeply too) — the definition carries that: it is the band BELOW the current top
+// end (model-catalog.md `tiers`).
+//
+// `scoped-coder` (added 2026-07-20) is the one band that exists to NOT be picked.
+// The other three each have a home slot; this one has none, and that is its point.
+// It marks a model that executes a change someone else scoped but cannot hold a
+// task together across a long agentic trajectory — so banking it answers "what is
+// this model" once and stops pre-flight re-asking every run (rule 1 would otherwise
+// tag it `unconfirmed — please classify` forever), while leaving it below every
+// slot's floor. Named for what it IS, not its rank: `low-tier` would repeat the
+// `mid-tier` mistake, and `budget` would name a price rather than a capability.
+export const TIERS = ['frontier', 'deep-reasoner', 'balanced-coder', 'scoped-coder']
+
+// Bands that may fill a slot. `scoped-coder` is deliberately absent — pre-flight
+// offers it as a *classification*, never as a candidate for implementer or
+// reviewer. Kept as its own list rather than "all but the last" so adding a future
+// band has to state its own answer instead of inheriting one by position.
+export const SLOT_ELIGIBLE_TIERS = ['frontier', 'deep-reasoner', 'balanced-coder']
+
+// Renamed tiers, old -> new. Legacy values are ACCEPTED and normalized rather
+// than rejected: catalogs are user data that predate the renames, and a hard
+// failure would strand them (same posture as run-state's obsolete-field warnings).
+//   prior-frontier -> deep-reasoner   encoded a CHRONOLOGY ("the previous
+//     generation's frontier") for what is a capability band, so a newly released
+//     model that landed in it had no honest home.
+//   mid-tier -> balanced-coder        encoded an ORDINAL POSITION, and an
+//     inaccurate one: with the three bands that existed at the rename it was the
+//     bottom, not the middle (scoped-coder was added below it later).
+export const LEGACY_TIERS = {
+  'prior-frontier': 'deep-reasoner',
+  'mid-tier': 'balanced-coder',
+}
+
+export function normalizeTier(tier) {
+  return LEGACY_TIERS[tier] || tier
+}
+
+// Efforts an operating point may be banked at (model-catalog.md `tiers`).
+// Deliberately floored at `high`: a point records what a model REACHES when
+// pushed, never a throttled-down cheap seat — a cheaper operating point is a
+// cheaper MODEL (pre-flight.md step 2). `high` is the default point, so a
+// single-point entry banked without an effort behaves as it always did.
+export const EFFORTS = ['high', 'xhigh', 'max']
+export const DEFAULT_EFFORT = 'high'
+
+// An entry's capability is a MAP from effort to the tier it reaches there:
+//
+//   "tiers": { "high": "balanced-coder", "max": "deep-reasoner" }
+//
+// One model can therefore be a routine implementer at high AND a deep reasoner
+// at max, and pre-flight offers each point as its own slot candidate. This is
+// tier = f(model, effort) — the shape removed on 2026-07-13 — restored on
+// 2026-07-19 with the cost that killed it removed: the pairs are banked ONCE at
+// classification, so no per-slot, per-run effort question ever returns.
+//
+// Legacy single-point entries ({tier} or {tier, effort}) fold into a one-key map.
+export function toTiers(entry) {
+  if (entry?.tiers) {
+    const out = {}
+    for (const [effort, tier] of Object.entries(entry.tiers)) out[effort] = normalizeTier(tier)
+    return out
+  }
+  if (entry?.tier) return { [entry.effort || DEFAULT_EFFORT]: normalizeTier(entry.tier) }
+  return {}
+}
+
+// Whether a tier may fill a slot. Wired here rather than left for a caller to
+// remember, because SLOT_ELIGIBLE_TIERS spent its whole life as a constant no
+// production code read: model-catalog.md said banking `scoped-coder` "keeps the
+// model out of every slot's candidate list (SLOT_ELIGIBLE_TIERS)" and nothing
+// consulted it, so `points` handed scoped-coder models back undistinguished and
+// an agent building slot lists from that output offered them as implementer
+// candidates — inverting the one rule the band exists to enforce.
+export function isSlotEligible(tier) {
+  return SLOT_ELIGIBLE_TIERS.includes(tier)
+}
+
+// Every banked operating point, strongest first, as [{ effort, tier, slotEligible }].
+//
+// Each point is MARKED, never filtered out. The distinction matters: a
+// scoped-coder classification is a real, useful answer — banking it is what
+// stops pre-flight re-asking about the same model every run (rule 1) — so
+// hiding those models would defeat the band's purpose. What must not happen is
+// the classification flowing into a slot candidate list. Marking lets pre-flight
+// show "classified scoped-coder — not a slot candidate" and keeps both
+// properties; filtering would buy the second by destroying the first.
+export function pointsFromTiers(tiers) {
+  return Object.entries(tiers || {})
+    .map(([effort, tier]) => ({ effort, tier, slotEligible: isSlotEligible(tier) }))
+    .sort((a, b) => TIERS.indexOf(a.tier) - TIERS.indexOf(b.tier) || EFFORTS.indexOf(a.effort) - EFFORTS.indexOf(b.effort))
+}
+
+export function operatingPoints(catalog, id) {
+  return pointsFromTiers(toTiers((catalog?.models || []).find((m) => m && m.id === id)))
+}
+
+// The tier this model reaches at a given effort (null if no such point is banked).
+export function tierAt(catalog, id, effort) {
+  return toTiers((catalog?.models || []).find((m) => m && m.id === id))[effort] || null
+}
+
+// Known harness → user-config catalog location (model-catalog.md "Location" —
+// one catalog per harness, never shared across harnesses).
+export const HARNESS_PATHS = {
+  'claude-code': ['.claude', 'model-catalog.json'],
+  codex: ['.codex', 'model-catalog.json'],
+  pi: ['.pi', 'agent', 'model-catalog.json'],
+}
+
+export function pathForHarness(harness, env = process.env) {
+  const segs = HARNESS_PATHS[harness]
+  if (!segs) return null
+  const home = env.HOME || os.homedir()
+  return path.join(home, ...segs)
+}
+
+export function defaultPath(env = process.env) {
+  return pathForHarness('claude-code', env)
+}
+
+// ---- the team seed (model-catalog.md rule 7) — read-only, evidence not truth ----
+
+// The seed ships beside this module under references/model-catalog-seed.json.
+// Resolve from import.meta.url so source, copied flat installs, and Claude Code
+// symlink launches all read the installed package's immutable seed.
+export function defaultSeedPath() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), 'references', 'model-catalog-seed.json')
+}
+
+// Same absent-is-normal contract as readCatalog: a skill install that hasn't
+// shipped a seed (or a caller pointing at a scratch path in a test) just gets
+// null, and the caller falls through to discovery-source evidence.
+export function readSeed(file) {
+  if (!fs.existsSync(file)) return null
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+// A seed entry's `ids` map already holds the fully-resolved per-harness id —
+// alias resolution happened ONCE, by a human, when the entry was authored
+// (model-catalog.md rule 7's "must not guess"), so a lookup here is a direct
+// equality check, never a live normalization guess.
+export function findSeedEntry(seed, harness, id) {
+  return (seed?.models || []).find((m) => m?.ids && m.ids[harness] === id) || null
+}
+
+// The tiers this seed entry claims for one harness, {} if the entry doesn't
+// cover that harness at all (e.g. an entry seeded from a single harness's
+// catalog only, model-catalog-seed.json's `sonnet` row).
+export function seedTiersFor(seed, harness, id) {
+  const entry = findSeedEntry(seed, harness, id)
+  return entry?.tiers?.[harness] || {}
+}
+
+export function seedTierAt(seed, harness, id, effort) {
+  return seedTiersFor(seed, harness, id)[effort] || null
+}
+
+// A tiers map as one readable clause, for the citations pre-flight prints.
+function fmtTiers(tiers) {
+  return `{${Object.entries(tiers).map(([e, t]) => `${e}:${t}`).sort().join(', ')}}`
+}
+
+// True when two tiers maps state exactly the same operating points.
+function sameTiers(a, b) {
+  const ka = Object.keys(a).sort()
+  const kb = Object.keys(b).sort()
+  return ka.length === kb.length && ka.every((k, i) => k === kb[i] && a[k] === b[k])
+}
+
+// Rules 3 AND 7, both mechanized here, because this is the one call pre-flight
+// actually makes — a precedence rule the caller is trusted to apply by hand is
+// a rule that silently stops holding.
+//
+//   { proposals, suppressed }
+//
+// `proposals` — seed entries that survive BOTH filters:
+//   rule 3 (availability): only ids THIS RUN'S DISCOVERY yielded (discoveredIds).
+//     An entry the seed carries for an id discovery didn't produce is silently
+//     excluded, never surfaced (issue #370) — a seed that leaked into
+//     availability would let pre-flight propose a model the runtime cannot run.
+//   rule 7 (precedence): only ids with NO banked entry in the caller's own
+//     catalog. "A user's own measurement always beats the shipped default" —
+//     and it beats it PER MODEL, not per effort. That distinction is the whole
+//     point: a human who deliberately drops an operating point (banking example-coder-2
+//     at {high} after deciding its max point wasn't real) leaves no banked tier
+//     at `max`, so a per-effort merge would read the deletion as silence and
+//     hand the point straight back from the seed, every run, forever. A banked
+//     entry is a complete statement of that model's points in this harness.
+//
+// `suppressed` — what rule 7 dropped, with `disagrees` set when the seed's
+// claim differs from what the human banked. Reported, never silent: a
+// disagreement is the signal that the shipped seed has gone stale relative to
+// this user's measurements, and it is the only place that staleness is visible
+// (the seed can't be diffed against user-level catalogs in CI — they aren't in
+// the repo). Pre-flight surfaces it as a nudge to a seed owner, never as a
+// proposal, and never as a reason to re-ask a classification rule 1 settled.
+export function seedProposals(seed, harness, discoveredIds, catalog = null) {
+  const discovered = new Set(discoveredIds)
+  const proposals = []
+  const suppressed = []
+  for (const entry of seed?.models || []) {
+    const id = entry?.ids?.[harness]
+    if (!id || !discovered.has(id)) continue
+    const tiers = entry.tiers?.[harness]
+    if (!tiers || !Object.keys(tiers).length) continue // this entry says nothing about THIS harness
+    // Check the POINTS, not the field: an entry carrying `tiers: {}` classifies
+    // nothing, so it must not suppress the seed's pre-fill (same guard as bank).
+    const bankedEntry = (catalog?.models || []).find((m) => m && m.id === id)
+    const banked = toTiers(bankedEntry)
+    if (Object.keys(banked).length) {
+      const disagrees = !sameTiers(banked, tiers)
+      // Date-aware disagreement. "Your catalog wins (rule 7)" is the right default only
+      // while the banked entry is at least as fresh as the seed. When the seed DISAGREES
+      // and is NEWER than the human's banked confirmation, the seed may carry a
+      // reclassification the banked entry predates — the grok-4.5 case: seed demoted
+      // 2026-07-22, banked confirmed 2026-07-19. Flag it so pre-flight nudges toward
+      // re-confirmation instead of silently keeping the stale banked tier.
+      const seededAt = seed?.seededAt
+      const bankedConfirmedAt = bankedEntry?.confirmedAt
+      const seedNewer = disagrees && !!seededAt && !!bankedConfirmedAt && seededAt > bankedConfirmedAt
+      suppressed.push({ id, canonical: entry.canonical, banked, seed: tiers, disagrees, seededAt, bankedConfirmedAt, seedNewer })
+      continue
+    }
+    // `points` carries the same slotEligible marking as operatingPoints, so a
+    // seed-backed pre-fill and a banked entry are read the same way. Without it
+    // the shipped seed's six scoped-coder entries reached a fresh install's
+    // proposal block as team-endorsed slot options.
+    proposals.push({ id, canonical: entry.canonical, family: entry.family, tiers, points: pointsFromTiers(tiers), note: entry.note })
+  }
+  return { proposals, suppressed }
+}
+
+// ---- rule 5: another harness's catalog as tiering evidence ----
+
+// "Plainly matches" from model-catalog.md rule 5, made mechanical. The rule
+// transfers a tier between harnesses ONLY when one id is the other with a
+// `provider/` prefix attached or removed (`openai/gpt-5.6-sol` <-> `gpt-5.6-sol`).
+//
+// What it must REFUSE is the point. A harness-local alias (`sonnet`) normalizes
+// to nothing and gets no cross-harness pre-fill. And a pair that merely looks
+// related is not a match: the shipped seed documents this exact trap — stripping
+// `kimi-coding/` from `kimi-coding/k3` gives `k3`, not `kimi-k3`, so the seed's
+// authors deliberately kept those as two entries pending human confirmation. An
+// agent hand-applying rule 5 under time pressure makes that merge anyway and
+// transfers a tier its authors declined to transfer — while citing it as
+// `tier from pi catalog`, which reads like mechanized provenance. This function
+// is what makes the refusal survive contact with a tired reader.
+export function plainlyMatches(idA, idB) {
+  if (idA === idB) return true
+  const strip = (id) => (id.includes('/') ? id.slice(id.indexOf('/') + 1) : null)
+  return strip(idA) === idB || strip(idB) === idA
+}
+
+// Rule 5, end to end: for each discovered id with nothing banked in THIS
+// harness's catalog, look through the OTHER harnesses' catalogs for a plainly
+// matching entry and return its tiers as a pre-fill, citation included.
+//
+// Availability never transfers (rule 3, which applies doubly here): the result
+// is restricted to discoveredIds, so a model another harness has banked but this
+// harness cannot run never becomes a proposal.
+export function crossHarnessProposals(harness, discoveredIds, { readAt = readCatalog, paths = HARNESS_PATHS } = {}) {
+  const discovered = new Set(discoveredIds)
+  const own = readAt(pathForHarness(harness)) || { models: [] }
+  const out = []
+  for (const id of discovered) {
+    if (Object.keys(toTiers((own.models || []).find((m) => m && m.id === id))).length) continue // rule 1 outranks
+    for (const other of Object.keys(paths)) {
+      if (other === harness) continue
+      const cat = readAt(pathForHarness(other))
+      const hit = (cat?.models || []).find((m) => m && plainlyMatches(m.id, id))
+      const tiers = toTiers(hit)
+      if (!Object.keys(tiers).length) continue
+      out.push({
+        id,
+        matchedId: hit.id,
+        fromHarness: other,
+        family: hit.family,
+        tiers,
+        points: pointsFromTiers(tiers),
+        citation: `tier from ${other} catalog: ${hit.id}`,
+      })
+      break // first match wins; the harness order in HARNESS_PATHS is the tiebreak
+    }
+  }
+  return out
+}
+
+// Precedence order (model-catalog.md rule 7): own banked entry -> own
+// other-harness catalog (rule 5) -> team seed -> discovery-source evidence ->
+// unconfirmed. Resolved per MODEL, on whole `tiers` maps.
+//
+// This REPLACED resolveTierPrecedence on 2026-07-20. That function took one
+// scalar tier per source and resolved a single (model, effort) point — a shape
+// that had to be defended with a comment telling callers not to merge a seed's
+// points into a banked entry one effort at a time. A signature whose parameters
+// invite the bug its own comment forbids is a trap, not a safeguard: the next
+// caller reads the types, not the paragraph. Taking whole maps makes the
+// per-model rule the only thing you *can* express, so a deliberately-deleted
+// operating point cannot be restored from a weaker source no matter how the
+// call is written.
+//
+// `discoveryTiers` is the one arm no command can supply — it is evidence the
+// agent gathers (provider docs, pricing, benchmarks per rule 6). Pass it when
+// you have it; without it a model no banked/cross-harness/seed source covers
+// resolves to `unconfirmed`, which is the honest answer and the one pre-flight
+// prints as `tier: unconfirmed — please classify`.
+export function resolveModelTiers({ banked, crossHarness, seed, discoveryTiers } = {}) {
+  const has = (t) => t && Object.keys(t).length > 0
+  if (has(banked)) return { tiers: banked, source: 'banked', citation: null }
+  if (has(crossHarness?.tiers)) {
+    return { tiers: crossHarness.tiers, source: 'cross-harness', citation: crossHarness.citation }
+  }
+  if (has(seed?.tiers)) return { tiers: seed.tiers, source: 'team-seed', citation: seed.citation }
+  if (has(discoveryTiers)) return { tiers: discoveryTiers, source: 'discovery', citation: null }
+  return { tiers: {}, source: 'unconfirmed', citation: null }
+}
+
+// The whole of pre-flight step 2's tiering, in one call: for every discovered
+// id, which source wins and what it says. Composing the three mechanized arms
+// here is the point — run separately, their precedence is re-applied by hand at
+// the gate, and that hand-application is what failed. Callers get a decided
+// answer plus the citation to print, never a pile of candidate sources to rank.
+export function tierProposals(harness, discoveredIds, { seedFile = null, readAt = readCatalog, today = null, catalogFile = null } = {}) {
+  const day = today || new Date().toISOString().slice(0, 10)
+  // The OWN catalog honors an explicit path (CLI `--file`), same as seed-proposals/sync/bank.
+  // Without this, `tiers --file <catalog>` silently reads the default per-harness path instead —
+  // so its `seedDisagreements`/`staleClassifications` describe the wrong catalog. Cross-harness
+  // reads below stay at the standard per-harness locations (a foreign catalog is not relocatable).
+  const own = readAt(catalogFile || pathForHarness(harness)) || { models: [] }
+  const seed = readSeed(seedFile || defaultSeedPath())
+  const cross = crossHarnessProposals(harness, discoveredIds, { readAt })
+  const { proposals: seeded, suppressed } = seedProposals(seed, harness, discoveredIds, own)
+
+  const byId = (list) => new Map(list.map((x) => [x.id, x]))
+  const crossById = byId(cross)
+  const seedById = byId(seeded)
+
+  return {
+    models: discoveredIds.map((id) => {
+      const banked = toTiers((own.models || []).find((m) => m && m.id === id))
+      const r = resolveModelTiers({ banked, crossHarness: crossById.get(id), seed: seedById.get(id) })
+      return { id, ...r, points: pointsFromTiers(r.tiers) }
+    }),
+    // Surfaced, not swallowed: a seed that disagrees with what the human banked
+    // is the only signal that the shipped seed has gone stale (it cannot be
+    // diffed against user-level catalogs in CI — they are not in the repo).
+    // `seedNewer` on a disagreement flips the nudge: the SEED may be the fresher answer.
+    seedDisagreements: suppressed.filter((s) => s.disagrees),
+    // Classification-staleness (CLASSIFY_STALE_AFTER_DAYS): a discovered model whose
+    // banked classification is older than the threshold — a candidate for re-confirmation
+    // before it is offered for a slot. Surfaced, never changed.
+    staleClassifications: (own.models || [])
+      .filter((m) => m && discoveredIds.includes(m.id) && m.confirmedAt && dayDiff(m.confirmedAt, day) > CLASSIFY_STALE_AFTER_DAYS)
+      .map((m) => ({ id: m.id, confirmedAt: m.confirmedAt, ageDays: dayDiff(m.confirmedAt, day) })),
+  }
+}
+
+// A seed entry is never treated as confirmedAt (model-catalog.md rule 7): this
+// is the shape `bank` writes once the human confirms a seed-backed proposal —
+// a normal entry, stamped fresh, into the user's OWN per-harness file. It
+// carries no trace back to the seed beyond the note a caller chooses to keep.
+export function entryFromSeedConfirmation(seed, harness, id, today) {
+  const entry = findSeedEntry(seed, harness, id)
+  if (!entry) throw new Error(`entryFromSeedConfirmation: no seed entry for "${id}" under harness "${harness}"`)
+  const tiers = entry.tiers?.[harness]
+  if (!tiers || !Object.keys(tiers).length) {
+    throw new Error(`entryFromSeedConfirmation: seed entry "${entry.canonical}" has no tiers for harness "${harness}"`)
+  }
+  return { id, family: entry.family, tiers, confirmedAt: today, lastSeenAt: today }
+}
+
+// ---- pure catalog transforms ----
+
+function dayDiff(fromIso, toIso) {
+  return Math.floor((Date.parse(toIso) - Date.parse(fromIso)) / 86_400_000)
+}
+
+// Rule 4 in one place: bump lastSeenAt for every seen id, then drop entries whose
+// lastSeenAt (falling back to confirmedAt) is more than PRUNE_AFTER_DAYS old.
+// Bump-before-prune, so a rediscovered entry is never pruned in the same sync.
+export function syncCatalog(catalog, seenIds, today) {
+  const seen = new Set(seenIds)
+  const bumped = []
+  const kept = []
+  const pruned = []
+  const migrated = []
+  for (const entry of catalog.models || []) {
+    const e = { ...entry }
+    // Schema migration rides along with the sync write that every pre-flight read
+    // already performs — no separate migration step, nothing stale left behind.
+    // Two generations are healed here: renamed tier values, and the single-point
+    // {tier, effort} shape that predates the `tiers` map.
+    const fmt = (m) => Object.entries(m).map(([k, v]) => `${k}:${v}`).sort().join(',')
+    const before = e.tiers ? fmt(e.tiers) : (e.tier ? `${e.effort || DEFAULT_EFFORT}:${e.tier}` : '')
+    const tiers = toTiers(e)
+    const after = fmt(tiers)
+    if (before !== after || !e.tiers) {
+      if (before !== after) migrated.push(`${e.id}: {${before}} -> {${after}}`)
+      else migrated.push(`${e.id}: tier/effort -> tiers map {${after}}`)
+    }
+    e.tiers = tiers
+    delete e.tier
+    delete e.effort
+    if (seen.has(e.id)) {
+      e.lastSeenAt = today
+      bumped.push(e.id)
+    }
+    const basis = e.lastSeenAt || e.confirmedAt
+    if (basis && dayDiff(basis, today) > PRUNE_AFTER_DAYS) pruned.push(e.id)
+    else kept.push(e)
+  }
+  return { catalog: { ...catalog, models: kept }, bumped, pruned, migrated }
+}
+
+// Rule 2: a bank is a human confirmation — upsert by id, refresh confirmedAt
+// (and lastSeenAt: a model being confirmed was necessarily just discovered).
+export function bankEntry(catalog, entry, today) {
+  if (!entry || !entry.id) throw new Error('bank: the entry must have an "id"')
+  if (!entry.family) throw new Error('bank: "family" is required (model-catalog.md schema)')
+  if (!entry.tiers && !entry.tier) throw new Error('bank: one of "tiers" (effort -> tier map) or "tier" is required (model-catalog.md schema)')
+
+  if (entry.tiers && (Array.isArray(entry.tiers) || typeof entry.tiers !== 'object')) {
+    throw new Error('bank: "tiers" must be an object mapping effort -> tier (model-catalog.md schema)')
+  }
+
+  const incoming = toTiers(entry)
+  // An entry with no operating point is a cataloged model with no classification:
+  // tierAt returns null at every effort, pre-flight sees a hit with nothing in it,
+  // and no later sync flags it. `tiers: {}` passes a truthiness guard, so check the
+  // POINTS, not the field.
+  if (!Object.keys(incoming).length) {
+    throw new Error('bank: the entry has no operating points — "tiers" must hold at least one effort -> tier pair')
+  }
+  for (const [effort, tier] of Object.entries(incoming)) {
+    if (!EFFORTS.includes(effort)) {
+      throw new Error(`bank: effort "${effort}" not in ${EFFORTS.join('|')} — a point records what a model reaches when pushed, never a throttled-down cheap seat (pick a cheaper model instead)`)
+    }
+    if (!TIERS.includes(tier)) throw new Error(`bank: tier "${tier}" not in ${TIERS.join('|')}`)
+  }
+
+  const models = [...(catalog.models || [])]
+  const i = models.findIndex((m) => m && m.id === entry.id)
+  const existing = i === -1 ? null : models[i]
+
+  // A full `tiers` map REPLACES what was banked (the human restated the whole
+  // picture); a single `tier` UPSERTS just that point, so operating points can be
+  // confirmed one at a time as they are measured, without erasing the others.
+  const tiers = entry.tiers ? incoming : { ...toTiers(existing), ...incoming }
+
+  // The legacy single-point fields never persist — and that has to be enforced on
+  // BOTH sides of the merge. Stripping only the incoming entry left `existing.tier`
+  // spread back in with nothing in `stamped` to shadow it, so an upsert onto a
+  // pre-`tiers` entry stored a `tier` that could flatly contradict the map
+  // ("tier": "frontier" beside "tiers": {"high": "balanced-coder"}). Reads go
+  // through toTiers and were fine; the FILE was wrong, which is what a human and a
+  // cross-harness lookup (catalog rule 5) actually inspect.
+  const strip = ({ tier: _t, effort: _e, ...rest }) => rest
+  const stamped = { ...strip(entry), tiers, confirmedAt: today, lastSeenAt: today }
+  if (i === -1) models.push(stamped)
+  else models[i] = { ...strip(existing), ...stamped }
+  return { ...catalog, models }
+}
+
+// ---- file I/O (atomic write, same as run-state.mjs) ----
+
+export function readCatalog(file) {
+  if (!fs.existsSync(file)) return null
+  return JSON.parse(fs.readFileSync(file, 'utf8'))
+}
+
+export function writeCatalog(file, catalog) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(catalog, null, 2)}\n`)
+  fs.renameSync(tmp, file)
+}
+
+// ---- CLI ----
+
+function parseArgs(argv) {
+  const positional = []
+  const opts = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--stdin') opts.stdin = true
+    else if (a === '--file') opts.file = argv[++i]
+    else if (a === '--harness') opts.harness = argv[++i]
+    else if (a === '--today') opts.today = argv[++i]
+    else if (a === '--seen') opts.seen = argv[++i]
+    else if (a === '--seed-file') opts.seedFile = argv[++i]
+    else positional.push(a)
+  }
+  return { positional, opts }
+}
+
+function todayIso(opts) {
+  return opts.today || new Date().toISOString().slice(0, 10)
+}
+
+// A write into a file stamped for another harness is cross-contamination
+// (its ids live in a different vocabulary) — refuse it.
+function harnessMismatch(catalog, opts, file) {
+  if (catalog && catalog.harness && opts.harness && catalog.harness !== opts.harness) {
+    return `model-catalog: catalog at ${file} belongs to harness "${catalog.harness}", not "${opts.harness}" — one catalog per harness (model-catalog.md).`
+  }
+  return null
+}
+
+// model-catalog.md rule 7: the seed is read-only — `bank`/`sync` refuse it as a
+// write target. Checked two ways so a copy of the seed at a non-default path is
+// still caught: the resolved path matches the shipped seed location, OR the
+// file on disk carries the seed's own `seededAt` stamp (the same shape test
+// readSeed's caller would use to tell a seed from a per-harness catalog).
+function refuseIfSeedWrite(file, catalog) {
+  const isDefaultSeedPath = path.resolve(file) === path.resolve(defaultSeedPath())
+  const looksLikeSeed = !!(catalog && catalog.seededAt)
+  if (isDefaultSeedPath || looksLikeSeed) {
+    return `model-catalog: ${file} is the team seed — read-only (model-catalog.md rule 7). bank/sync never write to it; confirm into your own per-harness catalog instead.`
+  }
+  return null
+}
+
+export function runCli(argv) {
+  const [cmd, ...rest] = argv
+  const { positional, opts } = parseArgs(rest)
+  let file = opts.file
+  if (!file && opts.harness) {
+    file = pathForHarness(opts.harness)
+    if (!file) {
+      console.error(`model-catalog: no known catalog location for harness "${opts.harness}" (${Object.keys(HARNESS_PATHS).join('|')}) — pass --file with its user-config path.`)
+      return 2
+    }
+  }
+  if (!file) file = defaultPath()
+
+  switch (cmd) {
+    case 'path': {
+      console.log(file)
+      return 0
+    }
+    case 'read':
+    case 'list': { // alias: "list" is the verb agents guess first
+      const c = readCatalog(file)
+      if (c == null) {
+        console.error(`model-catalog: no catalog at ${file} (absent is normal — classify from discovery-source evidence).`)
+        return 3
+      }
+      console.log(JSON.stringify(c, null, 2))
+      return 0
+    }
+    case 'points': {
+      // Pre-flight builds its slot candidates from these — without a subcommand an
+      // agent has to hand-derive them from `read`, which is exactly the hand-rolling
+      // this script exists to prevent.
+      const c = readCatalog(file)
+      if (c == null) {
+        console.error(`model-catalog: no catalog at ${file} (absent is normal — no banked points to list).`)
+        return 3
+      }
+      const id = positional[0]
+      const out = id
+        ? { id, points: operatingPoints(c, id) }
+        : (c.models || []).map((m) => ({ id: m.id, family: m.family, points: operatingPoints(c, m.id) }))
+      console.log(JSON.stringify(out, null, 2))
+      return 0
+    }
+    case 'sync': {
+      const c = readCatalog(file)
+      if (c == null) {
+        console.error(`model-catalog: no catalog at ${file} (absent is normal — nothing to sync).`)
+        return 3
+      }
+      const seedRefusal = refuseIfSeedWrite(file, c)
+      if (seedRefusal) { console.error(seedRefusal); return 2 }
+      const mismatch = harnessMismatch(c, opts, file)
+      if (mismatch) { console.error(mismatch); return 2 }
+      const seenIds = (opts.seen || '').split(',').map((s) => s.trim()).filter(Boolean)
+      const { catalog, bumped, pruned, migrated } = syncCatalog(c, seenIds, todayIso(opts))
+      writeCatalog(file, catalog)
+      console.log(JSON.stringify({ bumped, pruned, migrated }, null, 2))
+      return 0
+    }
+    case 'bank': {
+      const raw = opts.stdin ? fs.readFileSync(0, 'utf8') : positional[0]
+      const entry = JSON.parse(raw)
+      const c = readCatalog(file) || { ...(opts.harness ? { harness: opts.harness } : {}), models: [] }
+      const seedRefusal = refuseIfSeedWrite(file, c)
+      if (seedRefusal) { console.error(seedRefusal); return 2 }
+      const mismatch = harnessMismatch(c, opts, file)
+      if (mismatch) { console.error(mismatch); return 2 }
+      if (!c.harness && opts.harness) c.harness = opts.harness // stamp a pre-field file at the next confirmed write
+      writeCatalog(file, bankEntry(c, entry, todayIso(opts)))
+      return 0
+    }
+    case 'seed': {
+      const seedFile = opts.seedFile || defaultSeedPath()
+      const seed = readSeed(seedFile)
+      if (seed == null) {
+        console.error(`model-catalog: no seed at ${seedFile} (absent is normal — a fresh checkout with no seed just gets no pre-fills).`)
+        return 3
+      }
+      console.log(JSON.stringify(seed, null, 2))
+      return 0
+    }
+    case 'seed-proposals': {
+      // Pre-flight builds its seed-backed pre-fills from these — restricted to
+      // --seen (rule 3: an id the seed knows but this run's discovery didn't
+      // yield never appears) and to models with no banked entry in THIS
+      // harness's own catalog (rule 7 precedence). Both filters live in
+      // seedProposals so neither depends on the caller remembering them.
+      const seedFile = opts.seedFile || defaultSeedPath()
+      const seed = readSeed(seedFile)
+      if (seed == null) {
+        console.error(`model-catalog: no seed at ${seedFile} (absent is normal — nothing to propose from).`)
+        return 3
+      }
+      const harness = opts.harness || 'claude-code'
+      const seenIds = (opts.seen || '').split(',').map((s) => s.trim()).filter(Boolean)
+      const { proposals, suppressed } = seedProposals(seed, harness, seenIds, readCatalog(file))
+      console.log(JSON.stringify({
+        proposals: proposals.map((p) => ({ ...p, citation: `tier from team seed: ${p.id}` })),
+        suppressed: suppressed.map((s) => ({
+          ...s,
+          citation: s.disagrees
+            ? (s.seedNewer
+                ? `team seed is NEWER than your banked ${s.id} and disagrees — seed says ${fmtTiers(s.seed)} (seededAt ${s.seededAt}), you banked ${fmtTiers(s.banked)} (confirmedAt ${s.bankedConfirmedAt}). The seed may carry a reclassification your entry predates — RE-CONFIRM rather than assume your catalog wins.`
+                : `team seed disagrees with your banked ${s.id} — seed says ${fmtTiers(s.seed)}, you banked ${fmtTiers(s.banked)}; your catalog wins (rule 7). Refresh the seed if yours is the better answer.`)
+            : `already banked: ${s.id} — seed adds nothing (rule 7)`,
+        })),
+      }, null, 2))
+      return 0
+    }
+    case 'tiers': {
+      // Pre-flight step 2's tiering in ONE call. The three arms exist as separate
+      // commands too, but running them separately means re-applying precedence by
+      // hand at the gate — and hand-applied precedence is the failure this whole
+      // 2026-07-20 audit traced. Prefer this command; reach for the individual
+      // ones only when you need to see a single source in isolation.
+      const harness = opts.harness || 'claude-code'
+      const seenIds = (opts.seen || '').split(',').map((s) => s.trim()).filter(Boolean)
+      console.log(JSON.stringify(tierProposals(harness, seenIds, { seedFile: opts.seedFile, today: todayIso(opts), catalogFile: file }), null, 2))
+      return 0
+    }
+    case 'cross-harness': {
+      // Rule 5 had no implementation at all until now — it was the only
+      // precedence rule left to the agent's prose comprehension mid-gate, and
+      // it OUTRANKS the team seed, so the stronger evidence source was the least
+      // enforced one. An agent that skipped the hand-step fell through to the
+      // seed, which is exactly how a stale seed tier reached a live run.
+      const harness = opts.harness || 'claude-code'
+      const seenIds = (opts.seen || '').split(',').map((s) => s.trim()).filter(Boolean)
+      console.log(JSON.stringify(crossHarnessProposals(harness, seenIds), null, 2))
+      return 0
+    }
+    case 'bank-from-seed': {
+      // Turns a confirmed seed-backed proposal into a banked entry. Hand-writing
+      // this JSON was the gap: `bank` accepts whatever confirmedAt it is handed,
+      // so "a seed entry is never treated as confirmedAt" (rule 7) depended on
+      // the agent not copying `seededAt` across. entryFromSeedConfirmation
+      // enforces it — resolving the alias, taking THIS harness's tiers, and
+      // stamping today — and until now nothing called it.
+      const id = positional[0]
+      if (!id) { console.error('model-catalog: bank-from-seed needs a model id (the id as THIS harness exposes it).'); return 2 }
+      const seed = readSeed(opts.seedFile || defaultSeedPath())
+      if (seed == null) { console.error('model-catalog: no seed to confirm from.'); return 3 }
+      const harness = opts.harness || 'claude-code'
+      let entry
+      try {
+        entry = entryFromSeedConfirmation(seed, harness, id, todayIso(opts))
+      } catch (e) { console.error(`model-catalog: ${e.message}`); return 2 }
+      const c = readCatalog(file) || { ...(opts.harness ? { harness: opts.harness } : {}), models: [] }
+      const seedRefusal = refuseIfSeedWrite(file, c)
+      if (seedRefusal) { console.error(seedRefusal); return 2 }
+      const mismatch = harnessMismatch(c, opts, file)
+      if (mismatch) { console.error(mismatch); return 2 }
+      if (!c.harness && opts.harness) c.harness = opts.harness
+      writeCatalog(file, bankEntry(c, entry, todayIso(opts)))
+      console.log(JSON.stringify(entry, null, 2))
+      return 0
+    }
+    case 'help':
+    case '--help':
+      console.log('model-catalog: read (alias: list) | path | points [<id>] | tiers --seen <id,id,...> | sync --seen <id,id,...> | bank <entryJson> | bank-from-seed <id> | cross-harness --seen <id,id,...> | seed | seed-proposals --seen <id,id,...> — options --harness <claude-code|codex|pi>, --file <path>, --seed-file <path>, --today <YYYY-MM-DD>, --stdin (see header).')
+      return 0
+    default:
+      console.error('model-catalog: unknown command. Use read|path|points|sync|bank|seed|seed-proposals (see header).')
+      return 2
+  }
+}
+
+// Only run the CLI when invoked directly (so tests can import the pure functions).