Skip to content

Handling escalations

When the runner hits something ambiguous or risky, it doesn't guess — it pauses and escalates to you. An escalation is a deliberate hand-off, not a failure to recover from on its own.

Why escalations happen

The monitor caps retries and runs gates, but it never auto-resolves decisions that need human judgment. Common reasons a run escalates:

  • Rebase conflicts — never auto-resolved.
  • Gate failures it can't recover from after retrying.
  • Contract disagreements between domains.
  • Unresolved open questions in the spec that block progress.
  • Retry or iteration limits being exceeded.

Note

Escalating is the safe default. The runner would rather stop and ask than commit a change it isn't confident about.

Read the escalation

When a run pauses, open the pipeline state file in your repo:

pipemason status        # prints .pipeline/STATE.md
# or open it directly
.pipeline/STATE.md

The escalation block tells you exactly what's needed. It includes:

  • phase — where the run stopped.
  • reason — what triggered the escalation.
  • awaiting — what the runner needs from you to continue.
  • recovery — a suggested next action.

Fix the underlying issue

Resolve whatever the escalation describes. For a rebase conflict, that means resolving the conflict in your working tree. For a gate failure, it might mean clarifying the spec or fixing an environment problem. For a contract disagreement, it may mean deciding which interface is correct.

Make the fix the same way you would for any teammate's blocked work — the escalation block's recovery hint points you at the most likely next step.

Resume the run

Once the issue is addressed, continue from where it stopped:

pipemason resume

The monitor re-enters at the paused phase. It never silently advances past an unresolved escalation, so if the same condition still applies, it will pause again with an updated block.

Tip

For program runs, advance the whole program after fixing a story-level escalation with pipemason program resume.

Typical flow

  1. Run pauses; you're notified of an escalation.
  2. Open .pipeline/STATE.md and read the escalation block.
  3. Fix the underlying issue described under awaiting / recovery.
  4. Run pipemason resume (or program resume).
  5. Confirm the run continues past the phase that stopped it.