fix(models): Claude Fable 5.1 is selectable, and the alias help names the current generation (#2726)

[trinity-ability]

Anthropic shipped claude-fable-5-1 and Trinity's catalog never moved, so the model was unselectable everywhere the catalog feeds — absent from the operator picker and the admin fleet-default dropdown, and 422'd by the server-validated public-channel override. This is not drift (#2086 made drift impossible by deriving every list from one source); it is source-vs-reality staleness, the one control #2086 deliberately left human. The fix is one ModelEntry at index 1 plus one codegen run — no consumer was edited — with the (latest) marker moved off claude-fable-5, the agent-server alias help text restated so opus stops being documented as Opus 4.8, the fable alias accepted by the same router that advertises it, a one-line ops-dashboard label mapping, and four docs/user-docs/ sentences that were telling customers Fable 5 is the most capable model.

Fixes #2726

What changed

• src/backend/services/model_catalog.py — one ModelEntry for claude-fable-5-1 / Claude Fable 5.1 / note Most capable — longest tasks (latest) at index 1, with its three booleans passed positionally (True, True, False) per the dataclass's own ⚠️, and the em-dash written as the \u2014 escape its neighbours use. claude-fable-5 keeps its id, its slot and both policy flags, and loses only the (latest) marker — no Legacy relabel, no reposition. Adds a Last synced: 2026-09-12 bump anchor (the model_context.py:40-44 idiom) so catalog staleness becomes provable by inspection.
• src/frontend/src/constants/modelCatalog.js — regenerated via python3 scripts/gen_model_catalog.py. Never hand-edited; re-running the script on the pushed tree leaves git status empty.
• docker/base-image/agent_server/routers/chat.py — GET /api/model's help text now states the durable rule before the perishable list: "each resolves to the current generation of its family — today sonnet (Sonnet 5), opus (Opus 5), haiku (Haiku 4.5), fable (Fable 5.1)". PUT /api/model accepts fable / fable[1m], and its 400 detail names the same four aliases the GET advertises.
• src/backend/routers/ops.py — one "claude-fable-5-1": "Claude Fable 5.1" mapping entry. The prettifier's re.sub(r'-\d{8}$','') strips only an 8-digit suffix, so the point-release id kept its -1 and fell through to the title-case fallback as the literal "Claude Fable 5 1".
• Tests — tests/unit/test_2086_model_catalog_parity.py 12→14 tests; new tests/unit/test_2726_ops_model_label.py (9 tests); tests/test_agent_chat.py exercises the fable alias.
• Docs — feature-flows/model-selection.md (both preset tables, the alias sentence, the 400-detail row, changelog), feature-flows.md index row, one unconditional correction in workspace-model-choice.md, and four docs/user-docs/ files.

No consumer was edited — ModelSelector.vue, Settings.vue, settings_service.py, client_portal/service.py and the MCP tools all derive from the catalog. Editing one would be the #2086 regression.

Acceptance criteria

• AC 1 — claude-fable-5-1 selectable end-to-end: operator picker (PRESET_MODELS projects MODEL_CATALOG), admin fleet-default dropdown (adminDefaultSelectable filter), public-channel override (is_valid_public_channel_model("claude-fable-5-1") is now true, so PUT /api/agents/{name}/public-channel-model answers 200 instead of 422 — pinned by test_fable_5_1_is_present_and_selectable_end_to_end).

  AC 1 lists four broken surfaces; three are ticked. The Workspace composer is deliberately NOT included. ent#403 excluded the whole Fable tier from that client-facing surface days before this issue was filed, on a written rationale recorded in docs/memory/feature-flows/workspace-model-choice.md, requirements/core-agent.md AC-1 and requirements/public-access.md §47.2 FR-2 — Opus-vs-Fable is an operator distinction, not a client one. That omission was never catalog staleness (workspace=False is set on purpose), so a refresh would never have changed it; reversing it is a product decision — a type-feature for the private tracker, not this P1 bug. The issue owner chose to keep the Workspace excluded. Both workspace kwargs are omitted, the entry is flag-identical to claude-fable-5, and WORKSPACE_MODELS is unchanged.

• AC 2 — Fable 5.1 carries (latest); Fable 5 no longer does. Pinned by test_at_most_one_latest_marker_per_family_and_fable_is_5_1, which asserts the rule (at most one (latest) per family, any family) plus the two AC-specific ids.

• AC 3 — the alias help text names the generation each alias resolves to; proven against the built image (below), not just the source.

• AC 4 — the id is the exact undated claude-fable-5-1. The dated legacy ids are deliberately left alone (see Notes).

• AC 5 — generated mirror in sync: test_generated_js_is_byte_fresh passes, and re-running the codegen on the pushed tree produces no diff.

• AC 6 — docs/memory/feature-flows/model-selection.md preset tables + changelog updated, plus the index row.

• AC 7 — no default changes. PLATFORM_DEFAULT_MODEL_VALUE and the recommended marker are untouched; the new entry is recommended=False, asserted both at import time and by test_recommended_is_exactly_one_and_is_the_platform_default.

Folded-in adjacent fix

PUT /api/model rejected fable with a 400 while GET /api/model on the same router advertised it in available_models — a pre-existing advertise-vs-accept asymmetry outside every AC. It is folded in here rather than deferred: same file, same handler pair, riding the same base-image rebuild; AC 3 makes the contradiction worse by naming a generation for an alias the sibling endpoint 400s; and accepting it restores an advertised contract rather than granting a new capability. It is still a behaviour change outside the ACs — a maintainer may reasonably ask for it as a separate PR, in which case dropping the valid_aliases and 400-detail hunks from chat.py leaves the rest of this PR intact.

Deployment note

The agent-server changes (the alias help text and fable acceptance) reach an agent only after ./scripts/deploy/build-base-image.sh and a container recreate. Existing agents keep serving the old note and keep 400ing fable until then. Zero functional impact in the meantime — model selection itself is unaffected, and nothing else in this PR depends on the image. The backend and frontend halves ship with the normal image build: the public-channel PUT accepts the new id the moment the backend restarts. No migration, no data backfill, no restart ordering; a stored public_channel_model of claude-fable-5 is unaffected because that id does not move and keeps both flags.

Verification

/verify-local --skip-agent on this tree — status pass: unit 15,349 passed / 31 skipped / 0 failed; build + import-smoke OK; boot + health OK; integration 70 passed / 13 skipped / 2 registry-deselected / 0 failed (isolated project trinity-verify-d410c1b4).

Base-image proof. The agent-server change can only be proven in the image, and the global-mode agent stage refuses while the operator's dev stack is live, so it was proven directly. Built trinity-agent-base:issue-2726-verify from this HEAD with --build-arg VERSION="$(cat VERSION)" (14 s, cache hit — the arg is load-bearing: Dockerfile:8 feeds ENV TRINITY_BASE_VERSION at line 18, above apt/Go/Node/Claude Code, so omitting it invalidates every layer below). trinity-agent-base:latest id was captured before and after and is unchanged; the throwaway image was removed; no container joined trinity-agent-network and agent-trinity-system was never touched.

A defect in the plan's own recipe, stated honestly. As first written, the §7 check ran docker run --rm --network none "$TAG" python - <<'PYCHK' — without -i. docker run does not forward stdin without it, so the heredoc program was never read: python got an empty program and exited 0 on any image. Measured: the verbatim form produced no output at all. The evidence below is from the corrected form, and the negative control proves it bites.

docker run --rm -i --network none "$TAG" python - <<'PYCHK'
# (a) the alias-help literal, (b) the valid_aliases list, (c) the 400 detail —
# extracted from the file's AST inside the container, hard-asserted, no `||`.
PYCHK

Three extracted literals, verbatim from the run:

• (a) Claude model aliases (Anthropic API): each resolves to the current generation of its family — today sonnet (Sonnet 5), opus (Opus 5), haiku (Haiku 4.5), fable (Fable 5.1). Add [1m] suffix for the 1M extended-context beta (e.g. sonnet[1m]). — and no Opus 4.8.
• (b) ['sonnet', 'opus', 'haiku', 'fable', 'sonnet[1m]', 'opus[1m]', 'haiku[1m]', 'fable[1m]']
• (c) the 400 detail lists (sonnet, opus, haiku, fable).

id -u inside the image = 1000 (Invariant #17).

Negative controls — the proof is non-vacuous. The same script against origin/dev's chat.py exits 1 at arm (a). Two host mutants exit 1 at arms (b) and (c) respectively (new note + old valid_aliases; new valid_aliases + old 400 detail). All three arms bite independently — without (b) and (c) the folded-in fable fix would have ridden on a grep that matches the old file too.

Unit-level, re-run after rebase:

Command	Result
test_2086_model_catalog_parity.py + test_ent243_prompt_tier.py	52 passed (was 49)
test_ent403_workspace_model.py + test_894_public_channel_model.py	56 passed (unchanged — the Workspace is untouched)
test_2726_ops_model_label.py (new)	9 passed
npx vitest run tests/unit/portalModelChoice.spec.js	54 passed
full frontend npm run test:unit	125 files / 2,732 passed
python3 scripts/gen_model_catalog.py && git status --porcelain	empty — mirror byte-fresh

Meta-tests — each new guard was watched to fail before being trusted. The parity guard is derived (both halves come from the catalog), so it ratifies whatever the catalog says; a green first run is not evidence. Planting each violation turned the matching guard red: flipping the new entry's public_channel to False; restoring (latest) on Fable 5; dropping the id from the flag groups (the coverage assertion); and removing the ops mapping (3 failed).

Notes

• Deviation from the dossier's D4. Fable 5 keeps its slot and its id — no Legacy (prior Fable) relabel and no reposition; only the marker drops. AC 2 asks that Fable 5 stop being labelled the latest, and dropping the marker is exactly that; Legacy would imply a deprecation Trinity has no policy behind (the reference says Fable 5 is still served) and would cost a visible picker reorder for a claim no AC makes.
• The ops dashboard now reads "Claude Fable 5.1", but the JS twin stores/observability.js:281-291 deliberately still returns raw ids for the Fable family: it has no fable branch at all, and adding one would be a second, hand-synced copy of the same mapping — the exact shape refactor: centralize the selectable model catalog — one source of truth for three hand-synced lists #2086 exists to prevent. The Python mapping is the one the cost/token dashboards read.
• Two cosmetics accepted, not fixed. (1) Typing the exact string claude-fable-5 in the operator picker now matches both rows (ModelSelector.vue:120 uses .includes), new one first — harmless, there is no auto-select (:163 guards highlightedIndex >= 0). (2) Settings.vue:360 renders {{ m.label }} — {{ m.note }}, so the new row shows a nested em-dash — identical in shape to what Fable 5 renders today, so not a regression; re-wording an operator string no AC touches would be scope creep.
• The dated legacy ids (claude-haiku-4-5-20251001, claude-opus-4-5-20251101, claude-sonnet-4-5-20250929) were deliberately not renormalised to the reference's undated form — doing so would invalidate every stored agent setting pinned to them, for zero AC gain. Considered, not overlooked.
• Owed .claude/agents/test-runner.md catalog rows — the submodule is read-only in this run, so the two rows are listed here instead: tests/unit/test_2086_model_catalog_parity.py 12→14 tests, and a new entry for tests/unit/test_2726_ops_model_label.py (9 tests).

Follow-ups (not filed — for the maintainer)

1. MCP .describe() examples still cite claude-opus-4-8 — chat.ts:438,655, schedules.ts:176, loops.ts:166. Free text, no enum, nothing breaks; Update and actualize the available LLM model list across the app (add Opus 4.8, retire EOL models) #1080 refreshed these, refactor: centralize the selectable model catalog — one source of truth for three hand-synced lists #2086 then redefined the refresh contract as "one file, one script".
2. Dated legacy ids vs the reference's undated ids — deliberately not renormalised here (stored settings), but worth a decision.
3. The stale-prose class — this is its third instance (Update and actualize the available LLM model list across the app (add Opus 4.8, retire EOL models) #1080, bug: Fable 5 / Sonnet 5 missing from platform default-model dropdown and PUBLIC_CHANNEL_MODELS whitelist (drifted from ModelSelector presets) #1660, bug: selectable model catalog is stale — Claude Fable 5.1 (claude-fable-5-1) not selectable anywhere; tier labels + alias help text behind the current lineup #2726). refactor: centralize the selectable model catalog — one source of truth for three hand-synced lists #2086's contract is "one file, one script", but prose that enumerates or counts the catalog sits outside it: two tables in model-selection.md, a table and an entry count in workspace-model-choice.md, tier strings in requirements/public-access.md FR-2, counts in requirements/core-agent.md and runtimes.md, and four docs/user-docs/ files. Every refresh must hand-chase all of them, and it has already failed once (item 5). Wants a catalog canary diffing MODEL_CATALOG against the published lineup, or — far cheaper — a scheduled monthly "re-verify the catalog" issue. The Last synced: anchor added here makes staleness provable; it does not prevent it.
4. model_catalog.py's "That is the whole maintenance surface — one file, one script" is true of the catalog and false of a model refresh — this PR is 14 files. Worth amending so the next person's estimate is right.
5. docs/memory/requirements/runtimes.md:314 says "7 of 9 PRESET_MODELS entries" — already stale before this PR (10 since refactor: centralize the selectable model catalog — one source of truth for three hand-synced lists #2086), 11 now. Out of this PR's blast radius.
6. docker/base-image/agent_server/services/headless_executor.py:1616 carries a three-alias docstring that omits fable.
7. The backend PUT proxy collapses the agent-server 400 into a generic 503 (routers/chat.py:677-686), so an operator who sends an invalid model gets "Failed to set model" rather than the 400 detail this PR just improved.
8. An offline AST guard for the agent-server help text — it has no parity-tested twin (it is not an Invariant Setup improvements #5 vendored mirror), so today only a built image can catch it drifting.

🤖 Generated with Claude Code

https://claude.ai/code/session_017YoUiMQgPj3BeFMpyYpfkB

[vybe]

merge-train: batch validated on train/20260913-0705 (#2745) — lane C, /validate-pr + /review + /cso --diff clean; catalog parity 23/23; the chat.py alias fold-in is accepted as-is. Post-merge: base image rebuild + agent recreate for the alias to land.