Problem
Runtime checks are spread across startup, the Linux installer, Docker helpers, settings, and error messages. Users and agents cannot run one bounded command to explain why Headless cannot start or which dependency or permission is wrong.
Split from #54 G1. The host-log checks depend on G2.
Contract
- Add an architecture decision defining checks, output schema, exit status, redaction, and offline behavior.
- Implement
headless doctor as a local CLI command that never launches a browser, changes configuration, repairs files, or contacts the network.
- Report product and protocol versions, platform, executable resolution, runtime directory safety, socket state, artifact-store safety, default host-log health, FFmpeg availability, browser availability, settings validity, and relevant sandbox constraints.
- Use structured, bounded JSON with stable check identifiers, severity, status, safe details, and actionable suggestions.
- Distinguish healthy, warning, unsupported, and failed checks. Exit nonzero only for failures that prevent supported operation.
- Never expose environment values, credentials, cookies, storage, page data, usernames embedded in URLs, or arbitrary file contents.
- Handle a running host without disrupting it and detect stale or unsafe socket state without deleting anything.
Acceptance criteria
- Healthy macOS and Linux installations return a deterministic successful report.
- Missing browser, missing FFmpeg, unsafe runtime permissions, stale socket, corrupt settings, and unavailable host logs produce the correct bounded findings.
- The command is read-only and works offline with no browser process launch.
- Unknown arguments fail closed.
- Output stays below the protocol framing budget even though the command is local.
- CLI help, command docs, shell tests, and unit tests cover happy and failure paths.
- Existing startup behavior remains unchanged.
Problem
Runtime checks are spread across startup, the Linux installer, Docker helpers, settings, and error messages. Users and agents cannot run one bounded command to explain why Headless cannot start or which dependency or permission is wrong.
Split from #54 G1. The host-log checks depend on G2.
Contract
headless doctoras a local CLI command that never launches a browser, changes configuration, repairs files, or contacts the network.Acceptance criteria