@s-berdia/opencode-router 1.1.0 → 1.2.0

package/README.md

@@ -1,15 +1,21 @@
 # opencode-router
 
-Automatic model routing for [OpenCode](https://opencode.ai) on the **Go**, **Go Plus**, and **Free** plans.
+[![npm version](https://img.shields.io/npm/v/@s-berdia/opencode-router)](https://www.npmjs.com/package/@s-berdia/opencode-router)
+[![npm downloads](https://img.shields.io/npm/dm/@s-berdia/opencode-router)](https://www.npmjs.com/package/@s-berdia/opencode-router)
+[![CI](https://github.com/s-berdia/Opencode_router/actions/workflows/ci.yml/badge.svg)](https://github.com/s-berdia/Opencode_router/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-![opencode-router demo: the scorecard gives each agent a model, and the build agent changes to the next model at 85% of its 5-hour limit](docs/router-demo.gif)
+**Switch models before you hit your [OpenCode](https://opencode.ai) limit.** Automatic
+model routing and quota failover for the **Go**, **Go Plus**, and **Free** plans.
+
+![opencode-router demo: the scorecard gives each agent a model, and the build agent moves to a free model at 85% of the shared Go allowance](docs/router-demo.gif)
 
 [Watch the demo in full quality (MP4, 25 seconds)](docs/router-demo.mp4?raw=true)
 
 opencode-router gives each OpenCode agent the best model for its job and for your plan.
-It records how much of your quota each model uses. When a model is near its limit, the
-router moves the agent to the next model in its list. When the limit resets, the router
-moves the agent back.
+All Go models share one usage allowance, and the router estimates how much of it you
+used. When the allowance is near its limit, the router moves the agents to free models,
+so your work does not stop. When the use falls again, the router moves them back.
 
 For full step-by-step instructions, read the [usage guide](./USAGE.md). Before you use
 the router, read its [known limits](./USAGE.md#11-known-limits).
@@ -23,8 +29,10 @@ the router, read its [known limits](./USAGE.md#11-known-limits).
   monthly allowance of each model to calculate how many tokens the model can supply in
   5 hours.
 - **Automatic failover.** The `plan`, `build`, `general`, and `explore` agents each have a
-  ranked list of up to 4 models. The router changes to the next model before a limit is
-  reached, and after a rate-limit error.
+  ranked list of up to 4 models. On Go and Go Plus, the last one is a free model. At 85%
+  of the shared Go allowance, or after a usage-limit error, the agents move to their free
+  model. After a rate-limit or overload error of one model, the agent moves to the next
+  model in its list.
 - **Live apply.** The router changes the models in the running OpenCode session. You do
   not have to restart OpenCode after a refresh.
 - **Clear results.** A scorecard shows each model and its scores. With `--verbose`, it
@@ -41,6 +49,15 @@ the router, read its [known limits](./USAGE.md#11-known-limits).
 
 ## Quick start
 
+If you have the OpenCode command-line tool, run this command. Then close OpenCode, start
+it again, and go to step 4.
+
+```bash
+opencode plugin @s-berdia/opencode-router --global
+```
+
+If you do not have the command-line tool, edit the config file:
+
 1. Open your global OpenCode config file in a text editor:
    - Windows: `C:\Users\<your-user-name>\.config\opencode\opencode.json`
    - macOS and Linux: `~/.config/opencode/opencode.json`
@@ -77,7 +94,7 @@ See [Update the router](./USAGE.md#12-update-the-router).
 | Command | What it does |
 | :-- | :-- |
 | `/refresh-routing` | Calculate the routing table again, apply it, and show the scorecard |
-| `/routing-status` | Show the model in use for each agent (after failover) and its 5-hour quota use |
+| `/routing-status` | Show the model in use for each agent (after failover) and the estimated use of the Go allowance |
 | `/routing-plan go-plus` | Save a plan profile (`go`, `go-plus`, or `free`) and apply it immediately |
 | `/routing-eval` | Send one test prompt to the `build` models and write a report |
 | `/routing-update` | Look for a newer version and remove the old copy that OpenCode keeps. Then restart OpenCode |
@@ -135,8 +152,8 @@ or a value that is not valid, the router ignores it and shows a note in the scor
 | Key | Default | Meaning |
 | :-- | :-- | :-- |
 | `plan` | detected from your catalog | `go`, `go-plus`, or `free` |
-| `chainDepth` | 4 for agents, 3 for helpers | Number of models in each failover list. `roles.<role>.chainDepth` wins over it |
-| `softThreshold` | `0.85` | Change to the next model when 5-hour use reaches this part of the 5-hour limit (0.85 = 85%) |
+| `chainDepth` | 4 for agents, 3 for helpers | Number of models in each failover list, including the free model at the end. `roles.<role>.chainDepth` wins over it |
+| `softThreshold` | `0.85` | Move the agents to their free model when the use of the shared Go allowance reaches this part of a window's limit (0.85 = 85%) |
 | `privacy.freeModelsOk` | `true` | `false` keeps `plan`, `build`, and `general` off free models |
 | `denyModels` | `[]` | Model IDs to never use. `*` and `?` wildcards are permitted |
 | `allowModels` | `[]` | If not empty, use only these model IDs |
@@ -175,7 +192,7 @@ score = w_intelligence * intelligence
 
 | File | Contents |
 | :-- | :-- |
-| `~/.config/opencode/router/ledger.json` | Spend and tokens per model for 5 hours, 7 days, and 30 days |
+| `~/.config/opencode/router/ledger.json` | Spend and tokens per model, the use of the shared Go allowance in the last 30 days, and cooldowns |
 | `~/.config/opencode/router/routing-table.json` | The last routing table |
 | `~/.config/opencode/router/last-apply.json` | The result of the last live apply |
 | `~/.config/opencode/router/eval-report.md` | The report of the last `/routing-eval` |
@@ -190,6 +207,8 @@ If `XDG_CONFIG_HOME` is set, the router uses `$XDG_CONFIG_HOME/opencode` in plac
 Models with `-free` in their name can collect your prompts for training. The scorecard
 marks them `free*`. To keep your main work off these models, set
 `"privacy": { "freeModelsOk": false }`. To never use them, set `"denyModels": ["*-free"]`.
+With either setting, the agents have no free model to move to, so they stop when the Go
+allowance runs out.
 
 Once each 24 hours, the router sends one request to `registry.npmjs.org` to get the
 newest version number of the router. It sends no other data. To stop this, set
@@ -210,6 +229,12 @@ To use your local build in OpenCode, put the absolute path of the folder in the
 list. Example for Windows: `"plugin": ["file:///C:/code/Opencode_router"]`. Run
 `npm run build` after each change, then restart OpenCode.
 
+## Contributing
+
+Bug reports, model scores, and code changes are welcome. Read
+[CONTRIBUTING.md](./CONTRIBUTING.md). For questions and ideas, use
+[Discussions](https://github.com/s-berdia/Opencode_router/discussions).
+
 ## License
 
 [MIT](./LICENSE)

package/USAGE.md

@@ -42,7 +42,22 @@ Make sure that you have these items:
 
 ## 2. Install the plugin
 
-### Option A: from npm (recommended)
+### Option A: with the OpenCode command-line tool (fastest)
+
+1. Run this command. It works in PowerShell, CMD, Git Bash, macOS, and Linux:
+
+   ```bash
+   opencode plugin @s-berdia/opencode-router --global
+   ```
+
+   The command downloads the plugin and adds `"@s-berdia/opencode-router"` to the
+   `plugin` list of your global config file.
+2. Close OpenCode. Start OpenCode again.
+
+If the `opencode` command is not found, use Option B. Or install the command-line tool
+with `npm install -g opencode-ai`, and then do step 1 again.
+
+### Option B: from npm, by hand
 
 1. Open the global OpenCode config file.
 
@@ -82,7 +97,7 @@ Make sure that you have these items:
 To use the router in one project only, put the `plugin` entry in `opencode.json` in the
 root folder of that project, not in the global file.
 
-### Option B: from source
+### Option C: from source
 
 Use this option to test changes to the code.
 
@@ -142,7 +157,9 @@ message automatically.
 ## 4. Read the scorecard
 
 The scorecard has one block of rows for each role. The first row of a block is the model
-that the role uses. The other rows are the failover models, in sequence.
+that the role uses. The other rows are the failover models, in sequence. On Go and Go
+Plus, the last row of each agent is a free model (see
+[How the router changes models](#how-the-router-changes-models)).
 
 | Column | Meaning |
 | :-- | :-- |
@@ -153,13 +170,38 @@ that the role uses. The other rows are the failover models, in sequence.
 | Score | The total score, 0 to 100 |
 | Intel | Intelligence score, 0 to 100 |
 | Speed | Speed score, 0 to 100 |
-| Endur | Endurance score, 0 to 100. A high value means that the model can run for a long time on your quota |
-| Tokens/5h | The estimated number of tokens that your quota gives in 5 hours. `unlimited` means no limit |
-| Cap/mo | The monthly dollar allowance for the model on your plan. `inf` means no limit |
+| Endur | Endurance score, 0 to 100. A high value means that the model uses the Go allowance slowly |
+| Tokens/5h | The estimated number of tokens in 5 hours if the agent uses only this model. `unlimited` means no limit |
+| Cap/mo | The monthly limit of the model on your plan. `inf` means no limit |
 | Class | `go` = included in your Go subscription. `free*` = free (your data can be collected). `paid` = Zen pay-as-you-go |
 
 The **Notes** section under the table shows problems, for example a missing catalog.
 
+### How the router changes models
+
+- All `go` models share one usage allowance. Each message uses a part of it: the cost of
+  the message divided by the monthly limit of its model (`Cap/mo`). A model with a low
+  limit uses the allowance faster.
+- The allowance has 3 windows: 5 hours (20% of the monthly allowance), 7 days (50%), and
+  30 days (100%). The router estimates the use in each window from the messages that it
+  records.
+- When the use in a window reaches `softThreshold` (default 85%), the `plan`, `build`,
+  `general`, and `explore` agents use the free model at the end of their list. When the
+  use falls under the threshold again, they go back to their first model.
+- After a usage-limit error from a `go` model, the router stops all `go` models for
+  1 hour. The agents use their free models in that time.
+- After a different rate-limit or overload error, the router stops only that model for
+  1 hour. The agent uses the next model in its list.
+
+`/routing-status` shows the estimated use of the allowance and the state of each agent:
+
+| State | Meaning |
+| :-- | :-- |
+| `healthy` | The agent uses its first model |
+| `failover` | The agent uses a later model, because an earlier model is in cooldown |
+| `free-fallback` | The agent uses its free model, because the Go allowance is near its limit or in cooldown |
+| `limited` | The agent has no usable model. The router keeps the first model |
+
 ## 5. Select your plan
 
 The router finds your plan from the models in your catalog. If it selects the wrong plan,
@@ -205,6 +247,9 @@ use free models.
 }
 ```
 
+With this setting, these agents have no free model at the end of their list. When the
+Go allowance runs out, they stop until it resets.
+
 ### Never use some models
 
 `*` matches any text. `?` matches one character.
@@ -227,8 +272,9 @@ If `allowModels` is not empty, the router uses only the models in the list.
 
 ### Change models earlier or later
 
-`softThreshold` sets when the router changes to the next model. `0.7` changes at 70% of
-the 5-hour limit. The default is `0.85`.
+`softThreshold` sets when the agents change to their free model. `0.7` changes when the
+use of the shared Go allowance reaches 70% in one of its windows (5 hours, 7 days, or
+30 days). The default is `0.85`.
 
 ```json
 {
@@ -265,7 +311,8 @@ Use this setting when you know that a model is better or worse than its score.
 
 `chainDepth` sets the number of models in each failover list. The default is 4 for the
 agents and 3 for the internal helpers. A value under `roles.<role>` wins over the
-top-level value.
+top-level value. On Go and Go Plus, the last model of each list is a free model, if your
+privacy setting permits free models.
 
 ```json
 {
@@ -366,7 +413,7 @@ These commands work in PowerShell, CMD, Git Bash, macOS, and Linux.
 | `opencode-router refresh --scope project` | Write the routing table to `opencode.json` in the current folder |
 | `opencode-router refresh --plan free` | Use the `free` profile for this run only |
 | `opencode-router refresh --json` | Print the result as JSON |
-| `opencode-router status` | Show the model in use for each role (after failover) and its 5-hour use |
+| `opencode-router status` | Show the model in use for each role (after failover) and the estimated use of the Go allowance |
 | `opencode-router plan go-plus --scope global` | Save the plan in the global settings, then calculate and write the routing table |
 | `opencode-router cat` | Show the catalog path, its date, and the number of models |
 | `opencode-router install --scope global` | Write the slash commands as files in `~/.config/opencode/command/`. If `router.config.json` does not exist, it also writes an empty one |
@@ -447,7 +494,7 @@ The router writes these files:
 
 | File | Written by | Contents |
 | :-- | :-- | :-- |
-| `~/.config/opencode/router/ledger.json` | Plugin | Spend and tokens per model for 5 hours, 7 days, and 30 days, and cooldowns |
+| `~/.config/opencode/router/ledger.json` | Plugin | Spend and tokens per model, the use of the shared Go allowance in the last 30 days, and cooldowns |
 | `~/.config/opencode/router/routing-table.json` | Plugin | The last routing table |
 | `~/.config/opencode/router/last-apply.json` | Plugin | The result of the last live apply |
 | `~/.config/opencode/router/eval-report.md` | `/routing-eval` | The test report |
@@ -478,11 +525,12 @@ Do not commit the `router/` folder. It contains your usage data.
 | "live PATCH not attempted (no OPENCODE_SERVER_URL set)" | Normal when you run `refresh` in a terminal | No action. Or see [Apply to a running OpenCode server](#apply-to-a-running-opencode-server) |
 | "hot-apply failed: ..." | OpenCode did not accept the change | Restart OpenCode. The file `opencode.json` has the new models |
 | A model that you selected by hand changes back | The router selects the model at each message | See [Known limits](#11-known-limits) |
+| An agent uses a free model (`free-fallback` in `/routing-status`) | The Go allowance is near its limit, or a usage-limit error occurred | No action. The agent goes back to its first model when the use falls or the cooldown ends. To change the limit, set [`softThreshold`](#change-models-earlier-or-later) |
 | The scores look wrong | A model has no entry in `model-scores.json` | Run `npx @s-berdia/opencode-router refresh --dry-run --verbose`. If the source is `heuristic` or `default`, add the model to `scores` |
 
 ## 11. Known limits
 
-These are the limits of version 1.1.0.
+These are the limits of version 1.2.0.
 
 1. The router sets the model of the `plan`, `build`, `general`, and `explore` agents at
    each message. If you select a different model by hand, the router replaces it. To
@@ -492,12 +540,18 @@ These are the limits of version 1.1.0.
 3. The slash commands always write the global files (`~/.config/opencode/`). To write the
    files of one project, use the terminal tool with `--scope project`.
 4. The slash commands need Node.js 20 or later on the `PATH`.
-5. Use numbers are estimates. The router takes 20% of the monthly allowance as the
-   5-hour limit. The 5-hour period starts at the first message after the last period
-   ended. If two OpenCode windows write at the same moment, one record can be lost.
-6. After a rate-limit or quota error, the model goes into a 1-hour cooldown. A
-   rate-limit error for a full session puts only the model of that session into a
-   cooldown.
+5. Use numbers are estimates. The router counts only the messages that it records. Use
+   from another computer is not included. After an update from version 1.1 or earlier,
+   the estimate starts at 0%. If two OpenCode windows write at the same moment, one
+   record can be lost.
+6. The router treats the 3 windows as rolling windows. If OpenCode resets a window at a
+   fixed time, the estimate can differ from the console.
+7. After a usage-limit error, all `go` models go into a 1-hour cooldown. After a
+   different rate-limit or overload error, only that model goes into a cooldown.
+8. With `"privacy": { "freeModelsOk": false }`, the `plan`, `build`, and `general` agents
+   have no free model. When the Go allowance runs out, they stop until it resets.
+9. The router does not know about **Extra usage** in the OpenCode console. It moves the
+   agents to free models at the threshold, also when Extra usage is on.
 
 ## 12. Update the router
 
@@ -544,7 +598,7 @@ To select the version yourself, write it in the `plugin` list:
 
 ```json
 {
-  "plugin": ["@s-berdia/opencode-router@1.1.0"]
+  "plugin": ["@s-berdia/opencode-router@1.2.0"]
 }
 ```
 

package/dist/bin.js

@@ -1657,6 +1657,7 @@ function catalogMeta(file = catalogCacheFile()) {
 
 // src/scoring.ts
 var FIVE_HOUR_SHARE = 0.2;
+var WEEK_SHARE = 0.5;
 var FREE_ROLE_BONUS = 6;
 var DEFAULT_UNVETTED_PENALTY = 8;
 function modelClass(model) {
@@ -2169,6 +2170,13 @@ function rankRole(catalog, roleName, table, cfg, feeds) {
       chosen.push(entry);
     }
   }
+  if (cfg.plan !== "free" && !chosen.some((entry) => entry.model.free)) {
+    const free = scored.find((entry) => entry.model.free);
+    if (free) {
+      if (chosen.length >= depth && chosen.length > 1) chosen.pop();
+      chosen.push(free);
+    }
+  }
   return chosen.map((entry, index) => ({
     rank: index + 1,
     providerID: entry.model.providerID,
@@ -2230,27 +2238,27 @@ async function buildRoutingTable(opts = {}) {
   };
   return { table, cfg, scoreTable, catalog };
 }
-function activeEntries(table) {
-  return ROLE_NAMES.flatMap((role) => table.active[role] ?? []);
-}
-function pickForRole(table, role, isHealthy) {
+function pickForRole(table, role, isUsable) {
   const chain = table.active[role];
   if (!chain || chain.length === 0) return void 0;
-  return chain.find((entry) => isHealthy(entry.id)) ?? chain[0];
+  return chain.find(isUsable) ?? chain[0];
 }
 function healthCheck(result, ledger) {
-  return (modelId) => ledger.isHealthy(modelId, monthlyCapFor(modelId, result.scoreTable, result.cfg.plan), result.cfg.softThreshold);
-}
-function usagePercent(result, ledger, modelId) {
-  return ledger.usage(modelId, monthlyCapFor(modelId, result.scoreTable, result.cfg.plan)).pct5h * 100;
+  const allowanceOk = ledger.allowanceAvailable(result.cfg.softThreshold);
+  return (entry) => !ledger.inCooldown(entry.id) && (allowanceOk || entry.class !== "subscription");
 }
 function statusRows(result, ledger) {
-  const isHealthy = healthCheck(result, ledger);
+  const isUsable = healthCheck(result, ledger);
+  const allowanceOk = ledger.allowanceAvailable(result.cfg.softThreshold);
   return ROLE_NAMES.map((role) => {
-    const entry = isAgentRole(role) ? pickForRole(result.table, role, isHealthy) : result.table.active[role]?.[0];
-    if (!entry) return { role, pct5h: 0, state: "none" };
-    const state = !isHealthy(entry.id) ? "limited" : entry.rank > 1 ? "failover" : "healthy";
-    return { role, entry, pct5h: usagePercent(result, ledger, entry.id), state };
+    const entry = isAgentRole(role) ? pickForRole(result.table, role, isUsable) : result.table.active[role]?.[0];
+    if (!entry) return { role, state: "none" };
+    const first = result.table.active[role]?.[0];
+    let state = "healthy";
+    if (!isUsable(entry)) state = "limited";
+    else if (entry.rank > 1 && entry.class === "free" && first?.class === "subscription" && !allowanceOk) state = "free-fallback";
+    else if (entry.rank > 1) state = "failover";
+    return { role, entry, state };
   });
 }
 
@@ -2276,6 +2284,11 @@ function formatScorecard(table, opts = {}) {
   lines.push(`- Plan: **${table.plan}**`);
   lines.push(`- Updated: ${when} (UTC)`);
   lines.push(`- Legend: go = Go subscription, free* = $0 (data may be collected), paid = Zen pay-as-you-go`);
+  if (table.plan !== "free") {
+    lines.push(
+      "- All `go` models share one usage allowance. When it is near its limit, each agent uses the free model at the end of its list."
+    );
+  }
   lines.push("");
   lines.push("| Role | # | Model | Var | Score | Intel | Speed | Endur | Tokens/5h | Cap/mo | Class |");
   lines.push("| :-- | --: | :-- | :-- | --: | --: | --: | --: | --: | --: | :-- |");
@@ -2305,23 +2318,37 @@ function formatScorecard(table, opts = {}) {
   );
   return lines.join("\n");
 }
-function formatStatus(table, rows) {
+function percent(part) {
+  return `${(part * 100).toFixed(0)}%`;
+}
+function formatStatus(table, rows, allowance) {
   const lines = [];
   lines.push(`## opencode-router status`);
   lines.push("");
   lines.push(`- Plan: **${table.plan}**`);
+  if (allowance) {
+    const { usage } = allowance;
+    lines.push(
+      `- Go allowance used (estimate): 5 hours ${percent(usage.pct5h)}, 7 days ${percent(usage.pctWeek)}, 30 days ${percent(usage.pctMonth)}`
+    );
+    if (usage.cooldownUntil !== null) {
+      const until = new Date(usage.cooldownUntil).toISOString().slice(11, 16);
+      lines.push(`- Go allowance cooldown until ${until} UTC (${usage.cooldownReason ?? "usage limit"})`);
+    }
+  }
+  const freeFallback = allowance ? `free-fallback = a free model, because the Go allowance is at ${percent(allowance.softThreshold)} or more or in cooldown; ` : "";
   lines.push(
-    `- State: healthy = first model; failover = a later model, because the first is limited; limited = the model in use is near its limit or in cooldown`
+    `- State: healthy = first model; failover = a later model, because an earlier model is in cooldown; ${freeFallback}limited = no usable model`
   );
   lines.push("");
-  lines.push("| Role | Model in use | Rank | Usage (5h) | State |");
-  lines.push("| :-- | :-- | --: | --: | :-- |");
+  lines.push("| Role | Model in use | Rank | State |");
+  lines.push("| :-- | :-- | --: | :-- |");
   for (const row of rows) {
     if (!row.entry) {
-      lines.push(`| ${row.role} | _none_ | - | - | - |`);
+      lines.push(`| ${row.role} | _none_ | - | - |`);
       continue;
     }
-    lines.push(`| ${row.role} | \`${row.entry.id}\` | ${row.entry.rank} | ${row.pct5h.toFixed(0)}% | ${row.state} |`);
+    lines.push(`| ${row.role} | \`${row.entry.id}\` | ${row.entry.rank} | ${row.state} |`);
   }
   return lines.join("\n");
 }
@@ -2399,7 +2426,6 @@ var DAY = 24 * HOUR;
 var WINDOW_5H = 5 * HOUR;
 var WINDOW_WEEK = 7 * DAY;
 var WINDOW_MONTH = 30 * DAY;
-var MONTHLY_LIMIT = 0.95;
 function emptyState(now) {
   return {
     cost5h: 0,
@@ -2482,7 +2508,8 @@ var LedgerStore = class {
     }
     return this.roll(entry, now);
   }
-  record(modelId, costUSD, tokens) {
+  /** `allowanceShare`: the cost divided by the model's monthly limit; 0 for a model outside the Go allowance. */
+  record(modelId, costUSD, tokens, allowanceShare = 0) {
     const state = this.state(modelId);
     state.cost5h += costUSD;
     state.costWeek += costUSD;
@@ -2491,8 +2518,23 @@ var LedgerStore = class {
     state.tokensWeek += tokens;
     state.tokensMonth += tokens;
     state.lastUsedAt = this.now();
+    if (allowanceShare > 0) this.addShare(allowanceShare);
     this.save();
   }
+  /** Call after sync() or state(), never before: a reload would drop changes to the old data. */
+  sharedAllowance() {
+    if (!this.data.allowance || !Array.isArray(this.data.allowance.buckets)) this.data.allowance = { buckets: [] };
+    return this.data.allowance;
+  }
+  addShare(share) {
+    const allowance = this.sharedAllowance();
+    const now = this.now();
+    const hour = Math.floor(now / HOUR) * HOUR;
+    allowance.buckets = allowance.buckets.filter(([start]) => start + HOUR > now - WINDOW_MONTH);
+    const bucket = allowance.buckets.find(([start]) => start === hour);
+    if (bucket) bucket[1] += share;
+    else allowance.buckets.push([hour, share]);
+  }
   cooldown(modelId, durationMs, reason) {
     const state = this.state(modelId);
     state.cooldownUntil = this.now() + durationMs;
@@ -2504,15 +2546,46 @@ var LedgerStore = class {
     state.cooldownUntil = void 0;
     this.save();
   }
-  usage(modelId, monthlyCapUSD) {
-    return usageOf(this.state(modelId), monthlyCapUSD);
+  inCooldown(modelId) {
+    const until = this.state(modelId).cooldownUntil;
+    return until !== void 0 && this.now() < until;
   }
-  /** Healthy = not cooling down, under the soft threshold for 5 hours, and under the monthly limit. */
-  isHealthy(modelId, monthlyCapUSD, softThreshold) {
+  /** After a usage-limit error: every model that uses the shared allowance is limited. */
+  cooldownAllowance(durationMs, reason) {
+    this.sync();
+    const allowance = this.sharedAllowance();
+    allowance.cooldownUntil = this.now() + durationMs;
+    if (reason) allowance.lastError = reason;
+    this.save();
+  }
+  usage(modelId) {
     const state = this.state(modelId);
-    if (state.cooldownUntil && this.now() < state.cooldownUntil) return false;
-    const u = usageOf(state, monthlyCapUSD);
-    return u.pct5h < softThreshold && u.pctMonth < MONTHLY_LIMIT;
+    return {
+      cost5h: state.cost5h,
+      costMonth: state.costMonth,
+      tokens5h: state.tokens5h,
+      tokensMonth: state.tokensMonth,
+      cooldownUntil: state.cooldownUntil ?? null
+    };
+  }
+  /** Rolling use of the shared allowance in the last 5 hours, 7 days, and 30 days. */
+  allowance() {
+    this.sync();
+    const allowance = this.sharedAllowance();
+    const now = this.now();
+    const cooldownUntil = allowance.cooldownUntil !== void 0 && now < allowance.cooldownUntil ? allowance.cooldownUntil : null;
+    return {
+      pct5h: windowShare(allowance.buckets, now, WINDOW_5H) / FIVE_HOUR_SHARE,
+      pctWeek: windowShare(allowance.buckets, now, WINDOW_WEEK) / WEEK_SHARE,
+      pctMonth: windowShare(allowance.buckets, now, WINDOW_MONTH),
+      cooldownUntil,
+      cooldownReason: cooldownUntil === null ? null : allowance.lastError ?? null
+    };
+  }
+  /** True when no window has reached `softThreshold` and no usage-limit cooldown is active. */
+  allowanceAvailable(softThreshold) {
+    const u = this.allowance();
+    return u.cooldownUntil === null && u.pct5h < softThreshold && u.pctWeek < softThreshold && u.pctMonth < softThreshold;
   }
   snapshot() {
     return structuredClone(this.data);
@@ -2523,17 +2596,16 @@ var LedgerStore = class {
     this.loadedMtime = mtimeOf(this.file);
   }
 };
-function usageOf(state, monthlyCapUSD) {
-  const cap5h = monthlyCapUSD === null ? null : monthlyCapUSD * FIVE_HOUR_SHARE;
-  return {
-    cost5h: state.cost5h,
-    costMonth: state.costMonth,
-    tokens5h: state.tokens5h,
-    tokensMonth: state.tokensMonth,
-    pct5h: cap5h === null || cap5h <= 0 ? 0 : state.cost5h / cap5h,
-    pctMonth: monthlyCapUSD === null || monthlyCapUSD <= 0 ? 0 : state.costMonth / monthlyCapUSD,
-    cooldownUntil: state.cooldownUntil ?? null
-  };
+function windowShare(buckets, now, windowMs) {
+  const from = now - windowMs;
+  let sum = 0;
+  for (const [start, share] of buckets) {
+    const end = Math.min(start + HOUR, now);
+    if (end <= from || start > now) continue;
+    const span = end - start;
+    sum += span <= 0 ? share : share * (end - Math.max(start, from)) / span;
+  }
+  return sum;
 }
 
 // src/install.ts
@@ -2959,12 +3031,12 @@ async function cmdStatus(opts) {
   const result = await build(opts);
   const ledger = new LedgerStore(ledgerFile());
   const rows = statusRows(result, ledger);
+  const allowance = result.cfg.plan === "free" ? void 0 : ledger.allowance();
   if (opts.json) {
-    const usage = {};
-    for (const entry of activeEntries(result.table)) usage[entry.id] = { pct: usagePercent(result, ledger, entry.id) };
-    process.stdout.write(JSON.stringify({ table: result.table, rows, usage }, null, 2) + "\n");
+    process.stdout.write(JSON.stringify({ table: result.table, rows, allowance: allowance ?? null }, null, 2) + "\n");
   } else {
-    process.stdout.write(formatStatus(result.table, rows) + "\n");
+    const status = allowance && { usage: allowance, softThreshold: result.cfg.softThreshold };
+    process.stdout.write(formatStatus(result.table, rows, status) + "\n");
     await writeUpdateNotice(opts);
   }
   return 0;