dsh-multi-provider-usage 0.7.1 → 0.7.3

package/README.md

@@ -36,23 +36,31 @@ panel settings page — extended from one provider to three.
   console token is auto-discovered from `OPENCODE_CONSOLE_TOKEN`, the OpenCode
   CLI auth file, or its local `opencode.db`; the token never leaves the host.
   When that token is missing, the balance slot becomes a clickable "Set up" chip
-  that opens the plugin settings instead of silently showing nothing. Command
+  that opens the plugin settings, where the OpenCode GO card renders a
+  step-by-step setup guide, instead of silently showing nothing. Command
   Code's tooltip breaks its amount into purchased + free credits; a credits
   response without either pool renders a muted **No top-up** badge.
 - **Auto-update** — on boot and every configured interval the host checks the
-  GitHub release feed. A local `link:`/`file:` checkout is fast-forwarded when it
-  is on `main`, clean, and a strict fast-forward. An npm / market / tarball copy
-  updates itself: the release tarball is unpacked and each packaged file
-  (`lib/`, `package.json`, `cordis.patch.yml`, `docs/`) is written to a temp file
-  and renamed over the target, so pnpm's hardlinked store is never edited in
-  place. Either way the running Host keeps the old module graph, so the
-  widget/settings show "updated — restart DSH". The plugin never restarts DSH by
-  itself.
+  npm registry, the npmmirror mirror and the GitHub release feed together and
+  trusts the newest version any of them reports. A local `link:`/`file:` checkout
+  is fast-forwarded when it is on `main`, clean, and a strict fast-forward. An
+  npm / market / tarball copy updates itself: the release tarball is downloaded
+  from the first source that serves it (registry → mirror → GitHub, in turn) and
+  each packaged file (`lib/`, `package.json`, `cordis.patch.yml`, `docs/`) is
+  written to a temp file and renamed over the target, so pnpm's hardlinked store
+  is never edited in place. Either way the running Host keeps the old module
+  graph, so the widget/settings show "updated — restart DSH". The plugin never
+  restarts DSH by itself.
 - **Balance-change animation** — the widget polls on its normal interval; when
   a provider's balance differs from the previous poll, the number counts from
   the old value to the refreshed one while a red/green delta chip (for example
   `-0.1`) floats up and fades away. There is no popup and no turn-event
   tracking, so the animation may appear up to one poll interval later.
+- **Low-balance tone** — a balance at or below 5 renders amber and at or below 1
+  renders red (thresholds are in the currency unit and apply to USD and CNY
+  plans alike), in both the sidebar and the settings page's live-usage sections.
+- **Click-to-retry failures** — an error line in the widget is itself clickable
+  (and keyboard-activatable) and forces one fresh upstream read.
 - **Same-origin proxy** — the browser only talks to `/provider-usage/usage` and
   `/provider-usage/settings`; API keys stay in the host process.
 - **Failure isolation** — one broken provider never hides the other two. The
@@ -65,6 +73,12 @@ panel settings page — extended from one provider to three.
 - **Bundle settings page** — sidebar **Plugins** panel → this bundle's card:
   enable/disable each provider, edit credential refs and endpoints, choose the
   GLM region, and see non-network detection status. Save applies immediately.
