Native recovers from project configuration, formal artifacts, and Runtime state, not conversation history. After an interruption or error, start with read-only diagnostics, then run the specific recovery action returned by Runtime. Do not bypass checks by editing phases, hashes, journals, or selection manually.
Standard diagnostic sequence
Check in this order:
- Confirm the enabled workflows,
native.artifact_root, and native.clarification_mode in .comet/config.yaml.
- Check whether
comet native status can see the target change.
- Confirm
.comet/current-change.json selects the correct workflow and change.
- Read the phase, findings, checkpoint, acceptance page, and continuation from
status --details.
- Check whether doctor reports an interrupted transaction, stale lock, workspace identity problem, or evidence-retention issue.
When findings are truncated, handle the returned items and then read details again. When acceptancePage.nextCursor is non-null, retrieve every page with --acceptance-cursor; do not assume acceptance items outside the current page do not exist.
A change is missing on another device
Native discovers changes only under the configured artifact root. If you synced docs/comet/changes/... but the other device lacks .comet/config.yaml, still points to ., or enables another default workflow, resume-probe correctly returns that there is no resumable change. A change’s comet-state.yaml does not select the project root in reverse.
To recover:
- Confirm the actual synced directory, such as
docs/comet/changes/<name>.
- On the target device, run
comet init --workflow native --root docs to restore matching project configuration and managed assets, or restore a trusted .comet/config.yaml.
- Run
comet native status and show.
- Once the target is unambiguous, run
comet native select <change-name>.
- Continue from
/comet or /comet-native.
Do not create a second change for the same requirement or copy artifacts into another root to create two writable states.
Interrupted transition
An ordinary phase transition writes runtime/transition.json before updating Run state, comet-state.yaml, trajectory, and checkpoint. After interruption, status and doctor report that recovery is required.
Ordinary transitions support continuation only:
If the journal is malformed or Runtime cannot prove the two sides of state are consistent, it preserves the files and stops. Back up the state and inspect the error instead of assembling state manually.
Interrupted Archive or root move
Archive and artifact root moves are multi-step transactions. Doctor reports whether the current journal stage supports continue or rollback:
After Archive writes its final completion marker, it has crossed the irreversible boundary and can only continue to completion. A root move continues or rolls back only when Runtime can prove the identities and hashes of the source, staging, destination, and quarantine. When two trees differ, it does not delete either one arbitrarily.
If .comet/config.yaml contains native.pending_root_move, run doctor first. Do not delete the field or move the directories manually.
Baseline or verification evidence problems
Locks and evidence retention
Ordinary new, next, archive, and root move commands do not take over a lock merely because it appears old. Only explicit doctor --repair may take it over after proving that the local owner no longer exists, lock identity is unchanged, and no conflicting transaction is active. Active locks and locks with an unprovable owner remain untouched.
Evidence retention reports candidates by default. Explicit repair removes only derived evidence from active changes that is at least 30 days old, lies outside the latest 32 files of each evidence kind, and is proven unreferenced through the dependency closure. Archived evidence, current references, unknown files, and in-progress recovery transactions remain untouched.
Save a snapshot before state changes
If an audit or handoff requires the Runtime response from before a transition, use machine-readable mode on the first call before state changes and redirect stdout directly to the destination:
After confirming that the file is complete, do not reconstruct or overwrite it after the transition. The snapshot proves only what Runtime returned when it was generated; it does not represent later state.
Continue with Continuation and checkpoints, Native safety and recovery, and Native CLI. Last modified on July 22, 2026
