Rch

RCH — Remote Compilation Helper

rch transparently offloads compilation commands to remote workers via a Claude Code PreToolUse hook (and, for every other agent/shell, via the managed cargo shim). The daemon picks a healthy worker, rsync's the workspace, runs the build, syncs artifacts back, and exits with the worker's exit code.

This skill is the operational layer agents use when that pipeline isn't working — and the much more common case where it thinks it's working but is silently building locally. Single principle: self-resolve before asking the human. Every recovery path here is one the agent can run alone.

Harmonized against remote_compilation_helper main @ b5c0566 (2026-08-25), workspace v1.0.58. The released 1.0.58 binary predates the post-release shim toolchain-wrapper commits; where that matters it is called out.

Read This First

When a build feels slow, run one thing:

RCH_VISIBILITY=verbose <your-command> 2>&1 | grep -E '^\[RCH\]'

The summary line is a contract:

If you can't see why offload isn't happening, prove the path in isolation, loudly:

RCH_REQUIRE_REMOTE=1 RCH_VISIBILITY=verbose rch exec -- cargo check --workspace --all-targets

[RCH] remote <worker> (...) ⇒ the offload pipeline is healthy and the problem is upstream (hook classifier, PATH/shim order, the invocation form). A refusal line names exactly what's missing. Then references/RECOVERY_PLAYBOOKS.md.

Quick Start

rch check                                   # exit 0 ready / 1 degraded / 2 not ready
rch status --workers --jobs                 # full status
rch status --remediation                    # bands: operator-action vs self-healing vs normal fail-open
rch status --fleet                          # desired vs live workers: bypassed / disabled / unreachable / missing
rch workers probe --all                     # connectivity + component matrix + probe_warnings
rch hook status && rch agents status        # which agents are wrapped
rch shim status                             # cargo shim: PATH order, local builds running, toolchains wrapped
rch admit "cargo test -p foo"               # read-only admission preflight
rch diagnose --dry-run "cargo check --workspace --all-targets"
RCH_REQUIRE_REMOTE=1 rch exec -- cargo check --workspace --all-targets
rch self-test --all                         # end-to-end verify
rch doctor --reliability --scope topology,pressure   # (`ownership` scope is post-1.0.58)
rch doctor --fix --dry-run                  # what doctor would auto-fix
rch --robot-triage --json                   # agent mega-command

If rch status shows storage pressure, check both / and /tmp on the worker before deciding what to fix:

ssh <user>@<host> 'df -h / /tmp /data 2>/dev/null; free -h; cat /proc/pressure/memory /proc/pressure/io'

Fast Triage Order

Run in order; stop at the first failing stage.

1. Availability — rch check, rch status --workers --jobs, rch status --fleet, rch workers probe --all, rch queue
2. Config + socket consistency — rch config show --sources, rch --json config get general.socket_path, rch --json daemon status (version is in rch --json status → .data.daemon.daemon.version)
3. Interception — rch hook status, rch agents status, rch shim status, rch hook install (idempotent)
4. Classification + admission + closure — rch diagnose --dry-run "<cmd>", rch admit "<cmd>"
5. Remote compile proof — RCH_REQUIRE_REMOTE=1 rch exec -- cargo check --workspace --all-targets
6. If sync fails or storage looks bad — rch cache status --workers <id>, rch gc --dry-run --workers <id>, then references/DISK_AND_PRESSURE.md

Quick Fixes

Worker Priority and Slots Are Measured, Never Guessed

Rule: never hand-set priority or slots in workers.toml from intuition, core count, or price tier. Derive them from a persisted SpeedScore. If no score exists, fixing that comes first — it is a bug, not a reason to guess.

Hand-tuned priorities silently invert. A real example from this fleet: the two highest-priority workers (110) had the fewest slots (4 and 5) while ten-slot workers sat at 100, so the scheduler preferentially routed to the smallest, most disk-constrained boxes — which is exactly why those two filled to 96–98% first.

The correct sequence

rch workers benchmark --all --force     # measure
rch workers list --speedscore           # confirm scores persisted and DIFFER
rch workers compare <id> <id> <id>      # side-by-side
rch speedscore <worker>                 # per-worker detail + components
# only now: set priority ∝ measured score, slots ∝ cores

