Skip to main content
Native will automatically resume most interrupts. It retains the provable requirements, implementation progress and acceptance results in the warehouse, and only re-executes the lost native processes or verification evidence. You can directly continue with the original Change. The Runtime will read the current state, check the working directory, and return to a safe next step. The recovery basis comes from the project documents. brief.md, target Specs, comet-state.yaml and verification.md record the contents that have been confirmed and completed for the task; .comet/runtime/native/ saves the execution process on the current device and can be rebuilt when needed.

​
Automatic recovery mechanism

Each time the Change continues, Native will compare the repository status with the local execution record:
  1. Find the actual branch or worktree where the Change is located;
  2. Read the most recent complete write of comet-state.yaml;
  3. Check whether the running task, test or Verifier has been interrupted;
  4. Rebuild the missing or expired local execution records;
  5. Proceed to the current stage based on the existing evidence or return to the position that requires re-verification.
When the Native records of Shape and Build are lost, Native will continue in the original stage, and the confirmed requirements and acceptance items remain unchanged. Verify or Archive relies on local execution evidence. When relevant records are lost, the current implementation will be re-verified.

​
Session interruption recovery

After the terminal is closed, the Agent session ends, or a process exits unexpectedly, Native will mark the still-running native tasks as interrupts and then determine which steps can be safely retried. Revalidation caused by recovery is included in the execution of recovery, and the counts of implementation failure and continuous no progress remain unchanged. When a new Verifier is actually started, the number of Verifier attempts will increase normally.

​
Continue across devices

Before changing the equipment, please synchronize the following contents first
  • Project code;
  • brief.md, target Specs and comet-state.yaml in Change;
  • The generated verification.md;
  • When using the custom product catalog, the corresponding .comet/config.yaml.
After the new device opens the same repository, Native will reconstruct the local execution records based on these files. Old processes, Agent sessions and Subagent tasks remain on the original device. The new device creates new execution tasks from the verifiable state in the warehouse. The completed Shape and Build will be retained. When Change is verifying or has already waited for Archive, the new device will re-verify the synchronized code. During the recovery period, the number of acceptance failures, the number of implementation failures, and the count of no progress remain unchanged. Code that has not been synchronized on old devices cannot be restored from the Change state. When the synchronized implementation does not satisfy acceptance items, the new Verifier will point out the unmet parts and return the Change to Build.

​
Workspace restoration

Native will scan the worktree registered by Git and give priority to the working directory that is bound to the Change branch. Even if you start from the main directory of the repository, the Runtime can find the actual location of the Change and allow the Agent to continue in that directory. When the current branch, worktree type, or project root does not match the Change record, the Runtime will pause the write and return to the expected directory. When the original directory still exists, the Agent will switch to the correct location. When worktree has been removed but the branch is still valid, Native can rebuild worktree. The following situations require you to confirm the workspace:
  • The original branch has been renamed or taken over by other work.
  • There are multiple working directories that match exactly.
  • The original directory and branch have been lost.
  • The same “Change” status appears in different versions at two locations.
You can choose a trusted directory, restore from a backup, or stop the Change. The Runtime will retain the existing files and wait for a clear decision.

​
Archive transaction recovery

Archive will update the official Spec, final status and verification report in sequence, and then move the Change into the archive directory. Runtime uses transactions to record each step, so when a process exits halfway, it can resume from a completed step. When continuing with the same Archive again, Native will check the transaction and the actual file:
  • When the transaction is consistent with the file, proceed from the next step.
  • When the Change has been archived and the workspace closure fails, retain the archived result and return to the Git recovery action.
  • When both the active and archive directories exist simultaneously, retain the contents on both sides and wait for diagnosis.
  • When multiple changes modify the same Spec, wait for you to determine the archiving sequence.
The failure to wrap up the workspace occurred after Archive. Change might have completed the archiving or Git commit. At this point, check the actual Git status according to the returned recoveryArgs, and then continue with the merge, push or PR process.

​
Verification report restoration

verification.md is a readable projection of comet-state.yaml. When the report is missing, the write is interrupted, or the version is outdated, Native will regenerate the report based on the current state. When the report file is lost but the status and local execution records can still prove that the verification has been passed, the recovery only involves rebuilding the report. When the local execution records before archiving are also lost, Native will return “Verify” to re-obtain complete acceptance evidence. This distinction can preserve proven results while ensuring that the Archive uses reliable evidence on current devices and current code.

​
Situations that require user handling

Native will pause when it automatically determines that it may cause error overwriting, duplicate side effects, or incorrect archiving. Common situations are as follows: await-user indicates that your choice is needed for the next step. blocked indicates that the current status lacks a safe advancement path. The Runtime will simultaneously return the cause, the party responsible for handling, and the actions allowed to be executed.

​
Status viewing and diagnosis

Normal recovery is automatically completed by Native. When you want to view the current record or troubleshoot blockages, you can run:
show and status showcase the official products, work areas, acceptance progress and next steps. doctor checks migration, transaction, directory and state consistency. doctor --repair is only used in cases where the diagnostic results clearly provide repair actions. During the recovery process, let the Runtime manage comet-state.yaml, local execution records, locks, and transactions. Continuing according to the actions returned by continuation, recoveryArgs or doctor can preserve the confirmed progress and the fault scene. Continue reading: Task advancement and interruption recovery, Native Security Boundary , Multi-Change Parallelism and Conflict Control and Product and State .
Last modified on September 4, 2026