# docker-nuke Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build `docker-nuke`, a macOS command that captures diagnostics from a wedged Docker Desktop, force-kills it, and restarts it back to a responsive daemon.

**Architecture:** A single self-contained bash script in the dotfiles repo, symlinked into `~/.local/bin`. Every unit of logic is a small named function; `main` runs only when the script is executed, not when sourced, so the test harness can source the file and unit-test functions without triggering a real nuke. Side-effecting behaviour is made testable through injection: `DOCKER_NUKE_DUMP_ROOT` redirects dump output to a temp dir, and a stub `docker` on `PATH` simulates healthy/failing/hanging daemons. Process-killing functions take an explicit PID list so tests can exercise them against throwaway `sleep` processes.

**Tech Stack:** Bash, `pgrep`/`kill`, `sample`, `osascript`, `open`. Lint via `shellcheck`. Tests are a dependency-free bash harness (no `bats` on this machine).

## Global Constraints

- Script style follows `~/dotfiles/.local/bin/claude-tmux`: `#!/usr/bin/env bash`, `set -euo pipefail`, 2-space indent, `snake_case` functions, `printf` over `echo`, `bin_exists()` guard, heredoc help text, `case` dispatch.
- **Write bash 3.2-compatible code.** `/bin/bash` on this machine is 3.2.57. No `mapfile`, no `declare -A`, no `${var,,}`.
- **Never use `pgrep -f docker`.** It matches this script's own name and command line, so the script would kill itself. Match only the app bundle path and exact process names.
- **Never write absolute personal paths (`/Users/<name>/...`) into committed files.** Repo rule from `~/dotfiles/AGENTS.md`. Use `$HOME` or `~`.
- **Never `git add -A` or `git add .`.** The dotfiles repo has unrelated uncommitted changes (modified nvim/zsh/tmux configs, deleted opencode plugins). Stage only the exact files named in each task.
- Commit messages use conventional commits with a scope, matching repo history: `feat(docker-nuke): ...`.
- Exit codes: `0` success, `1` daemon did not return, `2` usage error or user abort.
- Every diagnostic capture runs under its own timeout and records failure instead of aborting. The dump must never block recovery.

---

## File Structure

| File | Responsibility |
|---|---|
| `~/dotfiles/.local/bin/docker-nuke` | The entire tool: config, helpers, dump, kill, restart, `main` |
| `~/dotfiles/.local/bin/test-docker-nuke.sh` | Test harness: assertions, stubs, all unit tests |
| `~/.local/bin/docker-nuke` | Symlink to the dotfiles copy, puts it on `PATH` |
| `~/dotfiles/docs/specs/2026-07-19-docker-nuke-design.md` | Approved spec, moved into the repo |
| `~/dotfiles/docs/plans/2026-07-19-docker-nuke.md` | This plan |

The script stays one file because it must be self-contained to run from `PATH` as a single symlink. Testability comes from the source guard, not from splitting into libraries.

---

### Task 1: Repo scaffold, help text, and argument parsing

**Files:**
- Create: `~/dotfiles/.local/bin/docker-nuke`
- Create: `~/dotfiles/.local/bin/test-docker-nuke.sh`
- Create: `~/dotfiles/docs/specs/2026-07-19-docker-nuke-design.md` (moved from `~/docs/superpowers/specs/`)

**Interfaces:**
- Consumes: nothing
- Produces: `usage()` (prints help to stdout); `parse_args "$@"` setting globals `OPT_FORCE`, `OPT_NO_RESTART`, `OPT_DRY_RUN`, `OPT_DEEP` to `0`/`1`, returning `2` on an unknown flag; `bin_exists NAME`

- [ ] **Step 1: Move the spec into the repo, stripping absolute paths**

```bash
mkdir -p ~/dotfiles/docs/specs ~/dotfiles/docs/plans
mv ~/docs/superpowers/specs/2026-07-19-docker-nuke-design.md \
   ~/dotfiles/docs/specs/2026-07-19-docker-nuke-design.md
rmdir -p ~/docs/superpowers/specs 2>/dev/null || true
sed -i '' "s#/Users/[^/]*/#~/#g" ~/dotfiles/docs/specs/2026-07-19-docker-nuke-design.md
grep -c "/Users/" ~/dotfiles/docs/specs/2026-07-19-docker-nuke-design.md
```

Expected: prints `0`.

- [ ] **Step 2: Write the failing test**

Create `~/dotfiles/.local/bin/test-docker-nuke.sh`:

```bash
#!/usr/bin/env bash
# Test harness for docker-nuke. No external dependencies.
# Run: ./test-docker-nuke.sh

set -uo pipefail  # deliberately not -e: a failing assertion must not abort the run

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
TESTS_RUN=0
TESTS_FAILED=0
TMPROOT=""

setup_tmp() {
  TMPROOT="$(mktemp -d)"
  export DOCKER_NUKE_DUMP_ROOT="$TMPROOT/dumps"
}

teardown_tmp() {
  if [ -n "$TMPROOT" ] && [ -d "$TMPROOT" ]; then
    rm -rf "$TMPROOT"
  fi
  TMPROOT=""
}

pass() {
  TESTS_RUN=$((TESTS_RUN + 1))
  printf '  ok   %s\n' "$1"
}

fail() {
  TESTS_RUN=$((TESTS_RUN + 1))
  TESTS_FAILED=$((TESTS_FAILED + 1))
  printf '  FAIL %s\n       %s\n' "$1" "$2"
}

assert_eq() {
  local desc="$1" expected="$2" actual="$3"
  if [ "$expected" = "$actual" ]; then
    pass "$desc"
  else
    fail "$desc" "expected [$expected] got [$actual]"
  fi
}

assert_contains() {
  local desc="$1" haystack="$2" needle="$3"
  case "$haystack" in
    *"$needle"*) pass "$desc" ;;
    *) fail "$desc" "expected to contain [$needle] got [$haystack]" ;;
  esac
}

assert_not_contains() {
  local desc="$1" haystack="$2" needle="$3"
  case "$haystack" in
    *"$needle"*) fail "$desc" "expected NOT to contain [$needle] got [$haystack]" ;;
    *) pass "$desc" ;;
  esac
}

# Source the script under test. DOCKER_NUKE_LIB stops main from running.
setup_tmp
# shellcheck source=/dev/null
source "$SCRIPT_DIR/docker-nuke"
set +e  # the sourced script sets -e; undo it for the harness

printf '\n=== argument parsing ===\n'

test_parse_args() {
  parse_args --force
  assert_eq "--force sets OPT_FORCE" "1" "$OPT_FORCE"

  parse_args -n
  assert_eq "-n sets OPT_NO_RESTART" "1" "$OPT_NO_RESTART"

  parse_args --dry-run
  assert_eq "--dry-run sets OPT_DRY_RUN" "1" "$OPT_DRY_RUN"

  parse_args --deep
  assert_eq "--deep sets OPT_DEEP" "1" "$OPT_DEEP"

  parse_args
  assert_eq "no flags leaves OPT_FORCE off" "0" "$OPT_FORCE"

  parse_args --bogus >/dev/null 2>&1
  assert_eq "unknown flag returns 2" "2" "$?"

  local help_text
  help_text="$(usage)"
  assert_contains "usage mentions --dry-run" "$help_text" "--dry-run"
  assert_contains "usage mentions --deep" "$help_text" "--deep"
}
test_parse_args

printf '\n=== summary ===\n'
teardown_tmp
printf 'ran %d, failed %d\n' "$TESTS_RUN" "$TESTS_FAILED"
[ "$TESTS_FAILED" -eq 0 ]
```

