@ljwei-stak/dsh-model-router 0.16.0 → 0.16.2

package/.dsh-plugin/shared/official-tools-runtime.mjs

@@ -7,6 +7,8 @@
  * a package name, executable or argument. Installs are serialized (npm global
  * state must not interleave), output is kept as a bounded tail, and success is
  * always confirmed by a fresh probe rather than the installer's exit code.
+ * When a newer release is known, a probe that is still older fails the job
+ * instead of reporting success.
  */
 import { spawn } from 'node:child_process'
 import { mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'
@@ -15,6 +17,7 @@ import { getOfficialTool, installCommandLine, OFFICIAL_TOOLS } from './official-
 import { discoverZCodeBundle, unverifiedZCodeInstalls } from './zcode-bundle.mjs'
 import { openZCodeInstaller } from './zcode-installer.mjs'
 import { compareReleaseVersions, latestVersions } from './latest-versions.mjs'
+import { versionStillOlder } from './version-order.mjs'
 
 const PROBE_TIMEOUT_MS = 8_000
 const INSTALL_TIMEOUT_MS = 900_000
@@ -30,6 +33,44 @@ const probeCache = new Map()
 const PROBE_CACHE_MS = 60_000
 const installJobs = new Map()
 let installChain = Promise.resolve()
+const CLAUDE_UPDATE_TIMEOUT_MS = 180_000
+
+/** Non-interactive updater for a native Claude Code install. npm does not move that copy. */
+export const CLAUDE_UPDATE_ARGS = Object.freeze(['update'])
+
+/**
+ * Quote a fixed registry command for `shell: true`.
+ * Node concatenates shell arguments without escaping; Windows cmd would otherwise
+ * split on characters inside package specs such as `@scope/pkg@latest`.
+ */
+export function shellCommandLine(executable, args, platform = process.platform) {
+  const quote = value => {
+    const text = String(value)
+    if (text.includes('\0') || /[\r\n]/.test(text)) throw new Error('命令参数含有非法字符。')
+    if (platform === 'win32') return `"${text.replace(/"/g, '""')}"`
+    return `'${text.replace(/'/g, `'"'"'`)}'`
+  }
+  return [executable, ...(args ?? [])].map(quote).join(' ')
+}
+
+/** Visible failure when the installer exited cleanly but the probed copy is still older. */
+export function staleInstallMessage(label, installedVersion, latestVersion) {
+  return `${label} 的更新没有生效：检测到的版本仍是 ${installedVersion}，低于最新 ${latestVersion}。PATH 上可能有另一份更早的安装。请查看本行安装日志。`
+}
+
+/**
+ * Which updater to run. `order` is compareReleaseVersions(installed, latest):
+ * -1 older, 0 same, 1 newer, null when either version is unknown.
+ */
+export function officialUpdatePlan({ toolId, installed, order, platform }) {
+  if (installed && order === 1) return 'refuse-downgrade'
+  if (installed && order === 0) return 'already-current'
+  if (installed && order === -1 && toolId === 'claude-code') return 'claude-update-then-registry'
+  if (installed && (order === -1 || order === null) && toolId === 'minimax-code' && platform === 'win32') {
+    return 'minimax-official-installer'
+  }
+  return 'registry-install'
+}
 
 async function trustedExecutionReadiness(toolId) {
   // Loaded only during an install to avoid coupling fast version probes to
@@ -50,7 +91,10 @@ function runCapture(executable, args, { timeoutMs, onOutput, useShell = false, s
     let stopReason = null
     let child
     try {
-      child = spawn(executable, args, {
+      // One pre-quoted command string so Node's shell wrapper cannot split
+      // `@scope/pkg@latest`. PowerShell keeps useShell false and an args array.
+      const command = useShell ? shellCommandLine(executable, args) : executable
+      child = spawn(command, useShell ? [] : args, {
         stdio: ['ignore', 'pipe', 'pipe'],
         windowsHide: true,
         // Windows npm CLIs install as .cmd shims; only cmd.exe can execute
@@ -145,14 +189,14 @@ async function fetchOfficialMiniMaxInstaller(signal) {
   return officialMiniMaxInstaller(Buffer.concat(chunks))
 }
 
-async function runOfficialMiniMaxInstaller(job) {
+async function runOfficialMiniMaxInstaller(job, { reason } = {}) {
   let staging = null
   let prefixRoot = null
   try {
     job.finishedAt = null
     job.error = null
     job.phase = 'downloading-and-verifying'
-    pushLine(job, '— npm 原生依赖未就绪；改用 MiniMax 官方 Windows 安装脚本（安装最新版）—')
+    pushLine(job, reason || '— npm 原生依赖未就绪；改用 MiniMax 官方 Windows 安装脚本（安装最新版）—')
     const prefixResult = await runCapture('npm', ['config', 'get', 'prefix'], {
       timeoutMs: 5_000, useShell: true, signal: job.controller.signal,
     })
@@ -208,6 +252,10 @@ async function runOfficialMiniMaxInstaller(job) {
     if (!probe.installed || !readiness.ready) {
       throw new Error(`官方安装器完成，但执行入口未通过 npm registry 摘要核验：${readiness.reason ?? probe.detail}`)
     }
+    const latest = await latestVersions.lookup(job.tool).catch(() => null)
+    if (latest?.version && versionStillOlder(probe.version, latest.version)) {
+      throw new Error(staleInstallMessage(job.tool.label, probe.version, latest.version))
+    }
     job.status = 'succeeded'
     job.finishedAt = new Date().toISOString()
     pushLine(job, `— 官方安装器已完成，MiniMax Code ${probe.version ?? ''} 的执行入口已核验 —`)
@@ -444,6 +492,86 @@ export function startInstall(toolId) {
   return jobView(job)
 }
 
+function captureLines(job) {
+  return chunk => {
+    for (const line of String(chunk).split(/\r?\n/)) {
+      if (line.trim()) pushLine(job, line.slice(0, 500))
+    }
+  }
+}
+
+/** Mark the job succeeded only when the fresh probe is installed, ready, and not still older. */
+async function finishVerifiedInstall(job, probe) {
+  job.postInstallProbe = probe
+  if (job.cancelRequested) { markCancelled(job); return true }
+  if (!probe.installed) {
+    job.status = 'failed'
+    job.finishedAt = new Date().toISOString()
+    job.error = `安装命令已完成，但重探测失败：${probe.detail}`
+    return true
+  }
+  const latest = await latestVersions.lookup(job.tool).catch(() => null)
+  if (latest?.version && versionStillOlder(probe.version, latest.version)) {
+    failBecauseStillOlder(job, probe, latest.version)
+    return true
+  }
+  const readiness = await trustedExecutionReadiness(job.tool.id)
+  if (job.cancelRequested) { markCancelled(job); return true }
+  if (!readiness.ready) {
+    if (IS_WINDOWS && job.tool.id === 'minimax-code') {
+      await runOfficialMiniMaxInstaller(job)
+      return true
+    }
+    job.status = 'failed'
+    job.finishedAt = new Date().toISOString()
+    job.error = `安装命令和版本探测已成功，但官方执行入口未就绪：${readiness.reason}`
+    return true
+  }
+  job.status = 'succeeded'
+  job.finishedAt = new Date().toISOString()
+  pushLine(job, `— 已安装 ${job.tool.label} ${probe.version ?? ''}，官方执行入口已核验（新版本未经插件测试）—`)
+  return true
+}
+
+function failBecauseStillOlder(job, probe, latestVersion) {
+  job.postInstallProbe = probe
+  job.status = 'failed'
+  job.finishedAt = new Date().toISOString()
+  job.error = staleInstallMessage(job.tool.label, probe?.version, latestVersion)
+}
+
+/**
+ * Native Claude Code lives outside the npm prefix. `claude update` is the
+ * vendor's non-interactive updater; return true when the job is finished.
+ */
+async function tryClaudeUpdate(job, latestVersion) {
+  if (job.cancelRequested) { markCancelled(job); return true }
+  pushLine(job, '$ claude update')
+  job.phase = 'installing'
+  const outcome = await runCapture('claude', CLAUDE_UPDATE_ARGS, {
+    timeoutMs: CLAUDE_UPDATE_TIMEOUT_MS,
+    useShell: IS_WINDOWS,
+    signal: job.controller.signal,
+    onOutput: captureLines(job),
+  })
+  if (job.status !== 'running') return true
+  if (outcome.cancelled || job.cancelRequested) { markCancelled(job); return true }
+  if (!outcome.ok) {
+    pushLine(job, `— claude update 未完成（退出码 ${outcome.code ?? '信号终止'}），将继续尝试注册表安装 —`)
+    return false
+  }
+  await ensureNpmPrefixOnPath()
+  probeCache.delete(job.tool.id)
+  const probe = await probeToolWith(job.tool, defaultRunner)
+  if (job.cancelRequested) { markCancelled(job); return true }
+  if (latestVersion && versionStillOlder(probe.version, latestVersion)) {
+    job.postInstallProbe = probe
+    pushLine(job, `— claude update 已结束，但探测到的版本仍是 ${probe.version}，低于 ${latestVersion} —`)
+    return false
+  }
+  return finishVerifiedInstall(job, probe)
+}
+
 async function runInstallJob(manager, args, job) {
   if (job.status !== 'running') return
   job.phase = 'preflight'
@@ -452,10 +580,12 @@ async function runInstallJob(manager, args, job) {
   probeCache.delete(job.tool.id)
   const before = await probeToolWith(job.tool, defaultRunner)
   if (job.cancelRequested) { markCancelled(job); return }
+  let latest = null
+  let order = null
   if (before.installed) {
-    const latest = await latestVersions.lookup(job.tool, { fresh: true }).catch(() => null)
+    latest = await latestVersions.lookup(job.tool, { fresh: true }).catch(() => null)
     if (job.cancelRequested) { markCancelled(job); return }
-    const order = latest?.version ? compareReleaseVersions(before.version, latest.version) : null
+    order = latest?.version ? compareReleaseVersions(before.version, latest.version) : null
     if (order === 1) {
       job.status = 'failed'
       job.finishedAt = new Date().toISOString()
@@ -476,59 +606,76 @@ async function runInstallJob(manager, args, job) {
       pushLine(job, `— 已是最新版本 ${before.version}，但执行入口未就绪：${readiness.reason}；重新安装修复 —`)
     }
   }
+  const plan = officialUpdatePlan({
+    toolId: job.tool.id,
+    installed: before.installed === true,
+    order,
+    platform: process.platform,
+  })
+  let triedClaudeUpdate = false
+  if (plan === 'claude-update-then-registry') {
+    triedClaudeUpdate = true
+    const finished = await tryClaudeUpdate(job, latest?.version)
+    if (finished || job.status !== 'running') return
+  } else if (plan === 'minimax-official-installer') {
+    await runOfficialMiniMaxInstaller(job, {
+      reason: '— 已安装的 MiniMax Code 由官方安装目录接管；直接运行官方 Windows 安装脚本以更新到最新版 —',
+    })
+    return
+  }
   job.phase = 'installing'
   const outcome = await runCapture(manager, args, {
     timeoutMs: INSTALL_TIMEOUT_MS,
     useShell: IS_WINDOWS,
     signal: job.controller.signal,
-    onOutput: chunk => {
-      for (const line of chunk.split(/\r?\n/)) {
-        if (line.trim()) pushLine(job, line.slice(0, 500))
-      }
-    },
+    onOutput: captureLines(job),
   })
   if (job.status !== 'running') return
   if (outcome.cancelled || job.cancelRequested) { markCancelled(job); return }
-  job.finishedAt = new Date().toISOString()
   job.exitCode = outcome.code
   job.timedOut = outcome.timedOut
   if (outcome.timedOut) {
     job.status = 'failed'
+    job.finishedAt = new Date().toISOString()
     job.error = `安装超时（${INSTALL_TIMEOUT_MS / 1000}s），已终止。`
-  } else if (outcome.ok) {
-    job.phase = 'verifying'
-    await ensureNpmPrefixOnPath()
-    probeCache.delete(job.tool.id)
-    const probe = await probeToolWith(job.tool, defaultRunner)
-    if (job.cancelRequested) { markCancelled(job); return }
-    job.postInstallProbe = probe
-    if (!probe.installed) {
-      job.status = 'failed'
-      job.error = `安装命令已完成，但重探测失败：${probe.detail}`
-    } else {
-      const latest = await latestVersions.lookup(job.tool).catch(() => null)
-      if (latest?.version && compareReleaseVersions(probe.version, latest.version) === -1) {
-        pushLine(job, `— 注意：PATH 上的 ${job.tool.label} 仍是 ${probe.version}，低于最新 ${latest.version}；可能有另一份旧安装排在 PATH 前面 —`)
-      }
-      const readiness = await trustedExecutionReadiness(job.tool.id)
-      if (job.cancelRequested) { markCancelled(job); return }
-      if (!readiness.ready) {
-        if (IS_WINDOWS && job.tool.id === 'minimax-code') await runOfficialMiniMaxInstaller(job)
-        else {
-          job.status = 'failed'
-          job.error = `安装命令和版本探测已成功，但官方执行入口未就绪：${readiness.reason}`
-        }
-      } else {
-        job.status = 'succeeded'
-        pushLine(job, `— 已安装 ${job.tool.label} ${probe.version ?? ''}，官方执行入口已核验（新版本未经插件测试）—`)
-      }
+    return
+  }
+  if (!outcome.ok) {
+    if (IS_WINDOWS && job.tool.id === 'minimax-code') {
+      await runOfficialMiniMaxInstaller(job)
+      return
     }
-  } else if (IS_WINDOWS && job.tool.id === 'minimax-code') {
-    await runOfficialMiniMaxInstaller(job)
-  } else {
     job.status = 'failed'
+    job.finishedAt = new Date().toISOString()
     job.error = `安装命令失败（退出码 ${outcome.code ?? '信号终止'}）。${outcome.stderr.split('\n').find(Boolean)?.slice(0, 200) ?? ''}`
+    return
+  }
+  job.phase = 'verifying'
+  await ensureNpmPrefixOnPath()
+  probeCache.delete(job.tool.id)
+  const probe = await probeToolWith(job.tool, defaultRunner)
+  if (job.cancelRequested) { markCancelled(job); return }
+  job.postInstallProbe = probe
+  const latestAfter = (await latestVersions.lookup(job.tool).catch(() => null)) ?? latest
+  const stillOlder = Boolean(latestAfter?.version && versionStillOlder(probe.version, latestAfter.version))
+  if (stillOlder && job.tool.id === 'claude-code' && !triedClaudeUpdate) {
+    triedClaudeUpdate = true
+    const finished = await tryClaudeUpdate(job, latestAfter.version)
+    if (finished || job.status !== 'running') return
+    failBecauseStillOlder(job, job.postInstallProbe ?? probe, latestAfter.version)
+    return
+  }
+  if (stillOlder && IS_WINDOWS && job.tool.id === 'minimax-code') {
+    pushLine(job, `— npm 完成后 ${job.tool.label} 仍是 ${probe.version}，低于最新 ${latestAfter.version}；改用官方安装脚本 —`)
+    await runOfficialMiniMaxInstaller(job)
+    return
+  }
+  if (stillOlder) {
+    pushLine(job, `— 注意：PATH 上的 ${job.tool.label} 仍是 ${probe.version}，低于最新 ${latestAfter.version} —`)
+    failBecauseStillOlder(job, probe, latestAfter.version)
+    return
   }
+  await finishVerifiedInstall(job, probe)
 }
 
 async function runZCodeInstallJob(job) {

package/.dsh-plugin/shared/router-state.mjs

@@ -4,13 +4,15 @@
  * errors, cost, review and user ratings). One JSON file under the DSH home. Never stores keys.
  *
  * Several Host processes may share one DSH home, so every update takes a
- * lock file (`state.json.lock`, exclusive create; stale locks are broken),
+ * lock file (`state.json.lock`, exclusive create; only stale dead-owner locks
+ * are recovered). A busy live owner causes a bounded, explicit timeout,
  * re-reads the file, applies the change to the fresh copy and writes it back
  * atomically (temp file + rename). Reads re-read the file when its mtime or
  * size changed. A file that cannot be parsed is kept as
  * `state.json.corrupt-<timestamp>` and a notice is recorded instead of
  * silently discarding the history.
  */
+import { randomUUID } from 'node:crypto'
 import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
@@ -39,7 +41,7 @@ const LOCK_STALE_MS = 15_000
 const LOCK_TIMEOUT_MS = 10_000
 
 function emptyState() {
-  return { version: STATE_VERSION, onboarding: { completedAt: null }, health: null, quota: {}, authFailures: {}, runs: [], dynamicData: { liveBench: null, pricing: null, status: {}, revision: '' }, archivedSpending: sanitizeArchivedSpending(), notices: [], terminalSessions: [] }
+  return { version: STATE_VERSION, historyIncomplete: false, onboarding: { completedAt: null }, health: null, quota: {}, authFailures: {}, runs: [], dynamicData: { liveBench: null, pricing: null, status: {}, revision: '' }, archivedSpending: sanitizeArchivedSpending(), notices: [], terminalSessions: [] }
 }
 
 function sanitizeNotices(value) {
@@ -55,16 +57,62 @@ function retainRuns(state, maxRuns) {
   return state
 }
 
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const nonnegative = value => typeof value === 'number' && Number.isFinite(value) && value >= 0
+function invalidArchivedSpending(value) {
+  if (value === undefined || value === null) return false // old v1 files omit it
+  if (!record(value)) return true
+  for (const [field, pattern] of [['days', /^\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])$/u],
+    ['months', /^\d{4}-(?:0[1-9]|1[0-2])$/u]]) {
+    if (value[field] === undefined) continue
+    if (!record(value[field])) return true
+    for (const [key, totals] of Object.entries(value[field])) {
+      if (!pattern.test(key) || !record(totals)) return true
+      if (['costUsd', 'unknown', 'subscriptionUsd', 'subscriptionRuns'].some(name => totals[name] !== undefined
+        && (!nonnegative(totals[name]) || (['unknown', 'subscriptionRuns'].includes(name) && !Number.isInteger(totals[name]))))) return true
+    }
+  }
+  return false
+}
+
+function invalidRunSpending(run) {
+  if (!record(run) || invalidArchivedSpending(run.priorAttemptSpending)) return true
+  for (const field of ['packages', 'reviews']) {
+    if (run[field] === undefined) continue // missing legacy fields are not fabricated
+    if (!Array.isArray(run[field])) return true
+    for (const item of run[field]) {
+      if (!record(item) || (item.ran !== undefined && typeof item.ran !== 'boolean')) return true
+      if (['costUsd', 'referenceCostUsd'].some(name => item[name] !== undefined && item[name] !== null && !nonnegative(item[name]))) return true
+      if (item.ran === true || nonnegative(item.costUsd)) {
+        const at = item.finishedAt ?? run.createdAt
+        if (!nonnegative(at) || !Number.isFinite(new Date(at).getTime())) return true
+      }
+    }
+  }
+  return false
+}
+
 function sanitize(value, maxRuns) {
-  if (!value || typeof value !== 'object' || value.version !== STATE_VERSION) return emptyState()
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.version !== STATE_VERSION
+    || !Array.isArray(value.runs)) {
+    const error = new Error('模型路由状态版本或结构不受支持；原文件未修改，请先恢复或升级兼容版本。')
+    error.code = 'ROUTER_STATE_UNSUPPORTED'
+    throw error
+  }
+  const runs = value.runs.filter(run => run && typeof run.id === 'string')
   return retainRuns({
     version: STATE_VERSION,
+    // Unlike bounded notices, an incomplete-history marker cannot silently
+    // expire. Restoring a verified state file is required to recover budgets.
+    historyIncomplete: value.historyIncomplete === true || runs.length !== value.runs.length
+      || invalidArchivedSpending(value.archivedSpending) || runs.some(invalidRunSpending)
+      || sanitizeNotices(value.notices).some(notice => notice.kind === 'state-corrupt'),
     onboarding: { completedAt: Number.isFinite(value.onboarding?.completedAt) ? value.onboarding.completedAt : null },
     health: value.health && Array.isArray(value.health.tools) ? value.health : null,
     quota: value.quota && typeof value.quota === 'object' && !Array.isArray(value.quota) ? value.quota : {},
     authFailures: Object.fromEntries(Object.entries(value.authFailures && typeof value.authFailures === 'object' && !Array.isArray(value.authFailures) ? value.authFailures : {})
       .filter(([, entry]) => Number.isFinite(entry?.at))),
-    runs: Array.isArray(value.runs) ? value.runs.filter(run => run && typeof run.id === 'string') : [],
+    runs,
     dynamicData: value.dynamicData && typeof value.dynamicData === 'object' && !Array.isArray(value.dynamicData) ? value.dynamicData : { liveBench: null, pricing: null, status: {}, revision: '' },
     archivedSpending: sanitizeArchivedSpending(value.archivedSpending),
     notices: sanitizeNotices(value.notices),
@@ -93,36 +141,66 @@ export function terminalSessionRecord(record) {
 const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
 const stamp = at => new Date(at).toISOString().replace(/[:.]/g, '-')
 
-/** Exclusive lock file; a lock older than `staleMs` (crashed holder) is broken. */
+function ownerPid(raw) {
+  try {
+    const pid = JSON.parse(raw).pid
+    if (Number.isSafeInteger(pid) && pid > 0) return pid
+  } catch { /* support the previous pid/timestamp format */ }
+  const pid = Number(/^(\d+)\s+\d+\s*$/u.exec(raw)?.[1])
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : null
+}
+
+function ownerIsDead(pid) {
+  if (pid === null) return false
+  try { process.kill(pid, 0); return false }
+  catch (error) { return error?.code === 'ESRCH' }
+}
+
+/** Never steal a live or unknown owner's lock, even after the wait timeout. */
 async function acquireLock(lockFile, { staleMs = LOCK_STALE_MS, timeoutMs = LOCK_TIMEOUT_MS, now = Date.now } = {}) {
-  const started = now()
+  // Elapsed waits must not freeze or jump when wall-clock time changes.
+  const started = performance.now()
   for (let attempt = 0; ; attempt += 1) {
     try {
       const handle = await open(lockFile, 'wx')
-      await handle.writeFile(`${process.pid} ${now()}\n`, 'utf8').catch(() => {})
+      const owner = `${JSON.stringify({ pid: process.pid, token: randomUUID(), at: now() })}\n`
+      try { await handle.writeFile(owner, 'utf8') }
+      catch (error) { await handle.close(); await unlink(lockFile).catch(() => {}); throw error }
       await handle.close()
-      return async () => { await unlink(lockFile).catch(() => {}) }
+      return async () => {
+        if (await readFile(lockFile, 'utf8').catch(() => null) === owner) await unlink(lockFile).catch(() => {})
+      }
     } catch (error) {
       if (error?.code !== 'EEXIST') throw error
       const info = await stat(lockFile).catch(() => null)
-      if (info && now() - info.mtimeMs > staleMs) {
-        await unlink(lockFile).catch(() => {})
-        continue
+      const owner = await readFile(lockFile, 'utf8').catch(() => null)
+      if (info && owner !== null && now() - info.mtimeMs > staleMs && ownerIsDead(ownerPid(owner))) {
+        const currentInfo = await stat(lockFile).catch(() => null)
+        if (currentInfo?.ino === info.ino && currentInfo?.mtimeMs === info.mtimeMs
+          && await readFile(lockFile, 'utf8').catch(() => null) === owner) {
+          await unlink(lockFile).catch(() => {})
+          continue
+        }
       }
-      if (now() - started > timeoutMs) {
-        // A live holder that never releases: break it rather than lose the write.
-        await unlink(lockFile).catch(() => {})
-        continue
+      if (performance.now() - started >= timeoutMs) {
+        const failure = new Error('模型路由状态正在被其他操作使用，保存未完成；请稍后重试。')
+        failure.code = 'ROUTER_STATE_LOCK_TIMEOUT'
+        throw failure
       }
       await sleep(Math.min(5 + attempt * 5, 50) + Math.floor(Math.random() * 10))
     }
   }
 }
 
-export function createRouterState({ file = defaultStatePath(), maxRuns = MAX_RUNS, now = Date.now } = {}) {
+export function createRouterState({ file = defaultStatePath(), maxRuns = MAX_RUNS, now = Date.now,
+  lockTimeoutMs = LOCK_TIMEOUT_MS, lockStaleMs = LOCK_STALE_MS } = {}) {
+  if (![lockTimeoutMs, lockStaleMs].every(value => Number.isFinite(value) && value >= 1 && value <= 3_600_000)) {
+    throw new RangeError('Lock timing must be between 1 and 3600000 milliseconds')
+  }
   const historyLimit = Number.isInteger(maxRuns) && maxRuns > 0 ? Math.min(maxRuns, MAX_RUNS) : MAX_RUNS
   let cache = null
   let cacheKey = ''
+  let cacheCorrupt = false
   let chain = Promise.resolve()
   let pendingNotices = []
   const lockFile = `${file}.lock`
@@ -131,43 +209,53 @@ export function createRouterState({ file = defaultStatePath(), maxRuns = MAX_RUN
     return info ? `${info.mtimeMs}:${info.size}:${info.ino}` : 'missing'
   }
   /** Parse the file; keep an unparseable file as a backup and record a notice. */
-  const readFresh = async () => {
+  const readFresh = async ({ recoverCorrupt = false } = {}) => {
     let raw
     try { raw = await readFile(file, 'utf8') }
     catch (error) {
       if (error?.code === 'ENOENT') return { state: emptyState(), corrupt: false }
       throw error
     }
-    try { return { state: sanitize(JSON.parse(raw), historyLimit), corrupt: false } }
+    let parsed
+    try { parsed = JSON.parse(raw) }
     catch {
+      // Readers do not rename files outside the writer lock. Recheck under the
+      // lock so a concurrent valid replacement cannot be discarded as corrupt.
+      if (!recoverCorrupt) return { state: emptyState(), corrupt: true }
       const at = now()
-      const backup = `${file}.corrupt-${stamp(at)}`
-      let saved = true
-      try { await rename(file, backup) } catch { saved = false }
+      const backup = `${file}.corrupt-${stamp(at)}-${randomUUID()}`
+      await rename(file, backup)
       pendingNotices.push({
-        kind: 'state-corrupt', at, backup: saved ? backup : null,
-        message: saved
-          ? `模型路由状态文件已损坏，无法读取，已备份为 ${backup} 并重新开始记录。执行历史、评价和订阅冷却信息需要从备份中人工恢复。`
-          : '模型路由状态文件已损坏，无法读取，备份失败；已重新开始记录。',
+        kind: 'state-corrupt', at, backup,
+        message: `模型路由状态文件已损坏，无法读取，已备份为 ${backup} 并重新开始记录。执行历史、评价和订阅冷却信息需要从备份中人工恢复。`,
       })
-      return { state: emptyState(), corrupt: true }
+      return { state: { ...emptyState(), historyIncomplete: true }, corrupt: true }
     }
+    // Valid JSON with an unknown schema is not corrupt: preserve it exactly,
+    // and refuse both reads-as-empty and writes that would downgrade it.
+    return { state: sanitize(parsed, historyLimit), corrupt: false }
   }
   const load = async () => {
     const key = await fileKey()
     if (cache && key === cacheKey) return cache
     const fresh = await readFresh()
     cache = fresh.state
-    cacheKey = fresh.corrupt ? '' : key
+    cacheKey = key
+    cacheCorrupt = fresh.corrupt
     return cache
   }
   const persist = async state => {
     await mkdir(dirname(file), { recursive: true })
+    const committed = structuredClone(state)
+    const serialized = `${JSON.stringify(committed)}\n`
     const temp = `${file}.${process.pid}.${now()}.${Math.random().toString(36).slice(2, 8)}.tmp`
-    await writeFile(temp, `${JSON.stringify(state)}\n`, 'utf8')
-    await rename(temp, file)
-    cache = state
+    try {
+      await writeFile(temp, serialized, 'utf8')
+      await rename(temp, file)
+    } finally { await unlink(temp).catch(() => {}) }
+    cache = committed
     cacheKey = await fileKey()
+    cacheCorrupt = false
   }
   /**
    * Serialize read-modify-write updates within this process and, through the
@@ -176,17 +264,26 @@ export function createRouterState({ file = defaultStatePath(), maxRuns = MAX_RUN
   const update = change => {
     const next = chain.then(async () => {
       await mkdir(dirname(file), { recursive: true })
-      const release = await acquireLock(lockFile, { now })
+      const release = await acquireLock(lockFile, { now, timeoutMs: lockTimeoutMs, staleMs: lockStaleMs })
       try {
         cache = null
-        const state = await load()
-        if (pendingNotices.length) { state.notices.push(...pendingNotices); pendingNotices = [] }
+        const { state } = await readFresh({ recoverCorrupt: true })
+        if (pendingNotices.length) state.notices.push(...pendingNotices)
         const result = await change(state)
+        const returned = result === undefined ? undefined : structuredClone(result)
         retainRuns(state, historyLimit)
         state.notices = sanitizeNotices(state.notices)
         state.terminalSessions = sanitizeTerminalSessions(state.terminalSessions)
         await persist(state)
-        return result
+        pendingNotices = []
+        return returned
+      } catch (error) {
+        // A rejected callback or disk write must not leak uncommitted state
+        // into the reader cache, including partial rating/budget changes.
+        cache = null
+        cacheKey = ''
+        cacheCorrupt = false
+        throw error
       } finally {
         await release()
       }
@@ -198,9 +295,13 @@ export function createRouterState({ file = defaultStatePath(), maxRuns = MAX_RUN
   const read = async () => {
     await chain
     const state = await load()
-    if (pendingNotices.length) {
+    if (cacheCorrupt || pendingNotices.length) {
       const notices = [...pendingNotices]
-      try { await update(() => {}) } catch { return structuredClone({ ...state, notices: [...state.notices, ...notices] }) }
+      try { await update(() => {}) }
+      catch {
+        return structuredClone({ ...state, notices: [...state.notices, ...notices,
+          { kind: 'state-recovery-pending', at: now(), message: '模型路由状态恢复未完成；原文件保留，请稍后重试。' }] })
+      }
       return structuredClone(cache)
     }
     return structuredClone(state)
@@ -233,10 +334,10 @@ export function createRouterState({ file = defaultStatePath(), maxRuns = MAX_RUN
       return entry
     }),
     appendRun: run => update(current => { current.runs.push(run); return run }),
-    updateRun: (id, change) => update(current => {
+    updateRun: (id, change) => update(async current => {
       const run = current.runs.find(item => item.id === id)
       if (!run) throw new Error(`未找到运行记录 ${id}`)
-      change(run)
+      await change(run)
       return structuredClone(run)
     }),
     /** Remove one notice (for example after the user read the corrupt-file warning). */