opencode-context-indicator 1.5.3 → 1.5.4

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.5.4 — 2026-10-27
+
+Fix-and-hygiene release after a full-project review. No new commands.
+
+- **Subagent roll-up no longer collapses on a child's idle.** `session.idle`
+  wiped the child's parent attribution and accumulated totals, so the very next
+  live line reported `subagents 0 session(s)` right after any subagent
+  finished, even though its parent was still running. V2 now keeps a finished
+  child's entries until the parent itself goes idle or is deleted
+  (`clearChildSubagentTracking`, breadth-first, so sub-subagents are collected
+  too); `/context-breakdown` and `/cx` were never affected (they read
+  `state.json`). T29 covers the lifetime.
+- **TUI panel no longer re-measures every message once per second.** The
+  measured-contributors memo was keyed on the 1000 ms snapshot tick and the host
+  rebuilds the message array on every poll, so the full walk (per-character
+  token estimates plus `JSON.stringify` of tool args) ran on the render thread
+  every second. It is now keyed on a cheap signature (list length, last message
+  id, last message size including tool results and status), so a static session
+  costs almost nothing while streaming text and completing tool calls still
+  refresh.
+- **A summary-only log write keeps the live snapshot.** `pushFinalSummary` used
+  to rewrite `context-breakdown.log` with an empty live section, so every idle /
+  compaction / command payload blanked it until the next measured write. The
+  module now remembers the last rendered snapshot and re-renders it.
+- Doc fixes: the log is rewritten atomically rather than "appended" with
+  `appendFileSync`, and both its sections are process-local (survive rewrites,
+  not a restart); the `state.json` field list now includes `toolOutByTool`,
+  `reclaim`, `cacheRead`/`cacheWrite` and `compactedAt`/`compactStale`; "tested
+  against opencode" now says 2.1.4 (was a stale v2.0.28); the gate table now
+  states the actual scan scope.
+- Packaging: `docs/` is published, so the README screenshot resolves on the npm
+  page. Gate (a) expands `docs/` the same way it expands `lib/` and rejects any
+  non-image file there.
+- Tests: new `OPENCODE_CONTEXT_INDICATOR_LOG_FILE` override (test isolation -
+  idle/compacted handlers no longer rewrite the user's real
+  `context-breakdown.log`), T29 added (child / grand-child lifetime). 75 unit
+  checks.
+
 ## 1.5.3 — 2026-10-26
 
 - **Compaction ceiling aligned with opencode 2.1.4 (#51271).** `lib/limits.js`

package/README.md

@@ -13,7 +13,7 @@ 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 v2.0.28**; the
+and a redacted export. The V2 path is **tested against opencode 2.1.4**; the
 V1 path against 1.18.29+.
 
 > **V1 is feature-frozen.** It is kept working for compatibility (bug fixes
@@ -302,8 +302,9 @@ notice if needed.
   are also seeded from the snapshot at startup, and the retry backs off
   (30 s → 5 min, capped). A known `usable`/`limit`/`agent` is never overwritten
   with `null` when another instance rewrites the snapshot.
-* All three commands append their payload to `context-breakdown.log` (final-summaries
-  section), so it stays recoverable even if delivery fails.
+* All three commands copy their payload into `context-breakdown.log` (final-summaries
+  section) while the plugin instance lives, so it stays recoverable even if
+  delivery fails (see the log lifetime note under "Log / state file locations").
 * If `ctx.session.synthetic` throws, the command logs an actionable error and the
   payload is preserved in the log — there is no other delivery channel in this
   runtime (no `noReply`/`prompt` option exists).
@@ -405,16 +406,24 @@ 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}`, `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}`, `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 live `context-breakdown.log` snapshot is **rewritten** (never grows); final
-summaries (on `session.idle`) and compaction notes are **appended** — log writes
-use plain `appendFileSync`, not atomic replacement. Only the machine-readable
-`opencode-context-indicator-state.json` is written **atomically** (temp file +
-rename), so concurrent plugin instances cannot corrupt it. Cross-instance
-duplicate final summaries are prevented separately by an atomic claim marker
-(see `lib/dedup.js`).
+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`).
 
 ---
 
@@ -617,7 +626,7 @@ caller.
 ### Running tests
 
 ```bash
-npm run test:prepublish       # fast gate: tarball + tui.tsx + resolve + T1-T28 unit checks
+npm run test:prepublish       # fast gate: tarball + tui.tsx + resolve + T1-T29 unit checks
 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)
