docs: agent-node retry contracts (worst-case wall time, at-most-once inbox) + bundled suite fail-closed conventions

Dark-Alex-17 committed 2026-09-12 19:10:43 -06:00
1 parent 7df7d27a6f
commit becdbbb314
1 file changed
+19
+19
@@ -346,6 +346,12 @@ research_topic:
(agents that write code or deploy things); a child that authors files
(e.g. a probe lane writing test artifacts) is mildly side-effectful,
meaning a failed first attempt may leave partial artifacts behind.
Two contracts to keep in mind: worst-case node wall time is
`max_attempts × timeout` (every attempt gets its own fresh budget), and
teammate message delivery is **at-most-once across the retry boundary** —
messages a failed attempt already drained are not re-delivered to the
retry (same inbox Arc, no replay), and messages the failed attempt SENT
remain with its peers.
- **`fallback`:** Failure route with the same contract as `llm` nodes: on the
final failure (retries exhausted, hard error, or structured-output
extraction failure) the node writes `Agent node failed: <error>` as
@@ -754,6 +760,19 @@ across attempts. See [agent](#agent) for when re-running a child is safe;
structured-output extraction failures are never retried on either node
type (they route via `fallback` instead).
### Fail-closed conventions in the bundled review suite
The bundled review agents (adversary, review-gauntlet, code-reviewer,
finding-verifier, deep-research, step-runner) use `max_attempts` + `fallback`
so that **every run emits its machine-readable sentinel** even when a stage
dies: stage failures degrade to `PIPELINE-FAULT:`-prefixed markers in state,
verdict scripts treat any fault as blocking (a degraded run can never read
as CONFORMS / PASS / MERGE-READY), and detection is prefix-anchored so a
report merely *quoting* the marker is never misclassified. The adversary
additionally records caller-declared `verification_commands` once in a
deterministic `run_checks` stage — execution criteria ("tests green") are
judged against that recorded run, never re-executed by review branches.
### Turn cap (`max_iterations`)
`max_iterations` caps the number of model-call turns in one execution of the