17 KiB
17 KiB
PLAN — router-downgrade-cap (feat, r3: r2 + confirmation pass FATAL(7) → 1 BLOCKER + 6 MAJOR closed by the named changes below)
Contract: .claude/tasks/contracts/2026-10-13-router-downgrade-cap-0013.md
Files
- mods/model-router/hooks/register.ts
- mods/model-router/hooks/register.test.ts
- lib/effort-shift.md
Core change of r2 — the cap bounds the COLD READ, not the context size
LRN-204: a switch INTO a model costs the tokens that model's prompt cache does not
hold; within the 1 h TTL its cache holds the prefix up to its last main step. So the
cost of moving main to model M at a context of T tokens is
coldRead(M) = T − servedTokens(M) when M served main within the TTL, else T.
r1 compared T itself to the cap, which (correctness #1) refused the cheap re-down to a
warm Sonnet and forced a cold read on Fable instead. r2 compares coldRead.
Approach
- Config (
register.tsConfig type ~l.30-37, DEFAULT_CONFIG ~l.217-275, mergeRouting ~l.512-537):downgradeMaxTokens: numbernext toupgradeMaxTokensinConfig,RoutingandmergeRouting(pickPositive(user.downgradeMaxTokens, base.downgradeMaxTokens, 'downgradeMaxTokens', log)); default120000, comment "max cold read a downgrade may cost (LRN-204)".upgradeMaxTokenscomment becomes "max cold read an upgrade may cost".mainModelSwitch: true, merged FAIL-CLOSED likepickEnabled(~l.505-510): a non-boolean override logsmodel-router: config "mainModelSwitch" is not a boolean; switch offand reads asfalse[r3 #5:pickSwitchfalls back to the seeded default, which is nowtrue]. - Served record (State ~l.80-100,
mainPlan~l.3052) [r3, BLOCKER #1 / #6 / #12]:served: Map<string, { at: number; tokens: number }>keyed by the canonical id main was sent (plan.model).mainPlanreadstokens(readTokens) andnow($.clock.now()) on EVERY main step, routed or not, and recordsserved.set(canonical(plan.model), { at: now, tokens })after the decision, whatever the routing — an unrouted step on the session model is exactly the one that keeps that model warm. Texts (snapshot,toastChange) keep the lazy read.servedis NOT inresetSession's kept list (/clearstarts cold) and is cleared by/route reloadnext to the breaker marks (~l.1099-1108). ConstCACHE_TTL_MS = 60 * 60000next toCLASSIFY_*, comment: "the account's prompt-cache TTL (1 h here; an engine-reportedcache_ttlwould supersede it — TODO)".decideFor($, st, cur, tokens?, now?)takes the values when the caller has them and reads them itself otherwise; it returns{ call, wanted }as today.capSaidis set/cleared inmainPlanfrom the returned call (a text run never mutates it). Compaction / history rewrite [#6]: incoldRead, whentokens < entry.tokensthe entry is stale → drop it and returntokens(cold). - One cap helper replaces
capBlock(~l.1143-1147):coldBlock(st, id, tokens, max, now)→undefinedwhentokens !== undefined && coldRead ≤ max; else the reason'context size unknown'or`cold read ${cold} tokens over ${max}`.coldRead(st, id, tokens, now)=tokens − entry.tokenswhenserved.get(canonical id)exists andnow − entry.at ≤ CACHE_TTL_MS(floored at 0), elsetokens.decideForreceivestokens/nowfrommainPlan(texts read them lazily, as today). upgradeCall(~l.1177-1192):coldBlock(…, st.cfg.upgradeMaxTokens)in place ofcapBlock; samekeep(cur, why, 'model-router: upgrade skipped: …'),logKey 'upgrade-skipped'.leaveDown(~l.1160-1175) uses the same helper forupOk. NO return bypass (simplicity #1, correctness #1/#5, robustness #4-#6): a return to a warm model has a small cold read and passes by itself; turn end restorese.model.downgradeCall(~l.1196-1205):switch offrefusal first (text unchanged), thencoldBlock(…, st.cfg.downgradeMaxTokens)→skipped(cur, 'downgrade', block)withlogKey 'downgrade-skipped', thenfits, thenmoveTo. One sharedskipped(cur, kind, block)builds both skip calls (upgrade too).- Log spam (robustness #8):
downgrade-skippedis said once per session until a downgrade next succeeds:st.capSaid: boolean, set inmainPlanwhen the returned call is a downgrade skip (log suppressed while set), cleared inmainPlanwhen the returned call iswhy === 'downgrade'; the per-turnturnLoggeddedupe stays for the upgrade. [1m]carry (robustness #6):moveTokeeps[1m]fromcur; after a haiku hopcurhas none. ChangemoveTo(cur, target, why, session)to carry[1m]when EITHERcurorst.sessionModelhas it (and the target is not haiku); all callers passst.sessionModel.- Window re-check (robustness #2) [r3 #10]: in
decideMain, after theunknownCallcheck: whenst.turnModel !== undefined,tokens !== undefined,!fits(st, id, tokens), and the session model is a known ranked id, not down and not haiku →moveTo (cur, canonical(st.sessionModel), 'window', st.sessionModel)with a once-logmodel-router: context outgrew <id>: back to <session model>; any guard failing → fall through to the normal decision. Onlywindowsentries (haiku) can trigger it. - Classifier model axis, DOWNGRADES ONLY under the switch (correctness #2, simplicity
#3, robustness #3) [r3 #3 / #4 / #9]:
routeFromLabel(~l.3531-3541) writesroute: { ...phaseRoute(st.cfg, phase) }(tier + effort).mainModelbecomesmainModelSlot(st): Routed | null= the FIRST slot (userMain, turnMain, runMain, turnFloor) whose route carries a model name;decideForresolves the name from it. Two rules on that slot whenslot.source === 'classifier': (i) a floor with a model name wins over it (turnFloorroute name used instead:ultrathinkmid-turn still reaches fable/max); (ii) the resolvedwantedis dropped (undefined) when itranksAbovethe SESSION model (canonical(st.sessionModel)), never compared tocur— so a guess never moves main above the user's baseline, while a breaker fallback from a guessed sonnet to opus (below fable) still works and never falls to haiku. Texts and step agree (both go throughdecideFor). Existing test l.4568 (sonnet session, design guess → sonnet) holds; rename it…never moves UP. - Classifier vs a user
/effort(simplicity #2, correctness #6/#7, robustness #9) [r3 #7]:engineBasebecomes per turn:noteEngineBaserecords the engine effort of THIS turn's first main step, compared against the previous turn's value (st.engineBaseholds the last turn's,st.turnEnginethis turn's; at turn endengineBase = turnEngine).userMovedEffort= this turn's engine effort differs from the previous turn's: a/efforttyped between turns. InmainPlan, beforemainEffort:if (userMovedEffort(st, e)) st.turnMain = nullwhenturnMain.source === 'classifier'— the guess is dropped on both axes for THIS turn only;turnModelis NOT touched (no return without a cold-read check; turn end restorese.model). TheskipTurnparameter ofmainEffort(~l.1302) goes away. The next classified turn routes again from the new baseline effort. - User
/model(correctness #3, robustness #3): NO suspension. A user/modelsets the new baseline (sessionModel) and the classifier keeps routing from it;/route classify offor/route offpins the model. The r1 disposition claim is struck; the trade-off goes into the BDR amendment and the doctrine line. - Helper skills inside a run (robustness #1):
routeMainBySkill(st, skill, row, typed): when!typed && st.runMain !== nulland the row's tier ranks below the run's (rank throughresolveRoute→modelRank, so a phase naming a model is ranked too [r3 #15]), writeroute: { effort: row.route.effort }only — a model-loaded helper (e.g.using-git-worktreesinside/feat) moves effort, never the orchestrator's model. Typed skills and best-tier rows unchanged. Test l.1130 keepsskill mechanicalin the status and gainsexpect((await stepOn(…)).model).toBe(FABLE). - Toast hint (correctness #6) [r3 #11]:
skipped(cur, kind, block)setscall.why =${kind} skipped: ${block}`` (the bare block text is never thewhy) andcall.log = 'model-router: ' + why;downgradeHeldmatcheswhy === 'switch off'ORwhy.startsWith('downgrade skipped'); hint: switch → unchanged text; cap →, held: <why>. Test (m) covers the cap hint. - Texts (
show~l.1463,statusLine~l.1475):switch: on (downgrade, cap 120000 tokens cold)/switch: off (downgrade); status line [gated 2026-10-13]:· switch offonly when off, the· switch onfragment is dropped. - In-file comments (correctness #9): rewrite l.3438-3441 ("never a model move"), l.3535 and l.3546 to the new rule (effort + a downward tier under the switch and the cold-read cap).
- Doctrine (
lib/effort-shift.mdLimits bullet): "A plain typed prompt with no route in force is classified by a small model: the guessed phase sets the turn's effort and, undermainModelSwitchanddowngradeMaxTokens(max cold read, default 120000), may move main DOWN, never up; a user/modelonly moves the baseline the guess starts from (/route classify offto stop guessing; never-p)."
Edge cases
- Context size unknown: both caps block, logged once (upgrade per turn, downgrade per cap crossing); the window re-check does not fire on an unknown size.
- Compaction (
tokensbelow a served entry): that entry is stale, the move is cold. - TTL (60 min const) is an assumption of this account's cache; residual in TODO.
- Target down (breaker):
resolveNameyields the first available alias; a guessed route ranks against the session model, so its fallback stays between sonnet and fable. - Main already down, context grows past the downgrade cap mid-turn:
wantedunchanged → keep; a best route later moves up (cold read of Fable = delta since its last step, usually under 200k); no re-down unless Sonnet's cold read fits — which it does while Sonnet is warm. Turn end resetsturnModel; next turn starts one.model. - Haiku on main and the context passes 200k: window re-check returns main to the session model.
/route switch off: identical to today (refusal textswitch off).- Classifier
chat/unknown: nothing written. - Non-best session (
/model opus): coding guess → sonnet (downgrade); design guess → stays opus (never up by a guess); prompt RULES still upgrade as today. - Unrowed sub-agent with no explicit model spawned during a demoted turn may inherit
the demoted
parentModel(robustness #10): accepted residual, all repo agents are rowed and built-ins carrymodel=; logged in TODO. session.usage().context.tokensmay lag the new prompt (robustness #11): accepted, the cap is an economic guard, not a hard limit; logged in TODO.
Tests (register.test.ts) — contract letters
- Rig: add
usageVar(on, initial)returning{ set(n) }over ONE bottomsession.usagehook with a mutable count (never a secondon('session.usage'));bootRiggains an optionalusagehandle or a siblingbootRigVar. - Re-expressed (default flip), never weakened: l.305-315 (
/route model: alias resolved…→switch offfirst), l.605-614 and l.1665-1672 (toggle survival →switch off/switch: off), l.747 (switch offfirst), l.754 (drop theswitch online: default proves it), l.951-958 (show reflects /model opus→switch offfirst), l.2934-2943 (toast:switch offfirst, hint text unchanged), l.4576 (route carries no tier→carries the tier), l.4783-4799 (classify guard: a route landing during the call wins→switch offfirst [r3 #8]), every status-line assertion on· switch on(grep) → asserts the fragment is ABSENT by default and present as· switch offafterswitch off.bootClsgains atokensoption (ClsOpts) for (f) [r3 #13]. - (a)
cap: a downgrade under the cold-read cap moves main(fable, 1000 tokens, route mechanical → haiku, noswitch on). - (b)
cap: a downgrade above the cold-read cap keeps main(fable, 300000, route mechanical →{ model: FABLE, effort: 'low' }, log containsdowngrade skipped: cold read 300000 tokens over 120000); second step same turn: no second log line. - (c)
cap: unknown usage blocks the downgrade(tokens null). - (d)
cap: a warm model is cheap to return to, a cold one is capped[r3 #2] — rig withusageVarat 100000: route implement, step → SONNET (served sonnet@100000);endTurn; step on FABLE unrouted → FABLE (served fable@100000, the unrouted write);endTurn;set(210000); route implement, step → SONNET (moved from FABLE: cold read 110000 ≤ 120000 although the context is 210000);endTurn; CONTROL: route judge (opus, never served, ranks below fable), step → FABLE kept, log containsdowngrade skipped: cold read 210000 tokens over 120000. - (e)
classify: coding moves main to sonnet medium under the cap(fable, 1000). - (f)
classify: coding above the cap keeps fable at medium(fable, 300000). - (g)
downgrade: switch off keeps today's behavior(= l.747 re-expressed). - (h)
classify: a user /effort drops the model guess too(step effort ≠ engine base → FABLE at the step's effort,/route showagrees:session defaults). - (i)
classify: a design guess never moves a sonnet session up(= l.4568 renamed). - (j)
run slot: a model-loaded helper skill moves effort only(= l.1130 extended). - (k)
window: haiku outgrown returns main to the session model(route mechanical on fable at 1000 → haiku;set(250000); next step → FABLE, log once). - (l)
config: a quoted "false" mainModelSwitch reads as off with a warning(/route showcontainsswitch: off) [r3 #5]. - (m)
toast: a downgrade held by the cap says so(, held: downgrade skipped: cold read …) [r3 #11]. - (n)
cap: the served record expires after the TTL(clock advanced 61 min: cold = whole context, downgrade above cap refused) [r3 #13]. - (o)
cap: /route reload forgets the served record;cap: the skip line is said once until a downgrade succeeds(two turns above cap → one line; a downgrade under cap on a later turn; above cap again → one new line) [r3 #13]. - (p)
cap: a smaller context than the record is cold(set(50000) after served@100000 → downgrade to a never-served model refused only if 50000 > cap; use cap overridedowngradeMaxTokens: 40000inhome→ refused, entry dropped) [r3 #6]. - (q)
classify: a mid-turn ultrathink floor still reaches fable max(classifier coding → sonnet; mid-turn promptultrathink→ next step FABLE/max) [r3 #4]. - (r)
classify: a guessed sonnet rate-limited falls to opus, never haiku(coding → sonnet;failWith('rate_limit')→ next step OPUS) [r3 #3]. - (s)
classify: a user /effort drops the guess for one turn only(turn 1 engine effort high = base; turn 2 engine effort low (user /effort) → guess dropped, FABLE; turn 3 engine effort low → coding guess routes again → SONNET) [r3 #7]. - Run:
make test suite=lib/tests/mods.test.sh.
Disposition (STEP 0.6)
- honors BDR-115 (one writer per axis, full ids): cap and served record live in
decideMain's path, the only writer of main's model; full ids only. - honors LRN-204 (cold read per switch INTO a model, warm return): the cap measures exactly that quantity; no bypass needed.
- supersedes one clause of BDR-116 amendment W4-B ("EFFORT ONLY: main model never
moves on a guess") by user decision 2026-10-13, DOWN only, under the switch and the
cold-read cap; the
/effortguard stays (route dropped on both axes); the/modelguard is NOT kept (baseline moves, guess follows) — stated trade-off for the BDR. - honors BDR-107 effort rungs: no effort value changes.
CHALLENGE SUMMARY (r1 → r2 → r3)
- correctness #1 / simplicity #1 / robustness #4-#6 → cold-read cap + served record,
bypass dropped. correctness #2 / simplicity #3 / robustness #3 → downgrades only.
correctness #3 → claim struck, trade-off surfaced. correctness #4 / simplicity #6 →
full test list, letters aligned. simplicity #2 / correctness #6-#7 / robustness #9 →
drop the guessed route on both axes in
mainPlan. simplicity #4 → onecoldBlock. simplicity #5 → moot. robustness #1 → helper-skill effort-only inside a run. robustness #2 → window re-check. robustness #7 → pickSwitch. robustness #8 → once per cap crossing. robustness #10/#11 → accepted residuals (TODO). correctness #9 → comments + USAGE.md/README to STEP 6. - Confirmation pass (r2, FATAL(7)): BLOCKER #1 → served written on EVERY main step
(tokens + clock read per step). #2 → test (d) with
endTurnbetween legs. #3 → guess ranked against the session model. #4 → floor model wins over a guess. #5 → fail-closed switch picker. #6 → stale entry = cold,servednot kept across /clear. #7 → per-turnengineBase, noturnModelreset. #8/#13 → tests added. #9 → slot-sourced predicate. #10 → window re-check guards. #11 →whypinned throughskipped(). #12 →capSaidinmainPlan. #14 → TTL const + TODO. #15 → rank viaresolveRoute. - Deferred BLOCKERs: none. Re-challenge budget consumed (1 extra pass); verifier and security gates follow.