@openparachute/hub 0.6.1 → 0.6.3-rc.1

package/src/api-modules-ops.ts

@@ -39,6 +39,7 @@ import { MissingDependencyError, type MissingDependencyWire } from "@openparachu
 import { CURATED_MODULES, type CuratedModuleShort } from "./api-modules.ts";
 import { isLinked as defaultIsLinked } from "./bun-link.ts";
 import { PARACHUTE_INSTALL_CHANNEL_ENV } from "./commands/install.ts";
+import { buildModuleSpawnRequest } from "./commands/serve-boot.ts";
 import { getModuleInstallChannel } from "./hub-settings.ts";
 import { validateAccessToken } from "./jwt-sign.ts";
 import { readModuleManifest } from "./module-manifest.ts";
@@ -456,6 +457,11 @@ async function spawnSupervised(
   // anchors the child's iss expectation to the same value hub mints with.
   //
   // `deps.spawnEnv` still wins (test seam + first-boot vault-name pass-through).
+  //
+  // No per-service `.env` here, by design: the install path runs before the
+  // operator has had a chance to write `configDir/<short>/.env`, so install
+  // spawns with install-env only. The per-service `.env` is layered in by
+  // `buildModuleSpawnRequest` (serve-boot.ts) on the next `boot` or `start`.
   const childEnv: Record<string, string> = {
     PORT: String(entry.port),
     ...(deps.issuer ? { PARACHUTE_HUB_ORIGIN: deps.issuer } : {}),
@@ -713,6 +719,115 @@ export async function runInstall(
   registry.update(opId, { status: "succeeded" }, `${short} installed + spawned (pid ${state.pid})`);
 }
 
+/**
+ * POST /api/modules/:short/start — synchronous.
+ *
+ * A pure `supervisor.start(req)` of an ALREADY-INSTALLED module, using
+ * the same boot-derived SpawnRequest `bootSupervisedModules` builds
+ * (PORT / per-service .env / PARACHUTE_HUB_ORIGIN injection via the
+ * shared `buildModuleSpawnRequest`). This is the §3.3 endpoint Phase 3
+ * will repoint `parachute start <svc>` onto.
+ *
+ * Explicitly NOT an install: it does not run `bun add -g`, seed
+ * services.json, stamp installDir, or refresh well-known. If the module
+ * isn't in services.json (never installed) it returns 400 `not_installed`
+ * with an actionable hint — not a silent install. If services.json
+ * carries the row but no startCmd is resolvable (CLI-only module,
+ * unreadable module.json), it returns 422 `no_start_cmd`.
+ *
+ * Synchronous like restart: `supervisor.start` returns the new state in
+ * the body; no operation poll needed. Idempotent — starting an
+ * already-running module returns its existing state (the supervisor's
+ * own idempotent `start`).
+ */
+export async function handleStart(
+  req: Request,
+  short: CuratedModuleShort,
+  deps: ApiModulesOpsDeps,
+): Promise<Response> {
+  if (req.method !== "POST") return jsonError(405, "method_not_allowed", "use POST");
+  const authFail = await authorize(req, deps);
+  if (authFail) return authFail;
+
+  const spec = specFor(short);
+
+  // Pure-spawn precondition: the module must already be installed
+  // (present in services.json). `start` never installs — that's the
+  // install endpoint's job, which is far heavier (bun add -g / seed /
+  // stamp). A missing row is an operator error worth a clear message.
+  const entry = findService(spec.manifestName, deps.manifestPath);
+  if (!entry) {
+    return jsonError(
+      400,
+      "not_installed",
+      `${short} is not installed (no services.json entry) — install it first via POST /api/modules/${short}/install`,
+    );
+  }
+
+  // KNOWN_MODULES shorts (vault / scribe / runner): module.json is the
+  // canonical source for startCmd. Re-resolve from
+  // `<installDir>/.parachute/module.json` when installDir is stamped so the
+  // module is authoritative for its own spawn cmd — mirroring runInstall's
+  // post-bun-add re-resolve. Falls back to the imperative `extras.startCmd`
+  // carried by `spec` when installDir is absent or module.json is unreadable.
+  let spawnSpec: ServiceSpec = spec;
+  if (entry.installDir && KNOWN_MODULES[short]) {
+    const resolved = await resolveSpawnSpec(short, entry.installDir);
+    if (resolved) spawnSpec = resolved;
+  }
+
+  const cmd = spawnSpec.startCmd?.(entry);
+  if (!cmd || cmd.length === 0) {
+    return jsonError(
+      422,
+      "no_start_cmd",
+      `${short} has no resolvable startCmd (CLI-only module, or <installDir>/.parachute/module.json missing a startCmd)`,
+    );
+  }
+
+  // Build the SpawnRequest identically to the serve-boot path so `start`
+  // and boot produce the same child env (PORT / .env / HUB_ORIGIN). The
+  // test-seam / first-boot `spawnEnv` rides the shared helper's `extraEnv`
+  // and wins last, matching `spawnSupervised`'s precedence.
+  const spawnReq = buildModuleSpawnRequest(short, entry, cmd, {
+    configDir: deps.configDir,
+    ...(deps.issuer ? { hubOrigin: deps.issuer } : {}),
+    ...(deps.spawnEnv ? { extraEnv: deps.spawnEnv } : {}),
+  });
+
+  const state = await deps.supervisor.start(spawnReq);
+  return jsonOk({ short, state });
+}
+
+/**
+ * POST /api/modules/:short/stop — synchronous.
+ *
+ * A pure `supervisor.stop(short)` — SIGTERM the child, await exit (with
+ * SIGKILL escalation), mark `stopped`. Distinct from uninstall, which
+ * stops-then-removes the services.json row + `bun remove`s the package.
+ * `stop` leaves the module installed; it's the §3.3 endpoint Phase 3
+ * will repoint `parachute stop <svc>` onto.
+ *
+ * Idempotent: stopping a not-supervised module returns 200 with a
+ * `stopped: false` flag (nothing to stop) rather than erroring — the
+ * caller's intent ("ensure it's not running") is already satisfied.
+ */
+export async function handleStop(
+  req: Request,
+  short: CuratedModuleShort,
+  deps: ApiModulesOpsDeps,
+): Promise<Response> {
+  if (req.method !== "POST") return jsonError(405, "method_not_allowed", "use POST");
+  const authFail = await authorize(req, deps);
+  if (authFail) return authFail;
+
+  const state = await deps.supervisor.stop(short);
+  if (!state) {
+    return jsonOk({ short, stopped: false });
+  }
+  return jsonOk({ short, stopped: true, state });
+}
+
 /**
  * POST /api/modules/:short/restart — synchronous.
  *
@@ -741,6 +856,112 @@ export async function handleRestart(
   return jsonOk({ short, state });
 }
 
+/**
+ * GET /api/modules/:short/logs — synchronous.
+ *
+ * Serves the supervisor's bounded per-module ring buffer (§6.5): the most
+ * recent output the child wrote, INCLUDING the boot/crash lines that happened
+ * before the caller connected — which a naive connect-time SSE tap would lose
+ * (and which are "likely the most important one — the exit cause"). This is
+ * the §6 endpoint Phase 3 will repoint `parachute logs <svc>` onto.
+ *
+ * Returns the buffer as both a joined `text` blob and a `lines` array (the CLI
+ * tail wants the blob; a structured consumer wants lines). A module that isn't
+ * supervised returns 404 `not_supervised`, matching the `restart` handler's
+ * error contract for the same state — the caller can fall through to `start`.
+ *
+ * `?follow=1` is accepted as a best-effort streaming tap: we replay the buffer
+ * first (the must-have), then stream subsequent lines as `text/plain` chunks.
+ * The buffer replay is what captures the crash cause; the follow tail is the
+ * nice-to-have. Without `follow`, it's a one-shot JSON snapshot.
+ */
+export async function handleLogs(
+  req: Request,
+  short: CuratedModuleShort,
+  deps: ApiModulesOpsDeps,
+): Promise<Response> {
+  if (req.method !== "GET") return jsonError(405, "method_not_allowed", "use GET");
+  const authFail = await authorize(req, deps);
+  if (authFail) return authFail;
+
+  const lines = deps.supervisor.logs(short);
+  if (lines === undefined) {
+    // Same shape + status as `restart` for a not-supervised module, so the
+    // CLI client can treat both identically (fall through to `start`).
+    return jsonError(
+      404,
+      "not_supervised",
+      `${short} is not currently supervised — install or start it first`,
+    );
+  }
+
+  const follow = new URL(req.url).searchParams.get("follow");
+  if (follow === "1" || follow === "true") {
+    return streamModuleLogs(short, lines, deps);
+  }
+
+  // One-shot snapshot: the buffered lines as both a joined blob + the array.
+  return jsonOk({ short, lines, text: lines.join("") });
+}
+
+/**
+ * Best-effort follow stream (§6.5 nice-to-have). Replays the buffered lines
+ * (the must-have — captures the boot/crash cause) then forwards subsequent
+ * output as `text/plain` chunks by subscribing to a tee of the supervisor's
+ * live tap. The buffer replay is guaranteed; the live tail is opportunistic
+ * (it ends when the client disconnects or the module stops). Implemented via
+ * a polling diff of the ring buffer so it stays decoupled from `pumpLines`'
+ * internal sink and needs no new supervisor wiring.
+ */
+function streamModuleLogs(
+  short: CuratedModuleShort,
+  initial: string[],
+  deps: ApiModulesOpsDeps,
+): Response {
+  const encoder = new TextEncoder();
+  let lastLen = initial.length;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      // Replay the buffered lines first — the boot/crash cause.
+      for (const line of initial) controller.enqueue(encoder.encode(line));
+      timer = setInterval(() => {
+        const current = deps.supervisor.logs(short);
+        if (current === undefined) {
+          // Module went away (uninstalled / never-supervised) — end the stream.
+          if (timer) clearInterval(timer);
+          try {
+            controller.close();
+          } catch {
+            // already closed
+          }
+          return;
+        }
+        // The ring buffer may have dropped old lines off the front; only
+        // forward genuinely-new tail lines. If the buffer shrank below our
+        // cursor (eviction), reset to its current length to avoid replaying.
+        // Limitation: new lines written during a heavy eviction burst (a chatty
+        // module overflowing the 64KiB cap between two polls) may be skipped in
+        // the live tail — use the one-shot snapshot (no ?follow) for crash investigation.
+        if (current.length < lastLen) lastLen = current.length;
+        for (let i = lastLen; i < current.length; i++) {
+          const line = current[i];
+          if (line !== undefined) controller.enqueue(encoder.encode(line));
+        }
+        lastLen = current.length;
+      }, 500);
+    },
+    cancel() {
+      // Stop polling when the consumer disconnects.
+      if (timer) clearInterval(timer);
+    },
+  });
+  return new Response(stream, {
+    status: 200,
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
+  });
+}
+
 /**
  * POST /api/modules/:short/upgrade — async.
  *

package/src/api-modules.ts

@@ -42,8 +42,13 @@ import { FIRST_PARTY_FALLBACKS, KNOWN_MODULES } from "./service-spec.ts";
 // still required) and the latter for vault/scribe/runner (post-FALLBACK
 // retirement, hub#310). The local helper hides the split from the rest of
 // this file.
-import { type UiSubUnit, type UiSubUnitStatus, readManifest, readManifestLenient } from "./services-manifest.ts";
-import type { ModuleState, Supervisor } from "./supervisor.ts";
+import {
+  type UiSubUnit,
+  type UiSubUnitStatus,
+  readManifest,
+  readManifestLenient,
+} from "./services-manifest.ts";
+import type { ModuleStartError, ModuleState, Supervisor } from "./supervisor.ts";
 
 /**
  * Resolve a curated module to the display + install bootstrap data the
@@ -174,6 +179,16 @@ interface ModuleWireShape {
   latest_version: string | null;
   supervisor_status: ModuleState["status"] | null;
   pid: number | null;
+  /**
+   * Structured supervisor start-failure detail (§6.5 / §6.4), when the
+   * supervisor recorded one for this module — a preflight `MissingDependencyError`
+   * or the alive-but-never-bound shape (hub#487). Mirrors the services.json
+   * `lastStartError` the detached path persists, so `parachute status` and the
+   * SPA keep the SAME friendly missing-dependency surface (#188) whether a
+   * module was started via the supervisor or the detached path. Null when the
+   * module started cleanly (or the hub is in pidfile/CLI mode with no supervisor).
+   */
+  supervisor_start_error: ModuleStartError | null;
   /**
    * The path on disk where the module is installed, if known. Surfaces
    * the BUN_INSTALL or bun-link install location for operator debug —
@@ -477,6 +492,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       latest_version: latestByShort.get(short) ?? null,
       supervisor_status: state?.status ?? null,
       pid: state?.pid ?? null,
+      supervisor_start_error: state?.startError ?? null,
       install_dir: installed?.installDir ?? null,
       uis: toUisWireShape(installed?.uis),
       management_url: managementUrlByShort.get(short) ?? null,

package/src/cli.ts

@@ -454,7 +454,11 @@ async function main(argv: string[]): Promise<number> {
         console.log(statusHelp());
         return 0;
       }
-      return await status();
+      // Pass an empty `supervisor` block so `status` takes the Phase 3c
+      // dual-dispatch: on a box with a hub unit installed it reads the platform
+      // manager + the running supervisor; on a legacy detached box it falls back
+      // to the pidfile readout (design §6.4). Tests drive the seams directly.
+      return await status({ supervisor: {} });
 
     case "expose": {
       const hubExtract = extractHubOrigin(rest);
@@ -624,7 +628,13 @@ async function main(argv: string[]): Promise<number> {
         console.error(`parachute start: ${hubExtract.error}`);
         return 1;
       }
-      const startOpts = hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {};
+      // `supervisor: {}` opts into the Phase 3b dual-dispatch: on a box with a
+      // hub unit installed, drive the running supervisor; on a legacy detached
+      // box (no unit), fall through to the unchanged detached path (design §3.3).
+      const startOpts = {
+        supervisor: {},
+        ...(hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {}),
+      };
       return await start(hubExtract.rest[0], startOpts);
     }
 
@@ -633,7 +643,7 @@ async function main(argv: string[]): Promise<number> {
         console.log(stopHelp());
         return 0;
       }
-      return await stop(rest[0]);
+      return await stop(rest[0], { supervisor: {} });
     }
 
     case "restart": {
@@ -641,7 +651,7 @@ async function main(argv: string[]): Promise<number> {
         console.log(restartHelp());
         return 0;
       }
-      return await restart(rest[0]);
+      return await restart(rest[0], { supervisor: {} });
     }
 
     case "upgrade": {

package/src/cloudflare/connector-service.ts

@@ -0,0 +1,273 @@
+import {
+  type ManagedUnit,
+  type ManagedUnitDeps,
+  type ManagedUnitInstallResult,
+  type ManagedUnitMessages,
+  type ManagedUnitRemoveResult,
+  type ServiceCommandResult,
+  defaultManagedUnitDeps,
+  installManagedUnit,
+  launchdPlistPathForLabel,
+  removeManagedUnit,
+  renderManagedLaunchdPlist,
+  renderManagedSystemdUnit,
+  systemdUnitPathForName,
+} from "../managed-unit.ts";
+
+/**
+ * Reboot-persistent cloudflared connector.
+ *
+ * Pre-0.6.2 `parachute expose public --cloudflare` spawned the connector as a
+ * bare detached background process (`Bun.spawn(...).unref()`), which dies on
+ * reboot — the operator had to re-run the expose command every time the box
+ * restarted. This module installs a per-tunnel OS service that runs the same
+ * `cloudflared tunnel --config <path> run` command on boot, so the connector
+ * survives reboots.
+ *
+ * Platform shapes:
+ *   - macOS  → a launchd LaunchAgent plist at
+ *     `~/Library/LaunchAgents/computer.parachute.cloudflared.<tunnelName>.plist`
+ *     (RunAtLoad + KeepAlive), bootstrapped into the per-user GUI domain. No
+ *     sudo: a LaunchAgent runs as the logged-in user.
+ *   - Linux (non-root) → a systemd *user* unit at
+ *     `~/.config/systemd/user/parachute-cloudflared-<tunnelName>.service`,
+ *     `systemctl --user enable --now`, plus a best-effort
+ *     `loginctl enable-linger $USER` so the unit runs without an active login.
+ *   - Linux (root) → a systemd *system* unit at
+ *     `/etc/systemd/system/parachute-cloudflared-<tunnelName>.service`,
+ *     `systemctl enable --now`. No linger needed — system units run on boot.
+ *
+ * As of Phase 2b of the hub-as-supervisor unification, the per-platform
+ * install/remove/render machinery lives in `src/managed-unit.ts` as a reusable
+ * `ManagedUnit` abstraction (so the hub unit can reuse it — design §4.1). This
+ * module is now a thin connector-specific layer over that machinery: it builds
+ * the connector's `ManagedUnit` descriptor (empty env, no crash-loop ceiling —
+ * which keeps its rendered output BYTE-IDENTICAL to the pre-extraction code, the
+ * hard constraint since the connector is live on production) and supplies the
+ * connector-flavored install/remove messages. The public exports below keep
+ * their original signatures so `expose-cloudflare.ts` and the connector tests
+ * need no behavioral change.
+ *
+ * Everything is behind an injectable deps seam (re-exported `ConnectorServiceDeps`
+ * = the generalized `ManagedUnitDeps`) so tests drive the install/remove without
+ * touching real launchctl/systemctl or the operator's home directory.
+ *
+ * Service name keyed by the same per-host tunnel name the 0.6.1 work derives
+ * (`deriveTunnelName`), so install / remove always target the connector for
+ * exactly one tunnel and the expose off / legacy-sweep paths can tear it down.
+ */
+
+/** Synchronous command result from the injected service runner. */
+export type { ServiceCommandResult };
+
+/**
+ * Injectable side-effect seam for the connector-service module. This is the
+ * generalized `ManagedUnitDeps` re-exported under the connector's historical
+ * name so `expose-cloudflare.ts` + the connector tests are unchanged.
+ */
+export type ConnectorServiceDeps = ManagedUnitDeps;
+
+export const defaultServiceDeps: ConnectorServiceDeps = defaultManagedUnitDeps;
+
+/** Reverse-DNS prefix for the launchd label + plist filename. */
+const LAUNCHD_LABEL_PREFIX = "computer.parachute.cloudflared";
+/** systemd unit name prefix. */
+const SYSTEMD_UNIT_PREFIX = "parachute-cloudflared-";
+/** Provenance comment baked into every rendered connector unit file. */
+const CONNECTOR_HEADER = "Generated by parachute expose public --cloudflare — do not edit by hand.";
+
+/** launchd label for a tunnel (also the plist basename, minus `.plist`). */
+export function launchdLabel(tunnelName: string): string {
+  return `${LAUNCHD_LABEL_PREFIX}.${tunnelName}`;
+}
+
+/** launchd plist path under the user's LaunchAgents dir. */
+export function launchdPlistPath(tunnelName: string, home: string): string {
+  return launchdPlistPathForLabel(launchdLabel(tunnelName), home);
+}
+
+/** systemd unit name (with `.service` suffix). */
+export function systemdUnitName(tunnelName: string): string {
+  return `${SYSTEMD_UNIT_PREFIX}${tunnelName}.service`;
+}
+
+/** systemd unit path — user-level under $HOME, system-level under /etc. */
+export function systemdUnitPath(tunnelName: string, home: string, root: boolean): string {
+  return systemdUnitPathForName(systemdUnitName(tunnelName), home, root);
+}
+
+/**
+ * Build the connector's `ManagedUnit` descriptor. Empty `env` + no `crashLoop`
+ * are what keep the rendered output byte-identical to the pre-extraction code.
+ * `runAsInvokingUserOnSystemUnit: true` reproduces the connector's historical
+ * `User=` pin on the root/system unit.
+ */
+function connectorUnit(opts: {
+  tunnelName: string;
+  cloudflaredPath: string;
+  configPath: string;
+  logPath: string;
+}): ManagedUnit {
+  return {
+    launchdLabel: launchdLabel(opts.tunnelName),
+    systemdUnitName: systemdUnitName(opts.tunnelName),
+    headerComment: CONNECTOR_HEADER,
+    systemdDescription: `Parachute Cloudflare connector (${opts.tunnelName})`,
+    execStart: [opts.cloudflaredPath, "tunnel", "--config", opts.configPath, "run"],
+    env: {},
+    logPath: opts.logPath,
+    runAsInvokingUserOnSystemUnit: true,
+  };
+}
+
+/**
+ * Render the launchd LaunchAgent plist. Thin wrapper over the generalized
+ * renderer with the connector's descriptor — preserved signature so existing
+ * callers/tests are unchanged.
+ */
+export function renderLaunchdPlist(opts: {
+  tunnelName: string;
+  cloudflaredPath: string;
+  configPath: string;
+  logPath: string;
+}): string {
+  return renderManagedLaunchdPlist(connectorUnit(opts));
+}
+
+/**
+ * Render a systemd unit. Thin wrapper over the generalized renderer — preserved
+ * signature (`{ root, userName }` threaded through) so existing callers/tests
+ * are unchanged.
+ */
+export function renderSystemdUnit(opts: {
+  tunnelName: string;
+  cloudflaredPath: string;
+  configPath: string;
+  logPath: string;
+  root: boolean;
+  userName: string;
+}): string {
+  const { root, userName } = opts;
+  return renderManagedSystemdUnit(connectorUnit(opts), { root, userName });
+}
+
+export interface InstallResult {
+  /**
+   * "installed" → an OS service now owns the connector (survives reboot).
+   * "fallback" → the service tool was unavailable / failed; the caller should
+   * fall back to the transient `proc.unref()` spawn (does NOT survive reboot).
+   */
+  outcome: "installed" | "fallback";
+  /** Which init system installed the service (when outcome === "installed"). */
+  kind?: "launchd" | "systemd-user" | "systemd-system" | "unsupported";
+  /** Path of the written service file (when outcome === "installed"). */
+  servicePath?: string;
+  /** Human-readable lines for the CLI to print (warnings, hints). */
+  messages: string[];
+}
+
+export interface ConnectorServiceOpts {
+  tunnelName: string;
+  configPath: string;
+  logPath: string;
+  deps?: ConnectorServiceDeps;
+}
+
+/** Connector-flavored install/remove messages, supplied to the generalized installer. */
+function connectorMessages(): ManagedUnitMessages {
+  const lingerWarning =
+    "Note: could not enable lingering (loginctl enable-linger) — the connector will run while you're logged in but may not start on a cold boot before login. To run on cold boot without an active login, re-run this command as root (installs a system unit that needs no linger).";
+  return {
+    launchctlMissing: "launchctl not found; using a transient connector (won't survive a reboot).",
+    systemctlMissing: "systemctl not found; using a transient connector (won't survive a reboot).",
+    lingerWarning,
+    writeFailedPrefix:
+      "Failed to write service file; using a transient connector (won't survive a reboot)",
+    launchctlLoadFailedPrefix:
+      "launchctl could not load the connector service; using a transient connector (won't survive a reboot)",
+    daemonReloadFailedPrefix:
+      "systemctl daemon-reload failed; using a transient connector (won't survive a reboot)",
+    enableFailedPrefix:
+      "systemctl enable --now failed; using a transient connector (won't survive a reboot)",
+    // The connector always installs with start:true, so the `started` param these
+    // callbacks receive is unused here — the message is always the "starts now" variant.
+    launchdInstalled: (label, _started) =>
+      `Installed launchd LaunchAgent ${label} — the connector now starts on login/boot.`,
+    systemdInstalled: (unitName, root, _started) =>
+      `Installed systemd ${root ? "system" : "user"} unit ${unitName} — the connector now starts on boot.`,
+  };
+}
+
+/**
+ * Install (or refresh) the reboot-persistent connector service for one tunnel
+ * and start it. Idempotent: re-installing overwrites the service file and
+ * re-loads it, so re-`expose` of the same hostname converges on exactly one
+ * managed connector.
+ *
+ * Graceful fallback: if the platform's service tool is missing or any step
+ * fails, returns `{ outcome: "fallback", messages }` WITHOUT throwing — the
+ * caller then spawns the transient connector and warns it won't survive a
+ * reboot. We never hard-fail the expose because the service install didn't take.
+ */
+export function installConnectorService(opts: ConnectorServiceOpts): InstallResult {
+  const deps = opts.deps ?? defaultServiceDeps;
+  const cloudflaredPath = deps.which("cloudflared");
+  if (!cloudflaredPath) {
+    return {
+      outcome: "fallback",
+      messages: ["Could not resolve the cloudflared binary path; skipping boot-service install."],
+    };
+  }
+  if (deps.platform !== "darwin" && deps.platform !== "linux") {
+    return {
+      outcome: "fallback",
+      messages: [
+        `Boot-persistent connector isn't supported on ${deps.platform}; using a transient connector.`,
+      ],
+    };
+  }
+
+  const result: ManagedUnitInstallResult = installManagedUnit({
+    unit: connectorUnit({
+      tunnelName: opts.tunnelName,
+      cloudflaredPath,
+      configPath: opts.configPath,
+      logPath: opts.logPath,
+    }),
+    deps,
+    messages: connectorMessages(),
+    // start: true (default) — the connector's behavior is unchanged.
+  });
+  return result;
+}
+
+export interface RemoveResult {
+  /** True when a service file was found + removed (best-effort tool teardown ran). */
+  removed: boolean;
+  messages: string[];
+}
+
+/**
+ * Stop + remove the reboot-persistent connector service for one tunnel.
+ * Idempotent + best-effort: a missing service file is a no-op; tool failures
+ * never throw (the expose-off path must always succeed at clearing state even
+ * if the OS service tool hiccups). Mirrors `installConnectorService`'s seam.
+ *
+ * Called by `exposeCloudflareOff` (and the legacy-tunnel sweep) so tearing down
+ * a tunnel also tears down its boot service — otherwise the service would
+ * resurrect a dead connector on the next reboot.
+ */
+export function removeConnectorService(opts: {
+  tunnelName: string;
+  deps?: ConnectorServiceDeps;
+}): RemoveResult {
+  const deps = opts.deps ?? defaultServiceDeps;
+  const result: ManagedUnitRemoveResult = removeManagedUnit({
+    launchdLabel: launchdLabel(opts.tunnelName),
+    systemdUnitName: systemdUnitName(opts.tunnelName),
+    deps,
+    removedLaunchdMessage: (label) => `Removed launchd LaunchAgent ${label}.`,
+    removedSystemdMessage: (unitName) => `Removed systemd unit ${unitName}.`,
+  });
+  return result;
+}