@@ -636,12 +645,12 @@ 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) | 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 | no test/node_modules/tsconfig in the tarball |
 | (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-T28 | limit/agent/state fix assertions plus measureContributors, redacted-export, shared category-helper, sanitizer/unicode, prompt-cache, waste-detector, compaction-reserve, top-consumer and diff checks (74 total) | regressions in modelLimits, writeStateFile, hydrate, contributors, export |
-| (e) corporate-identifier scan | no forbidden identifiers in the published surface + test tree | compliance |
-| (f) non-English scan | no non-ASCII letters (`\p{L}` above U+007F) in any repo file | English-only source rule |
+| (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 |
+| (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 |
 
 **Isolated E2E — `test/e2e-tui.mjs`** (requires the OpenCode CLI)
 
@@ -655,7 +664,10 @@ The E2E is fully **non-invasive** to your running OpenCode Desktop:
 - `--standalone` starts a *private* server instead of the background service Desktop uses;
 - `OPENCODE_DB` points at a throwaway DB in `%TEMP%` (your sessions are untouched);
 - `OPENCODE_CONTEXT_INDICATOR_STATE_FILE` points at a throwaway state file in `%TEMP%`
-  — the live `opencode-context-indicator-state.json` is never read or written;
+  - the live `opencode-context-indicator-state.json` is never read or written;
+- `OPENCODE_CONTEXT_INDICATOR_LOG_FILE` does the same for the human-readable
+  `context-breakdown.log` (used by the unit gate, which drives idle/compacted
+  handlers);
 - `OPENCODE_CONFIG_DIR` points at a throwaway global config written by the script
   (plugins: this checkout; `update: "disable"`) **for Check A only** — the load
   source is deterministic and fail-closed instead of following your live config;

package/lib/cache.js

@@ -120,9 +120,15 @@ function lastKnownCacheWrite(sessionID) {
 // Clear per-session tracking. Full wipe on session.idle / session.deleted;
 // on session.compacted (keepToastDedup=true) the toast-dedup entries survive
 // the cleanup so consecutive compacted events still dedup.
+//
+// `keepSubagentRollup` preserves THIS session's parent attribution and token
+// totals. A finished subagent goes idle while its parent is still running; the
+// parent's live roll-up must keep counting that child, so the V2 idle handler
+// passes `true` for children and lets the parent's own idle/deleted wipe them
+// (see clearChildSubagentTracking).
 // ---------------------------------------------------------------------------
 
-function clearSessionTracking(sessionID, keepToastDedup = false) {
+function clearSessionTracking(sessionID, keepToastDedup = false, keepSubagentRollup = false) {
   if (!sessionID) return;
   lastShown.delete(sessionID);
   breakdownCache.delete(sessionID);
@@ -134,7 +140,7 @@ function clearSessionTracking(sessionID, keepToastDedup = false) {
     lastCompactedToast.delete(sessionID);
   }
   // Attribution cache (re-resolved on the next toast if needed).
-  sessionParentCache.delete(sessionID);
+  if (!keepSubagentRollup) sessionParentCache.delete(sessionID);
   // Idle-summary caches were previously left dirty — clean them too.
   lastKnownModelCache.delete(sessionID);
   lastKnownProviderCache.delete(sessionID);
@@ -145,7 +151,7 @@ function clearSessionTracking(sessionID, keepToastDedup = false) {
   lastKnownCacheWriteCache.delete(sessionID);
   lastBdWrite.delete(sessionID);
   // V2 subagent accumulation for this session.
-  sessionTotals.delete(sessionID);
+  if (!keepSubagentRollup) sessionTotals.delete(sessionID);
   // V2 agent label + context-fallback throttle (previously left dirty).
   sessionAgentCache.delete(sessionID);
   v2ContextFetchTimes.delete(sessionID);
@@ -155,6 +161,33 @@ function clearSessionTracking(sessionID, keepToastDedup = false) {
   lastCompactionHookAt.delete(sessionID);
 }
 
+// Drop the roll-up entries of every descendant of `rootID` (attribution plus
+// accumulated totals). Called when a session itself goes idle or is deleted:
+// until then, finished children stay in the cache so the live roll-up keeps
+// reporting them instead of collapsing to "0 session(s)" the moment a child
+// finishes. Breadth-first, because a sub-subagent hangs off a child and a
+// single-level sweep would leave it as a permanent orphan. Deletion during Map
+// iteration is well-defined in JS.
+function clearChildSubagentTracking(rootID) {
+  if (!rootID) return;
+  const queue = [rootID];
+  const seen = new Set(queue);
+  while (queue.length > 0) {
+    const parent = queue.shift();
+    for (const [childID, parentID] of sessionParentCache) {
+      if (parentID !== parent) continue;
+      // Full per-session wipe, not just the two roll-up maps: the child's
+      // lastKnown*/breakdown/tool-schema caches would otherwise linger until
+      // FIFO eviction and never be updated again.
+      clearSessionTracking(childID);
+      if (!seen.has(childID)) {
+        seen.add(childID);
+        queue.push(childID);
+      }
+    }
+  }
+}
+
 export {
   MAX_TRACKED_SESSIONS,
   BREAKDOWN_THROTTLE_MS,
@@ -190,4 +223,5 @@ export {
   lastKnownCacheRead,
   lastKnownCacheWrite,
   clearSessionTracking,
+  clearChildSubagentTracking,
 };

package/lib/state.js

@@ -52,7 +52,11 @@ const MAX_FINAL_SUMMARIES = 50; // bound the in-memory final-summary log
 const DEBUG_EVENTS = false;
 const EVENT_LOG_MAX_BYTES = 1024 * 1024; // ~1MB truncate threshold
 
-const LOG_FILE = join(tmpdir(), "context-breakdown.log");
+// Human-readable live log. Overridable via env for test isolation (same
+// contract as STATE_FILE); in production the env is never set.
+const LOG_FILE =
+  process.env.OPENCODE_CONTEXT_INDICATOR_LOG_FILE ||
+  join(tmpdir(), "context-breakdown.log");
 
 // Machine-readable snapshot consumed by the optional TUI sidebar (./tui.tsx,
 // package entry "./tui"). Written next to each log update — same moment, same
@@ -149,12 +153,27 @@ function renderFile(liveLines) {
 // Atomically rewrite the whole log file (bounded by design). The temp+rename
 // makes concurrent writers from multiple plugin instances safe: a reader sees
 // either the previous or the new file, never a half-written one.
+//
+// The last rendered live snapshot is remembered: callers that only add a final
+// summary / compaction note pass no live lines, and an empty snapshot section
+// after every idle would make the log useless.
+let lastLiveLines = [];
+
 function writeLog(liveLines) {
   try {
-    const content = renderFile(liveLines);
+    if (Array.isArray(liveLines) && liveLines.length > 0) {
+      lastLiveLines = liveLines;
+    }
+    const content = renderFile(
+      Array.isArray(liveLines) && liveLines.length > 0 ? liveLines : lastLiveLines,
+    );
     // Random temp suffix + exclusive create ("wx"): a predictable name could be
     // pre-created as a symlink for us to follow (CWE-377). "wx" fails instead.
     const tmp = `${LOG_FILE}.${randomBytes(6).toString("hex")}.tmp`;
+    // Unlike writeStateFile there is no ensureRegularFile(LOG_FILE) guard: the
+    // destination is only ever replaced by rename(2), which swaps the directory
+    // entry and never follows a symlink, so a pre-planted link cannot redirect a
+    // write. The "wx" temp below already blocks the symlink-attack vector.
     // Create BEFORE the finally-guarded section (mirrors writeStateFile): on an
     // (astronomically unlikely) EEXIST collision with a peer's temp, THEIR file
     // must not be cleaned up by us — the write fails and is logged instead.

package/lib/tui-panel.tsx

@@ -53,6 +53,74 @@ type PanelInput = {
 // (never once per poll) when it is unavailable and hide the whole section.
 let warnedMessagesUnavailable = false
 
+// Cheap change detector for the live message list. The host hands back a fresh
+// array on every poll, so identity cannot be used as a memo key, while walking
+// the whole list (per-character estimates + JSON.stringify of tool args) once
+// per 1000 ms tick is exactly the cost we want to avoid. Length + last message
+// id + created stamp + last message payload size covers appends, streaming and
+// tool completion; an in-place edit of an OLDER message lands one tick later,
+// when the tail changes. Known blind spot by design: the size is a SUM, so a
+// same-length substitution inside the last message is not detected.
+function listSignature(list: unknown[]): string {
+  const n = list.length
+  if (n === 0) return "0"
+  const last: unknown = list[n - 1]
+  if (last == null || typeof last !== "object") return `${n}:?`
+  const rec = last as Record<string, unknown>
+  const id = typeof rec.id === "string" ? rec.id : ""
+  const time = rec.time
+  const created =
+    time != null && typeof time === "object"
+      ? String((time as Record<string, unknown>).created ?? "")
+      : ""
+  let size = typeof rec.text === "string" ? rec.text.length : 0
+  const parts: unknown[] = Array.isArray(rec.content) ? rec.content : []
+  for (const raw of parts) {
+    if (raw == null || typeof raw !== "object") continue
+    const part = raw as Record<string, unknown>
+    if (typeof part.text === "string") {
+      size += part.text.length
+      continue
+    }
+    const state = part.state
+    if (state == null || typeof state !== "object") continue
+    const st = state as Record<string, unknown>
+    if (typeof st.input === "string") size += st.input.length
+    else if (st.input != null) {
+      try {
+        size += JSON.stringify(st.input).length
+      } catch {
+        /* unstringifiable input contributes no size */
+      }
+    }
+    // Tool RESULTS matter as much as args: measureContributors reads
+    // state.content, and a call that finishes between two ticks changes nothing
+    // else on the message. Without this the measured section would freeze for
+    // the whole remainder of the turn.
+    const content = st.content
+    if (typeof content === "string") {
+      size += content.length
+    } else if (Array.isArray(content)) {
+      for (const rawItem of content) {
+        if (rawItem == null || typeof rawItem !== "object") continue
+        const item = rawItem as Record<string, unknown>
+        if (typeof item.text === "string") {
+          size += item.text.length
+        } else {
+          // Non-text parts (e.g. file refs with long/base64 URIs) are not
+          // measured by measureContributors, so their marker is enough: never
+          // JSON.stringify a potentially megabyte-sized reference per tick.
+          size += 1
+        }
+      }
+    }
+    // Status transitions (pending -> completed/error) are cheap and always
+    // accompany a visible change.
+    if (typeof st.status === "string") size += st.status.length
+  }
+  return `${n}:${id}:${created}:${size}`
+}
+
 // Panel column layout (monospace), derived from the host-provided panel width
 // so cells never collide on narrow terminals. Gaps between columns keep a
 // truncated cell visually separated from its neighbour.
@@ -253,14 +321,38 @@ export function BreakdownPanel(props: {
     }
   })
 
+  // Memo for the measured contributors section: the signature/key pair keeps
+  // the expensive walk out of the per-tick path (see listSignature).
+  let contributorKey: string | null = null
+  let contributorValue: Contributor[] = []
+
   const contributors = createMemo<Contributor[]>(() => {
     const m = messages()
-    if (!m.available) return []
+    if (!m.available) {
+      contributorKey = null
+      contributorValue = []
+      return contributorValue
+    }
+    // Re-measure ONLY when the message list actually changed. The host rebuilds
+    // the array (and `props.snapshot()` ticks) every second, so keying on array
+    // identity would re-walk every message — per-character token estimates plus
+    // JSON.stringify of tool args — once per tick on the render thread.
+    let key: string
+    try {
+      key = listSignature(m.list)
+    } catch {
+      key = ""
+    }
+    if (key && key === contributorKey) return contributorValue
     try {
-      return measureContributors(m.list)
+      contributorValue = measureContributors(m.list)
+      contributorKey = key || contributorKey
     } catch {
-      return []
+      // Transient failure: leave the key unset so the next tick retries.
+      contributorValue = []
+      contributorKey = null
     }
+    return contributorValue
   })
 
   // Redacted export (key `e`). No message text, no full session id, no tool

package/lib/v2.js

@@ -24,6 +24,7 @@ import {
 import {
   BREAKDOWN_THROTTLE_MS,
   breakdownCache,
+  clearChildSubagentTracking,
   clearSessionTracking,
   ERROR_TOAST_DEDUP_MS,
   lastBdWrite,
@@ -833,6 +834,10 @@ async function handleV2Event(ctx, event) {
     // stale entry lingers, via the phantom filter — a deleted session has no
     // step). No dedicated in-memory index to clean up.
     clearSessionTracking(sid);
+    // Whatever this session was, its own descendants must go too: a deleted
+    // parent takes the whole subtree, and a deleted child takes its own
+    // sub-subagents (they would otherwise never be swept).
+    clearChildSubagentTracking(sid);
     return;
   }
 
@@ -922,7 +927,13 @@ async function handleV2Event(ctx, event) {
     } catch (err) {
       logErr("v2 final summary on idle failed", err);
     }
-    clearSessionTracking(sid);
+    // Children keep their parent attribution + totals while the parent runs:
+    // otherwise the very next live line reports "subagents 0" right after a
+    // subagent finishes. A root idle sweeps the whole child set instead.
+    const parentID = sessionParentCache.get(sid);
+    const isSubagent = parentID != null;
+    clearSessionTracking(sid, false, isSubagent);
+    if (!isSubagent) clearChildSubagentTracking(sid);
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-context-indicator",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "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, and a TUI sidebar. Dual V1 + V2 plugin entry.",
   "type": "module",
   "license": "MIT",
@@ -12,6 +12,7 @@
     "index.js",
     "lib/",
     "tui.tsx",
+    "docs/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"