dsh-agy-link 0.4.57 → 0.4.65

package/CHANGELOG.md

@@ -1,5 +1,265 @@
 # Changelog
 
+## 0.4.65 (2026-10-19)
+
+### English
+
+- **Fix: Paid Pro Argon Quota Pool Recognition & Metric Display (Fixes #46).**
+  - Added support for top-level `summary.buckets` parsing and model-level quota metrics via `/v1internal:retrieveUserQuota`.
+  - Automatically backfills `weeklyFraction` and `weeklyResetTime` when Argon models are detected in model catalog, resolving empty quota pills and dashes in `/agy pool`.
+  - Updated `/agy pool` display formatting to seamlessly fallback to `remainingFraction` when `weeklyFraction` is unset.
+- **Fix: Eliminate 15-Minute Flashing Black Terminal Window on Windows (Fixes #47).**
+  - Removed redundant `catalog.refreshIfNeeded()` background spawn from the 15-minute periodic watchdog timer, ensuring background heartbeats strictly execute HTTPS network queries without launching `agy` CLI sub-processes.
+  - Models now refresh cleanly on startup and on-demand upon model picker access.
+  - Fixed `ModelCatalog` cache TTL initialization to accurately honor `getConfig().modelsCacheTtlMs`.
+- **Fix: Quota Parity with `agy` CLI, Stale 5h Bucket Detection & Session Cleanup (Fixes #48).**
+  - Integrated official `/v1internal:retrieveUserQuota` model-level quota metrics into `refreshAccountQuota`, matching the exact figures reported by the `agy` CLI.
+  - Added `isStale5hBucket` heuristic to detect unmetered production endpoint placeholders (`remainingFraction === 1.0` with `resetTime ≈ now + 5h`) and overwrite them with active window model-level quota data.
+  - Fixed endpoint fallback behavior in `fetchQuotaSummary` so `preferredEndpointIndex` is not locked to the production endpoint when endpoint 0 (`daily-cloudcode-pa.googleapis.com`) responds normally with partial groups.
+  - Added unrounded quota percentage preview in frontend pill tooltips (`title="... (raw: 0.9711094)"`) for precise verification against raw API responses.
+  - Added automatic cleanup of stale account bindings in `sessions.json` upon engine startup and session selection.
+
+### 中文
+
+- **修复：付费 Pro 账号 Argon 额度池识别与展示（修复 #46）。**
+  - 增强额度解析，支持后端顶层 `summary.buckets` 以及通过 `/v1internal:retrieveUserQuota` 获取模型级别额度数据。
+  - 模型探测阶段发现 Argon 模型时自动补充 `weeklyFraction` 与 `weeklyResetTime`，彻底解决客户端胶囊与 `/agy pool` 中显示空白破折号（`—`）的问题。
+  - `/agy pool` 命令兼容展示 `weeklyFraction ?? remainingFraction`。
+- **修复：彻底解决 Windows 环境下每 15 分钟闪烁黑终端窗口问题（修复 #47）。**
+  - 从 15 分钟周期的后台刷新任务中移除了 `catalog.refreshIfNeeded()` 调用，使后台心跳严格保持在无外部进程的纯 HTTPS 网络请求，杜绝 Windows 终端弹窗。
+  - 模型目录在启动和模型选择器打开时按需刷新，并修复了 `ModelCatalog` 构造时硬编码 TTL 的问题（接入 `getConfig().modelsCacheTtlMs`）。
+- **修复：面板额度与 agy CLI 保持严格一致、识别 5h 虚假占位符并清理残留失效账号（修复 #48）。**
+  - 对接官方 agy CLI 相同的 `/v1internal:retrieveUserQuota` 接口，将模型级实际 WTUS 额度纳入账户额度刷新体系。
+  - 实现 `isStale5hBucket` 智能检测机制，识别生产域未记账的 5 小时虚假占位符（`remainingFraction === 1.0` 且 `resetTime ≈ now + 5h`），并由真实生效窗口数据覆盖替换。
+  - 修复 `fetchQuotaSummary` 端点降级逻辑，在 daily 域仅返回部分组别时进行多组结果合并，不再将全局端点锁死到不记账的生产域。
+  - 客户端胶囊悬浮气泡增加原始未舍入比例（例如 `97.1% (raw: 0.9711094)`）与 ISO 重置时间，方便与 agy 命令行及 API 返回对比。
+  - 启动及选择账号时自动清理 `sessions.json` 中已不存在的失效废弃账号引用。
+
+## 0.4.64 (2026-10-18)
+
+### English
+
+- **Feat: DSH Standard Error Code Alignment & Context Window Overflow Auto-Compaction.**
+  - Added `Err.CONTEXT_WINDOW_EXCEEDED` (`CONTEXT_WINDOW_EXCEEDED`), `Err.QUOTA`, and `Err.INVALID_CREDENTIAL` aligned with `@deepseek-ai/dsh-llm` standard contracts.
+  - Implemented `looksLikeContextWindowExceeded` classifier detecting Gemini/Antigravity token limit overflow signatures (`prompt is too long: \d+ tokens > \d+ maximum`, `context window exceeded`, `token limit exceeded`, etc.).
+  - Mapped context overflow to `CONTEXT_WINDOW_EXCEEDED`, allowing DSH's native agent loop to trigger context auto-compaction and summarization automatically rather than failing the turn with a fatal `PROCESS_EXIT`.
+- **Perf & Concurrency: Windows High-Concurrency & Zero-Blocking Credential Slots.**
+  - Added in-memory cached reads for Windows Credential Manager (`readWindowsCredentialRaw`, `invalidateWindowsCredentialCache`), slashing read latency from ~516ms (synchronous PowerShell process invocation) to <0.01ms (50,000x faster).
+  - Refactored `acquireCredentialSlot` cross-process locking to release `.credential-slot.lock` immediately after writing the slot identity, eliminating thread/process blocking across concurrent sessions during long LLM runs.
+  - Replaced slot join polling with an event-driven `slotEvents: EventEmitter`, providing 0ms instant wakeup for concurrent turns sharing the active identity.
+- **Feat: Multi-Turn Tool Call Disambiguation & Collision Self-Healing.**
+  - Implemented `ToolCallState`, `rememberToolCallId`, `consumeToolBinding`, and `expirePendingToolCalls` in `src/host/mapper.ts`.
+  - Disambiguates duplicate call IDs across tools (`${id}#${name}`) with FIFO ordering and assistant-turn expiration, eliminating `INVALID_ARGS` crashes in long agentic conversations.
+  - Updated `parseMirrorCallId` in `src/host/recording.ts` to seamlessly parse both canonical and hash-suffixed call IDs.
+- **Hardening: Headless Browser & Process Isolation Hardening.**
+  - Injected `AGY_CLI_NONINTERACTIVE_HEADLESS: '1'`, `BROWSER: 'none'`, and `CI: '1'` into `withAgyQuietEnv` to strictly prevent accidental browser popups during background checks.
+  - Redirected `ANTIGRAVITY_GEMINI_DIR` and `ANTIGRAVITY_APP_DATA_DIR` into isolated account directories in `isolatedHomeEnv` to eliminate credential bleed.
+- **Clean: Removed redundant native `generate_image` tool.**
+  - Fully removed `generate_image` registration, config schema, and related test fixtures.
+
+### 中文
+
+- **特性：对齐 DSH 标准错误码规范与上下文超限自动压缩触发。**
+  - 新增 `Err.CONTEXT_WINDOW_EXCEEDED` (`CONTEXT_WINDOW_EXCEEDED`)、`Err.QUOTA` 与 `Err.INVALID_CREDENTIAL`，深度对齐 `@deepseek-ai/dsh-llm` 标准协议契约。
+  - 实现 `looksLikeContextWindowExceeded` 分类器，精准识别 Gemini/Antigravity 上下文溢出特征（`prompt is too long: \d+ tokens > \d+ maximum`、`context window exceeded`、`token limit exceeded` 等）。
+  - 上下文溢出时抛出标准 `CONTEXT_WINDOW_EXCEEDED` 错误码，使 DSH 原生 Agent 循环自动触发上下文压缩（Context Compaction / Summarization），彻底告别直接进程崩溃断连（`PROCESS_EXIT`）。
+- **性能与并发：Windows 极致高并发与凭据槽位零阻塞优化。**
+  - 为 Windows Credential Manager 实现高频读内存缓存（`readWindowsCredentialRaw` / `invalidateWindowsCredentialCache`），将每次查询耗时从 516ms（同步拉起 powershell.exe）降至 <0.01ms（提速超 50,000 倍），彻底杜绝事件循环被卡死。
+  - 重构 `acquireCredentialSlot` 跨进程锁机制，在凭据写入槽位完成后立即释放 `.credential-slot.lock`，不再跨越整个 LLM 流式输出生命周期持锁，彻底解决多会话并发竞争卡死。
+  - 将轮询等待重构为基于事件的 `slotEvents: EventEmitter` 唤醒机制，同身份并发会话实现 0ms 零延迟极速放行。
+- **特性：多轮工具调用标识去重与碰撞自愈机制。**
+  - 在 `src/host/mapper.ts` 中实现 `ToolCallState`、`rememberToolCallId`、`consumeToolBinding` 与 `expirePendingToolCalls` 状态机。
+  - 对跨工具复用的相同 `callId` 自动添加后缀（`${id}#${name}`）并按 FIFO 队列匹配，在新 Assistant 消息到达时自动过期队列，杜绝 DSH `INVALID_ARGS` 报错。
+  - 同步更新 `parseMirrorCallId`，完美支持带 `#` 后缀的工具调用解析与回溯。
+- **加固：无头环境与进程隔离全面加固（防弹窗机制）。**
+  - 在 `withAgyQuietEnv` 中注入 `AGY_CLI_NONINTERACTIVE_HEADLESS: '1'`、`BROWSER: 'none'` 与 `CI: '1'`，从底层彻底阻止任何意外触发的浏览器登录弹窗。
+  - 在 `isolatedHomeEnv` 中重定向 `ANTIGRAVITY_GEMINI_DIR` 与 `ANTIGRAVITY_APP_DATA_DIR` 至账号隔离目录，杜绝环境变量遗漏导致的全局配置污染与凭据泄露。
+- **精简：移除冗余原生图像生成工具（`generate_image`）。**
+  - 彻底下线 `generate_image` 工具定义、配置项声明及对应测试文件。
+
+## 0.4.63 (2026-10-18)
+
+### English
+
+- **Fix: Prevent Mermaid post-render cleanup from deleting active diagram SVGs.**
+  - Resolved an issue where rendered flowchart SVGs were immediately removed by `cleanupTempElements` in the `finally` block due to an indiscriminate `document.getElementById(id)` query matching the newly inserted diagram SVG.
+  - Added ancestor check (`closest('[data-agy-mermaid-svg]')`) to ensure only leaked standalone temporary DOM elements outside the diagram container are purged.
+- **Fix: Enhanced Argon quota pool detection (Issue #46) and model effort support.**
+  - Added bucket-level Argon detection in quota summary parsing (`hasArgonBucket`), resolving cases where Paid Pro accounts had their Argon quota pools omitted due to varied group naming.
+  - Enabled reasoning effort folding and `--effort` parameter support for `argon`-prefixed models, and added `gemini-4-argon` to `DEFAULT_FALLBACK_MODELS`.
+- **Docs: Correct feature descriptions & refresh visual documentation.**
+  - Corrected inaccurate and exaggerated phrasing in the README feature table regarding settings consolidation, secondary parallel leases, and native context caching.
+  - Replaced dashboard screenshot with pixel-perfect mosaic redactions on all user email addresses, and enriched the documentation with real-world Token usage and 1M context metering figures.
+
+### 中文
+
+- **修复：Mermaid 流程图渲染后被清理机制误删导致内容空白消失的问题。**
+  - 修复 `cleanupTempElements` 在清理泄漏的临时 DOM 元素时，因直接通过 `document.getElementById(id)` 查找而误删了刚刚挂载到页面容器中的正式 `<svg>` 节点，导致流程图渲染后瞬间空白的问题。
+  - 增加最近祖先判断（`closest('[data-agy-mermaid-svg]')`），确保仅清理逃逸至容器外部的游离临时节点，正式图表永久保留。
+- **修复：付费 Pro 账号 Argon 额度池识别增强（Issue #46）与模型调用支持。**
+  - 在配额解析中增加 bucket 层级的 Argon 标识检测（`hasArgonBucket`），彻底解决因分组名称变体导致的付费 Pro 账号未识别 Argon 额度池的问题。
+  - 支持 `argon` 模型前缀的思维强度折叠与 `--effort` 参数传递，并在 `DEFAULT_FALLBACK_MODELS` 中补齐 `gemini-4-argon`。
+- **文档：纠正功能说明表述并升级图文文档（邮箱全面脱敏）。**
+  - 纠正 README 特性表中关于“插件页详情零冗余复用”、“同账号二次并发租赁”与“97% 缓存命中”的不准确表述，还原本质功能（设置控制台内嵌、副账号同身份并发租约、原生上下文缓存真实计量）。
+  - 全新更新控制台仪表盘截图，对所有账号邮箱实施严格的像素级马赛克脱敏，并新增真实会话 Token 用量与 1M 上下文负载的图文展示。
+
+## 0.4.62 (2026-10-17)
+
+### English
+
+- **Feat: Capacity vs. Account exhaustion separation & stay-on-capacity backoff.**
+  - **Decoupled Capacity vs. Account**: Added `looksLikeCapacityExhaustion` to distinguish upstream datacenter/cluster overload (503/529, "high demand", "capacity exceeded", "resource temporarily exhausted") from per-account rate limits (429 per-token/per-request exhaustion).
+  - **Stay Strategy**: Capacity overloads now surface as retryable `Err.OVERLOADED` (preserving `rate limit (server capacity overloaded)` for downstream compatibility). `rotateAway` skips account rotation when capacity is overloaded, avoiding rapid, fruitless churn through the entire account pool during regional Google outages.
+- **Feat: Windows cross-process slot lock with `process.kill(pid, 0)` liveness detection & instant self-healing.**
+  - **Liveness Detection**: Implemented `isProcessAlive(pid)` leveraging `process.kill(pid, 0)` with proper platform-level `ESRCH` and `EPERM` error code handling.
+  - **Instant Stale Lock Reclamation**: In `acquireCrossProcessSlotLock` for Windows multi-process slot arbitration, stale locks from abruptly killed or crashed processes are detected immediately upon PID verification and cleanly removed, eliminating unneeded blocking waits.
+- **Feat: Zero-flicker optimistic account switching & shimmer loading animation.**
+  - **Optimistic Account Switch**: Switching accounts in `AgySettingsSection` triggers an immediate 0ms UI update (`optimisticActiveId`) with graceful rollback on error, eliminating UI redraw jitter and perception latency.
+  - **Quota Shimmer Effect**: Integrated CSS shimmer animation (`@keyframes agy-shimmer` & `.agy-shimmer-track`) into quota progress bars during refresh and pending states, delivering a polished, modern look.
+- **Fix: Unified proxy indicator badge & system proxy inheritance for primary account.**
+  - **Inherited Proxy Visibility**: The proxy tag (`[globe] Proxy`) now resolves effective proxy configuration (`acc.proxyUrl || pool.systemProxy`). When accounts rely on global/system proxy settings, the proxy badge is reliably shown on the primary account alongside other accounts instead of silently omitting it.
+  - **Proxy Tooltip & Placeholder**: Hovering on the proxy tag now shows the effective proxy URL (`title: effectiveProxy`), and modal/input placeholders dynamically reflect the inherited system/global proxy URL.
+
+### 中文
+
+- **新功能：容量过载与账号配额耗尽精准解耦，机房压力下实行原地退避（Stay）。**
+  - **过载类型分离**：引入 `looksLikeCapacityExhaustion`，精准区分 Google 机房级/区域级容量瓶颈（503/529、"high demand"、"capacity exceeded"、"resource temporarily exhausted"）与单个账号的 429 频率超限。
+  - **原地退避调度（Stay）**：容量压力统一抛出可重试的 `Err.OVERLOADED`（错误信息保留 `rate limit (server capacity overloaded)` 以向下兼容）。`rotateAway` 遇到容量过载时跳过轮换、留在当前账号，彻底杜绝在机房整体拥堵时盲目将全号池快速轮换耗尽的恶性循环。
+- **新功能：Windows 跨进程凭证锁与 `process.kill(pid, 0)` 进程存活探测秒级自愈。**
+  - **进程存活性探测**：实现高可靠的 `isProcessAlive(pid)`，基于 `process.kill(pid, 0)` 准确识别 `ESRCH`（进程不存在）与 `EPERM`（跨权限存活进程）。
+  - **崩溃孤儿锁秒级清理**：在 Windows 多进程凭证槽互斥锁（`acquireCrossProcessSlotLock`）中，当持锁 PID 意外崩溃或被强杀时，竞争进程通过存活探测瞬间判定孤儿锁并自愈重置，无需冗长的超时等待。
+- **新功能：前端账号切换 0ms 乐观响应防闪烁与配额微光（Shimmer）动效。**
+  - **0ms 乐观切换**：在 `AgySettingsSection` 控制台切换账号时立即通过 `optimisticActiveId` 刷新界面状态并带有错误自动回滚保护，彻底消除切换等待过程中的白屏闪烁与延迟感。
+  - **配额微光流光动效**：配额条（`renderFamilyQuotaBar`）在刷新或等待就绪时接入平滑流光动效（`@keyframes agy-shimmer` 与 `.agy-shimmer-track`），交互反馈更具质感。
+- **修复：统一代理标识展示与主账号系统/全局代理继承识别。**
+  - **继承代理完整透出**：代理徽标（`[globe] 代理`）统一解析账号生效代理（`acc.proxyUrl || pool.systemProxy`）。当主账号继承使用系统/全局代理设置时，与号池副账号一样稳定展示代理徽标，消除“主账号缺少代理标识”的疑惑。
+  - **代理悬浮提示与输入框占位符**：鼠标悬停在“代理”徽标上可直接查看完整生效代理 URL；代理编辑框与新建账号对话框动态展示当前继承的系统代理地址。
+
+## 0.4.61 (2026-10-17)
+
+### English
+
+- **Feat: Official vector logo redesign & zero-redundancy console reuse across DSH.**
+  - **Redesigned Vector Logo** (`assets/icon.svg` & `./icon.svg` + `package.json` `icon`): Clean, transparent-background 36x36 retina vector icon featuring a vibrant antigravity orb gradient (`#38BDF8` → `#6366F1` → `#9333EA` → `#C026D3`), front/back occluded orbital rings, specular crescent highlight, and dual satellite bridge nodes (cyan & magenta). Pinned by `test/client-plugin-meta.test.ts`.
+  - **Settings & Navigation Brand Icons**:
+    - Upgraded `agyIcon` in Settings section header and Modal Console dialog to render the full official vector logo geometry.
+    - Added `installSettingsNavIcon` dynamically targeting the Settings dialog navigation sidebar (`[role="dialog"] nav button`), replacing DSH's fallback gear icon with the official Antigravity logo.
+  - **Zero-Redundancy Plugin Page Console**: Directly reuses the identical `AgySettingsSection` console in the plugins bundle/row view (`plugins.bundle.config` & `plugins.row.config`), eliminating duplicate dashboard code while keeping list card summaries clean.
+  - **Display Metadata**: Localized title and description in `locale/{en,zh,es,pt-BR}.json` ("Antigravity 桥接").
+
+### 中文
+
+- **新功能：官方矢量 Logo 视觉重构与 DSH 全场景控制台零冗余复用。**
+  - **矢量 Logo 全新设计**（`assets/icon.svg` 与 `./icon.svg` + `package.json` `icon` 字段）：采用纯透明背景、36x36 视网膜矢量微标，包含反重力渐变球体（`#38BDF8` → `#6366F1` → `#9333EA` → `#C026D3`）、前后立体穿插引力环、月牙镜面液态高光与双子引力光节点（天青与洋红）；通过 `test/client-plugin-meta.test.ts` 强校验。
+  - **设置界面与左侧导航图标全面接入 Logo**：
+    - 设置面板顶部与控制台弹窗标题的 `agyIcon` 升级为官方矢量微标几何体。
+    - 新增 `installSettingsNavIcon`，动态匹配设置对话框左侧导航菜单（`[role="dialog"] nav button`），将系统默认齿轮图标替换为专属 Antigravity Logo。
+  - **插件详情页零冗余复用**：侧边栏插件页（`plugins.bundle.config` 与 `plugins.row.config`）在详情页面中直接复用原版 `AgySettingsSection` 控制台，列表摘要卡片保持纯粹轻量，彻底避免界面冗余与代码重复。
+  - **展示元数据**：`locale/{en,zh,es,pt-BR}.json` 注入本地化展示元数据（"Antigravity 桥接"）。
+
+## 0.4.60 (2026-10-17)
+
+### English
+
+- **Fix: same-grant runs on a SECONDARY pool account now run in parallel — only identity SWITCHES serialize (cardboard-empire starvation, 2026-10-17).**
+  - **Incident**: the active pool account was a secondary (`elegantmanco@…`); only the primary account had a fast path, so every secondary run held the machine-global Windows credential slot EXCLUSIVELY for its whole run. One long agy run (the quota-investigation session, 12:34:30–12:44:18, 79 mirrored steps) starved all other sessions: three cardboard-empire turns sat at `request/context` for 8m50s+ with zero tokens even though their `request/header` had already been logged. When the long run exited the queue drained 16s later (first token 12:44:34) — the slot, not agy, was the bottleneck.
+  - **Change** (`credential-slot.ts`): the installed SECONDARY identity is now reference-counted. The first run performs the exclusive handoff and keeps the mutex; later runs on the SAME grant join as fast leases after proving the slot still carries that grant (`sameCredentialGrant` on every join, so an external slot takeover is never joined). **Runs already queued for the slot also join**: while waiting they poll every 100ms and take a lease the moment their own grant is installed, so a backlog of turns drains in parallel instead of one whole run at a time (the exact incident shape). The LAST holder persists a rotated access token and restores the primary. `fastPathRunCount()` now reports primary fast runs + live same-identity secondary holders, and `/agy status` shows the combined number.
+  - **Anti-starvation invariant preserved**: a run that needs a DIFFERENT identity (or the primary) registers a switch claim BEFORE queueing on the mutex; new same-identity joins are refused while any claim is outstanding (the single `slotSwitchPending` boolean became a `pendingSwitchClaims` counter), so a switcher can no longer be postponed indefinitely. Same-grant refreshes remain safe: refresh tokens are not single-use, and every joiner verifies the grant before running.
+  - **Tests** (`credential-slot.test.ts`): same-identity secondary runs share one installed identity and run in parallel (the mutex stays held by the owner until the last peer exits); an identity switch waits for EVERY peer; a pending switch refuses new peers (no starvation); a peer does not join an installed identity the slot no longer carries; last-holder rotated-token write-back; `parallel: false` still restores full exclusivity; existing corruption guards unchanged (26/26 pass).
+- **Fix: live Gemini quota synchronization & accurate 5h / weekly limit display.**
+  - **Root Cause**:
+    1. `AGY_ENDPOINTS` placed `https://cloudcode-pa.googleapis.com` ahead of `https://daily-cloudcode-pa.googleapis.com`. `cloudcode-pa` is the Cloud Code for VS Code legacy PA endpoint, returning a separate quota pool (which showed 4% @ 15:07).
+    2. `src/host/quota.ts` hardcoded `agyUserAgent` default to `1.1.15`. Google's Antigravity backend (`daily-cloudcode-pa.googleapis.com`) checks client versions and omits the entire `Gemini Models` group when receiving `1.1.15`, returning only third-party models. With `2.24.0` (matching Antigravity IDE 2.24.0), it immediately returns both Gemini Models and Claude/GPT groups with live 5-hour and weekly buckets.
+    3. Reordered `AGY_ENDPOINTS` to prioritize Antigravity's native `https://daily-cloudcode-pa.googleapis.com` endpoint, and updated `agyUserAgent` default version to `2.24.0`.
+  - **Result**: "刷新额度" and "同步" immediately display accurate Gemini 5-hour and weekly limits matching Antigravity IDE (e.g. 99% / 99% with correct reset countdowns) instead of getting stuck at 4%.
+- **Fix: primary account on Windows self-heals from durable verified store and prevents sibling account log pollution.**
+  - **Issue**: On Windows, the primary account (`systemHome`) could display a secondary account's email (e.g. `elegantmanco@…` instead of `g98…`) after background quota polls. The background quota poller read `detectEmailFromAgyLogs` from `~/.gemini/antigravity-cli/log`, where secondary accounts executing in the shared CLI home wrote auth success log lines.
+  - **Fix**: The primary account on Windows now binds directly to the durable verified store (`.primary-credential.json`, written only from live Google token verification). `normalizeLegacyPrimary` self-heals on startup/reload, and `detectEmailFromAgyLogs` rejects any email belonging to sibling accounts in the pool.
+
+### 中文
+
+- **修复：同一授权下的次级账号运行现在可以真正并行——只有「身份切换」才串行（cardboard-empire 饿死事件，2026-10-17）。**
+  - **事件**：当时生效的是号池里的次级账号（`elegantmanco@…`），而快路径只给系统主账号，于是每个次级运行都要独占机器级 Windows 凭据槽直到整个 run 结束。一个长 agy 运行（额度排查会话，12:34:30–12:44:18，79 个镜像步骤）把其它会话全部饿死：三个 cardboard-empire 回合停在 `request/context` 8 分 50 秒以上、零 token，而它们的 `request/header` 早已记录。长运行退出后 16 秒内队列就动了起来（12:44:34 首个 token）——证明瓶颈是凭据槽而不是 agy。
+  - **改动**（`credential-slot.ts`）：次级账号装入槽位的身份改为**引用计数**。第一个 run 完成独占交接并持有互斥锁；之后**同一授权**的 run 通过 `sameCredentialGrant` 校验槽位仍携带该凭据后直接加入（外部改写槽位时不会误加入）。**已经排队等槽的 run 也会加入**：排队期间每 100ms 轮询一次，一旦自己的授权被装入就立刻转成并行租约——这样一整批积压回合会并行排空，而不是一个 run 接一个 run 地串（正是本次事件形态）。**最后一个 holder** 才回写轮换后的 access token 并还原主账号。`fastPathRunCount()` = 主账号快路径 + 次级同身份在跑数，`/agy status` 展示合并值。
+  - **防饿死不变量保留**：需要切换身份（或切回主账号）的运行会在排队**之前**登记切换声明；只要有声明未完成，新的同身份 run 一律拒绝加入（原来的单个 `slotSwitchPending` 布尔改为 `pendingSwitchClaims` 计数），切换者不会再被无限推迟。同授权并发刷新是安全的（refresh token 非一次性），且每个加入者都会先校验授权。
+  - **测试**：同身份次级并行（互斥锁由所有者持有直到最后一个 peer 退出）、身份切换等待全部 peer、切换待定时拒绝新 peer（防饿死）、槽位被外部改写时不加入、最后持有者回写轮换 token、`parallel: false` 仍完全串行、原有防损坏守卫不变（26/26 通过）。
+- **修复：Gemini 额度显示 4% 卡死及刷新/同步无效问题，还原真实的 5 小时与周额度。**
+  - **根本原因**：
+    1. `AGY_ENDPOINTS` 此前误将 `https://cloudcode-pa.googleapis.com`（Cloud Code PA 遗留端点）置于首位，导致请求命中了非 Antigravity 的老配额周期（显示为 4.06% ↺ 15:07）。
+    2. `src/host/quota.ts` 中的 `agyUserAgent` 默认写死了版本号 `1.1.15`。Google Antigravity 后端（`daily-cloudcode-pa.googleapis.com`）对客户端版本有特性拦截：当 UA 为 1.x 时，响应中直接剔除 `Gemini Models` 额度组，导致此前测试误以为该端点缺失 Gemini 数据。更新为 `2.24.0`（与 Antigravity IDE 2.24.0 官方客户端一致）后，后端即刻完整返回 Gemini Models 的 5 小时与周额度。
+    3. 将 `AGY_ENDPOINTS` 调整为优先请求 Antigravity 原生端点 `https://daily-cloudcode-pa.googleapis.com`，并将 `agyUserAgent` 默认版本升级为 `2.24.0`。
+  - **效果**：点击「刷新」或「同步」后，插件面板即刻正确呈现与 Antigravity IDE 一致的真实额度（如 99% 5 小时额度与 99% 周额度及各自正确的重置倒计时），不再卡死在 4%。
+- **修复：Windows 主账号身份自愈并防御副账号日志污染（主账号显示为副账号邮箱问题）。**
+  - **问题**：在 Windows 单槽位多账号环境下，后台每 15 分钟的额度轮询通过 `detectEmailFromAgyLogs` 扫描全局 CLI 日志目录；当副账号（如 `elegantmanco@…`）在本地运行留下认证日志后，主账号邮箱被误覆盖为副账号，导致控制面板主账号显示错误。
+  - **修复**：主账号在 Windows 下权威绑定持久化验证凭据（`.primary-credential.json`），启动与重新载入时通过 `normalizeLegacyPrimary` 自动自愈；日志探测增加兄弟账号守卫（Sibling Account Guard），坚决忽略已在号池中的副账号邮箱，杜绝反向污染。
+
+## 0.4.59 (2026-10-16)
+
+### English
+
+- **Fix: turns queued for the Windows credential slot could pend forever as invisible zombies, immune to Stop (cardboard-empire incident, 2026-10-16 22:44).**
+  - **Incident**: a turn dispatched while another session's 32-minute run held the process-global credential slot never received the release wake-up. The turn sat at `request/context` with no agy process spawned for 30+ minutes; the idle watchdog never armed (it only arms after spawn); Stop did nothing because no wait in the dispatch phase observed the abort signal; and the leaked dispatch held one of the 3 `maxConcurrent` slots, starving later turns of other sessions into the same wedge.
+  - **Changes**:
+    1. **`AsyncMutex` rewrite** (`credential-slot.ts`): the promise-chain FIFO could never remove a waiter — an abandoned/aborted one would wedge the whole chain behind it. Now an explicit queue: a cancelled or timed-out waiter is REMOVED and the holder's release wakes the head directly. Cancelling a waiter deliberately does NOT grant the mutex (it is still held).
+    2. **Abort + bounded wait for the slot** (`acquireCredentialSlot`): new `signal` / `dispatchTimeoutMs` resolve-options. Stop now ends a queued dispatch immediately (`AbortedWaitError`); a bounded wait fails visibly (`WaitTimeoutError`) instead of parking silently.
+    3. **Lost-wake-up self-heal**: while queued, a liveness poll (5s) re-checks and takes the mutex directly if it is actually free — the exact failure shape from the incident now self-corrects within seconds even if a wake-up is ever lost again.
+    4. **Dispatch observability**: a 2-minute heartbeat logs the queue state ("dispatch still waiting Nm — X waiter(s), Y holder(s) … press Stop to cancel") so a stuck dispatch is visible in the console instead of a silent spinner.
+    5. **Dispatch retry** (`adapter.ts`): on a hard-cap slot timeout the dispatch releases the concurrency slot, backs off abort-aware (2s→4s→…→15s), and retries (`dispatchRetries`, default 1); exhaustion fails the turn VISIBLY with guidance — never an infinite pending state. Retry is confined to the pre-spawn dispatch phase; a turn that already emitted output is never re-driven.
+    6. **Rate-limit spacing sleep** is now abort-aware (Stop during the 60s window no longer spawns a turn nobody is reading).
+  - **Config**: new `dispatchTimeoutMinutes` (default **15** — each attempt waits up to 15 minutes for the slot, so persistence ≈ (1+retries)×15 min before a visible failure; 0 = wait indefinitely, still abort-aware / poll-healed / heartbeat-logged) and `dispatchRetries` (default 1). User-facing entry: `/agy dispatch` (inspect live queue + effective caps), `/agy dispatch <minutes|off>` and `/agy dispatch-retries <n>` — persisted via runtime overrides, effective next turn.
+  - **Fix: artificial concurrency limits removed — native agy parallelism restored.**
+    - agy is a stateless CLI and handles concurrent processes natively; the only machine-global constraint on Windows is the single credential store, and only when its IDENTITY changes.
+    - **Same-account fast path** (`parallelSameAccount`, default **on**): a run whose credential already sits in the slot starts immediately WITHOUT the mutex, so N sessions on one account run truly in parallel (concurrent refreshes on one grant are safe — refresh tokens are not single-use). `/agy parallel <on|off>` toggles it.
+    - **Account switches still serialize** (correctness): a secondary waits for same-account runs to drain before swapping the slot, new fast paths are refused while a switch pends, and the switch restores the primary afterwards — the anti-corruption invariants are unchanged and covered by new tests.
+    - **`maxConcurrent` default 3 → 0 (unlimited)**: no artificial admission bound; Google rate limits and the pool's cooldowns are the natural regulators. `/agy max-concurrent <n|off>`.
+  - **Fix: quota merge — the real remaining was blocked by the 6h window gate.** When the 5h bucket is exhausted, Google reports the NEXT reset at the weekly boundary (14+ hours out); the `is5hWindow` gate (reset must land within 6h) skipped the per-model merge, so the UI kept showing the coarse summary's meaningless "100%, resets in now+5h" placeholder while the account was actually down to **4.06%** (observed live 2026-10-17 00:37: reported reset 05:37:49 == refresh+5h exactly, while every model row carried 4.06% @ 15:07). The merge now tightens to the LOWEST reported remaining regardless of which window it owns; the weekly row stays visible separately. Regression test reproduces the exact incident numbers.
+  - **Fix: goal completion short-circuit swallowed genuine user messages.** `isGoalToolContinuation` scanned a fixed trailing window for goal markers "anywhere": a message sent right after a goal completed (the goal tool-result was still in that window) was finished as an EMPTY turn without spawning agy — twice in a row, "把相关的经验整理到agents.md" never reached the agent (2026-10-17, turns completed in 7s/16s with zero output). The scan now walks backwards and STOPS at a genuine user instruction (harness-injected texts — time samples, system-reminder wrappers, runtime context — stay transparent), so markers only short-circuit while they are actually the trailing content.
+  - **Tests**: mutex cancel-removes-and-wakes-next; timeout keeps the queue flowing; lost-wake-up poll grant; `acquireCredentialSlot` rejects when already aborted, honors Stop while queued, and fails visibly on the bounded wait; same-account fast path / drain / starvation; quota weekly-boundary tightening; goal-continuation genuine-message cases.
+
+### 中文 (Chinese)
+
+- **修复：排队等 Windows 凭据槽位的回合可能永远挂起成隐形僵尸，且 Stop 无法取消（cardboard-empire 事件，2026-10-16 22:44）。**
+  - **事件**：一个回合在另一会话 32 分钟长任务持有进程级凭据槽位期间派发，之后永远没有收到释放唤醒。该回合停在 `request/context`，30 多分钟没有拉起任何 agy 进程；空闲看门狗从未武装（只在 spawn 后才武装）；按 Stop 无效，因为派发阶段的所有等待都没有观察中止信号；泄漏的派发还占着 3 个 `maxConcurrent` 槽位之一，把其他会话的新回合也拖进同样的卡死。
+  - **修改**：
+    1. **重写 `AsyncMutex`**（credential-slot.ts）：原来的 promise 链式 FIFO 无法移除等待者——一个被放弃/中止的等待者会把整条链卡死。现在改为显式队列：被取消/超时的等待者会被移除，持有者释放时直接唤醒队头。取消等待者刻意不发放互斥锁（锁仍被持有）。
+    2. **槽位等待支持中止与限时**（`acquireCredentialSlot`）：新增 `signal` / `dispatchTimeoutMs` 选项。Stop 现在立即结束排队中的派发（`AbortedWaitError`）；限时等待可见地失败（`WaitTimeoutError`），不再静默挂起。
+    3. **丢失唤醒自愈**：排队期间每 5 秒自检一次，发现锁实际空闲就直接取锁——即使唤醒再次丢失，本事件形态也会在数秒内自愈。
+    4. **派发可观测性**：每 2 分钟心跳记录队列状态（"dispatch still waiting Nm — X waiter(s), Y holder(s) … press Stop to cancel"），卡死的派发在控制台可见，而不是无声转圈。
+    5. **派发重试**（adapter.ts）：槽位硬超时后释放并发槽位、可中止退避（2s→4s→…→15s）并重试（`dispatchRetries`，默认 1）；重试耗尽则让回合可见地失败并给出处理指引——绝不无限 pending。重试仅限 spawn 前的派发阶段；已经产出内容的回合绝不重跑。
+    6. **限流退避 sleep** 支持中止（60 秒窗口内的 Stop 不再照常 spawn 一个没人读的回合）。
+  - **配置**：新增 `dispatchTimeoutMinutes`（默认 **15** —— 每轮最多等 15 分钟，含重试总坚持 ≈ (1+重试)×15 分钟后可见失败；0 = 无限等待，仍可中止/轮询自愈/心跳可见）与 `dispatchRetries`（默认 1）。用户入口：`/agy dispatch`（查看实时队列与当前配置）、`/agy dispatch <分钟|off>` 与 `/agy dispatch-retries <次数>` —— 经 runtime overrides 持久化，下一回合生效。
+  - **修复：移除人为并发限制，恢复 agy 原生并行能力。**
+    - agy 是无状态 CLI，天然支持多进程并发；Windows 上唯一的机器级约束是单一凭据库，且仅在**账号身份切换**时才需要互斥。
+    - **同账号快路径**（`parallelSameAccount`，默认**开**）：凭据已在槽位中的账号立即启动、完全不取互斥锁 —— N 个会话在同一账号上真并行（同一授权的并发 token 刷新是安全的，refresh token 非一次性）。`/agy parallel <on|off>` 开关。
+    - **账号切换仍然串行**（正确性）：副账号先等同账号 run 全部退出再换槽位；切换等待期间拒绝新的快路径；切换完成后恢复主账号 —— 防腐蚀不变量原样保留，新增测试覆盖。
+    - **`maxConcurrent` 默认 3 → 0（不限制）**：移除人为准入上限；Google 速率限制与账号池冷却是天然调节器。`/agy max-concurrent <n|off>`。
+  - **修复：配额合并 —— 真实剩余被 6 小时窗口门槛挡掉。** 5 小时桶耗尽时，Google 把下一次重置报在周边界（14+ 小时后）；`is5hWindow` 门槛（重置必须落在 6 小时内）跳过了逐模型合并，于是界面持续显示粗粒度汇总端点那个无意义的"100%，now+5h 重置"占位值，而账号实际只剩 **4.06%**（2026-10-17 00:37 实测：上报重置 05:37:49 恰好等于刷新时刻+5h，而所有模型行都是 4.06% @ 15:07）。合并现在无条件取各来源中**最低**的剩余值；周额度行照常单独显示。回归测试复现了本次事故的精确数字。
+  - **修复：目标完成短路吞掉了真实用户消息。** `isGoalToolContinuation` 在固定尾部窗口里"任意位置"找目标标记：目标完成后立刻发送的消息（目标工具结果还在窗口里）被当成完成跳直接空转结束——连续两次，"把相关的经验整理到agents.md" 根本没到达 agent（2026-10-17，7 秒/16 秒"已完成"但零输出）。扫描改为从末尾回溯，遇到**真实用户指令即停止**（宿主注入的文本——时间采样、system-reminder 包裹、运行时上下文——保持透明），目标标记只有在真正处于末尾时才短路。
+  - **测试**：互斥锁取消后移除并唤醒下一个；超时不阻塞队列；丢失唤醒的轮询补偿；`acquireCredentialSlot` 已中止即拒绝、排队中响应 Stop、限时等待可见失败；同账号快路径 / 排空 / 防饿死；配额周边界收紧；目标延续真实消息场景。
+
+## 0.4.58 (2026-10-16)
+
+- **Fix: DSH `/goal` loop restart bug (autonomous runs continuing indefinitely instead of marking complete).**
+  - **Root Cause**:
+    1. In `src/host/mapper.ts`, whenever an agy run finished with `!ev.ok` (e.g. background EOF/network timeout right as generation finishes), it yielded `{ type: 'finish', reason: { kind: 'stop' } }` and returned early, bypassing the `supportsGoalUpdate` synthetic `update_goal` completion call even when agy generated a full, successful text response. DSH interpreted this as an uncompleted round and scheduled subsequent rounds indefinitely.
+    2. In `src/index.ts`, `sessionGoal` attempted to read `session.events`, but DSH `Session` instances store events in `session.log` / `session.snapshotEvents()`, causing session goal resolution to always return `null`.
+    3. In `src/host/dsh-goal.ts`, `isGoalToolContinuation` only inspected `messages[messages.length - 1]`. When DSH executes `update_goal`, it defers a `<goal_complete>` user notice (`source.kind: 'tool-goal'`), placing the tool result at `messages.length - 2` and causing agy to respawn on the completion notice.
+  - **Fix**:
+    1. `EventMapper.map` now unifies the finish path so `update_goal` and `exit_plan_mode` are always dispatched upon successful response generation regardless of trailing transport EOF flags.
+    2. `sessionGoal` queries DSH's live `ctx.goals.get(agent)` in O(1) and falls back to `session.log` / `session.snapshotEvents()`.
+    3. `isGoalToolContinuation` checks the trailing span for `agytc-bridge-goal-`, `source.kind === 'tool-goal'`, and `<goal_complete>`, finishing cleanly without respawning agy.
+    4. Marked `tool-goal` and `<goal_complete>` as synthetic harness messages so they never get treated as human user instructions.
+
+- **Fix: real-time 5-hour quota consumption and rolling countdown now accurately display instead of staying frozen at 100% / blank.**
+  - **Root Cause**:
+    1. Google's `retrieveUserQuotaSummary` endpoint returns coarse group-level numbers (`gemini-5h: 1.0`), while `fetchAvailableModels` reports the actual per-model 5-hour consumption and active rolling reset time (e.g. `0.70`, reset in 12 minutes). `QuotaService.refreshAccountQuota` gated the per-model tightening behind `else if (familyQuotas[fam]!.remainingFraction === undefined)`, so whenever the coarse summary returned `1.0`, active model usage was completely ignored and the family quota was locked at `100%`.
+    2. In `fetchAvailableModels`, hitting any staging endpoint (`daily-cloudcode-pa`) set `this.preferredEndpointIndex`, causing subsequent `retrieveUserQuotaSummary` calls to target the staging endpoint (which omits Gemini entirely).
+    3. `mergeFallbackFamilyQuota` returned stale `prev` data whenever `prev.remainingFraction` existed, freezing accounts at their 10:04 AM state (`resetTime` in the past), which caused `formatQuotaWindow` to drop the expired timestamp as empty and render no duration at all.
+  - **Fix**:
+    1. `fetchAvailableModels` now only sets `preferredEndpointIndex` if the endpoint is the official production endpoint (index 0).
+    2. Active 5-hour model consumption (window <= 6h) now tightens `familyQuotas[fam].remainingFraction` and its `resetTime` even when summary returned a coarse `1.0`.
+    3. Full-quota rows where `resetTime` has expired safely fall back to "已重置 · 可用" instead of a blank row, while active windows display the real rolling countdown (e.g. `↻ 02:50 (4小时 55分钟)`).
+
 ## 0.4.57 (2026-10-16)
 
 ### English

package/README.md

@@ -24,13 +24,18 @@
 
 # 中文
 
-把 **Google Antigravity 模型接入 DeepSeek Harness（DSH）** —— 支持**多账号智能池化轮换**、**官方双 Bucket 配额监控（5小时滚动 + 7天周额度）**、**浏览器免粘贴一键登录**与**浅色/深色主题高对比度自适应**，由官方未修改的 `agy` CLI 驱动，完整支持流式输出、思考折叠（thinking）、原生工具卡片与精确 token 用量。
+把 **Google Antigravity 模型接入 DeepSeek Harness（DSH）** —— 支持**多账号智能池化轮换**、**官方多 Bucket 配额监控（5小时滚动 + 7天周额度 + Argon 独立周池）**、**浏览器免粘贴一键登录**与**浅色/深色主题高对比度自适应**，由官方未修改的 `agy` CLI 驱动，完整支持流式输出、思考折叠（thinking）、原生工具卡片与精确 token 用量。
 
 <p align="center">
   <img src="./docs/assets/dashboard.png" alt="Antigravity 管理控制台 - 多账号池化与配额监控" width="460" />
   &nbsp;&nbsp;
   <img src="./docs/assets/model-picker.png" alt="DSH 模型选择器中的 Antigravity 模型列表" width="220" />
 </p>
+<p align="center">
+  <img src="./docs/assets/token-usage.png" alt="原生上下文缓存与 Token 用量统计" width="340" />
+  &nbsp;&nbsp;
+  <img src="./docs/assets/context-metering.png" alt="1M 物理上下文负载精确计量" width="340" />
+</p>
 
 ---
 
@@ -54,11 +59,14 @@
 
 - 👥 **多账号池化管理 (Account Pool)**：在 DSH 内添加任意数量的 Google 账号（主账号 + 备用账号群），每个账号拥有独立的 HOME 目录沙箱与凭证隔离。
 - 🔄 **顺序耗尽故障转移 (Sequential Drain)**：当前账号额度用尽（触发 429 限流或 5h / 周额度耗尽）时，系统**自动平滑接力至下一个可用账号**，对话完全不中断！
-- 📊 **官方双 Bucket 配额监控 (Dual-Bucket Quota)**：直接调用 Antigravity 官方专用的 `v1internal:retrieveUserQuotaSummary` 接口，同时展示 **5小时滚动额度** 与 **7天周额度** 真实数据及精准重置倒计时。
+- 🕰 **额度到期优先轮换 (Quota-Expiry-First)**：多个账号可用时，优先切换到**重置窗口最早到期**的账号，把"还剩很久才重置"的额度留给后面，整体池化利用率最大化。
+- 🧠 **网络抖动智能甄别 (Jitter-Safe Auth)**：代理抖动导致的 keyring 鉴权超时会被自动识别为**可重试的网络错误**而非"登录失效"——基于 agy 本次运行日志的 `keyringAuth` 传输证据精准分类，且粘性"需重新登录"隔离需二次确认，健康账号绝不会被误标。
+- 📊 **官方多 Bucket 配额监控 (Multi-Bucket Quota)**：直接调用 Antigravity 官方专用的 `v1internal:retrieveUserQuotaSummary` 接口，同时展示 **5小时滚动额度**、**7天周额度**，以及付费 Pro/Ultra 账号专属的 **Gemini 4 Argon 独立周额度池**（不占用普通 Gemini 池）。
+- 🔀 **手动切换当前账号 (Manual Switch-Active)**：控制台卡片一键「设为当前使用」，即刻把调度指针钉到指定账号。
 - 🔑 **GUI 内浏览器免粘贴登录 (In-GUI Zero-Paste OAuth)**：点击「➕ 添加账号」自动调起系统浏览器，本地回环监听自动捕获授权凭证，**全程无需手动复制粘贴授权码**。
 - 🎨 **多主题高对比度自适应 (Light & Dark Themes)**：原生适配 DSH 浅色/深色主题，告别发暗发灰与看不清文字，UI 视觉清晰锐利。
-- 🌐 **独立账号网络代理 (Per-Account Proxy)**：支持为每个账号独立绑定 HTTP(S) / SOCKS 代理，避免多账号同 IP 引起风控。
-- ⚡ **分模型族独立冷却 (Family-Scoped Cooldown)**：Gemini 与 Claude / GPT-OSS 速率限制独立计算，某个模型族受限不影响其他模型族正常调用。
+- 🌐 **独立账号网络代理 (Per-Account Proxy)**：支持为每个账号独立绑定 HTTP(S) / SOCKS 代理，避免多账号同 IP 引起风控；未显式配置时自动探测系统代理（macOS `scutil` / Windows 注册表 / Linux gsettings）。
+- ⚡ **分模型族独立冷却 (Family-Scoped Cooldown)**：Gemini、Claude、GPT-OSS 与 Argon 的速率限制独立计算，某个模型族受限不影响其他模型族正常调用。
 
 ---
 
@@ -66,21 +74,27 @@
 
 | 能力 | 说明 |
 | ---- | ---- |
-| 👥 **多账号池化轮换** | 支持主账号 + 多个备用账号；遇到 429 或配额耗尽自动平滑切换，模型族独立冷却 |
-| 📊 **官方双 Bucket 配额监控** | 实时拉取官方端点，同时呈现 **5h 滚动额度** 与 **7d 周额度** 双进度条与倒计时，单模型明细可展开 |
+| 🎨 **官方专属矢量 Logo** | 36×36 高质感纯矢量微标（`assets/icon.svg`），透明底自适应深浅主题；设置左侧导航菜单（`[role="dialog"] nav`）动态替换系统齿轮，呈现专属品牌标识 |
+| 🧩 **设置与插件面板统一** | 在 DSH「设置 → 插件」详情页直接内嵌 Antigravity 完整控制台，账号池、配额监控与代理配置一站式操作，列表保持轻量整洁 |
+| 🚀 **副账号并发租约** | Windows 凭据槽支持同一副账号多会话共享租约并发运行，消除单账号多任务排队饥饿；仅在跨账号身份切换时串行交接 |
+| ⚡ **原生上下文缓存与真实计量** | 完整映射 Google Gemini 原生上下文缓存协议（`cache_read_tokens`），精准追踪缓存读取与物理上下文占用，深度适配 1M 超长上下文 |
+| 👥 **多账号池化轮换** | 支持主账号 + 多个备用账号；遇到 429 或配额耗尽自动平滑切换，模型族独立冷却，额度到期早的账号优先接班 |
+| 🧠 **抖动安全鉴权 (Jitter-Safe Auth)** | 基于 agy 运行日志的 keyring 传输证据区分"网络抖动"与"真登出"，抖动自动按可重试网络错误处理；粘性隔离需二次确认，杜绝误标"需重新登录" |
+| 📊 **官方多 Bucket 配额监控** | 实时拉取官方端点，同时呈现 **5h 滚动额度**、**7d 周额度**与 **Argon 独立周池**（付费 Pro/Ultra）多进度条与倒计时，单模型明细可展开 |
 | 🔑 **浏览器一键登录** | 点击添加账号自动唤起 Google 授权页，本地回环自动捕获，全程无需复制粘贴任何代码 |
+| 🔀 **手动切换当前账号** | 控制台「设为当前使用」按钮即刻钉住调度指针；顶部徽标始终显示服务器实际调度的账号 |
 | 🎨 **多主题高对比 UI** | 浅色、深色主题自适应变色，纯矢量 SVG 图标（无 Emoji），字迹清晰不发暗 |
-| 🌐 **独立账号代理** | 每个账号支持独立配置 HTTP(S) 代理，隔离 IP 出口 |
-| 🔌 **原生模型路由** | 在 DSH 模型配置中注册 `antigravity` 提供方，`/model` 选择器随心切换 Gemini / Claude / GPT-OSS |
+| 🌐 **独立账号代理** | 每个账号支持独立配置 HTTP(S) 代理，隔离 IP 出口；亦可自动探测系统代理 |
+| 🔌 **原生模型路由** | 在 DSH 模型配置中注册 `antigravity` 提供方，`/model` 选择器随心切换 Gemini / Claude / GPT-OSS / Argon |
 | 🌊 **完整流式映射** | 文本、思考过程（thinking turn）与工具活动均无损映射到 DSH 原生流协议 |
 | 🃏 **原生工具卡片** | agy 执行的终端命令（`run_command`）、文件修改（inline diff）均以 DSH 原生卡片渲染 |
 | 🔗 **会话上下文保真** | DSH 会话与 agy 原生会话绑定（`--conversation`），由 agy 管理完整历史，每轮仅发送增量 |
+| 🎯 **DSH 目标与计划集成** | 长任务自动携带 DSH goal / plan 上下文，工具续跑不丢任务状态 |
 | 📊 **精确 Token 统计** | 输入 / 输出 / 思考 / 缓存读取 token 完整计入 DSH 用量统计，全面适配 1M 上下文 |
 | 🎛 **顶部控制台徽标** | 顶部栏 `AGY (n)` 徽标一键弹出控制台，直观查看账号池、配额进度条与代理状态 |
 | 🖼 **图片多模态** | 支持多模态图片传入，自动落盘本地媒体目录并通过 `--add-dir` 安全授权给 agy 查看 |
 | 🤝 **`agy_ask` 辅助工具** | 允许任意 DSH 模型把单次任务委托给 Antigravity 模型（AskAntigravity 协作模式） |
-| ⌨️ **`/agy` 快捷命令族** | `status` / `auth` / `models` / `mode` / `effort` / `workspace` / `clear` / `doctor` / `help` |
-
+| ⌨️ **`/agy` 快捷命令族** | `status` / `pool` / `auth` / `models` / `mode` / `effort` / `workspace` / `goal` / `session` / `enable-account` / `disable-account` / `clear` / `doctor` / `help` |
 ---
 
 ## 📋 前置要求
@@ -143,9 +157,23 @@ dsh plugin --profile web add dsh-agy-link
 ## 🧩 架构与工作原理
 
 1. **短生命周期进程驱动**：每一轮 DSH 对话启动一个独立的官方 `agy -p --output-format stream-json` 进程，解析 NDJSON 事件流。
-2. **多账号沙箱机制**：除主账号沿用系统默认 Keychain / HOME 外，所有备用账号在插件私有目录下建立专属 HOME 隔离区，独立写入 agy 格式的标准 OAuth 凭证。
-3. **双 Bucket 官方配额汇总**：插件定时后台静默轮询官方 `v1internal:retrieveUserQuotaSummary`，精准掌控每个账号的 5h 滚动削峰水位与 7d 账号阶梯周额度。
-4. **会话级无缝故障转移**：当遭遇 HTTP 429、额度耗尽或凭证异常时，号池调度器自动标记当前账号家族进入冷却，并无缝将后续请求路由到池内下一个有效账号。
+2. **多账号沙箱机制**：除主账号沿用系统默认 Keychain / HOME 外，所有备用账号在插件私有目录下建立专属 HOME 隔离区，独立写入 agy 格式的标准 OAuth 凭证。Windows 上 agy 的凭据实际存放在机器级 Credential Manager（`gemini:antigravity`），插件因此以「身份级引用计数租约」接管该槽：**同一授权的多个会话并行运行**，只有账号**身份切换**才串行，且由最后一个持有者还原主账号凭据。
+3. **多 Bucket 官方配额汇总**：插件定时后台静默轮询官方 `v1internal:retrieveUserQuotaSummary`，精准掌控每个账号的 5h 滚动削峰水位、7d 账号阶梯周额度，以及付费账号的 Argon 独立周池。
+4. **会话级无缝故障转移**：当遭遇 HTTP 429、额度耗尽或凭证异常时，号池调度器自动标记当前账号家族进入冷却（或按额度到期时间择优轮换），并无缝将后续请求路由到池内下一个有效账号。
+5. **失败分类与自愈**：错误按 AUTH / NETWORK / RATE_LIMIT / ELIGIBILITY 等精确分类；网络抖动借由 agy 运行日志自动甄别为可重试故障，绝不误伤健康账号的登录状态。
+
+---
+
+## ❓ 常见问题排查 (FAQ)
+
+### Windows 平台开始对话时为什么会短暂闪一下黑色命令行窗口（黑框）？
+**答：这是 Windows 系统的控制台分配机制，完全良性，不会影响对话和模型功能。**
+- **原因分析**：DSH 是基于 Electron 的图形桌面应用（GUI 进程），每次发起对话时，插件需要调用底层命令校验并同步当前账号在 Windows 凭据管理器（Credential Manager）中的 OAuth Token，随后启动 `agy.exe` 控制台子进程建立流式通信。在 Windows 11 下，系统默认终端若被设为「Windows 终端 (Windows Terminal)」，Windows Terminal 会拦截后台控制台子进程的句柄分配并闪现弹窗（这是 Windows Terminal 已知的 OpenConsole 委托拦截机制）。
+- **解决步骤**：
+  1. 打开 **Windows 终端 (Windows Terminal)** 的「设置」→「启动」（或进入 Windows「设置」→「系统」→「开发者选项」）。
+  2. 将 **默认终端应用程序 (Default terminal application)** 从「让 Windows 决定」或「Windows 终端」更改为 **「Windows 控制台主机 (Windows Console Host)」**。
+  3. 点击右下角 **保存 (Save)**。
+  4. **完全退出并重启 DSH**（使新启动的主进程应用更新后的控制台委托注册表），黑框闪烁即可彻底消除。
 
 ---
 
@@ -170,13 +198,18 @@ MIT License.
 
 # English
 
-Bring **Google Antigravity models into DeepSeek Harness (DSH)** — featuring **Multi-Account Pooling & Automatic Rotation**, **Official Dual-Bucket Quota Tracking (5h Rolling + 7d Weekly)**, **Zero-Paste In-GUI OAuth Login**, and **Theme-Adaptive High-Contrast UI**, powered by the official unmodified `agy` CLI.
+Bring **Google Antigravity models into DeepSeek Harness (DSH)** — featuring **Multi-Account Pooling & Automatic Rotation**, **Official Multi-Bucket Quota Tracking (5h Rolling + 7d Weekly + Argon Weekly Pool)**, **Zero-Paste In-GUI OAuth Login**, and **Theme-Adaptive High-Contrast UI**, powered by the official unmodified `agy` CLI.
 
 <p align="center">
   <img src="./docs/assets/dashboard.png" alt="Antigravity Management Console - Multi-Account Pool & Quota Monitor" width="460" />
   &nbsp;&nbsp;
   <img src="./docs/assets/model-picker.png" alt="Antigravity Model Lineup in DSH Model Picker" width="220" />
 </p>
+<p align="center">
+  <img src="./docs/assets/token-usage.png" alt="Native Context Caching & Token Usage Breakdown" width="340" />
+  &nbsp;&nbsp;
+  <img src="./docs/assets/context-metering.png" alt="Accurate 1M Context Window Metering" width="340" />
+</p>
 
 ---
 
@@ -199,11 +232,14 @@ Have multiple Google Antigravity / Gemini accounts? **dsh-agy-link makes multi-a
 
 - 👥 **Multi-Account Pooling**: Manage unlimited Google accounts (Primary + Secondary pool) with fully isolated HOME sandbox environments and credentials.
 - 🔄 **Sequential Drain Failover**: When an account reaches its rate limits (429) or runs out of 5h/weekly quotas, requests **automatically and smoothly fail over to the next available account** without interrupting your conversation!
-- 📊 **Official Dual-Bucket Quota Tracking**: Direct integration with Antigravity's official `v1internal:retrieveUserQuotaSummary` endpoint, providing real-time visibility for both **5-Hour Rolling Limit** and **7-Day Weekly Limit** with live countdowns.
+- 🕰 **Quota-Expiry-First Rotation**: With several accounts available, the scheduler prefers the one whose **reset window expires soonest**, maximizing utilization across the whole pool.
+- 🧠 **Jitter-Safe Auth Classification**: A keyring-auth timeout caused by proxy jitter is recognized as a **retryable network error**, not a sign-out — classified from the `keyringAuth` transport evidence in agy's own run log, and sticky "needs re-login" quarantine requires a second confirmation, so healthy accounts are never falsely flagged.
+- 📊 **Official Multi-Bucket Quota Tracking**: Direct integration with Antigravity's official `v1internal:retrieveUserQuotaSummary` endpoint, providing real-time visibility for the **5-Hour Rolling Limit**, the **7-Day Weekly Limit**, and the **Gemini 4 Argon weekly pool** (paid Pro/Ultra accounts, billed separately from the plain Gemini pool).
+- 🔀 **Manual Switch-Active**: One click on "Set active" pins the scheduler pointer to the account you choose.
 - 🔑 **In-GUI Zero-Paste OAuth**: One-click "Add Account" opens your browser and automatically captures OAuth tokens via local loopback — **no copying and pasting of authorization codes required**.
 - 🎨 **Theme-Adaptive High-Contrast UI**: Seamlessly adapts to Light and Dark DSH themes with crystal clear typography and crisp contrast.
-- 🌐 **Per-Account Proxy**: Configure dedicated HTTP(S) / SOCKS proxy for each individual account to isolate IP addresses.
-- ⚡ **Family-Scoped Cooldowns**: Gemini, Claude, and GPT-OSS rate limits are calculated independently, preventing one exhausted model from blocking others.
+- 🌐 **Per-Account Proxy**: Configure dedicated HTTP(S) / SOCKS proxy for each individual account to isolate IP addresses; when unset, the system proxy is auto-detected (macOS `scutil` / Windows registry / Linux gsettings).
+- ⚡ **Family-Scoped Cooldowns**: Gemini, Claude, GPT-OSS, and Argon rate limits are calculated independently, preventing one exhausted model from blocking others.
 
 ---
 
@@ -211,20 +247,27 @@ Have multiple Google Antigravity / Gemini accounts? **dsh-agy-link makes multi-a
 
 | Feature | Description |
 | --- | --- |
-| 👥 **Multi-Account Pool** | Primary + unlimited spare accounts with automatic Sequential Drain rotation upon rate limits |
-| 📊 **Dual-Bucket Quota HUD** | Real-time dual progress bars for both **5h rolling** and **7d weekly** quota limits with exact reset countdowns |
+| 🎨 **Official Vector Logo** | Clean 36×36 retina vector mark (`assets/icon.svg`) with transparent background; dynamically replaces fallback gear in DSH Settings sidebar (`[role="dialog"] nav`) |
+| 🧩 **Unified Settings & Plugin Console** | Embedded Antigravity console directly in DSH Plugins settings; configure account pool, quotas, and proxies in one place while keeping list cards clean |
+| 🚀 **Secondary Account Parallel Leases** | Windows credential slot allows concurrent sessions on the same account to share leases without queue starvation; serializes only for cross-account switches |
+| ⚡ **Native Context Caching & Token Metering** | Native Google Gemini Prompt Caching (`cache_read_tokens`) forwarding; accurate cache read tracking and real prompt occupancy across 1M context windows |
+| 👥 **Multi-Account Pool** | Primary + unlimited spare accounts with automatic Sequential Drain rotation upon rate limits; quota-expiry-first scheduling |
+| 🧠 **Jitter-Safe Auth** | Distinguishes network jitter from a real sign-out via keyring transport evidence in agy's run log; sticky quarantine requires confirmation — no false "needs re-login" flags |
+| 📊 **Multi-Bucket Quota HUD** | Real-time progress bars for the **5h rolling**, **7d weekly**, and **Argon weekly** (paid Pro/Ultra) pools with exact reset countdowns |
 | 🔑 **Zero-Paste Browser Login** | Automatic browser-based Google OAuth login with loopback callback handler |
+| 🔀 **Manual Switch-Active** | Pin the scheduler to any account from the console; the header badge always names the server-scheduled account |
 | 🎨 **Theme-Adaptive UI** | Dynamic light/dark theme switching, pure SVG vector marks (no emojis), high contrast |
-| 🌐 **Per-Account Proxy** | Dedicated HTTP(S) proxy per account slot |
-| 🔌 **Native Model Routing** | Registers `antigravity` provider in DSH; choose Gemini / Claude / GPT-OSS in `/model` picker |
+| 🌐 **Per-Account Proxy** | Dedicated HTTP(S) proxy per account slot, or auto-detected system proxy |
+| 🔌 **Native Model Routing** | Registers `antigravity` provider in DSH; choose Gemini / Claude / GPT-OSS / Argon in `/model` picker |
 | 🌊 **Full Streaming Protocol** | Native streaming for text, thinking turn annotations, and tool calls |
 | 🃏 **Native Tool UI Cards** | Command runs and inline diffs render as clean, native DSH tool cards |
 | 🔗 **Session Continuity** | Binds DSH sessions to native agy conversations (`--conversation`) for zero-redundancy context |
+| 🎯 **DSH Goal & Plan Integration** | Long-running tasks carry DSH goal / plan context across tool continuations |
 | 📊 **Accurate Token Metering** | Input, output, thinking, and cacheRead tokens are fully reported to DSH with 1M context support |
 | 🎛 **Top Header Console Badge** | Click the `AGY (n)` badge in the header to instantly open the management console |
 | 🖼 **Multimodal Images** | Stages images to local storage and passes safe absolute paths via `--add-dir` |
 | 🤝 **`agy_ask` Delegation** | Allows other DSH models to delegate subtasks to Antigravity models |
-| ⌨️ **`/agy` Commands** | Full command suite: `status`, `auth`, `models`, `mode`, `effort`, `workspace`, `clear`, `doctor`, `help` |
+| ⌨️ **`/agy` Commands** | Full command suite: `status`, `pool`, `auth`, `models`, `mode`, `effort`, `workspace`, `goal`, `session`, `enable-account`, `disable-account`, `clear`, `doctor`, `help` |
 
 ---
 
@@ -273,6 +316,7 @@ dsh plugin --profile web add dsh-agy-link
 | `defaultEffort` | `DSH_AGY_DEFAULT_EFFORT` | `(model default)` | Thinking budget: `low` / `medium` / `high` |
 | `hiddenModels` | `DSH_AGY_HIDDEN_MODELS` | `[]` | Model slugs hidden from the `/model` picker (deny-list, newly discovered models stay visible; manage them via the "Model visibility" row in the settings panel) |
 | `timeoutMs` | `DSH_AGY_TIMEOUT_MS` | `600000` | Activity watchdog timeout in milliseconds |
+| `longToolIdleMinutes` | `DSH_AGY_LONG_TOOL_IDLE_MINUTES` | `240` | Idle budget while a tool step is ACTIVE (minutes); `0` keeps the normal `timeoutMs` budget so wedged tools fail fast |
 | `workspaceRoot` | `DSH_AGY_WORKSPACE_ROOT` | session cwd | Working directory root |
 
 ---
@@ -293,6 +337,19 @@ you explicitly accept unattended tool execution.
 
 ---
 
+## ❓ FAQ & Troubleshooting
+
+### Why does a black command prompt / terminal window briefly flash when starting a conversation on Windows?
+**A: This is a cosmetic behavior of the Windows Console subsystem and is completely harmless.**
+- **Root Cause**: DSH is an Electron desktop app (GUI process). Before each conversation turn, the plugin verifies/syncs Google credentials via the Windows Credential Manager and launches the `agy.exe` console child process for streaming. On Windows 11, if the system default terminal is set to "Windows Terminal", Windows Terminal intercepts the background console allocation and momentarily flashes an empty window (a known Windows Terminal OpenConsole delegation behavior).
+- **Solution**:
+  1. Open **Windows Terminal** → **Settings** → **Startup** (or Windows **Settings** → **System** → **For developers**).
+  2. Change **Default terminal application** from "Let Windows decide" or "Windows Terminal" to **"Windows Console Host"**.
+  3. Click **Save** in the bottom-right corner.
+  4. **Completely exit and restart DSH** so the running host process picks up the updated console delegation setting.
+
+---
+
 ## ⚠️ Disclaimer
 
 This plugin operates strictly by invoking the official, unmodified `agy` CLI binary installed on your local system. Use of this plugin is subject to Google Antigravity's Terms of Service.

package/assets/icon.svg

@@ -0,0 +1,54 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <!-- Core Orb Gradient -->
+    <linearGradient id="agy-orb-gradient" x1="12" y1="11" x2="25" y2="25" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#38BDF8"/>
+      <stop offset="45%" stop-color="#6366F1"/>
+      <stop offset="85%" stop-color="#9333EA"/>
+      <stop offset="100%" stop-color="#C026D3"/>
+    </linearGradient>
+
+    <!-- Front Orbit Ring Gradient (Glowing Vibrant Gradient) -->
+    <linearGradient id="agy-ring-front" x1="6" y1="24" x2="31" y2="12" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#00D2FF"/>
+      <stop offset="40%" stop-color="#38BDF8"/>
+      <stop offset="70%" stop-color="#818CF8"/>
+      <stop offset="100%" stop-color="#F43F5E"/>
+    </linearGradient>
+
+    <!-- Back Orbit Ring Gradient (Subtle Occluded Depth) -->
+    <linearGradient id="agy-ring-back" x1="7" y1="12" x2="29" y2="24" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#38BDF8" stop-opacity="0.35"/>
+      <stop offset="100%" stop-color="#A855F7" stop-opacity="0.35"/>
+    </linearGradient>
+
+    <!-- Specular Highlight Curve -->
+    <linearGradient id="agy-highlight-grad" x1="14" y1="12" x2="19" y2="18" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#FFFFFF" stop-opacity="0.6"/>
+      <stop offset="100%" stop-color="#FFFFFF" stop-opacity="0.05"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Back Segment of Orbit Ring (passes behind central sphere) -->
+  <path d="M 6.8 14.2 C 8.2 9.6 17.8 7.2 26.2 10.8 C 28.0 11.6 29.3 12.6 30.2 13.8" 
+        stroke="url(#agy-ring-back)" stroke-width="2.4" stroke-linecap="round"/>
+
+  <!-- Central Antigravity Sphere -->
+  <circle cx="18" cy="18" r="7.5" fill="url(#agy-orb-gradient)"/>
+
+  <!-- Elegant Crescent Specular Highlight (adds glass/liquid depth) -->
+  <path d="M 13.2 15.2 A 5.5 5.5 0 0 1 21.0 13.0 A 6.2 6.2 0 0 0 14.0 18.0 Z" 
+        fill="url(#agy-highlight-grad)"/>
+
+  <!-- Front Segment of Orbit Ring (sweeps in front with vibrant glow) -->
+  <path d="M 30.2 13.8 C 31.4 18.2 21.8 26.2 12.8 24.2 C 9.4 23.4 7.4 21.8 6.6 19.6" 
+        stroke="url(#agy-ring-front)" stroke-width="2.6" stroke-linecap="round"/>
+
+  <!-- Left Satellite Node (DSH Cyan Anchor) -->
+  <circle cx="8.2" cy="18.2" r="2.2" fill="#00D2FF"/>
+  <circle cx="8.2" cy="18.2" r="1.0" fill="#FFFFFF"/>
+
+  <!-- Right Satellite Node (Antigravity Magenta Particle) -->
+  <circle cx="28.4" cy="20.4" r="1.8" fill="#F43F5E"/>
+  <circle cx="28.4" cy="20.4" r="0.8" fill="#FFFFFF"/>
+</svg>