opencode-context-indicator 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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
@@ -60,14 +94,14 @@ OpenCode Desktop app, not just in the terminal.
   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 corrected for opencode 2.2.x.** `calculateCeiling()` keeps the
-  same shape but the reserve share dropped from 15 % to 10 % in 2.2.0 (the
-  "fit output limits to the context window" change, PR #51271), so the plugin
-  now mirrors `max(floor(window * 0.10), window >= 32_000 ? 16_000 : 0)`. Every
-  `%` and the `compact at` line are now computed against the host's actual
-  trigger; on a large window the old formula understated the ceiling by ~5 % of
-  the window (~26 k tokens at 512 k). The 1.6.0 note that the ceiling was
-  unchanged in 2.2.0 was wrong — the `2 * RESERVE_MIN` gate did stay.
+- **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
@@ -100,11 +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 (superseded — see 1.7.0).**
+- **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.
 
@@ -150,8 +186,9 @@ Fix-and-hygiene release after a full-project review. No new commands.
 
 - **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%;
-  the share moved again in 2.2.0 — see 1.7.0),
+  `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

@@ -16,7 +16,7 @@ sidebar** and a **zero-LLM `/cx` breakdown panel** with measured contributors
 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 Desktop CLI); the V1 path against 1.18.29+.
+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.
@@ -72,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.x compaction ceiling**: `window =
-  limit.input || limit.context`; `reserve = max(floor(window * 0.10), 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` (the reserve
-  share is 10% since 2.2.0 / PR #51271; it was 15% up to 2.1.x). 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`
@@ -635,7 +637,8 @@ the sidebar instead.
   and toasts keep working).
 * **OpenCode ≥ 2.2.0** for the V2 path with the TUI surfaces (built and verified
   against **2.2.0**; the isolated load + state-write e2e also passes on the
-  **2.2.1** Desktop CLI). The server-only V2 path keeps working on
+  **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.
@@ -724,7 +727,7 @@ caller.
 
 ```bash
 npm run build:gui             # build dist/gui-experimental.cjs (required by the gate)
-npm run test:prepublish       # fast gate: tarball + tui.tsx + resolve + T1-T35 unit checks + GUI bundle
+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
@@ -747,7 +750,7 @@ STEP 80 s, ~3 min total.
 | (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-T35 | 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 (85 total; T30 schema-vs-builder drift, T31 registration + handler, T32-T35 fallback-vs-hook category priority across the report, the shared state file and the live log, 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 |
+| (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 |

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, core 2.2.x):
- *     window = limit.input || limit.context, reserve = max(10% of window, 16k
- *     when window >= 32k), usable = window - reserve (the share was 15% up to
- *     2.1.x). 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,

package/lib/limits.js

@@ -12,11 +12,11 @@
 // auto-compaction trigger ceiling as window - reserve, where
 // window = limit.input || limit.context (null/zero falls through to the context
 // window) and
-//   reserve = max(floor(window * 0.10), window >= 2 * 16_000 ? 16_000 : 0)
-// The share was 15% up to v2.1.x and is 10% since v2.2.0 (PR #51271 "fit output
-// limits to the context window"); the `2 * RESERVE_MIN` gate is unchanged. A
-// wrong reserve makes every displayed percentage wrong, so this mirrors the
-// host exactly.
+//   reserve = max(floor(window * 0.15), window >= 2 * 16_000 ? 16_000 : 0)
+// `RESERVE_SHARE = 0.15` in every RELEASED host from 2.1.4 through 2.2.2
+// (verified tag by tag; the `2 * RESERVE_MIN` gate is older and unchanged). The
+// unreleased `v2` branch HEAD has an inline `0.1` instead - do NOT mirror a
+// branch head: a wrong reserve makes every displayed percentage wrong.
 // A compaction.buffer configured in opencode itself is NOT visible to the
 // plugin (the plugin cannot read opencode's internal compaction config); the
 // env var OPENCODE_CONTEXT_INDICATOR_COMPACT_BUFFER overrides the reserve for
@@ -85,11 +85,11 @@ function getModelLimit(providerID, modelID) {
 }
 
 // Compute the reserve for a given window, matching opencode's
-// packages/core/src/session/compaction.ts calculateCeiling() in 2.2.x (the
-// share became 10% in 2.2.0; the 2 * RESERVE_MIN gate is older and unchanged).
+// packages/core/src/session/compaction.ts calculateCeiling() as RELEASED
+// (RESERVE_SHARE = 0.15 in 2.1.4 .. 2.2.2; the branch head is not a release).
 // Returns null when
 // window is not a finite positive number.
-const RESERVE_SHARE = 0.1; // core: 10% of the window (15% before v2.2.0)
+const RESERVE_SHARE = 0.15; // core: RESERVE_SHARE in every released 2.x
 const RESERVE_MIN = 16_000; // core: RESERVE_MIN
 function reserveFor(window, bufferOverride) {
   if (
@@ -109,7 +109,7 @@ function reserveFor(window, bufferOverride) {
     return bufferOverride;
   }
   // Default reserve formula (mirror of opencode core):
-  //   max(floor(window * 0.10), window >= 2 * RESERVE_MIN ? RESERVE_MIN : 0)
+  //   max(floor(window * 0.15), window >= 2 * RESERVE_MIN ? RESERVE_MIN : 0)
   // The threshold is 2 * RESERVE_MIN (32_000), not RESERVE_MIN.
   return Math.max(
     Math.floor(window * RESERVE_SHARE),
@@ -117,7 +117,7 @@ function reserveFor(window, bufferOverride) {
   );
 }
 
-// Native opencode compaction ceiling (calculateCeiling, core v2.2.x):
+// Native opencode compaction ceiling (calculateCeiling, released 2.x):
 //   window = limit.input || limit.context  (zero/null falls through to context)
 //   reserve = reserveFor(window)  [or bufferOverride when provided]
 //   usable  = window - reserve

package/lib/v2.js

@@ -15,6 +15,7 @@ import {
   extractToolTarget,
   fmt,
   isHookMeasuredEntry,
+  isHookSource,
   isSafeSessionKey,
   oneLine,
   safeReclaim,
@@ -741,7 +742,21 @@ function buildLiveLinesV2(sessionID, modelID, providerID, inputTokens, ctxTokens
   let snapInputTokens = null;
   let snapCtxTokens = null;
   let snapAt = null;
-  if (!bd || bd.source === "client-context") {
+  let borrowedSnapshot = false;
+  // A hook breakdown whose instance has NO request counters is just as
+  // unprintable as a fallback: the categories are measured, but the total this
+  // instance knows is 0 (it never completed a step - e.g. a mirror that only
+  // saw the compaction hook). Such an entry also takes the state.json path, so
+  // the header and the categories come from ONE measurement instead of a
+  // `ctx=0` header sitting above non-zero categories.
+  const haveLocalCounters =
+    (typeof inputTokens === "number" && inputTokens > 0) ||
+    (typeof ctxTokens === "number" && ctxTokens > 0);
+  if (
+    !bd ||
+    bd.source === "client-context" ||
+    (isHookSource(bd.source) && !haveLocalCounters)
+  ) {
     const entry = isSafeSessionKey(sessionID)
       ? readStateSnapshot()[sessionID]
       : null;
@@ -750,13 +765,33 @@ function buildLiveLinesV2(sessionID, modelID, providerID, inputTokens, ctxTokens
       snapInputTokens = safeSaneOrNull(entry.input);
       snapCtxTokens = safeSaneOrNull(entry.ctx);
       snapAt = typeof entry.updatedAt === "string" ? entry.updatedAt : null;
+      borrowedSnapshot = true;
     }
   }
   const source = bd?.source || "none";
   const rt = typeof reasoningTokens === "number" ? reasoningTokens : 0;
   const effInput = snapInputTokens != null ? snapInputTokens : inputTokens;
   const effCtx = snapCtxTokens != null ? snapCtxTokens : ctxTokens;
-  const total = typeof effCtx === "number" && effCtx > 0 ? effCtx : effInput;
+  // Only a POSITIVE counter is knowledge. A zero is exactly what the broken
+  // case looks like (a state entry written by the trailing-event fallback of a
+  // mirror instance carries `ctx: 0, input: 0`), and treating it as "known"
+  // would reprint the very `ctx=0` this path exists to avoid.
+  const haveSnapCounters =
+    (typeof snapInputTokens === "number" && snapInputTokens > 0) ||
+    (typeof snapCtxTokens === "number" && snapCtxTokens > 0);
+  // Still unknown (no counters here AND no usable hook measurement on disk):
+  // print "?" rather than a fabricated 0 that contradicts the categories below.
+  const countersKnown = haveLocalCounters || haveSnapCounters;
+  // `other = input - sum` needs the input itself; a ctx-only snapshot (the
+  // compaction hook knows ctx but a mirror never saw the request) cannot
+  // produce an honest residual.
+  const inputKnown =
+    countersKnown && typeof effInput === "number" && effInput > 0;
+  const total = !countersKnown
+    ? null
+    : typeof effCtx === "number" && effCtx > 0
+      ? effCtx
+      : effInput;
   const denom =
     usableInfo != null
       ? usableInfo.usable
@@ -764,13 +799,19 @@ function buildLiveLinesV2(sessionID, modelID, providerID, inputTokens, ctxTokens
         ? limit
         : null;
   const pct =
-    denom != null ? ` (${((total / denom) * 100).toFixed(1)}%)` : "";
+    denom != null && total != null
+      ? ` (${((total / denom) * 100).toFixed(1)}%)`
+      : "";
   // The reader must be able to tell a fresh local measurement from a borrowed
-  // snapshot (and from how old it is).
-  const snapNote = snapAt ? ` snapshot=${snapAt}` : "";
+  // snapshot (and from how old it is). A snapshot without a timestamp still
+  // must not look local.
+  const snapNote = borrowedSnapshot
+    ? ` snapshot=${snapAt || "unknown"}`
+    : "";
 
+  const shownTotal = total != null ? fmt(total) : "?";
   lines.push(
-    `[${ts}] session=${sessionID} model=${modelID} ctx=${fmt(total)}/${denom != null ? fmt(denom) : "?"}${pct} count=${fmt(total)} usable=${usableInfo != null ? fmt(usableInfo.usable) : "?"} limit=${limit != null ? fmt(limit) : "?"} maxOutput=${usableInfo != null ? fmt(usableInfo.maxOutput) : "?"} reserved=${usableInfo != null ? fmt(usableInfo.reserved) : "?"} input=${fmt(effInput)}${snapNote}`,
+    `[${ts}] session=${sessionID} model=${modelID} ctx=${shownTotal}/${denom != null ? fmt(denom) : "?"}${pct} count=${shownTotal} usable=${usableInfo != null ? fmt(usableInfo.usable) : "?"} limit=${limit != null ? fmt(limit) : "?"} maxOutput=${usableInfo != null ? fmt(usableInfo.maxOutput) : "?"} reserved=${usableInfo != null ? fmt(usableInfo.reserved) : "?"} input=${inputKnown ? fmt(effInput) : "?"}${snapNote}`,
   );
 
   // Residual = input minus every measured category (shared normaliser; `bd`
@@ -778,10 +819,11 @@ function buildLiveLinesV2(sessionID, modelID, providerID, inputTokens, ctxTokens
   // breakdown taken from state.json carries the residual the HOOK computed
   // against the input IT saw; this instance's `inputTokens` can differ (a mirror
   // that only saw the trailing event has 0), so that value is used instead.
-  const other =
-    typeof bd?.otherChars === "number"
+  const other = inputKnown
+    ? typeof bd?.otherChars === "number"
       ? bd.otherChars
-      : breakdownCategories(bd, effInput).other;
+      : breakdownCategories(bd, effInput).other
+    : null;
 
   if (bd) {
     lines.push(`  user        ${fmt(bd.userChars || 0)} (est tokens)`);
@@ -811,7 +853,11 @@ function buildLiveLinesV2(sessionID, modelID, providerID, inputTokens, ctxTokens
     lines.push(`  system      n/a (hook did not run)`);
     lines.push(`  tool schemas n/a`);
   }
-  lines.push(`  other       ${fmt(other)} (= input - sum of estimates)`);
+  lines.push(
+    other != null
+      ? `  other       ${fmt(other)} (= input - sum of estimates)`
+      : `  other       n/a (input unknown on this instance)`,
+  );
   lines.push(`  source      ${source}`);
 
   // Provider-reported prompt cache (EXACT, not an estimate; a subset of input —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-context-indicator",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Real-time context-window usage for OpenCode: per-category token breakdown, /context-diff, a zero-LLM /cx panel with per-session cost and a searchable family-session picker, a TUI sidebar, and an experimental Desktop panel. Dual V1 + V2 plugin entry.",
   "type": "module",
   "license": "MIT",