@hienlh/ppm 0.18.12 → 0.18.14

package/src/services/named-tunnel/cloudflared-login.service.ts

@@ -0,0 +1,182 @@
+/**
+ * Login session singleton behind the "log in to Cloudflare" popup.
+ *
+ * One process-per-machine at a time: a second `startLogin` call while one is
+ * live (`waiting`/`slow`) just returns the current snapshot instead of
+ * spawning a competing `cloudflared tunnel login`. Every terminal state
+ * (`success`/`timeout`/`cancelled`/`error`) drops the process ref, so the
+ * *next* call after a terminal state always starts a genuinely fresh process
+ * with a fresh URL — a killed session's URL is gone for good, there is no
+ * "cert appears later" path once the process is dead.
+ */
+import { readOriginCertState } from "./cloudflared-cert.ts";
+import { loginArgs } from "./named-tunnel-args.ts";
+import { ensureCloudflared } from "../cloudflared.service.ts";
+import { killProcessTree } from "../windows-process-tree.ts";
+import { broadcastGlobalEvent } from "../../server/ws/global.ts";
+import { verifyCertLive, pinsMatch, renameCertAside, pumpLoginStream } from "./cloudflared-login-helpers.ts";
+
+export type LoginState = "idle" | "waiting" | "slow" | "success" | "timeout" | "cancelled" | "error";
+export interface LoginSnapshot { state: LoginState; url: string | null; message: string | null }
+
+export const LOGIN_SLOW_MS = 60_000;
+export const LOGIN_TIMEOUT_MS = 300_000;
+const CERT_POLL_MS = 2_000;
+
+interface Session {
+  state: LoginState;
+  url: string | null;
+  message: string | null;
+  proc: ReturnType<typeof Bun.spawn> | null;
+  slowTimer: ReturnType<typeof setTimeout> | null;
+  killTimer: ReturnType<typeof setTimeout> | null;
+  certPollTimer: ReturnType<typeof setInterval> | null;
+}
+
+function freshSession(): Session {
+  return { state: "idle", url: null, message: null, proc: null, slowTimer: null, killTimer: null, certPollTimer: null };
+}
+
+let session: Session = freshSession();
+
+export function getLoginSnapshot(): LoginSnapshot {
+  return { state: session.state, url: session.url, message: session.message };
+}
+
+function clearTimers(): void {
+  if (session.slowTimer) clearTimeout(session.slowTimer);
+  if (session.killTimer) clearTimeout(session.killTimer);
+  if (session.certPollTimer) clearInterval(session.certPollTimer);
+  session.slowTimer = null;
+  session.killTimer = null;
+  session.certPollTimer = null;
+}
+
+/** Move to a terminal state: clear timers, drop the process ref, broadcast. */
+function setTerminal(state: LoginState, message: string | null): void {
+  clearTimers();
+  session.proc = null;
+  session.state = state;
+  session.message = message;
+  broadcastGlobalEvent({ type: "tunnel:login_state", state, message: message ?? undefined });
+}
+
+/** Wraps `pumpLoginStream` with this module's session-singleton hooks. */
+function pumpStream(stream: ReadableStream<Uint8Array>, proc: ReturnType<typeof Bun.spawn>): Promise<void> {
+  return pumpLoginStream(stream, {
+    isSuperseded: () => session.proc !== proc,
+    hasUrl: () => session.url != null,
+    onUrl: (url) => {
+      session.url = url;
+      broadcastGlobalEvent({ type: "tunnel:login_url", url });
+    },
+    onSuccess: () => setTerminal("success", "logged in"),
+  });
+}
+
+/**
+ * Start (or return the live) login session.
+ *
+ * The cert-present shortcut is intentionally re-verified on every call — not
+ * a bare `existsSync` — because a replaced or revoked cert must never
+ * silently pass as "already logged in".
+ */
+export async function startLogin(opts: { relogin?: boolean } = {}): Promise<LoginSnapshot> {
+  if (session.state === "waiting" || session.state === "slow") {
+    return getLoginSnapshot();
+  }
+
+  const relogin = !!opts.relogin;
+  if (!relogin) {
+    const certState = readOriginCertState();
+    if (certState.kind === "parsed") {
+      const liveCheck = await verifyCertLive(certState.cert.apiToken);
+
+      // WHY: a network blip must never discard a working credential. Only an
+      // authoritative "Cloudflare said no" (invalid) or a confirmed pin
+      // mismatch earns a rename-aside below; "unreachable" means the check
+      // itself failed to run, so cert.pem is left untouched and the user
+      // gets a clear, retryable error instead of an unwanted fresh login.
+      if (liveCheck === "unreachable") {
+        setTerminal("error", "không kết nối được Cloudflare để kiểm tra đăng nhập — thử lại");
+        return getLoginSnapshot();
+      }
+
+      if (liveCheck === "valid" && pinsMatch(certState.cert)) {
+        session = freshSession();
+        session.state = "success";
+        session.message = "already logged in";
+        return getLoginSnapshot();
+      }
+
+      // liveCheck === "invalid" (Cloudflare authoritatively rejected the
+      // token), or valid but pinned to a different account/zone: this cert
+      // can never pass the shortcut again as-is — move it aside now instead
+      // of leaving a bad file to keep silently triggering the same
+      // fallthrough on every future login attempt.
+      renameCertAside();
+    }
+  } else {
+    // Explicit ?relogin=1 — the user deliberately pressed "Đăng nhập lại",
+    // so this renames unconditionally regardless of network reachability.
+    renameCertAside();
+  }
+
+  const bin = await ensureCloudflared();
+  const proc = Bun.spawn([bin, ...loginArgs()], { stdout: "pipe", stderr: "pipe" });
+  session = { state: "waiting", url: null, message: null, proc, slowTimer: null, killTimer: null, certPollTimer: null };
+
+  session.slowTimer = setTimeout(() => {
+    if (session.proc !== proc) return;
+    session.state = "slow";
+    broadcastGlobalEvent({ type: "tunnel:login_state", state: "slow" });
+  }, LOGIN_SLOW_MS);
+
+  session.killTimer = setTimeout(() => {
+    if (session.proc !== proc) return;
+    killProcessTree(proc.pid);
+    setTerminal("timeout", "login timed out after 5 minutes");
+  }, LOGIN_TIMEOUT_MS);
+
+  session.certPollTimer = setInterval(() => {
+    if (session.proc !== proc) return;
+    if (readOriginCertState().kind === "parsed") setTerminal("success", "logged in");
+  }, CERT_POLL_MS);
+
+  Promise.all([pumpStream(proc.stdout, proc), pumpStream(proc.stderr, proc)])
+    .then(async () => {
+      if (session.proc !== proc) return; // already terminal
+      const code = await proc.exited;
+      if (session.proc !== proc) return;
+      if (code === 0) {
+        setTerminal("success", "logged in");
+      } else {
+        setTerminal("error", `cloudflared exited with code ${code}`);
+      }
+    })
+    .catch(() => {});
+
+  return getLoginSnapshot();
+}
+
+/** Kill the live process immediately (if any) and mark the session cancelled. */
+export function cancelLogin(): void {
+  if (session.proc) killProcessTree(session.proc.pid);
+  setTerminal("cancelled", "cancelled");
+}
+
+// Orphaned login process on server crash/restart would otherwise wait forever
+// for a browser callback that lands nowhere.
+process.on("exit", () => {
+  if (session.proc) {
+    try { killProcessTree(session.proc.pid); } catch {}
+  }
+});
+
+/**
+ * Aggregate for callers that need a single patchable seam (the HTTP routes) —
+ * route tests monkey-patch these properties directly rather than reaching for
+ * `mock.module`, which replaces the module for every importer process-wide and
+ * would poison the direct-function unit tests in this same file's test suite.
+ */
+export const cloudflaredLoginService = { getLoginSnapshot, startLogin, cancelLogin };

