opencode-context-indicator 1.6.0 → 1.7.1

package/CHANGELOG.md

@@ -4,6 +4,120 @@ Notable user-facing changes per release. Dates are commit days (UTC).
 The package also ships a dual V1/V2 plugin — see the README for the surface
 matrix; everything below concerns the V2 path unless stated otherwise.
 
+## 1.7.1 — 2026-10-29
+
+- **Fixed: the live log no longer prints `ctx=0` above real categories.** A hook
+  breakdown whose instance has no request counters (a mirror that only saw the
+  compaction, so `input`/`ctx` are still 0) used to be printed as-is: the header
+  contradicted the category lines below it. Such an entry now takes the same
+  path as a missing/fallback one and borrows the hook-measured `state.json`
+  snapshot whole (categories, counters, residual and a `snapshot=` stamp; a
+  snapshot without a timestamp is still marked `snapshot=unknown`). A counter is
+  knowledge only when it is positive: a borrowed entry whose own counters are 0,
+  or a ctx-only snapshot with no input, prints the unknown counter as `?`, and
+  the residual as `n/a (input unknown on this instance)` instead of a fabricated
+  `0` (`other = input - sum` needs an input). The same rule now applies to a
+  local hook entry that knows `ctx` but not `input`. T36 covers all four cases:
+  whole-entry borrow, no snapshot, zero-counter snapshot, ctx-only snapshot
+  (86 checks).
+- **Fixed: the compaction reserve is 15 % again (1.7.0 regression).** 1.7.0
+  switched the denominator to a 10 % share on the strength of an unreleased
+  branch head. Every RELEASED host from 2.1.4 through 2.2.2 (2.1.4, 2.2.0,
+  2.2.1, 2.2.2) still has `RESERVE_SHARE = 0.15` in
+  `packages/core/src/session/compaction.ts` (verified tag by tag), so on those
+  hosts 1.7.0 overstated the ceiling and the `compact at` line by ~5 % of the
+  window (~26 k tokens at 512 k) and therefore under-reported every `%`. The
+  plugin now mirrors `max(floor(window * 0.15), window >= 32_000 ? 16_000 : 0)`
+  again; the formula, the 16 k floor and the `2 * RESERVE_MIN` gate are
+  unchanged. Docs, the T16/T26 tables and the seed expectations are back on the
+  15 % numbers.
+- Dev: the isolated e2e (plugin load + state write) was re-run against the
+  **2.2.2** Desktop CLI (`opencode v2.2.2`); the Desktop 2.2.2 `app.asar` still
+  carries the `@opencode/plugin/gui` / `@opencode/plugin/rpc` bridge and the
+  `ComposerPill` / `Rpc.define` / `session.panel` symbols the experimental panel
+  uses, and `opencode-cli.exe` still exposes `opentui:runtime-module:` plus the
+  `node_modules` exclusion filter.
+
+## 1.7.0 — 2026-10-29
+
+Desktop GUI release (experimental): the plugin now has a surface in the
+OpenCode Desktop app, not just in the terminal.
+
+- **Desktop side-panel tab.** A new `./gui-experimental` part contributes a
+  "Context" tab to the session side region: model, `ctx / usable (percent)`, the
+  eight categories as value + bar + share, the measurement time and source tag,
+  a stale-after-compaction marker, the compaction reserve, and one line per
+  subagent with its own window and percentage. Opened from the `+` menu of the
+  side region, the command palette, or the `/cx` slash command.
+- **Composer pill.** A small always-on `NN% ctx` capsule above the composer,
+  amber from 65 % and red from 85 % of the usable window; clicking it opens the
+  tab. It hides itself while the server part is unavailable instead of showing a
+  stale number.
+- **New public RPC contract (`./rpc`).** A Desktop window has no filesystem
+  access, so the panel cannot read `state.json`; the server part now registers
+  an RPC contract (id `context-indicator`, method `family`) that returns the root
+  session plus every descendant as flat rows, and the GUI polls it through
+  `ctx.client.rpc()`. The contract is exported so other plugins and clients can
+  read the same data.
+- **One family walk instead of two.** `/context-breakdown` and the RPC now share
+  `collectFamilyReports()`: the descendant BFS, the shared wall-clock budget and
+  the per-session collection exist once. The RPC uses a 2 s budget (a poll runs
+  far more often than a command).
+- **Experimental warning.** The host GUI API (`@opencode/plugin/gui`) is marked
+  experimental upstream and may change between releases; if it does, the GUI
+  part stops loading while the server part, the slash commands and the TUI
+  surfaces keep working. The Desktop part is not covered by CI (it needs a real
+  window); CI typechecks it, builds the bundle and validates the artifact.
+- **Fixed: hook-measured categories are authoritative in `state.json`.** The
+  file is shared by every plugin instance, and the Desktop window's instance
+  never serves a model request, so its breakdown is always the client-context
+  fallback (no system prompt, no tool schemas). It used to overwrite the
+  hook-measured categories milliseconds after the hook wrote them, which is what
+  made the panel show `system 0` / `tool schemas 0` / a grossly inflated `other`
+  and could blank `user`/`assistant`. Entries now carry their `source`, and only
+  a hook breakdown may replace hook numbers (a fallback still fills a session
+  that no hook has ever measured). The same rule now applies to the command
+  report and to the live log, so all three surfaces agree.
+- **Fixed: the stale-after-compaction mark survives a fallback write.** A
+  conversation rebuilt from the persisted messages is not a measurement of the
+  compacted context; only a fresh hook breakdown clears the mark now, so the
+  panel keeps saying "stale after compaction" instead of silently dropping it.
+  The compaction hook also marks the entry as "already handled" only when it
+  actually persisted a measurement, so a hook instance with a cold cache no
+  longer suppresses the fallback and makes a compaction leave no trace at all.
+- **Fixed: compaction notes could vanish from the log.** `final summaries` lived
+  in per-process memory while the log file is shared, so the next snapshot
+  rewrite from another instance wiped a `COMPACTION`/`COMPACTED` note that had
+  just been appended. The writer now merges the section already on disk
+  (block-level, de-duplicated, bounded) under its own lock, and the live snapshot
+  prints a hook-measured `state.json` entry — categories, residual `other` and
+  its `ctx`/`input` counters, tagged `snapshot=<updatedAt>` — instead of this
+  instance's fallback-shaped view. Repeated compactions of one session are also
+  no longer collapsed into a single note when the host omits the event id.
+- **Reserve share (claim in 1.7.0 was wrong; corrected in 1.7.1).** This
+  release switched the denominator to a 10 % share; no host in the verified
+  range 2.1.4 through 2.2.2 used it. `calculateCeiling()` in those tags keeps
+  `RESERVE_SHARE = 0.15`, so 1.7.0 overstated the ceiling (and the `compact at`
+  line) by ~5 % of the window (~26 k tokens at 512 k) on them and therefore
+  under-reported every `%`. The 1.6.0 note that the ceiling was unchanged in
+  2.2.0 was right (the formula and the `2 * RESERVE_MIN` gate did stay); the
+  share line here was the wrong part.
+- Dev: `lib/format.js` (pure `fmt`/`num`) extracted so the GUI bundle has no
+  `node:*` import; gate (a) now expands `dist/`, gate (e)/(f) scan `gui/` and the
+  GUI build config, new gate (g) validates the built CJS bundle (app-provided
+  modules kept external, no React/OpenTUI/bare-`opencode` import, no Node
+  built-in, no ESM or dynamic import left), new unit checks T30 (schema vs row
+  builder), T31 (RPC registration + handler), T32 (fallback vs hook priority in
+  the report), T33 (fallback vs hook priority in the shared state file, stale
+  mark), T34 (summary merge across instances), T35 (hook-family authority for
+  the compaction hook, the V1 transform hooks and legacy untagged entries, plus
+  the live-log substitution) and T25c/T25d (a cold-cache or lock-refused
+  compaction hook must not arm the trailing-event guard), 85 checks total; CI
+  builds the GUI and typechecks it before the gate. The isolated e2e (plugin
+  load + state write) passes on both the 2.2.0 CLI and the 2.2.1 Desktop CLI;
+  the dev dependency stays pinned to `@opencode/plugin@2.2.0` for CI
+  reproducibility.
+
 ## 1.6.0 — 2026-10-27
 
 Host alignment release: opencode 2.2.0 moved TUI plugins to OpenTUI 0.7.
