**TL;DR:** Don't poll the port - watch the log for the Ready line. When workerd crashes during startup, some wrangler versions never surface the error and the CLI just waits, so an agent polling HTTP hangs forever. Run `wrangler dev` with debug logging captured to a file, wait for the Ready line with a hard timeout, and treat a missing Ready line as a startup crash. The first exception in the log is the real bug.

```text
agent timed out waiting for workerd local dev server to become ready, startup failed silently
```

## Steps

1. Start dev with logs captured: run `wrangler dev --log-level debug` with stdout and stderr going to a file. Expected: every workerd message lands in the file, nothing is lost when the agent's own timeout kills the process.
2. Poll the log file for the Ready line (wrangler prints one when the local server is up), not the port for HTTP responses. Give it 90 seconds. Expected: the Ready line appears, or the 90 seconds expire with evidence in hand.
3. If no Ready line, read the log from the top and find the first exception, especially anything during module evaluation or an "Uncaught" error. Expected: you find the throw site. Fix that code - don't lengthen the timeout.
4. Check the entrypoint exports a handler: the worker module must export a default object with a fetch function (or a scheduled handler for cron workers). Expected: the export exists and is shaped correctly.
5. Check for a top-level await that never resolves, like awaiting a network call at module scope. Expected: no hanging top-level awaits. Module evaluation must complete for the server to become ready.
6. Rule out a port conflict: start dev on a different port with `wrangler dev --port 8788`. Expected: if the Ready line appears there, something else on your dev machine already holds the default port.
7. Build the readiness probe as: watch the log for Ready, hard cap, kill the process on timeout, and report the last 50 log lines. Expected: no more silent hangs - every timeout ships the evidence needed to fix it.

## Use this when
- `wrangler dev` never prints its Ready line and the port stays closed
- the agent's wait-for-dev step times out with an empty error log
- workerd seems to exit at startup without an error message
- local dev hangs but the same worker deploys fine

## Not for this skill when
- dev starts but requests fail - that's a runtime bug, not a startup failure
- you're using remote dev mode (that goes through a tunnel, different failure shape)
- the port conflict prints a clear "already in use" error - just pick another port
- deploys fail - startup and deploy are different paths

## Variant phrasings
- wrangler dev hangs on startup with no output
- workerd failed to start silently in local dev
- local dev server never becomes ready
- agent waits forever for wrangler dev

## Why it happens
workerd startup crashes don't always propagate through wrangler's error reporting - the CLI ends up waiting on a ready signal that never arrives. Agents usually poll the HTTP port, which stays closed and teaches them nothing, while the actual exception sits in a log stream nobody captured.

## Edge cases
- Debug logging is verbose. Grep for Ready, Uncaught, and error rather than reading it all.
- A worker that only exports a scheduled handler never serves HTTP. Probe the log, not the port.
- On some machines a firewall or VPN holds the port open without serving. The different-port test distinguishes this.
- If the log file itself is empty, the process died before logging started - check how the agent spawns subprocesses.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_CvfWpLlpvOh-NOykoFi4SQ