@cesarus777/opencode-cgp 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.4.1 — 2026-11-07
+
+- Keep native performance Charts visible immediately after returning from help. Pause reads and polling during help, retain only the matching plot, and discard it when session, location, or window changes. See the [chart-help continuity plan](docs/plans/native-chart-help-continuity.md) and [0.4.1 release validation](docs/validation/release-0.4.1-2026-11-07.md).
+
+- Distinguish missing history service, timeout, incompatible response, rejected request and temporary failure in native Charts and standalone History. Preserve matching previous results with their successful-load timestamp and original range during refresh/failure; provide accurate keyboard retry without exposing server errors.
+- Coalesce native chart retries, discard obsolete responses, pause polling when recording/service compatibility needs attention, and keep refresh visible at narrow widths. Validate UX-10 with 233 offline tests and native/standalone synthetic-provider PTY checks on OpenCode 2.0.29 and 2.1.2; see the [chart recovery delivery record](docs/validation/chart-failure-recovery-2026-11-07.md).
+
+- Use plain-language measurement and compaction labels across the native sidebar/panel and standalone session dashboard. Distinguish provider-reported, estimated, stale, missing and unusable readings, accepted requests, context-reduction checks and unconfirmed completion.
+- Lead Details with readable explanations and a performance glossary while retaining exact diagnostic codes and accounting fields. Clarify context-chart legends with “Dim = last known context” and “┄ threshold”; preserve trace geometry and compaction semantics.
+- Validate UX-09 with 222 offline tests and native/standalone synthetic-provider PTY checks on OpenCode 2.0.29 and 2.1.2. The sidebar fixture occupies 22 lines at 39 columns and 23 at 35 columns. See the [terminology delivery record](docs/validation/plain-language-terminology-2026-11-07.md).
+
+- Compact the native sidebar to identity-first occupancy, early panel access, expandable history and two-line ordinary descendant rows. Group completed subtrees only when discovery and their measurement/lifecycle states are trustworthy; preserve attention-bearing ancestry and hidden-fold feedback.
+- Move sidebar throughput and aggregate diagnostics into panel Details, with route-family statistics independent of selection/folding. The ordinary fixture shrinks from 63 to 22 lines at 39 columns; validate with 220 offline tests and synthetic-provider PTY checks on OpenCode 2.0.29 and 2.1.2. See the [sidebar validation record](docs/validation/sidebar-density-2026-11-06.md).
+
+- Add native-panel keyboard help with preserved selection, scroll position and chart settings. Pause chart polling during help, keep Guard status visible, and reserve contextual help/close controls at narrow widths.
+- Report native inventory discovery progress, actionable continuation, failures and node bounds. Add the client plugin option `openShortcut` for keyboard entry from child composers through the existing `context-guard.show` command and display its effective shortcut; it remains unbound by default. See the [native keyboard/help validation](docs/validation/native-keyboard-help-2026-11-06.md).
+
+- Compact the standalone dashboard Overview into aligned columns or narrow cards, with bounded exception lines and full diagnostics in Details. Preserve the selected identity through resizing, updates and small viewports; page by visible session rows.
+- Add distinguishing session labels, contextual details/quit hints, and filtered-selection feedback. Validate with 213 offline tests and synthetic-provider PTY checks on OpenCode 2.0.29 and 2.1.2; see the [overview validation record](docs/validation/standalone-overview-density-2026-11-06.md).
+
+- Use consistent threshold and Guard status wording across the native sidebar, panel, and standalone dashboard. Replace “tokens until compaction” with distance below/over threshold, and separate capacity occupancy from “Near threshold” / “Threshold reached.”
+- Keep stale occupancy labeled “Last measured” while current pressure stays unknown. Explain last-known Guard health during disconnect and reason-specific reload/storage-repair requirements without treating reconnect as enforcement recovery.
+- Preserve critical status and selected identity at narrow sizes; retain monitoring-limit/model-limit warnings and exact diagnostic reason codes in Details. Validate with 209 offline tests and native/standalone OpenCode 2.1.2 PTY smoke tests; see the [status validation record](docs/validation/threshold-status-consistency-2026-11-06.md).
+
+- Open `/context-guard` with a compact selected-session summary and nested family list. Move full diagnostics and the context-history chart into Details (`i`), keeping retained performance Charts on `c`.
+- Preserve selected-session identity across views, refreshes, and ordering changes; fall back safely when a selected session disappears. Keep one panel consumer active across all views.
+- Add responsive table/card layouts, clickable footer actions, page and boundary navigation, and scrolling in Details. Keep Guard status visible and distinguish stale occupancy, threshold distance, and compaction lifecycle states.
+- Validate the native overview with 205 offline tests and an actual OpenCode 2.1.2 synthetic-provider PTY run; see the [validation record](docs/validation/native-panel-overview-2026-11-06.md).
+
+## 0.4.0 — 2026-10-29
+
+- Add a Models screen to the standalone terminal dashboard: aggregate charts and statistics across retained root, child and archived sessions, exact agent filtering, model sorting, time windows, bucket inspection and paginated request details.
+- Add the read-only, location-scoped `context-guard.analytics.v1` RPC with bounded scans, short-lived snapshots and pagination independent of aggregate totals. Older servers preserve existing dashboard screens and report Models as unsupported.
+
+- Preserve history graph indentation in the standalone dashboard so axes, gap markers and filled columns stay aligned.
+- Keep all model statistics accessible in narrow terminals, scrolling through wrapped rows before advancing model selection.
+- Clarify that the dashboard can run in a separate terminal while working in OpenCode; closing the native TUI was a test setup condition.
+
 ## 0.3.1 — 2026-10-29
 
 - Install the standalone dashboard's pinned OpenTUI renderer automatically with CGP, including its native platform library. Keep renderer loading lazy so server and offline commands still work on Bun >=1.1.34; the dashboard requires Bun >=1.3.0.

