palyra-cli and palyra-daemon crates to ensure that both the local environment (files, permissions, configuration) and the running daemon (connectivity, model providers, vault access) are in a healthy state.
DoctorCheck Pipeline
Therun_doctor function in crates/palyra-cli/src/commands/doctor/recovery.rs orchestrates the diagnostic pipeline. It evaluates the system across several dimensions, categorized by DoctorSeverity.
Execution Modes
The pipeline operates in several modes defined byDoctorExecutionMode [crates/palyra-cli/src/commands/doctor/recovery.rs#68-74]:
- Diagnostics: A read-only assessment of the current state.
- RepairPreview: Identifies issues and simulates fixes (Dry Run).
- RepairApply: Executes recovery steps to mutate the environment into a valid state.
- Rollback: Reverts a previous
RepairApplyoperation using stored manifests.
Severity Levels
Checks are classified to determine the exit code and the necessity of repair:- Blocking: Critical failures (e.g., missing config, corrupted database) that prevent the system from functioning.
- Warning: Non-critical issues (e.g., stale temporary files, sub-optimal permissions) that should be addressed but do not halt execution.
System Diagnostic Flow
The following diagram illustrates how theDoctorCommandRequest triggers the diagnostic and recovery logic.
Doctor Execution Logic
Sources: [crates/palyra-cli/src/commands/doctor/recovery.rs#48-175](http://crates/palyra-cli/src/commands/doctor/recovery.rs#48-175), [crates/palyra-cli/src/commands/doctor.rs#8-10](http://crates/palyra-cli/src/commands/doctor.rs#8-10)
Snapshots and Diagnostics
The diagnostics system aggregates state from multiple subsystems into a unified JSON structure.Component Snapshots
Theconsole_diagnostics_handler in the daemon collects data from:
- Model Provider: Status of LLM backends and embedding providers [crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#11-15].
- Auth Runtime: Admin status and profile availability [crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#16-20].
- Browser Service: Liveness and session counts from
palyra-browserd[crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#37-37]. - Memory: Maintenance status, vacuum schedules, and retention metrics [crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#54-56].
- Access Registry: Feature flags and rollout status for the requesting principal [crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#57-60].
Safe Output via Redaction
To prevent the accidental leakage of credentials (API keys, vault secrets) in diagnostic reports, the system usesredact_console_diagnostics_value. This function recursively traverses the JSON tree and masks values identified as sensitive [crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#28-28, crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#35-35].
Sources: [crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#6-114](http://crates/palyra-daemon/src/transport/http/handlers/console/diagnostics.rs#6-114)
Recovery and Repair
When issues are detected, theDoctorRepairKind enum defines the available automated fixes [crates/palyra-cli/src/commands/doctor/recovery.rs#178-237].
Key Repair Operations
| Kind | Action |
|---|---|
InitializeMissingConfig | Generates a default palyra.toml if missing. |
NormalizeAuthRegistry | Removes or quarantines invalid keys in auth_profiles.toml. |
BackfillAccessRegistry | Reconstructs the access control JSON if corrupted. |
GenerateBrowserAuthToken | Re-syncs the shared secret between the daemon and browser service. |
RestoreConfigBackup | Reverts the configuration to a known good state from the recovery/runs directory. |
Manifests and Rollback
Every repair operation that modifies the filesystem generates aDoctorRecoveryManifest [crates/palyra-cli/src/commands/doctor/recovery.rs#141-155]. This manifest includes:
- Run ID: A unique ULID for the recovery session.
- Entries: A list of
DoctorRecoveryManifestEntryrecords containingbefore_sha256andafter_sha256hashes of changed files [crates/palyra-cli/src/commands/doctor/recovery.rs#158-169]. - Backup Paths: Locations of the original files before they were modified.
rollback_run command uses these manifests to restore the environment to the exact state prior to the repair [crates/palyra-cli/src/commands/doctor/recovery.rs#56-56].
Recovery Data Flow
Sources: [crates/palyra-cli/src/commands/doctor/recovery.rs#129-169](http://crates/palyra-cli/src/commands/doctor/recovery.rs#129-169), [crates/palyra-cli/src/commands/doctor/recovery.rs#178-237](http://crates/palyra-cli/src/commands/doctor/recovery.rs#178-237)
CLI Commands
Thepalyra doctor command provides the primary interface for diagnostics.
--strict: Treats warnings as blocking errors [crates/palyra-cli/src/commands/doctor/recovery.rs#49-49].--repair: Enables the execution ofDoctorRepairStepitems [crates/palyra-cli/src/commands/doctor/recovery.rs#51-51].--dry-run: Shows what the repair would do without modifying the disk [crates/palyra-cli/src/commands/doctor/recovery.rs#52-52].--rollback-run <ID>: Reverts the changes associated with a specific recovery Run ID [crates/palyra-cli/src/commands/doctor/recovery.rs#56-56].
[crates/palyra-cli/src/commands/doctor.rs#8-10](http://crates/palyra-cli/src/commands/doctor.rs#8-10), [crates/palyra-cli/tests/cli_parity_matrix.toml#38-46](http://crates/palyra-cli/tests/cli_parity_matrix.toml#38-46)