fix: unify agent installation across runtimes

[simple-agent-manager]

Summary

• Adds a pinned structured install manifest synchronized in CI with the Go runtime table, TypeScript catalog, and cf-container image.
• Pre-bakes all six catalog agents into a Node 22 cf-container image; migrates Claude ACP and Amp to maintained packages.
• Adds standalone-only rootless npm/uv paths, generalized npm cleanup, and persistent user-visible selection failures.

Validation

• pnpm lint (0 errors; existing warnings only)
• pnpm typecheck
• pnpm test (including 5,894 API tests)
• pnpm build
• Focused Go ACP/session tests
• Local Docker image build and non-root runtime audit

Image size: 735,871,006 bytes. All catalog binaries resolve as uid 1000; a real non-root global npm fallback install succeeded under SAM_AGENT_HOME.

Staging Verification

Intentionally skipped by explicit user instruction. No staging deployment or mutation was performed. This PR must remain unmerged until the user later authorizes the next step.

End-to-End Verification

Manifest -> CI sync checker -> pinned Go install commands and Docker pre-bake. Agent-selection failure -> in-memory session error transition + persisted system chat message + existing BootLog/error reporter. Local Docker exercised the actual image boundary.

Post-Mortem

What broke

The first Codex instant session failed before producing output because runtime installation ran non-root against root-owned global paths.

Root cause

The cf-container image pre-baked only Claude while all other agents used root-oriented on-demand installers, and the TS/Go install sources had drifted.

Class of bug

Runtime capability and installation-source drift across execution environments.

Why it was not caught

No CI contract required every catalog agent to appear in the runtime installer and instant-session image.

Process fix included

quality:agent-install-manifest now blocks catalog/Go/image drift in CI.

Post-mortem file

tasks/archive/2026-07-11-unified-agent-installation.md

Specialist Review Evidence

• All local reviewers completed and findings addressed before merge
• Local reviewer processes were interrupted; needs-human-review is required and merge is deferred

Reviewer	Status	Outcome
task-completion-validator	FAILED	Local reviewer process interrupted; direct checklist applied
go-specialist	FAILED	Local reviewer process interrupted; direct checklist applied
cloudflare/constitution/test review	FAILED	Local reviewer process interrupted; direct checklists applied

Exceptions

• Scope: Staging verification and merge
• Rationale: Explicit user instruction forbids staging and production merge
• Expiration: Until later explicit authorization

Agent Preflight

• Preflight completed before code changes

Classification

• cross-component-change
• business-logic-change
• infra-change

External References

Official npm and PyPI registries were queried for current package pins.

Codebase Impact Analysis

packages/shared, packages/vm-agent, apps/api/Dockerfile.vm-agent-container, and CI quality checks.

Documentation & Specs

Internal task/archive and existing binary-install hardening backlog were updated; no public UX contract changed.

Constitution & Risk Check

Principle XI checked. Package versions are intentionally immutable supply/build inputs governed by one manifest, not deployment configuration. Primary risk is image growth; measured at 0.736 GB versus the 8 GB runtime disk budget.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/01kx8tmybbc103w1dr1vg61h33-take-look-idea-dt8mdw (005e513) with main (d202d2d)}

[sonarqubecloud]

Quality Gate failed

Failed conditions
E Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

💡 Need a hand with PR review? Try Gitar by Sonar!