REACH + OCTO

Appearance

Event Vocabulary ​

A closed set of twelve types. Every event in a TRACE file is one of these — no others exist, no custom extensions.

Execution Events ​

ARM_START ​

A REACH arm begins executing. Written before dotnet run is called.

json
{
  "event_type": "ARM_START",
  "payload": {
    "arm_name": "outlook.inbox",
    "script":   "task_a3f2.cs",
    "mode":     "READ"
  }
}

ARM_COMPLETE ​

A REACH arm finishes successfully.

json
{
  "event_type": "ARM_COMPLETE",
  "payload": {
    "arm_name":        "outlook.inbox",
    "duration_ms":     1240,
    "exit_code":       0,
    "finding_summary": "3 flagged items, 1 urgent thread"
  }
}

ARM_RETRY ​

A compile or runtime error — Claude is retrying.

json
{
  "event_type": "ARM_RETRY",
  "payload": {
    "arm_name": "outlook.inbox",
    "attempt":  2,
    "reason":   "compile_error",
    "error":    "CS0246: The type 'Outlook' could not be found"
  }
}

ARM_FAIL ​

A REACH arm failed after all retry attempts.

json
{
  "event_type": "ARM_FAIL",
  "payload": {
    "arm_name":    "outlook.inbox",
    "attempts":    3,
    "final_error": "Runtime error: MAPI not available"
  }
}

An ARM_START with no matching ARM_COMPLETE or ARM_FAIL is a detectable open event — an arm that started and never closed. This is signal, not noise.

Artifact Events ​

ARTIFACT_WRITTEN ​

A .reach-artifact or other output file was written to disk.

json
{
  "event_type": "ARTIFACT_WRITTEN",
  "payload": {
    "artifact_path": "sprint-review-2026-06-16.reach-artifact",
    "artifact_type": "reach-artifact",
    "produced_by":   "sprint-review.reach",
    "size_bytes":    1842
  }
}

Human Decision Events ​

PAUSE_SURFACED ​

OCTO surfaced a decision interface to the human.

json
{
  "event_type": "PAUSE_SURFACED",
  "payload": {
    "title":   "Good morning. Here's what needs you.",
    "items":   ["Sarah emailed twice", "Planner item 3 days overdue"],
    "actions": ["draft-reply", "snooze", "show-all"]
  }
}

HUMAN_DECIDED ​

The human made a choice at the decision surface.

json
{
  "event_type": "HUMAN_DECIDED",
  "payload": {
    "action_chosen":     "draft-reply",
    "time_to_decide_ms": 14200
  }
}

ACTION_TAKEN ​

An ACT-mode reach executed following a human decision.

json
{
  "event_type": "ACTION_TAKEN",
  "payload": {
    "action":   "draft-reply",
    "target":   "outlook.draft",
    "outcome":  "Draft created — Sarah thread",
    "exit_code": 0
  }
}

Chain Events ​

CHAIN_TRIGGERED ​

The output of one arm became the input of another.

json
{
  "event_type": "CHAIN_TRIGGERED",
  "payload": {
    "from_arm": "git.commits",
    "to_arm":   "timesystem.timesheet",
    "via":      "analyze.summary"
  }
}

This is the event that gives TRACE its name — the Agentic Chain in Timestamped Record of Agentic Chain Execution.

Session Events ​

OCTO_CLOSED ​

An OCTO orchestration completed and closed.

json
{
  "event_type": "OCTO_CLOSED",
  "payload": {
    "arms_completed": 4,
    "arms_failed":    0,
    "close_tone":     "warm",
    "close_message":  "Sarah will appreciate that. One less thing before your first meeting."
  }
}

REACH_CLOSED ​

A standalone REACH execution completed.

json
{
  "event_type": "REACH_CLOSED",
  "payload": {
    "duration_ms": 3410,
    "exit_state":  "complete"
  }
}

TRACE_ANNOTATED ​

A human or Claude added a note to a past run.

json
{
  "event_type": "TRACE_ANNOTATED",
  "payload": {
    "run_id": "uuid-of-run-being-annotated",
    "note":   "This was the deploy that caused the incident — see post-mortem"
  }
}

The Writing Contract ​

Three rules. Not enforced by a validator — enforced by trust.

Write at the moment of occurrence, not at completion. ARM_START before dotnet run. PAUSE_SURFACED before the human sees anything. HUMAN_DECIDED the moment a choice is made.

Never buffer. Flush immediately. Each event is flushed as a single atomic line before the next operation begins. A crash mid-line corrupts at most one event — identifiably malformed, not silently lost.

One line, one event, always valid JSON. No pretty-printing. Each line must be parseable independently.

Next ​