# 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.