[Phase 3] Meet NFR-4 startup latency with prebuilt or cached agent images

[Saber5656]

Background

NFR-4 requires the container to reach an agent-usable state within 10 seconds (project copy excluded). The legacy adapters run npm install -g <agent-package> inside the entrypoint on every session start (cage-demo/src/cli/run.rs:1186, src/adapter/*.rs). A cold start therefore routinely exceeds 10 seconds, varies with network conditions, and makes offline starts impossible. No current issue addresses startup performance, so implementing the issue set as-is produces a product that structurally misses NFR-4.

Scope

• Add a local image bake path: cage images build <agent> (or first-run auto-bake) that produces a cached image with the agent preinstalled, keyed by agent name + version, so subsequent runs skip npm install.
• Wire cage run --rebuild / --no-cache (PRD §11.5) to invalidate that cache.
• Wire cage run --agent-version <ver> (PRD §11.5) to pin the agent package version used for the bake.
• Emit per-step timing in --verbose (create, copy, git init, credential inject, agent ready) so NFR-4 is measurable; add a perf smoke test that is skipped when Docker is unavailable.
• Decide whether publishing prebuilt images (e.g. GHCR) is in scope for pre-alpha; document the decision either way (supply-chain implications belong to [Phase 3] Prepare pre-alpha release packaging #23's release policy).
• Ensure no credentials can end up in baked image layers (bake must happen before credential injection).

Acceptance Criteria

• Warm start (cached image) reaches agent-ready within 10 seconds on a documented reference machine.
• --rebuild, --no-cache, and --agent-version behave as documented.
• Startup latency is observable without a profiler (verbose timing output).
• Baked images contain no credential material.

References

• cage-demo/docs/PRD.md NFR-4, §11.5 (--rebuild, --no-cache, --agent-version)
• cage-demo/src/cli/run.rs entrypoint npm install
• [Phase 1] Implement the Agent Adapter trait and built-in adapters #10 (adapters), [Phase 3] Implement practical cage config, images, and update commands #21 (images command), [Phase 3] Prepare pre-alpha release packaging #23 (release policy)