Run file reference

Each run keeps a working copy of its workflow at run-<timestamp>/workflow.ctrlyoke.json. ctrlyoke adds the fields on this page to that copy while the run executes. The dashboard uses them to restore a run's state, and they help when you debug a run.

These fields are written by ctrlyoke. Do not author them in your own workflow files. For the fields you write yourself, see the workflow schema reference.

Where run files live

By default, run history lives under ~/.ctrlyoke/projects/<project>-<hash>/.runs/. The storage.runHistoryLocation setting can move it to .ctrlyoke/.runs/ inside the workspace instead. To keep user-scope run history somewhere other than ~/.ctrlyoke, set the CTRLYOKE_HOME environment variable. Your user settings.json stays in ~/.ctrlyoke either way. Each workflow gets its own folder under .runs/:

Path	Contents
`workflow.json`	The workflow's history entry: name, favorite flag, latest run, and next run number.
`runner.json`	Present only while a run executes. It names the run and the process that owns it.
`draft/workflow.ctrlyoke.json`	The workflow definition before its first run.
`run-<timestamp>/workflow.ctrlyoke.json`	The run's working copy, described on this page.
`run-<timestamp>/manifest.json`	Run summary: state, timestamps, step count, and token totals.
`run-<timestamp>/events.jsonl`	The run's event log, one JSON event per line. AI responses and script output are stored here, not in the working copy.

ctrlyoke treats a runner.json lock as stale, and reclaims it, when its owning process has exited or its heartbeat has been silent for 30 seconds. Deleting it by hand is only needed when two synced machines share one run-history folder.

Section	Purpose
Run file root	Root fields present only in a run's working copy.
Workflow runtime	Workflow-level runtime execution state for working files (optional, added automatically by ctrlyoke during execution).
Step runtime	Per-prompt runtime execution metadata (optional, added automatically during execution).
Parallel group topology	Normalized working-file topology for one authored parallel group.
Condition evaluation	Latest script-condition evaluation retained for the automation result projection (written automatically during execution).
Token totals	Run-scoped token aggregate projected from timeline history.
Harness token totals	Per-harness token subtotal within a run aggregate.

Run file root

Root fields present only in a run's working copy.

`parallelGroups`

Type: array of Parallel group topology

Normalized working-file topology for authored parallel groups.

`startedAt`

Type: number

Timestamp when workflow started (working files only)

`definitionRevision`

Type: integer
Constraints: minimum 1

Monotonic optimistic-concurrency counter, bumped on every definition-changing edit and not on runtime-only writes. Starts at 1; each promoted run restarts its own sequence at 1 (working files only).

`_runtime`

Type: Workflow runtime

Workflow runtime

Workflow-level runtime execution state for working files (optional, added automatically by ctrlyoke during execution). Its schemaVersion tracks run-file metadata independently of the root schemaVersion, which tracks the workflow-definition format.

`schemaVersion`

Type: number

Run-file format version for _runtime metadata and run bookkeeping, stamped on every write. It is independent of the root schemaVersion, which versions the workflow definition format. A file written by a newer ctrlyoke is refused rather than overwritten.

`lastActivityAt`

Type: number

Latest persisted activity for the run, including an appended step that has not started yet.

`currentIndex`

Type: number
Required: yes

Index of currently executing prompt (0-based)

`executionState`

Type: "idle" | "running" | "paused" | "stopped" | "cancelling" | "completed" | "error"
Required: yes

Current execution state

`startTime`

Type: number

Wall-clock timestamp when active workflow execution timing began

`pausedTime`

Type: number

Wall-clock timestamp when the current pause began

`totalPausedDuration`

Type: number

Accumulated time spent paused before the current pause, in milliseconds

`executionEndTime`

Type: number

Wall-clock timestamp when workflow execution reached a terminal state

`activeParallelGroup`

Type: { groupId, admission }

Durable admission state for the currently executing parallel group

Fields:

groupId · string · required
admission · "accepting" | "closing" · required

`tokenTotals`

