harnery 0.45.0 → 0.45.2

package/dist/commands/tunnel.js

@@ -1,18 +1,15 @@
 import { spawnSync } from "node:child_process";
-import { createHash, randomUUID } from "node:crypto";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { hostname } from "node:os";
+import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { resolveCoordRoot } from "../core/agents/coord-client.js";
 import { resolveBinName } from "../core/config.js";
-import { acquireNoClobberLease, createTunnelReadinessVerifier, pidAlive, processStartToken, readServer, serversDir, signalIfSameGeneration, tryRegisterServer, tunnelServerId, tunnelServerInput, unregisterServer, verifyProcessGeneration, withServerRegistrationCustody, } from "../core/servers/index.js";
-import { writePrivateJsonAtomic } from "../core/storage/atomic-json.js";
+import { tryRegisterServer, tunnelServerId, tunnelServerInput, unregisterServer, } from "../core/servers/index.js";
 import { processLogDestination, runProcessLogWorker, runRotatingProcessSync, spawnRotatingProcess, } from "../core/storage/process-log.js";
 import { normalizeAllowEntry } from "../lib/tunnel/allowlist.js";
 import { detectPublicAddresses, planCurrentAddresses, } from "../lib/tunnel/current-address.js";
 import { ALLOW_PATHS_ENV, normalizeAllowPaths } from "../lib/tunnel/path-scope.js";
-import { connectProbe, listeningPorts, portListening } from "../lib/tunnel/processes.js";
-import { clearState, DEFAULT_INSTANCE, ensureCloudflared, gateLogFile, isProcessAlive, providerLogFile, readConfig, tunnelDir, tunnelReadiness, writeConfig, writeState, } from "../lib/tunnel/state.js";
+import { connectProbe, findPidsByCommandLine, listeningPorts, portListening, } from "../lib/tunnel/processes.js";
+import { clearState, DEFAULT_INSTANCE, ensureCloudflared, gateLogFile, isProcessAlive, isTunnelStateLive, listStates, providerLogFile, readConfig, readState, writeConfig, writeState, } from "../lib/tunnel/state.js";
 /**
  * `tunnel`: provider-backed tunnel in front of a local upstream.
  *
@@ -221,13 +218,57 @@ function tailscaleAvailable() {
 function sleep(ms) {
     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, alreadyKilled) {
+    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) {
+    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, alreadyKilled) {
+    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
  * first port that's neither held by a live instance nor currently listening.
  */
 async function allocateGatePort(preferred) {
-    const used = new Set(listSelectedStates()
+    const used = new Set(listStates()
         .filter((s) => isProcessAlive(s.gate_pid))
         .map((s) => s.gate_port));
     // No discovery tool (null) is not "every port free": probe candidates by connecting.
@@ -342,16 +383,14 @@ function runTailscaleShare(mode, targetUrl, path, httpsPort, logPath) {
     }
 }
 function stopTailscaleShare(state) {
-    if (state.provider !== "tailscale")
+    if (state.provider !== "tailscale" || !state.tailscale_mode)
         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}`,
-        `--set-path=${state.tailscale_path}`,
+        `--https=${state.tailscale_https_port ?? 443}`,
+        `--set-path=${state.tailscale_path ?? "/"}`,
         "off",
     ];
     const status = runRotatingProcessSync({
@@ -363,9 +402,9 @@ function stopTailscaleShare(state) {
         // The gate is torn down and its port is freed for reuse regardless, so a
         // 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` +
+        emit.text(`\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} --set-path=${state.tailscale_path} off\n` +
+            `      tailscale ${cmd} --https=${state.tailscale_https_port ?? 443} --set-path=${state.tailscale_path ?? "/"} off\n` +
             `    Log: ${logPath}\n\n`);
         return false;
     }
