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 incommand-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) |
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 |
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<string, unknown> | No | Arbitrary key-value data attached via updateRun |
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:| 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. |
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 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 tolifecycle.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
- Comet Browser — Run lifecycle — inline lifecycle section with the same states, transitions, and envelope
- Multi-Agent Browser Isolation — tab ownership enforcement, OwnershipError, and sensitive actions list