@@ -20,10 +134,13 @@ Host alignment release: opencode 2.2.0 moved TUI plugins to OpenTUI 0.7.
   opencode 2.0.16+. The TUI module now ships compiled against OpenTUI 0.7, so
   the sidebar and the `/cx` panel require **opencode ≥ 2.2.0** and cannot load on
   an older host. Older-host installation was not re-verified for this release.
-- **Compaction ceiling unchanged.** `calculateCeiling()` in 2.2.0 is identical
+- **Compaction ceiling unchanged (this note was right; 1.7.0 briefly wrong).**
+  `calculateCeiling()` in 2.2.0 is identical
   to 2.1.x, so the `0.15 / 16k / 32k` reserve formula and every `%` denominator
   are unaffected. (2.2.0 changed how a *compaction request* is sized - measured
-  prompt instead of characters - not the trigger.)
+  prompt instead of characters - not the trigger. 1.7.0 later claimed the share
+  had dropped to 10 %; see 1.7.1 - no host in the verified range
+  2.1.4-2.2.2 uses it.)
 - Dev: `drift-watch` is green again (host 2.2.0, OpenTUI 0.7.0); `tsc`,
   `prepublish` and the isolated e2e pass against the 2.2.0 CLI.
 
@@ -67,9 +184,11 @@ Fix-and-hygiene release after a full-project review. No new commands.
 
 ## 1.5.3 — 2026-10-26
 
-- **Compaction ceiling aligned with opencode 2.1.4 (#51271).** `lib/limits.js`
+- **Compaction ceiling aligned with opencode 2.1.4.** `lib/limits.js`
   now mirrors `calculateCeiling()` exactly: the reserve is
-  `max(floor(window * 0.15), window >= 2 * 16_000 ? 16_000 : 0)` (was 10%),
+  `max(floor(window * 0.15), window >= 2 * 16_000 ? 16_000 : 0)` (the plugin's
+  older builds used 10 %; no host in the verified range uses it - the share
+  stayed 0.15 there),
   and an override buffer is honored **only while it is smaller than the
   window** — a buffer configured for a larger model is ignored instead of
   leaving zero room. The `compact at` line and the `%` denominator now match the

package/README.md

@@ -13,8 +13,10 @@ arguments, tool results (the outputs fed back into context) and the residual
 The package ships a **dual V1 + V2 plugin** (one entry works in both OpenCode
 generations) plus an optional TUI module (`./tui` entry) that renders a **live
 sidebar** and a **zero-LLM `/cx` breakdown panel** with measured contributors
-and a redacted export. The V2 path is **tested against opencode 2.2.0**; the
-V1 path against 1.18.29+.
+and a redacted export, and an **experimental Desktop GUI part**
+(`./gui-experimental`: a side-panel tab and a composer pill). The V2 path is
+**tested against opencode 2.2.0** (the isolated load + state-write e2e was also
+re-run against the 2.2.1 and 2.2.2 Desktop CLI); the V1 path against 1.18.29+.
 
 > **V1 is feature-frozen.** It is kept working for compatibility (bug fixes
 > only); all new features land in the V2 path.
@@ -70,11 +72,13 @@ For every served request the plugin estimates how the context window is split:
   duplicate group), reported honestly as *"N redundant tool outputs ≈ X tokens"*
   — never as "the model wasted effort". Findings are per-session and **path-free
   in the persisted/exported form**.
