---
name: od-cluster
description: Cluster/offload incidents — buildbox unreachable, k3s/offload failover, remote build spill, e2e-remote routing, SSH to debian hosts failing. Triggers on buildbox, debian1/2, remote build, spill, failover, unreachable host, e2e-remote. Invoke BEFORE hardcoding a hostname or SSHing blindly.
---

# Cluster / offload — incident playbook

audience: AI coding agents first. BLUF: read registry → contact ONLY reachable hosts → follow spill order.

## Covers

**Absorbs:** `tool-reliability-fatigue` (buildbox/k3s/offload subset — ids C084, C166 per taxonomy `_meta`).

**Keywords:** buildbox, k3s, offload, debian1, debian2, remote build, failover, ssh, e2e-remote, spill, vm, cluster, unreachable host.

**Registry coverage:** 2 of 217 (2026-08-08). Low count, high blast radius — wrong host contact or hardcoded hostname breaks failover.

## Doctrine

Read `~/.claude/buildbox-hosts.json` first. NEVER contact host registry does not mark reachable.

## First steps — registry is source of truth

1. **Read registry:** `~/.claude/buildbox-hosts.json` — host identity, `reachable` flag, spill order, access doors. NEVER hardcode `debian1`/`debian2`.
2. **Reachability:** for each candidate host, use registry state only. Unreachable → next in spill order; do not retry SSH hammering.
3. **Classify workload:** remote build (`build-remote`), seat dispatch (`seat-remote`), e2e (`e2e-remote`), harness on box. Each wrapper reads same registry.
4. **SSH/door failure:** capture `ssh -v` one attempt; check door name from registry; verify laptop network — not credential plane (see `od-auth` if 401/token).
5. **Offload path:** `e2e-remote --help` for browser+dev-server pairs; server binds `127.0.0.1`; artifacts inside repo tree for pull-back.
6. **Failover:** if primary box wedged, spill to next reachable; box reboot is acceptable — laptop unaffected (`docs/specs/2026-08-06-execution-plane-insulation.md`).

## Never-touch — applies here

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

- NEVER edit sshd config on buildboxes.
- NEVER bypass admission queue.
- NEVER `export OD_LOCAL_DISPATCH_OK=1` or `E2E_REMOTE_OK=1` to silence guards — route correctly instead.

## Placement map — read these paths

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

- `~/.claude/buildbox-hosts.json` — single source of host identity/state/spill order.
- `~/.local/share/overdeck/deploy` — deployed collector reads registry same as agents.
- `~/.local/state/overdeck` — fleet journals, dispatch state.

## Resolve — exact CLI (never guess syntax)

```
od-incidents list [--type cluster-offload] [--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 = registry readout showing reachable host + successful remote command output.
