Skip to content

RUN_HISTORY.md

Latest commit

 

History

History
109 lines (74 loc) · 4.14 KB

RUN_HISTORY.md

File metadata and controls

109 lines (74 loc) · 4.14 KB
Raw

Run History Contract

This document defines the canonical run-history model in Codex Autorunner.

Source Of Truth

Use FlowStore at .codex-autorunner/flows.db as the single source of truth for flow-engine run history. This store proves what the ticket-flow engine ran; it does not by itself make a turn visible in Web Hub Chats.

  • Runs: flow_runs
  • Timeline/events: flow_events
  • Artifacts: flow_artifacts

Legacy numeric run directories are compatibility-only and must not be used for new run history features.

Web Hub chat visibility is sourced from hub orchestration records: orch_thread_targets, orch_thread_executions, bindings, delivery ledgers, and chat-surface events. A ticket-flow turn is visible only when orchestration contains a repairable flow_run_id + ticket_id -> managed_thread_id link.

Retired Run Artifacts Are Not Live History

Retirement snapshots under .codex-autorunner/archive/runs/** are reviewable retained output, not live source of truth. They exist for operator review and audit after a run completes. Do not query archive storage directories to discover which runs exist; always use FlowStore.

Run retirement snapshots are pruned by age/count/byte retention policies (see STATE_ROOTS.md and state-cleanup.md).

What Runs Exist

Use FlowStore run records:

  1. Open FlowStore for the repo.
  2. Query list_flow_runs(...) (optionally by flow_type or status).
  3. Treat each FlowRunRecord.id (string) as the canonical run id.

Primary fields:

  • id
  • flow_type
  • status
  • created_at, started_at, finished_at
  • current_step
  • metadata

What Happened In A Run

Use FlowStore events:

  1. Query get_events(run_id, ...).
  2. Sort/order by seq (monotonic per DB).
  3. Render timeline using timestamp, event_type, data, and optional step_id.

For streaming/polling use cases, use after_seq and event-type filters (get_events_by_type(s)).

Where Artifacts Live

Use FlowStore artifacts:

  1. Query get_artifacts(run_id).
  2. Resolve each artifact by kind, path, created_at, and metadata.
  3. path may be absolute or repo-relative; resolve against repo root before reading.

Artifact discovery must come from flow_artifacts first. Filesystem scanning is fallback-only for legacy compatibility paths.

Chat Mirroring Artifact Kinds

When flow-chat mirroring is enabled, flow_artifacts may include:

  • chat_inbound - points to .codex-autorunner/flows/<run_id>/chat/inbound.jsonl
  • chat_outbound - points to .codex-autorunner/flows/<run_id>/chat/outbound.jsonl

Compatibility And Deprecation

  • Legacy numeric run logs (.codex-autorunner/runs/<int>/run.log) are deprecated and not canonical for new runs.
  • Legacy run_index storage/APIs have been removed from runtime code paths.

Usage Attribution Confidence

Hub usage summaries attribute token events to repos using a two-tier matcher:

  1. Exact path match (high confidence): the event's cwd is the repo root or a subdirectory of it.
  2. Heuristic name match (low confidence): the event's cwd contains a path component matching repo-id--*, which is the conventional worktree naming pattern. This match is name-based and may misattribute usage when non-worktree directories follow the same convention.

Both matched and unmatched usage is always visible in hub summaries. The source_confidence field in each UsageSummary distinguishes the two tiers:

  • confidence: "high" — all events matched by exact path.
  • confidence: "low" — all events matched by heuristic only.
  • confidence: "mixed" — a combination of exact and heuristic matches.
  • confidence: "none" — no events.

The heuristic_events count in the confidence dict reports how many events were attributed via heuristic matching. Operators can use this to assess attribution quality and decide whether stronger bindings are needed.

Unmatched Usage

Events that match no known repo remain in the unmatched bucket rather than being silently forced into a repo attribution. This is a contract: usage reports must never silently upgrade an unmatched or heuristic-only event into an authoritative attribution.