+  Each provider card embeds a **live usage** section — quota windows with
+  percentages, time-to-reset and the top-up balance, from the same canonical
+  snapshot the widget renders. While the page is open it follows the widget:
+  a 30-second poll (when the tab is visible) plus an "Updated HH:MM" stamp,
+  a **Refresh usage** control forces a re-read, and every save re-reads with
+  `refresh=1`, so a changed credential ref shows its own numbers immediately.
   The GLM card also carries the **referral link** (Z.ai "Invite Friends, Get
   Credits") as a clickable, copyable row. The URL is a bundle constant: it never
   goes through the settings route and a settings save cannot overwrite it.
@@ -78,16 +92,22 @@ panel settings page — extended from one provider to three.
 
 ## Install
 
-From a checkout:
+From npm:
 
 ```bash
-dsh plugin --profile desktop add /path/to/dsh-provider-usage
+dsh plugin --profile desktop add dsh-multi-provider-usage
 ```
 
 or, for the web profile:
 
 ```bash
-dsh plugin --profile web add /path/to/dsh-provider-usage
+dsh plugin --profile web add dsh-multi-provider-usage
+```
+
+From a checkout (for development):
+
+```bash
+dsh plugin --profile desktop add /path/to/dsh-provider-usage
 ```
 
 The package declares `dsh.bundle.patch`, so the CLI reconciles it into the
@@ -127,21 +147,48 @@ in this order:
 
 1. `opencodeConsoleApiKeyEnv` (`OPENCODE_CONSOLE_TOKEN` by default), resolved
    through DSH credentials;
-2. `~/.local/share/opencode/auth.json` (`$XDG_DATA_HOME/opencode/auth.json` when
-   set), provider `opencode`;
-3. the `credential` table of `~/.local/share/opencode/opencode.db` (read via
+2. the `credential` table of `~/.local/share/opencode/opencode.db` (read via
    `node:sqlite` when available; this is where current OpenCode releases keep
-   the OAuth grant).
+   the OAuth grant and rotate it);
+3. `~/.local/share/opencode/auth.json` (`$XDG_DATA_HOME/opencode/auth.json` when
+   set), provider `opencode` — the legacy location kept by older releases.
+
+The database is preferred deliberately: OpenCode migrated its grant there but
+often leaves the old `auth.json` behind, and that stale token returns 401. Every
+usable OAuth candidate is tried in turn (at most four), so one expired store
+cannot hide the live one. Channel builds (`opencode-beta.db`, `opencode-dev.db`,
+…) and `$OPENCODE_DB` are discovered too. The billing host comes from the grant's
+`metadata.server` (so a self-hosted console works), falling back to the public
+origin; `opencodeConsoleBaseUrl` overrides it.
+
+An OpenCode **API-key** login (`oc_sk_…`, the service-account method) carries no
+console session and is never sent to the billing endpoint. Such a login, a
+missing token, or an expired/revoked grant renders a clickable **Set up** chip
+(instead of a mute dash) that opens this bundle's page in the Plugins panel and
+names the fix: run `opencode auth login` and choose the **OpenCode Console
+account**, or store a console token as `OPENCODE_CONSOLE_TOKEN`.
+
+When the balance is not configured (or the console login is fixable), the
+OpenCode GO card in the plugin settings renders a step-by-step **setup guide**
+in place of the static hint. The lead-in names the state-specific fix (nothing
+configured, an API-key login, or an expired sign-in). Step ① shows the
+`opencode auth login` CLI command with a **Copy command** button; step ② is the
+manual path — copy the console token and store it as the `OPENCODE_CONSOLE_TOKEN`
+credential — with a **Copy credential ref** button and a link to the OpenCode
+console website (derived from `opencodeConsoleBaseUrl`, ending in `/console`);
+step ③ offers a **Re-check** button that re-reads the sign-in state and forces
+one upstream usage read, so a fresh login shows the balance without restarting
+DSH (unsaved form edits are never discarded by the re-check). The
+`/provider-usage` command gives the same state-specific guidance as text for
+all three fixable states.
 
 The optional `opencodeConsoleAuthFile` overrides the auth file (and its
-directory is used for `opencode.db`), `opencodeConsoleOrgId` supplies the
+directory is used to locate `opencode.db`), `opencodeConsoleOrgId` supplies the
 `x-org-id` header, and `opencodeConsoleEnabled: false` turns the whole balance
 read off. Balance failures never hide the GO quota: the provider stays `ok` with
-`balance: null` and a `meta.balanceError`. A missing console credential is
-actionable rather than hidden: the balance slot renders a clickable **Set up**
-chip that opens this bundle's page in the Plugins panel, whose tooltip names the
-fix (`opencode auth login` or `OPENCODE_CONSOLE_TOKEN`). Any other balance
-failure renders a muted **Balance —** badge whose tooltip carries the error.
+`balance: null` and a `meta.balanceError` (plus `meta.balanceSetup` when the
+user can fix it). Any other balance failure renders a muted **Balance —** badge
+whose tooltip carries the error.
 
 ### Command Code balance
 
@@ -222,7 +269,7 @@ the settings page and the auto-generated form hot-apply.
 | `glmRegion` | `"auto"` | `auto`, `zai`, `bigmodel`, `custom` |
 | `cacheMs` | `30000` | Per-provider host cache TTL |
 | `updateCheck` | `true` | npm update check (24 h) |