-* The denominator is the **opencode 2.2.0 compaction ceiling** (unchanged since
-  2.1.4): `window =
+* The denominator is the **opencode 2.x compaction ceiling**: `window =
   limit.input || limit.context`; `reserve = max(floor(window * 0.15), window >=
   2 * 16_000 ? 16_000 : 0)`; the ceiling is `window - reserve`. This mirrors
-  `calculateCeiling()` in `packages/core/src/session/compaction.ts`. When opencode
+  `calculateCeiling()` in `packages/core/src/session/compaction.ts`, whose
+  `RESERVE_SHARE` is 0.15 in every released host from 2.1.4 through 2.2.2 (the
+  unreleased `v2` branch has a different share; the plugin follows the release,
+  not the branch). When opencode
   carries a `compaction.buffer` configured in its own settings, the plugin
   cannot read that value (it is not exposed to plugins), so the default
   reserve formula is used — set `OPENCODE_CONTEXT_INDICATOR_COMPACT_BUFFER`
@@ -372,14 +376,95 @@ an error toast.
 
 ---
 
+## Desktop panel (experimental)
+
+OpenCode Desktop has no TUI, so the sidebar above cannot exist there. The
+package therefore ships a **GUI part** (`./gui-experimental`) that renders the
+same numbers as a Desktop **side-panel tab**, plus a **composer pill** with the
+current percentage.
+
+> **Experimental.** The host API it uses (`@opencode/plugin/gui`, opencode
+> 2.2.0+) is explicitly marked experimental upstream and may change between
+> releases; the export name `./gui-experimental` says so. If the host changes
+> the API, the GUI part fails to load while the server part, the slash commands
+> and the TUI surfaces keep working.
+
+### What it shows
+
+**Context tab** (side region): the model, `ctx / usable (percent)`, the eight
+categories as value + bar + share of the context, the measurement time, the
+`source` tag (`live` / `snapshot` / `client-context` / `no-data`), a
+`stale after compaction` marker, the compaction reserve, and one line per
+subagent with its own window and percentage.
+
+**Composer pill**: `38% ctx` above the composer, amber from 65 % and red from
+85 % of the usable window; clicking it opens the panel.
+
+### Opening it
+
+| Way | Where |
+| --- | --- |
+| `+` menu of the side region | "Context" |
+| Command palette / slash command `/cx` | "Open context panel" |
+| Clicking the composer pill | opens the tab for the current session |
+
+### Where the numbers come from
+
+A Desktop window has **no filesystem access**, so it cannot read `state.json`
+the way the TUI does. The server part registers an **RPC contract**
+(`lib/rpc.js`, id `context-indicator`, method `family`) that answers with the
+root session plus every descendant, and the GUI calls it through
+`ctx.client.rpc()`. The panel **polls** every 1.5 s (the pill every 5 s) instead
+of subscribing to events: the contract stays one method, a poll costs no provider
+call (the server answers from `state.json` plus its in-memory caches once the
+session has been measured; a session this instance never observed live costs at
+most one `session.get()` per instance, not per poll), and polling recovers by
+itself when the desktop app's background server restarts.
+
+The contract is published as the `./rpc` export, so other plugins and clients
+can read the same data:
+
+```js
+import { DesktopContextRpc } from "opencode-context-indicator/rpc"
+const { rows } = await client.rpc(DesktopContextRpc).family({ sessionID })
+```
+
+### Install
+
+The Desktop part is loaded from the same plugin entry, nothing extra to
+configure:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-context-indicator"]
+}
+```
+
+After installing, restart the app and check **Settings > Extensions**; the
+plugin must be listed with its GUI part loaded. The `dist/gui-experimental.cjs`
+bundle in the package is prebuilt, so no build step is needed on install.
+
+### Limits
+
+* **Desktop only.** The TUI has its own sidebar and `/cx` panel, and loading a
+  GUI bundle there does nothing.
+* **Polling, not push.** A change can take up to 1.5 s to appear (5 s for the
+  pill); the numbers themselves are the same snapshot the sidebar reads.
+* **Not exercised in CI.** The GUI needs a real Desktop window: CI typechecks
+  `gui/*.tsx`, builds the bundle and validates the artifact (gate `g`), and the
+  panel and the pill are verified manually in the app before a release.
+
+---
+
 ## Surface matrix
 
-| Surface | Toast | TUI sidebar | TUI panel (/cx) | Breakdown log file | Slash commands |
-| --- | :---: | :---: | :---: | :---: | :---: |
-| OpenCode **1.x** — Desktop | ✅ | — | — | ✅ | — |
-| OpenCode **1.x** — TUI | ✅ | — | — | ✅ | — |
-| OpenCode **2.x** — TUI | — | ✅ | ✅ | ✅ | ✅ |
-| OpenCode **2.x** — Desktop | — | — | — | ✅ | ✅ |
+| Surface | Toast | TUI sidebar | TUI panel (/cx) | Desktop panel | Desktop pill | Breakdown log file | Slash commands |
+| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| OpenCode **1.x** — Desktop | ✅ | — | — | — | — | ✅ | — |
+| OpenCode **1.x** — TUI | ✅ | — | — | — | — | ✅ | — |
+| OpenCode **2.x** — TUI | — | ✅ | ✅ | — | — | ✅ | ✅ |
+| OpenCode **2.x** — Desktop | — | — | — | ✅ (exp) | ✅ (exp) | ✅ | ✅ |
 
 Notes — these reflect what the plugin API actually exposes today:
 
