Preflight and retries

Run pinned checks, set a command failure limit, and recover when a check needs your input.

What preflight does

Preflight is the agent’s workflow for finishing an issue: read its required checks, fix failures, submit evidence, publish the result, and follow the configured pull request checks. The repository’s pinned closeout policy determines what is required.

The host validates evidence and enforces the checklist. The agent runs the commands, reviews their output, and makes repairs. The workflow uses the commands and review tools chosen by the repository; it does not require a particular package manager or review service.

Set a command failure limit

Add .acpdash/closeout.yaml to the repository’s configured base branch before starting the work:

version: 1
retry:
  maxFailedAttemptsPerItem: 5
items:
  - id: checks
    kind: command
    phase: done
    run: bun run check
    hint: Fix the failing checks and rerun this item.

Use your repository’s check command in run. This example allows five failed executions of each required command item before asking for your input. maxFailedAttemptsPerItem accepts an integer from 1 to 20. Five is an example, not a default: omitting retry leaves command attempts unlimited by the host.

The policy format remains version: 1. Without a policy file, the host adds no extra closeout checks. Approved BDD scenarios still require Cucumber proof.

The host pins the policy, including its retry limit, to each issue revision from the base commit. Editing it in a worker’s branch does not change that revision’s requirements. To change an active issue’s policy, update the base policy and use feedback and approval to create a new issue revision.

Run the checklist

The agent calls check_closeout to read the pinned requirements.
For each required command, it calls start_command with issueId, revision, and itemId, then inspects the completed command’s status and output.
It fixes clear failures within the approved scope and reruns the affected checks. If the expected behavior or scope remains uncertain after investigation, it asks you for a decision.
It submits recorded checks with submit_issue_checks, or Cucumber Messages with submit_issue_proof for issues with BDD scenarios. It publishes screenshots and other artifacts with share_proof.
A child agent pushes its tested commit and opens its pull request before report_item_result. A main agent’s direct quick-work result does not require a pull request.

Running the same command in an ordinary shell does not satisfy a pinned command item. The host needs the command record tied to the issue, revision, and item. A new implementation commit also needs fresh proof for requirements tied to a commit.

What counts as a failed attempt

The limit is tracked separately for each pinned command item in the current issue revision and retry round. Each command execution counts at most once, and the counts survive a host restart.

Event	Effect on the count
A pinned command finishes with a nonzero exit code	Adds one failed attempt.
A command is stopped or interrupted by a host restart	Does not add a failed attempt.
A command exits zero	Does not add a failed attempt or erase earlier failures.
A command exits zero but its commit changed or its worktree is dirty	Does not add a failed attempt; it still cannot provide valid passing evidence.
A new commit, pull request comment, ordinary chat message, or unrelated answer	Does not reset the count.
A receipt check, Cucumber submission, independent review, CI observation, or review-thread poll	Does not consume this command allowance.

Command output stays in the existing command history. Proof artifacts are published separately by the agent.

Recover from an exhausted check

The Closeout checklist shows the count, for example 5 of 5 failed attempts, 0 remaining. At the limit, the host refuses another start for that item and asks a question in Needs you.

Write corrective feedback as your own answer to that exhaustion question. A nonempty answer restores the full configured allowance for that item before the host delivers your feedback to the agent. In this example the checklist returns to 0 of 5 failed attempts, 5 remaining. There is no separate attempt-grant step.

Choosing Pause or Stop leaves the check exhausted. When you want to continue, explicitly resume the agent to reopen the exhaustion question, then answer it with corrective feedback. Resume alone does not restore attempts. An old question from a previous issue revision or assignment cannot restore the current allowance.

A project pause, another unanswered question, or a pending permission can still hold work after the allowance is restored. Restoring attempts does not make a failed check pass or accept the result.

Follow pull request feedback

After reporting a result, the agent still follows the configured CI and review requirements. It reads comments, logs, relevant code, and tests before deciding what to change. Clear fixes within scope can proceed; a real uncertainty about behavior, the choice of fix, or approved scope needs your answer. Non-actionable acknowledgements need no change.

The host wakes an idle issue owner for changes to configured failing CI or unresolved review-thread blockers. General pull request comments outside those configured notifications do not automatically wake an agent; the agent must monitor that feedback when the task requires it.

After a fix changes the commit, the agent reruns the affected verification and submits fresh proof. Earlier evidence stays in history. See verification and proof for acceptance requirements.

Get the agent guide

Agents can call get_closeout_instructions to retrieve the canonical preflight and pull request feedback instructions from the host. The text comes from the closeout section of the host operating guide, so providers can retrieve it even without discovering a local skill.

The host includes closeout guidance when assigning implementation or handling closeout feedback. See agent operating instructions for onboarding and updates.