package/src/services/named-tunnel/hostname-rules.ts

@@ -0,0 +1,58 @@
+/**
+ * Hostname shape rules for the named tunnel.
+ *
+ * Exactly one label above the zone, never the apex, never `www`. Two reasons,
+ * not just a rule to copy: `cloudflared route dns` never errors on a hostname
+ * outside the zone — it silently appends the zone instead (e.g. asking for
+ * `ppm-probe.ppm.sh` under zone `hienle.tech` creates `ppm-probe.ppm.sh.hienle.tech`),
+ * so PPM must refuse before calling it; and Cloudflare's free Universal SSL
+ * certificate only covers one level of subdomain, so a deeper label parses fine
+ * here but serves a TLS error to every visitor.
+ */
+
+export type HostnameCheck = { ok: true } | { ok: false; reason: string };
+
+const LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+const MAX_HOSTNAME_LENGTH = 253;
+
+/** Default proposal shown to the user: `ppm.<zone>`. */
+export function proposeHostname(zone: string): string {
+  return `ppm.${zone.trim().toLowerCase()}`;
+}
+
+/** Combine a user-typed prefix with the pinned zone. */
+export function buildHostname(prefix: string, zone: string): string {
+  return `${prefix.trim().toLowerCase()}.${zone.trim().toLowerCase()}`;
+}
+
+export function validateHostname(hostname: string, zone: string): HostnameCheck {
+  const host = hostname.trim().toLowerCase();
+  const z = zone.trim().toLowerCase();
+  if (!host || !z) return { ok: false, reason: "hostname and zone are required" };
+  if (host.length > MAX_HOSTNAME_LENGTH) return { ok: false, reason: "hostname exceeds 253 characters" };
+
+  if (host === z) {
+    return { ok: false, reason: "hostname cannot be the zone apex — a PPM token must never rewrite the zone's own record" };
+  }
+  if (host === `www.${z}`) {
+    return { ok: false, reason: "www is reserved" };
+  }
+  if (!host.endsWith(`.${z}`)) {
+    return { ok: false, reason: `hostname must be a subdomain of ${z} — cloudflared silently mis-routes anything else` };
+  }
+
+  // Everything above the zone must be exactly one label — Cloudflare's free
+  // certificate only covers one level, and a deeper label serves a TLS error.
+  const prefix = host.slice(0, host.length - z.length - 1);
+  if (prefix.includes(".")) {
+    return { ok: false, reason: "hostname must be exactly one label above the zone" };
+  }
+
+  for (const label of host.split(".")) {
+    if (!LABEL.test(label)) {
+      return { ok: false, reason: `invalid DNS label: "${label}"` };
+    }
+  }
+
+  return { ok: true };
+}

