Reference
cdp_run_action
Replay a learned action by id with end-to-end auto-repair. On iOS, the validated flow is partitioned before execution: exact-testID commands use the authority-bound React-tree prover, while native-only commands use XCTest. The RunRecord and result preserve the reported proof domain, and a react-tree pass never promotes an experimental action to Maestro-certified active status. Ordinary missing React testIDs remain TESTID_NOT_FOUND; native selector misses remain ordinary Maestro failures unless direct bounded evidence proves a NATIVE_SURFACE_BLIND environment. Pass autoRepair=false to opt out of selector repair. Successful runtime writes return their exact runtime sidecar path as writes.runtimeStatePath: fenced sessions use session-private state, while an unfenced compatibility process uses project-local .rn-agent/state. proofReplay=true is reserved for proof-capture rehearsal and writes no runtime state. When the canonical run ledger proves every authored mutating command completed and only trailing verification (extendedWaitUntil/assert) failed, the result stays failed but carries meta.trailingVerification (mutationEvidence proven, attempt lineage, termination provenance) — verify the live goal state instead of retrying or rebooting; auto-repair refuses so a merely-slow selector is never rewritten.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
actionId | string | Yes | Owned action id; resolves one .yaml or .yml file. | ||
projectRoot | string | No | Override project root (default: process.cwd()). | ||
platform | enum: ios | android | No | Force a specific platform; otherwise auto-detected from the active device session. | ||
appFile | string | No | GH #705: path to the .app Maestro reinstalls from after a clearState uninstall. Normally omit it — an iOS clearState flow resolves the bundle from the session’s attested install receipt, and the receipt is re-issued after the reinstall so later device_*/maestro_run calls keep working. | ||
autoRepair | boolean | No | Auto-repair on SELECTOR_NOT_FOUND failures. Default true. Pass false to disable (e.g. when investigating a failure manually). | ||
timeoutMs | number | No | Maestro execution timeout per attempt (ms). Default 120_000. | ||
trigger | enum: agent | ci | human | No | RunRecord trigger annotation. Default “agent”. CI calls should pass “ci”. | ||
forceReload | boolean | No | GH #173: when true (default), acknowledge any human edit to the YAML as the new baseline before running so downstream repair does not abort with STALE_TARGET. Pass false for the strict Phase 129 “respect external edits” behavior (useful for CI replays of fixed baselines). | ||
proofReplay | boolean | No | Read-only proof rehearsal mode. Requires autoRepair=false and forceReload=false; never writes action YAML, runtime sidecar, or DB state. | ||
params | Record<string, unknown> | No | Parameter bindings for the action’s ${VAR} placeholders, forwarded to maestro as -e KEY=VALUE on the first attempt AND the post-repair retry (GH #116). Keys must match /^[A-Z_][A-Z0-9_]*$/ (validated in maestro_run). |
cdp_run_action(actionId: <string>)