@ljwei-stak/dsh-model-router 0.24.0 → 0.25.1

package/.dsh-plugin/shared/task-executors.mjs

@@ -43,6 +43,24 @@ const BASE_ENV_KEYS = Object.freeze([
 ])
 
 const READ_ONLY_INSTRUCTION = 'Read the task supplied on standard input. Answer in the task language. Do not modify files.'
+const executionBoundaryFailure = error => ['ROUTER_CHECKPOINT_FAILED', 'ROUTER_BUDGET_CHANGED'].includes(error?.code)
+const usageFields = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens']
+
+/** Subscription evidence contains reported usage only, never prices or secrets. */
+function subscriptionReceipt(result, { provider, model, toolId = null, channel = 'harness-llm', now = Date.now } = {}) {
+  const usage = result?.usage && typeof result.usage === 'object' && !Array.isArray(result.usage)
+    ? Object.fromEntries(usageFields.filter(key => typeof result.usage[key] === 'number'
+      && Number.isFinite(result.usage[key]) && result.usage[key] >= 0).map(key => [key, result.usage[key]])) : null
+  const notStarted = result?.notStarted === true || result?.blocked === true
+  const incomplete = result?.usageIncomplete === true || !usage
+    || !['inputTokens', 'outputTokens'].every(key => Object.hasOwn(usage, key))
+    || usageFields.some(key => result?.usage?.[key] !== undefined && !Object.hasOwn(usage ?? {}, key))
+  return { provider: String(provider ?? ''), model: String(reportedCliModel(result?.actualModel ?? result?.reportedModel) ?? model ?? ''),
+    toolId, channel, usage: usage && Object.keys(usage).length ? usage : null,
+    ...(incomplete ? { usageIncomplete: true } : {}), ...(notStarted ? { notStarted: true } : {}),
+    finishedAt: typeof result?.finishedAt === 'number' && Number.isFinite(result.finishedAt)
+      && result.finishedAt >= 0 ? result.finishedAt : now() }
+}
 
 function additionalApiFields(value) {
   if (!value || typeof value !== 'object') return {}
@@ -409,6 +427,7 @@ export function looksLikeLoginFailure(detail) {
 }
 
 const count = value => Number.isFinite(value) && value >= 0 ? Math.round(value) : 0
+const knownCount = value => typeof value === 'number' && Number.isFinite(value) && value >= 0
 
 /** Token usage reported by the CLI, in the Harness TokenUsage shape (disjoint cache counts). */
 export function usageFromOutput(format, stdout = '') {
@@ -422,11 +441,14 @@ export function usageFromOutput(format, stdout = '') {
         ? Object.keys(result.modelUsage) : []
       return {
         usage: {
-          inputTokens: count(usage.input_tokens),
-          outputTokens: count(usage.output_tokens),
+          ...(knownCount(usage.input_tokens) ? { inputTokens: count(usage.input_tokens) } : {}),
+          ...(knownCount(usage.output_tokens) ? { outputTokens: count(usage.output_tokens) } : {}),
           cacheReadTokens: count(usage.cache_read_input_tokens),
           cacheWriteTokens: count(usage.cache_creation_input_tokens),
         },
+        ...(!knownCount(usage.input_tokens) || !knownCount(usage.output_tokens)
+          || ['cache_read_input_tokens', 'cache_creation_input_tokens'].some(key => usage[key] !== undefined && !knownCount(usage[key]))
+          ? { usageIncomplete: true } : {}),
         ...(Number.isFinite(reported) && reported >= 0 ? { reportedCostUsd: reported } : {}),
         ...(models.length === 1 && /^[A-Za-z0-9][A-Za-z0-9._:/\[\]-]{0,199}$/.test(models[0]) ? { reportedModel: models[0] } : {}),
       }
@@ -436,24 +458,33 @@ export function usageFromOutput(format, stdout = '') {
       if (!completed) return null
       const cached = count(completed.usage.cached_input_tokens)
       return { usage: {
-        inputTokens: Math.max(0, count(completed.usage.input_tokens) - cached),
-        outputTokens: count(completed.usage.output_tokens),
+        ...(knownCount(completed.usage.input_tokens) ? { inputTokens: Math.max(0, count(completed.usage.input_tokens) - cached) } : {}),
+        ...(knownCount(completed.usage.output_tokens) ? { outputTokens: count(completed.usage.output_tokens) } : {}),
         cacheReadTokens: cached,
         cacheWriteTokens: 0,
-      } }
+      }, ...(!knownCount(completed.usage.input_tokens) || !knownCount(completed.usage.output_tokens)
+        || completed.usage.cached_input_tokens !== undefined && (!knownCount(completed.usage.cached_input_tokens)
+          || completed.usage.cached_input_tokens > completed.usage.input_tokens) ? { usageIncomplete: true } : {}) }
     }
     if (format === 'gemini-json') {
       const models = JSON.parse(stdout)?.stats?.models
-      if (!models || typeof models !== 'object') return null
+      if (!models || typeof models !== 'object' || Array.isArray(models) || !Object.keys(models).length) return null
       let input = 0
       let output = 0
       let cached = 0
+      let inputKnown = true, outputKnown = true, incomplete = false
       for (const entry of Object.values(models)) {
+        inputKnown &&= knownCount(entry?.tokens?.prompt)
+        outputKnown &&= knownCount(entry?.tokens?.candidates)
+        incomplete ||= entry?.tokens?.cached !== undefined && (!knownCount(entry.tokens.cached)
+          || entry.tokens.cached > entry.tokens.prompt)
         input += count(entry?.tokens?.prompt)
         output += count(entry?.tokens?.candidates)
         cached += count(entry?.tokens?.cached)
       }
-      return { usage: { inputTokens: Math.max(0, input - cached), outputTokens: output, cacheReadTokens: cached, cacheWriteTokens: 0 } }
+      return { usage: { ...(inputKnown ? { inputTokens: Math.max(0, input - cached) } : {}),
+        ...(outputKnown ? { outputTokens: output } : {}), cacheReadTokens: cached, cacheWriteTokens: 0 },
+        ...(!inputKnown || !outputKnown || incomplete ? { usageIncomplete: true } : {}) }
     }
   } catch { /* usage is optional */ }
   return null
