A run is one orchestration execution. Inside it, nodes are the units of work and edges say how they relate. Nodes carry identity; the attempts at each node carry almost everything a consumer learns from.

​
Run

​
string
required
Producer-scoped stable run id.At most 200 characters.
​
ShortText
​
Timestamp
​
Timestamp
​
string
Opaque project/workspace locator for task-mix stratification (a name or hash, not necessarily a path).At most 500 characters.
​
Labels
​
Task
​
Configuration
​
Provenance
​
AcceptanceRule
​
Signal[]
Verdicts, scores and late events, each timestamped.
​
Slate
​
Preference[]
​
RunRescue
​
Receipt
​
Ext
  • run.id is REQUIRED and SHOULD stay stable when the same run is written again.
  • workspace is an opaque locator (a name or a hash), so consumers can group runs by project without learning a path.
  • The fields from task on are the observation added in 0.3.

​
Groups

A group is an optional named scope, such as a project or a phase of a run. Groups answer where work is shown; edges answer what work blocks. The two stay independent.
​
string
required
At most 200 characters.
​
ShortText
​
string
Another group id; parent edges must be acyclic.At most 200 characters.
​
Ext
  • A group’s parent MUST name an existing group (E120), and parent links MUST NOT form a cycle (E121).
  • A node’s group MUST name an existing group (E115). A node without a group belongs to the run root.

​
Nodes

A node is a unit of work whose identity does not depend on any attempt at it.
​
string
required
Stable identity independent of any attempt. Never a runtime locator such as a pane id.At most 200 characters.
​
string
required
Open set. Recommended vocabulary: impl, review, test, gate, question, docs, ship, plan, ops, task, unknown. gate marks an acceptance fan-in point. task is a generic task; unknown means the producer cannot determine a more specific kind.At most 100 characters.
​
ShortText
​
string
Optional group id; omitted means the run root.At most 200 characters.
​
string
Producer’s current projection over the node’s attempts. Recommended vocabulary: queued, working, review, blocked, done, failed, rejected, canceled, settled_unverified. Consumers learning from settled runs should trust attempt outcomes over this field.At most 100 characters.
​
Labels
​
Ext
​
string
The workflow piece id this node executes.At most 200 characters.
​
object
Present when the node is a gate.
  • A node id MUST NOT be a runtime locator, such as a terminal pane id or a process id.
  • kind is an open set. A gate is a node whose kind is gate, marking a point where acceptance is decided; it needs no separate entity.
  • state is the producer’s summary of the node’s attempts. A consumer learning from settled runs SHOULD trust attempt outcomes over node state.
  • From 0.3, vertex names the workflow piece the node executes, linking the run graph to its configuration.

​
Edges

An edge is a directed pair of node ids with a kind.
​
string
required
Source node id (the prerequisite / input / spawner / launcher / producer’s node).At most 200 characters.
​
string
required
Target node id (the dependent / gate / spawned node / launched node / consumer’s node).At most 200 characters.
​
string
default:"dep"
dep: to cannot start before from settles. fan_in: from is a member of gate to’s acceptance input set. spawn: node to was dynamically created by work on from inside the same harness (a Claude Code subagent through the Task tool). launch: work on from started node to as a separate harness session through its CLI (a Bash call running codex exec or claude -p). artifact: an attempt at from wrote the artifact named by artifact and an attempt at to later read it; from_attempt and to_attempt name the two attempts. Other values are accepted, but only dep and fan_in participate in the acyclicity rule.Recommended values (open set): dep, fan_in, spawn, launch, artifact.
​
EvidenceTier
required
How the edge is known. Required on every v0.2 edge, whoever the producer is: an edge without an evidence tier does not conform.
​
string
For kind artifact (required there): the id of the artifact that flowed along this edge. Must name an entry in artifacts.At most 200 characters.
​
string
For kind artifact (required there, optional elsewhere): the producing attempt id. Must be an attempt at node from and equal to the artifact’s producer.At most 200 characters.
​
string
For kind artifact (required there, optional elsewhere): the consuming attempt id. Must be an attempt at node to and among the artifact’s consumers.At most 200 characters.
​
ShortText
Short producer-authored note on what established the edge, e.g. Task tool_use id matched subagent meta or codex session began 3 s after codex exec in the same workspace.
​
Ext
  • from and to MUST name existing nodes (E110, E111).
  • Every edge MUST carry an evidence tier, whoever the producer is (E160). An edge read directly from a record the tool keeps is verified; one inferred from timing, text or paths is heuristic; one taken from a session’s own claim is reported.
  • dep and fan_in edges together MUST form a directed acyclic graph (E122). spawn, launch and artifact edges record observed lineage and MAY form cycles.
  • An artifact edge MUST name an existing artifact (E116, E117) and MUST carry from_attempt and to_attempt (E125). They MUST name existing attempts (E123) at the edge’s from and to nodes (E124); from_attempt MUST be the artifact’s producer and to_attempt one of its consumers (E164).
  • Edges are optional. A producer that knows only which steps ran writes nodes and attempts and adds edges when it can.

Privacy