thaloco/aman
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Harden runtime diagnostics for milestone 3

Browse source 
Make the milestone 3 runtime story predictable instead of treating doctor, self-check, and startup failures as loosely related surfaces.

Split doctor and self-check into distinct read-only flows, add tri-state diagnostic status with stable IDs and next steps, and reuse that wording in CLI output, service logs, and tray-triggered diagnostics. Add non-mutating config/model probes, a make runtime-check gate, and public recovery/validation docs for the X11 GA roadmap.

Validation: make runtime-check; PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'; python3 -m py_compile src/*.py tests/*.py; PYTHONPATH=src python3 -m aman doctor --help; PYTHONPATH=src python3 -m aman self-check --help. Leave milestone 3 open in the roadmap until the manual X11 validation rows are filled.
This commit is contained in:
Thales Maciel 2026-03-12 17:41:23 -03:00
parent a3368056ff
commit ed1b59240b
No known key found for this signature in database
GPG key ID: 33112E6833C34679
16 changed files with 1298 additions and 248 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/x11-ga/03-runtime-reliability-and-diagnostics.md
View file

@ -16,7 +16,7 @@ Once Aman is installed, the next GA risk is not feature depth. It is whether the
- Define `aman doctor` as the fast preflight check for config, runtime dependencies, hotkey validity, audio device resolution, and service prerequisites.
- Define `aman self-check` as the deeper installed-system readiness check, including managed model availability, writable cache locations, and end-to-end startup prerequisites.
- Make diagnostics return actionable messages with one next step, not generic failures.
- Standardize startup and runtime error wording across CLI output, service logs, tray notifications, and docs.
- Standardize startup and runtime error wording across CLI output, service logs, tray-triggered diagnostics, and docs.
- Cover recovery paths for:
- broken config
- missing audio device
@ -57,7 +57,7 @@ Once Aman is installed, the next GA risk is not feature depth. It is whether the
## Evidence required to close
- Updated command help and docs for `doctor` and `self-check`.
- Updated command help and docs for `doctor` and `self-check`, including a public runtime recovery guide.
- Diagnostic output examples for success, warning, and failure cases.
- A release validation report covering restart, offline-start, and representative recovery scenarios.
- Manual support runbooks that use diagnostics first and verbose foreground mode second.