Verify the score is real before you trust it

That third one has a loud tell: daemon.log fills with alternating Benchmark completed successfully ... score: 100.0 and Enqueued benchmark request ... reason: new_worker for the same worker. That is an infinite re-benchmark loop and will grow the log to hundreds of MB. (A persisted score is now treated as "already benchmarked" — if you still see the loop, the store is broken.)

rch workers benchmark (the CLI probe) times an SSH round-trip around a hello-world compile. It is not a capability measurement and must never be used to rank workers. The authoritative number is the daemon's SpeedScore (CPU 30 / disk 20 / compilation 20 / memory 15 / network 15 via rch-telemetry).

Before recommending more hardware

rch queue        # → "● N available  ● M busy  ● 0 offline / X / Y slots free"

If slots are free and nothing is queued, more machines will not help — say so. Look for the real constraint in this order: disk pressure (workers >90% degrade and fail builds long before slots run out; rch status --remediation shows the tightest free-disk ratio), then stale/inverted priorities, then slot counts that don't match core counts. Only recommend buying when rch queue shows sustained zero free slots under real load.

Anti-Asking Rules

These are the questions agents historically ask the human that they should just answer themselves. Do not ask. Do.

• "Can I restart the daemon?" — Yes, once rch --json queue | jq '.data.active_builds|length' is 0. rch daemon restart -y does not drain: -y skips the "N active build(s) will be interrupted" prompt, and the daemon may refuse (shutdown_blocked) while builds run. Wait or rch cancel first.
• "Can I install the hook / the shim?" — Yes on a dispatcher box (rch hook install, rch shim install). The shim refuses on a role = "worker" box by itself.
• "The autostart cooldown is blocking me — can I delete the cooldown file?" — Don't; wait auto_start_cooldown_secs (30 s) or run rch daemon start, which isn't gated by the hook cooldown.
• "Can I drop the corrupt telemetry db?" — Yes. references/TELEMETRY_RECOVERY.md. Telemetry is derived data.
• "Should I recover SSH keys from a sibling host?" — If the keys are missing here but reachable on another host, yes. references/SSH_KEY_RECOVERY.md Step 3.
• "Should I run the benchmarks before setting priorities?" — Yes, always. Priorities without a persisted SpeedScore are guesses.
• "Every worker scored the same — can I rank them by core count?" — No. An identical score across the fleet means scoring is broken; fix the score.
• "Should we buy more workers?" — Answer from rch queue and rch status --remediation, not intuition. Free slots + empty queue = no. Check disk pressure first.
• "The worker is at 97% disk — should I delete the rch build pool?" — Run rch cache status --workers <id> then rch gc --dry-run --workers <id>; let the reaper's verdicts (REAPABLE vs pooled (kept) vs active/recent (kept)) decide. Never rm -rf a .rch-target-* dir by hand while rch queue shows that project active.
• "A shimmed build exited 103 — should I uninstall the shim?" — No. 103 means the fleet had nothing admissible; rch status --remediation, fix that, retry.
• "It's waiting on a source-authority lock — is it hung?" — No. Another invocation holds a shared path-dependency root on that worker; it releases when that Cargo exits.

When in genuine doubt, capture the escalation packet (end of references/RECOVERY_PLAYBOOKS.md) and surface that — not a wall of text — to the human.

rch exec Modes You Should Know (details: references/EXEC_MODES.md)

Knobs Worth Knowing (Env Vars)

Every name below is read by 1.0.58 code (references/CONFIGURATION.md has the full list and the ones that are not read).

RABS (Asupersync-native Accelerated Build Sidecar) — What To Tell Agents

RABS is a new build-caching sidecar inside the rch workspace (11 crates — 10 rabs-* plus rabsd — all publish = false; binaries rabsd, rabs-wrap as a RUSTC_WRAPPER, rabs-wkr). As of 2026-08-25 it is opt-in and shadow-only: rabs-wrap computes a canonical action key, consults the daemon, records a would_have_hit receipt, then execs the real rustc unconditionally — it does not serve cache hits yet (bead bd-k52xe open). Nothing wires RUSTC_WRAPPER automatically; install.sh builds the spine best-effort and scripts/rabs_fleet_deploy.sh deploys it only to bwrap-capable hosts. It is fail-open by design (rabsd --doctor treats a dead daemon as WARN).