-| `autoUpdate` | `true` | Check GitHub releases; fast-forward a clean checkout, otherwise replace an installed package |
+| `autoUpdate` | `true` | Check npm, npmmirror and GitHub together; fast-forward a clean checkout, otherwise replace an installed package from the first source that serves the tarball |
 | `autoUpdateCheckHours` | `6` | Hours between auto-update checks (1–168) |
 | `injectSessionHeader` | `true` | OpenCode GO session-header fix |
 | `providerOrder` | all three ids | Provider display order in the widget; drag the cards in the plugin settings to reorder |
@@ -285,10 +332,12 @@ the settings page and the auto-generated form hot-apply.
 Failed providers have `"status": "error"`, `code`, `error` and `windows: []`;
 their siblings are still returned. A body with `providers: []` means no provider
 is enabled. `meta.balanceError` carries a tolerated balance failure (the
-provider still answers `ok`); `meta.balanceMissing` marks a Command Code credits
-response without purchased/free pools. `meta.errors` lists partial Command Code
-endpoint failures: the numbers stay, the health dot turns amber, and the tooltip
-names the failed calls. Error cards keep the plan they already resolved.
+provider still answers `ok`); `meta.balanceSetup` (`no-credential`, `api-key` or
+`expired`) marks a failure the user can fix by signing in again;
+`meta.balanceMissing` marks a Command Code credits response without
+purchased/free pools. `meta.errors` lists partial Command Code endpoint
+failures: the numbers stay, the health dot turns amber, and the tooltip names
+the failed calls. Error cards keep the plan they already resolved.
 
 ### `GET /provider-usage/settings`
 
@@ -374,7 +423,7 @@ network and no real keys. They cover the schema, all three adapters, OpenCode
 GO service integration/fallback, aggregation and error isolation, caching and
 forced refresh, settings conflicts/whitelisting, the client bundle contract,
 top-up balance discovery (credential and local auth.json) and failure
-isolation, and the session-header injection. 75 tests, all offline.
+isolation, and the session-header injection. 98 tests, all offline.
 
 ## License
 

package/README.zh.md

@@ -30,18 +30,24 @@
   购买额度 + 免费额度的 “Extra Credits” 余额；两者都显示在账号/套餐旁，并出现在
   `/provider-usage` 文本中。OpenCode 控制台令牌依次从 `OPENCODE_CONSOLE_TOKEN`、
   OpenCode CLI 的 auth.json 或本机 `opencode.db` 自动发现，令牌不会离开宿主进程。
-  没找到控制台令牌时，余额位置显示可点击的「配置余额」，点击直接打开本插件设置页。
+  没找到控制台令牌时，余额位置显示可点击的「配置余额」，点击直接打开本插件设置页；
+  设置页内为分步引导：可复制的登录命令、控制台网页链接与「重新检测」按钮。
   Command Code 的悬停提示会拆成「购买 + 免费」；credits 响应没有这两个池时显示
   灰色「无充值额度」。
-- **自动更新** — 宿主启动后以及按配置的间隔检查 GitHub Release。本地
-  `link:`/`file:` 目录检出在「main 分支、工作区干净、可严格 fast-forward」时直接
-  `git pull`；npm / 市场 / tarball 安装的副本则下载该 Release 的 tarball，先写临时
-  文件再 `rename` 覆盖 `lib/`、`package.json`、`cordis.patch.yml` 等打包文件——不会
-  就地改写 pnpm store 的硬链接。两种方式完成后，运行中的宿主仍持有旧模块，所以
+- **自动更新** — 宿主启动后以及按配置的间隔，同时向 npm registry、npmmirror 镜像与
+  GitHub Release 查询，以其中报告的最新版本为准。本地 `link:`/`file:` 目录检出在
+  「main 分支、工作区干净、可严格 fast-forward」时直接 `git pull`；npm / 市场 / tarball
+  安装的副本按「npm → npmmirror → GitHub」依次尝试下载 tarball，先写临时文件再
+  `rename` 覆盖 `lib/`、`package.json`、`cordis.patch.yml` 等打包文件——不会就地
+  改写 pnpm store 的硬链接。两种方式完成后，运行中的宿主仍持有旧模块，所以
   组件/设置页显示“已更新到 vX，重启 DSH 生效”；插件不会自行重启 DSH。
 - **余额变化动画** — 组件按正常轮询周期刷新；某个服务商的余额相比上一次轮询
   发生变化时，数字会从旧值滚动到新值，同时一个红色/绿色差值（例如 `-0.1`）
   向上飘走并淡出。没有弹窗，也不依赖对话轮次事件；动画最多可能晚一个轮询周期。