@@ -621,7 +652,7 @@ function captureProcess(spawnImpl, file, args, { cwd, env, stdin, timeoutMs, sig
   })
 }
 
-async function useApi(apiFallback, { route, task, signal, reason, adapter, preference, exitCode = null, timedOut = false, detail = '', raw = '', skipped = false, attempted = false }) {
+async function useApi(apiFallback, { route, task, signal, reason, adapter, preference, exitCode = null, timedOut = false, detail = '', raw = '', skipped = false, attempted = false, subscriptionResult = null }) {
   const provider = String(route?.provider ?? '')
   const model = String(route?.model ?? '')
   const fallback = {
@@ -637,7 +668,7 @@ async function useApi(apiFallback, { route, task, signal, reason, adapter, prefe
     }
   }
   try {
-    const api = await apiFallback({ route, task, signal, reason, detail, raw: String(raw ?? '').slice(-40_000), toolId: adapter?.id ?? null, attempted, timedOut, exitCode })
+    const api = await apiFallback({ route, task, signal, reason, detail, raw: String(raw ?? '').slice(-40_000), toolId: adapter?.id ?? null, attempted, timedOut, exitCode, subscriptionResult })
     // A billing-aware fallback can pause the step for the user's decision.
     if (api?.paused) {
       return {
@@ -646,6 +677,7 @@ async function useApi(apiFallback, { route, task, signal, reason, adapter, prefe
         pause: { ...api.pause, ...(detail ? { detail } : {}), ...(fallback.loginRequired ? { loginRequired: true } : {}) },
         ...reasoningExecutionFields(api),
         ...additionalApiFields(api),
+        ...(api?.billing ? { billing: api.billing } : {}),
         error: api.error,
       }
     }
@@ -674,6 +706,7 @@ async function useApi(apiFallback, { route, task, signal, reason, adapter, prefe
       error: api?.ok === true && answer.trim() ? undefined : (api?.error || reason),
     }
   } catch (error) {
+    if (executionBoundaryFailure(error)) throw error
     if (signal?.aborted) {
       return {
         ok: false, provider, model, preference, channel: 'harness-llm', toolId: adapter?.id ?? null,
@@ -833,6 +866,8 @@ export async function executeAssignedTask({
       return useApi(apiFallback, {
         route, task: prompt, signal, adapter, preference, exitCode: verified.exitCode ?? null,
         timedOut: verified.status === 'timed-out', attempted: true,
+        subscriptionResult: { usage: verified.usage, usageIncomplete: verified.usageIncomplete,
+          notStarted: verified.notStarted === true, actualModel: verified.actualModel, reportedModel: verified.reportedModel },
         reason: verified.error || verified.reason || '官方 CLI 执行失败，已回退模型目录 API。',
         detail: redactDiagnostic(verifiedDiagnostic(verified), childEnvironment(adapter, credentials, credentialMode).secret),
         raw: [verified.error, verified.reason, verified.detail, verified.stderrTail, verified.stdoutTail].filter(item => typeof item === 'string').join('\n'),
@@ -861,7 +896,7 @@ export async function executeAssignedTask({
         : probe.timedOut ? `${adapter.label} 检测超时，已回退模型目录 API。`
           : `${adapter.label} 无法运行，已回退模型目录 API。`
     if (probe.cancelled) {
-      return { ok: false, provider, model, preference, channel: 'official-cli', toolId: adapter.id, answer: '', fallback: null, timedOut: false, exitCode: null, error: reason, cancelled: true }
+      return { ok: false, provider, model, preference, channel: 'official-cli', toolId: adapter.id, answer: '', fallback: null, timedOut: false, exitCode: null, error: reason, cancelled: true, notStarted: true }
     }
     return useApi(apiFallback, { route, task: prompt, signal, adapter, preference, reason })
   }
@@ -871,11 +906,14 @@ export async function executeAssignedTask({
     ...(Number.isSafeInteger(stopGraceMs) && stopGraceMs >= 10 && stopGraceMs <= STOP_GRACE_MS ? { stopGraceMs } : {}),
   })
   if (run.cancelled) {
-    return { ok: false, provider, model, preference, channel: 'official-cli', toolId: adapter.id, answer: '', fallback: null, timedOut: false, exitCode: run.exitCode, error: '执行已取消。', cancelled: true }
+    const usage = usageFromOutput(adapter.format, run.stdout)
+    return { ok: false, provider, model, preference, channel: 'official-cli', toolId: adapter.id, answer: '', fallback: null, timedOut: false, exitCode: run.exitCode, error: '执行已取消。', cancelled: true,
+      credentialSource, ...(usage?.usage ? { usage: usage.usage } : {}), ...(usage?.usageIncomplete ? { usageIncomplete: true } : {}) }
   }
   if (!run.ok) {
     return useApi(apiFallback, {
       route, task: prompt, signal, adapter, preference, exitCode: run.exitCode, timedOut: run.timedOut, attempted: true,
+      subscriptionResult: usageFromOutput(adapter.format, run.stdout),
       reason: run.timedOut ? `${adapter.label} 执行超时，已回退模型目录 API。`
         : run.outputLimit ? `${adapter.label} 输出超过上限，已回退模型目录 API。`
           : `${adapter.label} 执行失败，已回退模型目录 API。`,
@@ -889,6 +927,7 @@ export async function executeAssignedTask({
   if (!parsed.ok) {
     return useApi(apiFallback, {
       route, task: prompt, signal, adapter, preference, exitCode: run.exitCode, attempted: true,
+      subscriptionResult: usageFromOutput(adapter.format, run.stdout),
       reason: `${parsed.error} 已回退模型目录 API。`,
       detail: failureDetail(adapter.format, run.stdout, run.stderr, secret),
       raw: `${run.stdout.slice(-20_000)}\n${run.stderr.slice(-20_000)}`,
@@ -896,7 +935,8 @@ export async function executeAssignedTask({
   }
   const answer = redact(parsed.answer, secret)
   if (!answer.trim()) {
-    return useApi(apiFallback, { route, task: prompt, signal, adapter, preference, exitCode: run.exitCode, attempted: true, reason: '官方 CLI 没有返回文本，已回退模型目录 API。' })
+    return useApi(apiFallback, { route, task: prompt, signal, adapter, preference, exitCode: run.exitCode, attempted: true,
+      subscriptionResult: usageFromOutput(adapter.format, run.stdout), reason: '官方 CLI 没有返回文本，已回退模型目录 API。' })
   }
   return officialSuccess({
     route, adapter, preference, answer, exitCode: run.exitCode,
@@ -954,14 +994,26 @@ const failureSummary = text => `${String(text ?? '').replace(/，?已(?:回退
  * - subscription-only: never fall back to an API key.
  * - api-only: never use the subscription.
  */
-export async function executeRouteWithBilling({ route, billing = null, apiFallback, ...options } = {}) {
+export async function executeRouteWithBilling({ route, billing = null, apiFallback, onSubscriptionResult, ...options } = {}) {
   const plan = billingPlan(route, billing?.routes ?? [])
+  const subscriptionAttempts = []
+  const recordSubscription = async receipt => {
+    // This executor attempts the subscription once, then may use its API
+    // fallback. Keep a bounded vector so unrelated result fields cannot grow it.
+    if (subscriptionAttempts.length >= 2) throw new Error('订阅尝试证据超过本步上限。')
+    subscriptionAttempts.push(receipt)
+    const event = { ...structuredClone(receipt), billing: 'subscription', subscriptionAttempts: structuredClone(subscriptionAttempts) }
+    await awaitExecutionCheckpoint(onSubscriptionResult, event,
+      () => ({ status: 'failed', packages: [{ ...event, ok: false, ran: !receipt.notStarted }] }), 'subscription-result')
+  }
   // Every result names the billing mode it ran under, whichever branch produced it.
-  const result = await routeWithBilling(plan, { route, billing, apiFallback, ...options })
-  return { ...result, billingMode: result?.billingMode ?? plan.mode }
+  const result = await routeWithBilling(plan, { route, billing, apiFallback, ...options, onSubscriptionResult: recordSubscription })
+  return { ...result, billingMode: result?.billingMode ?? plan.mode,
+    ...(subscriptionAttempts.length ? { subscriptionAttempts,
+      ...(result?.billing ? {} : { billing: 'subscription' }) } : {}) }
 }
 
-async function routeWithBilling(plan, { route, billing = null, apiFallback, ...options } = {}) {
+async function routeWithBilling(plan, { route, billing = null, apiFallback, onSubscriptionResult, ...options } = {}) {
   if (!billing) return executeAssignedTask({ ...options, route, apiFallback })
   const now = typeof billing.now === 'function' ? billing.now : Date.now
   const sub = plan.subscription
@@ -972,7 +1024,7 @@ async function routeWithBilling(plan, { route, billing = null, apiFallback, ...o
   const base = { provider, model, billingMode: plan.mode }
   const refuse = (error, extra = {}) => ({
     ok: false, ...base, preference: executionPreference(route), channel: sub?.kind === 'plan-key' ? 'harness-llm' : 'official-cli',
-    toolId: sub?.toolId ?? null, answer: '', fallback: null, error, ...extra,
+    toolId: sub?.toolId ?? null, answer: '', fallback: null, notStarted: true, error, ...extra,
   })
   const viaApi = async (reason, note, skipped = false) => {
     if (!apiRoute || (sub?.kind === 'plan-key' && apiRoute.provider === sub.route.provider && apiRoute.model === sub.route.model)) {
@@ -1016,11 +1068,16 @@ async function routeWithBilling(plan, { route, billing = null, apiFallback, ...o
   }
 
   if (sub.kind === 'plan-key') {
+    if (typeof apiFallback !== 'function') return refuse('编程套餐执行器不可用，此步骤未启动。', { notStarted: true, billing: 'subscription' })
     const reasoningRoute = routeForReasoningSwitch(route, sub.route)
     const originalEffort = typeof route?.reasoningEffort === 'string' && route.reasoningEffort ? route.reasoningEffort : null
     let attempt
     try { attempt = await apiFallback({ route: reasoningRoute, task: options.task, signal: options.signal, reason: '编程套餐（订阅）', subscription: true }) }
-    catch (error) { attempt = { ok: false, error: String(error?.message ?? error) } }
+    catch (error) {
+      if (executionBoundaryFailure(error)) throw error
+      attempt = { ok: false, error: String(error?.message ?? error) }
+    }
+    await onSubscriptionResult(subscriptionReceipt(attempt, { ...sub.route, now }))
     const droppedEffort = originalEffort && reasoningRoute.reasoningEffort !== originalEffort ? originalEffort : null
     if (attempt?.ok === true && String(attempt.answer ?? '').trim()) {
       return {
@@ -1083,8 +1140,15 @@ async function routeWithBilling(plan, { route, billing = null, apiFallback, ...o
     // No subscription login: the existing CLI-with-key / catalog API behaviour.
     return executeAssignedTask({ ...options, route, apiFallback })
   }
+  const confirmedSubscription = retrySubscription || login === 'subscription' || plan.mode === 'subscription-only'
   if (retrySubscription) options = { ...options, skipOfficial: null }
   const guarded = async args => {
+    if (args?.attempted === true && !confirmedSubscription) {
+      const pause = pauseFor('CLI 计费方式尚未核对，已暂停，未启动额外 API 调用。', '请先体检确认账号订阅或 API Key，再选择重试方式。')
+      return { ok: false, paused: true, billing: 'unknown', pause, error: pause.reason }
+    }
+    if (args?.attempted === true && confirmedSubscription) await onSubscriptionResult(subscriptionReceipt(args.subscriptionResult,
+      { provider, model, toolId: args.toolId ?? sub.toolId, channel: 'official-cli', now }))
     const vendor = vendorKey({ toolId: args?.toolId ?? sub.toolId })
     const info = classify(`${args?.detail ?? ''}
 ${args?.raw ?? ''}`, vendor)
@@ -1112,13 +1176,16 @@ ${args?.raw ?? ''}`, vendor)
       const pause = pauseFor(summary, args?.detail ?? '', { timedOut: args?.timedOut === true, exitCode: args?.exitCode ?? null })
       return { ok: false, paused: true, pause, error: pause.reason }
     }
-    return apiFallback(args)
+    return { ...await apiFallback(args), billing: 'api' }
   }
   const result = await executeAssignedTask({ ...options, route, apiFallback: guarded, credentialMode: 'session-only' })
+  if (confirmedSubscription && result.channel === 'official-cli' && (result.ok === true || result.cancelled && !result.notStarted)) {
+    await onSubscriptionResult(subscriptionReceipt(result, { provider, model, toolId: sub.toolId, channel: 'official-cli', now }))
+  }
   return {
     ...result,
     billingMode: plan.mode,
-    ...(result.ok && result.channel === 'official-cli' ? { billing: 'subscription' } : {}),
+    ...(result.channel === 'official-cli' && !result.billing ? { billing: confirmedSubscription ? 'subscription' : 'unknown' } : {}),
   }
 }
 
@@ -1233,6 +1300,7 @@ export async function observeExecutionProgress(hook, value) {
 export async function awaitExecutionCheckpoint(hook, value, partial, stage) {
   if (typeof hook !== 'function') return
   try { await hook(value) } catch (cause) {
+    if (executionBoundaryFailure(cause) && cause.execution) throw cause
     const budgetChanged = cause?.code === 'ROUTER_BUDGET_CHANGED'
     const error = new Error(budgetChanged ? String(cause.message) : `执行检查点保存失败：${String(cause?.message ?? cause)}`, { cause })
     error.code = budgetChanged ? 'ROUTER_BUDGET_CHANGED' : 'ROUTER_CHECKPOINT_FAILED'
@@ -1324,7 +1392,7 @@ async function runManualTool(target, prompt, options) {
  */
 async function runPackages({ packages, task, routingBypassed, routes, previous = [], targets = null, overrides = {}, choices = {}, options }) {
   const routeList = Array.isArray(routes) ? routes : []
-  const { credentialsFor, onPackageStart, onPackage, onStage, onCheckpointStart, onCheckpointResult, billing, ...runOptions } = options
+  const { credentialsFor, onPackageStart, onPackage, onStage, onCheckpointStart, onCheckpointResult, onSubscriptionResult, billing, ...runOptions } = options
   await observeExecutionProgress(onStage, 'preparing')
   const effectivePackages = checkedPackageSelections(packages, routeList, overrides, runOptions.runVerified, targets)
   const results = []
@@ -1406,6 +1474,11 @@ async function runPackages({ packages, task, routingBypassed, routes, previous =
     else {
       result = await executeRouteWithBilling({
         ...runOptions,
+        onSubscriptionResult: async event => {
+          event.id = item.id
+          await awaitExecutionCheckpoint(onSubscriptionResult, event,
+            () => ({ ...partial(), packages: [...results, { ...event, ok: false, ran: !event.notStarted }] }), 'subscription-result')
+        },
         billing: billing ? { ...billing, routes: billing.routes ?? routeList, ...(choices[item.id] ? { choice: choices[item.id] } : {}) } : null,
         credentials, route, task: promptText,
       })

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.25.1 — 2026-10-24
+
+- Add DeepSeek Harness Desktop 0.2.1-rc.3 to the exact Host peer range while retaining the existing 0.2.0-rc.1, 0.2.0-rc.2 and 0.2.1-rc.2 declarations.
+- Pin the published 0.2.1-rc.3 SDK dependency graph for source installation and regenerate the Desktop client against that SDK. Compatibility validation covers the plugin's Host/client contracts in addition to the version declarations.
+- Refresh current installation examples and workbench documentation for 0.25.1. Existing API monetary budgets, independent subscription usage, progress/cancellation and schema v3 state remain in place.
+
+Validation evidence and limits are tracked in the [0.25.1 acceptance report](docs/releases/0.25.1-validation.md). Offline SDK/build tests do not establish installed-Desktop operation or real vendor inference; earlier execution evidence retains its original version and date.
+
+## 0.25.0 — 2026-10-24
+
+- Separate API financial accounting from subscription usage. API costs and API reservations govern monetary budgets; subscriptions track calls and reported input/output/cache tokens, with incomplete or missing usage retained as unknown.
+- Keep confirmed subscription execution independent of exhausted API budgets or missing API prices. Before an actual API call or subscription-to-API fallback, estimate the actual API route and acquire the applicable confirmation and atomic reservation. A CLI using an API key remains API-billed.
+- Preserve subscription-attempt receipts alongside API fallback results and retain both ledgers across retry replacement and history trimming. Old reference-dollar fields remain readable without converting them into current subscription money or fabricated token counts.
+- Show API money and subscription quantities separately in the workbench, execution preview and history. Subscription tokens do not imply vendor allowance, remaining quota or percentage. Additional API quality/review calls still incur API charges.
+- Upgrade persistent state to schema v3 while migrating readable v1/v2 histories and protected execution state. Fully stop all Hosts before updating and keep state backups before downgrading.
+
+Final validation and release evidence are tracked in the [0.25.0 acceptance report](docs/releases/0.25.0-validation.md). No new real vendor inference or installed-DSH end-to-end claim is made by these changes.
+
 ## 0.24.0 — 2026-10-24
 
 - Reserve remaining execution estimates in shared persistent state before admission. Daily/monthly checks account for recorded API spending plus other active or interrupted reservations, preventing concurrent tasks from independently admitting the same estimated capacity. Unknown estimates or unresolved costs under a finite budget require explicit confirmation.

package/README.i18n.yaml

@@ -1,4 +1,4 @@
 # README translation pairing for this repository.
 # Reviewed together; Git blob hashes identify the exact synchronized texts.
-README.md: 3829f616ecffbfbc4d1793d4e3f2bc4eac6c9fc0
-README.zh.md: 7505f5c1dad20079be2a9bb47a40fd70b5d2bdf4
+README.md: 8ed6d21e04be401519e21fe6b5d6fd04832e9e4a
+README.zh.md: f2052443f9569bbd7311abb15c416472fdd41899

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.24.0** (`@ljwei-stak/dsh-model-router`). Concurrent executions now reserve remaining estimated budget in shared persistent state. Required checkpoints save each package before launch and after its receipt; interrupted executions retain their budget hold and unresolved cost evidence. The workbench separates recorded spending from reserved estimates. Windows/Linux Node 24 CI runs the full test, client build and package-integrity checks. 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.1** (`@ljwei-stak/dsh-model-router`). This compatibility update builds against the **0.2.1-rc.3** SDK and adds that Host version to the existing peer range. 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 covers **DeepSeek Harness Desktop 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2 / 0.2.1-rc.3**, 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).
 
@@ -27,26 +27,26 @@ Both README versions describe the same interfaces, formulas, defaults and limits
 **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.24.0
+dsh plugin --profile web add @ljwei-stak/dsh-model-router@0.25.1
 ```
 
 **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.24.0
+dsh plugin --profile desktop add @ljwei-stak/dsh-model-router@0.25.1
 ```
 
 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.24.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).
+**Package and entry point:** [`@ljwei-stak/dsh-model-router@0.25.1` 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.24.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.24.0 acceptance report](docs/releases/0.24.0-validation.md) for budget reservations, checkpoints 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.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.25.0 acceptance report](docs/releases/0.25.0-validation.md) for API/subscription separation and checkpoints, and the [0.25.1 acceptance report](docs/releases/0.25.1-validation.md) for SDK compatibility 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.
 
-**Compatibility:** Declared host support is DeepSeek Harness Desktop **0.2.0-rc.1**, **0.2.0-rc.2**, and **0.2.1-rc.2**. Node.js **>=22.19** and pnpm **10.34.6** are source development/build requirements, not plugin runtime prerequisites. Compatibility beyond the declared host versions is not claimed.
+**Compatibility:** Declared host support is DeepSeek Harness Desktop **0.2.0-rc.1**, **0.2.0-rc.2**, **0.2.1-rc.2**, and **0.2.1-rc.3**. Source builds pin the published **0.2.1-rc.3** SDK packages; retaining an older peer declaration does not turn offline tests into installed-Desktop acceptance. Node.js **>=22.19** and pnpm **10.34.6** are source development/build requirements, not plugin runtime prerequisites. Compatibility beyond the declared host versions is not claimed.
 
 **Contents:** [Quick evaluation](#quick-evaluation) · [Capabilities](#capabilities) · [Install](#install) · [Workbench](#workbench) · [Architecture](#architecture) · [Session tools](#session-tools) · [Official tools](#official-tools) · [Team lifecycle](#team-lifecycle) · [Costs](#costs) · [Routing algorithm](#routing) · [Data](#data) · [Development](#development) · [Troubleshooting](#troubleshooting)
 
@@ -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 checks include persistent concurrent budget reservations; recorded spending and remaining estimates are separate. Subscription-first routing, quota cooldown and explicit handling of other subscription failures remain available. |
+| 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.24.0
+@ljwei-stak/dsh-model-router@0.25.1
 ```
 
-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.24.0** 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.1** 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.24.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.
+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.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.
 
 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.
 
@@ -351,18 +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. Admission atomically checks recorded API spending plus other executions' remaining reservations in the same DSH_HOME, then reserves the new execution. Each saved receipt replaces its estimate with actual accounting; remaining holds are released only after the executor settles. Over-budget routing can try the economy preset or pause for confirmation. A finite daily/monthly limit with unknown prices, unresolved actual costs or unknown reservations requires explicit confirmation. Each later paid call rechecks fresh actual spending and remaining reservations. If an earlier charge exceeds its estimate or becomes unknown under a finite budget, later calls pause. A budget stop retains completed receipts and releases unused reservations after worker cleanup; crash or storage failures retain their holds. These local estimates do not establish 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. A subscription-to-API route change must pass a fresh estimate and reservation check for that actual API route; a missing price or exceeded budget stops the call. 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
@@ -373,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>
 
@@ -452,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, 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.
+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. State schema v2 preserves execution ownership, reservations and checkpoints, and upgrades readable v1 state without discarding its ledger. Older plugin versions reject v2 state; fully stop every Host process before upgrading and back up state before any downgrade. 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>
 
@@ -496,7 +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 budget admission, remaining reservations, mandatory checkpoints and interrupted-owner evidence. |
+| `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. |
@@ -532,13 +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 v2 contains protected reservations. Restore a compatible version; do not erase the ledger to bypass its checks. |
+| 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. |