Task progress and interruption recovery

Native writes the current progress and the next action into comet-state.yaml. After each action an Agent completes, it reads the latest continuation and continues with implementation, acceptance, or archiving. Even when a conversation is interrupted, the Agent is replaced, or the local Runtime is lost, the work can continue from the progress recorded in the file. At the milestones that matter — Shape confirmation, each acceptance round, and archive approval — Comet records the current stage and result in comet-state.yaml. That recorded progress is the recovery point; after an interruption, the work continues from the most recent one.

Whether the next step needs you

Commands such as comet native new, status, next, archive, and doctor all return continuation.v2. It describes the process status, the Agent action, and what you need to know at the same time. You do not need to read every field literally: the disposition field in continuation.v2 says which category this result belongs to, and checking it tells you whether this round needs you:

`disposition`	Meaning	What you do
`continue`	The next step is clear and the flow advances on its own	Do nothing; let Comet keep implementing, verifying, or archiving
`await-user`	You need to confirm, choose, or supply external information	Reply with a choice (for example, accept the result or revise the requirements) or supply the information as instructed
`blocked`	The workspace, state, concurrency, or execution budget prevents progress	Preserve the scene, run `comet native doctor <change-name>` as prompted, or supply the missing information
`done`	The change has finished archiving	Check the workspace wrap-up and finish this round

Except for await-user and blocked, no result needs your involvement. For these two, the Runtime returns the reason and the next choices; use doctor when a block needs diagnosis, as described later in this page. The complete field table for the same continuation.v2 is at the bottom of the page, in the “For Agents and automation” section.

Where the recovery points are stored

The state of an active change that can be carried across sessions and devices lives in the change directory and stays with the project code:

brief.md: the goal, scope, user decisions, and acceptance requirements;
specs/<capability>/spec.md: the complete target behavior after archiving;
comet-state.yaml: the stage, state version, acceptance results, Loop progress, Builder handoff, blocking causes, the last 50 execution records, and next step;
verification.md: the user-readable acceptance report generated by the Runtime.

Among these, comet-state.yaml is the authoritative state of the recovery flow, and the progress it records is the recovery point. You do not need to create checkpoint files by hand: the comet native checkpoint command has been removed. verification.md is only for reading; when it is missing or stale, it can be rebuilt from the YAML. Local execution information is stored separately in .comet/runtime/native/ and only matters on the current device:

.comet/runtime/native/
├── changes/<change-name>/state.json
├── logs/
├── locks/
└── transactions/

These files record the checks, logs, locks, and short-lived transactions running on this machine. They can be cleaned up or rebuilt, they are not a basis for cross-device synchronization, and they cannot overwrite a newer comet-state.yaml. Recovery behavior after an interruption in any stage — Shape, Build, Verify, or archive-ready — is described together in Recovery playbook.

Continue after switching devices or sessions

A new session on the same device can usually continue the current requirement directly: Comet first locates the active change, then returns the workspace and the next action. To inspect it manually, run:

comet native status <change-name> --details --json

Before switching devices, synchronize the following:

the project code and its branch or worktree;
.comet/config.yaml;
the brief.md, Specs, and comet-state.yaml in the change directory;
the generated verification.md, which can also be rebuilt on the target device.

The target device does not need .comet/runtime/native/. The Runtime checks the project root, the branch, the worktree, and the change binding. When the binding matches, it rebuilds the local execution state from the progress recorded in comet-state.yaml. When the binding does not match, the code is not synchronized, or an active/archive directory conflicts with a same-name directory, it keeps the existing files and waits for you to handle it.

How a regular change advances on its own

The main flow of a regular change is as follows:

Confirm Shape
  → Builder completes the implementation and read-only code review
  → Submit the Builder handoff
  → Runtime runs the necessary checks
  → A new read-only Verifier accepts items one by one
  → Enter Archive once everything passes
  → Finish the archive and workspace wrap-up

When the Verifier determines that some acceptance items have failed, the Runtime returns to Build and writes the unresolved acceptance items into the next step. When the requirements or acceptance criteria change, the Runtime returns to Shape and starts a new goal cycle. When an independent acceptance task lacks external information, fails repeatedly, or reaches the failure-count limit, the flow enters await-user or blocked. When the platform cannot prove to the Runtime that the Verifier executed independently of the Builder, even an all-pass Verifier result still needs your explicit acceptance. At that point you are given three mutually exclusive options:

accept the current result and prepare to archive;
keep the requirements and return to Build to revise the implementation;
revise the requirements or acceptance criteria and return to Shape.

Choose one of them; the Agent runs the command that matches your choice.

What you see when local state is abnormal

Each local state.json is tied to a change and a state_version. When the Runtime reads it, it distinguishes two situations:

State matches: continue from the progress currently recorded;
File missing, invalid, or stale: rebuild the local execution state from comet-state.yaml.

Both situations are handled by the Runtime automatically. For the recovery behavior after an interrupted check, a lost Verifier task, or an archive-ready result that lost its local execution basis, see Recovery playbook.

Stale commands are rejected

Every command that involves a user decision or a stage transition is bound to the state version and the expected action it was generated with, and the Runtime validates both before executing. Therefore, a confirmation from an old conversation, a late Verifier result, or a command that has already expired cannot be written into the new state. What you will see: the command is rejected with a message that the state version or expected action does not match. What to do: do not retry the old command. Re-read the latest continuation and continue with the new action. The paging cursor of status --details is also bound to the state version; after the state changes, an old cursor is rejected, so acceptance items, history, and workspace information from different versions are not mixed together. For the protocol-level details of how versions are written and validated, see Runtime protection and fault recovery.

Diagnosing abnormal situations

Day-to-day progress follows the latest continuation. When abnormal situations occur — Runtime files are missing or from an old version, a change needs migration, an archive or directory move was interrupted, or the state-to-workspace relationship cannot be determined — the Agent runs the read-only diagnostic command comet native doctor <change-name> to get the cause and a repair suggestion; when the continuation asks for diagnosis, it says so as well. Run with --repair only when the diagnostic result explicitly returns a safe repair action. When the state is corrupted, same-name directories conflict, or the recovery source is unclear, preserve the scene and handle the blocking cause the Runtime returned.

continuation.v2 field table (for Agents and automation)

The fields below are consumed by Agents and automation. For manual work you only need disposition from the first section.

continuation.v2 complete fields and disposition handling

Field	Purpose	How to use it
`disposition`	Says whether to continue, wait for the user, handle a block, or end	First decide whether the flow can advance automatically
`action`	Names the current action, such as confirming Shape, submitting the Builder handoff, starting the Verifier, or archiving	Execute only this one action
`commandArgs`	The complete command arguments generated by the Runtime	Keep the state-protection arguments as they are and only fill in the placeholders
`commandAlternatives`	The commands that correspond to mutually exclusive user decisions	After the user decides, choose only one of them
`inputOptions`	Describes the fields the command needs and provides a JSON template	Fill in only what the template exposes
`runnerAction`	Says whether the Agent should submit the implementation handoff, start the Verifier, wait for a result, or retry	Coordinates the Builder and the Verifier
`userCommunication`	Says whether you must be reported to and awaited this round	When `required: true`, pause the advancement

disposition has four outcomes:

Outcome	Meaning	What happens next
`continue`	The next step is clear	Execute `action`, `commandArgs`, or `runnerAction`
`await-user`	You need to confirm, choose, or supply external information	Relay what the Runtime says and wait for a reply
`blocked`	The workspace, state, concurrency, or execution budget prevents progress	Preserve the scene and handle it according to the recovery action or the `doctor` result
`done`	The change has finished archiving	Check the workspace wrap-up and then end

continue does not necessarily correspond to a Shell command. After entering Build, runnerAction may ask the Builder to finish the implementation first; after entering Verify, it may ask to start a new read-only Verifier. The Agent should read these fields together and not look only at commandArgs.

Continue reading: Products and state, Verification and repair, and Recovery playbook.

Get started

Understand Comet Native

Advanced

Practical scenarios

Task progress and interruption recovery

Whether the next step needs you

Where the recovery points are stored

Continue after switching devices or sessions

How a regular change advances on its own

What you see when local state is abnormal

Stale commands are rejected

Diagnosing abnormal situations

continuation.v2 field table (for Agents and automation)

​Whether the next step needs you

​Where the recovery points are stored

​Continue after switching devices or sessions

​How a regular change advances on its own

​What you see when local state is abnormal

​Stale commands are rejected

​Diagnosing abnormal situations

​continuation.v2 field table (for Agents and automation)

Whether the next step needs you

Where the recovery points are stored

Continue after switching devices or sessions

How a regular change advances on its own

What you see when local state is abnormal

Stale commands are rejected

Diagnosing abnormal situations

continuation.v2 field table (for Agents and automation)