package/src/cloudflare/state.ts

@@ -25,6 +25,14 @@ export interface CloudflaredTunnelRecord {
   startedAt: string;
   /** Absolute path to the cloudflared config.yml driving this tunnel. */
   configPath: string;
+  /**
+   * True when a reboot-persistent OS service (launchd/systemd) owns this
+   * connector (0.6.2). Drives the off-path to remove the service (not just
+   * SIGTERM the pid — a still-enabled service would otherwise restart the
+   * connector it just killed). Optional + defaults false so pre-0.6.2 state
+   * files (and the transient-fallback path) validate + read as unmanaged.
+   */
+  serviceManaged?: boolean;
 }
 
 /**
@@ -64,7 +72,7 @@ function validateRecord(raw: unknown, path: string): CloudflaredTunnelRecord {
     throw new CloudflaredStateError(`${path}: tunnel record must be an object`);
   }
   const r = raw as Record<string, unknown>;
-  return {
+  const record: CloudflaredTunnelRecord = {
     pid: requirePositiveInt(r, "pid", path),
     tunnelUuid: requireString(r, "tunnelUuid", path),
     tunnelName: requireString(r, "tunnelName", path),
@@ -72,6 +80,10 @@ function validateRecord(raw: unknown, path: string): CloudflaredTunnelRecord {
     startedAt: requireString(r, "startedAt", path),
     configPath: requireString(r, "configPath", path),
   };
+  // Optional — present from 0.6.2 onward. A non-boolean (or absent) value
+  // reads as unmanaged so legacy state files keep validating.
+  if (r.serviceManaged === true) record.serviceManaged = true;
+  return record;
 }
 
 function validate(raw: unknown, path: string): CloudflaredState {