```bash
chmod +x ~/dotfiles/.local/bin/test-docker-nuke.sh
```

- [ ] **Step 3: Run test to verify it fails**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: FAIL — `docker-nuke: No such file or directory`

- [ ] **Step 4: Write minimal implementation**

Create `~/dotfiles/.local/bin/docker-nuke`:

```bash
#!/usr/bin/env bash
# docker-nuke — capture diagnostics from a wedged Docker Desktop, then
# force-kill and restart it.
#
# Written for bash 3.2 compatibility (macOS /bin/bash).

set -euo pipefail

# --- configuration ----------------------------------------------------------

HEALTH_TIMEOUT=6        # seconds to wait on `docker info` before calling it wedged
GRACEFUL_WAIT=8         # seconds to let Docker quit politely
TERM_WAIT=5             # seconds to wait after SIGTERM before SIGKILL
RESTART_TIMEOUT=90      # seconds to wait for the daemon to come back
POLL_INTERVAL=2         # seconds between daemon health polls
SAMPLE_DURATION=2       # seconds of stack sampling per process
SAMPLE_TIMEOUT=10       # hard cap on a single `sample` invocation
DUMP_RETENTION=10       # how many dump directories to keep
LOG_TAIL_LINES=2000     # lines of Docker log to copy (keeps dumps small)

DOCKER_APP="/Applications/Docker.app"
DOCKER_LOG_DIR="$HOME/Library/Containers/com.docker.docker/Data/log"
DOCKER_RAW="$HOME/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw"
CRASH_DIR="$HOME/Library/Logs/DiagnosticReports"

# Overridable so tests never touch real state.
DUMP_ROOT="${DOCKER_NUKE_DUMP_ROOT:-$HOME/.local/state/docker-nuke}"

OPT_FORCE=0
OPT_NO_RESTART=0
OPT_DRY_RUN=0
OPT_DEEP=0

# --- helpers ----------------------------------------------------------------

bin_exists() { command -v "$1" >/dev/null 2>&1; }

log()  { printf '%s\n' "$*"; }
warn() { printf '%s\n' "$*" >&2; }

usage() {
  cat <<'EOF'
docker-nuke: force-restart a wedged Docker Desktop, capturing diagnostics first

Usage:
  docker-nuke [options]

Options:
  -f, --force        Skip the confirmation shown when Docker looks healthy
  -n, --no-restart   Kill Docker but do not relaunch it
      --dry-run      Report what would be killed and dumped; change nothing
      --deep         Also stop root launchd helpers (com.docker.vmnetd); needs sudo
  -h, --help         Show this help

Diagnostics are written to ~/.local/state/docker-nuke/<timestamp>/ before
anything is killed. The most recent 10 dumps are kept.

Exit codes:
  0  Docker killed and confirmed responsive again
  1  Daemon did not come back within the restart timeout
  2  Usage error, or aborted at the healthy-daemon prompt
EOF
}

parse_args() {
  OPT_FORCE=0
  OPT_NO_RESTART=0
  OPT_DRY_RUN=0
  OPT_DEEP=0
  while [ "$#" -gt 0 ]; do
    case "$1" in
      -f|--force)      OPT_FORCE=1 ;;
      -n|--no-restart) OPT_NO_RESTART=1 ;;
      --dry-run)       OPT_DRY_RUN=1 ;;
      --deep)          OPT_DEEP=1 ;;
      -h|--help)       usage; return 3 ;;
      *)
        warn "docker-nuke: unknown option '$1'"
        usage >&2
        return 2
        ;;
    esac
    shift
  done
  return 0
}

# --- entrypoint -------------------------------------------------------------

main() {
  local rc=0
  parse_args "$@" || rc=$?
  if [ "$rc" -eq 3 ]; then return 0; fi
  if [ "$rc" -ne 0 ]; then return "$rc"; fi
  log "docker-nuke: not yet implemented"
  return 0
}

# Only run when executed, not when sourced by the test harness.
if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
  main "$@"
fi
```

```bash
chmod +x ~/dotfiles/.local/bin/docker-nuke
```

- [ ] **Step 5: Run test to verify it passes**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: PASS — `ran 8, failed 0`

- [ ] **Step 6: Lint**

Run: `shellcheck ~/dotfiles/.local/bin/docker-nuke ~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: no output (clean). Fix any warnings before committing.

- [ ] **Step 7: Commit**

```bash
cd ~/dotfiles
git add .local/bin/docker-nuke .local/bin/test-docker-nuke.sh docs/specs/2026-07-19-docker-nuke-design.md
git commit -m "feat(docker-nuke): add script scaffold, arg parsing, and test harness"
```

---

### Task 2: `run_timeout` helper

Everything that touches a wedged Docker must be time-bounded. This wraps `timeout` when available and falls back to a pure-bash implementation, so the tool still works if coreutils disappears.

**Files:**
- Modify: `~/dotfiles/.local/bin/docker-nuke` (add after `bin_exists`)
- Modify: `~/dotfiles/.local/bin/test-docker-nuke.sh` (add test section)

**Interfaces:**
- Consumes: `bin_exists` from Task 1
- Produces: `run_timeout SECONDS CMD [ARGS...]` — runs CMD, returns its exit code, or `124` if it exceeded SECONDS. Callers must invoke it in a conditional (`if run_timeout ...`) so `set -e` does not abort on a non-zero return.

- [ ] **Step 1: Write the failing test**

Add to `test-docker-nuke.sh`, immediately before the `=== summary ===` block:

```bash
printf '\n=== run_timeout ===\n'

