control.poll.until

Poll a read-only probe workflow until a predicate on its output holds (or stop/deadline)

Overview

Property	Value
Workflow type	Linear
Library	App-control
Version	1.0

Input Schema

Field	Type	Required	Default	Description
workflow_type	string	Yes	—	Read-only probe workflow type to run each tick
input	json	No	—	Probe input, passed verbatim on every tick (default {})
result_path	string	Yes	—	Dotted path into the probe's terminal state_data (e.g. 'green' or 'status.phase')
equals	json	No	—	Value the resolved path must equal to satisfy the wait (default true)
stop_when_truthy	string	No	—	Optional dotted path; when it resolves truthy the wait aborts as FAILED (e.g. 'failed_checks' — red CI should stop the wait, not ride the deadline)
interval_seconds	integer	No	—	Seconds between ticks (default 60, clamped 5..3600)
deadline_seconds	integer	No	—	Overall budget before the wait fails as timed out (default 3600, capped 86400)

Output Schema

Field	Type	Required	Default	Description
workflow_type	string	Yes	—	Read-only probe workflow type to run each tick
input	json	No	—	Probe input, passed verbatim on every tick (default {})
result_path	string	Yes	—	Dotted path into the probe's terminal state_data (e.g. 'green' or 'status.phase')
equals	json	No	—	Value the resolved path must equal to satisfy the wait (default true)
stop_when_truthy	string	No	—	Optional dotted path; when it resolves truthy the wait aborts as FAILED (e.g. 'failed_checks' — red CI should stop the wait, not ride the deadline)
interval_seconds	integer	No	—	Seconds between ticks (default 60, clamped 5..3600)
deadline_seconds	integer	No	—	Overall budget before the wait fails as timed out (default 3600, capped 86400)
satisfied	boolean	No	—	True once the predicate held on the most recent tick
attempts	integer	No	—	Probe runs performed so far
waited_seconds	integer	No	—	Elapsed seconds since the first tick
observed	json	No	—	Value resolved at result_path on the most recent successful probe
started_at_epoch	integer	No	—	Unix time of the first tick
last_checked_at_epoch	integer	No	—	Unix time of the most recent tick
last_probe_workflow_id	string	No	—	Workflow id of the most recent probe run
last_probe_error	string	No	—	Error from the most recent probe run, when it failed
pending_probe_workflow_id	string	No	—	Probe started by the previous tick and not yet read. Absent means no probe is in flight, which is what arms a fresh one on the next tick.
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	poll	—
waiting	No	No	—	—	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	poll	waiting	—
waiting	poll	waiting	—
waiting	complete	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "control.poll.until",
  "initial_data": {
    "workflow_type": "value",
    "result_path": "value"
  }
}