Operator surface: rch rabs gc plan|run|history, rch rabs worker reconcile <W> (proposals only), rch rabs doctor, rch rabs inventory. These act on the RABS CAS (~/.cache/rch/rabs-state/cas), not on worker target dirs — don't reach for them for disk pressure. If an agent asks "is RABS making my builds faster?" the honest answer today is no; the win is still rch offload itself.

Reference Index

Recognising what's wrong:

• references/FAIL_OPEN.md — every [RCH] local (...) reason and refusal line mapped to a self-fix
• references/ERROR_CODES.md — RCH-Ennn catalog, RCH-Innn refusal codes, RCH-Rnnn runbooks, the three exit-code schemes
• references/TROUBLESHOOTING.md — diagnostic flow + common errors

Solving specific failure classes:

• references/RECOVERY_PLAYBOOKS.md — symptom → fix in ≤90 s, lettered playbooks A–P
• references/SHIM.md — cargo shim, toolchain wrapping, local-build alarm, building locally on purpose
• references/EXEC_MODES.md — strict remote, job mode, clean overlay, receipts, exec envelope, source-authority locks
• references/SSH_KEY_RECOVERY.md — when workers.toml references keys this host doesn't have
• references/PATH_DEPENDENCIES.md — multi-repo workspaces, closure planner, [path_topology]
• references/DISK_AND_PRESSURE.md — pooled target dirs, rch gc / rch cache, reaper config, RCH-E210..217, sbh handoff
• references/TELEMETRY_RECOVERY.md — corrupt ~/.local/share/rch/telemetry/telemetry.db
• references/SELF_HEALING.md — autostart cooldown, temporary bypass + auto-rejoin, [self_healing]
• references/SSH_TUNING.md — ControlMaster, keepalives, retry classification

Operating in fleets and swarms:

• references/MULTI_AGENT_CONTENTION.md — TOCTOU, source-authority locks, fleet deploy races, autostart cooldown sharing
• references/OPERATIONS.md — runbook + worker fleet lifecycle
• references/WORKERS.md — worker config, lifecycle states, os = gate, Windows workers, fleet commands
• references/CONFIGURATION.md — every config section/key/default, env vars (incl. the ones that don't exist), runtime paths
• references/HOOKS.md — hook protocol, per-agent install, what is/isn't intercepted
• references/MACHINE_INTROSPECTION.md — --json shapes, envelope, verified jq recipes
• references/COMMANDS.md — full command/flag reference (quoted from clap)

Automation scripts (in scripts/):

• auto_recover.sh — heuristic, dry-run-by-default fleet recovery
• worker_disk_triage.sh — read-only mount-aware disk report per worker
• protocol_test.sh — probe the hook protocol with synthetic input
• multi_agent_safety.sh — flock wrapper for fleet/setup operations
• mine_rch_history.sh — find prior agent sessions that hit a given failure
• diagnose-rch.sh — end-to-end diagnostic (health, socket, workers, hook, shim, protocol)
• validate-setup.sh — verify prerequisites/config/daemon/hook before use

Templates and project docs:

• assets/workers-template.toml
• Source: https://github.com/Dicklesworthstone/remote_compilation_helper — README.md, CHANGELOG.md, docs/runbooks/*

Adjacent Skills

• sbh — disk-pressure defense for AI coding workloads. Use when RCH-E210/211/215/216 fires and rch gc isn't enough.
• agent-mail — file reservations and messaging between agents. Use before rch fleet deploy or any worker config edit in a swarm.
• ntm / vibing-with-ntm — multi-agent tmux orchestration; common parent context for agents that hit rch failures.
• cass — search prior agent sessions; scripts/mine_rch_history.sh is the fallback when the cass index has dead pointers.
• provision-new-machine — provisioning a cloud VPS as an rch worker (root env, TMPDIR-only, no global CARGO_TARGET_DIR).

Reading Output: TUI vs Hook

rch with no subcommand is the PreToolUse hook (JSON in, JSON out) — don't run bare rch expecting help; use rch --help. rch dashboard (alias rch tui) and rch web are interactive and block your session; rch dashboard --dump-state / --test-mode are the non-interactive escapes.