# CI module agent notes

This module owns the ARC runner image, content-keyed cache plumbing, Kubernetes
manifests, and timing evidence.

- Runner pods must not use host mounts or receive package-registry credentials.
- Share only the pnpm content-addressed store and immutable, input-hash-keyed venv
  archives. Never persist `node_modules`, virtual environments, `dist`, `build`,
  `.next`, test output, or workspace state.
- `@platform-modules` packages come anonymously from the in-cluster registry
  gateway. Public packages use npmjs.
- Keep toolchains in the image and pin every downloaded artifact and base image.
- Treat measured cold-pod/warm-laptop output as evidence. Never substitute an
  estimate when the cluster is unavailable.
- Run `bash modules/ci/tests/run.sh` before committing changes here.
- Every manifest in `k8s/` must be named in an `install-arc.sh` apply call;
  `tests/install-arc.test.sh` fails otherwise. A manifest the installer never
  applies is a check that enforces nothing.
- CI wedges silently by design of the ARC topology: the scale-set listener is the
  only thing polling GitHub, so when it dies, jobs queue forever and no error
  surfaces anywhere. `k8s/listener-watchdog.yaml` is the standing remedy — it
  force-deletes pods stuck mid-deletion and restores the "a Ready listener
  exists" invariant on its own. When CI looks wedged, run
  `bash modules/ci/arc-watchdog-status.sh` first; do not re-diagnose by hand.
- Anything here that can wedge silently needs the same treatment: a mechanism
  that detects and repairs it without a human noticing first.