reflect_archive

Category: reflection
Access: write
Audience: advanced (ordinary users do not normally call this directly)

Purpose

Archives a terminal run. Call it to retire completed, failed, or canceled runs from default history listings.

Arguments

Required: run_id.

run_id.

Result

Object with run_id, archived_at, and newly_archived flag.

Boundaries

Run access follows the input-project gate: foreign or unfiltered runs read as not-found for non-star callers.

Lifecycle / side effects

Stamps archived_at on a terminal run; history stays listed by default until include_archived filtering hides it. Idempotent: re-archiving reports newly_archived false with the same stamp.

Errors

Unknown, discarded, or foreign runs fail as run_not_found. Pending or running runs fail as cannot_archive_active_run. Shapes are normal invalid_state_transition payloads.

Example

{
  "run_id": "<uuid>"
}

Result shape:

{
  "archived_at": "<iso-8601>",
  "newly_archived": true,
  "run_id": "<uuid>"
}