test_run_timeout() {
  local out rc

  out="$(run_timeout 5 printf 'hello')"
  assert_eq "returns command stdout" "hello" "$out"

  run_timeout 5 true
  assert_eq "propagates success" "0" "$?"

  run_timeout 5 false
  assert_eq "propagates failure" "1" "$?"

  rc=0
  run_timeout 1 sleep 5 || rc=$?
  assert_eq "returns 124 on timeout" "124" "$rc"

  # Force the pure-bash fallback by making bin_exists report nothing available.
  # The override is scoped to a subshell so later tests still see the real one.
  rc=0
  (
    bin_exists() { return 1; }
    run_timeout 1 sleep 5
  ) || rc=$?
  assert_eq "fallback path also returns 124" "124" "$rc"

  rc=0
  out="$(
    bin_exists() { return 1; }
    run_timeout 5 printf 'fallback-ok'
  )" || rc=$?
  assert_eq "fallback path returns stdout" "fallback-ok" "$out"
}
test_run_timeout
```

- [ ] **Step 2: Run test to verify it fails**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: FAIL — `run_timeout: command not found`

- [ ] **Step 3: Write minimal implementation**

In `docker-nuke`, insert directly after the `bin_exists` definition:

```bash
# Run a command with a hard time limit. Returns 124 if it timed out.
# Call inside a conditional so `set -e` does not abort on a non-zero return.
run_timeout() {
  local secs="$1"
  shift
  if bin_exists timeout; then
    timeout "$secs" "$@"
    return $?
  fi
  if bin_exists gtimeout; then
    gtimeout "$secs" "$@"
    return $?
  fi

  # Pure-bash fallback: run in background and poll.
  "$@" &
  local pid=$!
  local waited=0
  while kill -0 "$pid" 2>/dev/null; do
    if [ "$waited" -ge "$secs" ]; then
      kill -9 "$pid" 2>/dev/null || true
      wait "$pid" 2>/dev/null || true
      return 124
    fi
    sleep 1
    waited=$((waited + 1))
  done
  local rc=0
  wait "$pid" || rc=$?
  return "$rc"
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: PASS — `ran 14, failed 0`

- [ ] **Step 5: Lint and commit**

```bash
shellcheck ~/dotfiles/.local/bin/docker-nuke ~/dotfiles/.local/bin/test-docker-nuke.sh
cd ~/dotfiles
git add .local/bin/docker-nuke .local/bin/test-docker-nuke.sh
git commit -m "feat(docker-nuke): add run_timeout helper with pure-bash fallback"
```

---

### Task 3: Process discovery (safety-critical)

This is the task most likely to cause real damage if wrong. A naive `pgrep -f docker` matches this script's own name, so `docker-nuke` would kill itself mid-run. The tests exist specifically to prove it does not.

**Files:**
- Modify: `~/dotfiles/.local/bin/docker-nuke`
- Modify: `~/dotfiles/.local/bin/test-docker-nuke.sh`

**Interfaces:**
- Consumes: `DOCKER_APP` from Task 1
- Produces: `docker_pids` — prints one PID per line, sorted, deduped, never including the current process or its parent

- [ ] **Step 1: Write the failing test**

Add before `=== summary ===`:

```bash
printf '\n=== docker_pids ===\n'

test_docker_pids() {
  # Keep both forms: newline for counting, space-padded for substring checks.
  # A space-padded haystack is required — searching newline-separated output
  # for " <pid> " can never match, which would make these assertions vacuous.
  local pids_nl pids_sp
  pids_nl="$(docker_pids)"
  pids_sp=" $(printf '%s' "$pids_nl" | tr '\n' ' ') "

  assert_not_contains "never returns own PID" "$pids_sp" " $$ "
  assert_not_contains "never returns parent PID" "$pids_sp" " $PPID "

  # Guard against a vacuous suite: if Docker is running there must be matches.
  local count
  count="$(printf '%s\n' "$pids_nl" | grep -c . || true)"
  if pgrep -x com.docker.backend >/dev/null 2>&1; then
    if [ "$count" -gt 0 ]; then
      pass "finds Docker processes while Docker is running"
    else
      fail "finds Docker processes while Docker is running" "got 0 pids"
    fi
  fi

  # Every returned PID must be a live process.
  local pid bad=""
  for pid in $pids_nl; do
    if ! kill -0 "$pid" 2>/dev/null; then
      bad="$bad $pid"
    fi
  done
  assert_eq "all returned PIDs are live" "" "$bad"

  # Output must be numeric and deduped.
  local nonnum=""
  for pid in $pids_nl; do
    case "$pid" in
      ''|*[!0-9]*) nonnum="$nonnum [$pid]" ;;
    esac
  done
  assert_eq "all output is numeric" "" "$nonnum"

  local uniq
  uniq="$(printf '%s\n' "$pids_nl" | sort -u | grep -c . || true)"
  assert_eq "output is deduped" "$count" "$uniq"

  # A decoy process whose name contains "docker" but is not Docker Desktop
  # must not be matched.
  local decoy="$TMPROOT/docker-nuke-decoy"
  cat >"$decoy" <<'STUB'
#!/usr/bin/env bash
sleep 30
STUB
  chmod +x "$decoy"
  "$decoy" &
  local decoy_pid=$!
  sleep 1
  pids_sp=" $(docker_pids | tr '\n' ' ') "
  assert_not_contains "ignores decoy named docker-nuke-*" "$pids_sp" " $decoy_pid "
  kill -9 "$decoy_pid" 2>/dev/null || true
  wait "$decoy_pid" 2>/dev/null || true
}
test_docker_pids
```

- [ ] **Step 2: Run test to verify it fails**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: FAIL — `docker_pids: command not found`

- [ ] **Step 3: Write minimal implementation**

Add to `docker-nuke` after `run_timeout`:

```bash
# Exact process names to target, in addition to anything under Docker.app.
# NOTE: never use `pgrep -f docker` here — it matches this script's own
# command line and the tool would kill itself.
DOCKER_PROC_NAMES="com.docker.backend com.docker.build com.docker.krun \
com.docker.vpnkit com.docker.virtualization vpnkit docker"

docker_pids() {
  local self="$$"
  local parent="${PPID:-0}"
  local name pid
  {
    pgrep -f "$DOCKER_APP" 2>/dev/null || true
    for name in $DOCKER_PROC_NAMES; do
      pgrep -x "$name" 2>/dev/null || true
    done
  } | sort -un | while read -r pid; do
    if [ -z "$pid" ]; then continue; fi
    if [ "$pid" = "$self" ]; then continue; fi
    if [ "$pid" = "$parent" ]; then continue; fi
    printf '%s\n' "$pid"
  done
}
```

Note the explicit `if ... then continue; fi` form. The shorter `[ "$pid" = "$self" ] && continue` returns 1 when the test fails, which `set -e` treats as a fatal error.

- [ ] **Step 4: Run test to verify it passes**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: PASS — `ran 20, failed 0`

- [ ] **Step 5: Manually confirm it finds the real Docker processes**

Run: `bash -c 'source ~/dotfiles/.local/bin/docker-nuke; docker_pids | wc -l'`
Expected: a non-zero count while Docker Desktop is running (roughly 9-12 on this machine).

Cross-check against the raw list:

Run: `pgrep -f '/Applications/Docker.app' | wc -l`
Expected: same order of magnitude. If `docker_pids` returns 0 while Docker is running, the matching is broken — stop and fix before continuing.

- [ ] **Step 6: Lint and commit**

```bash
shellcheck ~/dotfiles/.local/bin/docker-nuke ~/dotfiles/.local/bin/test-docker-nuke.sh
cd ~/dotfiles
git add .local/bin/docker-nuke .local/bin/test-docker-nuke.sh
git commit -m "feat(docker-nuke): add self-excluding Docker process discovery"
```

---

### Task 4: Health check

**Files:**
- Modify: `~/dotfiles/.local/bin/docker-nuke`
- Modify: `~/dotfiles/.local/bin/test-docker-nuke.sh`

**Interfaces:**
- Consumes: `run_timeout`, `HEALTH_TIMEOUT`
- Produces: `docker_healthy` — returns 0 if `docker info` answers within `HEALTH_TIMEOUT`, non-zero otherwise. `make_docker_stub DIR MODE` is a test-only helper (lives in the harness, not the script) where MODE is `healthy`, `broken`, or `hang`.

- [ ] **Step 1: Write the failing test**

Add before `=== summary ===`:

```bash
printf '\n=== docker_healthy ===\n'

# Creates a stub `docker` in DIR. MODE: healthy | broken | hang
make_docker_stub() {
  local dir="$1" mode="$2"
  mkdir -p "$dir"
  case "$mode" in
    healthy)
      cat >"$dir/docker" <<'STUB'
#!/usr/bin/env bash
printf 'Server Version: 99.0.0\n'
exit 0
STUB
      ;;
    broken)
      cat >"$dir/docker" <<'STUB'
#!/usr/bin/env bash
printf 'Cannot connect to the Docker daemon\n' >&2
exit 1
STUB
      ;;
    hang)
      cat >"$dir/docker" <<'STUB'
#!/usr/bin/env bash
sleep 300
STUB
      ;;
  esac
  chmod +x "$dir/docker"
}

test_docker_healthy() {
  local stub="$TMPROOT/stub" oldpath="$PATH" rc

  make_docker_stub "$stub" healthy
  PATH="$stub:$oldpath"
  rc=0; docker_healthy || rc=$?
  assert_eq "healthy daemon returns 0" "0" "$rc"

  make_docker_stub "$stub" broken
  rc=0; docker_healthy || rc=$?
  assert_eq "broken daemon returns non-zero" "1" "$rc"

  make_docker_stub "$stub" hang
  HEALTH_TIMEOUT=1
  rc=0; docker_healthy || rc=$?
  assert_eq "hanging daemon returns 124" "124" "$rc"
  HEALTH_TIMEOUT=6

  PATH="$oldpath"
}
test_docker_healthy
```

- [ ] **Step 2: Run test to verify it fails**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: FAIL — `docker_healthy: command not found`

- [ ] **Step 3: Write minimal implementation**

Add to `docker-nuke` after `docker_pids`:

```bash
# Returns 0 if the daemon answers within HEALTH_TIMEOUT, else non-zero
# (124 specifically means it hung rather than errored).
docker_healthy() {
  local rc=0
  run_timeout "$HEALTH_TIMEOUT" docker info >/dev/null 2>&1 || rc=$?
  return "$rc"
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: PASS — `ran 23, failed 0`

- [ ] **Step 5: Lint and commit**

```bash
shellcheck ~/dotfiles/.local/bin/docker-nuke ~/dotfiles/.local/bin/test-docker-nuke.sh
cd ~/dotfiles
git add .local/bin/docker-nuke .local/bin/test-docker-nuke.sh
git commit -m "feat(docker-nuke): add timeout-bounded daemon health check"
```

---

### Task 5: Diagnostic dump and retention

**Files:**
- Modify: `~/dotfiles/.local/bin/docker-nuke`
- Modify: `~/dotfiles/.local/bin/test-docker-nuke.sh`

**Interfaces:**
- Consumes: `run_timeout`, `docker_pids`, `DUMP_ROOT`, `DUMP_RETENTION`, `LOG_TAIL_LINES`, `SAMPLE_DURATION`, `SAMPLE_TIMEOUT`, `DOCKER_LOG_DIR`, `DOCKER_RAW`, `CRASH_DIR`
- Produces: `new_dump_dir` (creates and prints a timestamped dir); `capture NAME SECS CMD...` (writes `$DUMP_DIR/NAME`, records failures in `CAPTURE_FAILURES`, always returns 0); `run_dump` (populates the dump, sets global `DUMP_DIR`); `prune_dumps [KEEP]`

- [ ] **Step 1: Write the failing test**

Add before `=== summary ===`:

```bash
printf '\n=== dump ===\n'

test_dump() {
  local d rc

  d="$(new_dump_dir)"
  assert_eq "dump dir is created" "yes" "$([ -d "$d" ] && printf 'yes' || printf 'no')"
  assert_contains "dump dir lives under DUMP_ROOT" "$d" "$DUMP_ROOT"

  DUMP_DIR="$d"
  CAPTURE_FAILURES=""

  capture "ok.txt" 5 printf 'captured'
  assert_eq "successful capture writes its file" "captured" "$(cat "$d/ok.txt")"
  assert_eq "successful capture records no failure" "" "$CAPTURE_FAILURES"

  rc=0
  capture "slow.txt" 1 sleep 5 || rc=$?
  assert_eq "timed-out capture still returns 0" "0" "$rc"
  assert_contains "timed-out capture is recorded" "$CAPTURE_FAILURES" "slow.txt"
  assert_contains "timed-out capture notes failure in file" "$(cat "$d/slow.txt")" "failed or timed out"

  rc=0
  capture "missing.txt" 5 this-command-does-not-exist || rc=$?
  assert_eq "failed capture still returns 0" "0" "$rc"
  assert_contains "failed capture is recorded" "$CAPTURE_FAILURES" "missing.txt"

  # Retention: 12 dumps in, 10 newest survive.
  rm -rf "${DUMP_ROOT:?}"
  mkdir -p "$DUMP_ROOT"
  local i
  for i in 01 02 03 04 05 06 07 08 09 10 11 12; do
    mkdir -p "$DUMP_ROOT/2026010${i}T000000Z"
  done
  prune_dumps 10
  assert_eq "keeps exactly 10 dumps" "10" "$(ls -1 "$DUMP_ROOT" | wc -l | tr -d ' ')"
  assert_eq "prunes the oldest" "no" \
    "$([ -d "$DUMP_ROOT/20260101T000000Z" ] && printf 'yes' || printf 'no')"
  assert_eq "keeps the newest" "yes" \
    "$([ -d "$DUMP_ROOT/20260112T000000Z" ] && printf 'yes' || printf 'no')"
}
test_dump
```

- [ ] **Step 2: Run test to verify it fails**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: FAIL — `new_dump_dir: command not found`

- [ ] **Step 3: Write minimal implementation**

Add to `docker-nuke` after `docker_healthy`:

```bash
DUMP_DIR=""
CAPTURE_FAILURES=""

new_dump_dir() {
  local stamp
  stamp="$(date -u '+%Y%m%dT%H%M%SZ')"
  local dir="$DUMP_ROOT/$stamp"
  mkdir -p "$dir"
  printf '%s\n' "$dir"
}

# capture NAME SECONDS CMD... — write CMD output to $DUMP_DIR/NAME.
# Never fails: a timeout or error is recorded and execution continues, so a
# broken capture can never block recovery.
capture() {
  local name="$1" secs="$2"
  shift 2
  local out="$DUMP_DIR/$name"
  local rc=0
  run_timeout "$secs" "$@" >"$out" 2>&1 || rc=$?
  if [ "$rc" -ne 0 ]; then
    printf '\n[docker-nuke] capture "%s" failed or timed out (rc=%s)\n' "$name" "$rc" >>"$out"
    CAPTURE_FAILURES="$CAPTURE_FAILURES $name"
  fi
  return 0
}

# Sample user-space stacks of the daemon-side processes. This is the one
# signal that cannot be reconstructed after the processes are killed.
capture_samples() {
  if ! bin_exists sample; then
    printf 'sample(1) not available\n' >"$DUMP_DIR/samples-skipped.txt"
    return 0
  fi
  local name pid
  for name in com.docker.backend com.docker.krun; do
    for pid in $(pgrep -x "$name" 2>/dev/null || true); do
      capture "sample-$name-$pid.txt" "$SAMPLE_TIMEOUT" \
        sample "$pid" "$SAMPLE_DURATION" -mayDie
    done
  done
}

capture_logs() {
  mkdir -p "$DUMP_DIR/logs"
  local f base
  for f in "$DOCKER_LOG_DIR"/host/*.log "$DOCKER_LOG_DIR"/vm/*.log; do
    if [ -f "$f" ]; then
      base="$(basename "$f")"
      tail -n "$LOG_TAIL_LINES" "$f" >"$DUMP_DIR/logs/$base" 2>/dev/null || true
    fi
  done
}

capture_crashes() {
  mkdir -p "$DUMP_DIR/crashes"
  if [ ! -d "$CRASH_DIR" ]; then
    return 0
  fi
  local f
  ls -1t "$CRASH_DIR" 2>/dev/null | grep -i docker | head -5 | while read -r f; do
    cp "$CRASH_DIR/$f" "$DUMP_DIR/crashes/" 2>/dev/null || true
  done
}

disk_report() {
  df -h
  printf '\n--- Docker.raw ---\n'
  ls -lh "$DOCKER_RAW" 2>/dev/null || printf 'Docker.raw not found\n'
  du -h -d0 "$DOCKER_RAW" 2>/dev/null || true
}

socket_report() {
  local sock="$HOME/.docker/run/docker.sock"
  printf 'socket: %s\n' "$sock"
  ls -l "$sock" 2>/dev/null || printf 'socket does not exist\n'
  printf '\n--- listeners ---\n'
  lsof "$sock" 2>/dev/null || printf 'no processes hold the socket\n'
}

run_dump() {
  DUMP_DIR="$(new_dump_dir)"
  CAPTURE_FAILURES=""
  log "docker-nuke: capturing diagnostics to $DUMP_DIR"

  capture "ps.txt" 10 ps -eo pid,ppid,stat,%cpu,%mem,etime,command
  capture "docker-info.txt" "$HEALTH_TIMEOUT" docker info
  capture "docker-version.txt" "$HEALTH_TIMEOUT" docker version
  capture "disk.txt" 15 disk_report
  capture "memory.txt" 10 vm_stat
  capture "socket.txt" 10 socket_report
  capture_logs
  capture_crashes
  capture_samples
}

prune_dumps() {
  local keep="${1:-$DUMP_RETENTION}"
  if [ ! -d "$DUMP_ROOT" ]; then
    return 0
  fi
  local d
  ls -1 "$DUMP_ROOT" 2>/dev/null | sort -r | tail -n "+$((keep + 1))" | while read -r d; do
    if [ -n "$d" ]; then
      rm -rf "${DUMP_ROOT:?}/$d"
    fi
  done
}
```

`disk_report` and `socket_report` are defined as functions so `capture` can time-bound them as single units.

- [ ] **Step 4: Run test to verify it passes**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: PASS — `ran 34, failed 0`

- [ ] **Step 5: Confirm a real dump is well-formed**

Run:

```bash
DOCKER_NUKE_DUMP_ROOT=/tmp/dn-check bash -c \
  'source ~/dotfiles/.local/bin/docker-nuke; run_dump; printf "failures:%s\n" "$CAPTURE_FAILURES"; ls -la "$DUMP_DIR"'
```

Expected: `ps.txt`, `docker-info.txt`, `disk.txt`, `memory.txt`, `socket.txt`, `logs/`, `crashes/`, and at least one `sample-*.txt`. `disk.txt` should show the near-full data volume. Sampling makes this take ~10-15s — that is the designed cost.

Then clean up: `rm -rf /tmp/dn-check`

- [ ] **Step 6: Lint and commit**

```bash
shellcheck ~/dotfiles/.local/bin/docker-nuke ~/dotfiles/.local/bin/test-docker-nuke.sh
cd ~/dotfiles
git add .local/bin/docker-nuke .local/bin/test-docker-nuke.sh
git commit -m "feat(docker-nuke): add pre-kill diagnostic dump with retention"
```

---

### Task 6: Kill escalation

Tested against throwaway `sleep` processes rather than real Docker, so the escalation logic is proven without bouncing containers.

**Files:**
- Modify: `~/dotfiles/.local/bin/docker-nuke`
- Modify: `~/dotfiles/.local/bin/test-docker-nuke.sh`

**Interfaces:**
- Consumes: `docker_pids`, `GRACEFUL_WAIT`, `TERM_WAIT`, `DOCKER_APP`
- Produces: `pids_alive PID...` (prints the subset still running, space-separated); `kill_pids SIGNAL PID...`; `wait_for_exit SECONDS PID...` (returns 0 once all are gone, 1 on timeout); `nuke_docker` (full escalation against `docker_pids`)

- [ ] **Step 1: Write the failing test**

Add before `=== summary ===`:

```bash
printf '\n=== kill escalation ===\n'

test_kill() {
  local a b rc alive

  sleep 60 & a=$!
  sleep 60 & b=$!
  sleep 1

  alive="$(pids_alive "$a" "$b")"
  assert_contains "pids_alive reports first live pid" " $alive " " $a "
  assert_contains "pids_alive reports second live pid" " $alive " " $b "

  kill_pids TERM "$a"
  sleep 1
  alive="$(pids_alive "$a" "$b")"
  assert_not_contains "SIGTERM kills the target" " $alive " " $a "
  assert_contains "SIGTERM leaves others alone" " $alive " " $b "

  rc=0; wait_for_exit 3 "$a" || rc=$?
  assert_eq "wait_for_exit returns 0 for a dead pid" "0" "$rc"

  rc=0; wait_for_exit 2 "$b" || rc=$?
  assert_eq "wait_for_exit returns 1 while pid lives" "1" "$rc"

  kill_pids KILL "$b"
  sleep 1
  assert_eq "SIGKILL clears the last pid" "" "$(pids_alive "$a" "$b")"

  rc=0; kill_pids TERM 999999 || rc=$?
  assert_eq "killing a nonexistent pid is not an error" "0" "$rc"

  wait "$a" 2>/dev/null || true
  wait "$b" 2>/dev/null || true
}
test_kill
```

- [ ] **Step 2: Run test to verify it fails**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: FAIL — `pids_alive: command not found`

- [ ] **Step 3: Write minimal implementation**

Add to `docker-nuke` after `prune_dumps`:

```bash
pids_alive() {
  local pid alive=""
  for pid in "$@"; do
    if kill -0 "$pid" 2>/dev/null; then
      alive="$alive $pid"
    fi
  done
  printf '%s' "${alive# }"
}

kill_pids() {
  local sig="$1"
  shift
  local pid
  for pid in "$@"; do
    kill "-$sig" "$pid" 2>/dev/null || true
  done
  return 0
}

# Returns 0 once every PID is gone, 1 if SECONDS elapses first.
wait_for_exit() {
  local secs="$1"
  shift
  local waited=0
  while [ "$waited" -lt "$secs" ]; do
    if [ -z "$(pids_alive "$@")" ]; then
      return 0
    fi
    sleep 1
    waited=$((waited + 1))
  done
  if [ -z "$(pids_alive "$@")" ]; then
    return 0
  fi
  return 1
}

# Stop root launchd helpers. Only called with --deep; prompts for sudo.
stop_privileged_helpers() {
  log "docker-nuke: stopping privileged helpers (sudo required)"
  sudo launchctl stop com.docker.vmnetd 2>/dev/null || true
  sudo launchctl stop com.docker.socket 2>/dev/null || true
}

# Three-stage escalation: polite quit, SIGTERM, SIGKILL.
nuke_docker() {
  local pids
  pids="$(docker_pids | tr '\n' ' ')"
  if [ -z "$pids" ]; then
    log "docker-nuke: no Docker processes found"
    return 0
  fi

  log "docker-nuke: asking Docker Desktop to quit"
  osascript -e 'quit app "Docker Desktop"' >/dev/null 2>&1 || true
  # shellcheck disable=SC2086
  if wait_for_exit "$GRACEFUL_WAIT" $pids; then
    log "docker-nuke: Docker exited cleanly"
    return 0
  fi

  log "docker-nuke: sending SIGTERM"
  # shellcheck disable=SC2086
  kill_pids TERM $pids
  # shellcheck disable=SC2086
  if wait_for_exit "$TERM_WAIT" $pids; then
    log "docker-nuke: Docker exited after SIGTERM"
    return 0
  fi

  log "docker-nuke: sending SIGKILL"
  # shellcheck disable=SC2086
  local remaining
  remaining="$(pids_alive $pids)"
  # shellcheck disable=SC2086
  kill_pids KILL $remaining
  sleep 1

  if [ "$OPT_DEEP" -eq 1 ]; then
    stop_privileged_helpers
  fi

  # shellcheck disable=SC2086
  local still
  still="$(pids_alive $pids)"
  if [ -n "$still" ]; then
    warn "docker-nuke: processes survived SIGKILL: $still"
    return 1
  fi
  log "docker-nuke: all Docker processes terminated"
  return 0
}
```

The `SC2086` disables are deliberate: `$pids` must word-split into separate arguments here.

- [ ] **Step 4: Run test to verify it passes**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: PASS — `ran 41, failed 0`

- [ ] **Step 5: Lint and commit**

```bash
shellcheck ~/dotfiles/.local/bin/docker-nuke ~/dotfiles/.local/bin/test-docker-nuke.sh
cd ~/dotfiles
git add .local/bin/docker-nuke .local/bin/test-docker-nuke.sh
git commit -m "feat(docker-nuke): add three-stage kill escalation"
```

---

### Task 7: Restart, daemon polling, and summary

**Files:**
- Modify: `~/dotfiles/.local/bin/docker-nuke`
- Modify: `~/dotfiles/.local/bin/test-docker-nuke.sh`

**Interfaces:**
- Consumes: `docker_healthy`, `run_timeout`, `RESTART_TIMEOUT`, `POLL_INTERVAL`, `DUMP_DIR`, `CAPTURE_FAILURES`
- Produces: `start_docker`; `wait_for_daemon SECONDS` (0 when healthy, 1 on timeout); `write_summary VERDICT ELAPSED`

- [ ] **Step 1: Write the failing test**

Add before `=== summary ===`:

```bash
printf '\n=== restart and summary ===\n'

test_restart_and_summary() {
  local stub="$TMPROOT/stub2" oldpath="$PATH" rc

  make_docker_stub "$stub" healthy
  PATH="$stub:$oldpath"
  rc=0; wait_for_daemon 6 || rc=$?
  assert_eq "wait_for_daemon returns 0 when healthy" "0" "$rc"

  make_docker_stub "$stub" broken
  rc=0; wait_for_daemon 4 || rc=$?
  assert_eq "wait_for_daemon returns 1 when never healthy" "1" "$rc"
  PATH="$oldpath"

  DUMP_DIR="$(new_dump_dir)"
  CAPTURE_FAILURES=" slow.txt"
  write_summary "recovered" "42"
  local s
  s="$(cat "$DUMP_DIR/summary.txt")"
  assert_contains "summary records the verdict" "$s" "recovered"
  assert_contains "summary records elapsed time" "$s" "42"
  assert_contains "summary records capture failures" "$s" "slow.txt"
}
test_restart_and_summary
```

- [ ] **Step 2: Run test to verify it fails**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: FAIL — `wait_for_daemon: command not found`

- [ ] **Step 3: Write minimal implementation**

Add to `docker-nuke` after `nuke_docker`:

```bash
start_docker() {
  log "docker-nuke: relaunching Docker Desktop"
  open -a Docker >/dev/null 2>&1 || open "$DOCKER_APP" >/dev/null 2>&1 || true
}

wait_for_daemon() {
  local secs="$1"
  local waited=0
  while [ "$waited" -lt "$secs" ]; do
    if docker_healthy; then
      return 0
    fi
    sleep "$POLL_INTERVAL"
    waited=$((waited + POLL_INTERVAL))
  done
  return 1
}

write_summary() {
  local verdict="$1" elapsed="$2"
  if [ -z "$DUMP_DIR" ] || [ ! -d "$DUMP_DIR" ]; then
    return 0
  fi
  {
    printf 'docker-nuke summary\n'
    printf '===================\n\n'
    printf 'verdict:          %s\n' "$verdict"
    printf 'elapsed seconds:  %s\n' "$elapsed"
    printf 'dump directory:   %s\n' "$DUMP_DIR"
    printf 'capture failures: %s\n' "${CAPTURE_FAILURES:-none}"
    printf '\nTriage hints\n------------\n'
    printf '* ps.txt      STAT column: U or D means stuck in the kernel, not user space\n'
    printf '* disk.txt    a nearly full data volume is a common cause of Docker hangs\n'
    printf '* sample-*    user-space stacks showing where the daemon was stuck\n'
    printf '* logs/       Docker host and vm logs from just before the kill\n'
  } >"$DUMP_DIR/summary.txt"
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: PASS — `ran 46, failed 0`

- [ ] **Step 5: Lint and commit**

```bash
shellcheck ~/dotfiles/.local/bin/docker-nuke ~/dotfiles/.local/bin/test-docker-nuke.sh
cd ~/dotfiles
git add .local/bin/docker-nuke .local/bin/test-docker-nuke.sh
git commit -m "feat(docker-nuke): add restart, daemon polling, and triage summary"
```

---

### Task 8: Wire up `main`, dry-run, and install the symlink

**Files:**
- Modify: `~/dotfiles/.local/bin/docker-nuke` (replace the placeholder `main`)
- Modify: `~/dotfiles/.local/bin/test-docker-nuke.sh`
- Create: `~/.local/bin/docker-nuke` (symlink)
- Modify: `~/dotfiles/README.md`

**Interfaces:**
- Consumes: everything from Tasks 1-7
- Produces: `confirm_healthy_nuke` (returns 0 to proceed, 2 to abort); `dry_run_report`; the finished `main`

- [ ] **Step 1: Write the failing test**

Add before `=== summary ===`:

```bash
printf '\n=== dry run ===\n'

test_dry_run() {
  local out rc before

  before="$(ls -1 "$DUMP_ROOT" 2>/dev/null | wc -l | tr -d ' ')"
  rc=0
  out="$("$SCRIPT_DIR/docker-nuke" --dry-run 2>&1)" || rc=$?
  assert_eq "dry run exits 0" "0" "$rc"
  assert_contains "dry run says it changed nothing" "$out" "no changes made"
  assert_contains "dry run lists processes it would kill" "$out" "would kill"
  assert_eq "dry run writes no dump" "$before" \
    "$(ls -1 "$DUMP_ROOT" 2>/dev/null | wc -l | tr -d ' ')"

  rc=0
  out="$("$SCRIPT_DIR/docker-nuke" --help 2>&1)" || rc=$?
  assert_eq "--help exits 0" "0" "$rc"
  assert_contains "--help prints usage" "$out" "Usage:"

  rc=0
  "$SCRIPT_DIR/docker-nuke" --nonsense >/dev/null 2>&1 || rc=$?
  assert_eq "unknown flag exits 2" "2" "$rc"
}
test_dry_run
```

- [ ] **Step 2: Run test to verify it fails**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: FAIL — dry run output does not contain `would kill`

- [ ] **Step 3: Write minimal implementation**

In `docker-nuke`, replace the placeholder `main` with:

```bash
confirm_healthy_nuke() {
  local info
  info="$(run_timeout "$HEALTH_TIMEOUT" docker info \
    --format '{{.ServerVersion}} ({{.ContainersRunning}} running)' 2>/dev/null || true)"
  log "docker-nuke: Docker looks healthy: ${info:-unknown}"
  log "Nuking will stop running containers."
  printf 'Proceed anyway? [y/N] '
  local reply=""
  read -r reply || true
  case "$reply" in
    y|Y|yes|YES) return 0 ;;
    *) log "docker-nuke: aborted"; return 2 ;;
  esac
}

dry_run_report() {
  local pids
  pids="$(docker_pids | tr '\n' ' ')"
  log "docker-nuke: DRY RUN — no changes made"
  if [ -z "$pids" ]; then
    log "  would kill: (no Docker processes found)"
  else
    log "  would kill: $pids"
    # shellcheck disable=SC2086
    ps -o pid,stat,%cpu,%mem,etime,comm -p $pids 2>/dev/null || true
  fi
  log "  would dump to: $DUMP_ROOT/<timestamp>"
  if [ "$OPT_NO_RESTART" -eq 1 ]; then
    log "  would not restart Docker (--no-restart)"
  else
    log "  would restart Docker and wait up to ${RESTART_TIMEOUT}s"
  fi
}

main() {
  local rc=0
  parse_args "$@" || rc=$?
  if [ "$rc" -eq 3 ]; then return 0; fi
  if [ "$rc" -ne 0 ]; then return "$rc"; fi

  if [ "$OPT_DRY_RUN" -eq 1 ]; then
    dry_run_report
    return 0
  fi

  if docker_healthy && [ "$OPT_FORCE" -eq 0 ]; then
    confirm_healthy_nuke || return 2
  fi

  local started elapsed verdict
  started="$(date +%s)"

  run_dump
  nuke_docker || true

  if [ "$OPT_NO_RESTART" -eq 1 ]; then
    verdict="killed, not restarted (--no-restart)"
    elapsed=$(( $(date +%s) - started ))
    write_summary "$verdict" "$elapsed"
    prune_dumps
    log "docker-nuke: $verdict"
    log "docker-nuke: diagnostics in $DUMP_DIR"
    return 0
  fi

  start_docker
  if wait_for_daemon "$RESTART_TIMEOUT"; then
    verdict="recovered"
    elapsed=$(( $(date +%s) - started ))
    write_summary "$verdict" "$elapsed"
    prune_dumps
    local info
    info="$(run_timeout "$HEALTH_TIMEOUT" docker info \
      --format '{{.ServerVersion}} ({{.ContainersRunning}} running)' 2>/dev/null || true)"
    log "docker-nuke: Docker is back after ${elapsed}s — ${info:-ok}"
    log "docker-nuke: diagnostics in $DUMP_DIR"
    return 0
  fi

  verdict="daemon did not return within ${RESTART_TIMEOUT}s"
  elapsed=$(( $(date +%s) - started ))
  write_summary "$verdict" "$elapsed"
  prune_dumps
  warn "docker-nuke: $verdict"
  warn "docker-nuke: still running: $(docker_pids | tr '\n' ' ')"
  warn "docker-nuke: diagnostics in $DUMP_DIR"
  warn "docker-nuke: try 'docker-nuke --deep', or check disk space in $DUMP_DIR/disk.txt"
  return 1
}
```

- [ ] **Step 4: Run test to verify it passes**

Run: `~/dotfiles/.local/bin/test-docker-nuke.sh`
Expected: PASS — `ran 51, failed 0`

- [ ] **Step 5: Install the symlink and confirm it resolves**

```bash
ln -sfn ../../dotfiles/.local/bin/docker-nuke ~/.local/bin/docker-nuke
ls -l ~/.local/bin/docker-nuke
command -v docker-nuke
docker-nuke --help
```

Expected: the symlink resolves (matching the relative style used by `cl` and `brave-debug`), `command -v` prints `~/.local/bin/docker-nuke`, and help text prints.

- [ ] **Step 6: Confirm the healthy-daemon guard works**

Run: `printf 'n\n' | docker-nuke`
Expected: reports Docker looks healthy, prompts, then `aborted`. Exit code 2 (`echo $?`). **Docker must still be running afterwards** — verify with `docker info --format '{{.ServerVersion}}'`.

- [ ] **Step 7: Document it in the README**

Add an entry to `~/dotfiles/README.md` in whatever section lists the `.local/bin` scripts (match the file's existing format):

```markdown
- `docker-nuke` — force-restart a wedged Docker Desktop. Captures diagnostics to
  `~/.local/state/docker-nuke/<timestamp>/` before killing anything. `--dry-run`
  to preview, `--no-restart` to leave Docker down, `--deep` for root helpers.
```

- [ ] **Step 8: Lint and commit**

```bash
shellcheck ~/dotfiles/.local/bin/docker-nuke ~/dotfiles/.local/bin/test-docker-nuke.sh
cd ~/dotfiles
git add .local/bin/docker-nuke .local/bin/test-docker-nuke.sh README.md docs/plans/2026-07-19-docker-nuke.md
git commit -m "feat(docker-nuke): wire up main, dry-run mode, and docs"
```

---

### Task 9: Live end-to-end verification

**Requires explicit user go-ahead.** This bounces every running container. Do not run it unprompted.

**Files:** none modified.

**Interfaces:**
- Consumes: the installed `docker-nuke`
- Produces: evidence that a real nuke recovers the daemon

- [ ] **Step 1: Record pre-nuke state**

```bash
docker info --format 'version={{.ServerVersion}} running={{.ContainersRunning}} total={{.Containers}}'
docker ps --format '{{.Names}}' | sort >/tmp/dn-before.txt
wc -l </tmp/dn-before.txt
```

Expected: records the container names that were running, for comparison afterwards.

- [ ] **Step 2: Run the real nuke**

Run: `time docker-nuke --force`
Expected: dump path printed, kill stages logged, then `Docker is back after Ns`. Exit code 0.

- [ ] **Step 3: Verify recovery**

```bash
echo "exit: $?"
docker info --format 'version={{.ServerVersion}} running={{.ContainersRunning}}'
docker ps --format '{{.Names}}' | sort >/tmp/dn-after.txt
diff /tmp/dn-before.txt /tmp/dn-after.txt || true
```

Expected: the daemon responds. Containers with a restart policy are back; those without remain stopped — this is the documented non-goal, not a bug. Report the diff to the user rather than silently restarting anything.

- [ ] **Step 4: Verify the dump is useful**

```bash
ls -1t ~/.local/state/docker-nuke | head -1
cat ~/.local/state/docker-nuke/$(ls -1t ~/.local/state/docker-nuke | head -1)/summary.txt
```

Expected: `verdict: recovered`, a plausible elapsed time, `capture failures: none`, and the triage hints. Confirm `disk.txt` and at least one `sample-*.txt` are present and non-empty.

- [ ] **Step 5: Verify no stray processes and clean up**

```bash
rm -f /tmp/dn-before.txt /tmp/dn-after.txt
pgrep -x docker-nuke || echo "no docker-nuke processes left behind"
```

Expected: `no docker-nuke processes left behind` — proving the script did not kill or orphan itself.

---

## Self-Review

**Spec coverage:** Health check (Task 4, wired in 8) · pre-kill dump with all ten artifacts (Task 5) · dump-never-blocks-recovery (Task 5, `capture` always returns 0) · retention of 10 (Task 5) · three-stage kill escalation (Task 6) · restart and 90s poll (Task 7) · report with version, count, elapsed, dump path (Task 8) · process targeting incl. the self-kill hazard (Task 3) · all six flags (Tasks 1, 5, 6, 8) · exit codes 0/1/2 (Tasks 1, 8) · constants (Task 1) · `run_timeout` with fallback (Task 2) · `set -e`/`pgrep` care (Tasks 2, 3) · staged verification (Tasks 8, 9). No gaps.

**Non-goals honored:** no container snapshot/replay; no sudo outside `--deep`; no pruning or disk cleanup anywhere.

**Type consistency:** `DUMP_DIR` and `CAPTURE_FAILURES` are declared in Task 5 and consumed unchanged in Task 7. `capture NAME SECS CMD...` keeps that argument order at every call site. `wait_for_exit`/`wait_for_daemon` both take seconds first and return 0 on success, 1 on timeout. `pids_alive` returns a space-separated string in every use. `parse_args` returns 3 for `--help` and 2 for bad flags, handled identically in the Task 1 and Task 8 versions of `main`.