Problem
The bootstrap hardening work in #872 makes local daemon-host access fail loudly when secrets.json contains a stale or missing DeviceToken that no longer matches any device in devices.json. That is the right security behavior, but today the operator recovery path is manual and error-prone.
Current diagnostics can detect:
- bootstrap incomplete state before first successful non-local startup
- completed bootstrap with stale or missing daemon-host local token
But there is no first-class repair tool for either case.
Goal
Add a supported repair workflow that restores daemon-host local control-plane access without forcing operators to manually edit devices.json / secrets.json, and without silently resetting all remote pairings.
Proposed scope
Implement one of:
- doctor --fix support for pairing/bootstrap repair, or
- a dedicated command like netclaw pair recover-local-access
The tool should:
- detect the broken local pairing states already surfaced by ExposureModeDoctorCheck
- repair local daemon-host access by writing devices.json and secrets.json atomically
- preserve existing remote paired devices when possible
- avoid silently regenerating bootstrap state on top of completed installs
- fail loudly when safe in-place repair is not possible
Required behavior
Case 1: bootstrap incomplete
When bootstrap has not completed and local bootstrap state is inconsistent, the tool should offer a safe reset of bootstrap artifacts so the next non-local daemon start can reseed cleanly.
Case 2: bootstrap completed, daemon-host local token stale/missing
When existing remote devices still exist but the daemon-host local token is stale or missing, the tool should create or rotate a daemon-host local paired device without wiping unrelated remote devices.
Constraints
- Do not silently delete all pairings unless the operator explicitly confirms a full reset
- Do not silently generate a fresh bootstrap token/device pair on top of completed installs
- Do not require raw-token recovery from devices.json alone, since that is impossible by design
- Prefer offline-safe repair steps when the daemon is stopped or when direct local filesystem access is available
Acceptance criteria
- operators can recover daemon-host local netclaw daemon pair / local CLI access from a detected mismatch state
- remote devices are preserved when a local-only repair is possible
- netclaw doctor remediation points to the repair command/path
- tests cover incomplete bootstrap reset and completed-install local-token repair paths
Context
This gap came out of the review/follow-up work on #872 and the related re-entrant init discussion in #455.
Problem
The bootstrap hardening work in #872 makes local daemon-host access fail loudly when secrets.json contains a stale or missing DeviceToken that no longer matches any device in devices.json. That is the right security behavior, but today the operator recovery path is manual and error-prone.
Current diagnostics can detect:
But there is no first-class repair tool for either case.
Goal
Add a supported repair workflow that restores daemon-host local control-plane access without forcing operators to manually edit devices.json / secrets.json, and without silently resetting all remote pairings.
Proposed scope
Implement one of:
The tool should:
Required behavior
Case 1: bootstrap incomplete
When bootstrap has not completed and local bootstrap state is inconsistent, the tool should offer a safe reset of bootstrap artifacts so the next non-local daemon start can reseed cleanly.
Case 2: bootstrap completed, daemon-host local token stale/missing
When existing remote devices still exist but the daemon-host local token is stale or missing, the tool should create or rotate a daemon-host local paired device without wiping unrelated remote devices.
Constraints
Acceptance criteria
Context
This gap came out of the review/follow-up work on #872 and the related re-entrant init discussion in #455.