harnery 0.44.0 → 0.45.0

package/src/commands/tunnel.ts

@@ -1,5 +1,7 @@
 import { type ChildProcess, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { hostname } from "node:os";
 import { resolve } from "node:path";
 import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
@@ -7,11 +9,22 @@ import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveCoordRoot } from "../core/agents/coord-client.ts";
 import { resolveBinName } from "../core/config.ts";
 import {
+  acquireNoClobberLease,
+  createTunnelReadinessVerifier,
+  pidAlive,
+  processStartToken,
+  readServer,
+  type ServerRecord,
+  serversDir,
+  signalIfSameGeneration,
   tryRegisterServer,
   tunnelServerId,
   tunnelServerInput,
   unregisterServer,
+  verifyProcessGeneration,
+  withServerRegistrationCustody,
 } from "../core/servers/index.ts";
+import { writePrivateJsonAtomic } from "../core/storage/atomic-json.ts";
 import {
   processLogDestination,
   runProcessLogWorker,
@@ -25,26 +38,20 @@ import {
   planCurrentAddresses,
 } from "../lib/tunnel/current-address.ts";
 import { ALLOW_PATHS_ENV, normalizeAllowPaths } from "../lib/tunnel/path-scope.ts";
-import {
-  connectProbe,
-  findPidsByCommandLine,
-  listeningPorts,
-  portListening,
-} from "../lib/tunnel/processes.ts";
+import { connectProbe, listeningPorts, portListening } from "../lib/tunnel/processes.ts";
 import {
   clearState,
   DEFAULT_INSTANCE,
   ensureCloudflared,
   gateLogFile,
   isProcessAlive,
-  isTunnelStateLive,
-  listStates,
   providerLogFile,
   readConfig,
-  readState,
   type TailscaleMode,
   type TunnelProvider,
   type TunnelState,
+  tunnelDir,
+  tunnelReadiness,
   writeConfig,
   writeState,
 } from "../lib/tunnel/state.ts";
@@ -335,53 +342,6 @@ function sleep(ms: number): Promise<void> {
   return new Promise((r) => setTimeout(r, ms));
 }
 
-/**
- * Kill every process whose command line matches `pattern` (an extended regular
- * expression), skipping our own PID and any already-killed. Returns the count
- * killed. Used as a fallback so orphaned gate/cloudflared processes get cleaned
- * even when the state file was lost (which otherwise left them squatting on the
- * port).
- */
-function killByPattern(pattern: string, alreadyKilled: Set<number>): number {
-  let killed = 0;
-  for (const pid of findPidsByCommandLine(pattern)) {
-    if (!pid || pid === process.pid || alreadyKilled.has(pid)) continue;
-    try {
-      process.kill(pid);
-      alreadyKilled.add(pid);
-      killed++;
-    } catch {
-      /* race: already gone */
-    }
-  }
-  return killed;
-}
-
-/**
- * Command-line pattern for ONE instance's gate, identified by its port. Matches
- * both launch forms: `bun run .../gate.ts --name N --port P` and a host CLI
- * re-executing itself as `<cli> tunnel gate --name N --port P`. Port boundary is
- * guarded with `( |$)` so port 9001 doesn't match 90011.
- */
-function gatePattern(gatePort: number): string {
-  return `(gate\\.ts|tunnel gate) .*--port ${gatePort}( |$)`;
-}
-
-/**
- * Sweep stray gate + cloudflared processes for ONE instance, identified by its
- * gate port. Both signatures are port-scoped so tearing down one tunnel never
- * touches another:
- *   - gate:        see gatePattern (the port is on the gate's argv)
- *   - cloudflared: `--url http://localhost:<port>` (order-independent, so it
- *     matches regardless of the `--protocol http2` flag we also pass).
- */
-function sweepStrays(gatePort: number, alreadyKilled: Set<number>): number {
-  return (
-    killByPattern(gatePattern(gatePort), alreadyKilled) +
-    killByPattern(`--url http://localhost:${gatePort}( |$)`, alreadyKilled)
-  );
-}
-
 /**
  * Pick a gate port for a new instance. An explicit `--gate-port` is honored
  * (and rejected if it's already taken); otherwise scan upward from 9001 for the
@@ -389,7 +349,7 @@ function sweepStrays(gatePort: number, alreadyKilled: Set<number>): number {
  */
 async function allocateGatePort(preferred: number | undefined): Promise<number> {
   const used = new Set<number>(
-    listStates()
+    listSelectedStates()
       .filter((s) => isProcessAlive(s.gate_pid))
       .map((s) => s.gate_port),
   );
@@ -522,13 +482,14 @@ function runTailscaleShare(
 }
 
 function stopTailscaleShare(state: TunnelState): boolean {
-  if (state.provider !== "tailscale" || !state.tailscale_mode) return true;
-  const cmd = tailscaleCommand(state.tailscale_mode);
+  if (state.provider !== "tailscale") return true;
+  if (!originalTailscaleRoute(state)) return false;
+  const cmd = tailscaleCommand(state.tailscale_mode!);
   const logPath = tunnelLogDestinations(state.name, "tailscale").provider;
   const args = [
     cmd,
-    `--https=${state.tailscale_https_port ?? 443}`,
-    `--set-path=${state.tailscale_path ?? "/"}`,
+    `--https=${state.tailscale_https_port}`,
+    `--set-path=${state.tailscale_path}`,
     "off",
   ];
   const status = runRotatingProcessSync({
@@ -541,9 +502,9 @@ function stopTailscaleShare(state: TunnelState): boolean {
     // surviving serve/funnel mapping could later re-expose whatever next binds
     // that port. Surface it loudly so the operator can clear it by hand.
     emit.text(
-      `\n  ⚠ Failed to remove the Tailscale ${cmd} mapping (path ${state.tailscale_path ?? "/"}).\n` +
+      `\n  ⚠ Failed to remove the Tailscale ${cmd} mapping (path ${state.tailscale_path}).\n` +
         `    It may still be exposing this machine. Clear it with:\n` +
-        `      tailscale ${cmd} --https=${state.tailscale_https_port ?? 443} --set-path=${state.tailscale_path ?? "/"} off\n` +
+        `      tailscale ${cmd} --https=${state.tailscale_https_port} --set-path=${state.tailscale_path} off\n` +
         `    Log: ${logPath}\n\n`,
     );
     return false;
@@ -559,13 +520,48 @@ function contextVhost(): string | null {
 }
 
 function providerIsAlive(state: TunnelState): boolean {
-  if (state.provider === "tailscale") return true;
-  const pid = state.cloudflared_pid ?? state.provider_pid;
+  if (!canonicalProviderFields(state)) return false;
+  if (state.provider === "tailscale") return state.provider_state === "ready";
+  const pid = state.cloudflared_pid;
   return typeof pid === "number" && isProcessAlive(pid);
 }
 
-function tunnelIsAlive(state: TunnelState): boolean {
-  return isTunnelStateLive(state);
+function canonicalProviderFields(state: TunnelState): boolean {
+  return (
+    !Object.hasOwn(state, "provider_pid") &&
+    !Object.hasOwn(state, "provider_start_token") &&
+    (state.provider !== "tailscale" ||
+      (state.cloudflared_pid === undefined && state.cloudflared_start_token === undefined))
+  );
+}
+
+function originalProcessWitnesses(state: TunnelState): boolean {
+  if (
+    !canonicalProviderFields(state) ||
+    !Number.isSafeInteger(state.gate_pid) ||
+    state.gate_pid < 1 ||
+    typeof state.gate_start_token !== "string" ||
+    !state.gate_start_token ||
+    typeof state.registration_id !== "string" ||
+    !state.registration_id
+  )
+    return false;
+  if (state.provider === "tailscale")
+    return (
+      originalTailscaleRoute(state) &&
+      (state.provider_state === "ready" || state.provider_state === "pending")
+    );
+  return (
+    state.provider === "cloudflare" &&
+    Number.isSafeInteger(state.cloudflared_pid) &&
+    state.cloudflared_pid! > 0 &&
+    typeof state.cloudflared_start_token === "string" &&
+    !!state.cloudflared_start_token
+  );
+}
+
+function readinessOf(state: TunnelState) {
+  return tunnelReadiness(state, createTunnelReadinessVerifier({ coordRoot: registryRoot() }));
 }
 
 interface GateSpawnOpts {
@@ -588,8 +584,7 @@ interface GateSpawnOpts {
  * re-reads — that snapshot is precisely why `reload` has to exist.
  */
 function spawnGate(o: GateSpawnOpts, launch: GateLaunch): ChildProcess {
-  // `--name`/`--port` on argv mirror the env vars; they're what makes the gate
-  // process distinguishable per-instance in a command-line search (see sweepStrays).
+  // Keep the instance name and port visible in process diagnostics.
   const gateProc = spawnRotatingProcess({
     path: o.gateLogPath,
     command: launch.command,
@@ -610,7 +605,115 @@ function spawnGate(o: GateSpawnOpts, launch: GateLaunch): ChildProcess {
   return gateProc;
 }
 
+export interface TunnelRoute {
+  path: string;
+  httpsPort: number;
+}
+function originalTailscaleRoute(state: TunnelState): boolean {
+  return (
+    (state.tailscale_mode === "serve" || state.tailscale_mode === "funnel") &&
+    typeof state.tailscale_path === "string" &&
+    state.tailscale_path.startsWith("/") &&
+    Number.isSafeInteger(state.tailscale_https_port) &&
+    state.tailscale_https_port! > 0 &&
+    state.tailscale_https_port! <= 65535
+  );
+}
+function routeOf(state: TunnelState | null): TunnelRoute | null {
+  return state?.provider === "tailscale" && originalTailscaleRoute(state)
+    ? { path: state.tailscale_path!, httpsPort: state.tailscale_https_port! }
+    : null;
+}
+function routeKey(route: TunnelRoute): string {
+  return `${route.httpsPort}:${route.path}`;
+}
+
+/** Serialize the instance and every shared provider route before any external effect. */
+export function withTunnelLifecycleCustody<T>(
+  name: string,
+  requested: TunnelRoute | null,
+  effect: () => PromiseLike<T>,
+): Promise<T>;
+export function withTunnelLifecycleCustody<T>(
+  name: string,
+  requested: TunnelRoute | null,
+  effect: () => T,
+): T;
+export function withTunnelLifecycleCustody<T>(
+  name: string,
+  requested: TunnelRoute | null,
+  effect: () => T | PromiseLike<T>,
+): T | Promise<T> {
+  if (!/^[a-z0-9][a-z0-9-]*$/i.test(name)) throw new Error("invalid tunnel lifecycle name");
+  const leases: Array<ReturnType<typeof acquireNoClobberLease>> = [];
+  const release = () => {
+    for (const lease of leases.splice(0).reverse()) lease.release();
+  };
+  const acquire = (category: string, key: string) => {
+    const scope = `tunnel-${category}-${createHash("sha256").update(key).digest("hex")}`;
+    leases.push(
+      acquireNoClobberLease({
+        path: resolve(
+          tunnelDir(),
+          ".custody",
+          category,
+          createHash("sha256").update(key).digest("hex"),
+        ),
+        scope,
+        authoritySha256: createHash("sha256").update(scope).digest("hex"),
+        staleAfterMs: 1,
+      }),
+    );
+  };
+  try {
+    acquire("instance", name.toLowerCase());
+    const retained = listSelectedStates();
+    const existing = routeOf(retained.find((state) => state.name === name) ?? null);
+    const routes = [
+      ...new Set(
+        [existing, requested].filter((route): route is TunnelRoute => !!route).map(routeKey),
+      ),
+    ].sort();
+    for (const key of routes) acquire("route", key);
+    for (const other of retained) {
+      if (other.name.toLowerCase() === name.toLowerCase()) {
+        if (other.name !== name)
+          throw new Error(
+            `tunnel instance ${name} aliases retained spelling ${other.name}; lifecycle custody is unavailable`,
+          );
+        continue;
+      }
+      const route = routeOf(other);
+      if (route && routes.includes(routeKey(route)))
+        throw new Error(
+          `Tailscale route ${routeKey(route)} is retained by tunnel ${other.name}; provider custody is unavailable`,
+        );
+    }
+    const result = effect();
+    if (
+      result !== null &&
+      (typeof result === "object" || typeof result === "function") &&
+      typeof (result as PromiseLike<T>).then === "function"
+    )
+      return Promise.resolve(result).finally(release);
+    release();
+    return result as T;
+  } catch (error) {
+    release();
+    throw error;
+  }
+}
+
 async function up(opts: UpOpts): Promise<void> {
+  const name = resolveName(opts.name);
+  const requested =
+    resolveProvider(opts.provider) === "tailscale"
+      ? { path: resolveTailscalePath(opts.path, name), httpsPort: resolveHttpsPort(opts.httpsPort) }
+      : null;
+  return withTunnelLifecycleCustody(name, requested, () => upWithCustody(opts));
+}
+
+async function upWithCustody(opts: UpOpts): Promise<void> {
   const launch = currentGateLaunch();
   if (!launch) {
     emit.error({ code: "tunnel_requires_bun", message: requiresBunMessage() });
@@ -630,8 +733,17 @@ async function up(opts: UpOpts): Promise<void> {
     provider === "tailscale" ? resolveHttpsPort(opts.httpsPort) : undefined;
   const allowPaths = resolveAllowPaths(opts.allowPath);
 
-  const existing = readState(name);
-  if (existing && tunnelIsAlive(existing)) {
+  const existing = readSelectedState(name);
+  const readiness = existing ? readinessOf(existing) : null;
+  if (readiness === "unknown") {
+    emit.error({
+      code: "tunnel_custody_unknown",
+      message: `Tunnel [${name}] readiness is unknown; retained its state and refused cleanup or replacement.`,
+    });
+    process.exit(1);
+    return;
+  }
+  if (existing && readiness === "ready") {
     if (existing.provider !== provider) {
       emit.error({
         code: "tunnel_instance_in_use",
@@ -654,16 +766,21 @@ async function up(opts: UpOpts): Promise<void> {
     emit.text(`  Paths:      ${formatPaths(existing.allow_paths)}\n`);
     return;
   }
-  if (existing) downOne(name, new Set());
+  if (existing) {
+    downOneWithCustody(name, new Set());
+    if (readSelectedState(name)) {
+      emit.error({
+        code: "tunnel_custody_unknown",
+        message: `Tunnel [${name}] has a live or unverifiable process; retained its state and refused a replacement.`,
+      });
+      process.exit(1);
+    }
+  }
 
   // Allocate the gate port (after clearing dead state so its old port frees up
   // for reuse). Explicit --gate-port is validated; otherwise auto-scan.
   const gatePort = await allocateGatePort(opts.gatePort ? Number(opts.gatePort) : undefined);
 
-  // Self-heal: clear any orphaned gate/cloudflared on THIS instance's port from
-  // a prior crashed or state-cleared run so the gate port is free before we bind.
-  if (sweepStrays(gatePort, new Set())) await sleep(500);
-
   const cfg = readConfig();
   if (provider === "cloudflare" && cfg.allowed_ips.length === 0) {
     emit.error({
@@ -711,17 +828,13 @@ async function up(opts: UpOpts): Promise<void> {
     launch,
   );
 
+  const gateStartToken = processStartToken(gateProc.pid!);
   await sleep(800);
 
   // A host CLI that re-executes itself takes longer to load than a bare script,
   // so wait for the gate to actually listen before the provider forwards to it.
   if (!isProcessAlive(gateProc.pid!) || !(await waitForPortBound(gatePort, 15_000))) {
-    try {
-      process.kill(gateProc.pid!);
-    } catch {
-      /* already dead */
-    }
-    sweepStrays(gatePort, new Set());
+    signalIfSameGeneration(gateProc.pid!, gateStartToken, "SIGTERM");
     emit.error({
       code: "tunnel_gate_failed",
       message: `Gate failed to start. Check log: ${gateLogPath}`,
@@ -732,6 +845,8 @@ async function up(opts: UpOpts): Promise<void> {
   let url: string;
   let registered = true;
   let cloudflaredPid: number | undefined;
+  let cloudflaredStartToken: string | undefined;
+  let pendingReceipt: ServerRecord | null = null;
 
   if (provider === "cloudflare") {
     // Force HTTP/2 transport. The default QUIC transport wedges at precheck on
@@ -747,20 +862,13 @@ async function up(opts: UpOpts): Promise<void> {
     });
     cfdProc.unref();
     cloudflaredPid = cfdProc.pid!;
+    cloudflaredStartToken = processStartToken(cloudflaredPid) ?? undefined;
 
     const ready = await waitForReady(providerLogPath, 30_000);
     registered = ready.registered;
     if (!ready.url) {
-      try {
-        process.kill(gateProc.pid!);
-      } catch {
-        /* already dead */
-      }
-      try {
-        process.kill(cloudflaredPid);
-      } catch {
-        /* already dead */
-      }
+      signalIfSameGeneration(gateProc.pid!, gateStartToken, "SIGTERM");
+      signalIfSameGeneration(cloudflaredPid, cloudflaredStartToken, "SIGTERM");
       emit.error({
         code: "tunnel_url_timeout",
         message: `Failed to obtain tunnel URL within 30s. Check log: ${providerLogPath}`,
@@ -776,12 +884,38 @@ async function up(opts: UpOpts): Promise<void> {
     // `heal` would then be unable to see or clean up.
     url = tailscaleUrl(tailscalePath!, tailscaleHttpsPort!);
     const gateTarget = `http://127.0.0.1:${gatePort}`;
-    runTailscaleShare(
-      tailscaleMode!,
-      gateTarget,
-      tailscalePath!,
-      tailscaleHttpsPort!,
-      providerLogPath,
+    const pending: TunnelState = {
+      name,
+      provider,
+      url,
+      gate_pid: gateProc.pid!,
+      gate_start_token: gateStartToken ?? undefined,
+      started_at: new Date().toISOString(),
+      target,
+      vhost,
+      gate_port: gatePort,
+      allow_paths: allowPaths,
+      tailscale_mode: tailscaleMode,
+      tailscale_path: tailscalePath,
+      tailscale_https_port: tailscaleHttpsPort,
+      provider_state: "pending",
+    };
+    pendingReceipt = recordTunnelServer(pending);
+    if (!pendingReceipt) {
+      const evidence = recordRefusedTunnelLaunch(pending);
+      signalIfSameGeneration(pending.gate_pid, pending.gate_start_token, "SIGTERM");
+      throw new Error(
+        `Tailscale admission refused before provider effect; retained witnesses at ${evidence}`,
+      );
+    }
+    beginTailscaleRoute(pending, pendingReceipt, () =>
+      runTailscaleShare(
+        tailscaleMode!,
+        gateTarget,
+        tailscalePath!,
+        tailscaleHttpsPort!,
+        providerLogPath,
+      ),
     );
   }
 
@@ -789,7 +923,10 @@ async function up(opts: UpOpts): Promise<void> {
     name,
     provider,
     url,
+    ...(provider === "tailscale" ? { provider_state: "ready" as const } : {}),
     gate_pid: gateProc.pid!,
+    gate_start_token: gateStartToken ?? undefined,
+    cloudflared_start_token: cloudflaredStartToken,
     cloudflared_pid: cloudflaredPid,
     started_at: new Date().toISOString(),
     target,
@@ -800,8 +937,22 @@ async function up(opts: UpOpts): Promise<void> {
     tailscale_path: tailscalePath,
     tailscale_https_port: tailscaleHttpsPort,
   };
-  writeState(state);
-  recordTunnelServer(state);
+  const receipt = provider === "tailscale" ? pendingReceipt : recordTunnelServer(state);
+  if (receipt) state.registration_id = receipt.registration_id;
+  try {
+    if (!receipt) throw new Error("registration refused");
+    publishTunnelState(state, receipt);
+  } catch {
+    const evidence = recordRefusedTunnelLaunch(state);
+    signalIfSameGeneration(state.gate_pid, state.gate_start_token, "SIGTERM");
+    if (state.cloudflared_pid)
+      signalIfSameGeneration(state.cloudflared_pid, state.cloudflared_start_token, "SIGTERM");
+    emit.error({
+      code: "tunnel_registration_refused",
+      message: `Tunnel [${name}] registration custody was refused; saved process witnesses at ${evidence}.`,
+    });
+    process.exit(1);
+  }
 
   const bin = resolveBinName();
   const stopHint =
@@ -836,43 +987,191 @@ function registryRoot(): string {
   return resolveCoordRoot() ?? process.cwd();
 }
 
-function recordTunnelServer(state: TunnelState): void {
-  const coordRoot = registryRoot();
-  tryRegisterServer(tunnelServerInput(state, coordRoot), { coordRoot });
+function unknownTunnelFrame(name: string): Error {
+  return Object.assign(
+    new Error(
+      `Tunnel [${name}] state is unreadable or its custody is unknown; retained the frame.`,
+    ),
+    {
+      code: "tunnel_custody_unknown",
+    },
+  );
+}
+
+function readSelectedState(name: string): TunnelState | null {
+  const path = resolve(
+    tunnelDir(),
+    name === DEFAULT_INSTANCE ? "state.json" : `state-${name}.json`,
+  );
+  let bytes: string;
+  try {
+    bytes = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw unknownTunnelFrame(name);
+  }
+  try {
+    const raw = JSON.parse(bytes) as TunnelState;
+    if (
+      !raw ||
+      typeof raw !== "object" ||
+      Array.isArray(raw) ||
+      raw.name !== name ||
+      (raw.provider !== "cloudflare" && raw.provider !== "tailscale") ||
+      (raw.provider === "tailscale" && !originalTailscaleRoute(raw)) ||
+      typeof raw.url !== "string" ||
+      !raw.url ||
+      typeof raw.target !== "string" ||
+      !raw.target ||
+      typeof raw.vhost !== "string" ||
+      !Number.isSafeInteger(raw.gate_pid) ||
+      raw.gate_pid < 1 ||
+      !Number.isSafeInteger(raw.gate_port) ||
+      raw.gate_port < 1 ||
+      raw.gate_port > 65535 ||
+      !Array.isArray(raw.allow_paths) ||
+      raw.allow_paths.some((path) => typeof path !== "string")
+    )
+      throw unknownTunnelFrame(name);
+    return raw;
+  } catch {
+    throw unknownTunnelFrame(name);
+  }
+}
+
+function listSelectedStates(): TunnelState[] {
+  let files: string[];
+  try {
+    files = readdirSync(tunnelDir());
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw unknownTunnelFrame("inventory");
+  }
+  const states: TunnelState[] = [];
+  for (const file of files) {
+    const name = file === "state.json" ? DEFAULT_INSTANCE : /^state-(.+)\.json$/.exec(file)?.[1];
+    if (!name) continue;
+    const state = readSelectedState(name);
+    if (state) states.push(state);
+  }
+  return states.sort((a, b) =>
+    (typeof b.started_at === "string" ? b.started_at : "").localeCompare(
+      typeof a.started_at === "string" ? a.started_at : "",
+    ),
+  );
 }
 
-/** Tear down a single instance by name. Returns the number of processes killed. */
-function portHeldByOtherLiveInstance(port: number, name: string): boolean {
-  return listStates().some(
-    (s) => s.name !== name && s.gate_port === port && isProcessAlive(s.gate_pid),
+function matchesTunnelReceipt(state: TunnelState, receipt: ServerRecord): boolean {
+  return (
+    originalProcessWitnesses(state) &&
+    tunnelServerId(state.name) === receipt.id &&
+    receipt.host === hostname() &&
+    receipt.kind === "service" &&
+    receipt.type === "tunnel" &&
+    receipt.port === state.gate_port &&
+    receipt.url === state.url &&
+    receipt.registration_id === state.registration_id &&
+    receipt.pid === state.gate_pid &&
+    receipt.start_token === state.gate_start_token
   );
 }
 
+/** Retain a refused launch without overwriting another launch's canonical state. */
+export function recordRefusedTunnelLaunch(state: TunnelState): string {
+  const path = resolve(tunnelDir(), `failed-${state.name}-${randomUUID()}.json`);
+  writePrivateJsonAtomic(path, state);
+  return path;
+}
+
+/** A canonical state frame may be published only by its current registration. */
+export function publishTunnelState(state: TunnelState, receipt: ServerRecord): void {
+  if (!matchesTunnelReceipt(state, receipt))
+    throw new Error("tunnel state registration custody does not match");
+  withServerRegistrationCustody(receipt, { coordRoot: registryRoot() }, () => writeState(state));
+}
+
+/** Retain pending route intent before asking the provider to change external state. */
+export function beginTailscaleRoute<T>(
+  state: TunnelState,
+  receipt: ServerRecord,
+  effect: () => T,
+): T {
+  if (state.provider !== "tailscale" || state.provider_state !== "pending")
+    throw new Error("Tailscale route intent is not pending");
+  publishTunnelState(state, receipt);
+  return withServerRegistrationCustody(receipt, { coordRoot: registryRoot() }, effect);
+}
+
+function recordTunnelServer(state: TunnelState): ServerRecord | null {
+  if (!state.gate_start_token) return null;
+  const coordRoot = registryRoot();
+  const record = tryRegisterServer(tunnelServerInput(state, coordRoot), { coordRoot });
+  if (record) state.registration_id = record.registration_id;
+  return record;
+}
+
+function tunnelRegistration(state: TunnelState): { known: boolean; record: ServerRecord | null } {
+  if (!originalProcessWitnesses(state)) return { known: false, record: null };
+  const coordRoot = registryRoot();
+  const id = tunnelServerId(state.name);
+  let record: ServerRecord | null;
+  try {
+    record = readServer(id, { coordRoot });
+  } catch {
+    return { known: false, record: null };
+  }
+  const present = existsSync(resolve(serversDir(coordRoot), `${id}.json`));
+  if (!present) return { known: false, record: null };
+  return { known: !!record && matchesTunnelReceipt(state, record), record };
+}
+
+/** Unknown saved identities retain state and never authorize a signal. */
 export function downOne(name: string, killed: Set<number>): number {
+  try {
+    return withTunnelLifecycleCustody(name, null, () => downOneWithCustody(name, killed));
+  } catch {
+    return 0;
+  }
+}
+
+function downOneWithCustody(name: string, killed: Set<number>): number {
   const before = killed.size;
-  const state = readState(name);
-  if (state) {
-    if (state.provider === "tailscale") stopTailscaleShare(state);
-    for (const pid of [state.gate_pid, state.cloudflared_pid, state.provider_pid]) {
-      if (typeof pid !== "number") continue;
-      if (isProcessAlive(pid)) {
-        try {
-          process.kill(pid);
-          killed.add(pid);
-        } catch {
-          /* race: already gone */
-        }
+  const state = readSelectedState(name);
+  if (!state) return 0;
+  const registration = tunnelRegistration(state);
+  if (!registration.known) return 0;
+  const targets = [
+    { pid: state.gate_pid, token: state.gate_start_token },
+    { pid: state.cloudflared_pid, token: state.cloudflared_start_token },
+  ].filter(
+    (target): target is { pid: number; token: string | undefined } =>
+      typeof target.pid === "number",
+  );
+  for (const target of targets) {
+    if (pidAlive(target.pid) && verifyProcessGeneration(target.pid, target.token) !== "same")
+      return 0;
+  }
+  if (!registration.record) return 0;
+  let cleared = false;
+  try {
+    withServerRegistrationCustody(registration.record, { coordRoot: registryRoot() }, () => {
+      for (const target of targets) {
+        if (!pidAlive(target.pid) || killed.has(target.pid)) continue;
+        const result = signalIfSameGeneration(target.pid, target.token, "SIGTERM");
+        if (!result.sent) throw new Error("tunnel process custody is unknown");
+        killed.add(target.pid);
       }
-    }
+      // Observation and deletion share custody; an old stopper cannot clear a winner.
+      if (targets.some((target) => pidAlive(target.pid))) return;
+      if (JSON.stringify(readSelectedState(name)) !== JSON.stringify(state)) return;
+      if (state.provider === "tailscale" && !stopTailscaleShare(state)) return;
+      clearState(name);
+      cleared = true;
+    });
+  } catch {
+    return killed.size - before;
   }
-  // Fallback: sweep orphans on this instance's gate port, even when state was
-  // lost; they'd otherwise squat on the port and break the next `up`. Skip it
-  // when another live instance now owns that port: a stale record's port is
-  // reused after a reboot, and sweeping it would kill the live tunnel there.
-  const port = state?.gate_port ?? DEFAULT_GATE_PORT;
-  if (!portHeldByOtherLiveInstance(port, name)) sweepStrays(port, killed);
-  clearState(name);
-  unregisterServer(tunnelServerId(name), { coordRoot: registryRoot() });
+  if (cleared) unregisterServer(registration.record, { coordRoot: registryRoot() });
   return killed.size - before;
 }
 
@@ -880,14 +1179,15 @@ function down(opts: DownOpts): void {
   const killed = new Set<number>();
 
   if (opts.all) {
-    const states = listStates();
+    const states = listSelectedStates();
     if (states.length === 0) {
       emit.text("No tunnels up. Nothing to stop.\n");
       return;
     }
     for (const s of states) downOne(s.name, killed);
+    const retained = states.filter((state) => readSelectedState(state.name)).length;
     emit.text(
-      `Stopped ${states.length} tunnel(s) [${states.map((s) => s.name).join(", ")}], ${killed.size} process(es).\n`,
+      `Requested stop for ${states.length} tunnel(s); ${killed.size} process signal(s), ${retained} state record(s) retained pending verified exit.\n`,
     );
     return;
   }
@@ -895,8 +1195,8 @@ function down(opts: DownOpts): void {
   const name = resolveName(opts.name);
   // Bare `down` targets the default instance. If it's not up but named ones
   // are, don't silently no-op; point the operator at them.
-  if (name === DEFAULT_INSTANCE && !readState(DEFAULT_INSTANCE)) {
-    const others = listStates();
+  if (name === DEFAULT_INSTANCE && !readSelectedState(DEFAULT_INSTANCE)) {
+    const others = listSelectedStates();
     if (others.length > 0) {
       emit.text(
         `No default tunnel running. Other tunnels up: ${others.map((s) => s.name).join(", ")}.\nUse \`${resolveBinName()} tunnel down --name <name>\` or \`${resolveBinName()} tunnel down --all\`.\n`,
@@ -907,9 +1207,9 @@ function down(opts: DownOpts): void {
 
   downOne(name, killed);
   emit.text(
-    killed.size === 0
-      ? `No tunnel processes found for [${name}]. Nothing to stop.\n`
-      : `Stopped ${killed.size} process(es). Tunnel [${name}] down.\n`,
+    readSelectedState(name)
+      ? `Tunnel [${name}] state retained pending verified process exit or custody; ${killed.size} signal(s) sent.\n`
+      : `Tunnel [${name}] has no remaining recorded processes.\n`,
   );
 }
 
@@ -945,10 +1245,29 @@ async function waitForPortBound(port: number, timeoutMs: number): Promise<boolea
  * edge reconnects without noticing.
  */
 export async function reloadOne(state: TunnelState): Promise<{ ok: boolean; message: string }> {
+  try {
+    return await withTunnelLifecycleCustody(state.name, routeOf(state), () =>
+      reloadOneWithCustody(state),
+    );
+  } catch {
+    return {
+      ok: false,
+      message: `[${state.name}] lifecycle or provider route custody is unavailable; retained the tunnel.`,
+    };
+  }
+}
+
+async function reloadOneWithCustody(state: TunnelState): Promise<{ ok: boolean; message: string }> {
   const bin = resolveBinName();
   const name = state.name;
   const gatePort = state.gate_port;
 
+  if (!canonicalProviderFields(state))
+    return {
+      ok: false,
+      message: `[${name}] obsolete or ambiguous provider authority is unknown; retained the tunnel.`,
+    };
+
   if (!providerIsAlive(state)) {
     return {
       ok: false,
@@ -974,28 +1293,54 @@ export async function reloadOne(state: TunnelState): Promise<{ ok: boolean; mess
     };
   }
 
-  // Kill ONLY the gate. sweepStrays() is deliberately avoided here: it also
-  // matches `--url http://localhost:<port>`, which is the provider process we
-  // are going out of our way to keep alive.
-  const killed = new Set<number>();
-  if (isProcessAlive(state.gate_pid)) {
-    try {
-      process.kill(state.gate_pid);
-      killed.add(state.gate_pid);
-    } catch {
-      /* race: already gone */
+  const registration = tunnelRegistration(state);
+  if (!registration.known || !registration.record)
+    return { ok: false, message: `[${name}] registration custody changed; retained the tunnel.` };
+  const stopGate = async (): Promise<{ ok: boolean; message: string }> => {
+    if (
+      state.provider === "cloudflare" &&
+      state.cloudflared_pid &&
+      verifyProcessGeneration(state.cloudflared_pid, state.cloudflared_start_token) !== "same"
+    )
+      return {
+        ok: false,
+        message: `[${name}] provider generation is unknown or changed; retained the tunnel.`,
+      };
+    if (pidAlive(state.gate_pid)) {
+      if (!registration.record)
+        return {
+          ok: false,
+          message: `[${name}] registration custody is unavailable; retained the tunnel.`,
+        };
+      const result = signalIfSameGeneration(state.gate_pid, state.gate_start_token, "SIGTERM");
+      if (!result.sent)
+        return {
+          ok: false,
+          message: `[${name}] gate generation is unknown or changed; retained the tunnel.`,
+        };
     }
-  }
-  killByPattern(gatePattern(gatePort), killed);
-
-  if (!(await waitForPortFree(gatePort, 5_000))) {
+    if (!(await waitForPortFree(gatePort, 5_000)))
+      return {
+        ok: false,
+        message: `[${name}] port ${gatePort} never released; retained the tunnel state.`,
+      };
+    return { ok: true, message: "gate released" };
+  };
+  let released: { ok: boolean; message: string };
+  try {
+    released = await withServerRegistrationCustody(
+      registration.record,
+      { coordRoot: registryRoot() },
+      stopGate,
+    );
+  } catch {
     return {
       ok: false,
-      message:
-        `[${name}] port ${gatePort} never released, so the old gate looks wedged. ` +
-        `Tunnel is down; check \`${bin} tunnel status\`.`,
+      message: `[${name}] registration custody is unavailable; retained the tunnel.`,
     };
   }
+  if (!released.ok) return released;
+  if (registration.record) unregisterServer(registration.record, { coordRoot: registryRoot() });
 
   const cfg = readConfig();
   const gateProc = spawnGate(
@@ -1012,6 +1357,7 @@ export async function reloadOne(state: TunnelState): Promise<{ ok: boolean; mess
     launch,
   );
 
+  const gateStartToken = processStartToken(gateProc.pid!);
   await sleep(800);
   const pid = gateProc.pid;
   if (
@@ -1027,8 +1373,24 @@ export async function reloadOne(state: TunnelState): Promise<{ ok: boolean; mess
     };
   }
 
-  writeState({ ...state, gate_pid: pid });
-  recordTunnelServer({ ...state, gate_pid: pid });
+  const next = {
+    ...state,
+    gate_pid: pid,
+    gate_start_token: gateStartToken ?? undefined,
+    registration_id: undefined,
+  };
+  const nextReceipt = recordTunnelServer(next);
+  try {
+    if (!nextReceipt) throw new Error("registration refused");
+    publishTunnelState(next, nextReceipt);
+  } catch {
+    const evidence = recordRefusedTunnelLaunch(next);
+    signalIfSameGeneration(pid, gateStartToken, "SIGTERM");
+    return {
+      ok: false,
+      message: `[${name}] new gate registration custody was refused; retained witnesses at ${evidence}.`,
+    };
+  }
   const allowNote =
     state.provider === "cloudflare" ? ` Allowlist: ${cfg.allowed_ips.length} IP(s).` : "";
   return { ok: true, message: `[${name}] gate reloaded, URL unchanged: ${state.url}.${allowNote}` };
@@ -1038,7 +1400,7 @@ async function reload(opts: ReloadOpts): Promise<void> {
   const bin = resolveBinName();
 
   if (opts.all) {
-    const all = listStates();
+    const all = listSelectedStates();
     // Only live tunnels are reloadable, and a box commonly accumulates stale
     // state files from long-dead runs. Reporting those as failures would make
     // the common post-`allow add` path exit non-zero for no real reason.
@@ -1067,7 +1429,7 @@ async function reload(opts: ReloadOpts): Promise<void> {
   }
 
   const name = resolveName(opts.name);
-  const state = readState(name);
+  const state = readSelectedState(name);
   if (!state) {
     emit.error({
       code: "tunnel_not_found",
@@ -1081,8 +1443,9 @@ async function reload(opts: ReloadOpts): Promise<void> {
   if (!r.ok) process.exit(1);
 }
 
-function instanceState(state: TunnelState): "up" | "stale" {
-  return tunnelIsAlive(state) ? "up" : "stale";
+function instanceState(state: TunnelState): "up" | "stale" | "unknown" {
+  const readiness = readinessOf(state);
+  return readiness === "ready" ? "up" : readiness === "dead" ? "stale" : "unknown";
 }
 
 function fmtUptime(startedAt: string): string {
@@ -1097,9 +1460,9 @@ function fmtUptime(startedAt: string): string {
 function statusDetail(state: TunnelState): void {
   const gateAlive = isProcessAlive(state.gate_pid);
   const providerAlive = providerIsAlive(state);
-  const providerPid = state.cloudflared_pid ?? state.provider_pid;
+  const providerPid = state.cloudflared_pid;
   const cfg = readConfig();
-  emit.text(`${gateAlive && providerAlive ? "up" : "stale"} [${state.name}]\n`);
+  emit.text(`${instanceState(state)} [${state.name}]\n`);
   emit.text(
     `  Provider:    ${state.provider}${state.tailscale_mode ? ` (${state.tailscale_mode})` : ""}\n`,
   );
@@ -1122,7 +1485,7 @@ function statusDetail(state: TunnelState): void {
 function status(opts: StatusOpts): void {
   // Named → detailed single block.
   if (opts.name) {
-    const state = readState(resolveName(opts.name));
+    const state = readSelectedState(resolveName(opts.name));
     if (!state) {
       emit.text(`down [${resolveName(opts.name)}]\n`);
       return;
@@ -1132,7 +1495,7 @@ function status(opts: StatusOpts): void {
   }
 
   // No name → table of every instance.
-  const states = listStates();
+  const states = listSelectedStates();
   if (states.length === 0) {
     emit.text("down\n");
     return;
@@ -1175,7 +1538,7 @@ function status(opts: StatusOpts): void {
 
 function logs(opts: LogsOpts): void {
   const name = resolveName(opts.name);
-  const state = readState(name);
+  const state = readSelectedState(name);
   const provider = state?.provider ?? "cloudflare";
   const destinations = tunnelLogDestinations(name, provider);
   const path = opts.provider ? destinations.provider : destinations.gate;
@@ -1212,7 +1575,9 @@ const sameEntryIn = (list: readonly string[], entry: string) =>
  * restarts were owed.
  */
 function allowChangedHint(): void {
-  const live = listStates().filter((s) => s.provider === "cloudflare" && providerIsAlive(s));
+  const live = listSelectedStates().filter(
+    (s) => s.provider === "cloudflare" && providerIsAlive(s),
+  );
   if (live.length === 0) return;
   emit.text(
     `Each gate reads the allowlist once at start, so this applies on reload ` +
@@ -1354,7 +1719,9 @@ export async function refreshCurrentAddress(
   }
   if (!plan.changed || !options.reload) return result;
 
-  const live = listStates().filter((s) => s.provider === "cloudflare" && providerIsAlive(s));
+  const live = listSelectedStates().filter(
+    (s) => s.provider === "cloudflare" && providerIsAlive(s),
+  );
   for (const s of live) {
     const r = await reloadOne(s);
     emit.text(`${r.ok ? "ok  " : "FAIL"} ${r.message}\n`);