Events

Orcho writes lifecycle events to events.jsonl.

events.jsonl is the append-only run timeline. CLI output is one presentation of that timeline. Headless consumers such as MCP clients, dashboards, SDK readers, and reconnecting tools should read events and persisted artifacts instead of scraping terminal text.

Record shape

Each line is one JSON object:

{
  "seq": 12,
  "ts": "2026-06-29T14:27:18.123",
  "kind": "phase.end",
  "phase": "review_changes",
  "payload": {
    "title": "REVIEW_CHANGES",
    "outcome": "rejected"
  }
}

Top-level fields:

Field	Meaning
`seq`	Monotonic sequence number within the run event stream.
`ts`	Timestamp written by the event store.
`kind`	Stable event kind string such as `run.start` or `gate.end`.
`phase`	Active phase tag when known; `null` when not phase-scoped.
`payload`	Event-specific data. Required keys depend on `kind`.

The run id is normally the containing run directory or the status/evidence context that pointed the consumer at this file. It is not repeated as a top-level field on every event line.

Required payload keys are a lower bound, not the complete schema. Extra fields are allowed. Unknown event kinds are accepted so plugin authors can emit advisory events without patching core first.

Examples

Run lifecycle

{
  "seq": 1,
  "ts": "2026-06-29T14:27:00.000",
  "kind": "run.start",
  "phase": null,
  "payload": {
    "task": "Add validation to the login endpoint",
    "run_kind": "single_project",
    "project": "/repo/app",
    "profile": "feature"
  }
}

Use run.start and run.end to open and close the run lifecycle.

Phase progress

{
  "seq": 8,
  "ts": "2026-06-29T14:27:10.000",
  "kind": "phase.start",
  "phase": "implement",
  "payload": {
    "title": "IMPLEMENT"
  }
}

Use phase.start and phase.end to render progress rows.

Gate verdict

{
  "seq": 31,
  "ts": "2026-06-29T14:29:42.000",
  "kind": "gate.end",
  "phase": "review_changes",
  "payload": {
    "name": "review_changes",
    "outcome": "rejected",
    "duration_s": 42.4
  }
}

Use gate.start, gate.end, and phase-specific verdict events such as validate_plan.verdict or cross_final_acceptance.verdict to update decision chips.

Artifact emitted

{
  "seq": 44,
  "ts": "2026-06-29T14:30:05.000",
  "kind": "artifact.created",
  "phase": "final_acceptance",
  "payload": {
    "path": "review.json",
    "artifact_kind": "review"
  }
}

Use artifact.created to learn that a durable file exists. Read the artifact itself for the full content.

Handoff or recovery signal

{
  "seq": 52,
  "ts": "2026-06-29T14:30:40.000",
  "kind": "phase.handoff_requested",
  "phase": "validate_plan",
  "payload": {
    "phase": "validate_plan",
    "handoff_type": "operator_decision",
    "trigger": "plan_rejected",
    "round": 2,
    "handoff_id": "handoff_20260629_143040"
  }
}

Use phase.handoff_requested for pause/resume UX. Do not infer handoff state from terminal banners.

Common event families

Family	Examples	Use
Run lifecycle	`run.start`, `run.end`	Open and close a run.
Phase lifecycle	`phase.start`, `phase.end`	Render phase progress.
Agent runtime	`agent.start`, `agent.tool_use`, `agent.summary`	Show runtime activity and usage.
Typed contracts	`agent.contract_ready`, `plan.parsed`	Know that structured output was produced and parsed.
Gates	`gate.start`, `gate.end`, `validate_plan.verdict`	Update approval/rejection state.
Handoffs	`phase.handoff_requested`	Pause and resume safely.
Cross-project	`cross_validate_plan.verdict`, `cross_final_acceptance.verdict`, `cross.delivery.*`	Observe cross-project planning, release gate, and delivery.
Subtask DAG	`subtask.start`, `subtask.end`, `subtask.receipt`	Render compact DAG implementation progress.
Artifacts	`artifact.created`	Locate durable files.

The canonical registry lives in orcho-core/docs/reference/event_registry.md and the event vocabulary in core/observability/event_kinds.py.

Events, evidence, notifications

These surfaces answer different questions.

Surface	Question	Rule
Events	What happened, in what order?	Durable progress facts.
Evidence	Why is this run ready or blocked?	Proof and delivery explanation.
Notifications	How does a client learn faster?	Delivery channel, not source of truth.

If an observer disconnects, it should resume from durable state. It should not ask the running process to remember what the observer missed.

MCP usage

For MCP clients:

Use orcho_run_status for current state and run id.
Use orcho_run_events_tail for live progress.
Use orcho_run_evidence for proof and final explanation.
Use orcho_run_diagnose when the run stops unexpectedly.
Use delivery or handoff tools only after the typed state says a decision is required.

Use events for progress. Use status for state. Use evidence for readiness.

Compatibility policy

Event kind strings are wire shape. Do not rename an existing event kind without a migration plan. Adding optional payload fields is compatible. Adding a new required key to an existing event is a breaking change for consumers that validate payloads.

Observe through MCP explains the client observation loop.
MCP control surface lists typed lifecycle tools.
Evidence bundle explains proof artifacts.
Artifacts lists common files written by a run.