docs: plan the AgentCore Runtime V2 migration

[philmerrell]

Summary

Docs only. This turns the review-queue entry "A/B the V2 AgentCore Runtime in dev" (Proposal 1 in reviews/2026-09-25.md) into a plan: docs/specs/agentcore-runtime-v2.md. It combines what the 2026-09-18 announcement says with findings checked against AWS and our tree. The queue entry now points at the spec.

What the spec establishes

• Gate 1 is answered. The CloudFormation schema for AWS::BedrockAgentCore::Runtime accepts PlatformVersion, and the property is not create-only. Flipping it is an in-place update, so the runtime ID in SSM does not rotate. The dev runtime currently reports V1.
• Blocker B1: backend deploys could revert V2. scripts/build/deploy-runtime-image-if-changed.sh rebuilds a full-replacement update-agent-runtime payload from an allow-list, and platformVersion is not on it. Each backend.yml run could put the runtime back on V1 until the next platform.yml, which would contaminate the A/B without anything failing. This needs fixing before the flag goes on.
• Risk B2: V2 clones startup state into every session. V2 starts each session by restoring a snapshot of the running container, so anything computed at import time is copied into every microVM. The concrete case is runtime_health.py, which stamps its idle clock at import. A restored instance would report a /ping time from when the snapshot was taken. The spec also covers warm-up placement, sockets opened at startup, random-number state, and the OTEL instance ID.
• B3: the planned metric can't see the improvement. The turn-latency EMF starts at handler entry and cannot see a Runtime cold start, so cold starts have to be measured client-side (tests/load).
• Cost model. V2 bills the memory a session actually uses instead of the peak. That changes the trade-offs behind the idle reaper and the in-process caches, and it moves the basis for the W5 instance-SKU arithmetic.
• Plan. In order: the deploy-script fix, then a flag that always sets PlatformVersion explicitly (V1/V2) so rollback is a deterministic in-place update, then idle-clock hardening, then the dev A/B.
• Phase 2 (§5a). Start the conversation's microVM when the user starts typing, using the staged session ID the SPA already creates and a no-op /invocations warm action. V2 only, because V1 bills idle microVMs at peak memory.

Reviewer notes

• No code changes. Everything here is verified, asserted or hypothesis, and each claim in the spec says which.
• aws-cdk-lib 2.270.0 and our boto3==1.43.68 pin do not know platformVersion yet. The dev check read the upstream botocore model through AWS_DATA_PATH; nothing was installed.
• A feature/agentcore-runtime-v2-flag branch already exists at the develop tip with no commits. The spec says to reuse it or delete it.

🤖 Generated with Claude Code