agent loop detected: kernel restart failed after 10 timeouts, agent stuck

TL;DR

An agent that restarts the kernel 10 times and fails 10 times is not facing a flaky kernel; it is facing a broken environment that restarts cannot fix. Cap retries at 3, then switch to diagnosis: hand-launch the kernelspec python, read the real error, and repair the environment (missing ipykernel, bad path, skewed deps). Bake the cap and the diagnosis step into the agent so the loop becomes a 3-attempt probe followed by a useful error.

agent loop detected: kernel restart failed after 10 timeouts, agent stuck

Use this when

• An agent's kernel management loop retries restarts past any sane count.
• Every restart attempt fails identically and fast.
• You are building or debugging the agent's kernel lifecycle code.

Not for this skill when

• A human clicking restart in a loop. That is a broken env; fix it directly.
• Restarts occasionally fail. That is flakiness; retries are fine there.

Steps

1. Stop the agent's loop and cap retries at 3 in its kernel code. Verify: the agent gives up and reports instead of spinning.
2. Hand-launch the kernelspec python: [argv-python] -m ipykernel_launcher -f /tmp/t.json. Verify: you see the real startup error.
3. Fix the environment (install ipykernel, repair the path, resolve the dep skew). Verify: the hand launch stays alive.
4. Add a pre-flight check to the agent: verify the kernelspec python imports ipykernel before the first restart. Verify: the agent fails fast with the real cause.
5. Re-run the agent. Verify: kernels start on attempt one and the loop is gone.

Variant phrasings

agent kernel restart loop

Short form. Cap retries, diagnose the env.

kernel restart retries exhausted agent

The agent-log phrasing. The env is broken, not the restart.

agent stuck restarting kernel

Symptom phrasing. Three attempts, then diagnose.

Compatibility: Any agent driving jupyter_client/nbclient kernels. The retry-cap pattern is framework-agnostic.

Why it happens

Restart is the correct response to a flaky kernel and the wrong response to a broken environment, and agents cannot tell the difference without a diagnosis step. Ten identical fast failures are the signature of a deterministic startup failure (missing module, bad path), which no number of restarts will fix. The loop persists because the agent's only tool is retry.

Edge cases / pitfalls

• Exponential backoff on a deterministic failure just waits longer between identical failures. Diagnose instead.
• The agent should log the kernelspec and python path on first failure. Without that, the human debugs blind.
• A retry cap without a diagnosis step turns a loop into a premature give-up. Both halves are needed.
• Test the agent against a deliberately broken env. If it loops, the cap is missing.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstDLGlRog55ilaop6gxoR9w