@goodandready/dsh-opencode-provider 0.5.23 → 0.5.25

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.5.25 — release 2: stale data
+
+- **#87 — stale usage**: a failed usage refresh now returns the last successful report with `stale: true` and `lastSuccessAt` instead of discarding it. The quota sidebar/panel and Settings label the stale snapshot; an explicit refresh no longer loses the previous reading.
+- **#88 — stale analytics**: a failed analytics rescan keeps the previous report and heatmap visible with a stale notice and a retry button instead of blanking the panel; successful rescans clear the stale flag.
+- 127 tests.
+
+## 0.5.24 — release 1: account safety
+
+- **#89 — managed credential cleanup**: keys saved through Settings or imported from `auth.json` are recorded in `~/.dsh/storages/dsh-opencode/managed-credentials.json` (refs only, never secrets). Removing an account asks for confirmation and deletes only plugin-managed credentials after the settings save succeeds; external environment/`auth.json` references are left intact. Cleanup failures are reported separately from the account removal.
+- **#83 — autoSwitch**: new `autoSwitch` setting (default `true`, preserving prior behavior). When off, the selected/first usable account serves alone; quota/credential failures do not rotate and quota fallback is disabled. Exposed in Settings and TUI.
+- 126 tests.
+
 ## 0.5.23
 
 - **DSH 0.2.2 support**: compatibility now accepts every `0.2.2` prerelease and final release with `>=0.2.1-rc.2 <0.2.3-0`; `0.2.2-rc.1` is recorded as verified. Dev/typecheck dependencies moved to `@deepseek-ai/*@0.2.2-rc.1`, Cordis 4.1.0 and Schemastery 3.19.0; peer ranges admit both the 0.2.1 and 0.2.2 lines.

package/README.md

@@ -132,12 +132,12 @@ npm pack
 Install the **packed tarball** into a profile:
 
 ```bash
-dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.23.tgz
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.25.tgz
 # DSH Desktop:
-dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.23.tgz
+dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.25.tgz
 
 # Or install the published package:
-dsh plugin --profile web add @goodandready/dsh-opencode-provider@0.5.23
+dsh plugin --profile web add @goodandready/dsh-opencode-provider@0.5.25
 ```
 
 Restart dsh (or DSH Desktop), then pick **OpenCode (plugin)** or **OpenCode Go (plugin)** in the model picker.

package/README.ru.md

@@ -131,12 +131,12 @@ npm pack
 Установка из **упакованного tarball**:
 
 ```bash
-dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.23.tgz
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.25.tgz
 # DSH Desktop:
-dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.23.tgz
+dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.25.tgz
 
 # Либо установка опубликованного пакета из npm:
-dsh plugin --profile web add @goodandready/dsh-opencode-provider@0.5.23
+dsh plugin --profile web add @goodandready/dsh-opencode-provider@0.5.25
 ```
 
 После установки перезапустите dsh (или DSH Desktop) и выберите **OpenCode (plugin)** или **OpenCode Go (plugin)** в списке моделей.

package/README.zh.md

@@ -126,12 +126,12 @@ npm pack
 通过**打包文件 (.tgz)**安装：
 
 ```bash
-dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.23.tgz
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.25.tgz
 # DSH 桌面端：
-dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.23.tgz
+dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-opencode-provider-0.5.25.tgz
 
 # 或从 npm 安装已发布版本：
-dsh plugin --profile web add @goodandready/dsh-opencode-provider@0.5.23
+dsh plugin --profile web add @goodandready/dsh-opencode-provider@0.5.25
 ```
 
 安装完成后重启 dsh 或 DSH 桌面端，在模型选择器中选择 **OpenCode (plugin)** 或 **OpenCode Go (plugin)** 即可。

package/lib/client.js

