Skip to main content
Comet Native uses multi-layer mechanisms to protect the workflow. The Hook Router determines the ownership of the write before it occurs. The Native Guard handles the write according to the stage, and the Runtime then stabilizes the state with state versions, locks, atomic file operations, and transaction protection. The recovery process is based on the status of the order placement and does not rely on the previous round of dialogue or the Agent’s self-description. These mechanisms undertake different responsibilities. Hook is suitable for preventing erroneous writes that the platform can observe. The Runtime is responsible for protecting the workflow state and file operations. The Verifier is responsible for determining whether the implementation meets the requirements. No layer can replace any other layer on its own.

​
Layered runtime protection

​
Which change a write belongs to

.comet/current-change.json uses comet.selection.v2 to record the workflow and change to which the current write belongs. It is only responsible for the current attribution and does not limit the number of active changes in the project. Hook Router determines the write attribution in the following order:
  1. Locate the Comet project based on the working directory provided by the Hook request;
  2. Read the workflow enabled by the project and the current selection;
  3. Enumerate the active changes corresponding to the workflow;
  4. After determining the unique owner, only the Guard of that owner is called.
When there is only one active change and no current selection, the Router can infer that it is the owner. When there are multiple candidates, the Router will refuse to write until a clear selection is made through comet native select <change-name>. When the selected file is damaged, the target has been archived, the workflow has been disabled, or the change status cannot be read, the Router will also stop writing. In the old version of the global Hook, if there is no trusted request working directory, it will remain neutral to avoid inferring the current change from the Hook installation directory or other items. When an anomaly is detected in the project or during the target range check, the Router will handle it as a failed shutdown.

​
Stage-aware change control

Native Guard divides the goals within the project into formal requirements, implementation files, and Runtime management files. Formal requirements and implementation files must be written separately. When a single tool call modifies two types of files simultaneously, Guard will reject the operation to prevent the sharing of a state transition that cannot be accurately attributed between requirement changes and implementation changes. During the Verify or Archive period, when it is observed that the implementation is written, RC1 will not continue to use the original candidate. The Runtime will increase the implementation rounds, clear invalid acceptance conclusions, and return to the Build. When the formal requirements change, the Runtime will return to Shape and invalidate the validation results and archiving authorizations in the old target cycle.

​
Pre-protection for observable writing

Hook Router can only handle events where the platform provides the write intent and the destination path. The following writes may not go through phase guarding:
  • The IDE or background process directly modifies the file;
  • The platform does not expose any Shell or file operations to the Hook;
  • The Hook request has no attributable target path.
  • Clarify the goals that lie outside the current project.
Therefore, Hook is an engineering protection before writing, not an operating system-level sandbox. The subsequent Runtime will still verify the status version, workspace, candidate, check and archive conditions. The Verifier will also read the actual implementation. Unexposed writes by the platform need to be detected through subsequent checks and acceptance. Comet cannot guarantee immediate interception.

​
Versioned state consistency

In comet-state.yaml, starting from 1, each stable state transition can only increase once. Before writing a new state, the Runtime compares the disk version:
  • The current version must be equal to the expected version of the operation.
  • The new version must be exactly the current version plus one.
  • Before submission, the disk state will be read again to prevent another process from modifying it first.
Commands involving user decisions will also be carried:
These two protections can reject confirmations in old conversations, late Verifier results, and expired commands. When a version conflict occurs, the correct action is to re-read the latest continuation and then perform the operations allowed by the current state.

​
Project-level concurrent mutual exclusion

The state modification, selection, migration and Archive of Native are all executed through project-level change locks. Only one controlled change operation can enter the critical section at the same time. After obtaining the lock, the Runtime will also check:
  • Is artifact root moving?
  • Whether there are uncommitted, unrolled or unidentifiable transactions;
  • Is the current operation exactly the recovery action that the transaction allows to continue?
When an unfinished transaction is detected, the new change operation will be stopped and an error that requires the transaction to be restored first will be returned. Both the lock and transaction directories are managed by the Runtime. Manual deletion may cause the file status and transaction records to lose their correspondence.

​
Path and file identity verification

RC1 employs restricted reads and atomic writes for stable files. When reading the official product, the Runtime will check:
  • A reference is a standardized relative path within a project;
  • The path has not entered a sensitive directory or the local Runtime.
  • The file is an ordinary file, and the parent directory is not a symbolic link.
  • The file size is within the corresponding upper limit, and the text is valid UTF-8.
  • It remains the same file object before opening, during reading and after reading.
  • The real path is always located in the managed root directory.
When content identity is required, the Runtime will simultaneously record SHA-256. If a file is replaced during the read process, the parent directory points to changes, or the content exceeds the upper limit, this read will fail. When writing to a stable file, the Runtime first creates an exclusive temporary file in the target directory, writes and synchronizes the content, then verifies the identity of the parent directory chain and the temporary file, and finally commits through renaming or an exclusive link. When changes are detected in the path, directory or file object during the submission process, the operation will stop and the current path will no longer be written.

​
Recoverable transactional archiving

Archive will update the canonical Spec, final status and reports, and move the active change into archive. RC1 records these actions as transactions instead of a set of unrelated file commands. The transaction will record the expected content hash and the identity of the file object. Before replacing or deleting an existing target, the Runtime will place the original content in a controlled isolation area and verify that the isolated object is still consistent with the transaction record. After an interruption, the Runtime can continue the confirmed steps based on the log. When the content, path or object identity changes, the transaction will stop. The following situations need to be handled first before continuing with the Archive:
  • Both the active and archive directories exist simultaneously.
  • The transaction log is damaged or inconsistent with the actual directory;
  • canonical Spec changes during a transaction;
  • Another active change declares the same capability in any registered Git worktree.
When there are multiple owners for the same capability, Archive requires the user to determine the serial order. The first archived change becomes the new canonical Spec. Subsequent changes need to be re-aligned and re-accepted. The Runtime will not automatically overwrite the specifications of another change.

​
Breakpoint recovery based on stable states

The authoritative state for cross-session and cross-device recovery is comet-state.yaml in the change directory. .comet/runtime/native/changes/<change-name>/state.json only records the local execution of this machine. The recovery behavior for each scene — an interrupted check, a lost Verifier task, an archive-ready result that returns to Verify, a verification.md rebuild, and so on — is described together in Recovery playbook.

​
Zero-write environment-aware recovery

comet resume-probe finds the recovery target based on the default workflow specified by .comet/config.yaml. It does not modify change, nor does it switch branches or workspaces. ambient_resume: false will disable the environment-aware recovery of ordinary requests. When explicitly entering Comet, it is still processed according to the entry command. When multiple active changes exist, the probe uses an explicit name or the current selection; When the unique owner is missing, return ask_user.

​
Unified diagnosis and recovery entry

For daily progress, only the latest continuation is executed. When troubleshooting is needed, read the status in the following order:
doctor --repair is only applicable to states that have been recognized by the Runtime and supported for recovery. When the config, YAML, transaction or directory ownership cannot be determined, it is safer to keep the on-site state than the manual splicing state. Continue reading: Task advancement and interruption recovery, Product and State and Recovery and Fault Handling .
Last modified on September 4, 2026