# Reliability: what can stall or take vid2context down

An audit of hang and crash risks per surface, with the file and line where each one lives (line numbers as of 2026-11-15), and what was done about it. "Fixed" means the change and a test are in the tree; "open" means it is known and left for the owner of that code.

Every limit below has an env var with a safe default. They are listed in `.env.example` and [docs/providers.md](https://vid2context.com/docs/providers.md).

## HTTP server (`packages/server`)

| Risk | Evidence | Status |
|---|---|---|
| The timeout middleware answered 504 but left the work running; only `ctx.signal` stops it. | `src/middleware.ts:127` races `next()`; `src/services.ts:142` folds `AbortSignal.timeout` into `ctx.signal` | Fixed earlier (deadline in `ctx.signal`), 499 for client aborts in `src/errors.ts` |
| No cap on concurrent expensive requests (context, transcript, pack, bundle, ask, briefs, MCP tool calls): a burst runs every pipeline at once and exhausts memory, sockets and yt-dlp slots. | routes mount with no limiter, `src/app.ts` | Fixed: `src/concurrency.ts` (`VID2CONTEXT_MAX_CONCURRENT`, `VID2CONTEXT_MAX_WAITING`, `VID2CONTEXT_QUEUE_WAIT_MS`), 503 `busy` with `Retry-After` |
| `/api/v1/health` is liveness only: a container whose storage, disk or binaries are broken still looks healthy. | `src/app.ts:267` | Fixed: `GET /healthz` and `/healthz?deep=1` (also `/api/v1/healthz`) check storage, rungs, disk space, yt-dlp, ffmpeg and the keyless network; 503 when a required check fails (`VID2CONTEXT_HEALTH_REQUIRE`), cached and single-flight (`src/health.ts`, `src/health-node.ts`) |
| Shutdown waited for `server.close()`, which never resolves while an SSE client (job events, MCP GET stream) stays connected, so such deploys ended in the forced `exit(1)`. | `src/node.ts:68` (before) | Fixed: `src/lifecycle.ts` `gracefulClose` gives requests half of `VID2CONTEXT_SHUTDOWN_TIMEOUT_MS`, closes MCP sessions, jobs and downloads, then cuts what is still open |
| An unhandled promise rejection anywhere in the process exits Node 22 and ends every in-flight request. | `src/node.ts` had no handler | Fixed: logged with the stack, the process keeps serving (`VID2CONTEXT_EXIT_ON_UNHANDLED=1` restores the exit) |
| Slow clients (slowloris) could hold sockets; Node's defaults were not configurable and are only checked every 30 s. | `src/node.ts:50` (before) | Fixed: `VID2CONTEXT_HEADERS_TIMEOUT_MS`, `VID2CONTEXT_BODY_TIMEOUT_MS`, `VID2CONTEXT_KEEPALIVE_TIMEOUT_MS`, passed at server creation with a matching check interval |
| Request bodies: JSON routes are capped by `bodyLimit` (`VID2CONTEXT_MAX_BODY_KB`), uploads by `VID2CONTEXT_MAX_UPLOAD_MB`, `/imports` caps its own at 5 MB. `/mcp` and `/oauth/*` are outside `/api/*` and had no cap. | `src/middleware.ts:179`, `packages/mcp-http/src/routes.ts` | Fixed in mcp-http (below) |
| Large transcripts: responses are built in memory (`JSON.stringify`, ETag hash). Bounded by `VID2CONTEXT_MAX_SEGMENTS` (200000) in core, which keeps one response to tens of MB. | `src/http-util.ts` `jsonWithEtag` | Acceptable; no change |
| Single-flight runs use their own timeout signal, so a run nobody waits for any more still runs to its deadline (it fills the cache). | `src/services.ts:206` | Acceptable by design |

## Remote MCP (`packages/mcp-http`) and stdio MCP (`packages/mcp`)

| Risk | Evidence | Status |
|---|---|---|
| `POST /mcp` and the OAuth form posts read the whole body with no size limit. | `src/transport.ts:106`, `src/oauth.ts` | Fixed: `VID2CONTEXT_MCP_MAX_BODY_KB` (default 1024), 413 before the SDK parses |
| Session mode builds the server with no signal, so a tool call has no deadline of its own; only the client's `notifications/cancelled` or the session closing stops it. | `src/transport.ts:132` | Open: needs a per-call deadline inside `@vid2context/mcp` tool wrappers (item 44) |
| Idle sessions are swept (`VID2CONTEXT_MCP_SESSION_IDLE_SEC`), at most 256 kept. | `src/transport.ts` | Fine |
| stdio: no SIGTERM or stdin-close handler; the process exits when stdin ends because nothing else holds the loop. | `packages/mcp/src/bin.ts:32` | Fine; noted |

## Jobs (`packages/jobs`)

Hardened in this round by another session (stall and per-attempt timeouts, a cap on queued jobs, a Retry-After clamp, the slot held on abort); see `packages/jobs` and [jobs.md](https://vid2context.com/docs/guides/jobs.md). Findings from this audit passed to that owner:

| Risk | Evidence | Status |
|---|---|---|
| A handler that never settles and ignores its signal holds a concurrency slot forever. | `src/execute.ts:153` `raceAbort` only rejects on abort | Fixed: the stall watchdog aborts it, the slot is freed after a 5 s grace (`src/watchdog.ts`) |
| On start, every `running` record is requeued, including jobs another live process sharing the store is still running (no heartbeat on the record). | `src/queue.ts:126` | Fixed: running attempts heartbeat every 30 s; a fresh `running` record is watched and taken over only when stale or handed back |
| `enqueue` grows `pending` without bound. | `src/queue.ts:144` | Fixed: `VID2CONTEXT_MAX_QUEUED_JOBS` (1000), then `rate-limited` |
| `close()` aborts running jobs at once instead of draining them. | `src/queue.ts:193` | Jobs owner; the server's shutdown gives it half the grace period before cutting connections |
| Cloud Tasks token, enqueue and JWKS fetches use `ctx.fetch` with no timeout. | `src/cloud-tasks.ts:85`, `:104`, `:200` | Fixed: 15 s deadline, then `timeout` |
| The SSE heartbeat timer writes into the stream without a try; a write after the consumer is gone throws from a timer. | `src/sse.ts:127` | Fixed: a failed write ends the stream |

## yt-dlp provider (`providers/ytdlp`)

| Risk | Evidence | Status |
|---|---|---|
| A request aborted while waiting for a `YTDLP_CONCURRENCY` slot stayed in the wait list; when woken it took the slot and spawned yt-dlp anyway, because an abort listener added after the abort never fires. The process then ran to its full timeout. The wait list was unbounded. | `src/process.ts:54`, `:57`, `:136` (before) | Fixed: waiters leave the queue on abort and slots pass to the next live waiter; spawn checks the signal; `YTDLP_MAX_WAITING` (64) refuses more as busy. Timeout hints name the caller's env var (`timeoutEnvVar`) |
| YouTube changes break extraction until the weekly update check runs. | `src/binary.ts:23` (weekly), `src/errors.ts:90` | Fixed: an extractor error that yt-dlp marks as needing an update ("Confirm you are on the latest version using yt-dlp -U", recorded from yt-dlp 2023.03.04 against YouTube and Vimeo) triggers an immediate checksum-verified update of the managed binary, at most once per `YTDLP_SELF_UPDATE_MIN_SEC` (default 6 h) across processes, and one retry. The hint says whether it updated, was already latest, was too soon, or is a user binary |
| An old binary is invisible until it breaks. | `packages/cli/src/doctor/run.ts` | Fixed: `doctor` and `/healthz?deep=1` warn when yt-dlp is older than `YTDLP_STALE_DAYS` (default 60) |
| Every child has a timeout, kills its process group on abort and caps stdout and stderr. | `src/process.ts` | Fine |

## Rung chain (`packages/core/src/chain.ts`)

Owned by another session in this round. The per-rung timeout (`VID2CONTEXT_RUNG_TIMEOUT_MS`, default 180 s, local rungs exempt) and the stop-on-abort check before each rung are in `chain.ts`. Remaining risk: a timed-out rung's call keeps running until the request signal ends, because `runChain` cannot hand the call a signal of its own without a change to the `call(rung)` signature in `pipeline.ts`.

## STT and LLM providers (not changed here)

| Risk | Evidence | Status |
|---|---|---|
| Most providers use `fetchWithTimeout` (default `VID2CONTEXT_FETCH_TIMEOUT_MS`). | `packages/core/src/context.ts:88` | Fine |
| `stt-transformers` on Node fetches remote audio and runs ffmpeg with only `ctx.signal`, no timeout, and collects decoded PCM without a cap. | `providers/stt-transformers/src/node.ts` | Open, for that provider's owner |
| whisper.cpp and ffmpeg runners have timeouts and kill on abort. | `providers/stt-whisper-cpp/src/exec.ts`, `packages/ffmpeg/src/process.ts` | Fine |

## Storage and web app

| Risk | Evidence | Status |
|---|---|---|
| Storage is opened once per process and shared; a failed open is retried on the next request. | `packages/server/src/services.ts` | Fine; the deep health check now writes and reads a probe key |
| The web app's calls have no client-side timeout and rely on the server's deadline (`VID2CONTEXT_REQUEST_TIMEOUT_MS`). | `packages/web/src/lib/api.ts` | Fine while the server deadline holds |