@@ -65,6 +65,9 @@ window.__ModuleLoader__.load({
 				dragAccount: "Drag to reorder accounts",
 				accountLimit: "At most 20 accounts are allowed.",
 				removeAccount: "Remove",
+				removeAccountConfirm: "Remove this account and delete its plugin-managed credential {ref}? This cannot be undone.",
+				managedKey: "Managed key",
+				accountCleanupFailed: "Account removed, but credential cleanup failed:",
 				pinAccount: "Pin",
 				activeAccount: "Pinned account",
 				activeAccountNow: "Active account",
@@ -93,6 +96,7 @@ window.__ModuleLoader__.load({
 				runwaySafe: "safe",
 				noUsage: "Quota is unavailable.",
 				usageError: "Quota error",
+				usageStale: "Showing the last successful quota reading; the latest refresh failed.",
 				refresh: "Refresh",
 				refreshed: "Refreshed",
 				loading: "Loading…",
@@ -141,6 +145,7 @@ window.__ModuleLoader__.load({
 				heatmapAllAccounts: "All accounts",
 				analyticsHint: "Aggregated from local session metadata by last activity. A session that switched models is counted under its last model; failures are not exposed by the projection. Only plugin routes are counted; legacy opencode sessions belong to the built-in catalog.",
 				analyticsPartial: "This report is partial: the projection scan hit its file limit or skipped unreadable files.",
+				analyticsStale: "Showing the previous successful scan; the latest refresh failed.",
 				analyticsEmpty: "No plugin sessions in this window. Legacy opencode sessions belong to the built-in catalog.",
 				showAll: "Show all",
 				modelSearch: "Search models…",
@@ -197,6 +202,8 @@ window.__ModuleLoader__.load({
 				routingFailed: "Failed",
 				quotaFallbackModel: "Quota fallback model",
 				quotaFallbackModelHint: "If Go rejects with a quota error, retry once on this free model through Console/Zen.",
+				autoSwitch: "Automatic account failover",
+				autoSwitchHint: "Try the next account before any output when the current account hits quota or a credential failure. Off keeps the selected account only.",
 				stickySession: "Sticky account per conversation",
 				stickySessionHint: "Prefer the last successful account for the same conversation; explicit model rules and pinned accounts win.",
 				off: "Off",
@@ -278,6 +285,9 @@ window.__ModuleLoader__.load({
 				dragAccount: "拖动以调整账户顺序",
 				accountLimit: "最多允许 20 个账户。",
 				removeAccount: "移除",
+				removeAccountConfirm: "移除此账户并删除插件管理的凭据 {ref}？此操作无法撤销。",
+				managedKey: "插件管理的密钥",
+				accountCleanupFailed: "账户已移除，但凭据清理失败：",
 				pinAccount: "固定",
 				activeAccount: "固定账户",
 				activeAccountNow: "当前账户",
@@ -306,6 +316,7 @@ window.__ModuleLoader__.load({
 				runwaySafe: "安全",
 				noUsage: "配额不可用。",
 				usageError: "配额错误",
+				usageStale: "显示上次成功读取的配额；最新刷新失败。",
 				refresh: "刷新",
 				refreshed: "已刷新",
 				loading: "加载中…",
@@ -354,6 +365,7 @@ window.__ModuleLoader__.load({
 				heatmapAllAccounts: "全部账户",
 				analyticsHint: "按最后活动时间聚合本地会话元数据。切换过模型的会话计入最后使用的模型；本地投影不暴露失败。仅统计插件路由；旧 opencode 会话属于内置目录。",
 				analyticsPartial: "此报告不完整：投影扫描达到文件上限或跳过了不可读文件。",
+				analyticsStale: "显示上次成功扫描的结果；最新刷新失败。",
 				analyticsEmpty: "此窗口内没有插件会话。旧 opencode 会话属于内置目录。",
 				showAll: "显示全部",
 				modelSearch: "搜索模型…",
@@ -410,6 +422,8 @@ window.__ModuleLoader__.load({
 				routingFailed: "失败",
 				quotaFallbackModel: "配额回退模型",
 				quotaFallbackModelHint: "Go 返回配额错误时，通过 Console/Zen 用此免费模型重试一次。",
+				autoSwitch: "自动切换账户",
+				autoSwitchHint: "当前账户额度耗尽或凭据失败时，在输出前尝试下一个账户。关闭后只使用选定账户。",
 				stickySession: "每个会话固定账户",
 				stickySessionHint: "同一会话优先使用上次成功的账户；显式模型规则和固定账户优先。",
 				off: "关闭",
@@ -1006,6 +1020,10 @@ window.__ModuleLoader__.load({
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "oc-bars",
 				children: [
+					usage.stale === true ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
+						className: "oc-hint",
+						children: [t("usageStale"), usage.lastSuccessAt === void 0 ? "" : ` (${new Date(usage.lastSuccessAt).toLocaleTimeString()})`]
+					}) : null,
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Row, {
 						label: t("fiveHour"),
 						window: windows.fiveHour
@@ -1334,6 +1352,7 @@ window.__ModuleLoader__.load({
 			const [stateError, setStateError] = (0, react.useState)(null);
 			const [analytics, setAnalytics] = (0, react.useState)(null);
 			const [analyticsError, setAnalyticsError] = (0, react.useState)(null);
+			const [analyticsStale, setAnalyticsStale] = (0, react.useState)(false);
 			const [days, setDays] = (0, react.useState)(7);
 			const [busy, setBusy] = (0, react.useState)(false);
 			const analyticsSeq = (0, react.useRef)(0);
@@ -1349,14 +1368,16 @@ window.__ModuleLoader__.load({
 				const seq = analyticsSeq.current + 1;
 				analyticsSeq.current = seq;
 				setAnalyticsError(null);
+				setAnalyticsStale(analytics !== null);
 				fetchAnalytics(windowDays).then((next) => {
 					if (seq !== analyticsSeq.current) return;
 					setAnalytics(next);
 					setAnalyticsError(null);
+					setAnalyticsStale(false);
 				}).catch((caught) => {
 					if (seq !== analyticsSeq.current) return;
-					setAnalytics(null);
 					setAnalyticsError(caught instanceof Error ? caught.message : "analytics failed");
+					setAnalyticsStale(analytics !== null);
 				});
 			};
 			(0, react.useEffect)(() => {
@@ -1573,59 +1594,69 @@ window.__ModuleLoader__.load({
 							children: t("intro")
 						})]
 					}),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("section", {
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
 						className: "oc-card",
-						children: analyticsError !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+						children: [
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
 								className: "oc-card-title",
 								children: t("usageAnalytics")
 							}),
-							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
+							analyticsError !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
 								className: "oc-hint",
 								children: [
 									t("failed"),
 									": ",
 									analyticsError
 								]
-							}),
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							}) : null,
+							analyticsStale && analytics !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "oc-hint",
+								children: t("analyticsStale")
+							}) : null,
+							analyticsError !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								type: "button",
 								className: "oc-button",
 								onClick: () => loadAnalytics(days),
 								children: t("refresh")
+							}) : null,
+							analytics === null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "oc-hint",
+								children: t("loading")
+							}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(UsageAnalyticsView, {
+								analytics,
+								t,
+								days,
+								onDays: setDays
 							})
-						] }) : analytics === null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
-							className: "oc-card-title",
-							children: t("usageAnalytics")
-						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-							className: "oc-hint",
-							children: t("loading")
-						})] }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(UsageAnalyticsView, {
-							analytics,
-							t,
-							days,
-							onDays: setDays
-						})
+						]
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
 						className: "oc-card",
-						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
-							className: "oc-card-title",
-							children: t("requestHeatmap")
-						}), analyticsError !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
-							className: "oc-hint",
-							children: [
-								t("failed"),
-								": ",
-								analyticsError
-							]
-						}) : analytics === null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-							className: "oc-hint",
-							children: t("loading")
-						}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(RequestHeatmapView, {
-							heatmap: analytics.heatmap,
-							t
-						})]
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
+								className: "oc-card-title",
+								children: t("requestHeatmap")
+							}),
+							analyticsError !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
+								className: "oc-hint",
+								children: [
+									t("failed"),
+									": ",
+									analyticsError
+								]
+							}) : null,
+							analyticsStale && analytics !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "oc-hint",
+								children: t("analyticsStale")
+							}) : null,
+							analytics === null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "oc-hint",
+								children: t("loading")
+							}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(RequestHeatmapView, {
+								heatmap: analytics.heatmap,
+								t
+							})
+						]
 					})
 				]
 			});
