Harden runtime diagnostics for milestone 3

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

View file

@ -34,6 +34,13 @@ class ProcessTimings:
total_ms: float
@dataclass(frozen=True)
class ManagedModelStatus:
status: str
path: Path
message: str
_EXAMPLE_CASES = [
{
"id": "corr-time-01",
@ -748,6 +755,32 @@ def ensure_model():
return MODEL_PATH
def probe_managed_model() -> ManagedModelStatus:
if not MODEL_PATH.exists():
return ManagedModelStatus(
status="missing",
path=MODEL_PATH,
message=f"managed editor model is not cached at {MODEL_PATH}",
)
checksum = _sha256_file(MODEL_PATH)
if checksum.casefold() != MODEL_SHA256.casefold():
return ManagedModelStatus(
status="invalid",
path=MODEL_PATH,
message=(
"managed editor model checksum mismatch "
f"(expected {MODEL_SHA256}, got {checksum})"
),
)
return ManagedModelStatus(
status="ready",
path=MODEL_PATH,
message=f"managed editor model is ready at {MODEL_PATH}",
)
def _assert_expected_model_checksum(checksum: str) -> None:
if checksum.casefold() == MODEL_SHA256.casefold():
return