Propose agent execution plane v1

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

@@ -0,0 +1,97 @@
+# 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.
+