claude-usage-limits 1.8.0 → 1.9.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "author": {
     "name": "Ridelink",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usage-limits",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Reports how much of your Codex usage limit is left as turns of work rather than a percentage, prices a job before you start it, and counts the other agents sharing the same budget.",
   "author": {
     "name": "Ridelink",

package/README.md

@@ -430,6 +430,44 @@ times one that answers from context. The upper end is the honest one for a long
 run, since turns get dearer as the context grows.
 
 
+## Which effort and model should this run at
+
+```
+node skills/usage-limits/scripts/usage.js --recommend        # against the headroom
+node skills/usage-limits/scripts/usage.js --recommend 15     # against a 15 turn job
+```
+
+```
+Recommendation for 15 turns
+
+  Posture   tight - a 15 turn job fits, but only just (5-hour window, 12% left, resets in 1h 40m)
+  Effort    xhigh -> medium; one notch covers the mechanical stretches; keep judgement calls at full effort
+            this session: /effort medium   (only the user can run it)
+            new sessions: node scripts/lowpower.js on --effort medium
+  Model     keep opus for the judgement; the saving is in where the mechanical bulk runs
+            dispatch self-contained mechanical work to a subagent on sonnet at low effort, and keep the judgement here
+```
+
+It weighs the binding window, the measured cost of a turn, and how much of the
+output is actually reasoning, then names a posture - roomy, tight, critical, or
+reset-first - and the exact commands. When there is room it says to keep
+everything as it is, out loud, because turning effort down when the budget is
+not tight buys nothing and costs quality. When reasoning is only a sliver of
+the output it says so too, and leaves effort alone: the reasoning share is the
+ceiling on what lowering effort can save. `--json` returns the decision as an
+object.
+
+The three levers it recommends across belong to different hands. The running
+session's effort and model are the user's alone (`/effort`, `/model`, applied
+immediately); new sessions belong to `lowpower.js`, which writes `settings.json`
+for the next launch; and delegated work belongs to the agent itself, which can
+dispatch a subagent on any model at any effort, mid-session, with no one asked.
+No script or hook can change the model or effort of a session already running -
+`settings.json` is read at launch and hook output has no model field - which is
+why the recommendation separates "this session" from "new sessions" instead of
+pretending one command covers both.
+
+
 ## Plans
 
 It reads which plan you are on and adjusts what it tells you, because the
@@ -545,6 +583,10 @@ overwrite the saved originals.
 The file change applies to new sessions. For a session already running,
 `/effort low` does the same thing immediately.
 
+`--effort max` is refused: `settings.json` does not accept `max`, so saving it
+would store a value the next session silently ignores. `max` lives in
+`/effort` and `CLAUDE_CODE_EFFORT_LEVEL` only.
+
 That covers the setting. The larger saving is behavioural, and the skill file
 spells it out: batch tool calls, read line ranges instead of whole files, skip
 subagents when the context already exists, stop retrying a fix that is not

package/bin/cli.js

@@ -11,6 +11,7 @@ const HELP = `claude-usage-limits - how much agent usage is left, and whether th
   claude-usage-limits --json              the same numbers, machine readable
   claude-usage-limits --status            one short line, for a status line
   claude-usage-limits --forecast 15       what a 15 turn job would cost
+  claude-usage-limits --recommend [15]    which effort and model this budget calls for
   claude-usage-limits --sessions          what recent sessions cost
   claude-usage-limits --session last      one session in full, or give its id
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "keywords": [
     "claude",

package/skills/usage-limits/SKILL.md

@@ -272,6 +272,45 @@ to `low` is the largest per-turn saving available without changing model or
 scope. The file change applies to new sessions; for the session already
 running, `/effort low` takes effect immediately.
 
+### Choosing the level
+
+Do not guess which effort or model the budget calls for; the report can say:
+
+```
+node scripts/usage.js --recommend        # against the headroom in general
+node scripts/usage.js --recommend 15     # against a 15 turn job
+```
+
+It weighs the binding window, the measured cost of a turn, and how much of
+the output is actually reasoning, then names the posture (roomy, tight,
+critical, or reset-first) and the exact commands. When there is room it says
+to keep everything as it is, out loud, so cheapness never becomes a habit.
+Add `--json` for the decision as fields.
+
+The three levers it recommends across belong to different hands, and keeping
+that straight is the whole trick:
+
+| Lever | Whose hand | When it acts |
+| --- | --- | --- |
+| `/effort`, `/model` | the user's only | this session, immediately |
+| `lowpower.js on` (writes settings.json) | yours, right now | new sessions, at launch |
+| subagent model and effort | yours, freely | that dispatch, immediately |
+
+The running session's own model and effort cannot be changed by any script or
+hook: settings.json is read at launch and hook output has no model field. So
+when the recommendation says `/effort low`, put that in front of the user as
+one short line and keep working; do not wait on it. What can be done without
+asking anyone is the other two rows: write the next session's settings with
+`lowpower.js`, and send self-contained mechanical bulk to a subagent on a
+cheaper model at low effort, which is a change of model that needs nobody's
+permission. The cold start still costs (see `references/tactics.md` on
+subagents), so delegate work that is big and mechanical, not quick questions.
+
+One catch to know about: `settings.json` does not accept `max`, so a saved
+effort level tops out at `xhigh`. `max` only survives through `/effort` or the
+`CLAUDE_CODE_EFFORT_LEVEL` environment variable, and `lowpower.js` refuses to
+write it rather than save a value the next session would silently ignore.
+
 Do not take that on trust: the report measures it. Under the model table it
 says how much of the output was reasoning and what that cost, for example
 
@@ -394,5 +433,6 @@ a turn, which is the thing it is trying to save.
 | `scripts/codex.js` | The Codex reader: the meter and the pace out of `~/.codex/sessions`, plus the live `--refresh` call. |
 | `scripts/install-codex-hook.js` | `status`, `on`, `off`. Installs the Codex-side instruction, which Claude Code does not need. |
 | `scripts/lowpower.js` | `status`, `on`, `off`. Restores what it replaced. Claude Code only. |
+| `scripts/recommend.js` | The chooser behind `usage.js --recommend`: posture, then the effort and model commands for each lever. Not meant to be called by hand. |
 | `references/tactics.md` | Every lever that lowers cost, and why it works. |
 | `references/how-it-works.md` | Where the numbers come from and where they are soft. |

package/skills/usage-limits/references/how-it-works.md

@@ -130,7 +130,17 @@ calculation.
 **List prices are a proxy.** The rate table is first-party API pricing. How a
 subscription plan actually meters usage is not published, and the weighting
 almost certainly is not exactly this. It is close enough for ratios, which is
-all it is used for.
+all it is used for. No published or community source shows the meter weighting
+models differently from their dollar prices, so calibrating dollars against
+your own meter remains the best method anyone outside Anthropic has.
+
+**The snapshot is slow by design.** The percentages come from Claude Code's
+own cache of the account meter, which refreshes on its own schedule - roughly
+hourly in practice, because the endpoint behind it rate-limits aggressive
+polling. Between refreshes every figure here is the last real reading plus
+arithmetic. That is why an old snapshot is reported as a floor with its age
+attached rather than dressed up as a current percentage, and why `/usage` is
+the one way to force a fresh reading.
 
 **A reset time can be in the past.** The cache refreshes when Claude Code
 talks to the API, so an idle spell leaves it behind. A window whose `resets_at`
@@ -168,6 +178,13 @@ immediately. Re-run the report if the shape of the work changes.
 The rate table in `scripts/usage.js` is a plain object at the top of the file.
 When new models ship, add a row.
 
+A bracketed suffix on a model id (`claude-sonnet-5[1m]`) is stripped before
+the lookup: it marks a context-window variant of the same model, not a new
+one. Cache reads price at a tenth of the input rate unless a row carries a
+`cacheRead` figure of its own - Fable and Mythos 5.1 price reads outright at
+$0.25 per million, far under the tenth rule, and reads are the dominant input
+in exactly the long sessions where the difference matters.
+
 Until someone does, a model this table has not seen is priced at the average of
 the family its name contains: an unreleased `claude-opus-5-2` is charged at the
 mean of every Opus rate on record. Averaging assumes nothing about which

package/skills/usage-limits/references/tactics.md

@@ -56,6 +56,13 @@ Switch at a task boundary rather than mid-task, because a model switch
 invalidates the prompt cache and the rebuild can cost more than the saving on
 a short remaining task.
 
+The switch needs no boundary at all when the work is delegated: a subagent
+can be dispatched on a cheaper model at low effort mid-session, and that is
+the one model change the agent can make without anyone's hand on `/model`.
+It pays the cold start from lever 7, so it is for self-contained bulky work,
+not quick questions. `node scripts/usage.js --recommend` prices whether the
+budget calls for it.
+
 ### 3. Read less, and read it once
 
 - Line ranges instead of whole files. Grep with a result limit instead of

package/skills/usage-limits/scripts/brief.js

@@ -502,7 +502,9 @@ function briefText(parts) {
           'save at clean boundaries as you go, and keep a short running note of ' +
           'what is done, what is next, and which files are mid-change, so that ' +
           'stopping at any moment loses nothing. Say in one line what may not ' +
-          'land before the reset, then keep working.'
+          'land before the reset, then keep working. If part of what remains is ' +
+          'mechanical, node scripts/usage.js --recommend (from the skill directory) ' +
+          'names the effort and model it should run at.'
         : 'Open your reply with one short line stating this and confirming the ' +
           'request fits, then get on with the work. Keep it to a single line. ' +
           'There is room, so use it: work at full quality, take on the whole ' +

package/skills/usage-limits/scripts/lowpower.js

@@ -81,6 +81,15 @@ function planApply(settings, options, existingState) {
   if (EFFORT_LEVELS.indexOf(effort) === -1) {
     throw new Error('unknown effort "' + effort + '", expected one of ' + EFFORT_LEVELS.join(', '));
   }
+  // Claude Code refuses 'max' in settings.json; it only survives through
+  // /effort or CLAUDE_CODE_EFFORT_LEVEL. Writing it here would save a value
+  // the next session silently ignores, which is worse than an error.
+  if (effort === 'max') {
+    throw new Error(
+      "settings.json does not accept 'max'. Use --effort xhigh here, and /effort max " +
+        'or CLAUDE_CODE_EFFORT_LEVEL=max for the sessions that need it.'
+    );
+  }
   wanted.effortLevel = effort;
   if (options.model) wanted.model = options.model;
 

package/skills/usage-limits/scripts/recommend.js

@@ -0,0 +1,295 @@
+'use strict';
+
+// Turns the budget figures into a choice of effort and model, and says where
+// each half of that choice can actually be applied. There are three levers and
+// they belong to different hands:
+//
+//   - The running session's effort and model are the user's: only /effort and
+//     /model change them, and they change them immediately.
+//   - New sessions are the script's: lowpower.js writes effortLevel and model
+//     into settings.json, which Claude Code reads at launch.
+//   - Delegated work is Claude's alone: a subagent can be dispatched on any
+//     model at any effort, mid-session, with no one asked.
+//
+// Nothing here touches disk. decide() is a pure function over the same report
+// data usage.js already gathers, so the reasoning can be tested without a
+// transcript in sight.
+
+// One notch down, not a cliff. Dropping xhigh to low on work that still has
+// judgement in it costs more in rework than it saves; the ladder loses height
+// a step at a time and 'critical' is the only posture that goes straight to
+// the floor.
+const NEXT_LOWER = { max: 'high', xhigh: 'medium', high: 'medium', medium: 'low', low: 'low' };
+
+// Below this share of output, reasoning is not where the money is going, and
+// turning effort down would trade quality for a saving that is not there.
+const REASONING_FLOOR = 0.1;
+
+// Turns-left walls used when no job size is given. Ten turns is barely a
+// feature; twenty-five is room for one, carefully.
+const CRITICAL_TURNS = 10;
+const TIGHT_TURNS = 25;
+
+const HOUR = 60 * 60 * 1000;
+
+// Where the mechanical bulk should go when it is delegated. One tier down
+// from whatever is doing the judgement; haiku is already the floor.
+function delegateModel(model) {
+  const name = String(model || '').toLowerCase();
+  if (name.indexOf('haiku') !== -1) return 'haiku';
+  if (name.indexOf('sonnet') !== -1) return 'haiku';
+  return 'sonnet';
+}
+
+// The effort actually in force. settings.json says 'default' when nothing is
+// set, and the measured dominant effort of recent turns is better evidence
+// than a guess; xhigh is what Claude Code defaults to when neither knows.
+function currentEffort(settings, recentEffort) {
+  const set = settings && settings.effortLevel;
+  if (set && set !== 'default') return set;
+  if (recentEffort) return recentEffort;
+  return 'xhigh';
+}
+
+function decide(inputs) {
+  const binding = inputs.binding;
+  const rates = inputs.rates;
+  const settings = inputs.settings || {};
+  const effortNow = currentEffort(settings, inputs.recentEffort);
+  const modelNow = (settings.model && settings.model !== 'default' && settings.model) || 'default';
+
+  const base = {
+    posture: 'unknown',
+    reason: null,
+    turnsLeft: null,
+    effort: { current: effortNow, target: effortNow, changes: false, why: null },
+    model: { current: modelNow, delegate: null, nextSession: null, why: null },
+    apply: { now: null, next: null, delegate: null },
+    notes: [],
+  };
+
+  if (!binding || binding.stale) {
+    base.reason = 'no fresh reading of the binding window';
+    return base;
+  }
+  if (!rates || !Number.isFinite(rates.median) || rates.median <= 0) {
+    base.reason = 'no measured turn cost to price the budget in turns';
+    return base;
+  }
+  if (!Number.isFinite(binding.usdPerPercent) || binding.usdPerPercent <= 0) {
+    base.reason = 'the binding window has no calibrated price per point yet';
+    return base;
+  }
+
+  const percentLeft = Number.isFinite(binding.percentLeft) ? binding.percentLeft : 0;
+  const turnsLeft = Math.floor((percentLeft * binding.usdPerPercent) / rates.median);
+  base.turnsLeft = turnsLeft;
+
+  // When the clock wins the race, the limit is not the constraint and there
+  // is nothing to buy by economising: whatever is left at the reset is lost.
+  const pace = inputs.recentTurnsPerHour;
+  if (
+    Number.isFinite(binding.msToReset) &&
+    binding.msToReset > 0 &&
+    Number.isFinite(pace) &&
+    pace > 0 &&
+    (binding.msToReset / HOUR) * pace < turnsLeft * 0.8
+  ) {
+    base.posture = 'reset-first';
+    base.reason = 'the window resets before this pace can spend it';
+    base.effort.why = 'the budget is not the constraint';
+    base.model.why = 'the budget is not the constraint';
+    return base;
+  }
+
+  // With a job size, the forecast arithmetic decides. Without one, the raw
+  // turns of headroom do. Both use the expensive end of the measured spread,
+  // because that is the honest number for a long run.
+  if (Number.isFinite(inputs.turns) && inputs.turns > 0) {
+    const percentHigh = (inputs.turns * rates.high) / binding.usdPerPercent;
+    if (percentHigh > percentLeft) {
+      base.posture = 'critical';
+      base.reason = 'a ' + inputs.turns + ' turn job does not fit in what is left';
+    } else if (percentHigh > percentLeft * 0.75) {
+      base.posture = 'tight';
+      base.reason = 'a ' + inputs.turns + ' turn job fits, but only just';
+    } else {
+      base.posture = 'roomy';
+      base.reason = 'a ' + inputs.turns + ' turn job fits with room to spare';
+    }
+  } else if (percentLeft <= 0 || turnsLeft <= 0) {
+    base.posture = 'critical';
+    base.reason = 'the binding window is spent';
+  } else if (turnsLeft <= CRITICAL_TURNS) {
+    base.posture = 'critical';
+    base.reason = 'about ' + turnsLeft + ' turns of headroom';
+  } else if (turnsLeft <= TIGHT_TURNS) {
+    base.posture = 'tight';
+    base.reason = 'about ' + turnsLeft + ' turns of headroom';
+  } else {
+    base.posture = 'roomy';
+    base.reason = 'about ' + turnsLeft + ' turns of headroom';
+  }
+
+  if (base.posture === 'roomy') {
+    base.effort.why = 'cheapness is not a virtue when the budget is not tight';
+    base.model.why = 'cheapness is not a virtue when the budget is not tight';
+    return base;
+  }
+
+  // Effort is the biggest per-turn lever, but only when reasoning is actually
+  // where the money goes. The reasoning share is the ceiling on the saving,
+  // so a small share means the honest advice is to leave effort alone.
+  const share = inputs.reasoningShare;
+  if (Number.isFinite(share) && share < REASONING_FLOOR) {
+    base.effort.why =
+      'reasoning is only ' + Math.round(share * 100) +
+      '% of output, so effort is not where the money is going';
+  } else {
+    const target = base.posture === 'critical' ? 'low' : NEXT_LOWER[effortNow] || 'medium';
+    if (target !== effortNow) {
+      base.effort.target = target;
+      base.effort.changes = true;
+      base.effort.why =
+        base.posture === 'critical'
+          ? 'reasoning is billed as output, and low is the largest saving that changes nothing else'
+          : 'one notch covers the mechanical stretches; keep judgement calls at full effort';
+    } else {
+      base.effort.why = 'already at the floor for this posture';
+    }
+  }
+
+  // The main model is only worth flipping when things are critical, and even
+  // then it lands in settings.json for the next session: switching the running
+  // session's model mid-task invalidates the prompt cache, so the change
+  // belongs at a session boundary.
+  base.model.delegate = delegateModel(modelNow);
+  base.model.why =
+    'keep ' + (modelNow === 'default' ? 'the current model' : modelNow) +
+    ' for the judgement; the saving is in where the mechanical bulk runs';
+  if (base.posture === 'critical' && base.model.delegate !== 'haiku') {
+    base.model.nextSession = 'sonnet';
+  }
+
+  // The commands, spelled out, because the point of a recommendation is that
+  // it can be acted on without working anything out.
+  if (base.effort.changes) {
+    base.apply.now = '/effort ' + base.effort.target;
+  }
+  if (inputs.codex) {
+    base.notes.push(
+      'Under Codex, settings.json is not in play: change model or effort through ' +
+        "Codex's own controls."
+    );
+  } else if (base.effort.changes || base.model.nextSession) {
+    const settingsEffort = base.effort.changes ? base.effort.target : effortNow;
+    base.apply.next =
+      'node scripts/lowpower.js on --effort ' +
+      (settingsEffort === 'max' ? 'xhigh' : settingsEffort) +
+      (base.model.nextSession ? ' --model ' + base.model.nextSession : '');
+  }
+  base.apply.delegate =
+    'dispatch self-contained mechanical work to a subagent on ' +
+    base.model.delegate +
+    ' at low effort, and keep the judgement here';
+
+  if (Number.isFinite(inputs.sessions) && inputs.sessions > 1) {
+    base.notes.push(
+      inputs.sessions + ' sessions are spending this budget at once, so the headroom ' +
+        'drains faster than these figures alone suggest.'
+    );
+  }
+  if (effortNow === 'max') {
+    base.notes.push(
+      "settings.json does not accept 'max', so a saved level can only go up to " +
+        'xhigh; max survives only through /effort or CLAUDE_CODE_EFFORT_LEVEL.'
+    );
+  }
+
+  return base;
+}
+
+// The report data usage.js gathers, reduced to what decide() reads.
+function fromReport(data, turns) {
+  return {
+    binding: (data && data.binding) || null,
+    rates: (data && data.rates) || null,
+    settings: (data && data.settings) || {},
+    recentEffort: data && data.recent ? data.recent.effort : null,
+    recentTurnsPerHour: data && data.recent ? data.recent.turns : null,
+    reasoningShare: data && data.reasoning ? data.reasoning.shareOfOutput : null,
+    sessions: data && data.sessions ? data.sessions.length : 1,
+    codex: Boolean(data && data.money === false),
+    turns: Number.isFinite(turns) ? turns : null,
+  };
+}
+
+// Local and small on purpose: requiring usage.js back for its formatters
+// would make the two modules a cycle.
+function fmtDuration(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return 'now';
+  const minutes = Math.round(ms / 60000);
+  if (minutes < 60) return minutes + 'm';
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return hours + 'h ' + (minutes % 60) + 'm';
+  return Math.floor(hours / 24) + 'd ' + (hours % 24) + 'h';
+}
+
+function renderRecommend(data, turns) {
+  const decision = decide(fromReport(data, turns));
+  const lines = [];
+  lines.push('Recommendation' + (Number.isFinite(turns) && turns > 0 ? ' for ' + turns + ' turns' : ''));
+  lines.push('');
+
+  if (decision.posture === 'unknown') {
+    lines.push('  Nothing to recommend yet: ' + decision.reason + '.');
+    lines.push('  Run /usage once, do a little work, then ask again.');
+    return lines.join('\n');
+  }
+
+  const binding = data.binding;
+  const where =
+    binding.label +
+    ' window, ' +
+    (Number.isFinite(binding.percentLeft) ? Math.max(0, Math.round(binding.percentLeft)) : '?') +
+    '% left' +
+    (Number.isFinite(binding.msToReset) ? ', resets in ' + fmtDuration(binding.msToReset) : '');
+  lines.push('  Posture   ' + decision.posture + ' - ' + decision.reason + ' (' + where + ')');
+
+  if (decision.posture === 'roomy' || decision.posture === 'reset-first') {
+    lines.push('  Effort    keep ' + decision.effort.current + '; ' + decision.effort.why);
+    lines.push('  Model     keep ' + decision.model.current + '; do not economise');
+    return lines.join('\n');
+  }
+
+  if (decision.effort.changes) {
+    lines.push('  Effort    ' + decision.effort.current + ' -> ' + decision.effort.target + '; ' + decision.effort.why);
+    lines.push('            this session: ' + decision.apply.now + '   (only the user can run it)');
+  } else {
+    lines.push('  Effort    keep ' + decision.effort.current + '; ' + decision.effort.why);
+  }
+  if (decision.apply.next) {
+    lines.push('            new sessions: ' + decision.apply.next);
+  }
+  lines.push('  Model     ' + decision.model.why);
+  lines.push('            ' + decision.apply.delegate);
+  if (decision.model.nextSession) {
+    lines.push('            new sessions: main model to ' + decision.model.nextSession + ' until the window resets');
+  }
+  for (const note of decision.notes) {
+    lines.push('  Note      ' + note);
+  }
+  return lines.join('\n');
+}
+
+module.exports = {
+  decide,
+  fromReport,
+  renderRecommend,
+  delegateModel,
+  currentEffort,
+  NEXT_LOWER,
+  REASONING_FLOOR,
+  CRITICAL_TURNS,
+  TIGHT_TURNS,
+};

package/skills/usage-limits/scripts/usage.js

@@ -47,8 +47,12 @@ const MINUTE = 60 * 1000;
 const HOUR = 60 * MINUTE;
 const DAY = 24 * HOUR;
 
-// USD per million tokens, first-party API rates.
+// USD per million tokens, first-party API rates. `cacheRead` is an absolute
+// $/MTok override for the few models that price reads outright instead of at
+// a tenth of input; everything else uses the CACHE_READ multiplier below.
 const RATES = {
+  'claude-fable-5-1': { input: 10, output: 50, cacheRead: 0.25 },
+  'claude-mythos-5-1': { input: 10, output: 50, cacheRead: 0.25 },
   'claude-fable-5': { input: 10, output: 50 },
   'claude-mythos-5': { input: 10, output: 50 },
   'claude-opus-5': { input: 5, output: 25 },
@@ -91,9 +95,21 @@ function familyAverage(family, table) {
   return { input: input / members.length, output: output / members.length };
 }
 
+// Claude Code aliases and some transcript records carry a bracketed variant
+// suffix - "fable[1m]" is the 1M-context toggle on the same model, not a
+// different one. Left in place it misses the exact rate lookup and lands on
+// the family average, which is wrong whenever a family's members price
+// differently (sonnet 5 at $2 against sonnet 4.6 at $3).
+function normalizeModel(model) {
+  return String(model || '')
+    .toLowerCase()
+    .replace(/\[[^\]]*\]\s*$/, '')
+    .trim();
+}
+
 // Whether the price came from the table or from an assumption.
 function isKnownModel(model) {
-  return Object.prototype.hasOwnProperty.call(RATES, String(model || '').toLowerCase());
+  return Object.prototype.hasOwnProperty.call(RATES, normalizeModel(model));
 }
 
 // Cache traffic is priced as a multiple of the input rate.
@@ -184,7 +200,7 @@ function readJson(file) {
 }
 
 function rateFor(model) {
-  const id = String(model || '').toLowerCase();
+  const id = normalizeModel(model);
   if (RATES[id]) return RATES[id];
   return familyAverage(familyOf(id)) || FALLBACK_RATE;
 }
@@ -199,16 +215,26 @@ function costOf(usage, model) {
 
   let writeUnits = write5m * CACHE_WRITE_5M + write1h * CACHE_WRITE_1H;
   if (writeUnits === 0) {
-    // Older records only carry the undifferentiated total.
+    // Older records only carry the undifferentiated total. Five minutes is
+    // the default TTL, so that is the assumption; an old-format one-hour
+    // session is under-priced by it, but assuming 2x would overcharge the
+    // common case to be right about the rare one.
     writeUnits = (usage.cache_creation_input_tokens || 0) * CACHE_WRITE_5M;
   }
 
-  const inputUnits =
-    (usage.input_tokens || 0) +
-    (usage.cache_read_input_tokens || 0) * CACHE_READ +
-    writeUnits;
+  // Reads price at a tenth of the input rate unless the model prices them
+  // outright. The distinction matters most exactly where reads dominate: a
+  // long session re-reads its whole context every turn, and pricing Fable
+  // 5.1's $0.25 reads by the tenth rule would overstate that spend fourfold.
+  const readTokens = usage.cache_read_input_tokens || 0;
+  const readCost = Number.isFinite(rate.cacheRead)
+    ? readTokens * rate.cacheRead
+    : readTokens * CACHE_READ * rate.input;
 
-  return (inputUnits * rate.input + (usage.output_tokens || 0) * rate.output) / 1e6;
+  const inputUnits = (usage.input_tokens || 0) + writeUnits;
+  return (
+    (inputUnits * rate.input + readCost + (usage.output_tokens || 0) * rate.output) / 1e6
+  );
 }
 
 function tokensOf(usage) {
@@ -812,13 +838,24 @@ function stampPlan(all, planId) {
   return stamped;
 }
 
-// A sample is better when it rests on more turns. Percentages read in whole
-// numbers, so a bigger percentage also divides more precisely.
+// A sample is better when it rests on more of the meter. Percentages read in
+// whole numbers, so a reading at 1% prices a point against a bracket that is
+// mostly rounding, while one at 60% divides by a number that means something.
+// Turn count only breaks the tie: it says how much local spend sat behind the
+// reading, not how precise the denominator was, and preferring it outright is
+// how a 44-turn baseline read at 1% once beat every honest sample after it.
 function betterCalibration(current, candidate) {
   if (!candidate || !Number.isFinite(candidate.usdPerPercent) || candidate.usdPerPercent <= 0) {
     return current || null;
   }
   if (!current || !Number.isFinite(current.turns)) return candidate;
+  if (
+    Number.isFinite(candidate.percent) &&
+    Number.isFinite(current.percent) &&
+    candidate.percent !== current.percent
+  ) {
+    return candidate.percent > current.percent ? candidate : current;
+  }
   return candidate.turns > current.turns ? candidate : current;
 }
 
@@ -933,16 +970,23 @@ function buildWindow(spec, snapshot, events, now, options) {
     // holding. The learned price covers it: what a point costs is a property
     // of the plan, not of this reading.
     const selfPriced =
-      rawPercent > 0 && upTo.cost > 0 && upTo.turns >= MIN_BASELINE_TURNS
+      rawPercent >= MIN_BASELINE_PERCENT && upTo.cost > 0 && upTo.turns >= MIN_BASELINE_TURNS
         ? { usdPerPercent: upTo.cost / rawPercent, turns: upTo.turns, percent: rawPercent }
         : null;
     // A metered window has nothing to learn: its price per point is stated.
     if (selfPriced && !extra.metered) window.calibration = selfPriced;
 
     const known = extra.knownCalibration;
+    // A remembered price read off a near-empty meter is the same rounding
+    // bracket in disguise, so it is no more usable than measuring one now.
     const usable =
-      known && Number.isFinite(known.usdPerPercent) && known.usdPerPercent > 0 ? known : null;
-    // Trust the better-sampled of the two, whichever that is; a stated price
+      known &&
+      Number.isFinite(known.usdPerPercent) &&
+      known.usdPerPercent > 0 &&
+      !(Number.isFinite(known.percent) && known.percent < MIN_BASELINE_PERCENT)
+        ? known
+        : null;
+    // Trust the better-measured of the two, whichever that is; a stated price
     // beats both.
     const stated =
       extra.metered && Number.isFinite(extra.usdPerPercent) && extra.usdPerPercent > 0
@@ -950,9 +994,7 @@ function buildWindow(spec, snapshot, events, now, options) {
         : null;
     const chosen =
       stated ||
-      (selfPriced && usable
-        ? (usable.turns > selfPriced.turns ? usable : selfPriced)
-        : selfPriced || usable);
+      (selfPriced && usable ? betterCalibration(usable, selfPriced) : selfPriced || usable);
 
     if (after.cost > 0 && chosen) {
       const pricePerPoint = chosen.usdPerPercent;
@@ -988,7 +1030,12 @@ function buildWindow(spec, snapshot, events, now, options) {
   // so when the two disagree that badly it is the local history that is
   // incomplete, not the meter.
   const thin = spent.turns < MIN_BASELINE_TURNS && percent >= UNEXPLAINED_PERCENT;
-  const measured = percent !== null && percent > 0 && spent.cost > 0 && !thin;
+  // The same rounding bracket again, in the optimistic direction this time: a
+  // window reading 1% divided a full hour of spend by one and priced the
+  // remaining 99 points at thousands of dollars. Below the floor the learned
+  // price takes over through the fallback chain.
+  const measured =
+    percent !== null && percent >= MIN_BASELINE_PERCENT && spent.cost > 0 && !thin;
   const derived = measured ? spent.cost / percent : null;
   const known = extra.knownCalibration;
   const metered =
@@ -1004,11 +1051,14 @@ function buildWindow(spec, snapshot, events, now, options) {
           : null;
   window.metered = metered;
 
+  // The API reports whole numbers, so a low reading is a wide bracket. A fact
+  // about the reading, not the pricing, so it is set whether or not a price
+  // per point could be found.
+  window.coarse = percent !== null && percent < MIN_BASELINE_PERCENT;
+
   if (percent !== null && priced !== null) {
     window.usdPerPercent = priced;
     window.remainingUSD = window.usdPerPercent * window.percentLeft;
-    // The API reports whole numbers, so a low reading is a wide bracket.
-    window.coarse = percent < 5;
 
     const perTurn = typicalTurnCost(recentEvents, inWindow, events, MIN_PACE_SAMPLE);
     window.percentPerTurn = perTurn === null ? null : perTurn / window.usdPerPercent;
@@ -1313,6 +1363,15 @@ const SATURATION_LIMIT = 105;
 // Fewer turns than this before the snapshot and a point cannot be priced.
 const MIN_BASELINE_TURNS = 5;
 
+// A reading below this cannot price a point either. The API reports whole
+// numbers, so at 1% the denominator is mostly rounding: the true figure is
+// anywhere in a bracket as wide as the reading itself, and a point priced
+// against it converts later spend into several times the points it really
+// moved. A snapshot taken just after a reset is the common case - one sat at
+// 1% while the local spend divided by it asserted 97% of a window that was
+// truly at 35.
+const MIN_BASELINE_PERCENT = 5;
+
 // Past this much of a window, a handful of local turns is not what spent it,
 // so their total is not a fair price for a point.
 const UNEXPLAINED_PERCENT = 20;
@@ -1328,6 +1387,10 @@ function reconstructWindow(spec, snapshot, events, now) {
   const past = totals(events.filter((e) => e.at >= pastStart && e.at <= resetsAt));
   if (past.cost <= 0) return null;
 
+  // The same rounding bracket that poisons the live correction poisons a
+  // rebuild: a closed window that read 1% prices a point off almost nothing.
+  if (snapshot.utilization < MIN_BASELINE_PERCENT) return null;
+
   const usdPerPercent = past.cost / snapshot.utilization;
 
   // The window running now began when the old one reset, not five hours ago.
@@ -2261,6 +2324,23 @@ async function main(argv) {
     }
     return 0;
   }
+  const recommendAt = argv.indexOf('--recommend');
+  if (recommendAt !== -1) {
+    // The turn count is optional: with one the verdict is about that job,
+    // without one it is about the headroom in general.
+    const next = argv[recommendAt + 1];
+    const turns = next && next.indexOf('--') !== 0 ? Number(next) : null;
+    const recommend = require('./recommend.js');
+    if (wantsJson) {
+      process.stdout.write(
+        JSON.stringify(recommend.decide(recommend.fromReport(data, turns)), null, 2) + '\n'
+      );
+    } else {
+      process.stdout.write(recommend.renderRecommend(data, turns) + '\n');
+    }
+    return 0;
+  }
+
   if (wantsJson) {
     process.stdout.write(JSON.stringify(data, null, 2) + '\n');
   } else {
@@ -2295,6 +2375,7 @@ module.exports = {
   reconstructWindow,
   SATURATION_LIMIT,
   MIN_BASELINE_TURNS,
+  MIN_BASELINE_PERCENT,
   buildWindows,
   limitWindows,
   lastRejections,