package/src/services/named-tunnel/login-output-parser.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure parsers for `cloudflared tunnel login` stdout/stderr chunks.
+ *
+ * cloudflared prints the browser URL and progress lines on stderr, not
+ * stdout (verified 2026-09-05, cloudflared 2026.3.0) — callers must feed both
+ * streams through these functions, never stdout alone.
+ */
+
+/** Primary shape: the real dash.cloudflare.com/argotunnel URL cloudflared prints today. */
+const PRIMARY_URL = /https:\/\/dash\.cloudflare\.com\/argotunnel\?[^\s]+/;
+
+/** Exact success line cloudflared prints on a successful login, exit code 0. */
+const SUCCESS_LINE = /You have successfully logged in\./;
+
+/**
+ * Extract the login URL from a stdout/stderr chunk (or accumulated buffer).
+ * Falls back to the first `https://` token on any line mentioning
+ * "argotunnel" so a cosmetic rename of the URL shape never leaves the flow
+ * stuck at `waiting` with no way for the user to open the browser page.
+ */
+export function extractLoginUrl(text: string): string | null {
+  const primary = text.match(PRIMARY_URL);
+  if (primary) return primary[0];
+
+  for (const line of text.split(/\r?\n/)) {
+    if (!/argotunnel/i.test(line)) continue;
+    const fallback = line.match(/https:\/\/[^\s]+/);
+    if (fallback) return fallback[0];
+  }
+  return null;
+}
+
+/** True once cloudflared has printed its success line. */
+export function isLoginSuccess(text: string): boolean {
+  return SUCCESS_LINE.test(text);
+}

package/src/services/named-tunnel/named-tunnel-args.ts

