feat: add attended draft PR lifecycle

[davidahmann]

Outcome

Adds Mill Wave 3: an attended, exact-candidate path from a locally validated and reviewed commit to one draft GitHub pull request, followed by truthful CI/review observation, merge readback, and closure.

Included

• binds the delegated GitHub actor, repository identity, remote, branch, policy, candidate commit/tree, and approval digest
• pushes with an expected-old-head lease and opens a marker-bound draft PR only
• journals remote effects and fails closed on ambiguous outcomes, identity drift, cancellation, and retry exhaustion
• preserves the same PR across one aggregated review-repair cycle
• validates exact-head checks, configured review, authorized human merge, merge shape/tree, default-branch containment, and post-merge checks
• fixes the accepted Wave 2 debts for Docker bind paths containing commas and state-restore worktree reconciliation
• updates runtime contracts, schemas, CLI, documentation, package canary, and fault/adversarial tests

Validation

• npm run check under Node 24.20.0
• 20 test files / 124 tests passing
• workflow contract, coverage thresholds, build, and packed draft-PR lifecycle canary passing
• exact-commit Codex review: no findings

Residual promotion gate

The attended real-provider canary has not been run because Wave 3 requires an explicitly named disposable GitHub repository. This PR does not claim that evidence and must remain pre-alpha until the maintainer authorizes that canary. Mill does not mark ready, merge, deploy, provision repositories, or rerun remote checks.

[davidahmann]

Wave 3 closure evidence

Wave 3 implementation and its attended real-provider promotion gate are complete.

Disposable real-provider canary

• Repository: Clyra-AI/clyra-test (private, previously empty, explicitly used as the disposable canary)
• Canary PR: https://github.com/Clyra-AI/clyra-test/pull/1
• Mill run: b358b6e3-0385-4c5a-a244-30e5fe181047
• Exact base: 86fc1d3194c0b8063790a506728e50de1e4ef6b7
• Exact candidate: 6521347340a5ea98aeb59d0cb6111d605f28335f
• Exact candidate tree: 30919160e2de67d5d6f2ad65be6a84f5ff7e8285
• Real Codex builder: completed through the operator's logged-in account; provider usage was measured
• Exact-candidate OCI verification: passed using the pinned no-network image
• Independent real Codex review: passed with no findings
• GitHub mutation recovery: the initial push returned an unmatched immediate readback, Mill entered effect_unknown, authoritative readback proved the exact candidate had landed, and pr reconcile verified the effect without another push
• PR delivery: exactly one draft PR was created with the recorded branch, marker, PR node ID, candidate SHA, and tree
• Real GitHub Actions validate: passed on the exact candidate
• Mill authoritative observation: awaiting_human at 2026-09-01T16:46:53.532Z
• The canary PR remains draft and unmerged, as required; Mill did not mark ready, merge, deploy, provision another repository, or rerun checks

Mill landing

• PR head reviewed and validated: d1488117081c54d5be9360065649bf512b77db7c
• Squash-merged result: f9da46b2707638e8ce854220b24d509077446d12
• Post-merge CI: https://github.com/davidahmann/mill/actions/runs/33533899932 — success
• Post-merge CodeQL: https://github.com/davidahmann/mill/actions/runs/33533899747 — success
• Local main is clean and matches origin/main

The merged documentation was frozen before this canary ran, so wording that calls the real-GitHub canary pending is historical pre-promotion state. Reconcile those status lines in the next substantive product wave rather than creating a closure-only PR.