Problem

On docker/macOS CI runners the keploy-agent container intermittently stalls at startup — it produces no logs and never reports healthy — so AgentClient.Setup waits the full agent-ready timeout (330s) and gives up. It's nondeterministic (~37% on the macOS python-docker lanes, and it recurs on main with unchanged code), so one wedged container turns an otherwise-green run red.

Two defects made this both unrecoverable and undiagnosable:

• Leak: the readiness-timeout branch returned before the if err != nil { stopAgent() } cleanup defer was in scope, so the wedged agent container and startAgent's goroutine leaked (the leaked context is a.agentCancel, which the readiness poll's own context never touches).
• Black box: nothing captured the agent container's own logs, so a failure was 330s of silence then a generic error — no way to tell a docker run/container-start stall from an in-agent hang.

Fix

1. On the readiness timeout: dump the agent container's docker logs + state (logAgentContainerDiagnostics, best-effort, 15s-bounded), call stopAgent() to tear the wedged container down (fixes the leak), and return a new pkg.ErrAgentNotReady sentinel.
2. pkg.RetryAgentSetup retries the bring-up up to 3× only on ErrAgentNotReady. A fresh Setup re-draws ports and regenerates the agent container, which is what clears a nondeterministic runtime stall. The readiness poll happens before any app/proxy is started, so a retry only re-brings-up the agent — the test set still runs once, against a healthy agent. Deterministic failures (missing privileges, bad config) don't match the sentinel and return immediately; a cancelled context stops the loop.
3. Retries pass a shorter SetupOptions.AgentReadyTimeout (120s): attempt 1 keeps the full slow-start budget (for the legitimately-slow ~126s cold start that 330s exists for), but a fresh agent is ready in ~1–2s, so a wedged retry is cut short. Worst case is bounded at 330+120+120s instead of 3×330s.

This retries the agent infrastructure, never a test assertion — a genuine test failure still fails on the first attempt.

Scope (deliberate)

• The leak fix + diagnostics live inside Setup, so they apply to every caller (record, replay, keploy mock, runner).
• The retry wraps the record/replay Instrument bring-up — the path that hits this stall. keploy mock and runner remain single-attempt (they still get the leak fix + diagnostics).
• The docker-compose per-test-set readiness path is out of scope: Setup skips the readiness poll for compose, so it never returns the sentinel. The observed failure is the plain-docker run poll inside Setup, which this covers. If the stall ever reproduces on a compose lane, those bare-error waits (record.go/replay.go/runner.go) would need the same treatment.

Tests

pkg/retry_agent_setup_test.go verifies: single call on success; retry only on the wrapped sentinel; no retry on a deterministic error; bounded attempts; and immediate stop on context cancellation. go build ./pkg/..., go vet, and the touched-package suites are clean.