Skip to main content

​
Task Lifecycle (Comet Browser Runs)

Every browser run managed by Comet-Bridge follows a strict lifecycle state machine. The lifecycle tracks run identity, status transitions, audit linkage, and execution metadata from creation through terminal completion. The authoritative lifecycle store lives in command-center-so. Comet-Bridge emits lifecycle events and run metadata to that authority during execution.

​
States

Terminal states (completed, aborted, failed) allow no further transitions.

​
Transitions

Attempting an invalid transition (e.g. completed to running) throws a LifecycleTransitionError with the run ID, source state, and target state.

​
Lifecycle envelope

Each run produces a 13-field metadata envelope shared by both MCP and CLI execution paths: The shared lifecycle-metadata.mjs module in Comet-Bridge ensures both MCP and CLI paths emit identical envelopes. See Comet Browser — MCP/CLI parity for details.

​
Operations

The lifecycle adapter exposes six operations: Additional query: getRunsByTaskThread returns all runs linked to a given task-thread ID (cache + disk scan). isValidTransition checks whether a transition would succeed without performing it.

​
Error types

​
LifecycleTransitionError

Thrown when an invalid state transition is attempted.

​
OwnershipError

Thrown when an agent attempts a sensitive action on a tab it does not own. See Multi-Agent Browser Isolation for the full ownership enforcement model and error fields.

​
Persistence

The lifecycle store uses an in-memory cache backed by atomic JSON file writes. Each run is stored as {runId}.json under src/data/comet-runs/. File writes use a tmp-rename pattern to prevent partial writes. In read-only environments (Railway, Vercel), persistence is disabled and the store operates in memory only.

​
Audit linkage

Lifecycle events are also recorded in browser-audit sessions. Each audit session can write lifecycle transitions to lifecycle.jsonl within the session directory, linking the runId and auditSessionId fields. See Comet Browser — Audit artifacts for the directory structure and event format.

​
See also