---
name: linux-runner-migration
description: "Plan to replace the gravity CI Linux runner with kitsubito (LAN Linux), deferred until after v0.1.1 ships."
metadata: 
  node_type: memory
  type: project
  originSessionId: 83445c6f-b810-48bf-bf1a-3ac5a2b94e2a
---

Decided 2026-06-07 (user, doyle session): replace the `gravity` self-hosted Linux CI runner with **kitsubito** (a local LAN Linux machine). Chosen over a WSL2 runner on HFENDULEAM because WSL disk footprint is real (Ubuntu ~2GB + rust ~2GB + this project's heavy `target/` — iroh/ring/rustls — 10–20GB over time); a dedicated LAN box costs no local disk and gives a true parallel host.

**Why:** gravity is the single Linux runner and has one job slot — when a tag push fires ci+release+docs-publish at once, their Linux legs queue serially behind gravity (observed at the v0.1.1 ship). The matrix itself IS parallel (ci.yml/release.yml matrix over `[[Linux,gravity],[Windows,hfenduleam]]`, fail-fast:false); the bottleneck is single-slot self-hosted capacity.

**How to apply (when resumed, AFTER v0.1.1 publish):**
1. Recon kitsubito first — not yet in memory: reachability on LAN, OS/arch, credentials/ssh. Add a [[cross-machine-test-rig]] style entry once known.
2. Stand up the GitHub Actions runner there (rust stable matching gravity ~1.93, mdbook, gh, build-essential+libssl-dev, base64/coreutils — docs-publish assumes bash+GNU coreutils).
3. Workflows hard-code the `gravity` host label in THREE files: `.github/workflows/{ci,release,docs-publish}.yml`. Retarget from host-label `gravity` to a shared role label (e.g. `linux-builder`) the new runner carries. docs-publish has NO hard Linux dependency — it's pinned by label only.
4. gravity → decommission or keep as cold fallback (carries the role label too if fallback).

Reboot/timing note: do NOT do disruptive runner work mid-release — a tag push triggers 3 workflows and the in-session live agent + Windows runner (C:/actions-runner/run.cmd on HFENDULEAM) must stay up. See [[cross-machine-test-rig]].