# Changelog

All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.1] - 2026-10-24

### Fixed

- Restore WSL Containers (WSLC) monitoring on WSL 3.0.3 by accepting JSON object streams, empty stats output and compact memory units alongside the older output format. No running containers now report zero usage instead of an EOF warning or unavailable metrics.
- Retry an inconsistent initial Windows host CPU sample once against the original baseline, avoiding a transient startup N/A when the next sample is valid. Persistent counter failures remain unavailable.

See the [release validation record](docs/validation/2026-10-24-v1.0.1.md) for checks and remaining publication gates.

## [1.0.0] - 2026-09-26

### Added

- First stable release with a [1.x compatibility policy](docs/compatibility.md) covering existing CLI options, JSON fields and units, and the four read-only MCP tools. No migration from the existing interfaces is required.
- Confirmed normal termination of verified primary-WSL processes in the Windows-native TUI, first shipped in the release candidate. Press `s`, select with the arrows, then `k` to review the target and `y` to confirm; `n` or Esc cancels. Python 3.9+ and pidfd support are required only for this optional action. See [scope and prerequisites](docs/process-actions.md).

### Changed

- Dim the TUI footer menu to distinguish controls from resource rows. Process-action feedback stays at normal intensity, and `--color never` remains unstyled.
- Include the rmcp 3.4 update from the release candidate without changing public MCP tools.

See the [release validation record](docs/validation/2026-09-26-v1.0.0.md) for candidate checks and their scope.

## [1.0.0-rc.1] - 2026-09-26

### Added

- Defined the [1.x compatibility policy](docs/compatibility.md) for the CLI, JSON output and read-only MCP tools. This release candidate preserves the existing interfaces and prepares the first stable release.
- Added confirmed, normal process termination in the Windows-native TUI for verified primary-WSL processes. Select a row with `s`, request termination with `k`, and confirm with `y`. The target distribution requires Python 3.9+ with pidfd support; unsupported targets fail closed. See [scope and prerequisites](docs/process-actions.md).

### Changed

- Updated the MCP dependency to rmcp 3.4 and adapted server configuration without changing the public tools.
- Release automation now supports RC tags and marks them as prereleases without replacing the latest stable release.

## [0.5.3] - 2026-09-16

### Fixed

- Improved CPU usage accuracy across Windows, WSL and containers by fixing missing Windows measurements, reducing sampling drift and removing verified WSL/container double counting. Unresolved overlap is marked `WSL*`; totals may still differ.

## [0.5.2] - 2026-09-14

### Changed

- Improved MCP onboarding for AI agents with practical Codex and GitHub Copilot CLI setup and usage examples.
- Documented multi-step diagnosis using system summary, resource listing, inspection, and hierarchy drill-down, preserving the same snapshot and observation-scoped resource IDs.
- Added an agent evaluation checklist and reusable manual test scenarios for MCP tool selection, arguments, and reasoning.
- Clarified that null environment observations do not necessarily mean zero usage and that container membership requires evidence from the returned hierarchy.
- Clarified that high memory usage alone does not prove paging, swapping, disk-I/O stalls, or memory-pressure causality.
- Improved MCP tool descriptions and guidance for snapshot reuse and safer interpretation.

This is a documentation and guidance-focused patch release. There are no MCP
protocol breaking changes, no new write/action tools, and no CLI/TUI behavior
changes intended. The MCP protocol, CLI/TUI behavior, and read-only safety model
remain compatible with v0.5.1.

## [0.5.1] - 2026-09-13

### Added

- Optional `wsltop mcp` read-only stdio server with system summary, resource listing, inspection and immediate-child tools, backed by the official Rust MCP SDK.
- Retained snapshots with opaque IDs, capture metadata, freshness/expiration rules and observation-scoped resource IDs. Pinned queries remain available during a refresh; failed collection preserves retained observations.
- MCP setup documentation and Linux/Windows protocol tests, including validation against extracted release executables.
- Target-specific cargo-binstall metadata for existing Linux and Windows GitHub release archives.

### Changed

- Installation guidance prioritizes prebuilt binaries and cargo-binstall. README examples and the live demo reflect the compact TUI introduced in v0.5.0.

### Fixed

- WSL category CPU uses a single shared-kernel observation instead of summing matched process rows, avoiding undercount during short-lived build-process churn. Process rows and one-shot JSON are unchanged.
- Container process-detail failures do not invalidate valid Docker/WSLC aggregate CPU and memory observations in MCP summaries.
- Resource lookup rejects ambiguous hierarchy parents and unknown Windows process generations; resource IDs are scoped to the original retained observation.

