harnery 0.43.0 → 0.45.0

package/dist/commands/tunnel.js

@@ -1,15 +1,18 @@
 import { 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 { resolveCoordRoot } from "../core/agents/coord-client.js";
 import { resolveBinName } from "../core/config.js";
-import { tryRegisterServer, tunnelServerId, tunnelServerInput, unregisterServer, } from "../core/servers/index.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 { 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, 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";
+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";
 /**
  * `tunnel`: provider-backed tunnel in front of a local upstream.
  *
@@ -218,57 +221,13 @@ 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(listStates()
+    const used = new Set(listSelectedStates()
         .filter((s) => isProcessAlive(s.gate_pid))
         .map((s) => s.gate_port));
     // No discovery tool (null) is not "every port free": probe candidates by connecting.
@@ -383,14 +342,16 @@ function runTailscaleShare(mode, targetUrl, path, httpsPort, logPath) {
     }
 }
 function stopTailscaleShare(state) {
-    if (state.provider !== "tailscale" || !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({
@@ -402,9 +363,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 ?? 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;
     }
@@ -417,13 +378,39 @@ function contextVhost() {
     return resolved ?? null;
 }
 function providerIsAlive(state) {
+    if (!canonicalProviderFields(state))
+        return false;
     if (state.provider === "tailscale")
-        return true;
-    const pid = state.cloudflared_pid ?? state.provider_pid;
+        return state.provider_state === "ready";
+    const pid = state.cloudflared_pid;
     return typeof pid === "number" && isProcessAlive(pid);
 }
-function tunnelIsAlive(state) {
-    return isTunnelStateLive(state);
+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() }));
 }
 /**
  * Spawn the detached gate worker.
@@ -434,8 +421,7 @@ function tunnelIsAlive(state) {
  * re-reads — that snapshot is precisely why `reload` has to exist.
  */
 function spawnGate(o, launch) {
-    // `--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,
@@ -454,7 +440,79 @@ 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() });
@@ -470,8 +528,17 @@ async function up(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 = 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",
@@ -493,15 +560,19 @@ async function up(opts) {
         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({
@@ -543,17 +614,12 @@ async function up(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))) {
-        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}`,
@@ -563,6 +629,8 @@ async function up(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
@@ -577,21 +645,12 @@ async function up(opts) {
         });
         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}`,
@@ -608,13 +667,38 @@ async function up(opts) {
         // `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 = {
+            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));
     }
     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,
@@ -625,8 +709,25 @@ async function up(opts) {
         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 = name === DEFAULT_INSTANCE ? `${bin} tunnel down` : `${bin} tunnel down --name ${name}`;
     emit.text(`\n  Instance: ${name}\n`);
@@ -654,72 +755,211 @@ async function up(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();
-    tryRegisterServer(tunnelServerInput(state, coordRoot), { coordRoot });
+    const record = tryRegisterServer(tunnelServerInput(state, coordRoot), { coordRoot });
+    if (record)
+        state.registration_id = record.registration_id;
+    return 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));
+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 };
 }
+/** 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 = 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) => 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;
 }
 function down(opts) {
     const killed = new Set();
     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);
-        emit.text(`Stopped ${states.length} tunnel(s) [${states.map((s) => s.name).join(", ")}], ${killed.size} process(es).\n`);
+        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`);
         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 && !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`);
             return;
         }
     }
     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`);
+    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`);
 }
 /** Poll until `port` has no LISTEN socket (or the deadline passes). */
 async function waitForPortFree(port, timeoutMs) {
@@ -753,9 +993,25 @@ 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,
@@ -778,27 +1034,51 @@ export async function reloadOne(state) {
                 `\`${bin} tunnel up --name ${name} --allow-path <prefix>\`.`,
         };
     }
-    // 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 */
+    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.`,
+                };
         }
+        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);
     }
-    killByPattern(gatePattern(gatePort), killed);
-    if (!(await waitForPortFree(gatePort, 5_000))) {
+    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({
         name,
@@ -810,6 +1090,7 @@ export async function reloadOne(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" ||
@@ -821,15 +1102,33 @@ export async function reloadOne(state) {
                 `Tunnel is down; check \`${bin} tunnel logs --name ${name}\`.`,
         };
     }
-    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}` };
 }
 async function reload(opts) {
     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.
@@ -855,7 +1154,7 @@ async function reload(opts) {
         return;
     }
     const name = resolveName(opts.name);
-    const state = readState(name);
+    const state = readSelectedState(name);
     if (!state) {
         emit.error({
             code: "tunnel_not_found",
@@ -870,7 +1169,8 @@ async function reload(opts) {
         process.exit(1);
 }
 function instanceState(state) {
-    return tunnelIsAlive(state) ? "up" : "stale";
+    const readiness = readinessOf(state);
+    return readiness === "ready" ? "up" : readiness === "dead" ? "stale" : "unknown";
 }
 function fmtUptime(startedAt) {
     const secs = Math.floor((Date.now() - new Date(startedAt).getTime()) / 1000);
@@ -886,9 +1186,9 @@ function fmtUptime(startedAt) {
 function statusDetail(state) {
     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`);
     emit.text(`  URL:         ${state.url}\n`);
     emit.text(`  Forwarding:  ${state.target} (Host: ${state.vhost})\n`);
@@ -909,7 +1209,7 @@ function statusDetail(state) {
 function status(opts) {
     // 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;
@@ -918,7 +1218,7 @@ function status(opts) {
         return;
     }
     // No name → table of every instance.
-    const states = listStates();
+    const states = listSelectedStates();
     if (states.length === 0) {
         emit.text("down\n");
         return;
@@ -955,7 +1255,7 @@ function status(opts) {
 }
 function logs(opts) {
     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;
@@ -989,7 +1289,7 @@ const sameEntryIn = (list, entry) => list.some((e) => canonicalEntry(e) === cano
  * restarts were owed.
  */
 function allowChangedHint() {
-    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 ` +
@@ -1096,7 +1396,7 @@ export async function refreshCurrentAddress(options) {
     }
     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`);