+- **余额低额预警** — 余额 ≤ 5 时余额徽章转黄、≤ 1 转红（货币单位通用），侧边栏
+  和设置页的「实时用量」一致生效，不用点开卡片也能一眼看到余额告急。
+- **失败可一键重试** — 读取失败时，组件里的错误文字本身可点击（也支持键盘
+  Enter/空格），立即强制重新读取。
 - **同源代理** — 浏览器只访问 `/provider-usage/usage` 和
   `/provider-usage/settings`，API Key 始终留在宿主进程。
 - **故障隔离** — 一个服务商失败不会影响另外两个；只要还有服务商成功，路由就返回
@@ -50,8 +56,12 @@
 - **设置快捷入口** — 组件标题栏的「设置」按钮直接打开侧边栏「插件」中的本插件
   页面，并定位到下面的配置页。
 - **插件设置页** — 侧边栏「插件」→ 本插件卡片：启用/禁用服务商、编辑凭据引用和
-  接口地址、选择 GLM 区域，并查看无网络请求的检测状态。保存后立即生效。GLM
-  卡片底部还有一条**推广链接**（Z.ai「邀请好友得积分」），可点击打开或一键复制；
+  接口地址、选择 GLM 区域，并查看无网络请求的检测状态。保存后立即生效。每个服务商
+  卡片内嵌「实时用量」：显示各额度窗口的百分比、剩余重置时间与订阅外充值余额（与
+  侧边栏组件同一份数据）；页面打开期间每 30 秒自动跟随刷新，并显示「更新于 HH:MM」
+  时间戳；「刷新用量」按钮强制读取；保存设置（例如换了 apiKeyEnv 凭据引用）后会以
+  `refresh=1` 立即重新读取，马上反映新凭据的用量与余额。
+  GLM 卡片底部还有一条**推广链接**（Z.ai「邀请好友得积分」），可点击打开或一键复制；
   链接是写死的常量，不经过设置接口，也不会被保存的表单覆盖。
 - **`/provider-usage` 聊天命令** — 在对话中打印所有启用服务商的用量文本。
 - **时间条** — 额度条下方，灰色是窗口已流逝时间，蓝色是剩余时间，几何尺寸与参考
@@ -62,7 +72,13 @@
 
 ## 安装
 
