dsh-cursor-dev 0.12.0 → 0.12.2

package/lib/usage.js

@@ -12,6 +12,7 @@
  * is created, and the token is never logged, echoed, or returned over HTTP.
  */
 import { readFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { proxyAwareFetch, readSystemProxy, describeProxy } from './proxy.js';
@@ -36,8 +37,59 @@ const REQUEST_TIMEOUT_MS = 15_000;
 const RESTORE_TIMEOUT_MS = 60_000;
 
 /**
- * Cursor's own auth store. The CLI keeps the tokens here rather than under
- * `~/.cursor`, which is what makes this discoverable at all.
+ * The macOS Keychain account the Cursor CLI stores its login under.
+ *
+ * The CLI's credential store is not one file across platforms: on macOS it
+ * keeps the login in the login Keychain as generic-password items named
+ * `cursor-access-token`, `cursor-refresh-token` and `cursor-api-key`, all under
+ * the account `cursor-user`. Windows and Linux write the same domain
+ * ("cursor") to `auth.json` inside the per-user config directory instead. Both
+ * stores are tried below, because the store is a user-visible CLI setting
+ * (`AGENT_CLI_CREDENTIAL_STORE=file` opts a macOS install into the file), and
+ * the earlier builds of this plugin only knew the file spelling.
+ */
+const KEYCHAIN_ACCOUNT = 'cursor-user';
+const KEYCHAIN_ACCESS_TOKEN_SERVICE = 'cursor-access-token';
+
+/**
+ * Every `auth.json` location the CLI may have written, in lookup order.
+ *
+ * The CLI's file credential store (`../cli-credentials` in the CLI bundle) names
+ * the file after its credential-store domain: `%APPDATA%\Cursor\auth.json` on
+ * Windows (that platform title-cases the domain), `$XDG_CONFIG_HOME/cursor/auth.json`
+ * on Linux, and `~/.cursor/auth.json` when the macOS CLI is forced onto the file
+ * store. `~/.config/Cursor` is the spelling earlier builds of this plugin
+ * assumed, so it stays in the list for machines whose token was already put
+ * there. {@link authFilePath} keeps returning that historical single answer.
+ */
+export function authFileCandidates(env = process.env) {
+    const paths = [];
+    const add = value => {
+        if (typeof value === 'string' && value !== '' && !paths.includes(value))
+            paths.push(value);
+    };
+    const appData = typeof env.APPDATA === 'string' ? env.APPDATA.trim() : '';
+    if (appData !== '')
+        add(join(appData, 'Cursor', 'auth.json'));
+    const xdg = typeof env.XDG_CONFIG_HOME === 'string' ? env.XDG_CONFIG_HOME.trim() : '';
+    if (xdg !== '')
+        add(join(xdg, 'cursor', 'auth.json'));
+    // Honouring HOME through the injected environment keeps the "env is the
+    // only input" contract the rest of this section promises (and lets a test
+    // point the reader at a throw-away directory).
+    const home = typeof env.HOME === 'string' && env.HOME.trim() !== '' ? env.HOME.trim() : homedir();
+    add(join(home, '.cursor', 'auth.json'));
+    add(join(home, '.config', 'cursor', 'auth.json'));
+    add(join(home, '.config', 'Cursor', 'auth.json'));
+    return paths;
+}
+
+/**
+ * The file the plugin has always named for the token.
+ *
+ * Kept as the historical public answer ("where is the token") for callers and
+ * error messages; the reader itself walks {@link authFileCandidates}, because
+ * the real store is Keychain on macOS.
  */
 export function authFilePath(env = process.env) {
     const appData = env.APPDATA;
@@ -46,33 +98,139 @@ export function authFilePath(env = process.env) {
     return join(homedir(), '.config', 'Cursor', 'auth.json');
 }
 
+/**
+ * Read one generic password out of the macOS login Keychain.
+ *
+ * The CLI itself reads these items with `/usr/bin/security` — that is exactly
+ * what its own keychain credential store does — so using the same tool keeps
+ * this out-of-band read on the code path Cursor's login already relies on: no
+ * native binding, no extra dependency, and the same failure modes when the
+ * keychain is locked or the item is missing. `-g` prints the secret to stderr
+ * as either `password: 0x<hex>` or, on newer macOS releases, as
+ * `password: "<text>"`; both shapes are decoded here. The value is returned to
+ * the caller and never logged.
+ *
+ * @param service - keychain item service name (e.g. `cursor-access-token`).
+ * @param account - keychain item account; the CLI always uses `cursor-user`.
+ * @param options - `securityPath` and `timeoutMs` exist for tests.
+ */
+async function keychainPassword(service, account = KEYCHAIN_ACCOUNT, options = {}) {
+    const executable = options.securityPath ?? '/usr/bin/security';
+    const timeout = options.timeoutMs ?? 5000;
+    return await new Promise(resolve => {
+        try {
+            execFile(executable, ['find-generic-password', '-a', account, '-s', service, '-g'], { timeout, windowsHide: true }, (error, stdout, stderr) => {
+                if (error !== null) {
+                    // A locked keychain asks the user for approval through a GUI
+                    // dialog; the timeout is what stops that from hanging a panel
+                    // refresh, and the error must say so instead of claiming the
+                    // item does not exist.
+                    const reason = error.killed === true
+                        ? `the keychain read timed out after ${timeout}ms (is the login keychain locked?)`
+                        : error.message;
+                    resolve({ ok: false, error: `no keychain item "${service}" for "${account}": ${reason}` });
+                    return;
+                }
+                const text = `${stdout ?? ''}\n${stderr ?? ''}`;
+                const hex = /^password: 0x([0-9a-fA-F]+)$/m.exec(text);
+                const quoted = /^password: "(.*)"$/m.exec(text);
+                let password;
+                if (hex !== null)
+                    password = Buffer.from(hex[1], 'hex').toString('utf8');
+                else if (quoted !== null)
+                    password = quoted[1].replace(/\\"/g, '"');
+                if (typeof password !== 'string' || password === '') {
+                    resolve({ ok: false, error: `cannot parse the keychain answer for "${service}"` });
+                    return;
+                }
+                resolve({ ok: true, password });
+            });
+        }
+        catch (error) {
+            resolve({ ok: false, error: `cannot run ${executable}: ${errorText(error)}` });
+        }
+    });
+}
+
 /**
  * Read the access token the CLI is already signed in with.
  *
+ * Every store the CLI may have used is tried, in the order the CLI itself
+ * prefers on this platform: an explicit `CURSOR_AUTH_TOKEN` first (the CLI
+ * accepts the same variable), then the macOS Keychain, then the file stores.
+ * `AGENT_CLI_CREDENTIAL_STORE` is honoured so a CLI deliberately running on the
+ * file store, or on the memory-only store, is not shadowed by a stale item.
  * The token is deliberately returned to the caller and never logged.
  *
  * @param env - environment source (injectable for tests).
+ * @param options - `platform`, `securityPath` and `timeoutMs` exist for tests.
  */
-export async function readAccessToken(env = process.env) {
-    const path = authFilePath(env);
-    let raw;
-    try {
-        raw = await readFile(path, 'utf8');
-    }
-    catch (error) {
-        return { ok: false, path, error: `cannot read ${path}: ${errorText(error)}` };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        return { ok: false, path, error: `cannot parse ${path}: ${errorText(error)}` };
+export async function readAccessToken(env = process.env, options = {}) {
+    const explicit = typeof env.CURSOR_AUTH_TOKEN === 'string' ? env.CURSOR_AUTH_TOKEN.trim() : '';
+    if (explicit !== '')
+        return { ok: true, path: 'CURSOR_AUTH_TOKEN', token: explicit };
+
+    const platform = options.platform ?? process.platform;
+    const store = typeof env.AGENT_CLI_CREDENTIAL_STORE === 'string' ? env.AGENT_CLI_CREDENTIAL_STORE.trim() : '';
+    const filePaths = authFileCandidates(env);
+    const attempted = [];
+
+    // `memory` keeps the login in the CLI process only; nothing else can read
+    // it, so only the environment variable above could have answered.
+    if (store !== 'memory') {
+        if (platform === 'darwin' && store !== 'file') {
+            const keychain = await keychainPassword(KEYCHAIN_ACCESS_TOKEN_SERVICE, KEYCHAIN_ACCOUNT, {
+                securityPath: options.securityPath,
+                timeoutMs: options.timeoutMs,
+            });
+            if (keychain.ok === true)
+                return { ok: true, path: `macOS keychain: ${KEYCHAIN_ACCESS_TOKEN_SERVICE} (${KEYCHAIN_ACCOUNT})`, token: keychain.password };
+            attempted.push(keychain.error);
+        }
+        for (const path of filePaths) {
+            let raw;
+            try {
+                raw = await readFile(path, 'utf8');
+            }
+            catch (error) {
+                attempted.push(`cannot read ${path}: ${errorText(error)}`);
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (error) {
+                attempted.push(`cannot parse ${path}: ${errorText(error)}`);
+                continue;
+            }
+            const token = parsed?.accessToken;
+            if (typeof token !== 'string' || token === '') {
+                attempted.push(`${path} has no accessToken field`);
+                continue;
+            }
+            return { ok: true, path, token };
+        }
     }
-    const token = parsed?.accessToken;
-    if (typeof token !== 'string' || token === '')
-        return { ok: false, path, error: `${path} has no accessToken field` };
-    return { ok: true, path, token };
+
+    const path = authFilePath(env);
+    const stores = [];
+    if (platform === 'darwin' && store !== 'file')
+        stores.push(`macOS keychain "${KEYCHAIN_ACCESS_TOKEN_SERVICE}"`);
+    stores.push(...filePaths);
+    // "Missing" is the normal signed-out state and repeating one ENOENT per
+    // candidate would bury the actionable sentence; a corrupt file or a locked
+    // keychain is worth quoting because it needs a different fix.
+    const failures = attempted.filter(reason => !/ENOENT|not be found|ItemNotFound/i.test(reason));
+    const parts = [store === 'memory'
+        ? `the Cursor CLI runs with AGENT_CLI_CREDENTIAL_STORE=memory, so its login is not readable by another process`
+        : `no Cursor login found (tried: ${stores.join(', ')})`];
+    if (store !== 'memory')
+        parts.push(`sign the CLI in with "agent login"`);
+    parts.push(`set CURSOR_AUTH_TOKEN to supply a token explicitly`);
+    if (failures.length > 0)
+        parts.push(`failures: ${failures.slice(0, 2).join('; ')}`);
+    return { ok: false, path, error: parts.join('; ') };
 }
 
 /**
@@ -327,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.
@@ -347,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),
         };
     };
 
@@ -374,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 };
@@ -386,6 +563,7 @@ export function registerUsageRoutes(ctx, deps) {
                     queueDepth: pool.queued,
                     conversations: state.conversations,
                     journal: journal?.stats?.(),
+                    quotaGuard: quotaGuard?.snapshot?.() ?? { blocked: false },
                     dataDir,
                 },
             });
@@ -473,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')
@@ -623,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,
@@ -746,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',
@@ -791,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
@@ -877,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; }
@@ -932,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; }
@@ -945,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>
@@ -957,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>
@@ -1072,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: '已锁定模型',
@@ -1143,11 +1402,10 @@ function dashboardHtml(state) {
       none: '暂无',
       unreachable: '无法连接',
       usageUnavailable: '用量暂时取不到：',
+      quotaBlocked: 'Cursor 额度已耗尽，已暂停新的子智能体任务；额度刷新确认恢复后会自动解除拦截。',
       updated: '更新于 ',
       failed: '获取失败 ',
-      spentOf: '已用 ',
-      of: ' / 共 ',
-      includedIn: '包含 ',
+      includedIn: '套餐内 ',
       bonus: ' · 赠送 ',
       starts: '开始 ',
       renews: '  →  续订 ',
@@ -1188,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',
@@ -1259,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 ',
@@ -1311,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();
@@ -1355,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. */
@@ -1387,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) : '—';
@@ -1407,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. */
@@ -1601,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);
   }
 
@@ -1858,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 !== '';
   }
 
@@ -1898,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) {
@@ -2184,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.
@@ -2199,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);
@@ -2279,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;
       });
   }
@@ -2385,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',
@@ -2398,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".
@@ -2409,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