dsh-cursor-dev 0.12.1 → 0.12.2

package/README.md

@@ -55,7 +55,7 @@ flowchart LR
 3. 按 DSH 提示完成加载；涉及后台代码更新时重启 DSH，然后刷新页面。在 Cursor 面板中选择模型并保存。
 4. 明确告诉父模型使用 `cursor_code`，或者用下面的斜杠命令派发第一个任务。
 
-**版本说明（0.12.1）：** 本版新增 macOS Keychain 登录凭据读取，修正 CLI 子进程的代理默认值和直连时的环境变量继承：未配置时为 `none`（直连），主动留空时使用系统代理，填写 URL 时使用显式代理。已有空值配置保持系统代理语义，面板仍使用原来的输入框，没有 UI 改版。macOS Keychain 路径尚未实机验证。DSH 兼容性仍为 `>=0.2.1-rc.2 <0.3.0-0`。插件市场已收录本插件，卡片版本随目录探测更新；npm 包名为 `dsh-cursor-dev`，实际已发布版本以 npm 的 `latest` 标签为准。要跟进后续改动请用 Git 来源；`.tgz` 是某一刻的固定快照。详见[安装来源与版本](docs/INSTALL.md#2-选择安装来源)。
+**版本说明（0.12.2）：** 本版加入额度耗尽保护：调用 `cursor_code` 或通过原生子智能体派发之前先检查 Cursor 用量，总、Auto、API 三个额度都到上限时直接拒绝并说明原因，不再把任务派出去后中途失败；用量接口暂时取不到时不拦截调用。`cursor_subagent` 现在也会生成可点击的对话子会话，面板里点运行中或已完成的行都能查看过程，不再报「没有可恢复的会话」。面板重排为额度四张卡片置顶、代理输入框移到模型选择上方、模型目录与来源说明折叠收起。DSH 兼容性仍为 `>=0.2.1-rc.2 <0.3.0-0`。插件市场已收录本插件，卡片版本随目录探测更新；npm 包名为 `dsh-cursor-dev`，实际已发布版本以 npm 的 `latest` 标签为准。要跟进后续改动请用 Git 来源；`.tgz` 是某一刻的固定快照。详见[安装来源与版本](docs/INSTALL.md#2-选择安装来源)。
 
 运行要求：DSH `>=0.2.1-rc.2 <0.3.0-0`（已在 `0.2.1-rc.2` 上验证）；Node.js `^22.19.0 || >=24.0.0`；已登录且可访问服务的 Cursor CLI。原生子智能体功能需要 DSH 的 `subagents`、`agents` 服务，后台任务还需要对应任务服务，建议使用当前 DSH 桌面版。CLI 安装方法见 [Cursor 官方文档](https://cursor.com/docs/cli)。
 
@@ -65,7 +65,7 @@ flowchart LR
 | --- | --- | --- |
 | `cursor_code` | 父模型派发完整任务，控制目录、模式、模型、会话与报告 | 工具结果回到调用它的父模型，包含答复、步骤和检测到的文件变更 |
 | `/cursor-subagent 任务内容` | 用户直接派发一次任务；可选前缀 `-m 模型` | 完成或失败后，插件把摘要交给原父代理继续处理 |
-| `cursor_subagent` | 当前源码新增的 DSH 原生一次性子智能体工具，可后台运行 | 使用 DSH 标准结果及后台任务机制；DSH 0.2.1 起这次运行在父会话里显示为一行 External 任务，可点击的镜像子会话只由 `cursor_code` 创建 |
+| `cursor_subagent` | 当前源码新增的 DSH 原生一次性子智能体工具，可后台运行 | 使用 DSH 标准结果及后台任务机制；父会话保留一行 External 任务，Cursor 面板里的会话行可直接打开实时镜像子对话 |
 
 例如，在一个空测试工作区发送：
 
@@ -220,7 +220,7 @@ See the [installation guide](docs/INSTALL.md) for detailed setup and troubleshoo
 3. Restart DSH when backend changes require it, then refresh the page. Open the Cursor panel under `/plugins/dsh-cursor-dev/`, select a model and save it. The history list keeps one row per run forever, so it sits in a height-capped scroll box and folds away when you click its heading (the choice is remembered); a row's **Delete** link clears that run's index record, journal and mirrored child — the same chain `resetSession` uses — and arms on the first click so the irreversible second click is deliberate.
 4. Ask the parent to use `cursor_code`, or send `/cursor-subagent` followed by a complete task. The command dispatches directly and hands a completion or failure summary back to the original parent.
 
-Version `0.12.1` adds macOS Keychain credential lookup and fixes the child CLI's proxy defaults and inherited environment: a missing setting means `none` (direct), an explicitly empty value follows the system proxy, and a URL selects an explicit proxy. Existing empty settings keep their meaning. The panel still uses the same text input; this is not a UI redesign. The macOS Keychain path has not been verified on a real Mac. DSH compatibility remains `>=0.2.1-rc.2 <0.3.0-0`. The dsh-market catalog already lists this plugin and updates its displayed version on subsequent probes. The public npm package is `dsh-cursor-dev`; its `latest` tag identifies the published version. Use the Git source to follow later changes; a `.tgz` is a fixed snapshot.
+Version `0.12.2` adds quota exhaustion protection: before `cursor_code` or a native subagent call starts, the plugin reads Cursor usage and refuses the call, explaining why, when the total, Auto and API buckets are all at their limit — instead of dispatching a run that later fails mid-way. A usage lookup that cannot be completed never blocks a call. `cursor_subagent` now also creates a clickable transcript child, so rows for running and finished runs open in the panel instead of reporting that no durable conversation exists. The panel puts the four quota cards first, moves the proxy input above the model picker, and folds the model catalogue and the source/egress notes. DSH compatibility remains `>=0.2.1-rc.2 <0.3.0-0`. The dsh-market catalog already lists this plugin and updates its displayed version on subsequent probes. The public npm package is `dsh-cursor-dev`; its `latest` tag identifies the published version. Use the Git source to follow later changes; a `.tgz` is a fixed snapshot.
 
 Requirements: DSH `>=0.2.1-rc.2 <0.3.0-0` (verified against `0.2.1-rc.2`); Node.js `^22.19.0 || >=24.0.0`; an authenticated Cursor CLI account with service access. Native dispatch additionally needs DSH's `subagents` and `agents` services, and background runs need the host's job services. A current DSH desktop installation is recommended.
 
@@ -239,7 +239,7 @@ The default model order is call argument → saved panel choice → plugin confi
 
 The current source registers a native DSH provider named `cursor` and a standard one-shot tool named `cursor_subagent`. Rich `cursor_code` calls also use the native lifecycle when those host services exist. The existing generic `subagent` backend remains configured as before.
 
-Cursor executes externally. From DSH 0.2.1 on, the host writes a single non-interactive `External` row for a `cursor_subagent` run; the clickable mirrored child conversation is created by `cursor_code`, which starts the provider directly. Standard background runs use DSH's job result and cancellation tools. Persistent mailbox continuation through `send_message`, and Cursor as a resident Agent Teams teammate, are not implemented. Use `cursor_code` with `continueSession` for explicit follow-ups.
+Cursor executes externally. From DSH 0.2.1 on, the host writes a single non-interactive `External` row for a `cursor_subagent` run. Both entrances also create a real transcript child that the Cursor panel opens while the first turn is running. The native service keeps its own lifecycle id; the separate transcript child does not add a duplicate catalog row. Standard background runs use DSH's job result and cancellation tools. Persistent mailbox continuation through `send_message`, and Cursor as a resident Agent Teams teammate, are not implemented. Use `cursor_code` with `continueSession` for explicit follow-ups.
 
 The parent remains responsible for reviewing the actual changes and verification evidence. File reports have scan limits and are not a substitute for final workspace checks. Cursor model availability and usage depend on the Cursor account; the parent model uses its separate DSH provider configuration.
 

package/docs/INSTALL.md

@@ -38,7 +38,7 @@ agent status --format json
 
 ## 2. 选择安装来源
 
-**当前源码版本：** `0.12.1`，新增 macOS Keychain 登录凭据读取，并修正 CLI 子进程的默认直连与代理环境变量继承；面板没有 UI 改版。macOS Keychain 路径尚未实机验证。DSH 兼容性保持 `>=0.2.1-rc.2 <0.3.0-0`。npm 包名为 `dsh-cursor-dev`，实际已发布版本以 npm 的 `latest` 标签为准。插件市场已收录本插件，卡片版本随目录探测更新。
+**当前源码版本：** `0.12.2`，新增额度耗尽保护（三个额度都到上限时提前拒绝，用量取不到时不拦截），`cursor_subagent` 生成的子会话可在面板点开查看轨迹，面板重排为额度置顶、代理输入框在模型选择上方。DSH 兼容性保持 `>=0.2.1-rc.2 <0.3.0-0`。npm 包名为 `dsh-cursor-dev`，实际已发布版本以 npm 的 `latest` 标签为准。插件市场已收录本插件，卡片版本随目录探测更新。
 
 | 你要安装的内容 | 安装来源 |
 | --- | --- |
@@ -46,7 +46,7 @@ agent status --format json
 | npm 公共源上的已发布版本 | `dsh-cursor-dev`（`0.11.0` 起可用，按包内 `files` 白名单安装，版本以 npm 的 `latest` 标签为准） |
 | 公开仓库的当前版本（推荐） | `git+https://github.com/Dclef/dsh-cursor-dev.git` |
 | 你本地的源码目录 | 该目录的绝对路径，例如 `D:/plugins/dsh-cursor-dev` |
-| 维护者提供的源码快照或发布包 | `.tgz` 文件的绝对路径，例如 `D:/Downloads/dsh-cursor-dev-0.12.1.tgz` |
+| 维护者提供的源码快照或发布包 | `.tgz` 文件的绝对路径，例如 `D:/Downloads/dsh-cursor-dev-0.12.2.tgz` |
 
 表中本地路径是示例，需要换成实际位置。npm 来源取 registry 上发布的最新版本；Git 来源会取得仓库默认分支的最新提交；`.tgz` 是某一刻的固定快照——要跟进后续改动就用 Git 来源。
 
@@ -88,7 +88,7 @@ dsh plugin add "/home/you/plugins/dsh-cursor-dev"
 安装收到的包：
 
 ```powershell
-dsh plugin add "D:/Downloads/dsh-cursor-dev-0.12.1.tgz"
+dsh plugin add "D:/Downloads/dsh-cursor-dev-0.12.2.tgz"
 ```
 
 终端没有 `dsh` 命令时，使用桌面插件管理即可。不要把在任意项目目录执行 `npm install` 当成已经在 DSH 当前 profile 中启用插件。
@@ -202,7 +202,7 @@ continueSession 设为 true。让 Cursor 说明上一轮做了什么，再核对
 | 显示 usage limit | 检查 Cursor 账号额度和模型可用性；更换父模型不会改变 Cursor 账号额度 |
 | 父模型没有调用插件 | 确认插件已启用、工具允许使用且父模型支持工具调用；明确要求使用 `cursor_code` 或直接用斜杠命令 |
 | 有 `cursor_code`，没有 `cursor_subagent` | 确认所装版本包含原生接入、bundle 配置已应用，以及当前 profile 提供子智能体和任务服务；升级后重启 |
-| DSH 升到 0.2.1 后 `cursor_subagent` 不再有可点击的镜像子会话 | 0.2.1 起宿主只用一行 External 任务表示外部子智能体，本插件的镜像因此只保留在 `cursor_code` 路径；运行结果、取消和后台机制不变 |
+| 点击运行中的 `cursor_subagent` 会话只显示运行轨迹 | 更新插件后台并重启 DSH；新版从首轮运行时即建立镜像，在 Cursor 面板中点击会话键即可打开子对话。宿主仍保留一行 External 任务；旧版本留下的已完成记录可在历史会话中读回 |
 | 更新后页面还是旧的 | 检查更新的是当前 profile 中实际加载的包，再重启 DSH 并刷新浏览器；只修改另一份源码不会自动更新所有安装副本 |
 | 续聊没有原来的内容 | 确认父会话、`sessionLabel` 和工作区；检查是否重置过映射、删除过 Cursor 记录，或发生了加载失败回退 |
 | 想彻底开始新任务 | 使用新 `sessionLabel`，或对原标签设置 `resetSession:true`；不要只依赖 `continueSession:false` 清空历史 |

package/docs/skill-drafts/subagent-model-routing/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: subagent-model-routing
+description: 调用 subagent、选择子智能体模型或排查 provider/model/reasoning_effort 路由错误时使用；默认省略路由字段，指定前查询目录，禁止空字符串与猜测路由。
+---
+
+# 子智能体模型路由与参数校验
+
+## 适用范围
+
+调用 `subagent`、选择子智能体的提供方、模型或推理等级，或排查以下错误时使用：
+
+- `Error: child LLM \`provider\` must be non-empty`
+- 子智能体模型路由不被当前 Session 允许
+- provider 与 model 不成对，或推理等级无效
+
+本技能只约束子智能体模型参数。用户明确指定专家、专家团或其他工具时，遵守对应工具的要求。
+
+## 调用规则
+
+1. **使用默认模型时，省略 provider、model、reasoning_effort 三个键。** 不用空字符串、空白字符串、null 或猜测值表示默认。
+2. **显式指定模型前，先调用 list_subagent_models。** 先查提供方，再按需查模型及其推理等级。使用返回的 ID，不从父会话模型、自身模型身份或显示名称推断。
+3. **provider 和 model 必须成对且非空。** 只有一个字段时，先补齐可验证的信息；本意为默认时，删除全部路由字段。
+4. **reasoning_effort 只使用目标模型公布的有效值。** 不要求固定等级时省略；不要硬套父模型等级。
+5. **目录与当前 Session 的允许路由分别校验。** 目录存在不保证当前会话允许。如果路由被拒绝，不猜另一个提供方、不反复碰撞。默认模型满足用户要求时，删除全部路由字段重试一次；用户锁定模型时，说明具体限制，不擅自替换。
+6. **不同工具的模型接口不能混用。** subagent 的路由、cursor_code 的 Cursor 模型、cursor_subagent 的默认配置和专家工具的专家名称不是同一接口。subagent_fork 不接受这些模型覆盖字段。
+7. **只发送实际需要的受支持字段。** 不为填满对象而给可选字段补空字符串。若调用层强制要求这些字段，检查正确调用方式；仍无法表达省略时报告接口限制，不伪造 ID。
+
+## 发送前检查
+
+- 默认调用：三个可选键都不存在。
+- 指定调用：provider/model 是已查证、成对的非空 ID。
+- reasoning_effort 若存在，与目标模型匹配。
+- prompt 是完整、可独立执行的任务说明；cwd 是实际工作区。
+- 没有把父会话或其他工具的模型名称当作已验证路由。
+
+## 默认调用示例
+
+```json
+{
+  "cwd": "E:/example/project",
+  "description": "核对额度显示逻辑",
+  "prompt": "只读检查当前工作区的额度规范化和显示逻辑，给出字段语义与最小修复建议，不修改文件。"
+}
+```
+
+指定模型时，查询目录后把返回的 provider/model 成对加入。仅在需要固定、且已确认有效时加入 reasoning_effort。本技能不保存固定提供方、模型或等级示例值，以免以后照抄失效。
+
+禁止发送：
+
+```json
+{
+  "provider": "",
+  "model": "",
+  "reasoning_effort": ""
+}
+```
+
+## 失败后的处理
+
+- provider must be non-empty：检查是否把可选字段传成空字符串；默认分支删除三个键，再调用一次。
+- provider/model 不成对：查询目录并补齐，或切回省略全部路由字段的默认分支。
+- 路由不允许：按会话权限限制处理，不通过改拼写绕过。
+- 推理等级无效：查询目标模型详情；不需要固定时省略。
+- 参数校验失败时，子智能体没有启动。只有成功结果包含子智能体 ID，才记为已启动；交付前必须收集实际结果。
+
+修正参数后继续用户已授权的原任务；不要将工具参数错误归因于用户项目或账户额度。

package/lib/index.js

@@ -26,6 +26,7 @@ import { registerCursorCommand } from './command.js';
 import { createMirrorHub } from './mirror.js';
 import { createRouteFence } from './fence.js';
 import { UsageClient, registerUsageRoutes } from './usage.js';
+import { CursorQuotaGuard } from './quota-guard.js';
 import { effectiveModel, readSettings, registerSettingsRoutes, resolveModelSelection } from './settings.js';
 import { createNativeCursorBridge } from './native-provider.js';
 import { describeProxy, proxySettingIsDirect, resolveChildProxy, withProxyEnvironment } from './proxy.js';
@@ -174,6 +175,8 @@ export function apply(ctx, config) {
     // transcript Cursor actually produced. `bind` learns the `agents` service
     // from a context that declared the dependency, because reading it off this
     // fiber answers `undefined` while the agent loop is still activating.
+    const usage = new UsageClient({ baseUrl: config.usageBaseUrl });
+    const quotaGuard = new CursorQuotaGuard(usage);
     const mirrors = createMirrorHub({ logger, maxChildDepth: config.maxChildDepth });
     const pool = resolved === undefined
         ? new UnavailablePool()
@@ -195,6 +198,7 @@ export function apply(ctx, config) {
         index,
         logger,
         mirrors,
+        quotaGuard,
         maxScanFiles: config.maxScanFiles,
         maxChildDepth: config.maxChildDepth,
         unavailable,
@@ -207,7 +211,7 @@ export function apply(ctx, config) {
         resolveDefaultMode: () => readSettings(dataDir).mode,
     });
 
-    const native = createNativeCursorBridge({ execute: rawTool.execute, mirrors, maxChildDepth: config.maxChildDepth });
+    const native = createNativeCursorBridge({ execute: rawTool.execute, mirrors, quotaGuard, maxChildDepth: config.maxChildDepth });
     const tool = { ...rawTool, execute: (args, exec) => native.execute(args, exec) };
     const disposeTool = ctx.tools.register({ ...tool, name: config.toolName });
 
@@ -256,6 +260,8 @@ export function apply(ctx, config) {
         dataDir,
         logger,
         mirrors,
+        usage,
+        quotaGuard,
         // The status route asks the CLI whether the account is signed in, which
         // means spawning it — same environment the ACP child gets.
         env: childEnvironment,
@@ -304,9 +310,9 @@ function mountHttpSurfaces(ctx, config, deps) {
             // the dashboard RPC itself and serves both a JSON view and a
             // self-contained HTML dashboard.
             if (config.usageUi === true) {
-                const usage = new UsageClient({ baseUrl: config.usageBaseUrl });
                 disposers.push(registerUsageRoutes(webCtx, {
-                    usage,
+                    usage: deps.usage,
+                    quotaGuard: deps.quotaGuard,
                     pool: deps.pool,
                     journal: deps.journal,
                     index: deps.index,

package/lib/native-provider.js

@@ -5,6 +5,7 @@ import { isAbsolute } from 'node:path';
 import { stat } from 'node:fs/promises';
 import { renderCursorReport } from './tool.js';
 import { resolveChildDepth } from './mirror.js';
+import { quotaBlockedMessage } from './quota-guard.js';
 
 export const CURSOR_PROVIDER = 'cursor';
 
@@ -33,7 +34,7 @@ function failure(error, cancelled = false) {
 
 /** Generic native calls use the panel settings and get their own conversation.
  * The cursor_code adapter supplies provider-private arguments for rich controls. */
-export function createCursorProvider({ execute, mirrors, maxChildDepth }) {
+export function createCursorProvider({ execute, mirrors, quotaGuard, maxChildDepth }) {
     const active = new Set();
     let closed = false;
     return {
@@ -52,15 +53,17 @@ export function createCursorProvider({ execute, mirrors, maxChildDepth }) {
                 throw new Error('cursor: native prompts must contain text blocks only');
             const task = request.prompt.map(block => block.text).join('\n\n').trim();
             if (!task) throw new Error('cursor: native prompt must not be empty');
+            const quotaStatus = await quotaGuard?.check?.();
+            if (quotaStatus?.blocked === true)
+                throw new Error(quotaBlockedMessage(quotaStatus));
             const originalParent = request.parent;
             // The recursion budget is the plugin's own now that the host leaves it
             // to the provider (`maxDepth: provider-managed`); refuse before any
             // process, child row, or lifecycle event exists.
             if (typeof maxChildDepth === 'number') resolveChildDepth(originalParent, maxChildDepth);
-            // dsh >= 0.2.1 starts native providers through the subagents service.
-            // That service only accepts an unregistered child id and models such a
-            // child as an external row without a local transcript, so the mirror
-            // belongs to the cursor_code bridge, which starts the provider directly.
+            // Keep the service's external lifecycle id separate from the local
+            // transcript child. The mirror is opened explicitly by the panel
+            // and does not publish another catalog row.
             const viaService = request.cursor === undefined;
             const args = request.cursor?.args ?? { task, sessionLabel: `native-${randomUUID()}` };
             const requestedCwd = typeof request.cwd === 'string' && request.cwd !== ''
@@ -82,15 +85,14 @@ export function createCursorProvider({ execute, mirrors, maxChildDepth }) {
             let settled = false;
             let disposal;
             const cursorLifecycle = {
-                descriptor: request.descriptor,
+                // The service descriptor belongs to its external row.
+                descriptor: viaService ? undefined : request.descriptor,
                 label: request.label,
                 acquired(session) { leasedSession = session; },
-                ...(viaService ? { mirror: false } : {
-                    opened(entry, key) {
-                        opened = { entry, key };
-                        ready.resolve();
-                    },
-                }),
+                opened(entry, key) {
+                    opened = { entry, key };
+                    ready.resolve();
+                },
             };
             const execution = Promise.resolve().then(() => execute({ ...args, workspaceRoot: cwd }, {
                 agent: originalParent,
@@ -125,8 +127,8 @@ export function createCursorProvider({ execute, mirrors, maxChildDepth }) {
                 }
             })().finally(() => active.delete(dispose));
             active.add(dispose);
-            // The service owns the child row for external runs; hand it a fresh id
-            // and let it observe `result`, without waiting for a mirror child.
+            // Publish the external lifecycle immediately, including while queued.
+            // Its id stays distinct from the panel's real transcript child.
             if (viaService)
                 return { id: `cursor-${randomUUID()}`, result, cursorReport, dispose };
             try {
@@ -168,13 +170,13 @@ function announceMirror(parent, child, label) {
 }
 
 /** Late-bound native service; absence preserves the existing standalone tool. */
-export function createNativeCursorBridge({ execute, mirrors, maxChildDepth }) {
+export function createNativeCursorBridge({ execute, mirrors, quotaGuard, maxChildDepth }) {
     let binding;
     return {
         bind(ctx) {
             const runtime = ctx.get?.('subagents');
             if (typeof runtime?.registerProvider !== 'function') return;
-            const provider = createCursorProvider({ execute, mirrors, maxChildDepth });
+            const provider = createCursorProvider({ execute, mirrors, quotaGuard, maxChildDepth });
             const unregister = runtime.registerProvider(provider);
             const current = { runtime, provider };
             binding = current;

package/lib/quota-guard.js

@@ -0,0 +1,113 @@
+const RECHECK_MS = 30_000;
+
+const QUOTA_ERROR = /\b(?:resource[_ -]?exhausted|insufficient[_ -]?quota|quota[_ -]?exceeded|credit[_ -]?balance[_ -]?exhausted)\b|\b(?:insufficient|out of|no remaining|zero|empty|exhausted|depleted)\b.{0,50}\b(?:cursor\s+)?(?:usage|quota|credits?|balance)\b|\b(?:cursor\s+)?(?:usage|quota|credits?|balance)\b.{0,50}\b(?:exhausted|depleted|used up|is empty|limit (?:has been )?reached|limit exceeded|insufficient)\b|\b(?:you(?:'ve| have) hit your usage limit|usage limit has been reached|no usage credits remaining)\b/i;
+
+/** Only the explicit upstream bucket percentages can establish global exhaustion. */
+export function usageQuotaExhausted(usage) {
+    const percentages = ['total', 'auto', 'api'].map(name => usage?.[name]?.percentUsed);
+    return percentages.every(value => typeof value === 'number' && Number.isFinite(value) && value >= 100);
+}
+
+/** Inspect an actual Cursor/ACP failure, never the dashboard's advisory prose. */
+export function cursorQuotaFailure(error) {
+    const code = error?.code;
+    if (code === 8 || /^(?:RESOURCE_EXHAUSTED|INSUFFICIENT_QUOTA|QUOTA_EXCEEDED|CREDIT_BALANCE_EXHAUSTED)$/i.test(String(code ?? '')))
+        return true;
+    const parts = [error?.name, error?.message, error?.data?.message, error?.cause?.message];
+    if (typeof error === 'string') parts.push(error);
+    try {
+        if (error !== null && typeof error === 'object') parts.push(JSON.stringify(error));
+    }
+    catch { /* An unstringifiable error can still match its message/code. */ }
+    return QUOTA_ERROR.test(parts.filter(value => typeof value === 'string').join(' '));
+}
+
+export function quotaBlockedMessage(state) {
+    return state?.source === 'cursor-error'
+        ? 'CURSOR_QUOTA_EXHAUSTED: Cursor reported that its usage is exhausted. New Cursor child-agent runs are paused until a successful quota refresh confirms capacity has returned.'
+        : 'CURSOR_QUOTA_EXHAUSTED: Cursor reports that all usage buckets are exhausted. No child agent was started. Check the quota panel and retry after a successful refresh confirms capacity has returned.';
+}
+
+/** Shared gate for native subagent starts and direct cursor_code calls. */
+export class CursorQuotaGuard {
+    #usage;
+    #now;
+    #recheckMs;
+    #state = { blocked: false, source: 'unknown' };
+    #lastCheckAt = 0;
+    #revision = 0;
+    #inflight;
+
+    constructor(usage, options = {}) {
+        this.#usage = usage;
+        this.#now = options.now ?? Date.now;
+        this.#recheckMs = options.recheckMs ?? RECHECK_MS;
+    }
+
+    snapshot() {
+        return { ...this.#state };
+    }
+
+    async check() {
+        const now = this.#now();
+        if (this.#state.blocked && now - this.#lastCheckAt < this.#recheckMs)
+            return this.snapshot();
+        if (this.#inflight !== undefined)
+            return this.#inflight;
+
+        const revision = this.#revision;
+        this.#inflight = (async () => {
+            let snapshot;
+            try {
+                snapshot = await this.#usage?.get?.({ force: this.#state.blocked });
+            }
+            catch {
+                snapshot = undefined;
+            }
+            this.#lastCheckAt = this.#now();
+            if (revision !== this.#revision && this.#state.blocked)
+                return this.snapshot();
+            return this.observeUsage(snapshot);
+        })().finally(() => { this.#inflight = undefined; });
+        return this.#inflight;
+    }
+
+    observeUsage(snapshot) {
+        if (snapshot?.ok !== true) {
+            if (!this.#state.blocked)
+                this.#state = { blocked: false, source: 'unknown' };
+            return this.snapshot();
+        }
+        const fetchedAt = snapshot.fetchedAt;
+        if (this.#state.blocked
+            && (!Number.isFinite(fetchedAt) || fetchedAt <= this.#state.since))
+            return this.snapshot();
+        this.#lastCheckAt = this.#now();
+        if (usageQuotaExhausted(snapshot.usage)) {
+            this.#state = {
+                blocked: true,
+                source: 'usage',
+                reason: 'all-usage-buckets-exhausted',
+                since: Number.isFinite(fetchedAt) ? fetchedAt : this.#now(),
+            };
+        }
+        else {
+            this.#state = { blocked: false, source: 'usage' };
+        }
+        return this.snapshot();
+    }
+
+    observeFailure(error) {
+        if (!cursorQuotaFailure(error))
+            return this.snapshot();
+        this.#revision += 1;
+        this.#lastCheckAt = this.#now();
+        this.#state = {
+            blocked: true,
+            source: 'cursor-error',
+            reason: 'cursor-reported-exhaustion',
+            since: this.#lastCheckAt,
+        };
+        return this.snapshot();
+    }
+}

package/lib/session-pool.js

@@ -57,6 +57,7 @@ export class SessionPool {
     /** Tail of the FIFO queue that serializes every Cursor turn. */
     #gate = Promise.resolve();
     #lockDepth = 0;
+    #activeKey;
 
     /**
      * @param config - plugin config (maxLiveSessions, sessionIdleMinutes, spawn/env).
@@ -99,6 +100,7 @@ export class SessionPool {
             modelChoice: entry.modelChoice,
             mode: entry.session.modes?.currentModeId,
             turns: entry.turns.length,
+            running: entry.key === this.#activeKey,
             reloaded: entry.reloaded,
             idleMs: Date.now() - entry.lastUsed,
             alive: entry.session.alive,
@@ -357,6 +359,7 @@ export class SessionPool {
      */
     async run(options, body) {
         const release = await this.#enter(options.signal);
+        this.#activeKey = options.key;
         try {
             options.signal?.throwIfAborted();
             const lease = await this.#acquire(options, options.signal);
@@ -373,6 +376,7 @@ export class SessionPool {
             }
         }
         finally {
+            this.#activeKey = undefined;
             release();
         }
     }

package/lib/tool.js

@@ -22,6 +22,7 @@ import { delegationDepthOf, resolveChildDepth } from './mirror.js';
 import { sameModel } from './models.js';
 import { buildPrompt } from './prompt.js';
 import { storeKeyOf } from './session-pool.js';
+import { cursorQuotaFailure, quotaBlockedMessage } from './quota-guard.js';
 
 /** Default wall-clock budget for one Cursor turn. */
 const DEFAULT_TIMEOUT_SECONDS = 1800;
@@ -89,7 +90,7 @@ function clean(value, seen) {
  * @param deps - plugin services and shared state.
  */
 export function cursorCodeTool(deps) {
-    const { pool, journal, index, logger, unavailable, mirrors } = deps;
+    const { pool, journal, index, logger, unavailable, mirrors, quotaGuard } = deps;
     // The recursion budget this tool enforces: the child it starts is a real
     // DSH child session, so a subagent calling this tool would create a
     // GRANDCHILD. `1` is the platform's own default (only a top-level agent
@@ -291,6 +292,15 @@ export function cursorCodeTool(deps) {
                 }
             }
 
+            const quotaStatus = await quotaGuard?.check?.();
+            if (quotaStatus?.blocked === true) {
+                return toLosslessJson({
+                    ok: false, sessionKey: 'quota-exhausted', conversationKey,
+                    stopReason: 'error', durationMs: 0,
+                    error: quotaBlockedMessage(quotaStatus), steps: [], changes: [],
+                });
+            }
+
             if (input.resetSession) {
                 pool.dropConversation(conversationKey);
                 journal.clear(conversationKey);
@@ -377,8 +387,8 @@ export function cursorCodeTool(deps) {
             let reused = false;
             let reloaded = false;
             const lifecycle = exec.cursorLifecycle;
-            // External native runs live in the subagents service as a row without a
-            // local transcript; only a lifecycle that asks for the mirror creates one.
+            // The service's external lifecycle id is separate from this child:
+            // the panel follows the mirror, whose transcript is written below.
             const mirrorEnabled = lifecycle?.mirror !== false;
             const openChild = async () => {
                 const entry = await mirrors?.open({
@@ -436,6 +446,13 @@ export function cursorCodeTool(deps) {
                         if (pickedMode !== undefined && session.modes?.currentModeId !== pickedMode)
                             await session.setMode(pickedMode);
                         turn = await session.prompt(input.prompt, abort.signal);
+                        if (cursorQuotaFailure(turn.text)) {
+                            const status = quotaGuard?.observeFailure?.(turn.text);
+                            if (status?.blocked === true) {
+                                const partialTurn = { ...turn, stopReason: 'error' };
+                                throw Object.assign(new Error(quotaBlockedMessage(status)), { partialTurn });
+                            }
+                        }
                         pool.recordTurn(sessionKey, turn);
                         const after = await fingerprint(workspaceRoot, deps.maxScanFiles);
                         const changes = mergeChanges(turn.diffs, compareFingerprints(before, after), workspaceRoot);
@@ -484,7 +501,10 @@ export function cursorCodeTool(deps) {
                 });
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const quotaStatus = cursorQuotaFailure(error) ? quotaGuard?.observeFailure?.(error) : undefined;
+                const message = quotaStatus?.blocked === true
+                    ? quotaBlockedMessage(quotaStatus)
+                    : error instanceof Error ? error.message : String(error);
                 logger?.warn?.(`cursor_code failed: ${message}`);
                 return toLosslessJson({
                     ok: false, sessionKey, conversationKey, generation: picked.generation,

package/lib/usage.js

@@ -485,7 +485,7 @@ export class UsageClient {
  * @param deps - `usage` client, `pool`, `journal`, `index`, `dataDir`, `mirrors`.
  */
 export function registerUsageRoutes(ctx, deps) {
-    const { usage, pool, index, journal, dataDir, mirrors, fence } = deps;
+    const { usage, quotaGuard, pool, index, journal, dataDir, mirrors, fence } = deps;
     const registrations = [];
     // `ctx.get` rather than `ctx.webServer`: a missing service must degrade to
     // "no UI", never to a failed plugin load.
@@ -505,24 +505,42 @@ export function registerUsageRoutes(ctx, deps) {
      */
     const panelState = () => {
         const children = new Map((mirrors?.snapshot?.() ?? []).map(child => [child.key, child]));
+        const live = pool.snapshot();
+        const conversations = index.list();
+        const saved = new Map(conversations.map(entry => [conversationKeyOf(entry.key), entry]));
+        const running = new Set(live.filter(entry => entry.running === true).map(entry => conversationKeyOf(entry.key)));
+        const withRestore = entry => {
+            const key = conversationKeyOf(entry.key);
+            const recorded = saved.get(key);
+            return {
+                ...entry,
+                restorable: typeof entry.cursorSessionId === 'string' && entry.cursorSessionId !== ''
+                    && recorded?.cursorSessionId === entry.cursorSessionId && !running.has(key),
+            };
+        };
         const withActivity = entry => {
             const activity = journal?.lastActivity?.(entry.key);
             return activity === undefined ? entry : { ...entry, activity };
         };
         const withChild = entry => {
             const child = children.get(entry.key);
-            const childSessionId = child?.childSessionId ?? entry.childSessionId;
+            const recorded = saved.get(conversationKeyOf(entry.key));
+            // Native run disposal releases the live mirror; its persisted log is
+            // still openable. Only use that address for the same Cursor session.
+            const remembered = typeof entry.cursorSessionId === 'string'
+                && recorded?.cursorSessionId === entry.cursorSessionId ? recorded : undefined;
+            const childSessionId = child?.childSessionId ?? entry.childSessionId ?? remembered?.childSessionId;
             if (typeof childSessionId !== 'string' || childSessionId === '')
                 return entry;
             return {
                 ...entry,
                 childSessionId,
-                parentSessionId: child?.parentSessionId ?? entry.parentSessionId ?? parentOfKey(entry.key),
+                parentSessionId: child?.parentSessionId ?? entry.parentSessionId ?? remembered?.parentSessionId ?? parentOfKey(entry.key),
             };
         };
         return {
-            live: pool.snapshot().map(withActivity).map(withChild),
-            conversations: index.list().map(withActivity).map(withChild),
+            live: live.map(withRestore).map(withActivity).map(withChild),
+            conversations: conversations.map(withRestore).map(withActivity).map(withChild),
         };
     };
 
@@ -532,6 +550,7 @@ export function registerUsageRoutes(ctx, deps) {
         handler: async (req, res) => {
             const force = typeof req?.url === 'string' && req.url.includes('force=1');
             const snapshot = await usage.get({ force });
+            quotaGuard?.observeUsage?.(snapshot);
             // `raw` is dropped: the normalized view is the contract, and the
             // upstream payload carries 200+ model ids nobody polls for.
             const publicView = { ...snapshot };
@@ -544,6 +563,7 @@ export function registerUsageRoutes(ctx, deps) {
                     queueDepth: pool.queued,
                     conversations: state.conversations,
                     journal: journal?.stats?.(),
+                    quotaGuard: quotaGuard?.snapshot?.() ?? { blocked: false },
                     dataDir,
                 },
             });
@@ -631,8 +651,18 @@ export function registerUsageRoutes(ctx, deps) {
             // conversation key (`parent::label`), so try both before giving up.
             const durableKey = conversationKeyOf(key);
             const entry = index?.get?.(key) ?? index?.get?.(durableKey);
-            if (entry === undefined)
-                sendJson(res, 404, { ok: false, key, error: 'no durable conversation for that key' });
+            const live = pool.snapshot().filter(row => conversationKeyOf(row.key) === durableKey);
+            const current = live.find(row => row.key === key);
+            if (entry === undefined) {
+                if (live.length > 0)
+                    sendJson(res, 409, { ok: false, key, code: 'conversation_pending', error: 'that conversation has not completed a saved turn; open its live timeline instead' });
+                else
+                    sendJson(res, 404, { ok: false, key, error: 'no durable conversation for that key' });
+            }
+            else if (live.some(row => row.running === true))
+                sendJson(res, 409, { ok: false, key, code: 'conversation_running', error: 'that conversation is still running; open its live timeline instead' });
+            else if (current && current.cursorSessionId !== entry.cursorSessionId)
+                sendJson(res, 409, { ok: false, key, code: 'conversation_pending', error: 'this generation has not completed a saved turn; open its live timeline instead' });
             else if (typeof entry.cursorSessionId !== 'string' || entry.cursorSessionId === '')
                 sendJson(res, 409, { ok: false, key, error: 'that conversation never recorded a Cursor session id' });
             else if (typeof pool?.replay !== 'function')
@@ -781,6 +811,7 @@ export function registerUsageRoutes(ctx, deps) {
         handler: (req, res) => {
             sendHtml(res, dashboardHtml({
                 ...panelState(),
+                quotaGuard: quotaGuard?.snapshot?.() ?? { blocked: false },
                 journal,
                 dataDir,
                 configModel: deps.configModel,
@@ -904,6 +935,7 @@ function dashboardHtml(state) {
         conversations: state.conversations ?? [],
         journal: state.journal?.stats?.() ?? { keys: 0, events: 0 },
         queueDepth: state.queueDepth ?? 0,
+        quotaGuard: state.quotaGuard ?? { blocked: false },
         endpoint: '/plugins/dsh-cursor-dev/api/usage',
         journalEndpoint: '/plugins/dsh-cursor-dev/api/journal',
         restoreEndpoint: '/plugins/dsh-cursor-dev/api/restore',
@@ -949,33 +981,52 @@ function dashboardHtml(state) {
     color-scheme: dark;
     --bg: #16161a; --card: #1e1e24; --line: #2c2c34; --fg: #e8e8ea;
     --muted: #9a9aa4; --accent: #6d8cff; --warn: #ffb454; --bad: #ff6b6b; --good: #56d364;
-    --hover: rgba(255, 255, 255, .04);
+    --hover: rgba(255, 255, 255, .04); --on-accent: #0d1020;
   }
   @media (prefers-color-scheme: light) {
     :root {
       color-scheme: light;
       --bg: #f6f6f8; --card: #ffffff; --line: #e2e2e8; --fg: #1c1c22;
       --muted: #6b6b76; --accent: #3b5bdb; --warn: #b26a00; --bad: #c92a2a; --good: #2b8a3e;
-      --hover: rgba(0, 0, 0, .035);
+      --hover: rgba(0, 0, 0, .035); --on-accent: #ffffff;
     }
   }
   * { box-sizing: border-box; }
-  body { margin: 0; padding: 20px; background: var(--bg); color: var(--fg);
+  html { background: var(--bg); }
+  body { margin: 0 auto; padding: 20px; max-width: 1080px; background: var(--bg); color: var(--fg);
     font: 13px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+  :focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
   h1 { font-size: 15px; margin: 0 0 2px; font-weight: 600; }
   h2 { font-size: 12px; margin: 0 0 10px; font-weight: 600; text-transform: uppercase;
     letter-spacing: .06em; color: var(--muted); }
   .head { display: flex; align-items: baseline; gap: 10px; flex-wrap: wrap; margin-bottom: 16px; }
   .muted { color: var(--muted); }
-  /* min() keeps the track from overflowing a panel narrower than 220px — plain
-     minmax(220px, 1fr) makes the grid wider than its card and clips the last tile. */
-  .grid { display: grid; gap: 12px; grid-template-columns: repeat(auto-fit, minmax(min(220px, 100%), 1fr)); }
   .card { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 12px 14px; }
-  .big { font-size: 26px; font-weight: 650; font-variant-numeric: tabular-nums; }
+  .big { font-size: 26px; font-weight: 650; font-variant-numeric: tabular-nums; line-height: 1.2; }
   .bar { height: 7px; border-radius: 4px; background: var(--line); overflow: hidden; margin: 8px 0 6px; }
-  .bar > i { display: block; height: 100%; background: var(--accent); }
+  .bar > i { display: block; width: 0; height: 100%; background: var(--accent); transition: width .3s ease; }
   .bar.warn > i { background: var(--warn); }
   .bar.bad > i { background: var(--bad); }
+  /* Keep the four usage figures in the same two-by-two layout as the panel. */
+  .quota-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 14px; }
+  .quota-card { min-width: 0; min-height: 174px; padding: 16px 18px; border-radius: 12px; }
+  .quota-card h2 { margin-bottom: 16px; font-size: 13px; letter-spacing: .02em; }
+  .quota-card .big { font-size: 34px; font-weight: 700; letter-spacing: -.025em; overflow-wrap: anywhere; }
+  .quota-card .bar { height: 8px; margin: 14px 0 8px; }
+  .quota-card .muted { font-size: 13px; overflow-wrap: anywhere; }
+  .quota-meta { margin-top: 12px; font-size: 12px; }
+  .quota-period { display: flex; flex-wrap: wrap; gap: 2px 8px; }
+  .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+    overflow: hidden; clip-path: inset(50%); white-space: nowrap; border: 0; }
+  details.fold { margin-top: 10px; border-top: 1px solid var(--line); padding-top: 8px; }
+  details.fold > summary { cursor: pointer; width: fit-content; max-width: 100%; color: var(--muted); font-size: 12px; border-radius: 4px; }
+  details.fold > summary:hover { color: var(--fg); }
+  .quota-meta > details.fold { margin-top: 8px; }
+  .status { margin-top: 6px; font-size: 12px; }
+  .quota-alert { margin: 0 0 12px; padding: 10px 12px; border: 1px solid var(--bad);
+    border-radius: 8px; background: var(--card); color: var(--bad); }
+  .quota-alert[hidden] { display: none; }
+  #model-state, #model-status, #message, #error, .note { overflow-wrap: anywhere; }
   /* A session key is one ~84-character token with no break opportunity, so an
      uncontained table stretches <body> instead of scrolling: the panel then
      grows a page-wide scrollbar and the cards drift off-screen. The scroll
@@ -1035,12 +1086,23 @@ function dashboardHtml(state) {
     font: inherit; color: var(--fg); background: var(--bg);
     border: 1px solid var(--line); border-radius: 7px; padding: 5px 9px;
   }
-  select { flex: 1 1 260px; min-width: 180px; max-width: 100%; }
-  input[type="search"] { flex: 0 1 200px; min-width: 130px; max-width: 100%; }
-  input[type="text"] { flex: 1 1 240px; min-width: 150px; max-width: 100%; }
-  select:focus, input[type="search"]:focus, input[type="text"]:focus { outline: none; border-color: var(--accent); }
-  button { cursor: pointer; }
+  /* min() lets a control shrink inside a panel narrower than its usual minimum. */
+  select { flex: 1 1 260px; min-width: min(180px, 100%); max-width: 100%; }
+  input[type="search"] { flex: 0 1 200px; min-width: min(130px, 100%); max-width: 100%; }
+  input[type="text"] { flex: 1 1 240px; min-width: min(150px, 100%); max-width: 100%; }
+  select:focus, input[type="search"]:focus, input[type="text"]:focus { border-color: var(--accent); }
+  button { cursor: pointer; transition: border-color .15s ease, background-color .15s ease; }
   button:hover { border-color: var(--accent); }
+  button.primary { background: var(--accent); border-color: var(--accent); color: var(--on-accent); font-weight: 600; padding: 5px 16px; }
+  button.primary:hover { background: var(--fg); border-color: var(--fg); color: var(--bg); }
+  .lock { display: flex; align-items: center; gap: 8px; margin: 8px 0 0; }
+  /* The proxy is machine configuration, not the main choice, so it gets one
+     thin strip above the picker rather than a box of its own. It stays open:
+     a wrong proxy is the usual reason the model list looks short. */
+  .env { margin-top: 12px; padding-bottom: 10px; border-bottom: 1px solid var(--line); }
+  .env .controls { margin: 0; }
+  .env input[type="text"] { font-size: 12px; padding: 4px 8px; }
+  .env label { font-size: 12px; }
   button.ghost { color: var(--muted); }
   button[disabled] { opacity: .5; cursor: default; border-color: var(--line); }
   .filter-note { font-size: 12px; }
@@ -1090,10 +1152,10 @@ function dashboardHtml(state) {
   /* The settings page hands this dashboard a short slot and clips the
      overflow, so a tall layout hides everything that matters. When the
      viewport is short everything tightens and the long explanatory note
-     goes away, which keeps the model picker and the tiles in view. */
+     goes away, which keeps the quota and the model picker in view. */
   body.compact { padding: 12px; }
   body.compact .head { margin-bottom: 10px; }
-  body.compact .grid { gap: 8px; }
+  body.compact .quota-grid { gap: 12px; }
   body.compact .card { padding: 8px 10px; border-radius: 8px; }
   body.compact h2 { margin-bottom: 6px; }
   body.compact .big { font-size: 20px; }
@@ -1103,7 +1165,18 @@ function dashboardHtml(state) {
   body.compact .controls { margin: 8px 0 4px; }
   body.compact .controls label { margin: 6px 0; }
   body.compact th, body.compact td { padding: 4px 7px; }
-  body.compact [data-t="modelNote"] { display: none; }
+  body.compact [data-t="modelNote"], body.compact [data-t="modelHint"] { display: none; }
+  body.compact .quota-card { min-height: 158px; padding: 14px 16px; border-radius: 12px; }
+  body.compact .quota-card .big { font-size: 32px; }
+  body.compact .quota-card .bar { height: 8px; margin: 12px 0 8px; }
+  @media (max-width: 420px) {
+    body { padding: 12px; }
+    .quota-grid { grid-template-columns: minmax(0, 1fr); }
+    .quota-card { min-height: 158px; }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after { transition: none !important; }
+  }
 </style>
 </head>
 <body>
@@ -1115,82 +1188,98 @@ function dashboardHtml(state) {
   <span class="muted" style="margin-left:auto"><a href="#" class="link" id="refresh" data-t="refresh">刷新</a></span>
 </div>
 
+<div id="quota-alert" class="quota-alert" role="alert" aria-live="assertive" hidden data-t="quotaBlocked">Cursor 额度已耗尽，已暂停新的子智能体任务；额度刷新确认恢复后会自动解除拦截。</div>
 <div id="error" class="card err" style="display:none"></div>
 <div id="setup" class="card" style="display:none"></div>
 
-<!-- The host embeds this dashboard in a slot that can be only a couple of
-     hundred pixels tall, and it clips whatever falls below that. The model
-     picker is the one control here, so it comes first: in a short slot the
-     quota tiles scroll away while the picker stays reachable. -->
-<div class="card" id="modelcard" style="margin-bottom:14px">
-  <h2 data-t="model">子智能体模型</h2>
+<!-- Usage stays above the model controls; each figure keeps its own card. -->
+<section id="usage-overview" aria-labelledby="usage-title">
+  <h2 class="sr-only" id="usage-title" data-t="usage">额度与用量</h2>
+  <div class="quota-grid">
+    <article class="card quota-card">
+      <h2 id="total-label" data-t="included">总包含额度</h2>
+      <div class="big" id="total-pct">—</div>
+      <div class="bar" id="total-bar" role="progressbar" aria-labelledby="total-label" aria-valuemin="0" aria-valuemax="100"><i></i></div>
+      <div class="muted" id="total-sub">—</div>
+    </article>
+    <article class="card quota-card">
+      <h2 id="auto-label" data-t="auto">Auto 额度</h2>
+      <div class="big" id="auto-pct">—</div>
+      <div class="bar" id="auto-bar" role="progressbar" aria-labelledby="auto-label" aria-valuemin="0" aria-valuemax="100"><i></i></div>
+      <div class="muted" id="auto-sub">—</div>
+    </article>
+    <article class="card quota-card">
+      <h2 id="api-label" data-t="api">API / 指定模型额度</h2>
+      <div class="big" id="api-pct">—</div>
+      <div class="bar" id="api-bar" role="progressbar" aria-labelledby="api-label" aria-valuemin="0" aria-valuemax="100"><i></i></div>
+      <div class="muted" id="api-sub">—</div>
+    </article>
+    <article class="card quota-card">
+      <h2 data-t="spend">本期消费</h2>
+      <div class="big" id="spend">—</div>
+      <div class="muted" id="spend-sub" style="margin-top:8px">—</div>
+    </article>
+  </div>
+  <div class="quota-meta muted">
+    <div class="quota-period">
+      <span data-t="period">计费周期</span>
+      <span id="cycle">—</span>
+    </div>
+    <details class="fold" id="message-box" hidden>
+      <summary data-t="officialNote">官方说明</summary>
+      <div id="message"></div>
+    </details>
+  </div>
+</section>
+
+<section class="row card" id="modelcard" aria-labelledby="model-title">
+  <h2 id="model-title" data-t="model">子智能体模型</h2>
   <div class="muted" data-t="modelHint"></div>
-  <div class="controls">
-    <select id="model"></select>
-    <button type="button" id="model-save" data-t="save">保存</button>
-    <button type="button" id="model-reload" class="ghost" data-t="reloadModels">重新读取模型列表</button>
+  <!-- The child CLI does not read the Windows registry, so a machine whose proxy
+       lives only in Internet Settings gets a child that lists a fraction of the
+       models. Empty means "ask the machine", which is what makes the full
+       catalogue appear with nobody configuring anything. -->
+  <div class="env">
+    <div class="controls">
+      <label class="muted" for="proxy" data-t="proxyLabel">代理</label>
+      <input type="text" id="proxy" autocomplete="off" spellcheck="false">
+    </div>
   </div>
-  <!-- The child CLI does not read the Windows registry, so a machine whose
-       proxy lives only in Internet Settings gets a child that lists a fraction
-       of the models. Empty means "ask the machine", which is what makes the
-       full catalogue appear with nobody configuring anything. -->
   <div class="controls">
-    <span class="muted" data-t="proxyLabel">代理</span>
-    <input type="text" id="proxy" autocomplete="off" spellcheck="false">
+    <select id="model" aria-labelledby="model-title"></select>
+    <button type="button" id="model-save" class="primary" data-t="save">保存</button>
   </div>
-  <label style="display:flex;align-items:center;gap:8px;margin:10px 0">
+  <label class="lock">
     <input type="checkbox" id="model-lock">
     <span data-t="modelLock">锁定面板模型（忽略单次调用的 model 参数）</span>
   </label>
-  <div class="muted" id="model-state"></div>
+  <div class="status" id="model-status" role="status" aria-live="polite"></div>
   <!-- The catalogue the CLI reports is too long for a dropdown, so it gets a
        browser: search, filter, and a switch per model. Switching a model off
        only hides it from the picker — it is never deleted, so switching it
        back on restores the same entry. -->
-  <div class="picker">
-    <div class="picker-top">
-      <input type="search" id="model-filter" autocomplete="off" spellcheck="false">
-      <div class="tabs" id="model-tabs"></div>
+  <details class="fold" id="model-browser">
+    <summary data-t="modelBrowse">模型目录、搜索与筛选</summary>
+    <div class="controls">
+      <button type="button" id="model-reload" class="ghost" data-t="reloadModels">重新读取模型列表</button>
     </div>
-    <div class="picker-body">
-      <div class="picker-list" id="model-list"></div>
-      <div class="picker-detail" id="model-detail"></div>
+    <div class="picker">
+      <div class="picker-top">
+        <input type="search" id="model-filter" autocomplete="off" spellcheck="false">
+        <div class="tabs" id="model-tabs"></div>
+      </div>
+      <div class="picker-body">
+        <div class="picker-list" id="model-list"></div>
+        <div class="picker-detail" id="model-detail"></div>
+      </div>
     </div>
-  </div>
-  <div class="muted" data-t="modelNote" style="margin-top:6px"></div>
-</div>
-
-<div class="grid">
-  <div class="card">
-    <h2 data-t="included">总包含额度</h2>
-    <div class="big" id="total-pct">—</div>
-    <div class="bar" id="total-bar"><i style="width:0%"></i></div>
-    <div class="muted" id="total-sub">—</div>
-  </div>
-  <div class="card">
-    <h2 data-t="auto">Auto 额度</h2>
-    <div class="big" id="auto-pct">—</div>
-    <div class="bar" id="auto-bar"><i style="width:0%"></i></div>
-    <div class="muted" id="auto-sub">—</div>
-  </div>
-  <div class="card">
-    <h2 data-t="api">API / 指定模型额度</h2>
-    <div class="big" id="api-pct">—</div>
-    <div class="bar" id="api-bar"><i style="width:0%"></i></div>
-    <div class="muted" id="api-sub">—</div>
-  </div>
-  <div class="card">
-    <h2 data-t="spend">本期消费</h2>
-    <div class="big" id="spend">—</div>
-    <div class="muted" id="spend-sub">—</div>
-  </div>
-</div>
-
-<div class="row card">
-  <h2 data-t="period">计费周期</h2>
-  <div id="cycle" class="muted">—</div>
-  <div id="message" class="muted" style="margin-top:6px"></div>
-</div>
+    <div class="muted" data-t="modelNote" style="margin-top:6px"></div>
+  </details>
+  <details class="fold" id="model-advanced">
+    <summary data-t="modelAdvanced">来源与出口</summary>
+    <div class="muted" id="model-state"></div>
+  </details>
+</section>
 
 <div class="row card">
   <h2 data-t="live">运行中的 Cursor 会话</h2>
@@ -1230,11 +1319,23 @@ function dashboardHtml(state) {
       account: '账号',
       loading: '加载中…',
       refresh: '刷新',
+      usage: '额度与用量',
       included: '总包含额度',
+      used: '已用',
       auto: 'Auto 额度',
       api: 'API / 指定模型额度',
       spend: '本期消费',
+      remaining: '剩余 ',
+      noData: '暂无数据',
+      levelWarn: '偏高',
+      levelBad: '接近上限',
+      officialNote: '官方说明',
       model: '子智能体模型',
+      modelBrowse: '模型目录、搜索与筛选',
+      modelAdvanced: '来源与出口',
+      appliesNext: '下次调用生效',
+      unsavedShort: '有改动未保存',
+      seeAdvanced: '模型列表或代理有异常，见「来源与出口」',
       modelHint: '默认跟随这里的模型；勾选锁定后，智能体传入的 model 参数也不会覆盖你的选择。',
       modelLock: '锁定面板模型（忽略单次调用的 model 参数）',
       modelLocked: '已锁定模型',
@@ -1301,11 +1402,10 @@ function dashboardHtml(state) {
       none: '暂无',
       unreachable: '无法连接',
       usageUnavailable: '用量暂时取不到：',
+      quotaBlocked: 'Cursor 额度已耗尽，已暂停新的子智能体任务；额度刷新确认恢复后会自动解除拦截。',
       updated: '更新于 ',
       failed: '获取失败 ',
-      spentOf: '已用 ',
-      of: ' / 共 ',
-      includedIn: '包含 ',
+      includedIn: '套餐内 ',
       bonus: ' · 赠送 ',
       starts: '开始 ',
       renews: '  →  续订 ',
@@ -1346,11 +1446,23 @@ function dashboardHtml(state) {
       account: 'account',
       loading: 'loading…',
       refresh: 'refresh',
+      usage: 'Quota & usage',
       included: 'Included total',
+      used: 'used',
       auto: 'Auto bucket',
       api: 'API / named bucket',
-      spend: 'Spend',
+      spend: 'Spend this period',
+      remaining: 'remaining ',
+      noData: 'no data yet',
+      levelWarn: 'high',
+      levelBad: 'near the limit',
+      officialNote: 'Official note',
       model: 'Child-agent model',
+      modelBrowse: 'Model catalogue, search and filters',
+      modelAdvanced: 'Source and egress',
+      appliesNext: 'applies on the next call',
+      unsavedShort: 'unsaved changes',
+      seeAdvanced: 'model list or proxy problem — see Source and egress',
       modelHint: 'Calls follow this default unless they specify a model. Lock it to prevent the agent from overriding your choice.',
       modelLock: 'Lock the panel model (ignore per-call model arguments)',
       modelLocked: 'model locked',
@@ -1417,10 +1529,9 @@ function dashboardHtml(state) {
       none: 'none',
       unreachable: 'unreachable',
       usageUnavailable: 'Usage unavailable: ',
+      quotaBlocked: 'Cursor quota is exhausted. New child-agent runs are paused until a quota refresh confirms capacity has returned.',
       updated: 'updated ',
       failed: 'failed ',
-      spentOf: 'spent ',
-      of: ' of ',
       includedIn: 'included ',
       bonus: ' · bonus ',
       starts: 'starts ',
@@ -1469,6 +1580,7 @@ function dashboardHtml(state) {
   var models = (boot.models && boot.models.list) || [];
   var modelsFetchedAt = (boot.models && boot.models.fetchedAt) || 0;
   var modelsSource = (boot.models && boot.models.source) || '';
+  var quotaGate = boot.quotaGuard || { blocked: false };
   var configModel = boot.configModel || '';
   var setupState = null;
   var LANG = pickLang();
@@ -1513,7 +1625,9 @@ function dashboardHtml(state) {
     }
     renderLangs();
     renderModel();
-    renderLive(lastPayload);
+    renderQuotaGuard(quotaGate);
+    if (lastPayload.ok === true) render(lastPayload);
+    else renderLive(lastPayload);
     renderSetup();
   }
   /** The 中文 / English switch, in the header. */
@@ -1545,8 +1659,15 @@ function dashboardHtml(state) {
     });
   }
 
+  function known(value) { return typeof value === 'number' && isFinite(value); }
   function pct(value) {
-    return typeof value === 'number' ? value.toFixed(1) + '%' : '—';
+    return known(value) ? value.toFixed(1) + '%' : '—';
+  }
+  /** The note under a bar, read off the same upstream percentage as the bar. */
+  function remaining(value) {
+    if (!known(value)) return t('noData');
+    var level = value >= 90 ? ' · ' + t('levelBad') : value >= 70 ? ' · ' + t('levelWarn') : '';
+    return t('remaining') + Math.max(0, 100 - value).toFixed(1) + '%' + level;
   }
   function money(value) {
     return typeof value === 'number' ? '$' + value.toFixed(2) : '—';
@@ -1565,9 +1686,12 @@ function dashboardHtml(state) {
   function text(node, value) { node.textContent = value == null ? '—' : String(value); }
   function setBar(id, percent) {
     var bar = $(id);
-    var p = typeof percent === 'number' ? Math.max(0, Math.min(100, percent)) : 0;
+    var p = known(percent) ? Math.max(0, Math.min(100, percent)) : 0;
     bar.firstElementChild.style.width = p + '%';
     bar.className = 'bar' + (p >= 90 ? ' bad' : p >= 70 ? ' warn' : '');
+    if (known(percent)) bar.setAttribute('aria-valuenow', String(p));
+    else bar.removeAttribute('aria-valuenow');
+    bar.setAttribute('aria-valuetext', known(percent) ? pct(percent) : t('noData'));
   }
 
   /** Compare the CLI's Auto id with the panel alias without conflating variants. */
@@ -1759,6 +1883,12 @@ function dashboardHtml(state) {
     if (proxyError) bits.push(t('proxyFailed') + proxyError);
     if (modelsError) bits.push(t('modelsFailed') + modelsError);
     text($('model-state'), bits.join('  ·  '));
+    var dirty = (draftModel !== null && canonicalModel(draftModel) !== canonicalModel(settings.model)) || switchesDirty();
+    var status = [t('inEffect') + modelLabel(inEffectNow),
+      t(settings.modelPolicy === 'panel' && inEffectNow ? 'modelLocked' : 'modelOverridable'),
+      t(dirty ? 'unsavedShort' : 'appliesNext')];
+    if (modelsError || proxyError) status.push(t('seeAdvanced'));
+    text($('model-status'), status.join(' · '));
     renderPicker(rows, selected, inEffectNow);
   }
 
@@ -2016,7 +2146,7 @@ function dashboardHtml(state) {
    * (an agent loop to hold it, a recorded Cursor session to read).
    */
   function canRestore(entry) {
-    return boot.children.available === true
+    return boot.children.available === true && entry.restorable !== false && entry.running !== true
       && typeof entry.cursorSessionId === 'string' && entry.cursorSessionId !== '';
   }
 
@@ -2056,6 +2186,10 @@ function dashboardHtml(state) {
           });
           return;
         }
+        if (body.code === 'conversation_pending' || body.code === 'conversation_running') {
+          openJournal(entry.key);
+          return;
+        }
         notice(t('restoreFailed') + (body.error || 'unknown error'));
       })
       .catch(function (error) {
@@ -2342,8 +2476,14 @@ function dashboardHtml(state) {
     renderCount(convos.length);
     applyFolded();
   }
+  function renderQuotaGuard(state) {
+    if (state && typeof state.blocked === 'boolean') quotaGate = state;
+    $('quota-alert').hidden = quotaGate.blocked !== true;
+  }
   function render(payload) {
     lastPayload = payload;
+    var gate = payload.extended && payload.extended.quotaGuard;
+    if (gate) renderQuotaGuard(gate);
     var err = $('error');
     // A failed snapshot carries no extended block; keep whatever the table
     // already shows rather than blanking it.
@@ -2357,20 +2497,26 @@ function dashboardHtml(state) {
     }
     err.style.display = 'none';
     var u = payload.usage || {};
-    setBar('total-bar', u.total && u.total.percentUsed);
-    setBar('auto-bar', u.auto && u.auto.percentUsed);
-    setBar('api-bar', u.api && u.api.percentUsed);
-    text($('total-pct'), pct(u.total && u.total.percentUsed));
-    text($('auto-pct'), pct(u.auto && u.auto.percentUsed));
-    text($('api-pct'), pct(u.api && u.api.percentUsed));
+    var d = u.dollars || {};
+    // Every percentage is the upstream percentUsed: the dollar fields count
+    // different things (spend includes bonus, limit does not), so a ratio of
+    // them disagrees with the bar.
+    ['total', 'auto', 'api'].forEach(function (name) {
+      var p = u[name] && u[name].percentUsed;
+      setBar(name + '-bar', p);
+      text($(name + '-pct'), pct(p));
+      text($(name + '-sub'), remaining(p));
+    });
+    $('auto-sub').title = u.autoMessage || '';
+    $('api-sub').title = u.namedMessage || '';
     text($('tier'), u.plan || payload.tier || t('account'));
-    text($('total-sub'), t('spentOf') + money(u.dollars && u.dollars.total) + t('of') + money(u.dollars && u.dollars.limit));
-    text($('auto-sub'), u.autoMessage || t('auto'));
-    text($('api-sub'), u.namedMessage || t('api'));
-    text($('spend'), money(u.dollars && u.dollars.total));
-    text($('spend-sub'), t('includedIn') + money(u.dollars && u.dollars.included) + t('bonus') + money(u.dollars && u.dollars.bonus));
-    text($('cycle'), t('starts') + when(u.billingCycle && u.billingCycle.start) + t('renews') + when(u.billingCycle && u.billingCycle.end));
+    text($('spend'), money(d.total));
+    text($('spend-sub'), t('includedIn') + money(d.included) + t('bonus') + money(d.bonus));
+    var cycle = u.billingCycle || {};
+    text($('cycle'), known(cycle.start) || known(cycle.end)
+      ? t('starts') + when(cycle.start) + t('renews') + when(cycle.end) : t('noData'));
     text($('message'), u.displayMessage || '');
+    $('message-box').hidden = !u.displayMessage;
     text($('stamp'), t('updated') + when(payload.fetchedAt));
     text($('source'), t('source') + (payload.source || '') + (payload.authPath ? t('credentials') + payload.authPath : ''));
     renderLive(payload);
@@ -2437,6 +2583,7 @@ function dashboardHtml(state) {
       })
       .catch(function (e) {
         text($('model-state'), t('saveFailed') + String(e));
+        text($('model-status'), t('saveFailed') + String(e));
         return undefined;
       });
   }
@@ -2543,6 +2690,7 @@ function dashboardHtml(state) {
     var nextProxy = proxyBox ? proxyBox.value.trim() : '';
     var proxyChanged = nextProxy !== (settings.proxy == null ? '' : String(settings.proxy));
     text($('model-state'), '…');
+    text($('model-status'), '…');
     post({
       model: value,
       modelPolicy: $('model-lock').checked ? 'panel' : 'per-call',
@@ -2556,8 +2704,9 @@ function dashboardHtml(state) {
       draftDisabled = null;
       renderLive(lastPayload);
       var announce = function () {
-        text($('model-state'), t('saved') + '  ·  ' + t('inEffect') + modelLabel(data.effectiveModel)
-          + '  ·  ' + t(settings.modelPolicy === 'panel' && data.effectiveModel ? 'modelLocked' : 'modelOverridable'));
+        var lock = t(settings.modelPolicy === 'panel' && data.effectiveModel ? 'modelLocked' : 'modelOverridable');
+        text($('model-state'), t('saved') + '  ·  ' + t('inEffect') + modelLabel(data.effectiveModel) + '  ·  ' + lock);
+        text($('model-status'), t('saved') + ' · ' + modelLabel(data.effectiveModel) + ' · ' + lock + ' · ' + t('appliesNext'));
       };
       // A new route reaches a different catalogue, which makes the list on
       // screen a fact about the old one — so re-read it before saying "saved".
@@ -2567,6 +2716,7 @@ function dashboardHtml(state) {
   });
   $('model-reload').addEventListener('click', function () {
     text($('model-state'), t('loading'));
+    text($('model-status'), t('loading'));
     loadSettings(true);
   });
   // Filtering is client-side on purpose: the list is already in the payload, so

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-cursor-dev",
   "displayName": "Cursor 子智能体",
-  "description": "把 Cursor CLI 当作子编码智能体来写业务代码：cursor_code 每次运行都在 DSH 里开一个真实的、可点开的子会话，cursor_subagent 则显示为宿主写入的 External 记录；可按任务选模型、会话在 DSH 重启后仍能续聊、返回逐步工具时间线与真实文件 diff，并自带额度/模型/会话面板。",
-  "version": "0.12.1",
+  "description": "把 Cursor CLI 当作子编码智能体来写业务代码：cursor_code 与 cursor_subagent 都提供可从面板点开的实时子对话，原生任务保留宿主的 External 运行记录；可按任务选模型、会话在 DSH 重启后仍能续聊、返回逐步工具时间线与真实文件 diff，并自带额度/模型/会话面板。",
+  "version": "0.12.2",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",