Type: Token totals

Latest run-scoped token aggregate projected from timeline history (working files only, written automatically during execution)

`pendingRewind`

Type: { fromStepIndex, baseDefinitionRevision }

Durable marker for an in-place, nonzero rewind. The full pre-rewind file is kept beside the run until the continuation is committed or discarded.

`pendingRewind.fromStepIndex`

Type: number
Required: yes

0-based index of the first rewound step

`pendingRewind.baseDefinitionRevision`

Type: number
Required: yes

Definition revision the rewind was taken from

`worktree`

Type: { schemaVersion: 1, mode, origin, … }

Disk-authoritative lifecycle metadata for a worktree-backed run. Distinct from the authored root worktree setting: this records the checkout the run actually used.

`worktree.schemaVersion`

Type: 1
Required: yes

`worktree.mode`

Type: "managed" | "named"
Required: yes

`worktree.origin`

Type: "created" | "discovered" | "recovered"
Required: yes

Whether ctrlyoke created the worktree, found it already present, or recovered it after an interrupted run

`worktree.branchName`

Type: string
Required: yes

`worktree.worktreePath`

Type: string
Required: yes

`worktree.executionRoot`

Type: string
Required: yes

`worktree.executionCheckoutRoot`

Type: string
Required: yes

`worktree.sourceCheckoutRoot`

Type: string
Required: yes

`worktree.namedWorkspaceRoots`

Type: array of { name, fsPath }
Required: yes

Fields:

name · string · required
fsPath · string · required

`worktree.baseCommit`

Type: string
Required: yes

`worktree.comparisonBaseLabel`

Type: string

Recorded comparison base used for named-branch divergence, when known

`worktree.comparisonBaseCommit`

Type: string

`worktree.changedFileCount`

Type: number

Number of files in the landed branch diff from baseCommit, when known

`worktree.dirty`

Type: boolean

Whether the named checkout had uncommitted changes at run start

`worktree.sourceCheckoutDirty`

Type: boolean

Whether source checkout changes existed when the managed worktree was created

`worktree.targetBranch`

Type: string

`worktree.lifecycleOwner`

Type: "ctrlyoke" | "user"
Required: yes

`worktree.lifecycleState`

Type: "provisioning" | "ready" | "finalizing" | "settled" | "blocked" | "orphaned"
Required: yes

`worktree.setupOutcome`

Type: "pending" | "running" | "succeeded" | "failed"

`worktree.landingOutcome`

Type: "landed" | "no-changes" | "blocked"

`worktree.mergeOutcome`

Type: "fast-forward" | "merge-commit" | "conflict" | "blocked" | "abort-failed"

`worktree.directoryState`

Type: "present" | "removed" | "missing" | "remove-failed"
Required: yes

`worktree.branchState`

Type: "present" | "deleted" | "missing"
Required: yes

`worktree.finalBranchTip`

Type: string

`worktree.conflictFiles`

Type: string[]

`worktree.message`

Type: string

`worktree.updatedAt`

Type: number
Required: yes

`worktreeNotice`

Type: string

Durable notice recorded when an inherited worktree default degraded to ordinary execution

`finalStep`

Type: { phase, loopCount, status?, … }

Runtime metadata for final step execution state (optional, added automatically during execution)

`finalStep.phase`

Type: "queue" | "finalStep"
Required: yes

Current workflow execution phase

`finalStep.loopCount`

Type: number
Required: yes

0-based final step execution loop count

`finalStep.status`

Type: "pending" | "sent" | "running" | "completed" | "failed" | "cancelled" | "skipped"

Current final step status

`finalStep.startedAt`

Type: number

Timestamp when final step execution started

`finalStep.completedAt`

Type: number

Timestamp when final step execution completed

`finalStep.preCondition`

Type: Condition evaluation

Latest pre-condition evaluation retained for the final step's automation result projection

`finalStep.endCondition`

Type: Condition evaluation

Latest end-condition evaluation retained for the final step's automation result projection

Step runtime

