This document explains the implementation path from an authored graph to a terminal run. For operator commands, use docs/product/operations.md; this page focuses on how those commands work internally.
sequenceDiagram
participant Human
participant CLI as agentflow CLI
participant Graph as graph loader
participant Runtime
participant Harness as Codex/Cursor
participant Supervisor
participant Delivery
Human->>CLI: validate --graph
CLI->>Graph: load, normalize, validate, compile
Graph-->>CLI: diagnostics, compiled summary, Mermaid
Human->>CLI: run --graph
CLI->>Graph: compile same contract for execution
CLI->>Runtime: runCompiledGraph(compiled_graph)
Runtime->>Runtime: write run root and preflight readiness
Runtime->>Runtime: initialize workspace backend
Runtime->>Harness: execute reachable node attempt
Harness-->>Runtime: result, stdout/stderr, final response
Runtime->>Supervisor: observe checkpoint health
Supervisor-->>Runtime: continue, repair causal target, or request authority
Runtime->>Delivery: write terminal delivery package
Delivery-->>Human: review brief, run learnings, audit index
Validation follows the same front half as a run, but stops before execution:
- Load the graph file and resolve paths relative to the graph directory where appropriate.
- Normalize authored fields into the v1 graph contract.
- Expand managed patterns and plugin workflow nodes into authored primitive graph nodes.
- Resolve launch settings from
defaultsandprofiles. - Compile the graph into primitive runtime nodes, edges, scopes, resolved tools, credential specs, and artifact references.
- Run full authoring review diagnostics.
- Run local readiness checks for repos, commands, ambient CLI hints, harnesses, plugin tool help, credentials, and context pointers.
- Optionally emit compiled JSON, a validation package, Mermaid text, or a rendered Mermaid image.
validate --show-compiled is the most direct way to inspect the contract the runtime will execute. validate --output-dir writes a reusable validation package. validate --diagram-output is for reviewing graph shape, dependencies, scopes, and artifact handoffs visually.
Compilation is the boundary between human-authored structure and the runtime scheduler.
flowchart TD
authored["Authored graph"] --> managed["Lower managed patterns and plugin workflows"]
managed --> tools["Resolve graph and node tool declarations"]
tools --> nodes["Create executable compiled nodes"]
nodes --> scopes["Create sequence, parallel, repeat, and cleanup scopes"]
scopes --> edges["Create dependency edges"]
edges --> refs["Validate artifact refs and repeat selectors"]
refs --> compiled["Compiled graph"]
Compiled nodes carry the effective policy needed to launch them: repo alias, profile name, workspace backend, harness, model, sandbox, artifact repair policy, context list, declared artifacts, selected skills, ambient CLI hints, and granted managed tools.
Authored ids remain visible for humans. Compiled ids are stable runtime ids that include scope context, especially inside managed patterns and repeat bodies. The authored_to_compiled map preserves that relationship for inspection, delivery, and resume.
runCompiledGraph creates the run root and writes the first durable artifacts before doing substantial work. The runtime then:
- Writes
run.json,compiled_graph.json,execution_manifest.json,state.json, and initial event files. - Evaluates readiness that must block execution, such as missing repos, commands, env vars, plugin tool help, credentials, or harness binaries for reachable nodes.
- Initializes the workspace backend:
inplacebinds repo aliases to the configured checkout paths.worktreecreates isolated Git worktrees under the run root and cleans them up at terminal state.
- Starts the scheduler loop with the compiled topology.
- Opens an attempt directory for each runnable node.
- Materializes context and prepares runtime tooling for harnessed agent nodes.
- Executes the node through an agent harness, local
exec, deterministic check, AI check, or checkpoint executor. - Records result files, logs, artifacts, events, state, and supervisor decisions.
Each attempt is the unit of execution and audit. A typical agent attempt includes:
agent/context.md,runtime/context.json, andhuman-debug/context-provenance.jsonagent/attempt-memory.mdandruntime/attempt-memory.jsonon retry attemptsruntime/tools/runtime.json,state.json, generatedbin/af, and generated plugin wrappers- stdout/stderr logs from the harness or local command under
human-debug/harness/ human-debug/tools/index.jsonland paired tool input/output payloads when generated wrappers are used- declared output artifacts under the attempt artifact directory or workspace paths
- reserved artifacts such as
agent_response,stdout,stderr, andverification_json workspace-changes/snapshots for agent, exec, and check attempts that reach the execution boundaryruntime/verifier.jsonandhuman-debug/verifier/verdict.mdfor passing agent attempts after declared artifacts materialize
Normal agents read agent/, declared artifacts/, and explicit context pointers. Files under human-debug/ are audit-only unless a diagnostic supervisor helper is explicitly asked to inspect them.
The attempt boundary matters because supervisor interventions attach to a specific attempt, downstream refs select from attempts, and resume decides whether completed attempts remain compatible with the current compiled contract.
Managed deep-research internals add one attempt-local workspace layer before context resolution. Angle, synthesis, and publisher attempts run against a disposable investigation workspace materialized from the current source state. The public workspace backend does not change, and graph authors cannot request this backend. Temporary exploratory edits inside the investigation workspace are audit/debug evidence and are discarded after the attempt; they are not source workspace mutations or delivered implementation changes.
Retries are evidence-based continuations, not blind reruns. When the supervisor schedules a retry, it records a structured intervention decision: failure fingerprint, prior strategy, selected strategy, resume point, restart boundary, workspace decision, evidence to reuse, evidence to discard, material delta, required next action, validation gate, and fallback if the same tactic repeats. The best restart boundary is not always the smallest one; unsafe, contaminated, over-broad, or wrong-direction progress can require a full failed-attempt reset, while transient verifier failures should rerun only verification. Same fingerprint plus same strategy plus same boundary plus no material delta is invalid. Attempt memory is then derived from runtime events, workspace snapshots, milestones, artifacts, completion packets, verifier results, and the recovery decision. af orient is the retry front door: it starts with retry orientation and attempt memory, then shows the unchanged success contract, artifacts, milestones, context, and support. Raw logs, provenance, case files, recovery plans, and debug tool payloads stay out of normal retry prompts.
Managed pattern internals also emit managed.progress events at meaningful boundaries such as internal node completion, ordinary deep-work completion feedback, repeated no-delta stalls, and managed repeat exhaustion. Ordinary managed feedback stays inside the pattern while the pattern can still make progress. A failed loop-body attempt inside a repeat consumes the repeat budget just like a failed gate when it has no authored failure continuation and no concurrent active work in the same repeat iteration; downstream nodes are blocked only after the repeat exhausts. When deep work repeats the same blocker without material delta, or when a managed repeat exhausts its authored cycles, the runtime records managed progress evidence and routes the failed boundary through the normal supervisor path. The supervisor may retry only when it can attach a material delta such as a requirement evidence map, repaired context, changed validation strategy, workspace cleanup, safe environment repair, target rerank with evidence, or accepted artifact repair.
The supervisor is engine-side control logic. It is not a separate always-running agent. It observes every executable checkpoint at scheduler boundaries and stays out of the way when the node is healthy. A failed or rejected checkpoint is treated as a symptom, not automatically as the root cause.
flowchart TD
checkpointResult["Checkpoint result"] --> healthy{"Healthy?"}
healthy -- yes --> continueGraph["Continue graph"]
healthy -- no --> caseFile["Write causal case file"]
caseFile --> cone["Build upstream causal cone"]
cone --> target["Rank recovery targets"]
target --> budget{"Recovery budget and typed authority state available?"}
budget -- no --> authority["Typed authority pause or contractual failure"]
budget -- yes --> repair["Repair nearest intent-aligned target"]
repair --> delta{"Material delta recorded?"}
delta -- no --> investigate["Widen causal search or change tactic"]
investigate --> cone
delta -- yes --> rerun["Rerun failed gate"]
rerun --> healthy
Supervisor decisions are written to event streams, supervisor-timeline.jsonl, interventions.jsonl, and state. Budget-spending recovery chains attach machine state under the symptom attempt's runtime/supervisor/ directory and raw diagnostic evidence under human-debug/interventions/. If the selected recovery target is upstream, the target writes normal attempt folders and the chain links the symptom, target, material delta, and rerun gate.
Failure routing is structured-control-plane only. The classifier reads trusted typed AuthorityRequest records, runtime-owned failure_code metadata, structured completion packets, outcome-verifier categories, repeated failure fingerprints, and node kind. Stdout, stderr, agent responses, verifier summaries, helper prose, and debug tool files can explain evidence, but they do not choose recovery class or pause a run.
For recovery-oriented actions, the supervisor records a failure fingerprint, writes requirement evidence maps, causal case files, target rankings, recovery chains, recovery plans, runtime overlays, and material deltas as machine state, emits supervisor.retry_scheduled, sleeps before re-queueing, and injects a compact agent/supervisor-recovery.md brief into the selected target's next attempt prompt and context. A retry without a material delta is blocked so the supervisor does not spend budget repeating the same failed tactic. Generic retry advice and target changes without evidence are not material deltas. The default retry delay is 10 seconds with exponential backoff capped at 2 minutes; AGENTFLOW_RETRY_BASE_DELAY_MS and AGENTFLOW_RETRY_MAX_DELAY_MS override the values.
Recovery envelopes include a runtime-owned resume decision. Resume points are continue_from_prior_progress, continue_from_milestone, repair_artifacts, rerun_verification, repair_validation_strategy, repair_workspace, fresh_retry, or fail_contract_gap; restart boundaries identify the actual retry surface: verification, artifact repair, milestone, work-list item, managed-pattern phase, node attempt, or upstream target. fresh_retry is reserved for cases where prior progress is absent, unsafe, irrelevant, or explicitly rejected by structured verifier evidence such as wrong-direction or contaminated-progress categories. Verification substrate failures are local: they use rerun_verification and do not rerun the worker unless structured verifier findings show an actual work defect.
Context pointer packaging can fail before the harness runs. Those failures are classified as context_contract_failure, analyzed with the shared run-ready context analyzer, and retried with a compact supervisor_context_repair packet when the supervisor can safely repair the packaging without changing graph authority.
Workspace repair uses the node-start baseline and node-end snapshots captured around every agent/exec attempt. If a failed attempt is classified as a forbidden or unrelated workspace edit, the overlay restores tracked files from the pre-attempt snapshot and removes untracked files introduced by that failed attempt before the retry is scheduled. Preexisting dirty workspace state is preserved as audit context and is not counted as a node-local read-only violation. For deep-research internals, source dirtiness is snapshot provenance and playground edits happen inside the disposable investigation workspace. Environment repair is intentionally narrower: it refreshes per-execution runtime tool wrappers and PATH/runtime metadata on the retry without mutating global machine state.
Authority pauses are last resort. The runtime pauses only when a trusted component emits a typed AuthorityRequest: missing credentials, missing harness authentication, planned checkpoints, external side-effect approval, or operator-authored pause. Product ambiguity, graph contract gaps, repo/sandbox/scope expansion, local context, artifact, workspace, validation strategy, and recoverable environment issues recover autonomously or fail contractually with evidence.
Resume is contract-aware. It does not blindly continue old state.
- Load the prior run root and run state.
- Re-load and recompile the current graph.
- Compare the prior compiled graph and current compiled graph.
- Preserve completed attempts only when the graph intent, supervision contract, and node contracts remain compatible.
- Invalidate affected nodes and dependent work when contracts changed.
- Continue the scheduler loop from the reconstructed session.
Node compatibility includes prompt-affecting support and execution contract fields: repo, dependencies, intent, effective policy, context pointers, selected skills, CLI hints, managed tool grants/config, declared artifacts, commands/checks, and managed lowering metadata. Raw pointed file contents, glob matches, instruction files, and debug/provenance files do not by themselves invalidate completed nodes unless the compiled graph contract changes.
agentflow resume --dry-run stops after reconstruction and reports what would be preserved, restarted, and initially startable without reconciling artifacts or creating workspaces. --reset-supervisor-budget keeps compatible completed work but restores the supervisor budget from the current graph, which is useful after fixing an exhausted run's graph or environment.
Paused supervisor runs additionally require explicit --human-action and optional --human-note when execution actually resumes; dry-run previews do not require human input. Planned checkpoint decisions are different: they happen during the original TTY run and are represented as checkpoint outcomes and operator feedback artifacts.
Terminal runs always attempt to write the delivery package. Runtime first collects deterministic evidence from state, attempts, events, checks, interventions, workspace changes, milestones, and declared artifacts. It writes delivery/evidence/delivery-source.json, delivery/evidence/delivery-source.md, the audit/index evidence files, and delivery/03-audit-index.md. A required read-only delivery curator then uses the supervisor profile to write the human-facing delivery/01-review-brief.md and delivery/02-run-learnings.md. Runtime verifies those curated files against delivery/evidence/delivery-source.json and records the result in delivery/evidence/curation-verdict.json.
Delivery is derived from final runtime state. Final accepted attempts and artifacts are the review surface; failed prior attempts that were later repaired or retried are listed as recovered issues, not active follow-ups. Active failures are reserved for unresolved terminal failures or active blocking observations.
If curated delivery fails, graph control-flow status remains the terminal graph outcome, but CLI/reporting mark delivery_status=failed and review_ready=false. Agentflow still writes a deterministic failure package: manifest, audit index, source evidence, curation verdict, and a human-readable delivery-failure brief. This keeps the runtime contract honest: a successful graph outcome still needs a verified human handoff.