Assistant/docs/proposals/ADR-0020-agent-execution-plane-v1.md

Proposal ADR-0020 — Agent Execution Plane V1

Status: Proposed Task: DEV-000104

Problem and evidence

ADR-0017 defines durable delegation semantics, but the audit found no automatic dispatcher/worker plane, lease/heartbeat lifecycle, callback authentication or independent verification boundary. A worker must be able to stop, restart and resume without turning a missing callback into success or silently duplicating external work.

Decision proposed

1. Keep work as the canonical owner of Delegation, AgentRun, AgentCheckpoint, AgentResult and verification gating. capability owns executor-neutral agent implementations; adapters own transport and process details.
2. Every dispatch has a stable dispatch_id, delegation id, run id, implementation id, exact source/worktree identity, bounded instruction artifact reference, requested capability set, authority/credential refs, deadline and idempotency key. The derived instruction must preserve OriginalHumanIntent, inferred goal, added context and verification plan as separate provenance fields.
3. A worker must acquire a durable lease before execution. Lease ownership is a fencing token, not an in-memory mutex. Heartbeats extend the lease only for the same run and fencing token; an expired lease makes late callbacks non-authoritative.
4. Dispatch and callback endpoints authenticate the worker identity and bind every message to delegation, run, dispatch, implementation and fencing token. Forged, replayed, out-of-order or duplicate callbacks are rejected or recorded as non-authoritative evidence. Idempotent acknowledgement is allowed only for the exact previously accepted event.
5. Checkpoints and artifacts are content-addressed metadata owned by artifact, with typed refs from Work. Artifact attestation records source revision/worktree, producer, digest, test command/result and capture time; an un-attested path or log is not completion evidence.
6. Cancellation is a durable Work decision. The dispatcher sends cancellation to the leased worker, records acknowledgement or timeout, and never erases history. A worker that cannot prove cancellation remains UNKNOWN or RECOVERING until reconciled.
7. Retry is policy-driven and distinguishes retryable transport/worker loss, execution-window exhaustion, human blocker, invalid result and unknown external outcome. Retry creates a new run under the same delegation and preserves prior checkpoints/results; it never reuses an idempotency key for an unproven external mutation.
8. A run result cannot complete Work directly. Independent verification must consume the declared artifacts and tests through a separate verifier identity and produce a typed verification result. Verification failure, missing evidence and verifier unavailability remain distinct states.
9. Secrets are resolved only through approved CredentialRef boundaries and are not copied into instructions, callbacks, artifacts, logs or task packets. Worker startup has no ambient credential inheritance.
10. The plane is durable and restartable: dispatch intent, lease, heartbeat, cancellation, checkpoint, result, verification and reconciliation events are persisted before their projections claim progress.

Lifecycle proposal

Delegation remains the higher-level human/work intent. A run progresses through DISPATCHED, LEASED, RUNNING, CHECKPOINTED, SUCCEEDED, FAILED, CANCEL_REQUESTED, CANCELLED, EXHAUSTED, WAITING_HUMAN, UNKNOWN or RECOVERING, subject to explicit transition guards. SUCCEEDED means only that the worker returned an accepted result; Work completion additionally requires independent verification. Lease expiry and missing heartbeat never become success.

Alternatives and rationale

• An in-memory queue or goroutine was rejected because it loses dispatch state on restart and violates durable timer/lease requirements.
• A single generic AgentManager was rejected because it collapses Work, Capability, Artifact and Continuity ownership.
• Trusting worker-reported success was rejected because the worker and verifier must remain separate authorities.
• Reusing the same run on retry was rejected because it makes duplicate external effects and late callbacks indistinguishable.

Boundaries, consequences and non-goals

No new canonical owner, provider, deployment authority, database migration, Codex-specific domain contract or automatic self-modification is proposed. The design enables restartable external work and truthful failure handling, but requires durable event ordering, fencing, artifact storage and verifier capacity before WP-301 can claim production readiness.

Migration, rollback and revisit triggers

Implementation must begin behind an opt-in dispatch path with a dry-run verifier and deterministic fake worker. Existing delegation records remain readable; unknown legacy RUNNING records are classified by WP-302 rather than silently resumed. Rollback disables new dispatch and drains/recovers leases; history and artifacts remain. Revisit if a worker needs authority beyond its declared capability, if a second transport changes callback guarantees, or if artifact attestation cannot be made independent of the worker.