@@ -0,0 +1,110 @@
+/**
+ * cloudflared argv builders for the named-tunnel flow, plus the two artifact
+ * files they depend on. Every builder here guarantees its own artifacts (mirrors
+ * `cloudflared.service.ts`'s `getQuickTunnelArgs` → `ensureQuickTunnelConfig`
+ * pattern) rather than assuming an earlier phase already created them.
+ *
+ * The run token never appears in argv, ever — it is written to a 0600 file and
+ * passed via `--token-file`, so it can't leak through `ppm status`, a process
+ * list, or a crash dump that captures cmdlines.
+ */
+import { resolve } from "node:path";
+import { hostname as osHostname } from "node:os";
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from "node:fs";
+import { getPpmDir } from "../ppm-dir.ts";
+import { getOriginCertPath } from "./cloudflared-cert.ts";
+
+const namedTunnelConfigPath = () => resolve(getPpmDir(), "cloudflared-named.yml");
+const namedTunnelTokenPath = () => resolve(getPpmDir(), "named-tunnel.token");
+const isWindows = process.platform === "win32";
+
+/**
+ * Ensure `getPpmDir()` exists without letting a pre-existing directory throw
+ * EEXIST (Windows read-only-attribute folders — Desktop/Documents/Downloads —
+ * have thrown on a recursive mkdir here before even though the dir was already
+ * present and usable).
+ */
+function ensurePpmDir(): void {
+  if (existsSync(getPpmDir())) return;
+  try {
+    mkdirSync(getPpmDir(), { recursive: true, mode: 0o700 });
+  } catch (e: any) {
+    if (e?.code !== "EEXIST") throw e;
+  }
+}
+
+/** Best-effort chmod — POSIX enforces the mode; Windows has no equivalent bit. */
+function chmodBestEffort(path: string, mode: number): void {
+  if (isWindows) return;
+  try { chmodSync(path, mode); } catch {}
+}
+
+/**
+ * Create `~/.ppm/cloudflared-named.yml` if absent; returns its path.
+ * A comment-only file still parses but logs `ERR Configuration file ... was
+ * empty` on every command (harmless noise, verified live); a *missing* file
+ * exits 1. `no-autoupdate: true` is a real, valid key so the file is never
+ * comment-only.
+ */
+export function ensureNamedTunnelConfig(): string {
+  const path = namedTunnelConfigPath();
+  if (!existsSync(path)) {
+    ensurePpmDir();
+    writeFileSync(path, "no-autoupdate: true\n", { mode: 0o600 });
+  }
+  chmodBestEffort(path, 0o600);
+  return path;
+}
+
+/** Write the run token to a 0600 file; returns its path. Overwritten on every call. */
+export function writeNamedTunnelToken(token: string): string {
+  ensurePpmDir();
+  const path = namedTunnelTokenPath();
+  writeFileSync(path, token, { mode: 0o600 });
+  chmodBestEffort(path, 0o600);
+  return path;
+}
+
+/** `tunnel login` has no cert yet, so no `--origincert` — that flag would point nowhere. */
+export function loginArgs(): string[] {
+  return ["tunnel", "login"];
+}
+
+/** Global flags (`--origincert`/`--config`) always precede the subcommand. */
+function managementPrefix(): string[] {
+  return ["--origincert", getOriginCertPath(), "--config", ensureNamedTunnelConfig()];
+}
+
+export function createTunnelArgs(name: string): string[] {
+  return [...managementPrefix(), "tunnel", "create", name];
+}
+
+export function tunnelTokenArgs(name: string): string[] {
+  return [...managementPrefix(), "tunnel", "token", name];
+}
+
+/**
+ * `--overwrite-dns` only when the caller has confirmed this is our own tunnel's
+ * UUID being re-pointed (e.g. after a reset) — never passed blindly, since it
+ * silently steals a CNAME that might belong to something else.
+ */
+export function routeDnsArgs(name: string, hostname: string, overwrite: boolean): string[] {
+  const flags = overwrite ? ["--overwrite-dns"] : [];
+  return [...managementPrefix(), "tunnel", "route", "dns", ...flags, name, hostname];
+}
+
+/**
+ * Argv for the long-running named-tunnel process. No `--token` literal ever
+ * appears here — only a path to a 0600 file cloudflared reads itself.
+ */
+export function namedRunArgs(token: string, port: number): string[] {
+  const cfg = ensureNamedTunnelConfig();
+  const tokenPath = writeNamedTunnelToken(token);
+  return ["--config", cfg, "tunnel", "run", "--token-file", tokenPath, "--url", `http://127.0.0.1:${port}`];
+}
+
+/** Stable, DNS-safe tunnel name derived from this machine's hostname. */
+export function tunnelNameForHost(): string {
+  const sanitized = osHostname().toLowerCase().replace(/[^a-z0-9-]/g, "-");
+  return `ppm-${sanitized}`.slice(0, 32);
+}

package/src/services/named-tunnel/named-tunnel-config.ts

@@ -0,0 +1,67 @@
+/**
+ * Runtime resolver: turns the persisted `tunnel` config row into the shape the
+ * supervisor and UI actually consume. This is where "incomplete" data degrades
+ * to quick — storage (`sanitizeConfig`) never makes that judgment itself, so
+ * `/disable`'s documented "keep the config so Retry works" contract survives a
+ * config round-trip.
+ */
+
+export type TunnelMode = "quick" | "named";
+
+export interface ResolvedTunnelConfig {
+  mode: TunnelMode;
+  hostname: string | null;
+  tunnelName: string | null;
+  token: string | null;
+  zoneID: string | null;
+  accountID: string | null;
+  dismissed: boolean;
+}
+
+const QUICK: Omit<ResolvedTunnelConfig, "dismissed"> = {
+  mode: "quick", hostname: null, tunnelName: null, token: null, zoneID: null, accountID: null,
+};
+
+function nonEmptyString(v: unknown): v is string {
+  return typeof v === "string" && v.length > 0;
+}
+
+export function resolveTunnelConfig(raw: unknown): ResolvedTunnelConfig {
+  let obj: Record<string, unknown> | null = null;
+  if (typeof raw === "string") {
+    try { obj = JSON.parse(raw); } catch { obj = null; }
+  } else if (raw && typeof raw === "object") {
+    obj = raw as Record<string, unknown>;
+  }
+
+  const dismissed = obj != null && typeof obj.dismissed === "boolean" ? obj.dismissed : false;
+
+  // Named mode requires BOTH the stored mode flag AND all four identity fields —
+  // checking fields alone would resurrect a tunnel the user explicitly disabled,
+  // since /disable intentionally keeps namedTunnel* fields around for Retry.
+  const named = obj != null && obj.mode === "named" &&
+    nonEmptyString(obj.namedTunnelToken) &&
+    nonEmptyString(obj.namedTunnelHostname) &&
+    nonEmptyString(obj.zoneID) &&
+    nonEmptyString(obj.accountID);
+
+  if (!named || obj == null) {
+    return { ...QUICK, dismissed };
+  }
+
+  return {
+    mode: "named",
+    hostname: obj.namedTunnelHostname as string,
+    tunnelName: nonEmptyString(obj.namedTunnelName) ? obj.namedTunnelName : null,
+    token: obj.namedTunnelToken as string,
+    zoneID: obj.zoneID as string,
+    accountID: obj.accountID as string,
+    dismissed,
+  };
+}
+
+/** `abcdef...` — first 6 chars + ellipsis; never the full secret. */
+export function maskToken(token: string | null): string | null {
+  if (token == null) return null;
+  return `${token.slice(0, 6)}...`;
+}

package/src/services/named-tunnel/named-tunnel-probe-state.ts

