From becdbbb31481f86ce5f60d92c783735e57a76e5e Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Sat, 12 Sep 2026 19:10:43 -0600 Subject: [PATCH] docs: agent-node retry contracts (worst-case wall time, at-most-once inbox) + bundled suite fail-closed conventions --- Graph-Agents.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/Graph-Agents.md b/Graph-Agents.md index 0ab5b10..46593e1 100644 --- a/Graph-Agents.md +++ b/Graph-Agents.md @@ -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: ` 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