Eager OCI digest resolution of external sub-agents adds ~2s each per launch; @sha256 pinning works but is undocumented

[aheritier]

Summary

External sub-agents referenced by tag (e.g. name:docker/foo:latest, or a bare docker/foo which defaults to :latest) are resolved EAGERLY at every docker agent run, even for sub-agents that are never invoked in the session. Each unpinned ref forces a registry digest HEAD on startup — measured at ~2.1s and ~1.7s for two sub-agents in our multi-agent config (~3.8s of network-bound startup tax), and it's a path that can hang when the registry/credential helper misbehaves (cf. #2972).

Pinning the reference to an immutable digest (docker/foo@sha256:…) resolves it from cache with zero network and removes the hang risk. This works today — but it is NOT documented anywhere, and every example in the docs/schema uses an unpinned tag.

Environment

• macOS (Apple Silicon), Docker Desktop
• docker-agent build: v1.75.0-16-g5b99da51d (commit 5b99da5)
• Config: multi-agent YAML with two external OCI sub-agents (docker/gordon, docker/grafana-agent)

Steps to reproduce

1. Define an agent with an external sub-agent by tag, e.g. sub_agents: ["x:docker/foo:latest"].
2. docker agent run config.yaml — observe a registry digest HEAD on startup before the TUI, even if x is never used.
3. Re-run with sub_agents: ["x:docker/foo@sha256:<digest>"] — startup no longer hits the registry for that ref.

Measured impact (warm/healthy cache)

• gordon:latest digest HEAD: ~2.1s/launch
• grafana-agent:latest digest HEAD: ~1.7s/launch
• Pinned @sha256: zero-network cache hit

(Compounds with #2972: this is one of the paths that can wedge on a stuck credential helper.)

Requests

1. Docs: document @sha256: digest pinning for sub_agents (and other external OCI refs), and note that tag/:latest refs incur a per-launch digest HEAD. Recommend pinning for reproducibility + startup speed. Affected pages: configuration/agents, concepts/multi-agent (External Sub-Agents), and the schema sub_agents description.
2. Behavior (optional): consider an on-disk digest cache with a short TTL so even tag refs avoid a registry round-trip on every quick restart; and/or a brief WARN when an unpinned external sub-agent ref is resolved at startup.

Workaround (works today)

Pin every external sub-agent to its digest:

sub_agents: ["gordon:docker/gordon@sha256:44117e73263afa5c861bdf3730dae7925918ffdd146827eee5bcff20bc55e8fa"]