Run state

3 min readReferenceUpdated 2026-05-19

What you'll find here

The craik.task_run lifecycle — status values, loop phases, persistence helpers, and the executor that drives bounded fixture- compatible runs.

Inspection without transcripts.

A task run links the task request, case file, policy envelope, runner identity, optional intent lock, receipts, and final handoff. It gives later loop orchestration an inspectable record without depending on an untracked chat transcript.

Status values

Status	Meaning
pending	The run has been created but has not started side effects.
running	The run is actively moving through loop phases.
completed	The run finished the task and wrote final state.
blocked	The run stopped because required context or approval is missing.
failed	The run stopped because execution failed.
interrupted	The run stopped before completion and can be inspected for recovery.

Phase values

Phase	Meaning
plan	Build or refresh the execution plan.
act	Perform one governed action.
observe	Capture action output and receipts.
evaluate	Decide whether the goal is satisfied or blocked.
continue	Advance to another bounded iteration.
stop	Finalize receipts, handoff, and terminal status.

started_at, phase_started_at, updated_at, and ended_at capture deterministic lifecycle timing. The iteration and max_iterations fields bound the loop before the executor exits.

Persistence

LocalStore stores task runs as validated JSON under the task_runs kind and exposes typed helpers:

put_task_run

get_task_run

list_task_runs

Transition rules are enforced.

TaskRunManager creates deterministic run ids and enforces transition rules: terminal runs cannot transition again, iteration counts cannot exceed max_iterations, phase changes refresh phase_started_at, and terminal statuses set ended_at.

Execution loop

SingleAgentLoopExecutor drives fixture-compatible single-agent runs through bounded steps.

1. Check intent-lock stop conditions.
2. Verify policy for configured side effects.
3. Record denial or pass receipts.
4. Send a craik.runner_step_request to the runner boundary.
5. Capture the craik.runner_step_result as craik.run_output.
6. Advance task-run state.

Defaults are conservative.

The default deterministic loop uses plan · act · observe · evaluate. The act phase is treated as a side-effect step and requires a matching policy grant. Reaching max_iterations, a runner failure, a blocked runner result, or an intent stop condition stops the run before additional side effects.

What's next

ConceptSingle-agent execution loopThe conceptual lifecycle.GuideSingle-agent fixture loopThe deterministic smoke-test workflow.ReferenceRunner step contractsThe per-step request and result shapes.