feat: ship durable execution foundations

[simple-agent-manager]

Summary

• Integrates the verified VM Agent foundation through 9c53b61e2 and Worker/ProjectData foundation through 4847cf0b8 onto current main (8c689a6a7), preserving the bounded control-loop protections from Fix runaway-cost and infinite-loop control paths #1777.
• Aligns both runtimes to canonical durable-execution protocol v1: VM-authoritative runtime identity, nested capabilities, stable delivery receipts with epoch-millisecond times, wrapped 202/200 prompt responses, and fail-closed 404/409 reconciliation.
• Adds exact-once checkpoint terminal ownership so cancellation, operation deadlines, delayed process exit, and strict-resume failure cannot fall through to a fresh session or late Ready.
• Scope is foundations only. Supervisor checkpoint episodes, execution-generation fencing, cancel/provision cleanup, wait semantics, terminal-child wake, and parent hibernation remain out of scope.

This draft is open early while full gates, specialist review, fresh-node staging verification, and CI evidence are completed.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test
• Additional validation run: focused API contract/durable-delivery suites (51 tests) and go test -race ./internal/acp
• Candidate-selection control-loop note: this PR preserves current-main Fix runaway-cost and infinite-loop control paths #1777 limits and isolation; it does not expand candidate selection or per-candidate I/O.

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging workflow triggered manually and passed for this branch
• Live app verified via Playwright — logged into app.sammy.party (staging) using test credentials and actively tested the application
• Existing workflows confirmed working — navigated dashboard, projects, and settings; confirmed no regressions in core flows (pages load, data displays, navigation works, no new console errors)
• New feature/fix verified on staging — the specific changes in this PR work correctly on the live staging environment (describe what was tested below)
• Infrastructure verification completed — existing staging nodes deleted first; freshly provisioned VM heartbeat and protocol behavior verified; test resources deleted afterward
• Mobile and desktop verification notes added for UI changes — N/A: no UI changes

Staging Verification Evidence

Pending fresh-node staging verification. Staging will be returned to zero VMs at rest.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified — N/A: no UI changes
• Accessibility checks completed — N/A: no UI changes
• Shared UI components used or exception documented — N/A: no UI changes
• Playwright visual audit run locally — N/A: no UI changes

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

1. ProjectData claims a stable delivery in claimDuePromptDeliveries and dispatches it through runPromptDeliveryClaim.
2. DefaultVmPromptDeliveryAdapter.submit probes /workspaces/{workspaceId}/agent-capabilities, then sendPromptToAgentOnNode serializes protocolVersion and deliveryId on the production request path.
3. VM handleVersionedPromptDelivery durably accepts/claims the receipt before invoking SessionHost.AcceptPrompt; the observer converges it to one terminal receipt.
4. Worker lookupReceiptResult permits replay only for a positive same-runtime not_found; changed or unproven runtime returns ambiguity.
5. VM CheckpointRollover and monitorProcessExit share one exact-once episode outcome; a terminal winner suppresses delayed restart and later Ready.

Untested Gaps

Fresh-node live protocol verification is pending and blocks readiness.

Post-Mortem (Required for bug fix PRs)

What broke

The prior integration was lost with its workspace. The surviving foundations also disagreed on the prompt-delivery wire contract, and checkpoint deadline/cancellation could lose ownership to delayed process-exit restart.

Root cause

The Worker negotiated durable delivery but omitted protocolVersion and deliveryId from the real JSON request body. Independently, checkpoint failure cleared or failed to durably claim the rollover episode before process.Stop/process.Wait races.

Class of bug

Cross-component contract drift plus asynchronous terminal-ownership race.

Why it wasn't caught

Mocks asserted adapter intent without inspecting the real HTTP body, and checkpoint tests let Stop immediately release Wait, hiding the delayed-exit ordering.

Process fix included in this PR

Exact shared Worker/VM contract fixture and production-path request-body assertion; deterministic delayed-Wait race tests under Go's race detector. Documentation/rule sync remains under specialist review.

Post-mortem file

tasks/active/2026-08-09-integrate-durable-execution-foundations.md

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human — N/A while review is pending; draft will not merge

Reviewer	Status	Outcome
task-completion-validator	PENDING	Phase 5 pending
go-specialist	PENDING	Phase 5 pending
cloudflare-specialist	PENDING	Phase 5 pending
constitution-validator	PENDING	Phase 5 pending
doc-sync-validator	PENDING	Phase 5 pending
test-engineer	PENDING	Phase 5 pending

Exceptions (If any)

• Scope: None.
• Rationale: N/A.
• Expiration: N/A.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

Canonical ready idea 01KZK586BN98BRDGKC44V12HT0, all read-only state from cancelled mission 6009d56f-9a80-4f29-aef6-fcf498edc721, and the surviving exact foundation commits were read before implementation. No third-party API behavior changed.

Codebase Impact Analysis

Affected: apps/api ProjectData delivery/alarm ownership and VM adapter; packages/shared contract types/constants; packages/vm-agent persistence, HTTP handlers, and ACP process lifecycle; migrations/tests/docs. Current-main control-loop budgets and kill switches are retained.

Documentation & Specs

Task/research file added. Durable-execution docs and rule synchronization remain under Phase 5 review.

Constitution & Risk Check

Checked no-hardcoded-business-values, exact-once ownership, append-only migration safety, control-loop I/O budgets, alarm isolation, fail-closed runtime identity, credential-free wire fixtures, legacy rollout compatibility, and zero-VM staging cleanup.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/resume-ship-durable-execution-5cdf7a (27f6a6d) with main (8c689a6)}

[sonarqubecloud]

Quality Gate passed

Issues
32 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.3% Duplication on New Code

See analysis details on SonarQube Cloud