Repository navigation
Troubleshooting and Recovery
Start with the exact symptom and the intended installation/profile. Preserve the original claim and source while gathering evidence. Do not erase a hold or replay an uncertain GitHub write to make the display appear healthy.
| Symptom | First useful check | Next step |
|---|---|---|
| The local check fails | Read the exact failure from the accounts-free check. | Compare intended payload/manifest and native prerequisites. A modified artifact is different from a qualified clean release. |
| No issue is picked | Confirm the selected profile's enrollment and the issue's current lifecycle/dependencies. | Follow Enrollment and readiness; do not manufacture ready work or duplicate a claim. |
| Capabilities report available, but a task cannot run | Read the operation's diagnostic and exact native-host/client requirements. | Availability describes an implemented adapter, not authentication, trusted hooks, account entitlement or tested host support. |
| A service will not start or stop | Use the platform-specific status and control instructions from the same source/profile. | Resolve manager access or foreign/modified installation evidence. Never kill a surviving coordinator to bypass its ownership lock. |
| A restart reports uncertain ownership or a journal hold | Read the prior issue claim, current PR, surviving native session and source disposition. | Reconcile actual effects and resume the existing owner where verified; leave ambiguous or resumable work intact. |
| A worker exits but the issue is open | Read the issue's latest blocker, PR and operational acceptance. | An exit code is not delivery. Complete the exact next step through the existing workflow. |
| Removal is refused | Check documented idle, ownership and installation conditions. | Uninstall preserves source/state; do not delete worktrees or journals to force it through. |
The architecture explains pending scope, inherited ownership and conservative recovery. PLATFORMS.md distinguishes Linux, macOS arm64 and native Windows evidence. Windows startup is manual; Windows/Linux reboot recovery and automatic source activation are not claimed.
Include version or commit/manifest digest, OS, Python/native client versions, expected versus observed behavior and a minimal reproduction. Redact credentials, private repository contents and operational logs before posting a public issue. Follow CONTRIBUTING.md for ordinary reports and SECURITY.md for confidential vulnerabilities.
Do not publish personal paths or raw runtime state to explain a failure. Say what is unverified and retain the sensitive evidence privately.