@@ -394,8 +479,13 @@ Notes — these reflect what the plugin API actually exposes today:
 * **V1 has no sidebar and no slash command.** The command/slot API (and the
   `./tui` entry) is a V2 feature; OpenCode 1.x has no equivalent, so V1 is
   toast + log only.
-* The Desktop app is TUI-less; its V2 surfaces are the log file and the
-  `/context` / `/context-breakdown` / `/context-diff` slash commands.
+* The Desktop app is TUI-less. Its V2 surfaces are the log file, the
+  `/context` / `/context-breakdown` / `/context-diff` slash commands, and the
+  **experimental** GUI part: a side-panel tab and a composer pill fed by the
+  plugin over RPC (see
+  [Desktop panel (experimental)](#desktop-panel-experimental)). That part needs
+  a host that loads `./gui-experimental` (opencode 2.2.0+); without it the log
+  file and the slash commands still work.
 
 ---
 
@@ -407,24 +497,22 @@ and `$TMPDIR` (usually `/tmp`) elsewhere:
 | File | Purpose |
 | --- | --- |
 | `context-breakdown.log` | Human-readable live snapshot + bounded final summaries |
-| `opencode-context-indicator-state.json` | Machine-readable snapshot consumed by the TUI sidebar and the `/cx` panel. Fields per entry: `sessionID`, `parentID`, `role`, `agent`, `model`, `providerID`, `ctx`, `input`, `usable` (compaction ceiling), `reserve` (tokens reserved for compaction), `limit` (context window), `reasoning`, `categories{user,assistant,reasoning,toolArgs,toolOut,system,toolSchemas,other}`, `toolOutByTool` (per-tool repeated-output estimate), `reclaim` (duplicate tool output, bounded), `cacheRead`/`cacheWrite` (provider-reported prompt-cache tokens), `compactedAt`/`compactStale`, `top` (top-5 heaviest single items, path-free), `previous` (previous distinct measurement for `/context-diff`), `updatedAt`. |
+| `opencode-context-indicator-state.json` | Machine-readable snapshot consumed by the TUI sidebar and the `/cx` panel. Fields per entry: `sessionID`, `parentID`, `role`, `agent`, `model`, `providerID`, `ctx`, `input`, `usable` (compaction ceiling), `reserve` (tokens reserved for compaction), `limit` (context window), `reasoning`, `categories{user,assistant,reasoning,toolArgs,toolOut,system,toolSchemas,other}`, `source` (provenance of the categories: `context-hook` / `compaction-hook` (V2) / `transform` / `system-transform` (V1) / `client-context` / `snapshot` - any hook-family source wins, a fallback never overwrites it), `toolOutByTool` (per-tool repeated-output estimate), `reclaim` (duplicate tool output, bounded), `cacheRead`/`cacheWrite` (provider-reported prompt-cache tokens), `compactedAt`/`compactStale`, `top` (top-5 heaviest single items, path-free), `previous` (previous distinct measurement for `/context-diff`), `updatedAt`. |
 | `context-events.log` | Raw event tap — **only** when `DEBUG_EVENTS` is flipped to `true` in the source (off by default) |
 
 The whole `context-breakdown.log` is **rewritten atomically** (temp file +
 rename, like the state file): the live snapshot is always regenerated and the
 final summaries (on `session.idle`) plus compaction notes are re-rendered from
-an in-memory buffer (bounded, last 50 per log), so the file never grows and
-concurrent plugin instances cannot observe a half-written file. A summary-only
-write (idle, compaction, command payload) re-renders the last live snapshot, so
-adding a note never blanks that section. That snapshot may predate a compaction
-or a deleted session - the leading `[<timestamp>]` line is the freshness cue.
-Both parts are **process-local**: they
-survive every rewrite and failed command delivery within the lifetime of the
-running instance, but they are dropped when the plugin instance is re-created
-(opencode restarts, or about 24 h of idling). A different instance that rewrites
-the file keeps its own view of the summary buffer; cross-instance duplicate
-summaries are prevented separately by an atomic claim marker (see
-`lib/dedup.js`).
+an in-memory buffer (bounded, last 50 blocks per instance), so the file never
+grows and concurrent plugin instances cannot observe a half-written file. A
+summary-only write (idle, compaction, command payload) re-renders the last live
+snapshot, so adding a note never blanks that section. That snapshot may predate a
+compaction or a deleted session - the leading `[<timestamp>]` line is the
+freshness cue. Each instance keeps its own buffer, so every write **merges the
+summary section already on disk** (de-duplicated by line, bounded to 400 lines):
+a note appended by the instance that handled the event survives the next
+snapshot rewrite from another instance. Cross-instance duplicate summaries are
+prevented separately by an atomic claim marker (see `lib/dedup.js`).
 
 ---
 
@@ -548,10 +636,12 @@ the sidebar instead.
   gracefully (the breakdown falls back to throttled `session.messages` fetches
   and toasts keep working).
 * **OpenCode ≥ 2.2.0** for the V2 path with the TUI surfaces (built and verified
-  against **2.2.0**). The server-only V2 path keeps working on 2.0.16+; the TUI
-  module pins the OpenTUI generation it was compiled against, so a host on
-  OpenTUI 0.6 (opencode ≤ 2.1.4) will not load the TUI surfaces - neither the
-  sidebar nor the `/cx` panel - from a 1.6.x install.
+  against **2.2.0**; the isolated load + state-write e2e also passes on the
+  **2.2.2** Desktop CLI, the latest at the time of writing). The server-only V2
+  path keeps working on
+  2.0.16+; the TUI module pins the OpenTUI generation it was compiled against,
+  so a host on OpenTUI 0.6 (opencode ≤ 2.1.4) will not load the TUI surfaces -
+  neither the sidebar nor the `/cx` panel - from a 1.6.x install.
 * **TUI sidebar**: terminal TUI only, requires the OpenTUI rendering stack that
   ships with OpenCode. `@opentui/core` and `solid-js` are **optional** peer
   dependencies resolved by OpenCode at runtime; the main plugin installs and runs
@@ -565,6 +655,12 @@ the sidebar instead.
   upstream limitation, on the **npm** path the sidebar is **auto-disabled**
   (the plugin logs one hint and registers no slot) — use a `file://` install for
   the live sidebar, see [Live sidebar: npm vs file:// install](#live-sidebar-npm-vs-file-install).
+* **Desktop GUI part** (optional, experimental): needs an OpenCode Desktop
+  release that loads the `./gui-experimental` export (opencode 2.2.0+, where the
+  GUI plugin API exists). The bundle is prebuilt and ships in the package, so it
+  adds **no** runtime dependency; `solid-js`, the GUI SDK and the client are
+  provided by the app itself. On hosts without that API the export is simply not
+  loaded and everything else keeps working.
 
 ---
 
@@ -630,15 +726,17 @@ caller.
 ### Running tests
 
 ```bash
-npm run test:prepublish       # fast gate: tarball + tui.tsx + resolve + T1-T29 unit checks
+npm run build:gui             # build dist/gui-experimental.cjs (required by the gate)
+npm run test:prepublish       # fast gate: tarball + tui.tsx + resolve + T1-T36 unit checks + GUI bundle
+npm run test:types            # tsc for the TUI entry AND the Desktop GUI part
 npm run test:e2e              # full E2E: isolated plugin load + one "Say OK" round-trip
 npm run test:e2e:quick        # E2E load-only, no LLM call
 npm run test:drift            # advisory: warns on non-breaking host drift (also in CI)
 npm run test:drift:strict     # release check: fails on ANY host drift
 ```
 
-`prepublishOnly` runs **both** gates automatically on `npm publish`
-(`node test/prepublish.mjs && node test/e2e-tui.mjs --full`) and is skipped with
+`prepublishOnly` runs **all** of it automatically on `npm publish`
+(`npm run build:gui && node test/prepublish.mjs && node test/e2e-tui.mjs --full`) and is skipped with
 `--ignore-scripts`. The whole chain takes roughly **1 minute** (fast gate ~20 s,
 isolated E2E ~10 s warm / up to ~90 s cold); the E2E is bounded by INIT 45 s +
 STEP 80 s, ~3 min total.
@@ -649,12 +747,13 @@ STEP 80 s, ~3 min total.
 
 | Step | What | Why |
 |---|---|---|
-| (a) tarball composition | `package.json` `files[]` expands to the base files plus every `lib/*` module (count asserted dynamically); `docs/` may contain images only | no test/node_modules/tsconfig in the tarball |
+| (a) tarball composition | `package.json` `files[]` expands to the base files plus every `lib/*` module (count asserted dynamically); `docs/` may contain images only; `dist/` may contain only the built GUI bundle | no test/node_modules/tsconfig in the tarball, and no published export pointing at nothing |
 | (b) pragma regression | esbuild `--jsx=automatic` → `@opentui/solid/jsx-runtime` present, `react/jsx-runtime` absent | a removed/broken pragma kills the sidebar on npm install |
 | (c) resolve chain | replica install: host-bridged + peer packages resolve; local tui.tsx relative imports resolve via node from the entry (resolve-bridge.cjs) | broken peer/optional dep or a bad local import silently breaks the sidebar |
-| (d) unit harness T1-T29 | limit/agent/state fix assertions plus measureContributors, redacted-export, shared category-helper, sanitizer/unicode, prompt-cache, waste-detector, compaction-reserve, top-consumer, diff and subagent-rollup checks (75 total) | regressions in modelLimits, writeStateFile, hydrate, contributors, export, subagent lifetime |
-| (e) corporate-identifier scan | no forbidden identifiers in the published surface (`index.js`, `tui.tsx`, `lib/*`, `README.md`, `CHANGELOG.md`, `package.json`) or the test tree | compliance |
+| (d) unit harness T1-T36 | limit/agent/state fix assertions plus measureContributors, redacted-export, shared category-helper, sanitizer/unicode, prompt-cache, waste-detector, compaction-reserve, top-consumer, diff, subagent-rollup and Desktop-RPC checks (86 total; T30 schema-vs-builder drift, T31 registration + handler, T32-T36 fallback-vs-hook category priority across the report, the shared state file and the live log (T36: a counter-less hook entry borrows the snapshot or prints `?`), T25c/T25d compaction-hook arming, T34 cross-instance summary merge) | regressions in modelLimits, writeStateFile, hydrate, contributors, export, subagent lifetime, and a GUI/server wire mismatch |
+| (e) corporate-identifier scan | no forbidden identifiers in the published surface (`index.js`, `tui.tsx`, `lib/*`, `gui/*`, `README.md`, `CHANGELOG.md`, `package.json`, the GUI build config) or the test tree | compliance |
 | (f) non-English scan | no non-ASCII letters (`\p{L}` above U+007F) in the same published surface and test tree (`docs/` is image-only and is not text-scanned) | English-only source rule |
+| (g) Desktop GUI bundle | `dist/gui-experimental.cjs` exists and is a non-trivial single-file CJS bundle: no ESM `import`, no dynamic `import()`, no Node built-in, and every app-provided module (`solid-js`, `solid-js/web`, `@opencode/plugin/gui`, `@opencode/plugin/rpc`) still a `require()` - no bundled second copy, no React/OpenTUI/bare-`opencode` import | a stale or hand-edited bundle, or a build that inlines the app instance, breaks the Desktop panel at load time |
 
 **Isolated E2E — `test/e2e-tui.mjs`** (requires the OpenCode CLI)
 
@@ -696,11 +795,13 @@ model.
 and on a daily schedule (GitHub auto-parks scheduled workflows after 60 days of
 repo inactivity — a push or manual run re-enables them):
 
-1. `npx --no-install tsc --noEmit` — typecheck of the TUI entry (`tui.tsx` + its
-   `lib/*` imports);
-2. `test/prepublish.mjs` — the full fast gate (a)–(f), including the standalone
-   esbuild transpile check (pragmas, no React);
-3. `test/drift-watch.mjs` — compares the OpenTUI pins and the
+1. `npx --no-install tsc --noEmit` and `npx --no-install tsc -p tsconfig.gui.json --noEmit`
+   - typecheck of the TUI entry (`tui.tsx` + its `lib/*` imports) and of the
+   Desktop GUI part (`gui/*.tsx`, Solid JSX);
+2. `npm run build:gui` - build the Desktop GUI bundle before the gate inspects it;
+3. `test/prepublish.mjs` - the full fast gate (a)-(g), including the standalone
+   esbuild transpile check (pragmas, no React) and the GUI bundle check;
+4. `test/drift-watch.mjs` - compares the OpenTUI pins and the
    `@opencode/plugin` types devDependency with the **latest released** opencode.
    It is **advisory by default**: patch drift prints a `::warning::` annotation
    and exits 0, so the daily pipeline does not go red on every host patch. Only
@@ -711,7 +812,10 @@ repo inactivity — a push or manual run re-enables them):
    `npm run test:drift:strict` to fail on any drift.
 
 The Node-pty E2E is not run in CI (requires the OpenCode binary) and is skipped
-gracefully when the CLI is absent (`[SKIP] opencode CLI not found`).
+gracefully when the CLI is absent (`[SKIP] opencode CLI not found`). The Desktop
+GUI part cannot be exercised headless at all: CI typechecks it, builds the
+bundle and checks the artifact, and the panel/pill are verified manually in a
+real Desktop window before a release.
 
 ---
 

package/dist/gui-experimental.cjs

@@ -0,0 +1 @@
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});let e=require("solid-js/web"),t=require("@opencode/plugin/gui"),n=require("solid-js"),r=require("@opencode/plugin/rpc");var i={sessionID:{type:`string`},parentID:{type:`string`},agent:{type:`string`},modelID:{type:`string`},providerID:{type:`string`},ctx:{type:`number`},input:{type:`number`},usable:{type:`number`},reserve:{type:`number`},user:{type:`number`},assistant:{type:`number`},reasoning:{type:`number`},toolArgs:{type:`number`},toolOut:{type:`number`},system:{type:`number`},toolSchemas:{type:`number`},other:{type:`number`},source:{type:`string`},updatedAt:{type:`string`},stale:{type:`boolean`}},a=Object.keys(i),o=r.Rpc.define({id:`context-indicator`,methods:{family:{input:{type:`object`,properties:{sessionID:{type:`string`}},required:[`sessionID`],additionalProperties:!1},output:{type:`object`,properties:{rows:{type:`array`,items:{type:`object`,properties:i,required:a,additionalProperties:!1}}},required:[`rows`],additionalProperties:!1}}},events:{}});function s(e){return Number.isFinite(e)?e>=1e3?`${(e/1e3).toFixed(1)}k`:String(Math.round(e)):`0`}var c=(0,e.template)(`<div>Server part unavailable: <!> (retrying)`),l=(0,e.template)(`<div>`),u=(0,e.template)(`<div>Loading context...`),d=(0,e.template)(`<div>No measurement yet. Send a prompt in this session and the numbers appear here.`),f=(0,e.template)(`<div><span></span><span>`),p=(0,e.template)(`<span>stale after compaction`),m=(0,e.template)(`<span>reserve `),h=(0,e.template)(`<div>Subagents (<!>)`),g=(0,e.template)(`<div><span></span><span></span><span><span style=display:block></span></span><span>`),_=1500,v=[[`system`,`System`],[`toolSchemas`,`Tool schemas`],[`user`,`User`],[`assistant`,`Assistant`],[`reasoning`,`Reasoning`],[`toolArgs`,`Tool args`],[`toolOut`,`Tool output`],[`other`,`Other`]];function y(e){if(!e)return`?`;try{let t=new Date(e);return Number.isNaN(t.getTime())?`?`:t.toLocaleTimeString()}catch{return`?`}}function b(e,t){return!t||t<=0?``:`${(e/t*100).toFixed(0)}%`}var x={panel:{display:`flex`,"flex-direction":`column`,gap:`10px`,padding:`12px`,"font-size":`12px`,"line-height":`1.45`},hint:{opacity:`0.65`,"font-size":`12px`},header:{display:`flex`,"align-items":`baseline`,"justify-content":`space-between`,gap:`8px`},model:{"font-weight":`600`,overflow:`hidden`,"text-overflow":`ellipsis`,"white-space":`nowrap`},total:{"font-variant-numeric":`tabular-nums`,"white-space":`nowrap`},section:{display:`flex`,"flex-direction":`column`,gap:`6px`},row:{display:`grid`,"grid-template-columns":`1fr auto 64px auto`,"align-items":`center`,gap:`6px`},label:{opacity:`0.8`,overflow:`hidden`,"text-overflow":`ellipsis`,"white-space":`nowrap`},value:{"font-variant-numeric":`tabular-nums`},track:{height:`4px`,"border-radius":`2px`,background:`currentColor`,opacity:`0.15`,overflow:`hidden`},fill:{height:`4px`,"border-radius":`2px`,background:`currentColor`,opacity:`0.9`},share:{opacity:`0.65`,"text-align":`right`,"font-variant-numeric":`tabular-nums`},meta:{display:`flex`,gap:`8px`,opacity:`0.6`,"font-size":`11px`},sub:{display:`flex`,"justify-content":`space-between`,gap:`8px`,"font-size":`11px`},subName:{overflow:`hidden`,"text-overflow":`ellipsis`,"white-space":`nowrap`,opacity:`0.85`},title:{"font-weight":`600`,opacity:`0.85`}};function S(r){let i=(0,t.usePlugin)(),[a,S]=(0,n.createSignal)([]),[C,w]=(0,n.createSignal)(``),[T,E]=(0,n.createSignal)(!1);(0,n.createEffect)(()=>{let e=r.session.id,t=!1,a=!1;E(!1),S([]),w(``);let s=async()=>{if(!(a||t)){t=!0;try{let t=await i.client.rpc(o).family({sessionID:e});if(a)return;S(Array.isArray(t?.rows)?t.rows:[]),w(``)}catch(e){if(a)return;w(e instanceof Error?e.message:String(e))}finally{t=!1,a||E(!0)}}};s();let c=setInterval(()=>void s(),_);(0,n.onCleanup)(()=>{a=!0,clearInterval(c)})});let D=()=>a()[0],O=()=>a().slice(1),k=e=>{let t=D()?.ctx||0;return t<=0||e<=0?`0%`:`${Math.min(100,Math.max(2,Math.round(e/t*100)))}%`};return(()=>{var t=l();return(0,e.insert)(t,(0,e.createComponent)(n.Show,{get when(){return T()},get fallback(){return(()=>{var t=u();return(0,e.effect)(n=>(0,e.style)(t,x.hint,n)),t})()},get children(){return[(0,e.createComponent)(n.Show,{get when(){return C()},get children(){var t=c(),n=t.firstChild.nextSibling;return n.nextSibling,(0,e.insert)(t,C,n),(0,e.effect)(n=>(0,e.style)(t,x.hint,n)),t}}),(0,e.createComponent)(n.Show,{get when(){return D()},get fallback(){return(0,e.createComponent)(n.Show,{get when(){return!C()},get children(){var t=d();return(0,e.effect)(n=>(0,e.style)(t,x.hint,n)),t}})},children:t=>[(()=>{var n=f(),r=n.firstChild,i=r.nextSibling;return(0,e.insert)(r,()=>t().modelID||`unknown model`),(0,e.insert)(i,()=>s(t().ctx),null),(0,e.insert)(i,(()=>{var n=(0,e.memo)(()=>t().usable>0);return()=>n()?` / ${s(t().usable)} (${b(t().ctx,t().usable)})`:``})(),null),(0,e.effect)(a=>{var o=x.header,s=x.model,c=t().modelID,l=x.total;return a.e=(0,e.style)(n,o,a.e),a.t=(0,e.style)(r,s,a.t),c!==a.a&&(0,e.setAttribute)(r,`title`,a.a=c),a.o=(0,e.style)(i,l,a.o),a},{e:void 0,t:void 0,a:void 0,o:void 0}),n})(),(()=>{var r=l();return(0,e.insert)(r,(0,e.createComponent)(n.For,{each:v,children:n=>(()=>{var r=g(),i=r.firstChild,a=i.nextSibling,o=a.nextSibling,c=o.firstChild,l=o.nextSibling;return(0,e.insert)(i,()=>n[1]),(0,e.insert)(a,()=>s(t()[n[0]])),(0,e.insert)(l,()=>b(t()[n[0]],t().ctx)),(0,e.effect)(s=>{var u=x.row,d=x.label,f=x.value,p=x.track,m={...x.fill,width:k(t()[n[0]])},h=x.share;return s.e=(0,e.style)(r,u,s.e),s.t=(0,e.style)(i,d,s.t),s.a=(0,e.style)(a,f,s.a),s.o=(0,e.style)(o,p,s.o),s.i=(0,e.style)(c,m,s.i),s.n=(0,e.style)(l,h,s.n),s},{e:void 0,t:void 0,a:void 0,o:void 0,i:void 0,n:void 0}),r})()})),(0,e.effect)(t=>(0,e.style)(r,x.section,t)),r})(),(()=>{var r=f(),i=r.firstChild,a=i.nextSibling;return(0,e.insert)(i,()=>y(t().updatedAt)),(0,e.insert)(a,()=>t().source||`none`),(0,e.insert)(r,(0,e.createComponent)(n.Show,{get when(){return t().stale},get children(){return p()}}),null),(0,e.insert)(r,(0,e.createComponent)(n.Show,{get when(){return t().reserve>0},get children(){var n=m();return n.firstChild,(0,e.insert)(n,()=>s(t().reserve),null),n}}),null),(0,e.effect)(t=>(0,e.style)(r,x.meta,t)),r})(),(0,e.createComponent)(n.Show,{get when(){return O().length>0},get children(){return[(()=>{var t=h(),n=t.firstChild.nextSibling;return n.nextSibling,(0,e.insert)(t,()=>O().length,n),(0,e.effect)(n=>(0,e.style)(t,x.title,n)),t})(),(()=>{var t=l();return(0,e.insert)(t,(0,e.createComponent)(n.For,{get each(){return O()},children:t=>(()=>{var n=f(),r=n.firstChild,i=r.nextSibling;return(0,e.insert)(r,()=>t.agent||`sub`),(0,e.insert)(i,()=>s(t.ctx),null),(0,e.insert)(i,(()=>{var n=(0,e.memo)(()=>t.usable>0);return()=>n()?` (${b(t.ctx,t.usable)})`:``})(),null),(0,e.effect)(a=>{var o=x.sub,s=x.subName,c=t.modelID,l=x.value;return a.e=(0,e.style)(n,o,a.e),a.t=(0,e.style)(r,s,a.t),c!==a.a&&(0,e.setAttribute)(r,`title`,a.a=c),a.o=(0,e.style)(i,l,a.o),a},{e:void 0,t:void 0,a:void 0,o:void 0}),n})()})),(0,e.effect)(n=>(0,e.style)(t,x.section,n)),t})()]}})]})]}})),(0,e.effect)(n=>(0,e.style)(t,x.panel,n)),t})()}var C=`context`,w=`window-analytics`,T=`Context`,E=5e3,D=65,O=85,k={id:C,title:T},A=t.Plugin.define({setup(r){let i=`${r.id}:${C}`,a=e=>{let t=e??r.sessions.current();t&&r.layout.open(i,t,{tab:`select`})};r.add(t.Panel,()=>({id:C,region:`side`,wide:!0,list:e=>e.open.includes(C)?[k]:[],render:t=>(0,e.createComponent)(S,{get session(){return t.session}}),mobile:{title:T,order:1,kind:`tab`,icon:w}})),r.add(t.MenuItem,()=>({id:C,menu:`session.panel`,title:T,icon:w,description:`Context-window usage`,run:()=>a()})),r.add(t.Command,()=>({id:`open`,title:`Open context panel`,description:`Context-window usage for this session`,keywords:`context tokens window panel`,section:`session`,slash:{name:`cx`},run:()=>a()}));let[s,c]=(0,n.createSignal)(void 0),l=async()=>{let e=r.sessions.current();if(!e)c(void 0);else try{let t=(await r.client.rpc(o).family({sessionID:e.id}))?.rows?.[0];if(!t||t.usable<=0){c(void 0);return}let n=t.ctx/t.usable*100;c({sessionID:e.id,label:`${n.toFixed(0)}% ctx`,tone:n>=O?`danger`:n>=D?`warning`:void 0})}catch{c(void 0)}};l();let u=setInterval(()=>void l(),E);(0,n.onCleanup)(()=>clearInterval(u)),r.add(t.ComposerPill,()=>({id:`usage`,show:({session:e})=>{let t=s();if(t&&t.sessionID===e.id)return{label:t.label,icon:w,tone:t.tone,title:`Context window usage`,run:()=>a(e)}}}))}});exports.default=A;

