perf: bake vm-agent into instant container image to cut cold-start latency

[simple-agent-manager]

Summary

Materially reduces instant Cloudflare Container cold-start latency by removing the per-container network install of vm-agent and baking the deployment-built binary into the runtime image. It also adds bounded phase timings so the remaining latency is attributable.

Key changes:

• Builds/version-tags Linux AMD64 vm-agent before Wrangler deploy, then copies the binary and vm-agent-version.json into Dockerfile.vm-agent-container.
• Removes the mandatory fresh-container download; bootstrap validates the baked binary/version, emits secret-free timing/version telemetry, and fails fast if either artifact is absent.
• Adds totalDurationMs, preContainerDurationMs, and containerLaunchDurationMs, while retaining deprecated response aliases for compatibility.
• Preserves PR Runtime-neutral env/file/secret injection for instant cf-container ACP #1561's runtime-assets boundary: user/project/profile/skill files and secrets are still resolved only at ACP session start and never enter image layers or launch configuration.
• Adds behavioral, contract, timing, cleanup, no-secret, version-parity, and deploy-ordering coverage.

Validation

• True linear rebase onto ad7044fde (PR Phase 3a: runtime-neutral session hibernate/wake #1562); rebased tree matched the reviewed merge resolution
• pnpm lint
• pnpm typecheck
• pnpm test (404 API files / 5,918 tests; 217 web files / 2,668 tests)
• pnpm build
• /usr/local/go/bin/go test ./... with Go 1.25.0
• Targeted cold-start tests (16 API + 7 deploy-workflow)
• Actual container-image build and normal-entrypoint probe; /health returned healthy and baked bootstrap-ready telemetry emitted in 3 ms

Staging Verification (REQUIRED — merge-blocking)

• Staging deployment green
• Live app verified
• New feature verified with a genuinely fresh container and real ACP response
• Temporary staging resources cleaned up
• N/A: no UI-visual changes — backend and infrastructure only

Staging Verification Evidence

Deployment run 29185746568 passed Cloudflare deploy, backup/count baseline, migration integrity, API health, and Playwright smoke tests. It deployed implementation commit fc22f3e80c8ab436cab63e3e50fdf1008b24554c with baked artifact sha256:3653de9b288c7bed684b72dc84fd0f033835f0170cf19e58a479b9984554e949 and VmAgentContainer image digest sha256:b50c3fb289b42c39284ea07dd85f7af073119953aeaf4b6ee7a53dba1a04d408.

A fresh launch created node 01KXAQFTDZBGFGPX5XZ0RSYTC9, workspace 01KXAQFTJW9YVZCVB1A8T5JXJP, and session 1637b2b0-a9cb-4e56-b0ad-5c7733dc4fa1. The API returned HTTP 201 and the agent completed a real response.

Measurement	Baseline	PR #1566	Change
Server-side total	16,674 ms	9,161 ms	-7,513 ms / 45.1%
Client-observed request	—	13.408 s	—

Post-change phase slices: pre-container 724 ms; container launch 2,584 ms; agent-ready 567 ms; workspace create 2,898 ms; ACP session create 2,237 ms; ACP session start 842 ms.

Authenticated browser checks for dashboard, the new session, and project agent settings all returned HTTP 200. Session content rendered with no unexpected console, page, or network errors. The API health endpoint returned HTTP 200/healthy. The temporary session was stopped; staging D1 confirmed the node was deleted and its workspace row removed.

The result is materially improved but remains above the <5s target. Evidence and the next dominant slices (workspace creation, container launch, ACP creation) were appended to SAM idea 01KX6JK8ZFC1EFWGYQENRMFWFK rather than claiming the target was met.

End-to-End Verification (multi-component)

• Build/deploy path verified: workflow → Go build/version metadata → Docker context → Wrangler container image
• Runtime path verified: container bootstrap → baked artifact validation → vm-agent ready → workspace/ACP creation → real agent response
• Security boundary verified by negative contract tests and staging launch configuration
• Cleanup path verified through product API and staging D1
• pnpm quality:observability-noise found no significant noise; D1/Workers telemetry subchecks were explicitly unavailable in this environment

Specialist Review Evidence (agent-authored PR)

• All local reviewers completed and findings addressed

Reviewer	Status	Outcome
cloudflare-specialist	ADDRESSED	Local Docker prerequisite documented; timing aliases deprecated; minor DB-write timing note accepted
test-engineer	ADDRESSED	Added no-secret assertions, executed bootstrap tests, timing invariants, failure cleanup, and version-shape tests
security-auditor	ADDRESSED	Secret boundary held; version parity and negative contracts added; runtime re-hash declined because it adds cold-path cost without a separate trust root
doc-sync-validator	ADDRESSED	Architecture and API/self-host docs synchronized
env-validator	PASS	Go setup ordering and version parity covered
go-specialist	PASS	Portable sha256sum/shasum fallback added
constitution-validator	PASS	No hardcoded business values introduced
task-completion-validator	ADDRESSED	Research/checklist/diff/criteria paths covered; staging vertical slice documented; only merge/production monitoring remains intentionally open

No reviewer is pending or failed. All CRITICAL/HIGH findings were addressed.

Post-Mortem

N/A: performance and observability improvement, not an incident fix.

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

N/A: this uses the repository's existing Cloudflare Containers, Wrangler, Go, and Make deployment path.

Codebase Impact Analysis

• Workflow and Makefile generate/version the container binary before Wrangler deploy.
• Dockerfile/bootstrap consume and validate the baked artifact without embedding runtime secrets.
• Instant-session API and web response type expose bounded timing fields with compatible aliases.
• Contract, behavioral, workflow, Go, and staging E2E verification cover the affected boundaries.

Documentation & Specs

Updated architecture overview, API reference, and self-hosting guide for baked artifact/version behavior.

Constitution & Risk Check

Generated version metadata derives from the deployment commit; artifact paths remain configurable; no new manual secret or environment prerequisite was added. Missing/mismatched baked artifacts fail fast and are observable rather than silently downloading on the cold path.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/priority-4-materially-reduce-dg2m5w (7c2ec9f) with main (ad7044f)}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud