@hienlh/ppm 0.18.11 → 0.18.13

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) };
+}

package/src/services/named-tunnel/named-tunnel-setup-confirm.ts

@@ -0,0 +1,98 @@
+/**
+ * Detached confirmation for a named-tunnel setup.
+ *
+ * Once the supervisor reload has been sent, `runSetup` returns to the caller
+ * immediately (a 45s status.json poll must never hold the HTTP response —
+ * see the setup service's own comment) and this module polls status.json in
+ * the background, broadcasting the final outcome over `/ws/global`.
+ *
+ * WHY a generation stamp: `setupInFlight`'s synchronous 409 lock is already
+ * released by the time this runs, and `isConfirmationRunning` only extends
+ * the 409 to a *same-hostname* retry (see the setup service) — a request for
+ * a *different* hostname is allowed straight through and immediately
+ * supersedes whatever confirmation was still polling. Without a generation
+ * check, that superseded confirmer would still broadcast its own result
+ * (`setup_done` or `setup_pending`) 1s-to-45s later, carrying the *old*
+ * hostname and overwriting the correct, newer result in every connected
+ * client. Each confirmation run is stamped with a monotonic generation, and
+ * a confirmer checks it is still the current one immediately before
+ * broadcasting — a superseded confirmer exits silently instead.
+ */
+import { readStatus } from "../supervisor-state.ts";
+import { broadcastGlobalEvent } from "../../server/ws/global.ts";
+
+const CONFIRM_POLL_BUDGET_MS = 45_000;
+const CONFIRM_POLL_INTERVAL_MS = 1_000;
+
+let generation = 0;
+/** The hostname + deadline of the confirmation currently allowed to broadcast. */
+let current: { hostname: string; deadline: number } | null = null;
+
+/**
+ * True while a background confirmation is still running for `hostname`.
+ * Bounded by the same poll budget the confirmer itself uses, so a wedged
+ * confirmation can never lock a hostname out of retry forever. A different
+ * hostname's confirmation immediately closes this window (superseding is
+ * unconditional, not per-hostname), matching "a different hostname proceeds
+ * and takes over" below.
+ */
+export function isConfirmationRunning(hostname: string): boolean {
+  return current !== null && current.hostname === hostname && Date.now() < current.deadline;
+}
+
+async function pollForConfirmation(hostname: string, budgetMs: number, intervalMs: number): Promise<boolean> {
+  const deadline = Date.now() + budgetMs;
+  while (Date.now() < deadline) {
+    const status = readStatus();
+    if (status.tunnelMode === "named" && status.shareUrl === `https://${hostname}`) return true;
+    await Bun.sleep(intervalMs);
+  }
+  return false;
+}
+
+/**
+ * Fire-and-forget: polls status.json and broadcasts the final outcome.
+ * Never throws into the caller. Silently drops its own broadcast if a newer
+ * setup (any hostname) has started since — see the module docstring.
+ * `opts` exists only so tests can shrink the poll budget/interval; production
+ * always uses the real 45s/1s constants.
+ */
+export function confirmReloadInBackground(
+  hostname: string,
+  opts: { pollBudgetMs?: number; pollIntervalMs?: number } = {},
+): void {
+  const budgetMs = opts.pollBudgetMs ?? CONFIRM_POLL_BUDGET_MS;
+  const intervalMs = opts.pollIntervalMs ?? CONFIRM_POLL_INTERVAL_MS;
+  const myGeneration = ++generation;
+  current = { hostname, deadline: Date.now() + budgetMs };
+  const isSuperseded = () => generation !== myGeneration;
+
+  pollForConfirmation(hostname, budgetMs, intervalMs)
+    .then((confirmed) => {
+      if (isSuperseded()) return;
+      if (confirmed) {
+        broadcastGlobalEvent({ type: "tunnel:setup_done", hostname });
+        return;
+      }
+      const latest = readStatus();
+      const warning = typeof latest.tunnelWarning === "string" ? latest.tunnelWarning : null;
+      broadcastGlobalEvent({
+        type: "tunnel:setup_pending",
+        hostname,
+        message: warning ?? "setup saved but the supervisor has not confirmed it yet — check again shortly",
+      });
+    })
+    .catch(() => {
+      if (isSuperseded()) return;
+      broadcastGlobalEvent({
+        type: "tunnel:setup_pending",
+        hostname,
+        message: "confirmation check failed — check status again shortly",
+      });
+    })
+    .finally(() => {
+      // Release the 409 window once this generation settles — but only if
+      // nothing newer has already taken `current` over.
+      if (!isSuperseded() && current) current.deadline = 0;
+    });
+}