package/README.md

@@ -107,7 +107,9 @@ Each command's help explains its inputs and shows an example. In a source checko
 
 ## Standalone terminal dashboard
 
-Run the dashboard with OpenCode's native TUI closed. The server must already be running, with Context Guard registered in the owning location. The standalone command requires **Bun >=1.3.0**. The package automatically installs **`@opentui/core@0.5.17`** and its platform renderer; no separate OpenTUI install is needed. Keep optional dependencies enabled so OpenTUI's native platform library is installed. Server imports and existing diagnostic commands retain Bun >=1.1.34 support. Solid and the native TUI plugin are unnecessary for this command.
+Run the dashboard in a separate terminal tab, window or pane while continuing to work in OpenCode. Both clients connect to the same running server, with Context Guard registered in the owning location. Launch `context-guard dashboard tui` from the same project directory, or select the server and directory explicitly. Each full-screen TUI needs its own terminal. The standalone command requires **Bun >=1.3.0**. The package automatically installs **`@opentui/core@0.5.17`** and its platform renderer; no separate OpenTUI install is needed. Keep optional dependencies enabled so OpenTUI's native platform library is installed. Server imports and existing diagnostic commands retain Bun >=1.1.34 support. Solid and the native TUI plugin are unnecessary for this command.
+
+The dashboard reads live updates without controlling OpenCode's sessions or server lifecycle. Concurrent dashboard/native-client PTYs pass local synthetic-provider validation on OpenCode 2.0.29 and 2.1.2; quitting the dashboard leaves the native client running.
 
 For an unreleased checkout:
 
@@ -127,7 +129,13 @@ bun node_modules/.bin/context-guard dashboard tui
 
 Local discovery uses the current directory by default. An explicit server requires an absolute **server-side** `--directory`; it is passed unchanged. Set `CONTEXT_GUARD_PASSWORD` and optional `CONTEXT_GUARD_USERNAME` (default `opencode`) in the environment for remote authentication. Use HTTPS except on loopback. Credentials in URLs are rejected.
 
