# MFD Monitor Agent Completion Design

## Objective

Bring the current Go single-binary host monitoring agent into alignment with `AGENTS.md`: complete missing host status behavior, preserve cached snapshots, support Linux and Windows service lifecycle, add reporter retry/backoff, improve partial-success handling, and raise comments/tests to the repository standard.

## Current Gaps

- Package-level Go types, functions, methods, and interfaces are mostly undocumented.
- Linux collection misses CPU usage percent, process start time, and process CPU percent.
- TCP listener mapping does not clearly report permission-related partial mappings.
- Windows collector and service runtime are incomplete; current service install only shells out to `sc.exe`.
- Linux service install does not explicitly require root and does not preserve `-config` in the systemd unit.
- Reporter logs failures but has no retry or bounded backoff.
- Tests do not cover enough collector parsing, partial/error statuses, service guards, reporter retry, or HTTP edge cases.

## Architecture

Keep the existing single-process architecture and package boundaries:

- `cmd/agent`: CLI and process lifecycle.
- `config`: defaults, JSON file loading, environment overrides.
- `collector`: platform collection into `status.HostStatus`.
- `snapshot`: collector aggregation and in-memory cache.
- `httpapi`: `GET /health` and `GET /status`, cache reads only.
- `reporter`: periodic POST of the cached `HostStatus`.
- `service`: Windows/Linux service install, uninstall, start, and stop.

No historical storage, pagination, auth, UDP collection, thread lists, process handles, or trend analysis are included.

## Behavior Design

Collection remains immediate-on-start and periodic afterward. HTTP and reporter paths both read the same cached snapshot and never trigger a live scan.

Each collector writes only its own section. If one collector fails, `snapshot.Cache` records a `StatusError`, marks `agent.snapshot_status` as `partial`, and keeps successful sections.

Linux should be the first complete collection implementation:

- CPU usage percent from `/proc/stat` with a bounded sample and context cancellation.
- Process start time from `/proc/<pid>/stat`.
- Process CPU percent best-effort; if exact calculation is unavailable, keep the field stable and do not fail the process collector.
- TCP listeners from `/proc/net/tcp`, `/proc/net/tcp6`, and `/proc/<pid>/fd`; unreadable process fd data should degrade listener status to `partial`.

Windows should expose a real service runtime path without NSSM. If full Windows metric collection would require a larger dependency decision, platform files should keep unsupported subsections explicit with `partial`/`error` statuses and tests around those contracts.

## Service Design

Linux install should require root before writing `/etc/systemd/system`, render a systemd unit for the configured service name, include `agent run`, preserve `-config <path>` when supplied, run `daemon-reload`, and enable the service. Errors should include the failed operation.

Windows install/start/stop/uninstall should remain behind Windows build tags and avoid NSSM. Administrator requirements should be checked where practical.

## Reporter Design

Reporter POST payload remains exactly the `HostStatus` JSON used by `/status`. Failed reports are logged and retried once after a short delay or handled with a simple bounded backoff. Retry/backoff must respect context cancellation and never terminate the process or block the local HTTP server.

## Comments And Tests

All Go package-level types, structs, interfaces, functions, and methods need concise comments. Comments should explain behavior, side effects, units, platform assumptions, and permission-sensitive degradation.

Tests should be written before behavior changes and cover:

- Linux parser helpers for CPU, memory, process stat/status, and TCP listeners.
- Snapshot partial aggregation and timeout behavior.
- HTTP not-ready and method-not-allowed behavior.
- Reporter HTTP errors, retry/backoff, payload structure, and cancellation.
- Linux service unit rendering, root guard, and config path propagation.
- Windows build-tagged service contracts where compile-testable.

## Verification

Completion requires:

- `go test ./...` passes.
- Current Linux build passes.
- `GOOS=windows GOARCH=amd64 go test ./...` is attempted and either passes or any blocker is documented with the exact failure.
- A final audit maps each `AGENTS.md` requirement touched by this pass to code, tests, or a documented remaining platform limitation.