> ## Documentation Index > Fetch the complete documentation index at: https://docs.equa.cc/llms.txt > Use this file to discover all available pages before exploring further. # Task lifecycle # Task Lifecycle (Comet Browser Runs) Every browser run managed by [Comet-Bridge](/tools/comet-browser) 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 | State | Terminal | Description | | ----------- | -------- | -------------------------------------------------------------------------- | | `pending` | No | Run created but not yet started (queued or deferred) | | `running` | No | Run started; browser session is active | | `completed` | Yes | Run finished successfully | | `aborted` | Yes | Run intentionally stopped (user cancel, timeout, operator decision) | | `failed` | Yes | Run ended with error (script failure, CDP disconnect, ownership violation) | Terminal states (`completed`, `aborted`, `failed`) allow no further transitions. ## Transitions | From | Allowed targets | | ----------- | --------------------------------------------------------------------------------- | | `pending` | `running` (start), `aborted` (cancel before start), `failed` (error before start) | | `running` | `completed` (success), `aborted` (cancel), `failed` (error) | | `completed` | None | | `aborted` | None | | `failed` | None | 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: | Field | Type | Required | Description | | ---------------- | ------------------------- | ----------------------------- | -------------------------------------------------------------------------------- | | `taskThreadId` | string | Yes | Task-thread identifier linking the run to an orchestration task | | `runId` | string | Yes | Unique run identifier (auto-generated UUID if omitted) | | `status` | enum | Yes | Current lifecycle state (`pending`, `running`, `completed`, `aborted`, `failed`) | | `startedAt` | ISO 8601 | Yes | Timestamp when the run was created | | `route` | `mcp` \| `cli` \| `http` | No | Execution channel that handled the run | | `fallbackUsed` | boolean | No | `true` when the run degraded from MCP to CLI (default `false`) | | `agentId` | string | No (required for multi-agent) | Agent identity for tab ownership (`--agent-id` or `COMET_AGENT_ID` env) | | `tabGroupId` | string | No | Chrome tab group ID when tab-group isolation is active | | `auditSessionId` | string | No | Links the run to a browser-audit session artifact | | `workflowId` | string | No | Workflow or playbook identifier | | `completedAt` | ISO 8601 | No | Set automatically when the run transitions to a terminal state | | `failureReason` | string | No | Human-readable reason when status is `aborted` or `failed` | | `metadata` | `Record` | No | Arbitrary key-value data attached via `updateRun` | The shared `lifecycle-metadata.mjs` module in Comet-Bridge ensures both MCP and CLI paths emit identical envelopes. See [Comet Browser -- MCP/CLI parity](/tools/comet-browser#mcpcli-parity) for details. ## Operations The lifecycle adapter exposes six operations: | Operation | Description | Idempotency | | --------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | **startRun** | Create and register a new run. Transitions to `running` (or `pending` if deferred). | Starting an already-running run returns the existing state. | | **updateRun** | Update metadata (auditSessionId, tabGroupId, workflowId, metadata) on a running run. Does not change state. | Only allowed when status is `running`. | | **completeRun** | Mark a run as successfully finished. Sets `completedAt`. | Completing an already-completed run is a no-op. | | **abortRun** | Mark a run as intentionally stopped. Sets `completedAt` and optional `failureReason`. | No-op from any terminal state. | | **failRun** | Mark a run as failed with a reason. Sets `completedAt` and `failureReason`. | No-op from any terminal state. | | **getRun** | Retrieve a run by ID. Returns the full lifecycle record or null. | Read-only. | 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. | Field | Type | Description | | --------- | ---------------------------- | --------------------------------------------------------------- | | `name` | `"LifecycleTransitionError"` | Error class name | | `runId` | string | The run that was targeted | | `from` | CometRunStatus | Current state of the run | | `to` | CometRunStatus | Attempted target state | | `message` | string | `"Invalid lifecycle transition for run {runId}: {from} → {to}"` | ### OwnershipError Thrown when an agent attempts a sensitive action on a tab it does not own. See [Multi-Agent Browser Isolation](/concepts/multi-agent#multi-agent-browser-isolation-comet-bridge) 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](/tools/comet-browser#audit-artifacts) for the directory structure and event format. ## See also * [Comet Browser -- Run lifecycle](/tools/comet-browser#run-lifecycle) -- inline lifecycle section with the same states, transitions, and envelope * [Multi-Agent Browser Isolation](/concepts/multi-agent#multi-agent-browser-isolation-comet-bridge) -- tab ownership enforcement, OwnershipError, and sensitive actions list