-Use `1` overview, `2` detail, `3` history, arrows or `j/k` to navigate, `/` to search, `f` for exact agent/model filters, `l` for location, `r` to refresh, and `?` for help. History uses Left/Right for six metrics, `w` for 5m/1h/24h/7d, and `[`/`]` to inspect exact samples or requests. Detail scrolls through full IDs and every exposed snapshot field. Editors take precedence over shortcuts; Enter applies and Escape cancels. Quit with `q` or Ctrl+C.
+Use `1` overview, `2` detail, `3` history, `4` models, arrows or `j/k` to navigate, `/` to search sessions, `f` for exact agent/model filters, `l` for location, `r` to refresh, and `?` for help. History uses Left/Right for six metrics, `w` for 5m/1h/24h/7d, and `[`/`]` to inspect exact samples or requests. Detail scrolls through full IDs and every exposed snapshot field. Editors take precedence over shortcuts; Enter applies and Escape cancels. Quit with `q` or Ctrl+C.
+
+Overview uses aligned columns at 72 cells or wider and compact cards below that width. Rows show agent/model, execution state, context occupancy, threshold distance, and a bounded exception line; `T` abbreviates threshold and `+N` points to more diagnostics in Details. At widths below 100 cells, `#N` distinguishes the current list positions; wider rows use unique session-ID suffixes where available. Selection follows the full session ID through updates and resizing. PageUp/PageDown moves by visible session rows; Enter/2 opens full details and Escape returns to the selection. Filters preserve the selected session even when they hide its row; arrows select a visible result. At very small heights, the selected identity takes precedence over additional row lines. See the [overview validation](docs/validation/standalone-overview-density-2026-11-06.md).
+
+For **aggregate statistics and charts for a model**, press **4**, select its full `provider/model` identity and press **Enter**. This combines completed requests from root, child and archived sessions in the owning location; no live session selection is needed. **Left/Right** selects weighted request TPS, TTFT median/p95, completed requests or reported output. **w** selects the time window, **[ / ]** inspects a bucket, **f** filters by agent, **d** toggles request details, and **n/p** pages models or requests. **s** cycles model-list sorting and **Escape** returns to the list. Existing inventory model filters seed model selection; session search does not restrict these aggregates.
+
+Models refreshes while visible using the dashboard's 30-second refresh interval; **r** requests a refresh (the server's archive cache lasts up to 30 seconds). Range totals precede pagination and chart reduction. Weighted request TPS divides reported output by summed matched request durations, including TTFT; concurrent durations add, so this measures request performance rather than fleet output per wall-clock second. In-flight requests appear after stream completion, which does not establish task success. TTFT is observed/approximate. Empty or ineligible buckets stay blank and partial coverage remains labeled. See [model analytics](docs/configuration.md#terminal-model-analytics) for server requirements and limits.
 
 The location editor's Tab key cycles up to four remembered owning directories; this is not server-wide discovery. History shows bounded retention, partial/downsampled data and gaps. Unknown measurements stay unknown, while stale occupancy remains labeled and pressure becomes unknown. Browser delivery is a later milestone. See [terminal validation and dependency sizes](docs/validation/dashboard-terminal-2026-10-28.md).
 
@@ -145,17 +153,23 @@ A provider measurement refers to its **completed request**, not the next assembl
 
 ## Native TUI
 
-Open `/context-guard` or **Open Context Guard** in the command palette for current prompt occupancy, effective input capacity, trigger/headroom, measurement freshness, compaction phase and nested agent status. A native sidebar section appears where the host mounts its sidebar; the panel also works on child routes and narrow terminals. The main session includes a live context chart scaled to its full effective input capacity, with a horizontal compaction threshold and recent usage samples. Pauses and temporarily lower values retain the previous chart level in gray with a dashed top; a confirmed compaction followed by reported usage permits a visible drop within the same trace. Key values stay visible as text. Estimates, unknown values, stale measurements and uncertain compaction remain explicit.
+Open `/context-guard` or **Open Context Guard** in the command palette for current prompt occupancy, effective input capacity, trigger/headroom, measurement freshness, compaction phase and nested agent status. A native sidebar section appears where the host mounts its sidebar; the panel also works on child routes and narrow terminals. The panel opens with a compact selected-session summary and a nested family list. **Up / Down** selects an agent; **i** opens its full Details and returns to Overview, while **c** opens retained performance Charts. Selection stays on the same session across views. The sidebar defaults to a compact occupancy bar, two-line ordinary agent rows, and conservative completed-agent grouping, with panel access before the tree. Click **History: show** (or its palette command) to expand the live context chart; panel Details always includes it. The chart is scaled to effective input capacity, with a horizontal compaction threshold and recent usage samples. Pauses and temporarily lower values retain the previous chart level in gray with a dashed top; a confirmed compaction followed by reported usage permits a visible drop within the same trace. Key values stay visible as text. Estimates, unknown values, stale measurements and uncertain compaction remain explicit.
+
+Across the sidebar, panel, and standalone dashboard, context percentages describe effective input capacity. “Near threshold,” “Threshold reached,” and tokens below/over threshold describe policy pressure; crossing a threshold does not promise a compaction. Stale quantities say “Last measured” and current pressure stays unknown. Status explains whether Guard can request compaction. A disconnected client shows last-known Guard status and whether measurements were retained; reconnecting never clears server suspension. Event-stream gaps require reload. Safety-storage failures require repairing storage and reloading. Summaries label measurements as “Provider reported” or “Estimated.” Details explains the request scope, compaction lifecycle, and performance terms before a labeled diagnostics section that retains exact codes. “Request accepted · waiting to start” is not completion; “ended · checking context reduction” still needs a confirming measurement. Exact reason codes remain available in panel/dashboard Details. OpenCode's native compaction remains available in observe mode.
+
+The TUI reads bounded snapshots over public OpenCode RPC, including when telemetry is disabled. Remote clients also need a client-side package registration in `cli.json`; see [the example](examples/cli.jsonc) and [controls, installation and bounds](docs/configuration.md#native-context-guard-view). It targets the inspected 2.0.29 API. The actual local host passes wide root, child and narrow grandchild panel checks. Use **Context Guard: open panel** above a child composer, where the host hides its usual prompt and palette shortcut. For keyboard entry, set `options: { "openShortcut": "<leader>v" }` on the plugin registration in the client `cli.json`; this is unbound by default, and the child action displays the effective shortcut. tmux, Neovim and cross-machine remote validation remain open.
+
+Press **?** in the native panel for scrollable help; **?** or **Escape** returns to the same view, selection, scroll position, and chart settings. Help pauses chart polling and keeps Guard status visible. Contextual footers reserve help/close controls at narrow widths. Overview distinguishes discovery in progress, resumable inventory, failed discovery, and the node bound; help exposes complete discovery diagnostics. Existing standalone keyboard meanings remain unchanged.
 
-The TUI reads bounded snapshots over public OpenCode RPC, including when telemetry is disabled. Remote clients also need a client-side package registration in `cli.json`; see [the example](examples/cli.jsonc) and [controls, installation and bounds](docs/configuration.md#native-context-guard-view). It targets the inspected 2.0.29 API. The actual local host passes wide root, child and narrow grandchild panel checks. Use **Context Guard: open panel** above a child composer, where the host hides its usual prompt and palette shortcut. tmux, Neovim and cross-machine remote validation remain open.
+Enabling Context Guard after work has already started also shows the last reported prompt usage for idle sessions and subagents. Opening the sidebar or panel restores it from the public session context, preserving its original age and **out of date** label. Stale usage still shows tokens and occupancy percentage. Restoration respects model changes, reverts and completed compactions; unavailable provider usage stays unknown. These reads never request compaction, and transcript content is never retained or sent through the plugin RPC.
 
-Enabling Context Guard after work has already started also shows the last reported prompt usage for idle sessions and subagents. Opening the sidebar or panel restores it from the public session context, preserving its original age and **STALE** label. Stale usage still shows tokens and occupancy percentage. Restoration respects model changes, reverts and completed compactions; unavailable provider usage stays unknown. These reads never request compaction, and transcript content is never retained or sent through the plugin RPC.
+Per-session live TPS, average model throughput, average session throughput and observed TTFT appear in panel Details, alongside explicitly labeled route-family statistics independent of selection or folded branches. Live TPS and TTFT use `~` to mark estimates; completed rates use provider totals. Configurable local history defaults to seven days with a 64 MiB total cap, independently of diagnostic telemetry. See [metric definitions and history exports](docs/configuration.md#live-performance-and-retained-history).
 
-Per-session live TPS, average model throughput, average session throughput and observed TTFT appear in the selected session and child rows. Live TPS and TTFT use `~` to mark estimates; completed rates use provider totals. Configurable local history defaults to seven days with a 64 MiB total cap, independently of diagnostic telemetry. See [metric definitions and history exports](docs/configuration.md#live-performance-and-retained-history).
+Compare models across retained sessions with `bun run inspect models /absolute/history-directory --model provider/model` (installed: `context-guard models ...`). JSON/CSV summaries include weighted request TPS, TTFT mean/median/p95, eligibility counts and coverage limits. Use `--from`, `--to` and `--agent` to scope the analysis. The standalone dashboard's Models screen shares these definitions; see [analytics definitions](docs/configuration.md#offline-model-analytics).
 
-Compare models across retained sessions with `bun run inspect models /absolute/history-directory --model provider/model` (installed: `context-guard models ...`). JSON/CSV summaries include weighted request TPS, TTFT mean/median/p95, eligibility counts and coverage limits. Use `--from`, `--to` and `--agent` to scope the analysis. This offline command precedes the planned TUI Models screen; see [analytics definitions](docs/configuration.md#offline-model-analytics).
+Press **c** in the Context Guard panel for retained-history terminal charts. View one metric at a time with **Left / Right**, change the time window with **[ / ]**, and select an agent instance with **Up / Down**. Press **c** to return to Overview or **q** to close the panel; controls and Guard status stay visible around the scrollable content. In Details, **Up / Down** scrolls instead of changing selection. **PageUp / PageDown** and **Home / End** move through family selection in Overview and scroll content in Details/Charts. Generate a self-contained interactive browser report with `bun run charts /absolute/history-directory --output report.html`. It includes filters, UTC timestamp tooltips, request statistics and SVG export. Installed packages expose the same command as `context-guard charts ...` (Bun required). See [chart controls and limits](docs/configuration.md#performance-charts).
 
-Press **c** in the Context Guard panel for retained-history terminal charts. View one metric at a time with **Left / Right**, change the time window with **[ / ]**, and select an agent instance with **Up / Down**. Press **c** to return or **q** to close the panel; controls stay visible below the scrollable content. Generate a self-contained interactive browser report with `bun run charts /absolute/history-directory --output report.html`. It includes filters, UTC timestamp tooltips, request statistics and SVG export. Installed packages expose the same command as `context-guard charts ...` (Bun required). See [chart controls and limits](docs/configuration.md#performance-charts).
+Native Charts and standalone History distinguish a missing history service, timeout, incompatible response, rejected request, and temporary failure. A failed refresh keeps matching results labeled **Showing previous results**, with their last-loaded timestamp and original range. Press **r** to retry. Native Charts pause automatic polling for disabled recording or missing/incompatible/rejected services; retry checks again. Context monitoring and Guard enforcement remain independent of chart recovery.
 
 ## Inspect
 
@@ -182,4 +196,4 @@ bun run test:live   # explicitly SKIPs without the required server environment
 
 Tests cover the core, mocked V2 events for concurrent nested subagents, restart safety, telemetry rotation, and CLI reading. [Live test instructions](docs/testing.md) describe the optional disposable-session check against an existing V2 host and a local OpenAI-compatible endpoint; no model download is required.
 
-Further reading: [API investigation](docs/reconnaissance.md), [architecture](docs/architecture.md), [Budget Controller extension](docs/budget-controller.md), [compatibility and limitations](docs/compatibility.md).
+Further reading: [API investigation](docs/reconnaissance.md), [architecture](docs/architecture.md), [Budget Controller extension](docs/budget-controller.md), [compatibility and limitations](docs/compatibility.md), and [TUI UX review](docs/plans/tui-ux-review.md). [Compact sidebar defaults](docs/plans/sidebar-density.md) (UX-07) are implemented; see the [validation record](docs/validation/sidebar-density-2026-11-06.md). [Plain-language terminology](docs/plans/plain-language-terminology.md) (UX-09) is implemented; see the [delivery record](docs/validation/plain-language-terminology-2026-11-07.md). [Chart recovery (UX-10)](docs/plans/chart-failure-recovery.md) is implemented; see the [delivery record](docs/validation/chart-failure-recovery-2026-11-07.md).