dsh-agy-link 0.4.59 → 0.4.65

package/CHANGELOG.md

@@ -1,5 +1,198 @@
 # 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
@@ -19,7 +212,9 @@
     - **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>`.
-  - **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.
+  - **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)
 
@@ -38,7 +233,9 @@
     - **同账号快路径**（`parallelSameAccount`，默认**开**）：凭据已在槽位中的账号立即启动、完全不取互斥锁 —— N 个会话在同一账号上真并行（同一授权的并发 token 刷新是安全的，refresh token 非一次性）。`/agy parallel <on|off>` 开关。
     - **账号切换仍然串行**（正确性）：副账号先等同账号 run 全部退出再换槽位；切换等待期间拒绝新的快路径；切换完成后恢复主账号 —— 防腐蚀不变量原样保留，新增测试覆盖。
     - **`maxConcurrent` 默认 3 → 0（不限制）**：移除人为准入上限；Google 速率限制与账号池冷却是天然调节器。`/agy max-concurrent <n|off>`。
-  - **测试**：互斥锁取消后移除并唤醒下一个；超时不阻塞队列；丢失唤醒的轮询补偿；`acquireCredentialSlot` 已中止即拒绝、排队中响应 Stop、限时等待可见失败。
+  - **修复：配额合并 —— 真实剩余被 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)
 

package/README.md

@@ -31,6 +31,11 @@
     
   <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>
 
 ---
 
@@ -69,6 +74,10 @@
 
 | 能力 | 说明 |
 | ---- | ---- |
+| 🎨 **官方专属矢量 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）多进度条与倒计时，单模型明细可展开 |
@@ -86,7 +95,6 @@
 | 🖼 **图片多模态** | 支持多模态图片传入，自动落盘本地媒体目录并通过 `--add-dir` 安全授权给 agy 查看 |
 | 🤝 **`agy_ask` 辅助工具** | 允许任意 DSH 模型把单次任务委托给 Antigravity 模型（AskAntigravity 协作模式） |
 | ⌨️ **`/agy` 快捷命令族** | `status` / `pool` / `auth` / `models` / `mode` / `effort` / `workspace` / `goal` / `session` / `enable-account` / `disable-account` / `clear` / `doctor` / `help` |
-
 ---
 
 ## 📋 前置要求
@@ -149,13 +157,26 @@ dsh plugin --profile web add dsh-agy-link
 ## 🧩 架构与工作原理
 
 1. **短生命周期进程驱动**：每一轮 DSH 对话启动一个独立的官方 `agy -p --output-format stream-json` 进程，解析 NDJSON 事件流。
-2. **多账号沙箱机制**：除主账号沿用系统默认 Keychain / HOME 外，所有备用账号在插件私有目录下建立专属 HOME 隔离区，独立写入 agy 格式的标准 OAuth 凭证。
+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**（使新启动的主进程应用更新后的控制台委托注册表），黑框闪烁即可彻底消除。
+
+---
+
 ## 🙏 参考与致谢
 
 - [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) — Antigravity 公开 OAuth 客户端与回环回调登录范式
@@ -184,6 +205,11 @@ Bring **Google Antigravity models into DeepSeek Harness (DSH)** — featuring **
   &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>
 
 ---
 
@@ -221,6 +247,10 @@ Have multiple Google Antigravity / Gemini accounts? **dsh-agy-link makes multi-a
 
 | Feature | Description |
 | --- | --- |
+| 🎨 **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 |
@@ -307,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>

package/dist/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>