package/src/services/named-tunnel/named-tunnel-setup.service.ts

@@ -0,0 +1,191 @@
+/**
+ * Zone → precheck → create → route → token → persist → confirm.
+ *
+ * The DNS collision precheck runs *before* `tunnel create`, so "is this
+ * record already ours" is answered via the Cloudflare API's own tunnel
+ * lookup-by-name (an idempotent retry has an existing tunnel; a first-time
+ * setup does not) rather than by depending on `create` having already run.
+ */
+import { readOriginCertState } from "./cloudflared-cert.ts";
+import { fetchZoneName } from "./cloudflare-zone-api.ts";
+import { fetchDnsRecords, fetchTunnelIdByName } from "./cloudflare-dns-api.ts";
+import { proposeHostname, validateHostname } from "./hostname-rules.ts";
+import { createTunnelArgs, routeDnsArgs, tunnelTokenArgs, tunnelNameForHost } from "./named-tunnel-args.ts";
+import { runCloudflared } from "./cloudflared-exec.ts";
+import { configService } from "../config.service.ts";
+import { requestTunnelReload, readStatus } from "../supervisor-state.ts";
+import { broadcastGlobalEvent } from "../../server/ws/global.ts";
+import { pinsMatch } from "./cloudflared-login-helpers.ts";
+import { confirmReloadInBackground, isConfirmationRunning } from "./named-tunnel-setup-confirm.ts";
+
+export type CertState = "none" | "invalid" | "ok" | "mismatch";
+
+/** Thrown by the flow below; routes map `.status` straight to the HTTP response. */
+export class SetupError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+  }
+}
+
+// `cloudflared tunnel token` prints one line of standard base64 (with `+`, `/`
+// and `=` padding — a real token is ~180 chars ending in `=`), not URL-safe
+// base64, so the alphabet must include those three or every real token is
+// rejected as "unexpected output".
+const TOKEN_SHAPE = /^[A-Za-z0-9+/=._-]{100,}$/;
+const RELOAD_RETRY_DELAY_MS = 2_000;
+
+/** Module-level in-flight guard — two concurrent setups would race `route dns`. */
+let setupInFlight = false;
+
+/**
+ * Read-mostly cert classification for `/status` — never leaks the token.
+ * `"mismatch"` is a pure pin comparison (no network call): the parsed cert's
+ * zoneID/accountID differ from whatever `tunnel` config already pinned, i.e.
+ * cloudflared logged into a *different* Cloudflare account than the one this
+ * machine's named tunnel was set up under.
+ */
+export function currentCertState(): CertState {
+  const state = readOriginCertState();
+  if (state.kind === "absent") return "none";
+  if (state.kind === "unparseable") return "invalid";
+  return pinsMatch(state.cert) ? "ok" : "mismatch";
+}
+
+export async function readZoneInfo(): Promise<{ zone: string; zoneID: string; accountID: string; proposedHostname: string }> {
+  const certState = readOriginCertState();
+  if (certState.kind !== "parsed") throw new SetupError(400, "Not logged in to Cloudflare");
+  if (!pinsMatch(certState.cert)) {
+    throw new SetupError(400, "cert belongs to a different Cloudflare account — log in again");
+  }
+  const zone = await fetchZoneName(certState.cert.zoneID, certState.cert.apiToken);
+  return { zone, zoneID: certState.cert.zoneID, accountID: certState.cert.accountID, proposedHostname: proposeHostname(zone) };
+}
+
+export async function disableNamedTunnel(): Promise<void> {
+  const current = configService.get("tunnel");
+  configService.set("tunnel", { ...current, mode: "quick" });
+  requestTunnelReload();
+}
+
+export type SetupOutcome =
+  | { ok: true; hostname: string; tunnelName: string }
+  | { ok: "pending"; hostname: string; tunnelName: string; message: string };
+
+/**
+ * The synchronous `setupInFlight` lock only covers the create/route/token
+ * cycle — once the supervisor reload is sent, confirmation continues in the
+ * background (`named-tunnel-setup-confirm.ts`) and this function has already
+ * returned. `isConfirmationRunning` extends the 409 specifically to a retry
+ * for the *same* hostname during that bounded (<=45s) window, so mashing
+ * "Set up" doesn't kick off a second, redundant create/route/token cycle for
+ * a request that is already in flight. A *different* hostname is still let
+ * through immediately and supersedes the earlier confirmer — see the confirm
+ * module for how the stale one is silenced instead of broadcasting late.
+ */
+export async function runSetup(hostname: string): Promise<SetupOutcome> {
+  if (setupInFlight) throw new SetupError(409, "a setup is already running");
+  if (isConfirmationRunning(hostname)) {
+    throw new SetupError(409, "a setup for this hostname is already confirming — check again shortly");
+  }
+  setupInFlight = true;
+  try {
+    return await runSetupInner(hostname);
+  } finally {
+    setupInFlight = false;
+  }
+}
+
+async function runSetupInner(hostname: string): Promise<SetupOutcome> {
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "zone", message: "reading Cloudflare zone" });
+  const certState = readOriginCertState();
+  if (certState.kind !== "parsed") throw new SetupError(400, "Not logged in to Cloudflare");
+  const { zoneID, accountID, apiToken } = certState.cert;
+
+  const zone = await fetchZoneName(zoneID, apiToken);
+  const check = validateHostname(hostname, zone);
+  if (!check.ok) throw new SetupError(400, check.reason);
+
+  const tunnelName = tunnelNameForHost();
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "precheck", message: "checking for a DNS collision" });
+  const existingId = await fetchTunnelIdByName(accountID, apiToken, tunnelName);
+  const records = await fetchDnsRecords(zoneID, apiToken, hostname);
+  let overwrite = false;
+  if (records.length > 0) {
+    const ownTarget = existingId ? `${existingId}.cfargotunnel.com` : null;
+    const isOwn = ownTarget != null && records.some((r) => r.content === ownTarget);
+    if (!isOwn) throw new SetupError(400, "that name already points somewhere else — pick another prefix");
+    overwrite = true;
+  }
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "create", message: "creating tunnel" });
+  const create = await runCloudflared(createTunnelArgs(tunnelName));
+  if (create.code !== 0 && !/already exists/i.test(create.stderr)) {
+    throw new SetupError(500, `cloudflared tunnel create failed: ${(create.stderr || create.stdout).trim()}`);
+  }
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "route", message: "routing DNS" });
+  const route = await runCloudflared(routeDnsArgs(tunnelName, hostname, overwrite));
+  if (route.code !== 0) {
+    throw new SetupError(500, `cloudflared tunnel route dns failed: ${(route.stderr || route.stdout).trim()}`);
+  }
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "token", message: "fetching run token" });
+  const tokenResult = await runCloudflared(tunnelTokenArgs(tunnelName));
+  const token = tokenResult.stdout.trim();
+  if (tokenResult.code !== 0 || !TOKEN_SHAPE.test(token)) {
+    throw new SetupError(500, "unexpected cloudflared output while fetching the run token");
+  }
+
+  broadcastGlobalEvent({ type: "tunnel:setup_step", step: "apply", message: "applying configuration" });
+  configService.set("tunnel", {
+    mode: "named",
+    namedTunnelName: tunnelName,
+    namedTunnelHostname: hostname,
+    namedTunnelToken: token,
+    zoneID,
+    accountID,
+  });
+
+  const pending = (message: string): SetupOutcome => {
+    broadcastGlobalEvent({ type: "tunnel:setup_pending", hostname, message });
+    return { ok: "pending", hostname, tunnelName, message };
+  };
+
+  const status = readStatus();
+  const capabilities = Array.isArray(status.capabilities) ? (status.capabilities as unknown[]) : [];
+  if (!capabilities.includes("retunnel")) {
+    return pending("run `ppm restart` to apply — this PPM version needs a restart to pick up named tunnels");
+  }
+
+  let reload = requestTunnelReload();
+  if (reload === "busy") {
+    await Bun.sleep(RELOAD_RETRY_DELAY_MS);
+    reload = requestTunnelReload();
+  }
+  if (reload === "busy") {
+    return pending("supervisor busy — it will pick up the new setting shortly, or run `ppm restart`");
+  }
+  if (reload === "no-supervisor") {
+    return pending("no supervisor detected — run `ppm restart`");
+  }
+
+  // reload === "sent" — don't block the HTTP response on up to 45s of
+  // polling: a proxy/tunnel in front of PPM with a shorter idle timeout would
+  // time the browser out while setup was actually succeeding. Confirm
+  // detached and let /ws/global carry the final result (setup_done, or a
+  // follow-up setup_pending if confirmation itself times out) — the UI
+  // already listens for both events.
+  confirmReloadInBackground(hostname);
+  return pending("reload sent — waiting for the supervisor to confirm");
+}
+
+/**
+ * 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 this file's own direct-function unit tests.
+ */
+export const namedTunnelSetupService = { readZoneInfo, runSetup, disableNamedTunnel, currentCertState };

