## TL;DR
One fixed timeout for every scan is the bug. Give the agent heartbeat checks: each scan declares what progress looks like (output growth, new findings, tool-specific markers), and the timeout becomes "no heartbeat for N minutes" instead of "total runtime over N minutes". Slow scans survive; dead ones get killed fast.

```text
agent failed to handle slow timeout during authorized scan orchestration
```

## Use this when
- The agent kills slow-but-healthy scans because a single global timeout expired.
- The agent waits indefinitely on scans that stopped producing anything.
- Different scan types (port scan, web crawl, fuzzing) all share one timeout value.

## Not for this skill when
- A single tool hangs with zero output from the start. That is a tool hang, not an orchestration problem.
- The tester set the timeout deliberately and the agent obeyed it. That is following instructions.
- Scans complete fine and the issue is result quality. Different problem.

## Steps
1. Define a heartbeat per scan type before the run: for nmap, output file growth; for a crawler, new URLs queued; for fuzzing, requests completed. Verify: each scan in the plan has a named heartbeat metric.
2. Replace the fixed total timeout with a heartbeat timeout: kill the scan only after N minutes with no heartbeat (start with 10). Verify: a slow-but-progressing scan runs past the old fixed limit without being killed.
3. Check heartbeats on a timer, not just at the end: the agent samples each running scan every few minutes. Verify: the run log shows one heartbeat line per scan per interval.
4. On a missed heartbeat, first try the cheap recovery (narrow the scope or restart the stage) before killing the whole scan. Verify: the recovery attempt is logged before any kill.
5. Record the final disposition of every scan (completed, heartbeat-killed, scope-reduced) in the run notes. Verify: the notes explain every scan that did not run to completion.

## Variant phrasings
### agent kills slow scans too early
Same heartbeat fix.
### one timeout for all scan types
Orchestration phrasing.
### agent cannot tell slow from stuck scans
Diagnostic phrasing.

Compatibility: harness-agnostic. Heartbeats only need the agent to read output files or tool progress on a timer.

## Why it happens
Fixed timeouts are easy to configure and wrong for heterogeneous work: a full-port scan and a quick service probe have nothing in common except that both are "scans". The agent cannot distinguish "slow" from "stuck" without a progress signal, so it either kills good work or babysits dead work. Heartbeats give it the signal it was missing.

## Edge cases / pitfalls
- Some tools buffer output and look dead while working. Learn each tool's flush behavior before choosing its heartbeat metric, or healthy scans get killed.
- Heartbeat intervals that are too tight add overhead and false kills on bursty tools. Start loose and tighten from real data.
- A scan that needs its timeout raised repeatedly is telling you the scope is too big. Shrink the scope instead of raising the limit forever.

## Provenance

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