---
name: od-overload
description: Resource overload incidents — CPU/RAM/disk-IO saturation, runaway processes, fork storms, cache thrash, laptop freeze. Triggers on load, OOM, swap, iowait, 100% CPU, slow desktop, confine/harness scopes eating the box, admission-queue backlog, npm/build installs pinning laptop. Invoke BEFORE killing anything.
---

# Resource overload — incident playbook

audience: AI coding agents first. BLUF: measure → identify owning cgroup → kill scope → route compute off laptop. NEVER kill by process name.

## Covers

**Absorbs:** `cpu-load`, `memory-load`, `disk-io-load`, `runaway-process`, `disk-cache-fatigue`.

**Keywords:** cpu, load, oom, memory, swap, ram, runaway, fork bomb, disk io, iowait, thrash, saturation, throttle, 100%, freeze, slow, cache, concurrency.

**Registry coverage:** 59 of 217 complaint records (2026-08-08). Dominant shape: non-interactive agent/build work on laptop; killing visible agent useless — daemon respawns; multiple `confine-*` / `v2-*` scopes concurrent.

## Doctrine

Measure first. Kill by cgroup scope, NEVER by process name. NEVER bypass admission queue.

## First steps — stop at first rung that explains load

1. **Measure:** `uptime`; `systemctl --user list-units 'confine-*' 'v2-*' --all`; per-scope CPU/mem (`systemctl status` or cgroup files). No numbers → no kill.
2. **Inventory:** `deckctl agents list` — laptop vs buildbox scopes, owning run/seat id. `local > 0` during heavy work = placement failure.
3. **Classify owner:** harness run, factory seat, npm install, browser e2e on laptop, queue backlog. Each has different fix path.
4. **Contain:** `deckctl agents stop --all` OR `systemctl --user stop <scope>` on the hot scope. NEVER `pkill`, NEVER `killall`.
5. **Route:** headless compute → buildbox (`seat-remote`, `e2e-remote`, admission queue). Read `docs/specs/2026-08-06-execution-plane-insulation.md` — laptop is terminal, not compute node.
6. **Repro before fix:** same command that caused saturation; artifact = measured before/after + fix sha or config change.

## Never-touch — applies here

From `modules/workstation/claude/incidents/never-touch.md`:

- NEVER kill by process name — cgroup scope only (`cgroup.kill` / `systemctl stop` on scope).
- NEVER kill owner gnome-terminal sessions.
- NEVER bypass admission queue or prevent-band gates.
- NEVER run fork-bomb/exhaustion tests on laptop or buildboxes without containment.
- NEVER write in shared main checkout — worktree only.

## Placement map — read these paths

`modules/workstation/claude/incidents/placement-map.md`:

- `~/.local/state/overdeck` — runtime state, journals, harness logs.
- `~/.claude` — hooks, `bin/`, cpu-guard, local-gate, admission queue.
- `~/.claude/buildbox-hosts.json` — where offload targets live; read before remote dispatch.
- Deploy clone `~/.local/share/overdeck/deploy` — collector + PATH tools source of truth.

## Resolve — exact CLI (never guess syntax)

```
od-incidents list [--type resource-overload] [--state S]
od-incidents show <id>
od-incidents search <query>
od-incidents resolve <id> --artifact <ref> [--summary <line>]
```

`resolve` REFUSES without `--artifact` (exit 2). Artifact = sha on origin/main, named passing test, or live command + expected output reviewer can rerun. No artifact ⇒ stays open.