feat(cli): add read-only doctor diagnostics

apps/headless/Sources/HeadlessCLI/main.swift

@@ -449,6 +449,10 @@ do {
                 "supported": .bool(true), "transport": .string("native-webkit"),
             ]))
             #endif
+        case .doctor:
+            let report = try HeadlessDoctor().run()
+            printJSON(report.document)
+            if report.hasFailures { exit(69) }
         case .start(let presentation, let allowlist, let supervised):
             let launch = try HostLauncher().start(
                 presentation: presentation, allowlist: allowlist, supervised: supervised

apps/headless/Sources/HeadlessProtocol/Artifacts.swift

@@ -28,25 +28,30 @@ public final class ArtifactStore: @unchecked Sendable {
     private let lock = NSLock()
 
     public init(environment: [String: String] = ProcessInfo.processInfo.environment) throws {
+        rootURL = try Self.resolvedRootURL(environment: environment, platform: .current)
+        try prepareRoot()
+    }
+
+    public static func resolvedRootURL(
+        environment: [String: String], platform: SettingPlatform = .current
+    ) throws -> URL {
         if let override = environment["HEADLESS_ARTIFACT_DIR"] {
             guard override.hasPrefix("/") else { throw ArtifactError.invalidRoot }
-            rootURL = URL(fileURLWithPath: override, isDirectory: true).standardizedFileURL
+            return URL(fileURLWithPath: override, isDirectory: true).standardizedFileURL
         } else {
-            #if os(macOS)
-            rootURL = FileManager.default.homeDirectoryForCurrentUser
+            if platform == .macOS {
+                return FileManager.default.homeDirectoryForCurrentUser
                 .appendingPathComponent("Library/Application Support/Headless/Artifacts", isDirectory: true)
-            #else
+            }
             let base: URL
             if let stateHome = environment["XDG_STATE_HOME"], stateHome.hasPrefix("/") {
                 base = URL(fileURLWithPath: stateHome, isDirectory: true)
             } else {
                 base = FileManager.default.homeDirectoryForCurrentUser
                     .appendingPathComponent(".local/state", isDirectory: true)
             }
-            rootURL = base.appendingPathComponent("headless/artifacts", isDirectory: true)
-            #endif
+            return base.appendingPathComponent("headless/artifacts", isDirectory: true)
         }
-        try prepareRoot()
     }
 
     public func reserve(

apps/headless/Sources/HeadlessProtocol/CLI.swift

@@ -19,6 +19,7 @@ public enum LocalCommand: Equatable, Sendable {
     case capabilities
     case schema
     case runtime
+    case doctor
     case start(
         presentation: AgentStartupPresentation?, allowlist: NavigationAllowlist,
         supervised: Bool
@@ -102,6 +103,10 @@ public struct CLIParser {
         case "runtime":
             try requireEmpty(arguments)
             return CLIInvocation(local: .runtime, jsonOutput: true)
+        case "doctor":
+            guard session == nil else { throw CLIParseError.invalidOption("--session") }
+            try requireEmpty(arguments)
+            return CLIInvocation(local: .doctor, jsonOutput: true)
         case "start":
             return try parseStart(arguments, jsonOutput: jsonOutput)
         case "config":
@@ -816,7 +821,7 @@ Core workflow:
 
 Commands:
   version | --version
-  start [--background|--foreground] [--allow PATTERN]... [--supervised] | status | stop | runtime
+  start [--background|--foreground] [--allow PATTERN]... [--supervised] | status | stop | runtime | doctor
   profile clear
   config list | config describe KEY | config get KEY
   config set KEY VALUE | config reset KEY

apps/headless/Sources/HeadlessProtocol/ChromiumRuntime.swift

@@ -164,6 +164,12 @@ public struct ChromiumRuntimeResolver {
         return candidates.filter { seen.insert($0).inserted }
     }
 
+    public static func defaultCandidatePaths(
+        environment: [String: String] = ProcessInfo.processInfo.environment
+    ) -> [String] {
+        defaultSystemCandidates(environment: environment)
+    }
+
     private static func isSnapPath(_ path: String) -> Bool {
         let standardized = URL(fileURLWithPath: path).standardizedFileURL.path
         return standardized == "/usr/bin/snap"