-从本地 checkout 安装：
+从 npm 安装：
+
+```bash
+dsh plugin --profile desktop add dsh-multi-provider-usage
+```
+
+开发时也可以直接从本地 checkout 安装：
 
 ```bash
 dsh plugin --profile desktop add /path/to/dsh-provider-usage
@@ -104,18 +120,38 @@ GO 额度接口不包含账户预付费余额。余额来自
 OAuth 令牌（GO API Key 访问会返回 403）。宿主按以下顺序解析：
 
 1. `opencodeConsoleApiKeyEnv`（默认 `OPENCODE_CONSOLE_TOKEN`），通过 DSH 凭据解析；
-2. `~/.local/share/opencode/auth.json`（设置了 `$XDG_DATA_HOME` 时用
-   `$XDG_DATA_HOME/opencode/auth.json`）中的 `opencode` provider；
-3. `~/.local/share/opencode/opencode.db` 的 `credential` 表（Node 支持
-   `node:sqlite` 时读取；当前 OpenCode 将 OAuth grant 存在这里）。
+2. `~/.local/share/opencode/opencode.db` 的 `credential` 表（Node 支持
+   `node:sqlite` 时读取；当前 OpenCode 将 OAuth grant 存在这里并在运行时轮换）；
+3. `~/.local/share/opencode/auth.json`（设置了 `$XDG_DATA_HOME` 时用
+   `$XDG_DATA_HOME/opencode/auth.json`）中的 `opencode` provider——旧版本的位置。
+
+数据库优先是刻意的：OpenCode 已把登录态迁到数据库，但经常把旧的 `auth.json`
+留在磁盘上，里面的过期令牌会返回 401。宿主会依次尝试每个可用的 OAuth 登录（最多
+四个），所以一份过期数据不会遮住仍然有效的登录。渠道版数据库（`opencode-beta.db`、
+`opencode-dev.db` 等）和 `$OPENCODE_DB` 也会被发现。余额请求使用 grant 里的
+`metadata.server`（自建控制台可用），缺省回落到公开域名；
+`opencodeConsoleBaseUrl` 可覆盖。
+
+OpenCode 的 **API Key** 登录（`oc_sk_…`，service-account 方式）不含控制台会话，
+不会被发到只接受控制台令牌的 billing 接口。API Key 登录、缺少令牌或登录已过期/
+被吊销时，余额位置显示可点击的「配置余额」而不是灰色横杠；点击打开本插件在
+Plugins 面板中的设置页，悬停提示修复方式：运行 `opencode auth login` 并选择
+**OpenCode Console account**，或把控制台令牌保存为 `OPENCODE_CONSOLE_TOKEN`。
+
+余额未配置或控制台登录可修复时，插件设置页的 OpenCode GO 卡片不再给一句静态
+提示，而是渲染分步**引导**：引言按当前状态指明修复方式（未配置 / API Key 登录 /
+登录已过期）。第①步给出 `opencode auth login` 命令与「复制命令」按钮；第②步是
+手动路径——从控制台网页复制令牌、保存为 `OPENCODE_CONSOLE_TOKEN` 凭据——带
+「复制凭据名」按钮和打开 OpenCode 控制台网页的链接（由 `opencodeConsoleBaseUrl`
+推导，以 `/console` 结尾）；第③步提供「重新检测」按钮，重读登录状态并强制刷新
+一次用量，新登录无需重启 DSH 即可显示余额（重新检测不会丢弃表单里未保存的修改）。
+`/provider-usage` 命令对三种可修复状态都会给出同样的文字引导。
 
 可用 `opencodeConsoleAuthFile` 覆盖 auth.json 路径（其目录也用于定位
 `opencode.db`），`opencodeConsoleOrgId` 提供 `x-org-id`，
 `opencodeConsoleEnabled: false` 可关闭余额读取。余额失败不会影响 GO 额度：
-provider 仍为 `ok`，`balance` 为 `null` 并带 `meta.balanceError`。缺少控制台
-令牌时不再静默隐藏：余额位置显示可点击的「配置余额」，点击打开本插件在
-Plugins 面板中的设置页，悬停提示修复方式（`opencode auth login` 或
-`OPENCODE_CONSOLE_TOKEN`）。其它余额失败显示灰色「余额 —」，悬停给出原因。
+provider 仍为 `ok`，`balance` 为 `null` 并带 `meta.balanceError`（可由用户修复时
+另带 `meta.balanceSetup`）。其它余额失败显示灰色「余额 —」，悬停给出原因。
 
 ### Command Code 余额
 
@@ -190,7 +226,7 @@ Loader 直接读取导出的 `Config` schema；所有字段都是 `.volatile()`
 | `glmRegion` | `"auto"` | `auto`、`zai`、`bigmodel`、`custom` |
 | `cacheMs` | `30000` | 单个服务商的宿主缓存 TTL |
 | `updateCheck` | `true` | npm 新版本检查（24 小时） |
-| `autoUpdate` | `true` | 检查 GitHub Release；干净 checkout 快进，安装包用 Release tarball 原地替换 |
+| `autoUpdate` | `true` | 同时查询 npm / npmmirror / GitHub Release；干净 checkout 快进，安装包按可达的源依次下载 tarball 原地替换 |
 | `autoUpdateCheckHours` | `6` | 自动更新检查间隔（1–168 小时） |
 | `injectSessionHeader` | `true` | OpenCode GO 会话头修复 |
 | `providerOrder` | 三个 id 全集 | 组件中的显示顺序；在插件设置里拖动卡片调整 |
@@ -252,10 +288,11 @@ Loader 直接读取导出的 `Config` schema；所有字段都是 `.volatile()`
 
 失败的服务商为 `"status": "error"`，带 `code`、`error` 和空 `windows`，其余服务商
 照常返回。`providers: []` 表示没有启用任何服务商。`meta.balanceError` 表示被容忍
-的余额失败（provider 仍为 `ok`）；`meta.balanceMissing` 表示 Command Code 的
-credits 响应没有购买/免费额度。`meta.errors` 列出 Command Code 的部分接口失败：
-数字照常显示，但健康点变黄，悬停可看到失败的接口。错误卡片仍保留已经解析出的
-套餐信息。
+的余额失败（provider 仍为 `ok`）；`meta.balanceSetup`（`no-credential`、`api-key`
+或 `expired`）表示用户重新登录即可修复的余额状态；`meta.balanceMissing` 表示
+Command Code 的 credits 响应没有购买/免费额度。`meta.errors` 列出 Command Code
+的部分接口失败：数字照常显示，但健康点变黄，悬停可看到失败的接口。错误卡片仍
+保留已经解析出的套餐信息。
 
 ### `GET /provider-usage/settings`
 
@@ -334,7 +371,7 @@ npm test
 测试是封闭的：伪造 `globalThis.fetch` + stub Cordis 上下文，不访问网络、不使用真实
 密钥。覆盖 schema、三个适配器、OpenCode GO 服务集成/回退、聚合与故障隔离、缓存与
 强制刷新、设置冲突/白名单、客户端 bundle 契约、充值余额发现（凭据 / 本地
-auth.json）与失败隔离、会话头注入、余额变化动画；共 75 个测试。
+auth.json）与失败隔离、会话头注入、余额变化动画；共 98 个测试。
 
 ## 许可证
 

package/lib/auto-update.js

@@ -6,10 +6,12 @@
  *
  *   - `checkout` (`link:` / `file:` directory): fast-forward the git checkout,
  *     but only when it is on `main`, clean, and can fast-forward `origin/main`.
- *   - `package` (npm / market / tarball install): download the GitHub release
- *     tarball and replace the packaged files in place. Every file is written
- *     to a temp file inside the package directory first and then renamed over
- *     the target, which keeps pnpm's hardlinked store untouched.
+ *   - `package` (npm / market / tarball install): pick the newest release
+ *     known to npm, the npmmirror mirror and GitHub together, then download
+ *     the release tarball from the first source that serves it and replace
+ *     the packaged files in place. Every file is written to a temp file
+ *     inside the package directory first and then renamed over the target,
+ *     which keeps pnpm's hardlinked store untouched.
  *
  * Neither strategy restarts the Host: the running module graph is stale once
  * the files land, so the UI reports `restartRequired`. The updater never
@@ -28,6 +30,10 @@ import { gunzipSync } from "node:zlib";
 
 export const AUTO_UPDATE_REPO = "wjw1-Evan/dsh-provider-usage";
 export const AUTO_UPDATE_RELEASE_URL = `https://api.github.com/repos/${AUTO_UPDATE_REPO}/releases/latest`;
