feat(compute): add Lambda MicroVM P3 approval lifecycle

[isadeks]

P3 lets an agent wait for human approval while its MicroVM sleeps or retires with a checkpoint. A later decision wakes the original worker or admits one replacement with the saved conversation and workspace. Unanswered approvals remain available by default.

Linear users can now reply approve or deny directly under the approval comment. The linked task owner’s reply applies to that exact request, is recorded atomically, and receives an acknowledgement in the same thread. Approval permits the pending action once. CLI decisions remain available on all backends; sleep and replacement are MicroVM-specific.

Area

• cdk — infrastructure, handlers, constructs
• agent — Python runtime / Docker image
• cli — bgagent client
• docs — guides or design sources
• tooling — shared-contract checks and artifact packaging

Related

Implements ADR-021 P3 for #645, including remaining P2 prerequisites. Related follow-ups: #817, #841 and #857. AgentCore remains the default compute backend.

Changes

• Add approval-aware suspend/resume supervision, guest activity barriers, explicit lifecycle connection closure, image capability checks, credential renewal and correlated failure diagnostics.
• Preserve unanswered approvals without default expiry; support explicit deadlines, cancellation feedback, a 600-second sleep delay and task/deployment sleep controls.
• Save versioned, checksum-verified conversation and workspace checkpoints. Confirm retirement before releasing capacity, admit one replacement and restore the pending action with its usage and ownership.
• Harden payload bootstrap, launch recovery, task-scoped permissions, capacity accounting and cleanup across compute paths.
• Move MicroVM resources into a nested stack with a compatibility mode for existing flat deployments; pin image versions.
• Enable MicroVM guests to use the existing Linear AgentCore Identity vault grant.
• Add native Linear decisions with owner/workspace/issue checks, durable comment bindings, retry-safe decision recording and notifications. Bundle the current Lambda/MicroVM SDKs for reply-triggered wake and recovery. Approval notices lead with the action and one-call decision meaning; technical IDs follow, and incomplete argument previews are labeled.

Validation

• Real retained Linear tests passed for MicroVM approve, MicroVM deny, AgentCore approve and AgentCore deny. Both MicroVMs were observed suspended before replying and completed after waking. Each approval allowed exactly one read; denials allowed no successful read. Verified the exact reply as decision source, same-thread acknowledgement, terminal worker state and eventual capacity release. The existing Identity vault grant still worked and shared configuration remained unchanged.
• Repeated all four live cases after the message update (4ffe36ee): verified the rendered action summaries, default ten-minute sleep, same-worker wake and scheduled capacity release. Notification/fanout unit tests 202 passed, plus compile and targeted lint.
• Live testing found Linear rejects UUIDv5 comment IDs. Corrected deterministic IDs to UUIDv4 format, deployed the fix and redrove the original persisted notification events; no approval rows were manufactured.
• Native approval focused suite: 502 tests passed. After the final UUID/SDK fixes, 34 thread/reply tests and 20 construct tests passed, plus TypeScript compile, targeted lint and actual bundle checks. Documentation links and commit-range secret scan passed.
• Latest full build: agent 2,170 passed / 13 skipped, CLI 1,005 passed, CDK 5,545 passed / 4 failed / 56 skipped. Compile, lint, contracts, docs and synth passed. Three failures are the resource-budget checks below. The fourth was a temporary VPC tree.json read failure; its isolated rerun passed 18/18 without a code change. The earlier github-tags failure did not recur.
• Commit-range secret and error-masking scans against upstream/main passed.
• Earlier live acceptance also covered expiry/cancellation, retirement/replacement, repeated sleep/wake, AWS access after credential expiry, sleep-off and compatible rollback. These runs validate their recorded configurations, not every deployment or upgrade.

The reproducible cloud test harness, raw receipts and retained Linear issue links stay outside this public PR. The verification guide contains the sanitized acceptance requirements.

Before marking ready

• Complete reusable flat-to-nested migration commands and independently verify upgrading a current-main deployment. The earlier deployment-specific migration is not portable upgrade acceptance.
• Restore the 490-resource budget: ECS + Gateway + Linear vault has 493, imported/managed MicroVM + Gateway + Linear vault has 492 each. Keep the cushion assertion unchanged.
• Obtain a green full build on the final integration commit, including checking the intermittent VPC test failure.

Deployment notes

Re-bootstrap to bundle 1.9.0 or later. Upgrade coordinator and rebuilt guest image together, and enable automatic suspension after checking compatibility; the deployment gate defaults off. Once enabled, the default approval sleep delay is ten minutes. Retain a compatible coordinator/image rollback pin.

Existing flat deployments must keep microvm_nested_stack=false until migration is complete. The recorded migration creates overlapping resources, switches consumers and drains old workers before deleting old resources. Portable migration commands and independent upgrade acceptance remain open above.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution under the terms of the project license.