@@ -0,0 +1,95 @@
+/**
+ * Pure decision function for the named-tunnel probe's "restart once, then warn
+ * and stop" state machine. Kept separate from `supervisor.ts` (which owns the
+ * actual kill/respawn/status-write side effects) so the transition logic is
+ * unit-testable without spawning a real cloudflared process or timers.
+ *
+ * The bug this exists to prevent: resetting `restartAttempted` anywhere other
+ * than a confirmed-healthy observation lets a dark hostname (e.g. the CNAME
+ * deleted in the dashboard) restart the connector every threshold window
+ * forever, because the RESTART itself always "succeeds" (cloudflared happily
+ * reconnects to Cloudflare's edge) even though the DNS route it needs is gone —
+ * a spawn success is not proof the hostname is reachable, only the probe's own
+ * fetch against the public URL is.
+ */
+
+export interface NamedProbeState {
+  /** Consecutive unhealthy probe cycles observed since the last reset. */
+  failCount: number;
+  /** Whether the one allowed restart-and-hope has already been used since the
+   *  last confirmed-healthy observation. */
+  restartAttempted: boolean;
+}
+
+export type NamedProbeAction =
+  | { type: "healthy" }
+  /** Counting a failure. `warnEarly` marks the tick that should surface a
+   *  soft "checking the connection" notice without touching the connector. */
+  | { type: "watch"; warnEarly: boolean }
+  | { type: "restart-once" }
+  | { type: "warn-and-stop" };
+
+export interface NamedProbeDecision {
+  action: NamedProbeAction;
+  nextState: NamedProbeState;
+}
+
+/**
+ * Is the thing answering the public hostname *our* server? `publicId` is the
+ * `instanceId` the hostname returned, `localId` the one our loopback server
+ * returned; either may be missing.
+ *
+ * A deleted CNAME does not make the hostname go dark — it falls back to the
+ * zone's wildcard record and some unrelated host answers 200 with a body that
+ * has no `instanceId`. If we know our own identity and the public answer lacks
+ * one (or differs), the hostname is not ours. Only when our own server has no
+ * identity (a build that predates `instanceId`) do we accept bare reachability.
+ */
+export function publicHostnameIsOurs(publicId: unknown, localId: unknown): boolean {
+  if (typeof localId !== "string") return true;
+  return typeof publicId === "string" && publicId === localId;
+}
+
+/**
+ * Decide the next action for one probe tick.
+ *
+ * - `healthy` → both counters reset to a clean slate (the only place
+ *   `restartAttempted` ever goes back to `false`).
+ * - unhealthy below `threshold` → `watch`. Acting on a dark hostname is
+ *   deliberately slow (a flaky minute must not kill a working connector), but
+ *   *saying nothing* for that long is a different decision: `watch` carries
+ *   `warnEarly` on the tick that crosses `earlyWarnAt`, so the UI can show
+ *   "checking the connection" while the restart budget is still untouched.
+ * - unhealthy at/above `threshold`, first time → `restart-once` (kill +
+ *   respawn the connector; arms `restartAttempted` so this never repeats
+ *   until a healthy observation clears it).
+ * - unhealthy at/above `threshold`, restart already attempted → `warn-and-stop`
+ *   (surface the warning; never kill again — the pinned URL stays put).
+ */
+export function decideNamedProbeAction(
+  healthy: boolean,
+  state: NamedProbeState,
+  threshold: number,
+  earlyWarnAt = 2,
+): NamedProbeDecision {
+  if (healthy) {
+    return { action: { type: "healthy" }, nextState: { failCount: 0, restartAttempted: false } };
+  }
+
+  const failCount = state.failCount + 1;
+  if (failCount < threshold) {
+    // Only on the crossing tick: re-writing the same warning every 30s would
+    // rewrite status.json forever for no new information.
+    const warnEarly = failCount === earlyWarnAt;
+    return {
+      action: { type: "watch", warnEarly },
+      nextState: { failCount, restartAttempted: state.restartAttempted },
+    };
+  }
+
+  if (!state.restartAttempted) {
+    return { action: { type: "restart-once" }, nextState: { failCount: 0, restartAttempted: true } };
+  }
+
+  return { action: { type: "warn-and-stop" }, nextState: { failCount: 0, restartAttempted: true } };
+}

package/src/services/named-tunnel/named-tunnel-readiness.ts