Per-prompt runtime execution metadata (optional, added automatically during execution). Execution-property fields record the values the step actually ran with after inheritance, including the session ID the harness reported; secrets are recorded by name only, never by value. The step's response text is not stored here — the run's events.jsonl is the only record of step output.

Also includes every field from Execution properties.

`startedAt`

Type: number

Timestamp when the executor claimed this step for dispatch

`stepId`

Type: string

Stable internal identity for this queue step within its run

`completedAt`

Type: number

Timestamp when this prompt completed execution (set for all terminal states, not just successful completion)

`terminalStatus`

Type: "completed" | "cancelled" | "failed" | "skipped"

Terminal state of this prompt. Absent or 'completed' means successful completion. Used to restore the correct visual status after a working file reload.

`retryCount`

Type: number

Number of retry attempts for this prompt

`elapsed`

Type: number

Completed prompt duration in seconds

`contextWindowUsed`

Type: number

Context window tokens in use, captured from the last completed output

`contextWindowSize`

Type: number

Context window size in tokens, captured from the last completed output

`failureKind`

Type: "userCancelled" | "processExit" | "harnessError" | "timeout" | "unknown"

Structured classification of the last harness/session failure for this prompt.

`failureMessage`

Type: string

Human-readable message describing the last harness/session failure.

`terminalFailure`

Type: boolean

Whether a failed member remains terminal for its parallel group. False when a per-step continue policy resolved the failure.

Parallel group topology

Normalized working-file topology for one authored parallel group.

`id`

Type: string
Required: yes
Constraints: at least 1 character(s)

`startIndex`

Type: integer
Required: yes
Constraints: minimum 0

`endIndex`

Type: integer
Required: yes
Constraints: minimum 0

`failFast`

Type: boolean
Required: yes

Condition evaluation

Latest script-condition evaluation retained for the automation result projection (written automatically during execution).

`passed`

Type: boolean
Required: yes

`action`

Type: "continue" | "stopWorkflow" | "retry" | "skipPrompt"

Populated for pre-conditions, where it explains the gate decision.

`script`

Type: string
Required: yes

`actual`

Type: string
Required: yes

`stdout`

Type: string
Required: yes

`stderr`

Type: string
Required: yes

`exitCode`

Type: number

`durationMs`

Type: number
Required: yes

`error`

Type: string

`operator`

Type: "eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"

How the compare source is compared against expected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treats expected as an unanchored regular expression — add ^ and $ to require a full match. 'isEmpty'/'isNotEmpty' take no expected. Word tokens only: operator: >= is a YAML parse error and operator: != silently parses as a YAML tag.

Token totals

Run-scoped token aggregate projected from timeline history. Written automatically during execution; not hand-authored.

`total`

Type: number

Sum of every AI attempt's token total observed in this run

`coverage`

Type: "complete" | "partial"

'complete' only when every executed AI attempt reported a usable total

`reportedAttemptCount`

Type: number

`attemptCount`

Type: number

`isFinal`

Type: boolean

False while the run can still add usage

`costUsd`

Type: number

`costPartial`

Type: boolean

`costSources`

Type: array of "harness-reported" | "price-table" | "user-override"

`byHarness`

Type: map of Harness token totals

Same aggregate partitioned by the harness recorded on each immutable attempt output.

`byLocalDay`

Type: map of map of Harness token totals

Same per-harness subtotals partitioned by the attempt start's local day (YYYY-MM-DD).

Harness token totals

Per-harness token subtotal within a run aggregate.

`input`

Type: number

`output`

Type: number

`cachedInput`

Type: number

`cacheCreated`

Type: number

`reasoningOutput`

Type: number

`total`

Type: number

`coverage`

Type: "complete" | "partial"

`reportedAttemptCount`

Type: number

`attemptCount`

Type: number

`costUsd`

Type: number

`costPartial`

Type: boolean

`costSources`

Type: array of "harness-reported" | "price-table" | "user-override"

Run file reference ​

Where run files live ​

Run file root ​

