feat(tunnels): named cloudflared tunnel via CLOUDFLARED_CONFIG

[ggiak]

Summary

Adds an opt-in named/persistent Cloudflare tunnel mode to the cloudflared
integration, so operators can expose OmniRoute on a stable, named hostname
(e.g. ai.example.com) instead of the ephemeral *.trycloudflare.com URL that
changes on every restart.

This targets the locally-managed cloudflared flow (cloudflared tunnel login
→ create → route dns → a ~/.cloudflared/config.yml with tunnel:,
credentials-file:, ingress:) — no Zero Trust dashboard / connector token is
required.

How it works

• Set CLOUDFLARED_CONFIG=/path/to/config.yml to switch into named-tunnel mode.
  OmniRoute then runs cloudflared tunnel --no-autoupdate --config <path> run.
  run reads credentials from the config's absolute credentials-file path, so
  it works even with OmniRoute's isolated HOME and needs no cert.pem.
• Named tunnels emit no public URL to scrape, so readiness is detected from
  cloudflared's Registered tunnel connection log line.
• publicUrl / apiUrl are reported from CLOUDFLARED_HOSTNAME, or — when that
  override is unset — auto-read from the config's first ingress hostname.
• Default quick-tunnel behavior is unchanged: mode is selected purely by
  whether CLOUDFLARED_CONFIG is set. With it unset, the code path is byte-for-byte
  the previous quick-tunnel path.
• Fails fast with a clear error if the config path is missing (instead of a 30s
  readiness timeout).

Also documents the previously-undocumented CLOUDFLARED_PROTOCOL.

Files

• src/lib/cloudflaredTunnel.ts — named-tunnel config resolution, config-file
  args, ingress-hostname parser, connection-ready detection, start wiring.
• tests/unit/cloudflaredTunnel.test.ts — pure-function unit tests (arg builder,
  config resolution, hostname normalizer, ingress parser, readiness matcher).
• tests/unit/cloudflaredTunnel-extended.test.ts — behavioral test driving the
  real startCloudflaredTunnel state machine via a fake child that emits a
  registered-connection log line; asserts args, publicUrl/apiUrl, state.
• .env.example, docs/ops/TUNNELS_GUIDE.md, docs/reference/ENVIRONMENT.md.

Testing

• Unit + behavioral: node --import tsx/esm --test tests/unit/cloudflaredTunnel.test.ts tests/unit/cloudflaredTunnel-extended.test.ts → 33/33 pass.
• Real-environment validation (Hard Rule fix(ci): add environment for npm token access #18) against a live cloudflared 2026.8.2:
  • The binary accepts the flag ordering tunnel --no-autoupdate --config <path> run (failure was on config content, not flag parsing).
  • The readiness regex matches real tunnel logs (Registered tunnel connection connIndex=… protocol=quic).
  • The ingress-hostname parser extracts the correct host from a real config.yml.
• npm run lint, npm run typecheck:core (my files), check:env-doc-sync, and Prettier are clean on the changed files.

Notes

• Pre-existing typecheck errors in open-sse/services/compression/omniglyph*
  (an omniglyph package API/version mismatch) exist on the base tip and are
  unrelated to this change — no files under open-sse/ are touched here.