@hienlh/ppm 0.23.6 → 0.23.7

package/src/services/speech-to-text/whisper-install.service.ts

@@ -0,0 +1,247 @@
+/**
+ * Installing Whisper on the host: download the prebuilt whisper.cpp for this
+ * platform, the chosen speech model, and the VAD model, then prove the binary
+ * actually runs here.
+ *
+ * That last step is not ceremony. The published Linux build needs glibc 2.34
+ * and libstdc++ from GCC 11, so on an older host (Ubuntu 20.04 ships glibc
+ * 2.31) every file downloads fine and the binary only fails when someone first
+ * speaks into the chat box. Running `--help` once at install time turns that
+ * into an install error naming the cause.
+ *
+ * One model is kept on disk at a time: they are 60–574 MB, and "which one is
+ * active" then has no state to drift — it is whichever file is there.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  DEFAULT_MODEL_ID,
+  MACOS_INSTALL_HINT,
+  VAD_MODEL,
+  WHISPER_MODELS,
+  WHISPER_VERSION,
+  modelById,
+  modelUrl,
+  vadModelUrl,
+  whisperAssetFor,
+  type WhisperAsset,
+} from "./whisper-catalog.ts";
+import { downloadVerified, type FetchFn } from "./whisper-download.ts";
+import {
+  findWhisperBinary,
+  whisperBinDir,
+  whisperDir,
+  whisperModelDir,
+  whisperTmpDir,
+  type WhisperBinary,
+} from "./whisper-paths.ts";
+
+export type InstallPhase = "binary" | "model" | "vad" | "verify";
+
+export interface InstallJobState {
+  modelId: string;
+  phase: InstallPhase;
+  receivedBytes: number;
+  totalBytes: number;
+  done: boolean;
+  error: string | null;
+}
+
+export interface WhisperStatusModel {
+  id: string;
+  label: string;
+  note: string;
+  bytes: number;
+}
+
+export interface WhisperStatus {
+  /** False only when this platform has no prebuilt build AND no binary on the host. */
+  installable: boolean;
+  /** Manual command for a platform PPM cannot install for (macOS). */
+  installHint: string | null;
+  binary: WhisperBinary | null;
+  version: string;
+  /** Model currently on disk, if any. */
+  model: WhisperStatusModel | null;
+  /** Binary + model + VAD model all present — the mic can use it. */
+  ready: boolean;
+  models: WhisperStatusModel[];
+  install: InstallJobState | null;
+}
+
+let currentJob: InstallJobState | null = null;
+
+const publicModel = (m: (typeof WHISPER_MODELS)[number]): WhisperStatusModel => ({
+  id: m.id,
+  label: m.label,
+  note: m.note,
+  bytes: m.bytes,
+});
+
+/** The installed model, found by which catalog file exists on disk. */
+export function installedModel(): (typeof WHISPER_MODELS)[number] | null {
+  return WHISPER_MODELS.find((m) => existsSync(resolve(whisperModelDir(), m.file))) ?? null;
+}
+
+export function vadModelPath(): string {
+  return resolve(whisperModelDir(), VAD_MODEL.file);
+}
+
+export function getWhisperStatus(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): WhisperStatus {
+  const binary = findWhisperBinary(platform);
+  const model = installedModel();
+  const hasAsset = whisperAssetFor(platform, arch) !== null;
+
+  return {
+    installable: hasAsset || binary !== null,
+    installHint: !hasAsset && platform === "darwin" ? MACOS_INSTALL_HINT : null,
+    binary,
+    version: WHISPER_VERSION,
+    model: model ? publicModel(model) : null,
+    ready: binary !== null && model !== null && existsSync(vadModelPath()),
+    models: WHISPER_MODELS.map(publicModel),
+    install: currentJob,
+  };
+}
+
+async function extractArchive(archive: string, asset: WhisperAsset, destDir: string, platform: NodeJS.Platform) {
+  const cmd =
+    asset.ext === "tar.gz"
+      ? ["tar", "-xzf", archive, "-C", destDir]
+      : platform === "win32"
+        ? // Windows 10+ ships bsdtar as tar.exe, which reads zip.
+          ["tar", "-xf", archive, "-C", destDir]
+        : ["unzip", "-o", "-q", archive, "-d", destDir];
+
+  const proc = Bun.spawn({ cmd, stdout: "ignore", stderr: "pipe" });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`extract failed (${cmd[0]} exit ${code}): ${stderr.slice(0, 200)}`);
+  }
+}
+
+/** Run the binary once so a host that cannot execute it fails here, not mid-sentence. */
+async function verifyBinaryRuns(path: string): Promise<void> {
+  let proc;
+  try {
+    proc = Bun.spawn({ cmd: [path, "--help"], stdout: "ignore", stderr: "pipe", windowsHide: true });
+  } catch (e: any) {
+    throw new Error(`whisper-cli could not be started: ${e?.message ?? e}`);
+  }
+  const [code, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+  if (code !== 0) {
+    const detail = stderr.trim().split("\n")[0] ?? `exit ${code}`;
+    throw new Error(`whisper-cli does not run on this host: ${detail}`);
+  }
+}
+
+/** Keep only the model just installed — the others are hundreds of MB of nothing. */
+function pruneOtherModels(keepFile: string) {
+  for (const m of WHISPER_MODELS) {
+    if (m.file !== keepFile) rmSync(resolve(whisperModelDir(), m.file), { force: true });
+  }
+}
+
+async function runInstall(modelId: string, platform: NodeJS.Platform, arch: string, fetchFn?: FetchFn) {
+  const model = modelById(modelId);
+  if (!model) throw new Error(`unknown model: ${modelId}`);
+  const job = currentJob!;
+  const progress = (received: number, total: number) => {
+    job.receivedBytes = received;
+    job.totalBytes = total || 0;
+  };
+
+  mkdirSync(whisperModelDir(), { recursive: true });
+
+  // A host that already has whisper-cli (Homebrew, distro package) needs models only.
+  if (!findWhisperBinary(platform)) {
+    const asset = whisperAssetFor(platform, arch);
+    if (!asset) throw new Error(`no whisper.cpp build for ${platform}/${arch} — install it manually`);
+    job.phase = "binary";
+    mkdirSync(whisperBinDir(), { recursive: true });
+    mkdirSync(whisperTmpDir(), { recursive: true });
+    const archive = resolve(whisperTmpDir(), asset.file);
+    await downloadVerified({ url: asset.url, dest: archive, sha256: asset.sha256, onProgress: progress, fetchFn });
+    await extractArchive(archive, asset, whisperBinDir(), platform);
+    rmSync(archive, { force: true });
+  }
+
+  job.phase = "model";
+  progress(0, model.bytes);
+  await downloadVerified({
+    url: modelUrl(model),
+    dest: resolve(whisperModelDir(), model.file),
+    sha256: model.sha256,
+    onProgress: progress,
+    fetchFn,
+  });
+
+  job.phase = "vad";
+  progress(0, VAD_MODEL.bytes);
+  await downloadVerified({
+    url: vadModelUrl(),
+    dest: vadModelPath(),
+    sha256: VAD_MODEL.sha256,
+    onProgress: progress,
+    fetchFn,
+  });
+
+  job.phase = "verify";
+  const binary = findWhisperBinary(platform);
+  if (!binary) throw new Error("whisper-cli missing after install");
+  await verifyBinaryRuns(binary.path);
+
+  pruneOtherModels(model.file);
+}
+
+/**
+ * Start an install in the background and return immediately — the UI polls
+ * `getWhisperStatus()`. One at a time: a second call while a job runs throws.
+ */
+export function startWhisperInstall(
+  modelId: string = DEFAULT_MODEL_ID,
+  opts: { platform?: NodeJS.Platform; arch?: string; fetchFn?: FetchFn } = {},
+): InstallJobState {
+  if (currentJob && !currentJob.done) throw new Error("An install is already running");
+  const platform = opts.platform ?? process.platform;
+  const arch = opts.arch ?? process.arch;
+  if (!modelById(modelId)) throw new Error(`unknown model: ${modelId}`);
+
+  const job: InstallJobState = {
+    modelId,
+    phase: "binary",
+    receivedBytes: 0,
+    totalBytes: 0,
+    done: false,
+    error: null,
+  };
+  currentJob = job;
+
+  runInstall(modelId, platform, arch, opts.fetchFn)
+    .then(() => {
+      job.done = true;
+    })
+    .catch((e: any) => {
+      job.error = e?.message ?? String(e);
+      job.done = true;
+      console.error("[whisper] install failed:", job.error);
+    });
+
+  return job;
+}
+
+/** Remove everything PPM downloaded. A system-installed whisper-cli is left alone. */
+export function uninstallWhisper(): void {
+  if (currentJob && !currentJob.done) throw new Error("An install is running");
+  rmSync(whisperDir(), { recursive: true, force: true });
+  currentJob = null;
+}
+
+/** Test seam: forget any finished job so a suite starts from a clean status. */
+export function _resetWhisperInstallState(): void {
+  currentJob = null;
+}

package/src/services/speech-to-text/whisper-paths.ts

@@ -0,0 +1,62 @@
+/**
+ * Where the Whisper install lives, and how the binary is found.
+ *
+ * Everything PPM downloads sits under `<ppm dir>/whisper/` so uninstall is one
+ * `rm -rf` and an isolated `PPM_HOME` (tests) never touches a real install.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { getPpmDir } from "../ppm-dir.ts";
+
+export const whisperDir = () => resolve(getPpmDir(), "whisper");
+export const whisperBinDir = () => resolve(whisperDir(), "bin");
+export const whisperModelDir = () => resolve(whisperDir(), "models");
+export const whisperTmpDir = () => resolve(whisperDir(), "tmp");
+
+export const cliName = (platform: NodeJS.Platform = process.platform) =>
+  platform === "win32" ? "whisper-cli.exe" : "whisper-cli";
+
+/**
+ * The extracted archive keeps its own top-level directory — `whisper-bin-ubuntu-x64/`
+ * on Linux, `Release/` on Windows — and those names carry the build tag, so the
+ * binary is located by looking one level down rather than assumed.
+ */
+export function findBundledBinary(platform: NodeJS.Platform = process.platform): string | null {
+  const root = whisperBinDir();
+  if (!existsSync(root)) return null;
+  const name = cliName(platform);
+  if (existsSync(resolve(root, name))) return resolve(root, name);
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const candidate = resolve(root, entry.name, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Homebrew's `whisper.cpp` is how a Mac gets a `whisper-cli` (the release has no
+ * macOS CLI to download), and a PPM started by launchd/systemd inherits a PATH
+ * that usually has neither Homebrew prefix in it — so both are checked directly
+ * rather than trusting `PATH` alone.
+ */
+const SYSTEM_PATHS = ["/opt/homebrew/bin/whisper-cli", "/usr/local/bin/whisper-cli", "/usr/bin/whisper-cli"];
+
+export function findSystemBinary(): string | null {
+  const onPath = Bun.which("whisper-cli");
+  if (onPath) return onPath;
+  return SYSTEM_PATHS.find((p) => existsSync(p)) ?? null;
+}
+
+export interface WhisperBinary {
+  path: string;
+  /** `bundled` = installed by PPM and removable from Settings; `system` = the host's own. */
+  source: "bundled" | "system";
+}
+
+export function findWhisperBinary(platform: NodeJS.Platform = process.platform): WhisperBinary | null {
+  const bundled = findBundledBinary(platform);
+  if (bundled) return { path: bundled, source: "bundled" };
+  const system = findSystemBinary();
+  return system ? { path: system, source: "system" } : null;
+}

package/src/services/speech-to-text/whisper-transcribe.service.ts

@@ -0,0 +1,117 @@
+/**
+ * One transcription = one `whisper-cli` run over a temp WAV.
+ *
+ * Per-request process rather than a long-lived `whisper-server`, for two
+ * reasons: Homebrew's formula builds with `WHISPER_BUILD_SERVER=OFF`, so a Mac
+ * has no server binary to talk to; and a resident server holds the model
+ * (574 MB) in RAM between sentences that are minutes apart.
+ *
+ * Runs are serialised. Two at once would each load the model and fight for the
+ * same cores, turning two five-second waits into two twelve-second ones.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, rmSync } from "node:fs";
+import { availableParallelism } from "node:os";
+import { resolve } from "node:path";
+import { isInventedLine } from "./whisper-hallucinations.ts";
+import { installedModel, vadModelPath } from "./whisper-install.service.ts";
+import { findWhisperBinary, whisperModelDir, whisperTmpDir } from "./whisper-paths.ts";
+
+const TIMEOUT_MS = 180_000;
+
+/**
+ * whisper.cpp defaults to 4 threads. Measured on a 24-thread i9-12900K with
+ * large-v3-turbo over a 10s clip: 4 threads 12.0s, 8 threads 8.1s, 16 threads
+ * 5.6s, 24 threads 5.4s — so it is worth raising, and worth capping where the
+ * curve flattens instead of taking every core the host has.
+ */
+export function threadCount(cpus: number = availableParallelism()): number {
+  return Math.max(1, Math.min(16, cpus));
+}
+
+/** A non-speech annotation on a line of its own: "[BLANK_AUDIO]", "(nhạc)", "*gunshot*". */
+const ANNOTATION = /^[[(*][^)\]*]*[\])*]$/;
+
+/**
+ * `-nt` prints text without timestamps, one line per segment. Three kinds of
+ * line are not something anyone dictated: an annotation, a line with no letter
+ * or digit in it at all (a bare "." is what this model makes of a hum in
+ * English), and a sentence it invented out of non-speech — see
+ * whisper-hallucinations.ts.
+ */
+export function parseWhisperText(stdout: string): string {
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(
+      (line) =>
+        line.length > 0 &&
+        !ANNOTATION.test(line) &&
+        /[\p{L}\p{N}]/u.test(line) &&
+        !isInventedLine(line),
+    )
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function whisperArgs(binary: string, wavPath: string, modelPath: string, language: string): string[] {
+  return [
+    binary,
+    "-m", modelPath,
+    "-f", wavPath,
+    "-l", language,
+    "-t", String(threadCount()),
+    "-nt",
+    "-np",
+    // Without VAD, silence is transcribed as an invented sentence — see whisper-catalog.ts.
+    "--vad",
+    "--vad-model", vadModelPath(),
+  ];
+}
+
+let queue: Promise<unknown> = Promise.resolve();
+
+export interface TranscribeResult {
+  text: string;
+  /** Wall time of the whisper-cli run, for the UI's "took Ns" and for tuning. */
+  ms: number;
+}
+
+/** Throws when Whisper is not installed, the run fails, or it outruns the timeout. */
+export async function transcribeWav(wav: Uint8Array, language = "vi"): Promise<TranscribeResult> {
+  const run = queue.then(() => runOnce(wav, language));
+  // Keep the chain alive after a failure, and never leak the rejection through it.
+  queue = run.catch(() => {});
+  return run;
+}
+
+async function runOnce(wav: Uint8Array, language: string): Promise<TranscribeResult> {
+  const binary = findWhisperBinary();
+  const model = installedModel();
+  if (!binary || !model) throw new Error("Whisper is not installed on this host");
+
+  mkdirSync(whisperTmpDir(), { recursive: true });
+  const wavPath = resolve(whisperTmpDir(), `${randomUUID()}.wav`);
+  await Bun.write(wavPath, wav);
+
+  const started = Date.now();
+  try {
+    const cmd = whisperArgs(binary.path, wavPath, resolve(whisperModelDir(), model.file), language);
+    const proc = Bun.spawn({ cmd, stdout: "pipe", stderr: "pipe", stdin: "ignore", windowsHide: true });
+    const timer = setTimeout(() => proc.kill(), TIMEOUT_MS);
+    const [stdout, stderr, code] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+    clearTimeout(timer);
+    if (code !== 0) {
+      const detail = stderr.trim().split("\n").slice(-1)[0] ?? `exit ${code}`;
+      throw new Error(`whisper-cli failed: ${detail}`);
+    }
+    return { text: parseWhisperText(stdout), ms: Date.now() - started };
+  } finally {
+    rmSync(wavPath, { force: true });
+  }
+}

package/src/services/supervisor.ts

@@ -20,7 +20,7 @@ import {
   readAndDeleteCmd, readStatus, updateStatus, writeStatus,
   STATUS_FILE, PID_FILE,
 } from "./supervisor-state.ts";
-import type { ResolvedTunnelConfig, TunnelMode } from "./named-tunnel/named-tunnel-config.ts";
+import { resolveTunnelConfig, type ResolvedTunnelConfig, type TunnelMode } from "./named-tunnel/named-tunnel-config.ts";
 import { readTunnelConfigFresh, chooseTunnelSpawn } from "./named-tunnel/named-tunnel-runtime.ts";
 import { waitForLogLine } from "./named-tunnel/named-tunnel-readiness.ts";
 import { nextNamedRetryDelayMs } from "./named-tunnel/named-tunnel-retry.ts";
@@ -101,6 +101,11 @@ const TUNNEL_REGEN_MIN_INTERVAL_MS = 300_000; // 5min
 // cache, never `configService` (a separate process, stale here) nor a fresh
 // async DB read (would reorder the startup adopt/probe-before-spawn race).
 let namedTunnelMode: ResolvedTunnelConfig | null = null;
+// Effective master switch: the argv flag AND `tunnel.enabled` from config.
+// Module-level rather than a local because the SIGUSR1 and Windows-command
+// handlers close over it before startup reaches the config read, and because
+// `retunnel` flips it live when the user toggles the switch.
+let tunnelSharingEnabled = false;
 // The mode of the tunnel actually spawned (as opposed to `namedTunnelMode`,
 // which is merely the persisted intent) — a token failure leaves config=named
 // but live=quick, and every status write / throttle / restart decision must
@@ -430,6 +435,26 @@ function restartTunnel(port: number) {
   spawnTunnel(port).catch((e) => log("ERROR", `restartTunnel failed: ${e}`));
 }
 
+/**
+ * Tear the tunnel down for good because the master switch went off — as opposed
+ * to `restartTunnel`, which kills in order to respawn.
+ *
+ * Bumping the generation is the load-bearing part: the running spawn loop is
+ * awaiting its child's `exited` and would otherwise treat the kill as a crash
+ * and respawn. The probe needs no stopping — it returns early once there is no
+ * `tunnelUrl` and no live process.
+ */
+function stopTunnelForDisable(): void {
+  tunnelGeneration++;
+  cancelNamedRetry();
+  namedRetryAttempt = 0;
+  if (tunnelChild) { try { tunnelChild.kill(); } catch {} tunnelChild = null; }
+  if (adoptedTunnelPid) { try { process.kill(adoptedTunnelPid, "SIGTERM"); } catch {} adoptedTunnelPid = null; }
+  tunnelUrl = null;
+  tunnelPort = null;
+  updateStatus({ shareUrl: null, tunnelPid: null, tunnelPort: null });
+}
+
 // ─── Server shutdown ───────────────────────────────────────────────────
 // On Windows the server's Claude SDK grandchildren are node-spawned (the
 // provider forces `executable: "node"`), so they live OUTSIDE Bun's job
@@ -855,6 +880,14 @@ export async function spawnTunnel(port: number, generation: number = ++tunnelGen
   // setup, disable, or token rotation since the last spawn must be picked up
   // before deciding what to spawn next.
   namedTunnelMode = await readTunnelConfigFresh();
+  // The freshest possible view of the master switch, so consult it here rather than
+  // relying on all six call sites remembering to. Two of them — the Windows
+  // leaked-probe-handle restart and the edge probe's respawns — do not, and a
+  // respawn is exactly when a switch flipped since the last spawn should take hold.
+  if (!namedTunnelMode.enabled) {
+    log("INFO", "Public tunnel is switched off — not spawning cloudflared");
+    return;
+  }
 
   let bin: string;
   try {
@@ -1206,6 +1239,10 @@ async function probeNamedTunnelHealth(): Promise<boolean> {
 }
 
 function startTunnelProbe() {
+  // Idempotent: a supervisor that booted with the tunnel switched off never
+  // started this, and turning the switch on has to be able to start it then —
+  // without leaving a second interval behind on the boots that did start it.
+  if (tunnelProbeTimer) return;
   tunnelProbeTimer = setInterval(async () => {
     if (shuttingDown || !tunnelUrl) { tunnelFailCount = 0; return; }
     if (!tunnelChild && !adoptedTunnelPid) { tunnelFailCount = 0; return; }
@@ -2049,7 +2086,16 @@ export async function runSupervisor(opts: {
         // restarts the ladder so a later transient failure gets a full budget.
         cancelNamedRetry();
         namedRetryAttempt = 0;
-        restartTunnel(_opts.port);
+        // `retunnel` is also how the master switch is applied without a
+        // restart, so it has to be able to mean "stop" and not only "respawn".
+        tunnelSharingEnabled = _opts.share && namedTunnelMode.enabled;
+        if (tunnelSharingEnabled) {
+          startTunnelProbe();
+          restartTunnel(_opts.port);
+        } else {
+          log("INFO", "Tunnel switched off — tearing down the running tunnel");
+          stopTunnelForDisable();
+        }
         // Deliberate fall-through (no return): a bare `ppm restart` sends a
         // bare SIGUSR2 with no command file of its own, and a `retunnel` that
         // happens to still be unclaimed at that instant must not silently
@@ -2091,7 +2137,7 @@ export async function runSupervisor(opts: {
       log("ERROR", `Self-replace failed: ${result.error}, restarting children`);
       spawnServer(serverArgs, logFd);
       // Tunnel was kept alive during selfReplace; only respawn if dead
-      if (opts.share && !tunnelChild && !tunnelUrl) spawnTunnel(_opts.port);
+      if (tunnelSharingEnabled && !tunnelChild && !tunnelUrl) spawnTunnel(_opts.port);
     }
   });
 
@@ -2200,7 +2246,16 @@ export async function runSupervisor(opts: {
           tunnelFailCount = 0;
           cancelNamedRetry();
           namedRetryAttempt = 0;
-          restartTunnel(_opts.port);
+          // Same dual meaning as the POSIX path: this is how the master switch
+          // is applied live, so it must also be able to mean "stop".
+          tunnelSharingEnabled = _opts.share && cfg.enabled;
+          if (tunnelSharingEnabled) {
+            startTunnelProbe();
+            restartTunnel(_opts.port);
+          } else {
+            log("INFO", "Tunnel switched off — tearing down the running tunnel");
+            stopTunnelForDisable();
+          }
         });
       }
       else if (cmd.action === "upgrade") {
@@ -2209,7 +2264,7 @@ export async function runSupervisor(opts: {
           if (!result.success) {
             log("ERROR", `Self-replace failed: ${result.error}, restarting children`);
             spawnServer(serverArgs, logFd);
-            if (opts.share && !tunnelChild && !tunnelUrl) spawnTunnel(_opts.port);
+            if (tunnelSharingEnabled && !tunnelChild && !tunnelUrl) spawnTunnel(_opts.port);
           }
         });
       }
@@ -2229,12 +2284,34 @@ export async function runSupervisor(opts: {
   // tunnel's origin port (public URL continuity), so adoption state must be
   // settled first — the old order raced spawnServer's port selection.
   let tunnelAdopted = false;
-  if (opts.share) {
-    // Populate the cache BEFORE adoptTunnel/probe — an adopted tunnel skips
-    // spawnTunnel entirely for this whole generation, so without this the
-    // cache would stay null (adoptTunnel's named-hostname gate always refuses,
-    // and the probe can never tell named from quick) until the next spawn.
+  // Populate the cache BEFORE adoptTunnel/probe — an adopted tunnel skips
+  // spawnTunnel entirely for this whole generation, so without this the
+  // cache would stay null (adoptTunnel's named-hostname gate always refuses,
+  // and the probe can never tell named from quick) until the next spawn.
+  // It also carries the master switch, so it is read before the gate rather
+  // than inside it.
+  // This read must not be able to decide whether the edge below gets spawned.
+  // It already did once: a `systemctl restart` brought this process up while
+  // the outgoing one still held the database's write lock, the rejection ended
+  // startup right here, and PPM ran for eight minutes with nothing listening on
+  // its public port — the server child came back on the health check, which has
+  // no equivalent for an edge that was never started in the first place.
+  //
+  // The fallback is sharing OFF, not the resolver's default: an absent config
+  // row means "on" (it predates the master switch), so defaulting would publish
+  // a tunnel for someone who had switched sharing off and whose config merely
+  // could not be read.
+  try {
     namedTunnelMode = await readTunnelConfigFresh();
+  } catch (e) {
+    log("ERROR", `Tunnel config unreadable — continuing with sharing off: ${e}`);
+    namedTunnelMode = resolveTunnelConfig({ enabled: false });
+  }
+  tunnelSharingEnabled = opts.share && namedTunnelMode.enabled;
+  if (opts.share && !tunnelSharingEnabled) {
+    log("INFO", "Tunnel off (tunnel.enabled = false) — no cloudflared will be started");
+  }
+  if (tunnelSharingEnabled) {
     // Defensive — already `false` at module init, but a fresh boot must never
     // start with an inherited restart-once budget "spent".
     namedProbeRestartAttempted = false;
@@ -2250,6 +2327,12 @@ export async function runSupervisor(opts: {
     // Sweep leftover cloudflared orphans (crashed supervisors / pre-fix stale
     // loops) so they don't saturate the network and false-trigger regeneration.
     await reapOrphanedTunnels(tunnelAdopted ? adoptedTunnelPid : null);
+  } else if (opts.share) {
+    // Switched off while a tunnel from an earlier boot is still alive: nothing
+    // adopts or probes it now, so it would go on serving a stale origin with no
+    // supervisor watching it.
+    killStaleTunnel();
+    await reapOrphanedTunnels(null);
   }
 
   // The edge owns the public port, so it must exist before anything else tries
@@ -2298,7 +2381,7 @@ export async function runSupervisor(opts: {
 
   // Spawn server + (fresh) tunnel in parallel
   const promises: Promise<void>[] = [spawnServer(serverArgs, logFd)];
-  if (opts.share && !tunnelAdopted) promises.push(spawnTunnel(_opts.port));
+  if (tunnelSharingEnabled && !tunnelAdopted) promises.push(spawnTunnel(_opts.port));
 
   await Promise.all(promises);