@ljwei-stak/dsh-model-router 0.23.1 → 0.25.0

package/README.md

@@ -10,7 +10,7 @@ Want release notes only? Click **Watch → Custom → Releases** (you do not nee
 
 A cost-aware model-routing workbench for **DeepSeek Harness Desktop**. Plan locally, compare configured routes, inspect execution permissions, and run dependent work packages through model APIs or supported official vendor CLIs.
 
-Current version: **0.23.1** (`@ljwei-stak/dsh-model-router`). Retries now check the whole unfinished downstream group against the budget, and stalled progress/cancel requests recover after a bounded wait. Workbench execution shows live elapsed time and per-package progress, supports cancellation with completed results and reported costs retained, and reconnects to the active job when the panel is reopened. Choose algorithm recommendations or manually assign each decomposed package to an exact model API or official tool, preserving dependencies, refreshed cost previews and retry targets. Routing now supports task-specific quality evidence, joint model/effort selection, historical P90 resource estimates and dependency-aware search. Manual mixed execution is read-only; tools use their configured default model, while the existing editable official-team workflow remains available. Compatibility remains **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2**, including Hermes/Pi installation and terminal support; neither has a verified managed runner yet. Real vendor execution evidence remains tied to **0.20.0**, with no new model experiments in this release. The router and [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) have been independent plugins since 0.12.0.
+Current version: **0.25.0** (`@ljwei-stak/dsh-model-router`). API calls use monetary accounting and daily/monthly budget reservations; subscriptions use a separate ledger of calls and reported tokens. Confirmed subscription execution is not blocked only because the API budget is exhausted or API prices are missing. A switch to an API must be priced and admitted before that API call; mixed results retain both channel receipts. The workbench separates API spending/reservations from subscription usage, with unknown counters kept unknown. Workbench execution shows live elapsed time and per-package progress, supports cancellation with completed results and reported costs retained, and reconnects to the active job when the panel is reopened. Choose algorithm recommendations or manually assign each decomposed package to an exact model API or official tool, preserving dependencies, refreshed cost previews and retry targets. Routing now supports task-specific quality evidence, joint model/effort selection, historical P90 resource estimates and dependency-aware search. Manual mixed execution is read-only; tools use their configured default model, while the existing editable official-team workflow remains available. Compatibility remains **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2**, including Hermes/Pi installation and terminal support; neither has a verified managed runner yet. Real vendor execution evidence remains tied to **0.20.0**, with no new model experiments in this release. The router and [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) have been independent plugins since 0.12.0.
 
 Official CLI teamwork runs packages sequentially with dependency context and no automatic model-directory API fallback. Editable teams explicitly choose the Harness sandbox or the vendor CLI's normal environment. In the latter, Git worktrees collect edits but do not restrict OS access. CLIs retain their configured model unless explicitly mapped. See [real Windows validation and its limits](docs/releases/0.20.0-validation.md).
 
@@ -24,25 +24,25 @@ Both README versions describe the same interfaces, formulas, defaults and limits
 
 **Category:** **Models & Reasoning** (模型与推理), the best fit in the [community directory's category list](https://www.alldsh.com/categories/); this is a community taxonomy, not an official DSH classification.
 
-**Install (DSH Plugin Hub / web profile):** With the DSH CLI available, install the published npm package with:
+**Install (DSH Plugin Hub / web profile):** With the DSH CLI available, install the versioned npm package with:
 
 ```sh
-dsh plugin --profile web add @ljwei-stak/dsh-model-router@0.23.1
+dsh plugin --profile web add @ljwei-stak/dsh-model-router@0.25.0
 ```
 
 **Install in Harness Desktop:** Launch Desktop once to initialize its `desktop` profile, quit Desktop fully, then run:
 
 ```sh
-dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.23.1
+dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.25.0
 ```
 
 You can also paste the package spec into **Harness Desktop → Plugins → Add plugin**. Restart Desktop after installation. A global `npm install -g` by itself does not register a Desktop plugin.
 
-**Package and entry point:** [`@ljwei-stak/dsh-model-router@0.23.1` on npm](https://www.npmjs.com/package/@ljwei-stak/dsh-model-router) is published. The root [`package.json`](package.json) declares the package and bundle patch; [`.dsh-plugin/index.mjs`](.dsh-plugin/index.mjs) exports the required `apply(ctx)` entry point. License: [MIT](LICENSE).
+**Package and entry point:** [`@ljwei-stak/dsh-model-router@0.25.0` on npm](https://www.npmjs.com/package/@ljwei-stak/dsh-model-router). The root [`package.json`](package.json) declares the package and bundle patch; [`.dsh-plugin/index.mjs`](.dsh-plugin/index.mjs) exports the required `apply(ctx)` entry point. License: [MIT](LICENSE).
 
 **Configuration:** There is no supported import of a user-authored JSON/YAML configuration file. Configure providers, models, and credentials on Harness's **Models** page; configure routing profiles and preferences in the plugin settings. Persistent router state is stored in `$DSH_HOME/model-router/state.json` (default: `~/.dsh/model-router/state.json`). Provider CLIs retain their own login and configuration. The router does not copy API keys into model profiles or terminal logs.
 
-**Screenshots and evidence:** The [workbench screenshot](docs/assets/workbench-task-preview.jpg) uses fixture models, prices, and health data; it is a simulated UI preview, not a live Harness or model run. See the [routing workflow diagram](docs/assets/routing-workflow.svg) for the execution flow. The [real Windows validation report](docs/releases/0.20.0-validation.md) documents specific 0.20.0 executions and their limits; 0.23.1 has no verified end-to-end vendor run. The [live progress screenshot](docs/assets/workbench-run-progress.png) is an offline simulation; see the [0.23.1 acceptance report](docs/releases/0.23.1-validation.md) for cancellation, recovery and validation boundaries.
+**Screenshots and evidence:** The [workbench screenshot](docs/assets/workbench-task-preview.jpg) uses fixture models, prices, and health data; it is a simulated UI preview, not a live Harness or model run. See the [routing workflow diagram](docs/assets/routing-workflow.svg) for the execution flow. The [real Windows validation report](docs/releases/0.20.0-validation.md) documents specific 0.20.0 executions and their limits; 0.25.0 has no verified end-to-end vendor run. The [live progress screenshot](docs/assets/workbench-run-progress.png) is an offline simulation; see the [0.25.0 acceptance report](docs/releases/0.25.0-validation.md) for API/subscription separation, checkpoints and validation boundaries.
 
 **Permissions and risks:** Planning is local and makes no model call. Execution sends the selected task/context to the chosen model API or vendor CLI and may incur charges. The default Harness-restricted environment separates read-only runs from approved `workspace-write` runs. An explicitly selected `cli-native` editable team runs with the current OS user's permissions, outside the Harness process sandbox; a Git worktree collects changes but does not restrict OS access. External providers and CLI services apply their own data handling and billing terms.
 
@@ -63,7 +63,7 @@ You can also paste the package spec into **Harness Desktop → Plugins → Add p
 | Editable CLI execution | A sequential CLI team from the workbench, or one supported CLI from a session, using approved isolated Git worktrees and conditional patch integration. |
 | Official tools | Detect, install/update, check launch readiness and inspect login status for twelve registry tools; installation jobs have logs and cancellation. |
 | Interactive terminal | PowerShell/system shell and all twelve registry CLI targets (ZCode TUI on verified Windows desktop installs), including fixed login commands, live output and multiple sessions. |
-| Costs and subscriptions | Daily/monthly budget checks, economy downgrade or pause, subscription-first routing, quota cooldown and explicit handling of other subscription failures. |
+| Costs and subscriptions | API money and concurrent budget reservations are separate from subscription calls/tokens. Unknown subscription usage stays unknown; API fallback is re-estimated and admitted before the paid call. |
 | History and quality | Per-package results, dependency views, failure details, rerun/reassignment, ratings and optional stronger-model review. |
 | Execution boundaries | Shows what each route can read/write and whether its process uses the Harness sandbox. |
 
@@ -78,16 +78,16 @@ Generating a route recommendation is local: it does not start a vendor CLI or ma
 Open **Plugins → Add plugin** and enter:
 
 ```text
-@ljwei-stak/dsh-model-router@0.23.1
+@ljwei-stak/dsh-model-router@0.25.0
 ```
 
-Use the official HTTPS npm source `https://registry.npmjs.org/` when a mirror lacks that exact version. Enable the plugin, then fully quit Harness (including its tray process) and restart it. Plugin details should show **0.23.1** and the sidebar should contain **模型路由** (Model Router). A global `npm install -g` alone does not register a Desktop plugin.
+Use the official HTTPS npm source `https://registry.npmjs.org/` when a mirror lacks that exact version. Enable the plugin, then fully quit Harness (including its tray process) and restart it. Plugin details should show **0.25.0** and the sidebar should contain **模型路由** (Model Router). A global `npm install -g` alone does not register a Desktop plugin.
 
 You can instead install a local `.tgz` archive or its extracted inner `package` directory through the plugin manager. Both must contain `package.json` and `.dsh-plugin`. See [releases](https://github.com/Alice-Marx/dsh-model-router/releases) for archived builds, or build your own checkout below.
 
 ### Upgrade from the old package name
 
-The old name `@ljwei-stak/model-router-galgame` ended at 0.13.0. Remove that plugin entry while retaining your profile/application data, then add `@ljwei-stak/dsh-model-router@0.23.1`. Do not keep both entries installed: they share the internal plugin id `model-router-galgame` and tool names. The retained id lets existing router settings and history carry over.
+The old name `@ljwei-stak/model-router-galgame` ended at 0.13.0. Remove that plugin entry while retaining your profile/application data, then add `@ljwei-stak/dsh-model-router@0.25.0`. Do not keep both entries installed: they share the internal plugin id `model-router-galgame` and tool names. The retained id lets existing router settings and history carry over.
 
 For the combined 0.11.x package, back up the profile and export the GAL saves you want to preserve before upgrading. Story playback, artwork, music and saves now belong to the independent `@ljwei-stak/dsh-galgame` package. The detailed save limitations are in [MIGRATION.md](docs/archive/MIGRATION.md).
 
@@ -102,7 +102,7 @@ The workbench groups the workflow into four navigation tabs. Its header summariz
 | **任务与执行** — Task and execution | Describe the task, generate advice, choose routed read-only execution or official CLI teamwork, preview and confirm, then inspect history. |
 | **模型配置** — Model configuration | Refresh/search the model directory and edit exact-route profiles. |
 | **官方工具** — Official tools | Complete onboarding checks, inspect/install tools and use the interactive terminal. |
-| **预算与安全** — Budget and security | Set routing/cost/review policies and inspect subscription status and execution boundaries. |
+| **预算与安全** — Budget and security | Manage API money/budgets and separate subscription usage; inspect subscription state and execution boundaries. |
 
 Switching tabs keeps the panels mounted, preserving in-progress installation and terminal state.
 
@@ -117,10 +117,12 @@ Switching tabs keeps the panels mounted, preserving in-progress installation and
 5. In **在工作台执行**, choose **模型路由（只读）** for the existing routed executor, or first select **团队分工** and choose **官方工具协作**. For official teamwork, select **只读检查** (read-only) or **编辑文件** (edit files). Editable teams also choose **Harness 受限环境** (Harness sandbox, the default) or **厂商 CLI 正常环境** (normal vendor environment, outside the Harness sandbox). Enter an existing absolute workspace path, or reuse the last run's path. Click **预览执行计划**, review each package, its permissions and required confirmations, then explicitly confirm execution. The Host rechecks the plan before starting; changed conditions can require confirmation again.
 6. Inspect **执行记录与子任务** for the actual channel, response, failures, cost and ratings. Official teamwork replans using only installed CLIs ready for the selected permission mode. Edits require approval and a clean Git repository; successful worktree changes are conditionally integrated. An unavailable or failed CLI never silently becomes an API call in this mode.
 
-After execution starts, the workbench shows elapsed time, the current package and each package's state. **取消执行** requests cancellation of the active call and stops later packages from starting; **正在取消** remains visible until the executor finishes cleanup. Completed results and reported usage remain in history. Cancelling cannot undo charges already incurred or changes already integrated. Closing the panel does not cancel a run; reopening it in the same browser session can reconnect while the Host retains that job. Host restarts clear these in-memory jobs, and completed ledger records remain available.
+After execution starts, the workbench shows elapsed time, the current package and each package's state. **取消执行** requests cancellation of the active call and stops later packages from starting; **正在取消** remains visible until the executor finishes cleanup. Completed results and reported usage remain in history. Cancelling cannot undo charges already incurred or changes already integrated. Closing the panel does not cancel a run; reopening it in the same browser session can reconnect while the Host retains that job. Host restarts clear these in-memory jobs; durably saved package receipts and budget reservations remain. A confirmed dead execution owner is marked `interrupted`, without automatically resuming calls or releasing its hold.
 
 Preview, progress and cancellation requests stop waiting after 15 seconds. Progress reads retry against the same job; an unacknowledged cancellation can be retried explicitly. A transport timeout does not establish that the Host task stopped and never automatically resubmits `startRun`. Before retrying a recorded step, budget checks include that step and all unfinished downstream packages that will execute; reassignment uses the selected route estimate and unknown prices remain unknown. The [timeout recovery screenshot](docs/assets/workbench-run-timeout.png) is an offline simulation.
 
+History shows active and interrupted budget reservations separately from actual spending. Runs with a reservation cannot be rerun or reassigned. If a Host crash or checkpoint failure leaves a reservation, first inspect the original task, retained worktree and provider bill; this release has no manual reconciliation/release control. Do not delete state to make the capacity appear free.
+
 Changing task text, planning mode, profiles, directory or relevant settings invalidates the prior recommendation. Changing execution inputs also discards the pending or completed preview, so execution requires a new preview of the current request. Previewing execution uses current Host state and can differ from a previous local plan.
 
 Example task:
@@ -339,9 +341,9 @@ A worktree separates collected changes; only the selected Harness environment su
 
 ### Failure and retry
 
-History stores package status, exit code, bounded scrubbed diagnostics, entry/model evidence and available usage/cost. A later adapter exception does not discard earlier results. `cli-completed` means the runtime completed its process/patch workflow; deliverables still need acceptance checks. `blocked`, `cancelled`, `incomplete` and `integration-pending` distinguish preflight, interruption, package failure and integration problems.
+Required checkpoints persist package launch state before an external call and its available result, usage and cost before the next paid step. A checkpoint failure stops later steps and preserves the reservation for reconciliation. History stores package status, exit code, bounded scrubbed diagnostics, entry/model evidence and available usage/cost. A later adapter exception does not discard earlier results. `cli-completed` means the runtime completed its process/patch workflow; deliverables still need acceptance checks. `blocked`, `cancelled`, `incomplete` and `integration-pending` distinguish preflight, interruption, package failure and integration problems.
 
-A retry targets a failed package and unfinished downstream packages, preserving other successful results. Eligible editable `incomplete/cancelled` runs require the recorded source, retained worktree and baseline: the Host validates them, creates a fresh worktree, seeds prior unintegrated edits, and continues. Already integrated or `integration-pending` teams cannot use this step-resume path. Native retry again requires write and unsandboxed consent (`confirmWrite` and `confirmUnsandboxed` in the workbench rerun request); disabling the legacy `confirmUnsandboxedCli` setting cannot bypass it. Previous attempt charges remain in spending totals.
+A retry targets a failed package and unfinished downstream packages, preserving other successful results. Eligible editable `incomplete/cancelled` runs require the recorded source, retained worktree and baseline: the Host validates them, creates a fresh worktree, seeds prior unintegrated edits, and continues. Already integrated or `integration-pending` teams cannot use this step-resume path. Native retry again requires write and unsandboxed consent (`confirmWrite` and `confirmUnsandboxed` in the workbench rerun request); disabling the legacy `confirmUnsandboxedCli` setting cannot bypass it. Previous attempt charges remain in spending totals. This retry path requires no active or interrupted reservation on the original run; a crash checkpoint is evidence to reconcile, not an automatic resume token.
 
 Implementation: [official-team-runtime.mjs](.dsh-plugin/shared/official-team-runtime.mjs), [official-tool-executor.mjs](.dsh-plugin/shared/official-tool-executor.mjs), and [run-ledger.mjs](.dsh-plugin/shared/run-ledger.mjs).
 
@@ -349,17 +351,21 @@ Implementation: [official-team-runtime.mjs](.dsh-plugin/shared/official-team-run
 
 ## Costs, subscriptions and quality
 
-- **Budgets:** per-run planning target plus daily/monthly checks. Over-budget routing can try the economy preset or pause for confirmation. Unknown prices remain unknown. These are local accounting/estimation controls, not a hard provider billing cap.
+- **API budgets:** per-run planning targets and daily/monthly monetary checks apply to API-billed execution. Admission atomically checks recorded API spending plus other API reservations, then reserves the new API estimate. Unknown API prices, costs or reservations under a finite limit require explicit confirmation. Later API calls recheck fresh spending and holds. Confirmed subscriptions do not consume API money or fail only because its budget is full or its price is missing. Switching a subscription to API is a new monetary admission: estimate the actual API route, obtain any required confirmation, and reserve atomically before the call. Local estimates are not a hard provider billing cap.
+- **Checkpoints and interruption:** routed executions, retries/reassignment, official teams, single-tool runs and session consultations use the durable lifecycle. Optional reviews and quality upgrades reserve extra capacity before another call. Before a quality upgrade starts, the first receipt and the pending additional attempt are saved, so interruption cannot erase the first charge or imply the second attempt was free. The UI displays actual spending and reservations separately; a reservation is not an invoice. Confirmed dead owners retain interrupted holds and unknown usage evidence until reconciled; elapsed time alone does not free them, and no call is automatically replayed.
 - **Subscription-first:** the default is to prefer a detected CLI account subscription or a configured coding-plan route. API-key environment variables are removed for CLI subscription attempts. `billing` can be `subscription-first`, `api-only` or `subscription-only`; `subscription` can be `cli-login`, `plan-key` or `none`.
-- **Fallback:** detected quota exhaustion/rate limits mark a subscription in cooldown and can retry the routed step on its configured API route, subject to policy and availability. Other attempted subscription failures pause by default (`onSubscriptionFailure: "ask"`): choose API retry, subscription retry or cancel in history. Managed editable/single-tool/team runs do not automatically retry on the API.
-- **Accounting:** API costs count toward budgets. Subscription runs display a reference cost separately. A valid CLI-reported amount, including zero, takes precedence. Token-based CLI cost requires complete usage and an actual reported model matching a configured model or its explicit CLI mapping; unknown or mismatched identity keeps cost unknown. The recommendation's price alone cannot establish actual CLI cost. Provider bills remain authoritative. Version 0.15.0 retains spending from evicted detailed runs and replaced retry results, so trimming history or retrying a step does not erase earlier charges. Costs already discarded by older versions cannot be reconstructed.
+- **Fallback:** detected quota exhaustion/rate limits mark a subscription in cooldown and can retry the routed step on its configured API route, subject to policy and availability. Other attempted subscription failures pause by default (`onSubscriptionFailure: "ask"`): choose API retry, subscription retry or cancel in history. A subscription-to-API route change must pass a fresh estimate and reservation check for the actual API route. A missing price or exceeded finite budget requires the applicable confirmation; without it, the API call stops. Managed editable/single-tool/team runs do not automatically retry on the API.
+- **Subscription usage:** record daily/monthly calls, reported input/output/cache tokens and unknown/incomplete-usage counts, with provider/tool/model groups. Missing counters are not zero. A subscription-to-API attempt keeps the subscription usage receipt as well as the API financial result. Historical reference-dollar fields may remain in old records, but current subscription statistics do not convert them to money or fabricate missing token data. Token counts do not establish a vendor subscription allowance, remaining quota or percentage.
+- **API accounting:** valid CLI-reported money, including zero, takes precedence for API-billed results. Otherwise token-based CLI cost requires complete usage and an actual reported model matching configured pricing or an explicit CLI mapping. Unknown or mismatched identity keeps API cost unknown; the recommended price does not prove actual cost. A CLI using an API key still belongs to API accounting. Provider bills remain authoritative. Replaced retry receipts and evicted history retain prior accounting.
 - **Quality and preference:** optional `off`/`sample`/`always` stronger-model review can add paid calls; it is not treated as human feedback. Explicit ratings adjust separate subjective utility for the exact route and task type, using time decay and low-sample shrinkage (default limit ±0.04, configurable up to ±0.1). They do not change objective quality scores or their hard floors; learning can be disabled, ratings withdrawn, or its starting point reset.
 
 Coding-plan keys and endpoints stay in Harness provider settings. A `plan-key` profile may name an exact configured `apiRoute` as its fallback; the profile editor does not accept credentials or arbitrary commands. Vendor plan eligibility and terms must be checked with the vendor.
 
 ### Actual cost versus planning estimate
 
-A valid CLI-reported USD amount, including explicit zero, wins over token-price calculation. Otherwise, token-based CLI accounting requires complete normalized usage, known nonnegative prices, and a reported actual model matching the priced route or its explicit CLI mapping:
+The formula below applies to API-billed results. Algorithmic route-price comparisons are planning inputs; they do not turn a subscription into an API bill. The execution preview separates API money from estimated subscription tokens.
+
+For API-billed results, a valid CLI-reported USD amount, including explicit zero, wins over token-price calculation. Otherwise, token-based CLI accounting requires complete normalized usage, known nonnegative prices, and a reported actual model matching the priced route or its explicit CLI mapping:
 
 <!-- formula:actual-cost -->
 ```math
@@ -370,7 +376,7 @@ $`C_a`$ is `actualUsd`; $`I_u`$, $`O`$, $`R`$, and $`W`$ correspond to `inputTok
 
 These ledger counters are disjoint after adapter normalization; do not add cached tokens to an inclusive input count. Missing optional cache prices use the input price. Incomplete usage, absent prices or unknown/unmatched identity keep the amount `null`, not zero. Complete terminal evidence can survive a failed/cancelled/timed-out run; partial events are marked `usageIncomplete`.
 
-For example, a complete API result with 1,000 uncached input tokens at \$1/million and 500 output tokens at \$5/million costs \$0.0035. A subscription result can show that amount as `referenceCostUsd` while `costUsd` stays null; reference cost is not added to API spending. A provider-reported \$0 is explicit evidence for that attempt, not proof that earlier unknown attempts were free. Actual provider bills are authoritative. No automatic API fallback in official-team mode prevents a router fallback; a vendor CLI may still use its own configured API credentials.
+For example, a complete API result with 1,000 uncached input tokens at \$1/million and 500 output tokens at \$5/million costs \$0.0035. A subscription result instead records the reported tokens and call count; it is not converted to API money. A provider-reported \$0 for an API attempt is explicit evidence for that attempt, not proof that earlier unknown attempts were free. Actual provider bills are authoritative. Official-team mode does not automatically fall back to API, but a vendor CLI using its own API credentials still incurs API-billed usage.
 
 <a id="routing"></a>
 
@@ -449,13 +455,13 @@ Implementation: [router.mjs](.dsh-plugin/shared/router.mjs), [assignment-solver.
 
 ## Data and privacy
 
-Router profiles/preferences are held in the Harness plugin settings. Runtime state is stored in `<DSH_HOME>/model-router/state.json` (default `~/.dsh/model-router/state.json`): health/onboarding, subscription cooldown, ratings, up to 200 recent runs, 50 terminal metadata records and opt-in public data snapshots. Applied rates and data/feedback policy versions are frozen in run records. Preferences are local to that shared DSH_HOME, not authenticated per-user accounts; public data requests do not upload tasks or feedback.
+Router profiles/preferences are held in the Harness plugin settings. Runtime state is stored in `<DSH_HOME>/model-router/state.json` (default `~/.dsh/model-router/state.json`): health/onboarding, subscription cooldown and separate usage aggregates, ratings, up to 200 recent runs, up to 100 execution reservations, 50 terminal metadata records and opt-in public data snapshots. Runs referenced by a reservation are protected from history trimming. Applied rates and data/feedback policy versions are frozen in run records. Preferences are local to that shared DSH_HOME, not authenticated per-user accounts; public data requests do not upload tasks or feedback.
 
 Version 0.15.0 also retains bounded spending aggregates for up to 90 populated calendar dates and 24 months. These contain amounts/counts, not task or response content.
 
 Run history includes task text, output excerpts, route/workspace, failures and costs. Stored task text is capped at 20,000 characters and each answer at 4,000; reruns can therefore depend on truncated stored context. The plugin does not store API keys in model profiles or terminal transcripts. Task execution still sends the selected task/context to the chosen provider or CLI.
 
-State writes use a lock and atomic replacement. Unparseable state is preserved as a `state.json.corrupt-<timestamp>` backup and surfaced as a notice. Back up state/profile data before migrations and avoid sharing unredacted histories or logs.
+State writes use a lock and atomic replacement. Schema v3 preserves separate subscription usage and channel-aware reservations while migrating readable v1/v2 state without discarding API history, holds or old reference fields. Historical missing tokens stay unknown. Older plugin versions reject v3 state; fully stop every Host process before upgrading and back up state before downgrading. Unparseable state is preserved as a `state.json.corrupt-<timestamp>` backup and surfaced as a notice. Avoid sharing unredacted histories or logs.
 
 <a id="development"></a>
 
@@ -493,6 +499,8 @@ Open [the local preview](http://127.0.0.1:4173). It uses mock models, tools and
 | `shared/official-tool-executor.mjs`, `official-team-runtime.mjs` | Trusted entry, permissions/process capture, dependency execution and patch integration. |
 | `shared/task-executors.mjs`, `subscription-billing.mjs` | Routed CLI/API execution, subscription policy and fallback. |
 | `shared/run-ledger.mjs`, `router-state.mjs` | Identity/usage/cost records, retained spending and locked atomic persistence. |
+| `shared/budget-reservations.mjs`, `execution-lifecycle.mjs` | Cross-process API budget admission, channel-aware reservations, mandatory checkpoints and interrupted-owner evidence. |
+| `shared/subscription-usage.mjs` | Independent observed subscription usage, calendar aggregation and retry/history retention. |
 | Other `.dsh-plugin/shared/` modules | Terminal contracts, tool health, public snapshots and bounded feedback. |
 | `.dsh-plugin/client.js` | Generated Desktop client bundle; rebuild after client changes. |
 | `scripts/` and `tests/` | Build/package/verification helpers and regression tests. |
@@ -503,6 +511,8 @@ Open [the local preview](http://127.0.0.1:4173). It uses mock models, tools and
 
 `check:client` rebuilds in memory and compares the generated output with the committed bundle; `prepack` refuses a stale bundle. pnpm 10 has no `pnpm peers check` command: use the strict install above. Unavailable/incompatible host SDK packages may require the installed Harness runtime for local integration testing; [setup-harness-dev.mjs](scripts/setup-harness-dev.mjs) links missing SDK packages from an explicitly supplied Host `node_modules`, and [start-harness-preview.mjs](scripts/start-harness-preview.mjs) starts a separate local web Host profile. These helpers do not replace dependency verification or Desktop acceptance checks.
 
+GitHub Actions runs a Node 24 matrix on Windows and Linux for the frozen strict dependency install, full test suite, committed-client consistency, actual client build and offline preview compilation. It packs the candidate and checks every file against raw Git blobs plus the runtime import closure. These checks use local fixtures and do not exercise real provider billing. After committing a local candidate, reproduce package verification with `node scripts/check-package.mjs` following `npm run pack:local`.
+
 Legacy compatibility/research files and dated reports are preserved for reference; their presence does not make every older integration an active feature of the current packaged plugin. Releases and synchronization follow [AGENTS.md](AGENTS.md); use versioned packages or verified release tags to reproduce a release.
 
 ### Verification layers and known limits
@@ -526,11 +536,14 @@ When maintaining these docs, update both languages in the same change: matching
 | Symptom | Check |
 | --- | --- |
 | No routes or planning disabled | Configure Harness Models, refresh the directory and wait for tool detection. |
-| Cost unknown | Supply both input/output USD prices for each compared route. |
+| API cost unknown | Supply both input/output USD prices for each compared API route and inspect usage/model evidence. |
+| Subscription usage unknown | The vendor did not report complete counters, or the historical record lacks them. Do not infer tokens from old dollar references or invent remaining quota. |
 | CLI installed but not executable | Review launch-readiness reason, platform/mode support and installation source. |
 | Login/entitlement still fails | Check the vendor account, CLI login, network and actual model access; installation alone is insufficient. |
 | Frontend says Host is older | Fully quit Harness, including the tray process, then restart. |
 | Preview differs from old advice | Directory, login, quota or budget state changed; review the new preview. |
+| Budget remains reserved after interruption | Check the original task, retained worktree and provider bill. The hold is not automatically cleared or replayed, and this release has no manual reconciliation/release control. |
+| Older plugin cannot read state | Schema v3 preserves protected execution and separate subscription usage. Restore a compatible version; do not erase accounting to bypass checks. |
 | Terminal TUI does not render | Check whether the card reports PTY or pipe fallback. |
 | Logged in, but no executable team route | Check `readyModes`, platform, selected install and permission mode; terminal login alone does not establish managed capability. |
 | Skills/MCP missing in Claude read-only | Restricted mode disables them; editable/native choices have different permissions and require the corresponding confirmation. |

package/README.zh.md

@@ -10,7 +10,7 @@
 
 面向 **DeepSeek Harness Desktop** 的成本感知模型路由工作台。在本地规划任务、比较已配置路线、检查执行权限，并通过模型 API 或支持的厂商官方 CLI 执行有依赖关系的工作包。
 
-当前版本：**0.23.1**（`@ljwei-stak/dsh-model-router`）。重跑预算现在覆盖实际会执行的未完成下游，进度和取消请求挂起后可恢复。工作台支持实时耗时、逐工作包进度和取消，保留已完成结果与已报告费用；关闭重开面板可接管原任务。支持“按算法推荐分配 / 手动调整分配”：拆分后的工作包可逐个指定模型 API 或官方工具，保留依赖、重新预览费用，并保存重跑目标。同时接入任务相关质量证据、模型与推理档位联合选择、历史资源 P90 估计与依赖感知搜索。手动混合执行当前只读；官方工具使用自身默认模型，原有官方团队编辑流程保留。继续兼容 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2**，沿用 Hermes/Pi 安装与终端支持；两者仍无经过验证的托管执行器。真实厂商执行证据仍见 **0.20.0** 报告，本版未新增模型实测。路由器与 [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) 自 0.12.0 起已拆分为独立插件。
+当前版本：**0.25.0**（`@ljwei-stak/dsh-model-router`）。API 按金额核算并检查日/月预算和预占；订阅独立统计调用次数与已报告 token 用量。已确认的订阅通道不会仅因 API 预算用满或缺少 API 单价而被阻止；真正转 API 前须对实际路线重新估价并通过预算预占，混合结果分别保留两个通道的收据。工作台把 API 支出/预占与订阅用量分开，缺失用量保持未知。工作台支持实时耗时、逐工作包进度和取消，保留已完成结果与已报告费用；关闭重开面板可接管原任务。支持“按算法推荐分配 / 手动调整分配”：拆分后的工作包可逐个指定模型 API 或官方工具，保留依赖、重新预览费用，并保存重跑目标。同时接入任务相关质量证据、模型与推理档位联合选择、历史资源 P90 估计与依赖感知搜索。手动混合执行当前只读；官方工具使用自身默认模型，原有官方团队编辑流程保留。继续兼容 **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2**，沿用 Hermes/Pi 安装与终端支持；两者仍无经过验证的托管执行器。真实厂商执行证据仍见 **0.20.0** 报告，本版未新增模型实测。路由器与 [GAL](https://github.com/Alice-Marx/deepseek-harness-galgame) 自 0.12.0 起已拆分为独立插件。
 
 官方 CLI 协作按依赖顺序逐包执行、传递依赖上下文，不会自动回退到模型目录 API。可编辑团队需明确选择 Harness 沙箱或厂商 CLI 正常环境。后者通过 Git worktree 收集修改，但不限制操作系统访问。未显式设置模型映射时，各 CLI 沿用自身配置的模型。参见[真实 Windows 验证及其局限](docs/releases/0.20.0-validation.md)。
 
@@ -27,22 +27,22 @@
 **安装（DSH Plugin Hub / web profile）：** 确保 DSH CLI 可用，然后安装已发布的 npm 包：
 
 ```sh
-dsh plugin --profile web add @ljwei-stak/dsh-model-router@0.23.1
+dsh plugin --profile web add @ljwei-stak/dsh-model-router@0.25.0
 ```
 
 **安装到 Harness Desktop：** 首次先启动一次 Desktop 初始化 `desktop` 配置，再彻底退出 Desktop，运行：
 
 ```sh
-dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.23.1
+dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.25.0
 ```
 
 也可以在 **Harness Desktop → 插件 → 添加插件** 中粘贴包名。安装后重启 Desktop。单独运行全局 `npm install -g` 不会注册 Desktop 插件。
 
-**发布包与入口：** [npm 上的 `@ljwei-stak/dsh-model-router@0.23.1`](https://www.npmjs.com/package/@ljwei-stak/dsh-model-router) 已发布。根目录[`package.json`](package.json)声明包名和 bundle patch；[`.dsh-plugin/index.mjs`](.dsh-plugin/index.mjs)导出所需的 `apply(ctx)` 入口。[许可证：MIT](LICENSE)。
+**发布包与入口：** [npm 上的 `@ljwei-stak/dsh-model-router@0.25.0`](https://www.npmjs.com/package/@ljwei-stak/dsh-model-router)。根目录[`package.json`](package.json)声明包名和 bundle patch；[`.dsh-plugin/index.mjs`](.dsh-plugin/index.mjs)导出所需的 `apply(ctx)` 入口。[许可证：MIT](LICENSE)。
 
 **配置文件与配置入口：** 当前不支持导入用户编写的 JSON/YAML 配置文件。Provider、模型和凭据在 Harness **模型**页面配置；路由档案与偏好在插件设置中配置。路由器持久状态存于 `$DSH_HOME/model-router/state.json`（默认：`~/.dsh/model-router/state.json`）。Provider CLI 沿用各自的登录和配置；路由器不会把 API 密钥复制进模型档案或终端日志。
 
-**截图与证据：** [工作台截图](docs/assets/workbench-task-preview.jpg)使用固定的模型、价格和健康状态数据，是模拟 UI 预览，不是实时 Harness 或模型运行。[路由流程图](docs/assets/routing-workflow.svg)展示执行路径。[真实 Windows 验证报告](docs/releases/0.20.0-validation.md)记录了 0.20.0 的具体执行及局限；0.23.1 尚无经过验证的端到端厂商运行。[实时进度截图](docs/assets/workbench-run-progress.png)是离线模拟；取消、重开恢复与验证边界见[0.23.1 验收报告](docs/releases/0.23.1-validation.md)。
+**截图与证据：** [工作台截图](docs/assets/workbench-task-preview.jpg)使用固定的模型、价格和健康状态数据，是模拟 UI 预览，不是实时 Harness 或模型运行。[路由流程图](docs/assets/routing-workflow.svg)展示执行路径。[真实 Windows 验证报告](docs/releases/0.20.0-validation.md)记录了 0.20.0 的具体执行及局限；0.25.0 尚无经过验证的端到端厂商运行。[实时进度截图](docs/assets/workbench-run-progress.png)是离线模拟；API/订阅分开计算、检查点与验证边界见[0.25.0 验收报告](docs/releases/0.25.0-validation.md)。
 
 **权限与风险：** 任务规划在本地完成，不调用模型。实际执行会把选定任务和上下文发送到所选模型 API 或厂商 CLI，并可能产生费用。默认使用 Harness 受限环境；只读运行不修改工作区，`workspace-write` 需要用户明确批准。明确选择 `cli-native` 的可编辑团队会在 Harness 进程沙箱之外，以当前操作系统用户权限运行；Git worktree 只收集修改，不限制操作系统访问。外部 Provider 和 CLI 服务各自适用其数据处理及计费规则。
 
@@ -63,7 +63,7 @@ dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.23.1
 | 可编辑 CLI 执行 | 从工作台执行顺序 CLI 团队，或在会话中调用单个受支持 CLI；使用获批的隔离 Git worktree，并有条件地合入补丁。 |
 | 官方工具 | 对注册表中的十二种工具检测、安装/更新、检查启动就绪和登录状态；安装任务提供日志和取消功能。 |
 | 交互终端 | PowerShell/系统 shell 与十二种注册表 CLI 目标（经过验证的 Windows 桌面安装支持 ZCode TUI）；包含固定登录命令、实时输出和多会话。 |
-| 费用与订阅 | 日/月预算检查、降级为省钱预设或暂停、订阅优先路由、额度冷却，以及对其他订阅失败的显式处理。 |
+| 成本与订阅 | API 金额与并发预算预占、订阅调用/token 分别计算；缺失订阅用量保持未知，转 API 前重新估价并通过预算检查。 |
 | 历史与质量 | 逐包结果、依赖视图、失败详情、重跑/改派、评分与可选的更强模型复核。 |
 | 执行边界 | 显示每条路线可读写的范围，以及进程是否使用 Harness 沙箱。 |
 
@@ -78,16 +78,16 @@ dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.23.1
 打开 **插件 → 添加插件**，输入：
 
 ```text
-@ljwei-stak/dsh-model-router@0.23.1
+@ljwei-stak/dsh-model-router@0.25.0
 ```
 
-镜像缺少该精确版本时，使用官方 HTTPS npm 源 `https://registry.npmjs.org/`。启用插件，然后完全退出 Harness（包括托盘进程）并重启。插件详情应显示 **0.23.1**，侧栏应出现 **模型路由**。仅执行全局 `npm install -g` 不会把插件注册到 Desktop。
+镜像缺少该精确版本时，使用官方 HTTPS npm 源 `https://registry.npmjs.org/`。启用插件，然后完全退出 Harness（包括托盘进程）并重启。插件详情应显示 **0.25.0**，侧栏应出现 **模型路由**。仅执行全局 `npm install -g` 不会把插件注册到 Desktop。
 
 也可以通过插件管理器安装本地 `.tgz` 压缩包，或解压后的内部 `package` 目录。两者都必须包含 `package.json` 和 `.dsh-plugin`。历史构建见 [Releases](https://github.com/Alice-Marx/dsh-model-router/releases)，也可按下文从源码构建。
 
 ### 从旧包名升级
 
-旧名称 `@ljwei-stak/model-router-galgame` 停留在 0.13.0。保留配置档/应用数据，移除旧插件条目，再添加 `@ljwei-stak/dsh-model-router@0.23.1`。不要同时保留两条插件：它们共用内部插件 id `model-router-galgame` 和工具名。保留该 id 能让现有路由设置与历史记录继续使用。
+旧名称 `@ljwei-stak/model-router-galgame` 停留在 0.13.0。保留配置档/应用数据，移除旧插件条目，再添加 `@ljwei-stak/dsh-model-router@0.25.0`。不要同时保留两条插件：它们共用内部插件 id `model-router-galgame` 和工具名。保留该 id 能让现有路由设置与历史记录继续使用。
 
 从合包 0.11.x 升级前，先备份配置档，并导出需要保留的 GAL 存档。剧情播放、立绘、音乐与存档现属于独立的 `@ljwei-stak/dsh-galgame`。详细存档限制见 [MIGRATION.md](docs/archive/MIGRATION.md)。
 
@@ -117,10 +117,12 @@ dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.23.1
 5. 在 **在工作台执行** 中，选择 **模型路由（只读）** 使用现有路由执行器；或先选择 **团队分工**，再选择 **官方工具协作**。官方协作可选择 **只读检查** 或 **编辑文件**。可编辑团队还需选择 **Harness 受限环境**（默认沙箱）或 **厂商 CLI 正常环境**（在 Harness 沙箱外运行）。填入已存在的工作区绝对路径，或沿用上次运行路径。点击 **预览执行计划**，查看各包、权限与所需确认，然后显式确认执行。Host 启动前会重新检查计划；条件变化可能要求重新确认。
 6. 在 **执行记录与子任务** 查看实际通道、回答、失败、费用与评分。官方协作仅使用已安装、且在所选权限模式下就绪的 CLI 重新规划。编辑需要批准和干净的 Git 仓库；成功的 worktree 修改有条件地合入。该模式下，不可用或失败的 CLI 不会静默变成 API 调用。
 
-执行开始后，工作台显示已耗时、当前工作包与每包状态。**取消执行**会请求停止当前调用，并阻止后续工作包启动；执行器完成收尾前持续显示**正在取消**。已完成结果和已报告用量仍保留在历史中。取消不能撤销已经产生的费用或已经整合的改动。关闭面板不会取消执行；同一浏览器会话重新打开后，可在 Host 仍保留该任务时重新连接。Host 重启会清除内存任务，已保存的历史记录仍可查看。
+执行开始后，工作台显示已耗时、当前工作包与每包状态。**取消执行**会请求停止当前调用，并阻止后续工作包启动；执行器完成收尾前持续显示**正在取消**。已完成结果和已报告用量仍保留在历史中。取消不能撤销已经产生的费用或已经整合的改动。关闭面板不会取消执行；同一浏览器会话重新打开后，可在 Host 仍保留该任务时重新连接。Host 重启会清除内存任务，已落盘的工作包结果与预算预占仍保留。确认执行进程已经退出后标记为 `interrupted`，不会自动续跑调用或释放预占。
 
 预览、进度和取消请求最长等待 15 秒。进度读取超时后继续查询同一任务；取消未确认时可手动重试。网络等待超时不代表 Host 任务已停止，也不会自动重发 `startRun`。重跑历史步骤前，预算覆盖该步及实际会执行的全部未完成下游；改派使用所选路线估价，未知价格仍保持未知。[超时恢复截图](docs/assets/workbench-run-timeout.png)为离线模拟。
 
+历史将活动/中断的预算预占与实际支出分别显示；有预占的运行不能重跑或改派。Host 崩溃或检查点保存失败后，请先核对原任务、保留的 worktree 和供应商账单；本版没有手工核对并释放预占的操作入口。不要通过删除状态把占用当成可用额度。
+
 修改任务文本、规划模式、路线配置、目录或相关设置，会使旧建议失效。修改执行输入也会丢弃待确认或已完成的预览，必须对当前请求重新预览。执行预览使用 Host 当前状态，因此可能与先前本地计划不同。
 
 任务示例：
@@ -339,9 +341,9 @@ worktree 用于分离和收集修改；只有所选 Harness 环境提供操作
 
 ### 失败与重试
 
-历史保存包状态、退出码、经过脱敏且有长度限制的诊断、入口/模型证据，以及可用的用量/费用。后续适配器异常不会丢弃先前结果。`cli-completed` 表示运行时完成了进程/补丁流程；交付物仍需通过验收。`blocked`、`cancelled`、`incomplete` 和 `integration-pending` 分别区分预检阻止、中断、包失败与合入问题。
+必须保存的检查点在外部调用前记录启动状态，在下一次付费步骤前保存已有结果、用量和费用。检查点保存失败会停止后续步骤，保留预占以供核对。历史保存包状态、退出码、经过脱敏且有长度限制的诊断、入口/模型证据，以及可用的用量/费用。后续适配器异常不会丢弃先前结果。`cli-completed` 表示运行时完成了进程/补丁流程；交付物仍需通过验收。`blocked`、`cancelled`、`incomplete` 和 `integration-pending` 分别区分预检阻止、中断、包失败与合入问题。
 
-重试针对失败包和未完成的后续依赖，保留其他成功结果。符合条件的可编辑 `incomplete/cancelled` 运行要求记录的源目录、保留的 worktree 与基线：Host 验证后创建新 worktree，播种先前尚未合入的修改，再继续执行。已经合入或 `integration-pending` 的团队不能使用这一步骤恢复路径。正常环境重试仍需写入和沙箱外执行的同意（工作台重跑请求中的 `confirmWrite` 与 `confirmUnsandboxed`）；关闭旧设置 `confirmUnsandboxedCli` 也不能绕过。先前尝试的费用保留在支出总额中。
+重试针对失败包和未完成的后续依赖，保留其他成功结果。符合条件的可编辑 `incomplete/cancelled` 运行要求记录的源目录、保留的 worktree 与基线：Host 验证后创建新 worktree，播种先前尚未合入的修改，再继续执行。已经合入或 `integration-pending` 的团队不能使用这一步骤恢复路径。正常环境重试仍需写入和沙箱外执行的同意（工作台重跑请求中的 `confirmWrite` 与 `confirmUnsandboxed`）；关闭旧设置 `confirmUnsandboxedCli` 也不能绕过。先前尝试的费用保留在支出总额中。原运行必须没有活动或中断预占，才能走这条重试路径；崩溃检查点是待核对证据，不是自动续跑令牌。
 
 实现：[official-team-runtime.mjs](.dsh-plugin/shared/official-team-runtime.mjs)、[official-tool-executor.mjs](.dsh-plugin/shared/official-tool-executor.mjs) 与 [run-ledger.mjs](.dsh-plugin/shared/run-ledger.mjs)。
 
@@ -349,17 +351,21 @@ worktree 用于分离和收集修改；只有所选 Harness 环境提供操作
 
 ## 成本、订阅与质量
 
-- **预算：** 单次规划目标加日/月检查。超预算路由可以尝试省钱预设，或暂停等待确认。未知价格保持未知。这些是本地核算/估计控制，不是厂商的硬性计费上限。
+- **API 预算：** 单次规划目标与日/月金额检查用于 API 计费执行。启动时原子检查已记录 API 支出和其他 API 预占，再为本次 API 估计预占。有限预算下，API 单价、费用或预占未知需要显式确认；后续 API 调用会按最新支出与预占重验。已确认的订阅通道不占 API 金额，也不会仅因 API 预算用满或单价缺失而被阻止。订阅转 API 是一次新的金额准入：按实际 API 路线估价、取得所需确认并原子预占后才调用。本地估计不是厂商硬性扣费上限。
+- **检查点与中断：** 路由执行、重跑/改派、官方团队、单工具运行和会话咨询共用持久执行生命周期。可选复核和质量升级在追加调用前预占额度。质量升级启动前，先保存首个收据与待核对的追加尝试，避免中断时抹掉首次费用或把第二次尝试视为免费。界面区分实际支出与预占，预占不是账单。确认进程退出后仍保留中断预占及未知用量证据以供核对；仅凭经过时间不会释放，也不会自动重放调用。
 - **订阅优先：** 默认优先检测到的 CLI 账号订阅或已配置 coding-plan 路线。CLI 订阅尝试会移除 API-key 环境变量。`billing` 可为 `subscription-first`、`api-only` 或 `subscription-only`；`subscription` 可为 `cli-login`、`plan-key` 或 `none`。
-- **回退：** 检测到额度耗尽/限流时，将订阅标记为冷却，并可按策略与可用性在已配置 API 路线上重试该路由步骤。其他已尝试的订阅失败默认暂停（`onSubscriptionFailure: "ask"`）：可在历史中选择 API 重试、订阅重试或取消。托管可编辑/单工具/团队运行不会自动在 API 上重试。
-- **核算：** API 费用计入预算。订阅运行单独显示参考费用。有效的 CLI 报告金额（包括零）优先采用。按 token 计算 CLI 费用，需要完整用量，以及报告的实际模型匹配某个已配置模型或其显式 CLI 映射；身份未知或不匹配时费用保持未知。仅有推荐路线价格不能确定实际 CLI 费用。厂商账单为准。0.15.0 起保留已淘汰详细运行和被重试替换结果的支出，因此裁剪历史或重试步骤不会抹掉先前费用。更早版本已丢弃的费用无法重建。
+- **回退：** 检测到额度耗尽/限流时，将订阅标记为冷却，并可按策略与可用性在已配置 API 路线上重试该路由步骤。其他已尝试的订阅失败默认暂停（`onSubscriptionFailure: "ask"`）：可在历史中选择 API 重试、订阅重试或取消。订阅切换到 API 时，必须按实际 API 路线重新估算并检查预占。缺少价格或超出有限预算时，需要相应确认；未获确认不会启动 API 调用。托管可编辑/单工具/团队运行不会自动在 API 上重试。
+- **订阅用量：** 独立记录日/月调用次数、已报告输入/输出/缓存 token 和未知/不完整用量次数，并按供应商、工具、模型分组。缺失计数不视为零。订阅转 API 时同时保留订阅用量收据和 API 计费结果。旧记录的参考美元字段可保留，但当前订阅统计不再把它折算为金额，也不据此补造 token。token 数不能证明厂商订阅总额度、剩余额度或已用百分比。
+- **API 核算：** 对 API 计费结果，有效的 CLI 报告金额（包括零）优先采用。否则按 token 计算 CLI 费用，需要完整用量，以及报告实际模型匹配已配置单价或显式 CLI 映射。身份未知或不匹配时 API 费用保持未知；推荐路线价格不能证明实际成本。CLI 使用 API Key 时仍属于 API 计费，厂商账单为准。重跑替换的收据和已裁剪历史保留先前核算。
 - **质量与偏好：** 可选 `off`/`sample`/`always` 更强模型复核可能增加付费调用，且不作为人工反馈。显式评分以时间衰减和小样本收缩，调整精确路线、任务类型对应的独立主观效用（默认上限 ±0.04，可配置至 ±0.1）。评分不改变客观质量分或其硬下限；可禁用学习、撤回评分或重置学习起点。
 
 Coding-plan 密钥与端点保留在 Harness 供应商设置中。`plan-key` 配置可将已配置的精确 `apiRoute` 指定为回退；路线编辑器不接受凭据或任意命令。厂商套餐资格与条款需向厂商核实。
 
 ### 实际费用与规划估计
 
-有效的 CLI 报告美元金额（包括明确的零）优先于 token × 单价计算。否则，按 token 核算 CLI 费用要求完整、归一化的用量，已知非负价格，以及报告的实际模型匹配计价路线或其显式 CLI 映射：
+下面公式用于 API 计费结果。算法中的路线价格比较是规划输入，不会把订阅变成 API 账单；执行预览分别显示 API 金额和订阅预估 token。
+
+对 API 计费结果，有效的 CLI 报告美元金额（包括明确的零）优先于 token × 单价计算。否则，按 token 核算 CLI 费用要求完整、归一化的用量，已知非负价格，以及报告的实际模型匹配计价路线或其显式 CLI 映射：
 
 <!-- formula:actual-cost -->
 ```math
@@ -370,7 +376,7 @@ $`C_a`$ 对应 `actualUsd`；$`I_u`$、$`O`$、$`R`$、$`W`$ 分别对应 `input
 
 经适配器归一化后，这些账本计数互不重叠；不要把缓存 token 再加到已包含缓存的输入计数中。缺少可选缓存单价时，使用输入单价。用量不完整、价格缺失或身份未知/不匹配时，金额保持 `null`，不是零。完整的终态证据可在失败、取消、超时后保留；部分事件标记为 `usageIncomplete`。
 
-例如，完整 API 结果含 1,000 个未缓存输入 token（\$1/百万）和 500 个输出 token（\$5/百万），费用为 \$0.0035。订阅结果可把该金额显示为 `referenceCostUsd`，而 `costUsd` 保持 null；参考费用不加进 API 支出。厂商报告的 \$0 是该次尝试的明确证据，不能证明先前费用未知的尝试免费。实际厂商账单为准。官方团队模式不自动回退 API，防止的是路由器自身的回退；厂商 CLI 仍可能使用它自己配置的 API 凭据。
+例如，完整 API 结果含 1,000 个未缓存输入 token（\$1/百万）和 500 个输出 token（\$5/百万），费用为 \$0.0035。订阅结果记录已报告 token 和调用次数，不折算成 API 金额。API 尝试中厂商报告的 \$0 是该次尝试的明确证据，不能证明先前费用未知的尝试免费。实际厂商账单为准。官方团队模式不自动回退 API，但厂商 CLI 使用自身 API 凭据时仍产生 API 计费。
 
 <a id="routing"></a>
 
@@ -449,13 +455,13 @@ $`L`$ 为延迟效用：$`t`$ 是匹配历史的 P90 耗时，单位为毫秒；
 
 ## 数据与隐私
 
-路由配置/偏好保存在 Harness 插件设置中。运行时状态写入 `<DSH_HOME>/model-router/state.json`（默认 `~/.dsh/model-router/state.json`）：健康/入门状态、订阅冷却、评分、最多 200 条近期运行、50 条终端元数据，以及主动启用的公共数据快照。运行记录会冻结采用的单价、数据/反馈策略版本。偏好属于共享的本地 DSH_HOME，不是经过认证的独立用户账号；公共数据请求不会上传任务或反馈。
+路由配置/偏好保存在 Harness 插件设置中。运行时状态写入 `<DSH_HOME>/model-router/state.json`（默认 `~/.dsh/model-router/state.json`）：健康/入门状态、订阅冷却与独立用量汇总、评分、最多 200 条近期运行、最多 100 条执行预占、50 条终端元数据，以及主动启用的公共数据快照。预占引用的运行不会被历史裁剪删除。运行记录会冻结采用的单价、数据/反馈策略版本。偏好属于共享的本地 DSH_HOME，不是经过认证的独立用户账号；公共数据请求不会上传任务或反馈。
 
 0.15.0 起还保留有界支出汇总，最多覆盖 90 个有数据的日历日期与 24 个月。只包含金额/计数，不含任务或回答内容。
 
 运行历史包含任务文本、输出节选、路线/工作区、失败与费用。保存的任务最多 20,000 字符，每条回答最多 4,000 字符，因此重跑可能依赖被截断的已存上下文。插件不把 API key 存进模型配置，也不保存终端转录。任务执行仍会把所选任务/上下文发送给相应供应商或 CLI。
 
-状态写入使用锁和原子替换。无法解析的状态保留为 `state.json.corrupt-<timestamp>` 备份，并显示提示。迁移前请备份状态/配置档数据；不要分享未经脱敏的历史或日志。
+状态写入使用锁和原子替换。状态结构 v3 保留独立订阅用量和分通道预占，升级可读的 v1/v2 状态时保留 API 历史、预占与旧参考字段；历史缺失 token 保持未知。旧插件会拒绝读取 v3 状态；升级前完全停止所有 Host 进程，降级前备份状态。无法解析的状态保留为 `state.json.corrupt-<timestamp>` 备份并显示提示。不要分享未经脱敏的历史或日志。
 
 <a id="development"></a>
 
@@ -493,6 +499,7 @@ npm run preview:ui
 | `shared/official-tool-executor.mjs`、`official-team-runtime.mjs` | 可信入口、权限/进程捕获、依赖执行与补丁合入。 |
 | `shared/task-executors.mjs`、`subscription-billing.mjs` | 路由 CLI/API 执行、订阅策略与回退。 |
 | `shared/run-ledger.mjs`、`router-state.mjs` | 身份/用量/费用记录、支出保留与加锁原子持久化。 |
+| `shared/budget-reservations.mjs`、`execution-lifecycle.mjs` | 跨进程预算准入、剩余预占、必须保存的检查点和中断进程证据。 |
 | 其他 `.dsh-plugin/shared/` 模块 | 终端契约、工具健康、公共快照与有界反馈。 |
 | `.dsh-plugin/client.js` | 生成的 Desktop 客户端 bundle；修改客户端后需重建。 |
 | `scripts/` 与 `tests/` | 构建/打包/验证辅助脚本与回归测试。 |
@@ -503,6 +510,8 @@ npm run preview:ui
 
 `check:client` 在内存中重建并比较已提交 bundle；`prepack` 会拒绝过期 bundle。pnpm 10 没有 `pnpm peers check` 命令：请使用上述严格安装。Host SDK 包不可用/不兼容时，本地集成测试可能需要已安装的 Harness 运行时；[setup-harness-dev.mjs](scripts/setup-harness-dev.mjs) 从显式提供的 Host `node_modules` 链接缺失 SDK 包，[start-harness-preview.mjs](scripts/start-harness-preview.mjs) 启动独立的本地 Web Host 配置档。这些辅助脚本不能代替依赖验证或 Desktop 验收。
 
+GitHub Actions 通过 Windows/Linux Node 24 矩阵执行冻结锁文件严格依赖安装、全量测试、已提交客户端一致性、实际客户端构建和离线预览编译。打包后逐文件对比原始 Git blob，并检查运行时 import 依赖是否完整。这些检查使用本地预置数据，不验证真实供应商计费。提交本地候选后，可先运行 `npm run pack:local`，再运行 `node scripts/check-package.mjs` 复现包验证。
+
 旧兼容/研究文件和带日期报告保留作参考；它们的存在不代表当前发行插件仍启用所有旧集成。发布与同步遵循 [AGENTS.md](AGENTS.md)；重现某次发布请使用带版本号的包或已验证的发布 tag。
 
 ### 验证层次与已知局限
@@ -526,11 +535,14 @@ npm run preview:ui
 | 现象 | 检查 |
 | --- | --- |
 | 没有路线或规划被禁用 | 配置 Harness 模型、刷新目录，并等待工具检测完成。 |
-| 费用未知 | 为每条参与比较的路线同时填写输入/输出美元单价。 |
+| API 费用未知 | 为每条参与比较的 API 路线填写输入/输出美元单价，并核对用量/模型证据。 |
+| 订阅用量未知 | 厂商未报告完整计数或历史记录缺失；不要从旧参考美元还原 token，也不要推断剩余额度。 |
 | CLI 已安装但不可执行 | 查看启动就绪原因、平台/模式支持和安装来源。 |
 | 登录/模型权限仍失败 | 检查厂商账号、CLI 登录、网络和实际模型访问；仅安装成功不够。 |
 | 前端提示 Host 版本较旧 | 完全退出 Harness（包括托盘进程）后重启。 |
 | 预览与旧建议不同 | 目录、登录、额度或预算状态已变化；请查看新预览。 |
+| 中断后预算仍被预占 | 核对原任务、保留的 worktree 和供应商账单。预占不会自动释放或续跑，本版没有手工核对并释放的操作入口。 |
+| 旧插件无法读取状态 | v3 保留受保护执行和独立订阅用量；恢复兼容版本，不要删除账本绕过检查。 |
 | 终端 TUI 不渲染 | 检查卡片报告的是 PTY 还是管道回退模式。 |
 | 已登录但团队没有可执行路线 | 检查 `readyModes`、平台、所选安装和权限模式；仅终端已登录不能证明具备托管执行能力。 |
 | Claude 只读中没有 skills/MCP | 受限模式会禁用它们；可编辑/正常环境选项权限不同，需要相应确认。 |

package/docs/WORKBENCH_USER_GUIDE.zh.md

@@ -215,19 +215,21 @@ PTY 加载失败时卡片显示**管道模式**：全屏界面、箭头键、尺
 
 ## 预算与安全
 
-**成本控制与路由方案**支持省钱优先、均衡、效果优先，以及每日/月度预算、超预算动作、订阅普通失败策略和质量回路。指定模型模式跳过路线比较；未知价格无法保证满足预算。
+**API 费用、预算与路由方案**支持省钱优先、均衡、效果优先，以及 API 每日/月度金额预算、超预算动作、订阅普通失败策略和质量回路。API 预算包含已发生费用和其他任务的 API 预占；指定模型跳过路线比较。已确认的订阅通道不占 API 预算，不会仅因 API 预算满或单价缺失而被阻止。
 
 **订阅与 API Key**显示供应商计费方式、订阅来源、状态/恢复时间及 API 回退是否可用。检测到额度用尽或限流后，路由执行可按策略转 API 并记录原因；其他订阅错误默认暂停确认。单工具/团队托管执行不会自动转 API。
 
-API 花费计入预算；订阅显示按 API 价折算的参考费用，不计入预算。预算和费用是本地估算/核算，不代替厂商账单；无法确定费用时显示未知。
+**订阅用量**独立显示今日/本月调用次数、厂商已报告的输入/输出/缓存 token，以及未知或不完整用量次数，并按供应商、工具和模型分组。部分已报告字段保留，未报告字段显示“未报告”，不会当零。旧参考美元数据可以保留，但不用于现行订阅金额统计，也无法据此还原缺失 token。
 
-有效的 CLI 自报金额优先，包括 `0`。只有完整 token 用量与回报实际模型可核对到已配置模型或其显式 CLI 映射时，才按相应单价折算。缺失或不匹配的实际模型、不完整用量都保留未知费用；Harness 推荐模型的价格不能证明该 CLI 实际成本。预览仍可使用推荐路线作规划估算，须与实际核算区分。
+API 按金额核算并计入预算，订阅按用量核对；订阅 token 不是厂商总配额、剩余额度或已用百分比，插件不据此猜测厂商限额。预算/费用是本地估算和核算，不替代账单。订阅回退到 API 前，会按实际 API 路线重估、取得必要确认并原子预占；未通过时不发起 API 请求。混合执行记录同时保留订阅用量收据与 API 费用。
 
-0.15.0 会保留裁剪详细历史及重试前的费用累计，避免超过 200 条历史或重跑步骤后预算漏算。此前旧版本已丢弃的消费记录无法恢复。
+对 API 计费，CLI 有效自报金额优先，包括 `0`。CLI 使用 API Key 时仍走 API 费用核算。只有完整 token 用量与回报实际模型可核对到已配置模型或其显式 CLI 映射时，才按相应单价折算。缺失或不匹配的实际模型、不完整用量都保留未知费用；Harness 推荐模型的价格不能证明该 CLI 实际成本。预览仍可使用推荐路线作规划估算，须与实际核算区分。
+
+裁剪详细历史和替换重试结果时，API 费用和订阅用量分别保留累计，避免超过 200 条详细记录或重跑步骤后漏算/重算。旧版已经丢弃的费用与缺失 token 无法恢复。状态结构 v3 从可读的 v1/v2 状态迁移，保留旧费用和预占；升级前完全退出 Harness（包括托盘和所有 Host），降级前保留状态备份，旧插件无法读取 v3。
 
 ### 持续反馈与本地偏好
 
-在**预算与安全 → 成本控制与路由方案 → 持续反馈与本地偏好**设置**启用用户反馈学习**、半衰期（默认30天）、收缩强度（默认3）和最大偏好效用调整（默认0.04，允许0–0.1）。较旧结果权重更低，少量评价被收缩到接近零；没有评价不等于失败或满意，执行成功也不自动计为好评。查看有效反馈数、有效权重和策略版本后重新规划。
+在**预算与安全 → API 费用、预算与路由方案 → 持续反馈与本地偏好**设置**启用用户反馈学习**、半衰期（默认30天）、收缩强度（默认3）和最大偏好效用调整（默认0.04，允许0–0.1）。较旧结果权重更低，少量评价被收缩到接近零；没有评价不等于失败或满意，执行成功也不自动计为好评。查看有效反馈数、有效权重和策略版本后重新规划。
 
 学习限定在同一个本地 **DSH_HOME 工作室共享**、最近 **200 次运行**，不按账号隔离，也不无限保存学习记忆；未核验实际模型的 CLI 默认结果不会训练推荐模型。启停不删除评价。“从现在重新学习”会先请求确认，再将学习起点移到当前时间；此前结果不再参与调整，但执行历史和费用累计保留。本版不为学习自动探索或增加付费模型调用。
 
@@ -286,4 +288,4 @@ Windows Codex 在 Harness 环境仅支持只读：其原 `CODEX_HOME` 状态仍
 
 问题反馈请附宿主/插件版本、执行模式、工具状态及脱敏错误，勿提供密钥。源码、安装和资料入口见[中文 README](../README.zh.md)。
 
-执行恢复：预览、进度与取消请求等待超过15秒会终止该次网络等待；进度会重试同一任务，取消未确认可手动重试，任务不会自动重新启动。历史步骤重跑前，预算按目标及未成功的下游步骤合计；整组超限时先确认再运行，改派按所选路线重估，缺失价格不视为零费用。
+执行恢复：预览、进度与取消请求等待超过15秒会终止该次网络等待；进度会重试同一任务，取消未确认可手动重试，任务不会自动重新启动。历史步骤重跑前，API 预算按目标及未成功下游中的 API 部分合计；订阅部分单列预估 token。API 部分超限时先确认再运行，改派按实际计费渠道重估，缺失 API 价格不视为免费。

package/docs/releases/0.24.0-validation.md

@@ -0,0 +1,41 @@
+# 0.24.0 release acceptance
+
+Date: 2026-10-24. Package: `@ljwei-stak/dsh-model-router@0.24.0`.
+
+Source acceptance: passed. Local tests and the actual Windows/Linux matrix below verify the implementation. The final tagged commit, archive digests and post-publication anonymous download checks are recorded separately in the dated release/archive evidence, so this document does not need to embed the checksum of its own containing archive.
+
+## Problems and resulting behavior
+
+- Concurrent executions could each pass a budget check against the same historical balance. Admission now checks recorded API spending plus other executions' remaining reservations under the shared state lock, then persists the new run and reservation atomically. Known estimated capacity is reserved before the call; missing prices and unresolved fees remain unknown and require explicit confirmation under a finite daily/monthly limit.
+- A Host interruption could lose completed-step records because the run was saved only at the end. Required checkpoints now save launch state before an external call and available receipts before the next paid step. A receipt replaces its portion of the remaining estimate with actual accounting. Routed runs, retry/reassignment, official teams, single-tool executions and session consultations use the lifecycle. Optional stronger-model reviews and quality upgrades reserve extra capacity before their additional calls.
+- Before every later paid call, admission rechecks fresh actual spending and remaining reservations. If earlier charges exceed estimates or unresolved fees prevent a finite budget from being verified, downstream calls stop. Subscription-to-API fallback must re-estimate its actual route; unknown pricing or exceeded budget prevents the call. Quality upgrades first save the initial receipt and pending additional attempt.
+- A budget stop preserves completed receipts and releases unused reservations only after the worker settles. It differs from a crash or storage failure, which retains holds for reconciliation.
+- Checkpoint persistence failure stops later calls. Confirmed dead owners become interrupted while retaining reservations and unresolved usage evidence. Live or uncertain owners are not expired by elapsed time. Protected run records remain in the bounded ledger, and active/interrupted reservations block rerun and reassignment.
+- Receipt timestamps remain attached to observed package receipts across later checkpoints and final saves, including day/month rollovers. Windows lock-file sharing races use the existing bounded contention wait; PATH and ZCode discovery use the declared platform path syntax.
+- Actual spending and reserved estimates are separate in the workbench. State schema v2 retains ownership, remaining reservations and checkpoints and accepts readable v1 state without dropping its ledger. Older plugin versions reject v2 state instead of silently rewriting away protected reservations.
+- A Windows/Linux Node 24 workflow runs strict frozen dependency installation, the complete test suite, committed-client consistency, actual client build/check, offline preview compilation and archive verification. Package verification compares every file byte to the selected Git revision and checks the local runtime import closure.
+
+## Validation record
+
+| Check | Observed evidence |
+| --- | --- |
+| Focused reservation/state regressions | `npm test` includes reservation/state tests for cross-process admission, receipt settlement, protected retention, dead-owner recovery, unknown costs, ownership checks and v1 migration; the final local suite has 1,126 passes, 0 failures and 3 environment skips. |
+| Host and executor integration | Full suite coverage includes required checkpoint failures, stopping downstream calls, retry accounting once, official team/tool/consultation/review/upgrade entry points, fallback repricing, fresh dispatch checks and receipt timestamps. Host path tests: 11/11; dispatch rechecks: 9/9; receipt-time regressions: 6/6. |
+| UI inspection | The actual client was inspected in the offline browser fixture `budget-reservations`: recorded spend, remaining reservations, interrupted-state guidance and disabled reruns; 0 browser console errors. [Screenshot](../assets/workbench-budget-reservations.png). All amounts and executions are simulated. |
+| Full local suite | `npm test`: 1,129 tests, 1,126 passed, 0 failed, 3 skipped. Full logs are retained in the release archive. |
+| Dependency/client/docs checks | `pnpm install --frozen-lockfile --strict-peer-dependencies` passed; actual client build and `check:client` passed (988,427 bytes); README pairing/hashes and offline preview compilation passed. Formula content is unchanged. |
+| Windows/Linux CI | [Implementation matrix run](https://github.com/Alice-Marx/dsh-model-router/actions/runs/40003924460) on `4795ade7adbd2a3075e3d9fde29f70372b542c03`: Node 24 / ubuntu-latest **success**; Node 24 / windows-latest **success**. Both ran the complete suite, strict installation, actual build/check, preview compilation and package verification. The final documentation commit runs the same matrix again before publication. |
+| Package integrity | Local candidate archive: 75 files match raw Git blobs, including all 40 local runtime modules. Final `v0.24.0` commit and archive digests are recorded in the Release assets, which avoid embedding an archive checksum in a document inside that same archive. |
+| Public release | After tag/upload, the publication audit anonymously downloads the npm archive, GitHub Release page and every attached asset and compares bytes and registry integrity. The dated public-npm/public-github verification JSON files are retained with the release archive. Neither version metadata nor a pushed tag alone establishes complete publication. |
+
+## Boundaries and upgrade
+
+Reservations represent remaining local estimates, not actual billed charges or a hard provider cap. Final charges can exceed estimates, and provider bills remain authoritative. Unknown or incomplete usage is not assigned zero. Subscription reference costs remain separate from recorded API spending. Calendar accounting retains its existing package-level settlement granularity; quality-cascade attempts are not split into separate daily/monthly invoices.
+
+A normal completed, cancelled or budget-stopped executor releases its remaining reservation only after its cleanup settles; completed receipts remain chargeable. A Host crash or checkpoint failure does not prove the provider stopped or establish its final charge. The reservation and any unresolved fee evidence remain available for reconciliation. This release has no manual reconciliation/release control, no automatic call replay and no arbitrary timeout that makes an interrupted reservation free. Inspect the original task, retained worktree and provider bill before considering recovery; do not erase state to bypass accounting.
+
+Live job/progress handles remain in Host memory and do not survive a restart. Persistent package checkpoints and reservations survive successful state writes; they do not restore an active worker or provide one-click continuation. Confirmed dead-owner detection is conservative; an owner whose liveness is uncertain remains reserved.
+
+Required checkpoints are part of the managed execution paths. Arbitrary imports or external provider calls outside these paths are not brought under the router's budget accounting by this change. Deliverable correctness, real vendor access, account eligibility and settled charges are not established by offline fixtures or CI.
+
+No new real paid-provider or vendor CLI inference or installed-DSH end-to-end acceptance is claimed for this release. Prior execution evidence remains dated in the [0.20.0 report](0.20.0-validation.md). Fully quit Harness, including tray/Host processes, update the plugin, then restart. Back up state/profile data before migration or downgrade; older plugin versions cannot read schema v2 state.

package/docs/releases/0.25.0-validation.md

@@ -0,0 +1,41 @@
+# 0.25.0 release acceptance
+
+Date: 2026-10-24. Package: `@ljwei-stak/dsh-model-router@0.25.0`.
+
+Source acceptance: passed. Local tests and the actual Windows/Linux matrix below verify the implementation. The final tagged commit, archive digests and post-publication anonymous download checks are recorded separately in the dated release/archive evidence, so this document does not embed the checksum of its own containing archive.
+
+## Problems and resulting behavior
+
+- API and subscription execution need different units. API results retain monetary charges and budget reservations. Subscription results have a separate quantity ledger: calls, reported input/output/cache tokens, and unknown/incomplete-usage counts, with daily/monthly and provider/tool/model summaries.
+- Confirmed subscriptions are not refused solely because an API money budget is exhausted or an API price is missing. Execution metadata and ownership remain durable for recovery, while subscription work does not consume API monetary capacity. Unknown authentication or unsupported execution capabilities are not treated as proof of an available subscription.
+- Unverified CLI authentication is not labelled as a confirmed subscription. It receives conservative API monetary admission; the resulting amount stays unknown rather than treating a reported reference figure as a settled bill. A failed unknown-billing CLI pauses before starting an extra API call.
+- Any actual API call, including fallback from a subscription, must estimate its actual API route and pass the applicable confirmation and atomic budget reservation before dispatch. CLI calls using API credentials remain API-billed. API quality escalation and optional API reviewers continue to incur API costs.
+- Mixed execution retains subscription-attempt usage evidence alongside the API financial result. Mandatory attempt/package checkpoints preserve available evidence. Retry replacement and detailed-history retention do not erase prior charges or subscription quantities and do not count the same receipt twice.
+- The workbench separates API money and subscription usage in the budget page, history and execution preview. A missing token counter stays unknown; a reported zero stays zero. Partial observed counters remain visible, while incomplete usage is identified. Old Host summaries that lack quantity data are unavailable rather than shown as a zero token balance.
+- State schema v3 accepts readable v1/v2 history and retains old reference fields and protected execution state. Old reference dollars are not used as current subscription monetary statistics, and absent historical tokens cannot be reconstructed from them. Older Hosts reject v3 instead of silently discarding the new state.
+
+## Validation record
+
+| Check | Observed evidence |
+| --- | --- |
+| Independent subscription quantities | 13 new quantity/state tests pass: reported zero, partial/unknown counters, provider/tool/model grouping, calendar rollover, legacy migration, retry replacement and history eviction. |
+| Host admission and fallback | 11 new Host tests pass, including full/unknown API budgets with a subscription, missing subscription prices, API-only/manual/key CLI admission, fallback repricing, an independent plan consultation, unknown CLI billing and a real killed child process at API dispatch. |
+| Receipt persistence and cancellation | 12 new runtime receipt tests and 11 reservation tests pass. They cover mandatory subscription receipt writes before fallback, cancellation, storage failure, independent API/quantity evidence, concurrent admission, pending API crash recovery and subscription steps between API steps. |
+| Workbench UI | Actual client inspected in the offline browser `billing-split` simulation: separate API money/subscription quantities, provider/tool/model rows and unknown counters. Browser console errors: 0. [Quantity screenshot](../assets/workbench-subscription-usage.png). New UI tests: 10/10. Amounts, usage and executions are simulated. |
+| Complete local suite | `npm test`: 1,186 tests; 1,183 pass, 0 fail, 3 environment skips. Full logs are retained in the release archive. |
+| Dependencies/client/docs | Strict frozen pnpm installation passed. Actual client build/check passed (986,763 bytes); syntax simplification retains readable names/lines and the existing under-1-MB bundle guard. README pairing/hashes and offline preview compile passed. Formula contents are unchanged. |
+| Windows/Linux CI | [Implementation matrix run](https://github.com/Alice-Marx/dsh-model-router/actions/runs/40082683345) on `2912b5b3bdebdd49ea7648bf87f2e252d4349c6d`: Node 24 / ubuntu-latest **success**; Node 24 / windows-latest **success**. Both ran strict installation, the complete suite, actual build/check, preview compilation and package verification. The final documentation commit runs the same matrix again before publication. |
+| Package/source integrity | Local candidate archive: 79 files match raw Git blobs, including all 42 local runtime modules. Final `v0.25.0` commit and archive digests are recorded in Release assets. The complete source ZIP is constructed from raw Git blobs and separately checked byte for byte. |
+| Public distribution | After tag/upload, the publication audit anonymously downloads the npm archive, GitHub Release page and every attached asset and compares bytes and registry integrity. Dated public-npm/public-github verification JSON files are retained with the release archive. Neither version metadata nor a pushed tag alone establishes complete publication. |
+
+## Boundaries and upgrade
+
+Subscription token counts are observed local usage, not a vendor allowance or quota meter. Different vendors may use different windows, token/cache rules or other charging units. The plugin does not infer a total allowance, remaining quota or percentage from API-equivalent prices or reported tokens. Quota exhaustion/reset information is only as reliable as vendor output and existing detection rules; a cooldown does not prove actual account eligibility.
+
+API estimates are not a hard provider billing cap, and the provider bill remains authoritative. A valid API zero applies to the observed attempt, not to earlier unknown attempts. A CLI can use its own configured API credentials even though it is launched as an official tool. Execution previews separate monetary API estimates from subscription token estimates; predicted quantities are not observed usage.
+
+Historical reference-dollar fields may remain for compatibility. Unknown old token usage remains unknown; already discarded records cannot be reconstructed. Existing package-level settlement/calendar granularity remains; this change does not claim independently settled provider invoices for every internal quality attempt.
+
+Crash or storage-failure recovery preserves unresolved execution evidence. There is no automatic paid replay, arbitrary timeout that clears live ownership, or new manual reconciliation/release control. Inspect the original task, retained worktree and provider usage/bill before recovery. Live progress handles remain in Host memory and are not restored as live workers after restart.
+
+No new real paid-provider/vendor CLI inference or installed-DSH end-to-end acceptance is claimed for this release. Prior real execution evidence remains dated in the [0.20.0 report](0.20.0-validation.md). Fully exit Harness, including tray and all Host processes, before updating; restart after installation. Back up state/profile data before migration or downgrade. Older plugin versions cannot read schema v3 state.