## TL;DR
An agent that starts a papermill run and waits forever is missing two things: a per-run timeout and the ability to interrupt the kernel. Set papermill's execution timeout so hangs become named failures, and give the agent a kernel-interrupt action it can use when progress stalls. The agent's run loop should watch cell progress (execution counts advancing) and treat a stalled count as a hang, not as patience.

```text
agent's papermill run hung on a cell the agent never interrupted, agent stuck waiting
```

## Use this when
- An agent's papermill invocation hangs and the agent waits indefinitely.
- The agent has no interrupt capability in its toolset.
- Runs hang on cells with loops, sleeps, or blocking I/O.

## Not for this skill when
- A human's papermill hangs. Set the timeout and interrupt it yourself.
- The run fails fast. That is a bug, not a hang.

## Steps
1. Set an execution timeout on every agent-driven papermill run. Verify: a hung run now fails with the cell named.
2. Give the agent a kernel interrupt tool (interrupt_kernel via the client). Verify: the agent can interrupt a test hang.
3. Add progress watching: the agent checks execution counts or log output periodically. Verify: a stalled count is detected within minutes.
4. Define the hang policy: interrupt once, then fail the run with the cell source attached. Verify: the policy triggers on a synthetic hang.
5. Fix the underlying hanging cell (loop guard, timeout, event wait). Verify: the run completes without needing the policy.

## Variant phrasings
### agent papermill hang no interrupt
Short form. Timeout plus interrupt tool.

### papermill run stuck agent waiting
The symptom phrasing. Watch progress, not just completion.

### agent cannot interrupt hung cell
The capability phrasing. Add the interrupt action.

Compatibility: papermill 2.x, jupyter_client kernel management. The pattern fits any agent framework.

## Why it happens
Papermill's default is to wait forever, and an agent without an interrupt tool inherits that default with no escape hatch. Humans interrupt hung cells reflexively; agents need the capability explicitly built and the policy for when to use it. Without both, the agent's run loop is a fancy way to wait forever.

## Edge cases / pitfalls
- An interrupt that the agent never uses is decoration. The progress watcher is what triggers it.
- Interrupting and retrying the same hanging cell loops forever. Interrupt once, then fail and report.
- The timeout must be generous enough for legitimately slow cells or the agent will interrupt real work.
- Log the cell source on hang. The human fixing it needs to see the code, not just the cell number.

## Provenance

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