Existing CLI/TUI controls and one-shot JSON remain compatible. MCP adds no process
termination, container control, shell tools or network listener.

## [0.5.0] - 2026-09-12

### Added

- Default compact two-line host CPU/RAM summary, including host-wide CPU counter metrics and physical RAM in use/total, independent of row filters and CPU display scale.
- Aligned CPU/RAM history graphs with a fixed 0–100% scale, held values between results and explicit failure markers.
- Colorized Windows/WSL/WSLC/Docker observations and environment labels; help explains overlapping CPU observations and different memory definitions.
- `--header classic` for the traditional one-line header and `--color auto|always|never`, including NO_COLOR and TERM=dumb support.

### Changed

- TUI summary, resource table and single-line footer are organized into distinct areas. Footer groups view, sort, CPU scale and refresh interval alongside key hints.
- Responsive summaries use 23 history columns on wide terminals and 15 on medium terminals; below 80 columns, totals and essential controls take priority. Values and environment columns stay aligned.
- Summary and table separators share a restrained Dim style; separator width follows content rather than filling wide terminals. Wide summaries add spacing between environments.
- Help and tree presentation retain top-like simplicity, consistent environment colors and existing container child grouping.
- Windows refresh periods include query time without overlapping collection calls.

### Fixed

- Windows TUI restores the caller's exact console input/output modes on exit, including flags changed by event handling.
- CPU and RAM from one Windows collection share a history timestamp, preventing slot drift when event processing crosses an interval boundary.
- Help scroll bounds use actual word wrapping so the last lines remain reachable on narrow terminals.
- Classic mode restores its original header fields; long tree commands do not stretch the summary separator, and standalone Docker headings receive their environment color.
- Windows command timeout handling uses Job Objects and bounded output cleanup, closes a completion/timeout race, and covers Windows command-line quoting. Success-path tests tolerate slow CI process startup.

## [0.4.0] - 2026-09-06

### Added

- Windows-native execution is now supported for both the one-shot CLI and interactive TUI.
- Windows-target compile checking, native Windows test execution, and target-specific command timeout implementations as groundwork for native Windows collection.
- A mockable process-snapshot collector boundary and shared `CollectorPlan` selection for current and additional WSL distributions across one-shot and streaming collection.
- Windows-native one-shot collection with `--distro NAME`, default-distro, and running-distro primary selection.
- Windows-native interactive monitoring with independent collector scheduling, partial updates, and terminal restoration.
- Shared CPU, memory, and name sorting with `--sort cpu|memory|name` and `--sort-order asc|desc`; TUI keys `c`, `m`, `n`, and `r` update the displayed order immediately.
- Linux x86_64 and Windows x86_64 MSVC release archives with SHA-256 checksums and extracted-executable verification; release packaging can be validated without publishing a tag.

### Changed

- Linux `/proc` parsing is target-neutral and separate from local filesystem collection; `libc` is now a Unix-only dependency.
- One-shot sampling now fixes the additional WSL collector set once per sample, verifies running status before each optional capture to avoid restarting stopped distributions, and keeps optional discovery and distro failures as warnings.
- Windows-native CLI and TUI use remote WSL snapshots while preserving `source: None` for the primary distro and connecting the existing Windows, WSLC, and Docker collectors.
- CLI/JSON and TUI share `ResourceQuery` sorting and snapshot projections. Child processes remain grouped beneath their containers, with limits applied after sorting and deterministic tie-breaking.
- Memory/name tree views include idle Windows applications and processes. CPU descending remains the default; JSON fields, CPU accounting, and collector-provided memory values are preserved.

### Fixed

- Windows TUI key-release events no longer undo toggle actions such as reverse sorting and tree view.
- WSL distribution matching is case-insensitive, preventing duplicate primary collection and mismatched remote snapshots.
- Optional distro discovery no longer delays initial TUI sampling; additional distro rows remain loading until an interval delta is available.

## [0.3.0] - 2026-08-29

### Added

- Stateful, partial TUI collector updates with a 150 ms current-WSL startup warmup and independent Windows, additional-WSL, WSLC, and Docker scheduling.
- Loading/error status with last-good collector data retained across transient failures.
- `--cpu-scale core|host` for top-style per-core or Task Manager-style whole-host human-readable CPU display.
- Conservative Windows application aggregation with WebView2 ownership evidence and tree-level PID detail.
- Top-style `TIME+` cumulative CPU time for Windows, WSL, Docker, and WSLC processes, plus summed Windows application totals.

### Changed