@@ -1653,6 +1684,7 @@ window.__ModuleLoader__.load({
 				accounts: state.config.accounts.map((account) => ({ ...account })),
 				modelAccountRules: state.config.modelAccountRules.map((rule) => ({ ...rule })),
 				quotaFallbackModel: state.config.quotaFallbackModel,
+				autoSwitch: state.config.autoSwitch !== false,
 				stickySession: state.config.stickySession,
 				visibleModels: state.config.visibleModels.length === 0 ? allIds : [...state.config.visibleModels],
 				filterModelsByPlan: state.config.filterModelsByPlan,
@@ -1704,6 +1736,7 @@ window.__ModuleLoader__.load({
 					account: rule.account.trim()
 				})).filter((rule) => rule.pattern !== "" && rule.account !== ""),
 				quotaFallbackModel: draft.quotaFallbackModel.trim(),
+				autoSwitch: draft.autoSwitch,
 				stickySession: draft.stickySession,
 				visibleModels: draft.showAll ? [] : draft.visibleModels,
 				filterModelsByPlan: draft.filterModelsByPlan,
@@ -1935,6 +1968,7 @@ window.__ModuleLoader__.load({
 			const [importing, setImporting] = (0, react.useState)(false);
 			const [checking, setChecking] = (0, react.useState)(null);
 			const [dragFrom, setDragFrom] = (0, react.useState)(null);
+			const [pendingCleanup, setPendingCleanup] = (0, react.useState)([]);
 			const load = (0, react.useCallback)(async () => {
 				setLoading(true);
 				try {
@@ -1964,12 +1998,25 @@ window.__ModuleLoader__.load({
 				setSaving(true);
 				setError(null);
 				try {
-					await saveConfig(patchOf(draft), draft.revision);
+					const patch = patchOf(draft);
+					await saveConfig(patch, draft.revision);
+					const stillUsed = new Set(patch.accounts.map((account) => account.apiKeyEnv?.trim() ?? "").filter((ref) => ref !== ""));
+					let cleanupError = null;
+					for (const ref of pendingCleanup) {
+						if (stillUsed.has(ref)) continue;
+						try {
+							await clearKey(ref);
+						} catch (caught) {
+							cleanupError = caught instanceof Error ? caught.message : String(caught);
+						}
+					}
+					setPendingCleanup([]);
 					window.dispatchEvent(new CustomEvent(CONFIG_CHANGED_EVENT));
 					setNotice(t("saved"));
 					setState(null);
 					setDraft(null);
 					await load();
+					if (cleanupError !== null) setError(`${t("accountCleanupFailed")} ${cleanupError}`);
 				} catch (caught) {
 					setError(caught instanceof Error ? caught.message : t("saveFailed"));
 				} finally {
@@ -2308,6 +2355,10 @@ window.__ModuleLoader__.load({
 									]
 								});
 							})(),
+							defaultAccount?.usage?.stale === true ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "oc-hint",
+								children: t("usageStale")
+							}) : null,
 							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 								className: "oc-row",
 								children: [
@@ -2409,8 +2460,8 @@ window.__ModuleLoader__.load({
 							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("h3", {
 								className: "oc-card-title",
 								children: [t("serviceStatus"), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-									className: `oc-badge ${state.service.usageCheckedAt === void 0 ? "oc-badge-warn" : state.service.usageError === void 0 ? "oc-badge-ok" : "oc-badge-bad"}`,
-									children: state.service.usageCheckedAt === void 0 ? t("notChecked") : state.service.usageError === void 0 ? t("serviceOk") : t("serviceDegraded")
+									className: `oc-badge ${state.service.usageCheckedAt === void 0 ? "oc-badge-warn" : state.service.usageError === void 0 && state.service.usageStale !== true ? "oc-badge-ok" : "oc-badge-bad"}`,
+									children: state.service.usageCheckedAt === void 0 ? t("notChecked") : state.service.usageError === void 0 && state.service.usageStale !== true ? t("serviceOk") : t("serviceDegraded")
 								})]
 							}),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
@@ -2421,7 +2472,7 @@ window.__ModuleLoader__.load({
 										children: t("usageEndpoint")
 									}),
 									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-										className: `oc-badge ${state.service.usageCheckedAt === void 0 ? "oc-badge-warn" : state.service.usageError === void 0 ? "oc-badge-ok" : "oc-badge-bad"}`,
+										className: `oc-badge ${state.service.usageCheckedAt === void 0 ? "oc-badge-warn" : state.service.usageError === void 0 && state.service.usageStale !== true ? "oc-badge-ok" : "oc-badge-bad"}`,
 										children: state.service.usageCheckedAt === void 0 ? t("notChecked") : t("checkedAt").replace("{time}", new Date(state.service.usageCheckedAt).toLocaleTimeString())
 									}),
 									state.service.usageLatencyMs === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
@@ -2434,6 +2485,10 @@ window.__ModuleLoader__.load({
 								className: "oc-hint",
 								children: state.service.usageError
 							}),
+							state.service.usageStale === true ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "oc-hint",
+								children: t("usageStale")
+							}) : null,
 							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 								className: "oc-row",
 								children: [
@@ -2592,7 +2647,11 @@ window.__ModuleLoader__.load({
 												known === void 0 || known.mark === "" ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 													className: "oc-badge oc-badge-bad",
 													children: accountMark(known, t)
-												})
+												}),
+												known?.managed === true ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+													className: "oc-badge",
+													children: t("managedKey")
+												}) : null
 											]
 										}),
 										known?.usage?.report === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