@@ -0,0 +1,59 @@
+/**
+ * Offset-anchored readiness reader for cloudflared's stderr log file.
+ *
+ * A quick or named tunnel is only "ready" once cloudflared writes a specific
+ * line to its log. The caller truncates that log before every spawn, but the
+ * truncation is best-effort and silently fails on Windows while a previous
+ * detached cloudflared process still holds the file open — so a scan of the
+ * WHOLE file can match a line left over from a dead connector and declare it
+ * "ready" in well under 200ms. Anchoring every read to a byte offset captured
+ * right after the truncate attempt makes that impossible: only bytes appended
+ * by THIS process generation are ever considered.
+ */
+import { existsSync, readFileSync } from "node:fs";
+
+export interface WaitForLogLineOpts {
+  /** Only bytes at or after this offset are scanned — excludes any content
+   *  left behind by a previous process generation. */
+  fromByteOffset: number;
+  timeoutMs: number;
+  /** Poll-time check for whether the watched process has already exited. */
+  getExitCode: () => number | null;
+  pollIntervalMs?: number;
+}
+
+/**
+ * Poll `path` until `regex` matches within the bytes appended after
+ * `fromByteOffset`, the watched process exits, or `timeoutMs` elapses.
+ *
+ * Reads the file as a Buffer and slices by byte offset (not string index) so
+ * a multi-byte UTF-8 character straddling the offset is never corrupted —
+ * `toString("utf8")` re-decodes the whole remaining tail on every poll, so a
+ * boundary can only delay a match by one poll interval, never corrupt it.
+ */
+export async function waitForLogLine(
+  path: string,
+  regex: RegExp,
+  opts: WaitForLogLineOpts,
+): Promise<string> {
+  const deadline = Date.now() + opts.timeoutMs;
+  const pollMs = opts.pollIntervalMs ?? 200;
+
+  while (Date.now() < deadline) {
+    if (existsSync(path)) {
+      try {
+        const buf = readFileSync(path);
+        const tail = buf.subarray(opts.fromByteOffset).toString("utf8");
+        const match = tail.match(regex);
+        if (match) return match[0];
+      } catch {
+        // Transient read race (file replaced mid-poll) — retry next tick.
+      }
+    }
+    if (opts.getExitCode() !== null) {
+      throw new Error(`cloudflared exited without matching ${regex}`);
+    }
+    await Bun.sleep(pollMs);
+  }
+  throw new Error(`readiness timeout (${opts.timeoutMs}ms)`);
+}

package/src/services/named-tunnel/named-tunnel-runtime.ts

@@ -0,0 +1,42 @@
+/**
+ * Runtime seam between "what's persisted" (named-tunnel-config.ts) and "what
+ * to actually spawn" (cloudflared.service.ts / named-tunnel-args.ts). Kept out
+ * of supervisor.ts (already large) and out of phase 1b's config/argv modules
+ * so neither grows to own the other's concern.
+ */
+import { getConfigValue } from "../db.service.ts";
+import { resolveTunnelConfig, type ResolvedTunnelConfig, type TunnelMode } from "./named-tunnel-config.ts";
+import { getQuickTunnelArgs } from "../cloudflared.service.ts";
+import { namedRunArgs } from "./named-tunnel-args.ts";
+
+/**
+ * Fresh (non-cached) read of the persisted tunnel config.
+ *
+ * The supervisor runs in its own process with its own `configService`
+ * singleton, which never observes writes the server process makes to
+ * SQLite — so every caller here must go through `getConfigValue` (a raw DB
+ * read), never `configService.get`, or the supervisor would spawn/adopt
+ * against a stale mode forever.
+ */
+export async function readTunnelConfigFresh(): Promise<ResolvedTunnelConfig> {
+  return resolveTunnelConfig(getConfigValue("tunnel"));
+}
+
+export interface TunnelSpawnPlan {
+  mode: TunnelMode;
+  args: string[];
+}
+
+/**
+ * Pick the argv for the next tunnel spawn attempt from a resolved config.
+ * When `config.mode` is not `"named"` (or the token is somehow absent —
+ * `resolveTunnelConfig` already guarantees this can't happen for a config row
+ * with `mode: "named"`, this is belt-and-suspenders), the output is exactly
+ * `getQuickTunnelArgs(port)` — byte-identical to today's quick-only argv.
+ */
+export function chooseTunnelSpawn(config: ResolvedTunnelConfig, port: number): TunnelSpawnPlan {
+  if (config.mode === "named" && config.token) {
+    return { mode: "named", args: namedRunArgs(config.token, port) };
+  }
+  return { mode: "quick", args: getQuickTunnelArgs(port) };
+}