ADR-0038: Termux Contributor Environment — Native Subset + CI-Only Gates, No proot

Status: accepted Date: 2026-08-09 Deciders: @barateza Tags: [termux, android, dev-env, tooling, proot, ci]

Context

Contributor development runs on a Termux installation (Android, arm64, bionic libc). Four pieces of the toolchain have no android/arm64 build on npm (docs/operations/environment-termux.md):

• workerd — Unsupported platform: android arm64 LE. Blocks wrangler dev, workers tests (@cloudflare/vitest-pool-workers), and local D1. Even the linux-arm64 glibc binary cannot run under bionic.
• TypeScript 7 — pnpm typecheck needs @typescript/typescript-android-arm64, which does not exist on npm (404). TS 7 is a native-binary compiler.
• Biome — pnpm lint needs @biomejs/cli-android-arm64, which does not exist on npm (404).
• Playwright — no android-arm64 browser builds → e2e and vitest browser mode cannot run.

proot-distro (a userspace, ptrace-based chroot — no root required) was proposed as the path to "fully runnable": it provides a glibc userspace (Debian/Ubuntu arm64) where those linux-arm64 binaries could run.

Key constraint discovered during evaluation: workerd's layer-2 sandbox is built on Linux namespaces + seccomp applied after process start (Cloudflare security model). proot emulates syscalls unprivileged and cannot create real kernel namespaces (unshare / clone(CLONE_NEWNS…) fail — a kernel privilege proot cannot fake). Therefore workerd cannot initialize its sandbox under proot, so wrangler dev, workers tests, and local D1 remain broken even inside a proot userspace.

Decision

1. Termux is a supported contributor environment with hard boundaries. Supported locally: node 24 / pnpm 11 / git / gh, vitest unit suites (app, packages/*, modules/nucleus), docs tooling (markdownlint, typedoc via the TS6 alias, vitepress), and remote wrangler operations (deploy, D1 --remote). CI-only (cannot run locally): typecheck, lint, e2e, and workers tests.
2. No proot-distro. Rejected — see Alternatives. It would add only local typecheck + lint, at measurable cost, and cannot fix the workerd family.
3. CI (linux x64) is the enforcement gate. Pre-commit/pre-push hooks do not run locally (husky prepare is skipped with --ignore-scripts); --no-verify is never used; CI runs the full gates (Biome, typecheck, docs lint, unit tests).
4. Lockfile discipline. The workspace has a latent pnpm 11.20 re-resolution issue (re-resolution re-picks root vite 5.4.21 as vitest's peer, which vitest rejects; only --frozen-lockfile installs are safe). Dependency bumps land as deliberate PRs generated on a supported platform, never via ad-hoc pnpm update on Termux.

Consequences

Positive

• Written, unambiguous boundaries: what must pass CI vs. what can be trusted locally — no re-litigating "why not proot?" per session.
• No ongoing cost of a second node/pnpm toolchain and no ptrace-emulation speed tax on an already slow device (native vite build is 15+ min).
• The workerd-under-proot dead end is documented so nobody re-attempts it.

Negative

• Local feedback loop for typecheck/lint/e2e/workers tests is push → CI → results.
• TypeScript 7 and Biome cannot be run locally at all without proot; accepted.

Neutral

• A rooted device could use a real chroot (faster, fewer emulation gaps), but namespaces may still block workerd; not required under this decision.

Alternatives Considered

• proot-distro (Debian/Ubuntu arm64) — Rejected. Delivers only local typecheck + lint; workerd still cannot run (namespaces wall); ptrace overhead on every syscall on top of an already slow device; a second toolchain to keep in sync; 1–2 GB rootfs.
• Rooted chroot — Rejected for now. Requires rooting the device; namespace availability varies by kernel/root setup; heavier operational burden than the CI-gate model.
• Remote dev box / Codespaces — Deferred. Would give full local-class gates but adds infrastructure; not needed while CI serves as the gate.

References

• docs/operations/environment-termux.md — capability matrix, the 4 hard blockers, latent lockfile issue, 2026-08-09 dependency snapshot
• docs/agents/tooling.md → Environment / sandbox quirks (Termux line)
• Cloudflare Workers security model — layer-2 sandbox: namespaces + seccomp
• ADR-0035 — precedent for environment/process policy as ADR material