parallelGroups ​

startedAt ​

definitionRevision ​

_runtime ​

Workflow runtime ​

schemaVersion ​

lastActivityAt ​

currentIndex ​

executionState ​

startTime ​

pausedTime ​

totalPausedDuration ​

executionEndTime ​

activeParallelGroup ​

tokenTotals ​

pendingRewind ​

pendingRewind.fromStepIndex ​

pendingRewind.baseDefinitionRevision ​

worktree ​

worktree.schemaVersion ​

worktree.mode ​

worktree.origin ​

worktree.branchName ​

worktree.worktreePath ​

worktree.executionRoot ​

worktree.executionCheckoutRoot ​

worktree.sourceCheckoutRoot ​

worktree.namedWorkspaceRoots ​

worktree.baseCommit ​

worktree.comparisonBaseLabel ​

worktree.comparisonBaseCommit ​

worktree.changedFileCount ​

worktree.dirty ​

worktree.sourceCheckoutDirty ​

worktree.targetBranch ​

worktree.lifecycleOwner ​

worktree.lifecycleState ​

worktree.setupOutcome ​

worktree.landingOutcome ​

worktree.mergeOutcome ​

worktree.directoryState ​

worktree.branchState ​

worktree.finalBranchTip ​

worktree.conflictFiles ​

worktree.message ​

worktree.updatedAt ​

worktreeNotice ​

finalStep ​

finalStep.phase ​

finalStep.loopCount ​

finalStep.status ​

finalStep.startedAt ​

finalStep.completedAt ​

finalStep.preCondition ​

finalStep.endCondition ​

Step runtime ​

startedAt ​

stepId ​

completedAt ​

terminalStatus ​

retryCount ​

elapsed ​

contextWindowUsed ​

contextWindowSize ​

failureKind ​

failureMessage ​

terminalFailure ​

Parallel group topology ​

id ​

startIndex ​

endIndex ​

failFast ​

Condition evaluation ​

passed ​

action ​

script ​

actual ​

Run file reference

Where run files live

Run file root

`parallelGroups`

`startedAt`

`definitionRevision`

`_runtime`

Workflow runtime

`schemaVersion`

`lastActivityAt`

`currentIndex`

`executionState`

`startTime`

`pausedTime`

`totalPausedDuration`

`executionEndTime`

`activeParallelGroup`

`tokenTotals`

`pendingRewind`

`pendingRewind.fromStepIndex`

`pendingRewind.baseDefinitionRevision`

`worktree`

`worktree.schemaVersion`

`worktree.mode`

`worktree.origin`

`worktree.branchName`

`worktree.worktreePath`

`worktree.executionRoot`

`worktree.executionCheckoutRoot`

`worktree.sourceCheckoutRoot`

`worktree.namedWorkspaceRoots`

`worktree.baseCommit`

`worktree.comparisonBaseLabel`

`worktree.comparisonBaseCommit`

`worktree.changedFileCount`

`worktree.dirty`

`worktree.sourceCheckoutDirty`

`worktree.targetBranch`

`worktree.lifecycleOwner`

`worktree.lifecycleState`

`worktree.setupOutcome`

`worktree.landingOutcome`

`worktree.mergeOutcome`

`worktree.directoryState`

`worktree.branchState`

`worktree.finalBranchTip`

`worktree.conflictFiles`

`worktree.message`

`worktree.updatedAt`

`worktreeNotice`

`finalStep`

`finalStep.phase`

`finalStep.loopCount`

`finalStep.status`

`finalStep.startedAt`

`finalStep.completedAt`

`finalStep.preCondition`

`finalStep.endCondition`

Step runtime

`startedAt`

`stepId`

`completedAt`

`terminalStatus`

`retryCount`

`elapsed`

`contextWindowUsed`

`contextWindowSize`

`failureKind`

`failureMessage`

`terminalFailure`

Parallel group topology

`id`

`startIndex`

`endIndex`

`failFast`

Condition evaluation

`passed`

`action`

`script`

`actual`