@@ -378,39 +417,13 @@ function contextVhost() {
     return resolved ?? null;
 }
 function providerIsAlive(state) {
-    if (!canonicalProviderFields(state))
-        return false;
     if (state.provider === "tailscale")
-        return state.provider_state === "ready";
-    const pid = state.cloudflared_pid;
+        return true;
+    const pid = state.cloudflared_pid ?? state.provider_pid;
     return typeof pid === "number" && isProcessAlive(pid);
 }
-function canonicalProviderFields(state) {
-    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) {
-    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) {
-    return tunnelReadiness(state, createTunnelReadinessVerifier({ coordRoot: registryRoot() }));
+function tunnelIsAlive(state) {
+    return isTunnelStateLive(state);
 }
 /**
  * Spawn the detached gate worker.
@@ -421,7 +434,8 @@ function readinessOf(state) {
  * re-reads — that snapshot is precisely why `reload` has to exist.
  */
 function spawnGate(o, launch) {
-    // Keep the instance name and port visible in process diagnostics.
+    // `--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).
     const gateProc = spawnRotatingProcess({
         path: o.gateLogPath,
         command: launch.command,
@@ -440,79 +454,7 @@ function spawnGate(o, launch) {
     gateProc.unref();
     return gateProc;
 }
-function originalTailscaleRoute(state) {
-    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) {
-    return state?.provider === "tailscale" && originalTailscaleRoute(state)
-        ? { path: state.tailscale_path, httpsPort: state.tailscale_https_port }
-        : null;
-}
-function routeKey(route) {
-    return `${route.httpsPort}:${route.path}`;
-}
-export function withTunnelLifecycleCustody(name, requested, effect) {
-    if (!/^[a-z0-9][a-z0-9-]*$/i.test(name))
-        throw new Error("invalid tunnel lifecycle name");
-    const leases = [];
-    const release = () => {
-        for (const lease of leases.splice(0).reverse())
-            lease.release();
-    };
-    const acquire = (category, key) => {
-        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).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.then === "function")
-            return Promise.resolve(result).finally(release);
-        release();
-        return result;
-    }
-    catch (error) {
-        release();
-        throw error;
-    }
-}
 async function up(opts) {
-    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) {
     const launch = currentGateLaunch();
     if (!launch) {
         emit.error({ code: "tunnel_requires_bun", message: requiresBunMessage() });
@@ -528,17 +470,8 @@ async function upWithCustody(opts) {
     const tailscalePath = provider === "tailscale" ? resolveTailscalePath(opts.path, name) : undefined;
     const tailscaleHttpsPort = provider === "tailscale" ? resolveHttpsPort(opts.httpsPort) : undefined;
     const allowPaths = resolveAllowPaths(opts.allowPath);
-    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") {
+    const existing = readState(name);
+    if (existing && tunnelIsAlive(existing)) {
         if (existing.provider !== provider) {
             emit.error({
                 code: "tunnel_instance_in_use",
@@ -560,19 +493,15 @@ async function upWithCustody(opts) {
         emit.text(`  Paths:      ${formatPaths(existing.allow_paths)}\n`);
         return;
     }
-    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);
-        }
-    }
+    if (existing)
+        downOne(name, new Set());
     // 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({
@@ -614,12 +543,17 @@ async function upWithCustody(opts) {
         allowPaths,
         gateLogPath,
     }, 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))) {
-        signalIfSameGeneration(gateProc.pid, gateStartToken, "SIGTERM");
+        try {
+            process.kill(gateProc.pid);
+        }
+        catch {
+            /* already dead */
+        }
+        sweepStrays(gatePort, new Set());
         emit.error({
             code: "tunnel_gate_failed",
             message: `Gate failed to start. Check log: ${gateLogPath}`,
@@ -629,8 +563,6 @@ async function upWithCustody(opts) {
     let url;
     let registered = true;
     let cloudflaredPid;
-    let cloudflaredStartToken;
-    let pendingReceipt = null;
     if (provider === "cloudflare") {
         // Force HTTP/2 transport. The default QUIC transport wedges at precheck on
         // constrained hosts (e.g. WSL, where UDP receive buffers can't grow and ICMP
@@ -645,12 +577,21 @@ async function upWithCustody(opts) {
         });
         cfdProc.unref();
         cloudflaredPid = cfdProc.pid;
-        cloudflaredStartToken = processStartToken(cloudflaredPid) ?? undefined;
         const ready = await waitForReady(providerLogPath, 30_000);
         registered = ready.registered;
         if (!ready.url) {
-            signalIfSameGeneration(gateProc.pid, gateStartToken, "SIGTERM");
-            signalIfSameGeneration(cloudflaredPid, cloudflaredStartToken, "SIGTERM");
+            try {
+                process.kill(gateProc.pid);
+            }
+            catch {
+                /* already dead */
+            }
+            try {
+                process.kill(cloudflaredPid);
+            }
+            catch {
+                /* already dead */
+            }
             emit.error({
                 code: "tunnel_url_timeout",
                 message: `Failed to obtain tunnel URL within 30s. Check log: ${providerLogPath}`,
@@ -667,38 +608,13 @@ async function upWithCustody(opts) {
         // `heal` would then be unable to see or clean up.
         url = tailscaleUrl(tailscalePath, tailscaleHttpsPort);
         const gateTarget = `http://127.0.0.1:${gatePort}`;
-        const pending = {
-            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));
+        runTailscaleShare(tailscaleMode, gateTarget, tailscalePath, tailscaleHttpsPort, providerLogPath);
     }
     const state = {
         name,
         provider,
         url,
-        ...(provider === "tailscale" ? { provider_state: "ready" } : {}),
         gate_pid: gateProc.pid,
-        gate_start_token: gateStartToken ?? undefined,
-        cloudflared_start_token: cloudflaredStartToken,
         cloudflared_pid: cloudflaredPid,
         started_at: new Date().toISOString(),
         target,
@@ -709,25 +625,8 @@ async function upWithCustody(opts) {
         tailscale_path: tailscalePath,
         tailscale_https_port: tailscaleHttpsPort,
     };
-    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);
-    }
+    writeState(state);
+    recordTunnelServer(state);
     const bin = resolveBinName();
     const stopHint = name === DEFAULT_INSTANCE ? `${bin} tunnel down` : `${bin} tunnel down --name ${name}`;
     emit.text(`\n  Instance: ${name}\n`);
@@ -755,211 +654,72 @@ async function upWithCustody(opts) {
 function registryRoot() {
     return resolveCoordRoot() ?? process.cwd();
 }
-function unknownTunnelFrame(name) {
-    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) {
-    const path = resolve(tunnelDir(), name === DEFAULT_INSTANCE ? "state.json" : `state-${name}.json`);
-    let bytes;
-    try {
-        bytes = readFileSync(path, "utf8");
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return null;
-        throw unknownTunnelFrame(name);
-    }
-    try {
-        const raw = JSON.parse(bytes);
-        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() {
-    let files;
-    try {
-        files = readdirSync(tunnelDir());
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        throw unknownTunnelFrame("inventory");
-    }
-    const states = [];
-    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 : ""));
-}
-function matchesTunnelReceipt(state, receipt) {
-    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) {
-    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, receipt) {
-    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(state, receipt, effect) {
-    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) {
-    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;
+    tryRegisterServer(tunnelServerInput(state, coordRoot), { coordRoot });
 }
-function tunnelRegistration(state) {
-    if (!originalProcessWitnesses(state))
-        return { known: false, record: null };
-    const coordRoot = registryRoot();
-    const id = tunnelServerId(state.name);
-    let record;
-    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 };
+/** Tear down a single instance by name. Returns the number of processes killed. */
+function portHeldByOtherLiveInstance(port, name) {
+    return listStates().some((s) => s.name !== name && s.gate_port === port && isProcessAlive(s.gate_pid));
 }
-/** Unknown saved identities retain state and never authorize a signal. */
 export function downOne(name, killed) {
-    try {
-        return withTunnelLifecycleCustody(name, null, () => downOneWithCustody(name, killed));
-    }
-    catch {
-        return 0;
-    }
-}
-function downOneWithCustody(name, killed) {
     const before = killed.size;
-    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) => 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);
+    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 */
+                }
             }
-            // 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;
+        }
     }
-    if (cleared)
-        unregisterServer(registration.record, { coordRoot: registryRoot() });
+    // 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() });
     return killed.size - before;
 }
 function down(opts) {
     const killed = new Set();
     if (opts.all) {
-        const states = listSelectedStates();
+        const states = listStates();
         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(`Requested stop for ${states.length} tunnel(s); ${killed.size} process signal(s), ${retained} state record(s) retained pending verified exit.\n`);
+        emit.text(`Stopped ${states.length} tunnel(s) [${states.map((s) => s.name).join(", ")}], ${killed.size} process(es).\n`);
         return;
     }
     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 && !readSelectedState(DEFAULT_INSTANCE)) {
-        const others = listSelectedStates();
+    if (name === DEFAULT_INSTANCE && !readState(DEFAULT_INSTANCE)) {
+        const others = listStates();
         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`);
             return;
         }
     }
     downOne(name, killed);
-    emit.text(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`);
+    emit.text(killed.size === 0
+        ? `No tunnel processes found for [${name}]. Nothing to stop.\n`
+        : `Stopped ${killed.size} process(es). Tunnel [${name}] down.\n`);
 }
 /** Poll until `port` has no LISTEN socket (or the deadline passes). */
 async function waitForPortFree(port, timeoutMs) {
@@ -993,25 +753,9 @@ async function waitForPortBound(port, timeoutMs) {
  * edge reconnects without noticing.
  */
 export async function reloadOne(state) {
-    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) {
     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,
@@ -1034,51 +778,27 @@ async function reloadOneWithCustody(state) {
                 `\`${bin} tunnel up --name ${name} --allow-path <prefix>\`.`,
         };
     }
-    const registration = tunnelRegistration(state);
-    if (!registration.known || !registration.record)
-        return { ok: false, message: `[${name}] registration custody changed; retained the tunnel.` };
-    const stopGate = async () => {
-        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.`,
-                };
+    // 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();
+    if (isProcessAlive(state.gate_pid)) {
+        try {
+            process.kill(state.gate_pid);
+            killed.add(state.gate_pid);
+        }
+        catch {
+            /* race: already gone */
         }
-        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;
-    try {
-        released = await withServerRegistrationCustody(registration.record, { coordRoot: registryRoot() }, stopGate);
     }
-    catch {
+    killByPattern(gatePattern(gatePort), killed);
+    if (!(await waitForPortFree(gatePort, 5_000))) {
         return {
             ok: false,
-            message: `[${name}] registration custody is unavailable; retained the tunnel.`,
+            message: `[${name}] port ${gatePort} never released, so the old gate looks wedged. ` +
+                `Tunnel is down; check \`${bin} tunnel status\`.`,
         };
     }
-    if (!released.ok)
-        return released;
-    if (registration.record)
-        unregisterServer(registration.record, { coordRoot: registryRoot() });
     const cfg = readConfig();
     const gateProc = spawnGate({
         name,
@@ -1090,7 +810,6 @@ async function reloadOneWithCustody(state) {
         allowPaths: state.allow_paths,
         gateLogPath: tunnelLogDestinations(name, state.provider).gate,
     }, launch);
-    const gateStartToken = processStartToken(gateProc.pid);
     await sleep(800);
     const pid = gateProc.pid;
     if (typeof pid !== "number" ||
@@ -1102,33 +821,15 @@ async function reloadOneWithCustody(state) {
                 `Tunnel is down; check \`${bin} tunnel logs --name ${name}\`.`,
         };
     }
-    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}.`,
-        };
-    }
+    writeState({ ...state, gate_pid: pid });
+    recordTunnelServer({ ...state, gate_pid: pid });
     const allowNote = state.provider === "cloudflare" ? ` Allowlist: ${cfg.allowed_ips.length} IP(s).` : "";
     return { ok: true, message: `[${name}] gate reloaded, URL unchanged: ${state.url}.${allowNote}` };
 }
 async function reload(opts) {
     const bin = resolveBinName();
     if (opts.all) {
-        const all = listSelectedStates();
+        const all = listStates();
         // 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.
@@ -1154,7 +855,7 @@ async function reload(opts) {
         return;
     }
     const name = resolveName(opts.name);
-    const state = readSelectedState(name);
+    const state = readState(name);
     if (!state) {
         emit.error({
             code: "tunnel_not_found",
@@ -1169,8 +870,7 @@ async function reload(opts) {
         process.exit(1);
 }
 function instanceState(state) {
-    const readiness = readinessOf(state);
-    return readiness === "ready" ? "up" : readiness === "dead" ? "stale" : "unknown";
+    return tunnelIsAlive(state) ? "up" : "stale";
 }
 function fmtUptime(startedAt) {
     const secs = Math.floor((Date.now() - new Date(startedAt).getTime()) / 1000);
@@ -1186,9 +886,9 @@ function fmtUptime(startedAt) {
 function statusDetail(state) {
     const gateAlive = isProcessAlive(state.gate_pid);
     const providerAlive = providerIsAlive(state);
-    const providerPid = state.cloudflared_pid;
+    const providerPid = state.cloudflared_pid ?? state.provider_pid;
     const cfg = readConfig();
-    emit.text(`${instanceState(state)} [${state.name}]\n`);
+    emit.text(`${gateAlive && providerAlive ? "up" : "stale"} [${state.name}]\n`);
     emit.text(`  Provider:    ${state.provider}${state.tailscale_mode ? ` (${state.tailscale_mode})` : ""}\n`);
     emit.text(`  URL:         ${state.url}\n`);
     emit.text(`  Forwarding:  ${state.target} (Host: ${state.vhost})\n`);
@@ -1209,7 +909,7 @@ function statusDetail(state) {
 function status(opts) {
     // Named → detailed single block.
     if (opts.name) {
-        const state = readSelectedState(resolveName(opts.name));
+        const state = readState(resolveName(opts.name));
         if (!state) {
             emit.text(`down [${resolveName(opts.name)}]\n`);
             return;
@@ -1218,7 +918,7 @@ function status(opts) {
         return;
     }
     // No name → table of every instance.
-    const states = listSelectedStates();
+    const states = listStates();
     if (states.length === 0) {
         emit.text("down\n");
         return;
@@ -1255,7 +955,7 @@ function status(opts) {
 }
 function logs(opts) {
     const name = resolveName(opts.name);
-    const state = readSelectedState(name);
+    const state = readState(name);
     const provider = state?.provider ?? "cloudflare";
     const destinations = tunnelLogDestinations(name, provider);
     const path = opts.provider ? destinations.provider : destinations.gate;
@@ -1289,7 +989,7 @@ const sameEntryIn = (list, entry) => list.some((e) => canonicalEntry(e) === cano
  * restarts were owed.
  */
 function allowChangedHint() {
-    const live = listSelectedStates().filter((s) => s.provider === "cloudflare" && providerIsAlive(s));
+    const live = listStates().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 ` +
@@ -1396,7 +1096,7 @@ export async function refreshCurrentAddress(options) {
     }
     if (!plan.changed || !options.reload)
         return result;
-    const live = listSelectedStates().filter((s) => s.provider === "cloudflare" && providerIsAlive(s));
+    const live = listStates().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`);