+/** npm registry — the canonical published package (also the `updateCheck` source). */
+export const NPM_REGISTRY_URL = "https://registry.npmjs.org";
+/** npmmirror mirror of the registry; reachable where npm/GitHub are not. */
+export const NPM_MIRROR_URL = "https://registry.npmmirror.com";
 /** Delay before the first background check, so activation is never blocked. */
 const FIRST_CHECK_DELAY_MS = 15_000;
 /** Hourly tick; the configured check interval gates actual network calls. */
@@ -390,6 +396,124 @@ async function fetchLatestRelease(fetchImpl) {
 	};
 }
 
+// ── package release sources ─────────────────────────────────────────────
+// An installed package updates by downloading a release tarball. GitHub is
+// the canonical source, but the registry serves the identical packaged
+// surface and is reachable where GitHub is not (and vice versa), so the
+// checker asks npm, the npmmirror mirror and GitHub together and trusts the
+// newest version any of them reports.
+
+/** Build the registry tarball URL for a version. */
+function registryTarballUrl(baseUrl, packageName, version) {
+	return `${baseUrl}/${packageName}/-/${packageName}-${version}.tgz`;
+}
+
+/** Fetch the latest published version from one npm registry endpoint. */
+async function fetchLatestFromRegistry(baseUrl, packageName, fetchImpl) {
+	const res = await fetchImpl(`${baseUrl}/${packageName}/latest`, {
+		headers: {
+			Accept: "application/vnd.npm.install-v1+json",
+			"User-Agent": "dsh-multi-provider-usage"
+		},
+		signal: AbortSignal.timeout(10_000)
+	});
+	if (!res.ok) throw new Error(`npm registry check ${res.status}`);
+	const doc = await res.json();
+	const version = typeof doc?.version === "string" ? doc.version : "";
+	if (parseVersion(version) === null) throw new Error("npm registry has no usable version");
+	const dist = doc?.dist?.tarball;
+	return {
+		version,
+		tarballUrl: typeof dist === "string" && dist.length > 0 ? dist : registryTarballUrl(baseUrl, packageName, version)
+	};
+}
+
+/**
+ * Pick the newest release known to any package source: npm registry, the
+ * npmmirror mirror and the GitHub release. One source lagging or failing is
+ * tolerated while any other answers; only when every source fails does the
+ * check itself fail. The winning source's tarball URL is the first download
+ * candidate.
+ */
+async function resolvePackageRelease({ packageName, fetchImpl }) {
+	const candidates = [
+		{ label: "npm", load: () => fetchLatestFromRegistry(NPM_REGISTRY_URL, packageName, fetchImpl) },
+		{ label: "npmmirror", load: () => fetchLatestFromRegistry(NPM_MIRROR_URL, packageName, fetchImpl) },
+		{ label: "GitHub", load: () => fetchLatestRelease(fetchImpl) }
+	];
+	const results = await Promise.allSettled(candidates.map((candidate) => candidate.load()));
+	/** @type {{ version: string, tarballUrl: string }[]} */
+	const successes = [];
+	/** @type {{ label: string, error: unknown }[]} */
+	const failures = [];
+	results.forEach((result, index) => {
+		if (result.status === "fulfilled") successes.push(result.value);
+		else failures.push({ label: candidates[index].label, error: result.reason });
+	});
+	if (successes.length === 0) {
+		throw new Error(`release check failed from all sources — ${describeFailures(failures)}`);
+	}
+	let best = successes[0];
+	for (const candidate of successes.slice(1)) {
+		if (isNewerVersion(candidate.version, best.version)) best = candidate;
+	}
+	return {
+		version: best.version,
+		// Each answering source's tarball URL, newest-version source first: a
+		// source that answered the check is also the likeliest download.
+		tarballUrls: [
+			best.tarballUrl,
+			...successes.filter((candidate) => candidate !== best).map((candidate) => candidate.tarballUrl)
+		]
+	};
+}
+
+/** Tarball URLs to try for a resolved release: answering sources first, then
+ * the canonical URLs for each source in case the check was partial. */
+function downloadCandidates(release, packageName) {
+	const urls = [];
+	const add = (url) => {
+		if (typeof url === "string" && url.length > 0 && !urls.includes(url)) urls.push(url);
+	};
+	for (const url of release.tarballUrls ?? []) add(url);
+	add(registryTarballUrl(NPM_REGISTRY_URL, packageName, release.version));
+	add(registryTarballUrl(NPM_MIRROR_URL, packageName, release.version));
+	add(`https://github.com/${AUTO_UPDATE_REPO}/archive/refs/tags/v${release.version}.tar.gz`);
+	return urls;
+}
+
+/** Short source label for a tarball URL, used in failure messages. */
+function sourceLabelOf(url) {
+	const text = String(url);
+	if (text.includes("registry.npmjs.org")) return "npm";
+	if (text.includes("registry.npmmirror.com")) return "npmmirror";
+	if (text.includes("github.com") || text.includes("githubusercontent.com") || text.includes("codeload")) return "GitHub";
+	return "release";
+}
+
+/** True when the failure is local, so another download source cannot help. */
+function isLocalWriteError(error) {
+	const code = typeof error?.code === "string" ? error.code : "";
+	if (/^(EACCES|EPERM|EROFS|EXDEV|EBUSY|ENOENT|ENOTDIR|EISDIR)$/.test(code)) return true;
+	return /is a symlink|permission denied|not writable/i.test(String(error?.message ?? error));
+}
+
+/** Attach an actionable hint to a filesystem-permission failure. */
+function withWriteHint(error) {
+	const message = String(error?.message ?? error);
+	if (!/^(EACCES|EPERM|EROFS)$/.test(typeof error?.code === "string" ? error.code : "")) return message;
+	return `${message} — the package directory is not writable; fix permissions or reinstall the package`;
+}
+
+/** Compact, bounded "source: error" summary for combined failure messages.
+ * Per-error bounds stay loose enough that an appended hint survives. */
+function describeFailures(failures) {
+	return failures
+		.map(({ label, error }) => `${label}: ${String(error?.message ?? error).slice(0, 240)}`)
+		.join("; ")
+		.slice(0, 800);
+}
+
 /**
  * Start the background checker.
  *
@@ -462,16 +586,33 @@ export function startAutoUpdate(options) {
 		lastCheckAt = now();
 		patch({ status: "checking", message: null });
 		inFlight = (async () => {
+			// A failed release check is an "error" (nothing new is known); a failed
+			// apply is "available" (the release is known, the download/write is
+			// not). The UI toasts only the latter.
+			let phase = "check";
 			try {
-				const release = await fetchLatestRelease(fetchImpl);
 				const install = detect({ packageDir, profileDir, packageName });
+				const release = install.kind === "checkout"
+					? await fetchLatestRelease(fetchImpl)
+					: await resolvePackageRelease({ packageName, fetchImpl });
 				patch({
 					latestVersion: release.version,
 					checkedAt: now(),
 					installKind: install.kind,
-					releaseUrl: release.url
+					releaseUrl: release.url ?? null
 				});
-				if (!isNewerVersion(release.version, currentVersion)) {
+				// `currentVersion` never changes in a running host, so a release
+				// this session already applied would be re-downloaded every cycle
+				// until restart. Compare against what this session applied.
+				const appliedVersion = typeof state.version === "string" && parseVersion(state.version) !== null
+					? state.version
+					: currentVersion;
+				if (!isNewerVersion(release.version, appliedVersion)) {
+					if (appliedVersion !== currentVersion) {
+						// Already self-updated to this release; restore the earlier
+						// "restart required" notice instead of re-applying.
+						return patch({ status: "updated" });
+					}
 					return patch({ status: "up-to-date", message: null, restartRequired: false });
 				}
 				if (install.kind === "checkout" && typeof install.checkout === "string") {
@@ -499,29 +640,50 @@ export function startAutoUpdate(options) {
 						message: "checkout updated; restart DSH to apply"
 					});
 				}
+				phase = "apply";
 				// Installed package (npm / market / tarball): replace the packaged
-				// files in place. The running Host keeps the old module graph until
-				// it is restarted, which the UI reports.
-				const result = await applyPackageUpdate({
-					packageDir,
-					tarballUrl: release.tarballUrl,
-					fetchImpl,
-					packageName,
-					expectVersion: release.version,
-					logger
-				});
-				logger.info?.(`dsh-multi-provider-usage: self-updated package to ${result.version}; restart DSH to apply`);
-				return patch({
-					status: "updated",
-					version: result.version,
-					updatedAt: now(),
-					restartRequired: true,
-					message: "package files replaced; restart DSH to apply"
-				});
+				// files in place, trying each download source in turn. The running
+				// Host keeps the old module graph until it is restarted, which the
+				// UI reports.
+				/** @type {{ label: string, error: unknown }[]} */
+				const failures = [];
+				const candidates = downloadCandidates(release, packageName);
+				for (const url of candidates) {
+					const label = sourceLabelOf(url);
+					try {
+						const result = await applyPackageUpdate({
+							packageDir,
+							tarballUrl: url,
+							fetchImpl,
+							packageName,
+							expectVersion: release.version,
+							logger
+						});
+						logger.info?.(`dsh-multi-provider-usage: self-updated package to ${result.version} from ${label}; restart DSH to apply`);
+						return patch({
+							status: "updated",
+							version: result.version,
+							updatedAt: now(),
+							restartRequired: true,
+							message: `package files replaced from ${label}; restart DSH to apply`
+						});
+					} catch (error) {
+						if (isLocalWriteError(error)) {
+							// No other download source can fix a local filesystem problem.
+							failures.push({ label, error: withWriteHint(error) });
+							break;
+						}
+						failures.push({ label, error });
+					}
+				}
+				const prefix = failures.length === candidates.length
+					? "update download failed from all sources"
+					: "update failed";
+				throw new Error(`${prefix} — ${describeFailures(failures)}`);
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
 				logger.warn?.(`dsh-multi-provider-usage: auto-update failed: ${message}`);
-				return patch({ status: "available", message, restartRequired: false });
+				return patch({ status: phase === "check" ? "error" : "available", message, restartRequired: false });
 			} finally {
 				inFlight = null;
 			}