@@ -2611,6 +2670,10 @@ window.__ModuleLoader__.load({
 												known.usage.error
 											]
 										}),
+										known?.usage?.stale === true ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+											className: "oc-hint",
+											children: t("usageStale")
+										}) : null,
 										/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 											className: "oc-row",
 											children: [
@@ -2661,6 +2724,10 @@ window.__ModuleLoader__.load({
 													type: "button",
 													className: "oc-button oc-button-danger",
 													onClick: () => {
+														const ref = account.apiKeyEnv.trim();
+														const managed = known?.managed === true && ref !== "";
+														if (managed && !window.confirm(t("removeAccountConfirm").replace("{ref}", ref))) return;
+														if (managed) setPendingCleanup((current) => current.includes(ref) ? current : [...current, ref]);
 														setKeyDrafts({});
 														update({ accounts: draft.accounts.filter((_, i) => i !== index) });
 													},
@@ -2796,6 +2863,18 @@ window.__ModuleLoader__.load({
 								className: "oc-hint",
 								children: t("routingHint")
 							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+								className: "oc-row",
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+									type: "checkbox",
+									checked: draft.autoSwitch,
+									onChange: (event) => update({ autoSwitch: event.target.checked })
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: t("autoSwitch") })]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+								className: "oc-hint",
+								children: t("autoSwitchHint")
+							}),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
 								className: "oc-row",
 								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {

package/lib/index.d.ts

@@ -60,6 +60,8 @@ interface Config {
   modelAccountRules?: ModelAccountRule[];
   /** Free model used once when the Go quota rejects a request; empty disables it. */
   quotaFallbackModel?: string;
+  /** Try the next account after a pre-stream quota/credential failure. */
+  autoSwitch?: boolean;
   /** Prefer the last successful account for a conversation. */
   stickySession?: boolean;
   /** Pinned account id; empty means automatic. */
@@ -92,6 +94,7 @@ interface ResolvedConfig {
   accounts: readonly AccountConfig[];
   modelAccountRules: readonly ModelAccountRule[];
   quotaFallbackModel: string;
+  autoSwitch: boolean;
   stickySession: boolean;
   activeAccount: string;
   showSidebarQuota: boolean;
@@ -260,6 +263,9 @@ interface UsageResult {
   readonly keyStatus?: UsageKeyStatus;
   readonly latencyMs?: number;
   readonly checkedAt: number;
+  /** True when `report` is the last successful reading after a failed refresh. */
+  readonly stale?: boolean;
+  readonly lastSuccessAt?: number;
 }
 interface UsageWindowPayload {
   status?: string;
@@ -373,6 +379,8 @@ interface RouteDeps {
   readonly analytics?: (days: number) => Promise<AnalyticsReport>;
   readonly heatmap?: (days: number) => Promise<RequestHeatmap>;
   readonly refreshTui?: () => void;
+  /** Test seam; defaults to the local managed-credentials registry. */
+  readonly managedPath?: string;
 }
 /** Register the Host HTTP surface consumed by the browser settings page. */
 declare function applyRoutes(ctx: Context, web: WebServer, deps: RouteDeps): void;

package/lib/index.js

@@ -81,7 +81,7 @@ const DEFAULT_GO_API_BASE = "https://opencode.ai/inference/go";
 const DEFAULT_GO_ZEN_BASE = "https://opencode.ai/zen/go/v1";
 const DEFAULT_USAGE_URL = "https://opencode.ai/zen/go/v1/usage";
 const DEFAULT_AUTH_ENTRY = "opencode-go";
-const DEFAULT_USER_AGENT = "dsh-opencode-provider/0.5.23";
+const DEFAULT_USER_AGENT = "dsh-opencode-provider/0.5.25";
 const DEFAULT_CONTEXT_WINDOW = 262144;
 const DEFAULT_MAX_TOKENS = 32768;
 const DEFAULT_GENERATE_MAX_TOKENS = 32768;
@@ -123,6 +123,7 @@ const Config = z.object({
 		account: z.string()
 	})).default([])),
 	quotaFallbackModel: markVolatile(z.string().default("")),
+	autoSwitch: markVolatile(z.boolean().default(true)),
 	stickySession: markVolatile(z.boolean().default(true)),
 	activeAccount: markVolatile(z.string().default("")),
 	showSidebarQuota: markVolatile(z.boolean().default(false)),
@@ -218,6 +219,7 @@ function resolveConfig(config) {
 		accounts: Array.isArray(config.accounts) ? config.accounts : [],
 		modelAccountRules: modelAccountRuleList(config.modelAccountRules),
 		quotaFallbackModel: typeof config.quotaFallbackModel === "string" ? config.quotaFallbackModel.trim() : "",
+		autoSwitch: config.autoSwitch !== false,
 		stickySession: config.stickySession !== false,
 		activeAccount: typeof config.activeAccount === "string" ? config.activeAccount : "",
 		showSidebarQuota: config.showSidebarQuota === true,
@@ -3327,8 +3329,9 @@ var OpenCodeAdapter = class extends LlmAdapter {
 		}
 		const eligible = fallback ? keys : keys.filter((entry) => !this.coolingDown(entry.key) && !this.modelCoolingDown(entry.key, options.model));
 		const ordered = eligible.length > 0 ? eligible : keys;
+		const candidates = config.autoSwitch ? ordered : ordered.slice(0, 1);
 		const forced = !fallback && eligible.length === 0;
-		const initial = ordered[0];
+		const initial = candidates[0];
 		const url = endpointFor(options.provider, model.transport, options.model, config);
 		let images;
 		if (hasImages(options)) {
@@ -3352,7 +3355,7 @@ var OpenCodeAdapter = class extends LlmAdapter {
 		let lastError;
 		let lastAccount = initial?.label ?? "default";
 		let loggedAny = false;
-		for (const [index, entry] of ordered.entries()) {
+		for (const [index, entry] of candidates.entries()) {
 			if (!fallback && !forced && (this.coolingDown(entry.key) || this.modelCoolingDown(entry.key, options.model))) continue;
 			lastAccount = entry.label ?? "default";
 			const attemptReason = index === 0 ? reason : "rotation";
@@ -3380,7 +3383,7 @@ var OpenCodeAdapter = class extends LlmAdapter {
 					const error = classifyResponseError(response.status, text, response.headers);
 					lastError = error;
 					logAttempt(false, error.code);
-					const canRotate = index < ordered.length - 1;
+					const canRotate = index < candidates.length - 1;
 					if (error.code === "INVALID_CREDENTIAL" || error.code === "RATE_LIMIT" || error.code === "QUOTA") {
 						if (!fallback) this.markRejection(entry.key, options.model, response.status, response.headers, error.code);
 						responseFailure = true;
@@ -3425,8 +3428,8 @@ var OpenCodeAdapter = class extends LlmAdapter {
 				lastError = classified;
 				const transient = this.isTransient(classified);
 				if (transient && !responseFailure && !fallback) this.markRejection(entry.key, options.model, 0, void 0, classified.code);
-				if (!(index < ordered.length - 1 && transient)) {
-					if (!fallback && config.quotaFallbackModel !== "" && isGoProvider(options.provider) && classified.code === "QUOTA") break;
+				if (!(index < candidates.length - 1 && transient)) {
+					if (!fallback && config.autoSwitch && config.quotaFallbackModel !== "" && isGoProvider(options.provider) && classified.code === "QUOTA") break;
 					throw classified;
 				}
 			}
@@ -3448,7 +3451,7 @@ var OpenCodeAdapter = class extends LlmAdapter {
 			ok: false,
 			error: finalError.code
 		});
-		if (!fallback && config.quotaFallbackModel !== "" && isGoProvider(options.provider) && (lastError === void 0 || lastError.code === "QUOTA")) try {
+		if (!fallback && config.autoSwitch && config.quotaFallbackModel !== "" && isGoProvider(options.provider) && (lastError === void 0 || lastError.code === "QUOTA")) try {
 			yield* this.run({
 				...options,
 				provider: CONSOLE_PROVIDER,
@@ -4661,6 +4664,44 @@ async function readModelAnalytics(days = 30) {
 	});
 	return report;
 }
+// src/managed-credentials.ts
+const REF_LIMIT = 128;
+function managedCredentialsPath() {
+	const home = process.env.DSH_HOME?.trim() || join(homedir(), ".dsh");
+	return join(home, "storages", "dsh-opencode", "managed-credentials.json");
+}
+function validRef(value) {
+	return typeof value === "string" && value !== "" && value.length <= REF_LIMIT;
+}
+async function readRefs(path) {
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf8"));
+		if (!Array.isArray(parsed.refs)) return /* @__PURE__ */ new Set();
+		return new Set(parsed.refs.filter(validRef));
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+async function writeRefs(path, refs) {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, JSON.stringify({ refs: [...refs].sort() }), "utf8");
+}
+async function readManagedCredentialRefs(path = managedCredentialsPath()) {
+	return readRefs(path);
+}
+async function mutate(path, ref, add) {
+	if (!validRef(ref)) return;
+	const refs = await readRefs(path);
+	if (add) refs.add(ref);
+	else refs.delete(ref);
+	await writeRefs(path, refs);
+}
+async function addManagedCredentialRef(ref, path = managedCredentialsPath()) {
+	await mutate(path, ref, true);
+}
+async function removeManagedCredentialRef(ref, path = managedCredentialsPath()) {
+	await mutate(path, ref, false);
+}
 // src/routes-public.ts
 function publicConfig(config) {
 	return {
@@ -4690,6 +4731,7 @@ function publicConfig(config) {
 			account: rule.account
 		})),
 		quotaFallbackModel: config.quotaFallbackModel,
+		autoSwitch: config.autoSwitch,
 		stickySession: config.stickySession,
 		activeAccount: config.activeAccount,
 		showSidebarQuota: config.showSidebarQuota,
@@ -4878,6 +4920,7 @@ function configOps(patch) {
 	if ("accounts" in patch) set("accounts", cleanAccounts(patch.accounts));
 	if ("modelAccountRules" in patch) set("modelAccountRules", cleanModelAccountRules(patch.modelAccountRules));
 	if ("quotaFallbackModel" in patch) set("quotaFallbackModel", patch.quotaFallbackModel);
+	if ("autoSwitch" in patch) set("autoSwitch", patch.autoSwitch === true);
 	if ("stickySession" in patch) set("stickySession", patch.stickySession === true);
 	if ("activeAccount" in patch) set("activeAccount", patch.activeAccount);
 	if ("showSidebarQuota" in patch) set("showSidebarQuota", patch.showSidebarQuota === true);
@@ -4911,6 +4954,7 @@ async function buildState(ctx, deps) {
 	}));
 	const usageByLabel = /* @__PURE__ */ new Map();
 	for (const entry of resolved) usageByLabel.set(entry.label ?? "default", usageByKey.get(entry.key) ?? null);
+	const managedRefs = await readManagedCredentialRefs(deps.managedPath);
 	const slots = [{
 		label: "default",
 		ref: config.apiKeyEnv,
@@ -4951,7 +4995,8 @@ async function buildState(ctx, deps) {
 			coolingUntil: health?.coolingUntil ?? 0,
 			mark: health?.reason ?? "",
 			keyStatus,
-			usage
+			usage,
+			managed: slot.ref !== "" && managedRefs.has(slot.ref)
 		});
 	}
 	let models = [];
@@ -4988,7 +5033,8 @@ async function buildState(ctx, deps) {
 		service: {
 			...usage?.checkedAt === void 0 ? {} : { usageCheckedAt: usage.checkedAt },
 			...usage?.latencyMs === void 0 ? {} : { usageLatencyMs: usage.latencyMs },
-			...usage?.error === void 0 ? {} : { usageError: usage.error }
+			...usage?.error === void 0 ? {} : { usageError: usage.error },
+			...usage?.stale === true ? { usageStale: true } : {}
 		},
 		routing: deps.adapter.routingTrace(),
 		auth: {
@@ -5125,6 +5171,7 @@ function applyRoutes(ctx, web, deps) {
 				return;
 			}
 			await credentials.set(credentialRef(refName), key);
+			await addManagedCredentialRef(refName, deps.managedPath);
 			json(res, 200, {
 				ok: true,
 				ref: refName
@@ -5144,6 +5191,7 @@ function applyRoutes(ctx, web, deps) {
 			const body = await readJson(req);
 			const refName = typeof body.ref === "string" && body.ref.trim() !== "" ? body.ref.trim() : deps.config().apiKeyEnv;
 			await credentials.unset(credentialRef(refName));
+			await removeManagedCredentialRef(refName, deps.managedPath);
 			json(res, 200, {
 				ok: true,
 				ref: refName
@@ -5169,6 +5217,7 @@ function applyRoutes(ctx, web, deps) {
 				return;
 			}
 			await credentials.set(credentialRef(ref), key);
+			await addManagedCredentialRef(ref, deps.managedPath);
 			json(res, 200, {
 				ok: true,
 				entry,
@@ -5404,6 +5453,18 @@ function buildOpenCodeTuiSection(deps) {
 				format: () => deps.quotaFallbackModel(),
 				parse: setOrClear
 			},
+			{
+				path: ["autoSwitch"],
+				group: "advanced",
+				kind: "boolean",
+				label: "Automatic account failover",
+				hint: "Try the next account before output on quota or credential failure.",
+				format: (value) => String(value === void 0 ? deps.autoSwitch() : value !== false),
+				parse: (text) => ({
+					kind: "set",
+					value: text.trim() === "true"
+				})
+			},
 			{
 				path: ["stickySession"],
 				group: "advanced",
@@ -5558,6 +5619,8 @@ function fingerprint(key) {
 /** Cached reader for the (undocumented) Go usage endpoint. Fail-open by design. */
 function createUsageReader(config, resolveKey, fetchImpl = fetch) {
 	const cache = /* @__PURE__ */ new Map();
+	/** Last successful reading per key, kept across explicit cache clears. */
+	const lastSuccess = /* @__PURE__ */ new Map();
 	const read = async (provider, explicitKey) => {
 		if (provider !== "opencode-go-direct" && provider !== "opencode-go") return void 0;
 		const current = config();
@@ -5575,7 +5638,7 @@ function createUsageReader(config, resolveKey, fetchImpl = fetch) {
 		const cacheKey = `${provider}:${fingerprint(key)}`;
 		const cached = cache.get(cacheKey);
 		if (cached !== void 0) {
-			const ttl = cached.report === void 0 ? FAILURE_TTL_MS : SUCCESS_TTL_MS;
+			const ttl = cached.report === void 0 || cached.stale === true ? FAILURE_TTL_MS : SUCCESS_TTL_MS;
 			if (Date.now() - cached.checkedAt < ttl) return cached;
 		}
 		const result = async () => {
@@ -5633,8 +5696,25 @@ function createUsageReader(config, resolveKey, fetchImpl = fetch) {
 			}
 		};
 		const fresh = await result();
-		cache.set(cacheKey, fresh);
-		return fresh;
+		const previous = cached?.report !== void 0 ? cached : lastSuccess.get(cacheKey);
+		if (fresh.report === void 0 && previous?.report !== void 0) {
+			const stale = {
+				...fresh,
+				report: previous.report,
+				stale: true,
+				lastSuccessAt: previous.lastSuccessAt ?? previous.checkedAt
+			};
+			cache.set(cacheKey, stale);
+			return stale;
+		}
+		const next = fresh.report === void 0 ? fresh : {
+			...fresh,
+			stale: false,
+			lastSuccessAt: fresh.checkedAt
+		};
+		if (next.report !== void 0) lastSuccess.set(cacheKey, next);
+		cache.set(cacheKey, next);
+		return next;
 	};
 	read.clear = () => {
 		cache.clear();
@@ -5711,6 +5791,7 @@ function apply(ctx, config) {
 			activeAccount: () => current().activeAccount,
 			filterModelsByPlan: () => current().filterModelsByPlan,
 			quotaFallbackModel: () => current().quotaFallbackModel,
+			autoSwitch: () => current().autoSwitch,
 			stickySession: () => current().stickySession,
 			showSidebarQuota: () => current().showSidebarQuota
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-opencode-provider",
-  "version": "0.5.23",
+  "version": "0.5.25",
   "description": "OpenCode / OpenCode Go LLM provider plugin for DeepSeek Harness (dsh).",
   "license": "MIT",
   "type": "module",