package/src/services/supervisor-state.ts

@@ -71,7 +71,10 @@ export function writeStatus(data: Record<string, unknown>) {
 }
 
 // ─── Command file protocol ─────────────────────────────────────────────
-export type CmdAction = "soft_stop" | "resume" | "restart";
+// "upgrade" is written directly by upgrade.service.ts (bypasses writeCmd, same
+// as restart.ts/stop.ts) and read by supervisor.ts's Windows poll loop — listed
+// here so the type matches what's actually read/written on disk.
+export type CmdAction = "soft_stop" | "resume" | "restart" | "retunnel" | "upgrade";
 
 /** Atomically claim + read command file (rename to .claimed, read, delete) */
 export function readAndDeleteCmd(): { action: CmdAction } | null {
@@ -88,8 +91,70 @@ export function readAndDeleteCmd(): { action: CmdAction } | null {
   }
 }
 
-export function writeCmd(action: CmdAction) {
+/**
+ * `retunnel` is the only low-priority action — it always yields to whatever
+ * is already pending, since a named-tunnel reload can wait behind a genuine
+ * lifecycle transition. The other three outrank it: a `resume` stuck behind
+ * an unclaimed `retunnel` would otherwise leave the server looking stopped
+ * (win32's poll loop is 1s; POSIX has a write/SIGUSR2 gap) for no reason.
+ */
+const LIFECYCLE_ACTIONS: readonly CmdAction[] = ["resume", "soft_stop", "restart", "upgrade"];
+
+/**
+ * Write `.supervisor-cmd`, but never clobber a *different* action that's still
+ * unclaimed — with one exception: a lifecycle action (`resume`/`soft_stop`/
+ * `restart`/`upgrade`) always overwrites a pending `retunnel`. Any other
+ * collision (two different lifecycle actions, or a `retunnel` behind a
+ * pending lifecycle action) returns `false` without writing so the caller can
+ * report "busy" instead of silently discarding someone else's request; a
+ * warning is logged either way so a dropped command is never silent. Note:
+ * `restart.ts`/`stop.ts` write this file directly and bypass this peek
+ * entirely, so the supervisor's dispatcher must still treat a stale/racing
+ * action defensively regardless of who wrote it — this is a best-effort
+ * single-slot guard, not a full queue.
+ */
+export function writeCmd(action: CmdAction): boolean {
+  try {
+    const existing = JSON.parse(readFileSync(CMD_FILE(), "utf-8")) as { action?: string };
+    if (existing?.action && existing.action !== action) {
+      const lifecycleOverridesRetunnel = LIFECYCLE_ACTIONS.includes(action) && existing.action === "retunnel";
+      if (!lifecycleOverridesRetunnel) {
+        try { process.stderr.write(`[writeCmd] dropped "${action}" — "${existing.action}" is already pending\n`); } catch {}
+        return false;
+      }
+    }
+  } catch {
+    // Missing file, unreadable, or invalid JSON — nothing unclaimed to protect.
+  }
   writeFileSync(CMD_FILE(), JSON.stringify({ action }));
+  return true;
+}
+
+/**
+ * Ask the running supervisor to reload the tunnel (e.g. after a named-tunnel
+ * setup/disable). POSIX confirms the supervisor is alive via a zero-signal
+ * probe before writing; win32 has no equivalent probe here, so it relies on
+ * the supervisor's existing 1s command-file poll loop to pick up the request.
+ */
+export function requestTunnelReload(): "sent" | "busy" | "no-supervisor" {
+  const status = readStatus();
+  const pid = status.supervisorPid as number | undefined;
+  if (!pid) return "no-supervisor";
+
+  if (process.platform !== "win32") {
+    try {
+      process.kill(pid, 0);
+    } catch {
+      return "no-supervisor";
+    }
+  }
+
+  if (!writeCmd("retunnel")) return "busy";
+
+  if (process.platform !== "win32") {
+    try { process.kill(pid, "SIGUSR2"); } catch { /* best-effort; poll loop is the fallback path */ }
+  }
+  return "sent";
 }
 
 // ─── Lockfile ──────────────────────────────────────────────────────────