- The default sampling and TUI refresh interval is 3000 ms, matching the calmer cadence commonly expected from Linux `top`; `--interval-ms` still overrides it.
- Docker and WSLC aggregate collection is separated from lazily requested process detail; optional collectors use a lower interactive cadence and no longer block local rows.
- The Windows host logical CPU count is cached after initial discovery instead of querying CIM for every process snapshot.
- Text and TUI output default to one fully busy logical CPU equaling 100%; internal accounting and JSON remain host-wide.
- Human-readable flat/TUI output ranks Windows applications once while flat JSON preserves PID-level compatibility; interactive metadata discovery is independently scheduled and retains last-good state.
- Resource JSON optionally includes additive `cpu_time_seconds`; unsupported container process backends retain detail rows without TIME+.
- Flat/TUI columns follow top-style process ordering: `ID/PID`, `CPU%`, memory, `TIME+`, then command.
- Single-process Windows application rows show the real PID; multi-process rows show `N PIDs` without changing JSON PID compatibility.
- Docker and WSLC process rows are enabled by default for text/TUI output; `--hide-container-processes` disables them, while flat JSON remains PID-compatible by default.

## [0.2.0] - 2026-08-24

### Added

- Docker-internal process discovery through `docker top`, independent of the invoking WSL distribution's `/proc` and PID namespace.
- WSLC-internal process discovery through `wslc.exe exec` and in-container `ps`.
- Container process CPU, PID, PPID, RSS, command, and argument metadata with Windows-host CPU normalization.
- Container-level `unattributed_cpu_percent` and `over_attributed_cpu_percent` accounting without proportional process scaling.
- Unified `--show-container-processes` and `--container-process-limit` options for optional flat Docker/WSLC process visibility.

### Changed

- Docker Desktop attribution remains an independent top-level group when no valid Docker-host/VM mapping is known; containers are no longer attached to the current WSL VM by numeric PID coincidence.
- Flat output ranks and limits containers by total container CPU, then groups CPU-sorted child processes and residual accounting directly beneath each selected container.
- Long container IDs are shortened to 12 characters in text process labels while complete native IDs remain available in JSON.
- Docker and WSLC ps-style process CPU averages are explicitly distinguished from interval-sampled `/proc` CPU measurements.

### Compatibility

- Default flat output continues to include existing container rows without internal process rows.
- Flat JSON remains a top-level resource array; process metadata is additive and opt-in.
- Tree JSON keeps existing fields and adds WSLC process attribution groups.
- `--show-docker-processes` and `--docker-process-limit` remain accepted as aliases for the unified container options.

## [0.1.0] - 2026-08-23

### Added

- Unified monitoring for Windows native processes, the current and additional running WSL distributions, WSL Containers, and Docker containers.
- Host-wide CPU normalization across all collectors.
- Resource kinds for processes, containers, infrastructure, and internal host resources.
- WSL/WSLC CPU attribution trees with clamped unattributed and sampling-skew values.
- Docker process attribution beneath container resources.
- Flat and structured tree JSON output.
- Interactive terminal UI with scrolling and display toggles.

### Changed

- CLI and TUI now share an in-process monitoring and sampling engine.
- Interactive mode honors collector, interval, limit, filtering, and initial tree options.
- Repository metadata, documentation, validation guidance, CI, and release automation for the initial release.

### Compatibility

- One-shot flat output remains the default.
- `--once` remains accepted.
- Flat JSON remains a top-level resource array.
- Raw WSL host rows remain hidden by default and available through `--show-wsl-host`.

[Unreleased]: https://github.com/adachi6k/wsltop/compare/v1.0.1...HEAD
[1.0.1]: https://github.com/adachi6k/wsltop/compare/v1.0.0...v1.0.1
[1.0.0]: https://github.com/adachi6k/wsltop/compare/v0.5.3...v1.0.0
[1.0.0-rc.1]: https://github.com/adachi6k/wsltop/compare/v0.5.3...v1.0.0-rc.1
[0.5.3]: https://github.com/adachi6k/wsltop/compare/v0.5.2...v0.5.3
[0.5.2]: https://github.com/adachi6k/wsltop/compare/v0.5.1...v0.5.2
[0.5.1]: https://github.com/adachi6k/wsltop/compare/v0.5.0...v0.5.1
[0.5.0]: https://github.com/adachi6k/wsltop/compare/v0.4.0...v0.5.0
[0.4.0]: https://github.com/adachi6k/wsltop/compare/v0.3.0...v0.4.0
[0.3.0]: https://github.com/adachi6k/wsltop/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/adachi6k/wsltop/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/adachi6k/wsltop/releases/tag/v0.1.0