package/index.js

@@ -127,10 +127,9 @@
  *
  *   - Metric: the native opencode overflow count — tokens.total when present,
  *     else input + output + cache.read + cache.write — compared against the
- *     model's compaction ceiling (opencode calculateCeiling, unchanged since
- *     2.1.4): window =
-  *     limit.input || limit.context, reserve = max(15% of window, 16k when
-  *     window >= 32k), usable = window - reserve. Percentages are NOT
+ *     model's compaction ceiling (opencode calculateCeiling, released 2.x):
+ *     window = limit.input || limit.context, reserve = max(15% of window, 16k
+ *     when window >= 32k), usable = window - reserve. Percentages are NOT
   *     clamped at 100% - exceeding the ceiling must stay visible.
  *   - Category estimates use a unicode-aware heuristic (see estimateTokens):
  *     Cyrillic ~2.5 chars/token, CJK ~1.5, latin/ASCII ~4. These are ESTIMATES,
@@ -177,7 +176,8 @@ import {
   modelLimits,
   reserveFor,
 } from "./lib/limits.js";
-import { lastKnownCacheRead, lastKnownCacheWrite, lastKnownCtxCache, lastKnownInputCache, lastKnownReasoningCache, sessionAgentCache, sessionParentCache } from "./lib/cache.js";
+import { breakdownCache, lastKnownCacheRead, lastKnownCacheWrite, lastKnownCtxCache, lastKnownInputCache, lastKnownReasoningCache, sessionAgentCache, sessionParentCache } from "./lib/cache.js";
+import { registerDesktopRpc, toDesktopRow } from "./lib/desktop.js";
 import {
   logErr,
   readStateSnapshot,
@@ -229,9 +229,12 @@ export {
   lastKnownCacheRead,
   lastKnownCacheWrite,
   lastKnownCtxCache,
+  breakdownCache,
   lastKnownInputCache,
   lastKnownReasoningCache,
   handleV2Event,
+  registerDesktopRpc,
+  toDesktopRow,
 };
 
 // ---------------------------------------------------------------------------
@@ -337,6 +340,13 @@ export default {
       logErr("v2 command transform registration failed", err);
     }
 
+    // Desktop GUI data channel (experimental GUI plugins, opencode 2.2.0+).
+    // The GUI part ships as ./gui-experimental and calls this contract through
+    // ctx.client.rpc(); without it the panel has no data, so the registration is
+    // non-fatal and the TUI / slash commands keep working either way.
+    const desktopRpc = await registerDesktopRpc(ctx);
+    if (desktopRpc) registrations.push(desktopRpc);
+
     const controller = new AbortController();
     void (async () => {
       try {