## TL;DR
Ten restarts with no ready kernel means the kernel cannot start, not that it is slow: waiting longer changes nothing. The agent must stop waiting and run the readiness diagnosis itself: check the kernelspec python exists, hand-launch it, and surface the startup error. Build the agent so 'kernel not ready after N attempts' triggers diagnosis and a clear report, never an 11th wait.

```text
agent timed out waiting for kernel ready after 10 restarts, kernel failed to come up
```

## Use this when
- An agent waits for kernel readiness, restarts repeatedly, and never gets a ready signal.
- Each attempt fails fast (not slowly).
- You own the agent's kernel lifecycle code.

## Not for this skill when
- The kernel becomes ready but slowly. That is a timeout-sizing issue.
- A human waits in the UI. That is a broken env; fix it directly.

## Steps
1. Confirm the pattern: attempts fail fast and identically. Verify: it is deterministic, not flaky.
2. Hand-launch the kernelspec command in a terminal. Verify: you see the real startup error.
3. Fix the environment (missing ipykernel, bad python path, dep skew). Verify: the hand launch stays alive and a manual ready-check passes.
4. Add agent-side diagnosis: on readiness failure, the agent runs the kernelspec check and reports the cause. Verify: the next failure produces a diagnosis, not a timeout.
5. Cap the wait: N attempts then diagnose, never infinite. Verify: the agent's worst case is a clear error.

## Variant phrasings
### agent kernel never ready timeout
Short form. Diagnose, do not wait longer.

### kernel ready wait failed agent
The lifecycle phrasing. Fast identical failures mean broken env.

### agent restart kernel not coming up
Symptom phrasing. Hand-launch the spec.

Compatibility: Any agent using jupyter_client kernel management. The diagnosis pattern is framework-agnostic.

## Why it happens
Kernel readiness is a handshake: the kernel process starts, connects its channels, and replies. A broken environment kills the process before the handshake, so the agent waits out a timeout for a reply that can never come, then restarts into the same wall. Ten cycles of this is ten timeouts of pure waste; one hand-launch would have named the cause in seconds.

## Edge cases / pitfalls
- Lengthening the readiness timeout is the wrong fix for fast failures. It only helps slow-but-working kernels.
- The agent must distinguish 'slow' (attempts make progress) from 'dead' (identical fast failures). Log attempt outcomes.
- A kernelspec pointing at a deleted env is the most common cause. Reinstall specs after env changes.
- Report the kernelspec path and python in the agent's error. The human needs those to fix it.

## Provenance

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