@mesh-tech/mesh-cli 0.20.2 → 0.20.4

package/dist/src/utils/tailscale.js

@@ -1,12 +1,3 @@
-/**
- * Userspace-Tailscale daemon management + tunnel-session state for
- * `mesh vpn tunnel` (MESH-2040 / Slice 1 of MESH-2014).
- *
- * A per-tenant `tailscaled` runs in userspace-networking mode (brew formula,
- * NOT the GUI app) exposing a SOCKS5 proxy; forwarders bridge `localhost:PORT`
- * to VPC services through it. State lives under `~/.config/mesh/tailscale/<tenant>/`
- * (r+w-granted under safehouse — see the MESH-2036 spike).
- */
 import * as fs from "node:fs";
 import * as net from "node:net";
 import * as os from "node:os";
@@ -22,9 +13,6 @@ import { resolveTunnelTargets, resolveElbIp, tenantPortIndex, PORT_BLOCK } from
 import { createForwarder } from "./socks-forward.js";
 import { mintRunnerToken, readRunnerManifest, writeRunnerManifest, clearRunnerManifest, getProcessGroupId, discoverRunnerPids, startControlServer, verifyRunnerOwnership, pollOwnership, findSquattedPorts, buildSquatterError, } from "./tunnel-ownership.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-// ============================================================================
-// Paths
-// ============================================================================
 export function tenantStateDir(tenant) {
     return path.join(CONFIG_DIR, "tailscale", tenant);
 }
@@ -37,22 +25,9 @@ export function logPath(tenant) {
 export function statePath(tenant) {
     return path.join(tenantStateDir(tenant), "tunnel-state.json");
 }
-/**
- * Daemon-scoped metadata, written by `ensureDaemon` when it actually spawns the
- * daemon. Unlike `tunnel-state.json` (which `down` clears), this survives `down`
- * so a later `up` reuses the RUNNING daemon's SOCKS port instead of minting a
- * fresh one the daemon isn't listening on (which would leave every forwarder
- * dialing a dead port). Also records the daemon pid so `stopDaemon` can kill it.
- */
 export function daemonMetaPath(tenant) {
     return path.join(tenantStateDir(tenant), "daemon.json");
 }
-/**
- * Ownership manifest written by the RUNNER (the process that binds the
- * forwarder ports) — pid, process-group id, per-run token, control port. The
- * ownership handshake (MESH-2407) verifies against it; teardown signals the
- * recorded process group.
- */
 export function runnerManifestPath(tenant) {
     return path.join(tenantStateDir(tenant), "runner.json");
 }
@@ -76,7 +51,6 @@ export function clearTunnelState(tenant) {
         fs.unlinkSync(statePath(tenant));
     }
     catch {
-        /* already gone */
     }
 }
 export function readDaemonMeta(tenant) {
@@ -99,13 +73,8 @@ export function clearDaemonMeta(tenant) {
         fs.unlinkSync(daemonMetaPath(tenant));
     }
     catch {
-        /* already gone */
     }
 }
-// ============================================================================
-// Daemon status parsing
-// ============================================================================
-/** Parse `tailscale status --json` → the fields we care about. */
 export function parseDaemonState(statusJson) {
     try {
         const j = JSON.parse(statusJson);
@@ -115,14 +84,9 @@ export function parseDaemonState(statusJson) {
         return { backendState: "Unknown" };
     }
 }
-// ============================================================================
-// Binary resolution (macOS / brew — Slice 1)
-// ============================================================================
-/** The brew `tailscaled` (NOT the GUI app, which ships no standalone daemon). */
 export function tailscaledBinPath() {
     return resolveBrewBin("tailscaled");
 }
-/** The brew `tailscale` CLI (prefer it over the GUI shim, which aborts under sandbox). */
 export function tailscaleBinPath() {
     return resolveBrewBin("tailscale");
 }
@@ -136,14 +100,9 @@ function resolveBrewBin(name) {
             return p;
     }
     catch {
-        /* fall through */
     }
     throw new Error(`${name} not found — install the standalone binary: brew install tailscale`);
 }
-// ============================================================================
-// Daemon lifecycle
-// ============================================================================
-/** Backend state via the tenant's control socket; "Down" when no daemon answers. */
 export function daemonState(tenant) {
     if (!fs.existsSync(socketPath(tenant)))
         return { backendState: "Down" };
@@ -155,12 +114,6 @@ export function daemonState(tenant) {
         return { backendState: "Down" };
     }
 }
-/**
- * Extract the `--socks5-server` port from a `tailscaled` command line. Pure so
- * it's unit-testable. Accepts both `--socks5-server=127.0.0.1:PORT` and the
- * space-separated form, and a `localhost` host literal. Returns null if absent
- * or malformed.
- */
 export function parseSocksPortFromArgv(argv) {
     const m = argv.match(/--socks5-server[=\s]+(?:127\.0\.0\.1|localhost):(\d+)/);
     if (!m)
@@ -168,13 +121,6 @@ export function parseSocksPortFromArgv(argv) {
     const port = Number(m[1]);
     return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
 }
-/**
- * Find the running userspace `tailscaled` for a tenant by its unique
- * `--socket=<path>` argument, returning its pid and the SOCKS port it ACTUALLY
- * bound (parsed from argv). Authoritative when `daemon.json` is missing or stale
- * (e.g. a daemon left by an older build that predates the meta file). Returns
- * null when no matching process is found or `ps` is unavailable.
- */
 export function findRunningDaemon(tenant) {
     const sock = socketPath(tenant);
     let out;
@@ -188,8 +134,6 @@ export function findRunningDaemon(tenant) {
         return null;
     }
     for (const line of out.split("\n")) {
-        // Match this tenant's daemon by its unique --socket path (skips the ps line,
-        // other tenants' daemons, and the GUI app).
         if (!line.includes("tailscaled") || !line.includes(`--socket=${sock}`))
             continue;
         const m = line.trim().match(/^(\d+)\s+(.*)$/);
@@ -199,7 +143,6 @@ export function findRunningDaemon(tenant) {
     }
     return null;
 }
-/** True if something accepts TCP on 127.0.0.1:port within `timeoutMs`. */
 export function portAccepts(port, timeoutMs = 400) {
     return new Promise((resolve) => {
         const s = new net.Socket();
@@ -218,18 +161,8 @@ export function portAccepts(port, timeoutMs = 400) {
         s.connect(port, "127.0.0.1");
     });
 }
-/**
- * Ensure a userspace `tailscaled` is running for the tenant and return the SOCKS
- * port the forwarders should dial. Idempotent — reuses a live daemon, but
- * RECONCILES the port: a daemon that's up on a different port than requested
- * (older build with no `daemon.json`, or stale meta) would otherwise leave every
- * forwarder dialing a dead port (MESH-2169). Trust `opts.socksPort` only if it
- * truly accepts; else adopt the running daemon's real port; else restart fresh.
- */
 export async function ensureDaemon(tenant, opts) {
     if (daemonState(tenant).backendState !== "Down") {
-        // The daemon's SOCKS proxy is only useful on the exact port the forwarders
-        // will dial. If the requested port already accepts, record it and use it.
         if (await portAccepts(opts.socksPort)) {
             writeDaemonMeta(tenant, {
                 socksPort: opts.socksPort,
@@ -237,17 +170,11 @@ export async function ensureDaemon(tenant, opts) {
             });
             return opts.socksPort;
         }
-        // Requested port is dead — the daemon is on a different one. Discover its
-        // real SOCKS port from argv and adopt it (no restart → no severing other
-        // sessions), rewriting daemon.json so future runs read the right port.
         const running = findRunningDaemon(tenant);
         if (running?.socksPort && (await portAccepts(running.socksPort))) {
             writeDaemonMeta(tenant, { socksPort: running.socksPort, pid: running.pid });
             return running.socksPort;
         }
-        // Can't discover/verify a working SOCKS port — the daemon is unusable to us.
-        // Tear it down (state dir keeps the node identity → no re-login) and fall
-        // through to a fresh start on opts.socksPort.
         stopDaemon(tenant);
         for (let i = 0; i < 12 && daemonState(tenant).backendState !== "Down"; i++) {
             await sleep(250);
@@ -269,8 +196,6 @@ export async function ensureDaemon(tenant, opts) {
             env: { ...process.env, AWS_REGION: opts.region },
         });
         child.unref();
-        // Persist the socks port + pid so `down` → `up` reuses this daemon's real
-        // port (not a fresh one it isn't listening on) and `stopDaemon` can kill it.
         if (child.pid)
             writeDaemonMeta(tenant, { socksPort: opts.socksPort, pid: child.pid });
     }
@@ -284,31 +209,11 @@ export async function ensureDaemon(tenant, opts) {
     }
     throw new Error(`tailscaled did not start for tenant '${tenant}' — see ${logPath(tenant)}`);
 }
-/**
- * Stop the detached `tailscaled` for a tenant (SIGTERM its pid) and remove the
- * socket + daemon metadata. Leaves the Headscale node identity in `tailscaled.state`
- * so a later `up` re-spawns and rejoins without an interactive re-login — unless
- * the caller logged out first.
- *
- * Best-effort, and that includes a corrupt `daemon.json`: an unsignalable
- * recorded pid is REFUSED (never handed to `kill`) but only warns — the socket
- * and meta are still cleared. `ensureDaemon` calls this on the UP path to
- * recycle a daemon it can't verify, so throwing here would dead-end
- * `mesh vpn tunnel up` / `mesh dev` on the very file this function deletes.
- * Safe to call when nothing is running.
- */
 export function stopDaemon(tenant) {
-    // Prefer the recorded pid; fall back to discovering it from argv so a daemon
-    // left without a daemon.json (older build / cleared meta) can still be killed.
     const meta = readDaemonMeta(tenant) ?? (() => {
         const running = findRunningDaemon(tenant);
         return running ? { socksPort: running.socksPort ?? 0, pid: running.pid } : null;
     })();
-    // `ensureDaemon` records `pid: 0` when it adopts a running daemon whose pid it
-    // could not attribute, so absent-or-0 is this file's "no pid known" sentinel —
-    // skip it, don't signal and don't fail. EVERY other unsignalable value (1, a
-    // negative, a fraction, a string from a truncated/hand-edited daemon.json) is
-    // corruption and must be refused rather than handed to kill. See utils/pid.ts.
     if (meta?.pid) {
         try {
             assertSignalablePid(meta.pid, {
@@ -318,13 +223,8 @@ export function stopDaemon(tenant) {
             process.kill(meta.pid, "SIGTERM");
         }
         catch (err) {
-            // Refusing to SIGNAL is the whole point; refusing to CLEAN UP is not.
-            // The unlink + clearDaemonMeta below are what make the corrupt file
-            // self-healing, and `ensureDaemon` (the UP path) depends on them. Warn
-            // with the `rm` remediation intact and fall through.
             if (err instanceof MeshCliError)
                 logWarn(renderErrorBody(err));
-            /* else: ESRCH/EPERM from process.kill — already gone, as before */
         }
     }
     for (const p of [socketPath(tenant)]) {
@@ -332,16 +232,10 @@ export function stopDaemon(tenant) {
             fs.unlinkSync(p);
         }
         catch {
-            /* already gone */
         }
     }
     clearDaemonMeta(tenant);
 }
-/**
- * Build the `tailscale up` argument vector. Pure so it can be unit-tested and so
- * the interactive (browser-register) and zero-touch (pre-auth key) forms differ
- * only by the trailing `--authkey`.
- */
 export function buildTailscaleUpArgs(opts) {
     const args = [
         "--socket", opts.socket, "up",
@@ -353,12 +247,6 @@ export function buildTailscaleUpArgs(opts) {
         args.push("--authkey", opts.preAuthKey);
     return args;
 }
-/**
- * Join the tenant's Headscale tailnet via Zitadel OIDC if not already Running.
- * Prints the device-flow registration URL and polls until registered. When a
- * pre-auth key is supplied the join is non-interactive: no `/register/` URL is
- * emitted, so the scrape/relay is skipped and we just wait for Running.
- */
 export async function joinHeadscale(tenant, loginServer, opts = {}) {
     if (daemonState(tenant).backendState === "Running")
         return;
@@ -374,8 +262,6 @@ export async function joinHeadscale(tenant, loginServer, opts = {}) {
             const m = buf.match(/https?:\/\/\S+\/register\/\S+/);
             if (m) {
                 urlShown = true;
-                // Relay the registration URL for headless/SSH machines (there's no local
-                // browser to pop). One-time per machine — the node registration persists.
                 logInfo(`\n  This machine isn't registered with the platform VPN yet.\n` +
                     `  Open this URL in a browser to authorize it (one-time, sign in with Zitadel):\n\n` +
                     `      ${m[0]}\n\n` +
@@ -385,7 +271,6 @@ export async function joinHeadscale(tenant, loginServer, opts = {}) {
         child.stdout.on("data", capture);
         child.stderr.on("data", capture);
     }
-    // Poll up to ~5 min — the join is an interactive browser approval.
     for (let i = 0; i < 600; i++) {
         await sleep(500);
         if (daemonState(tenant).backendState === "Running") {
@@ -396,29 +281,17 @@ export async function joinHeadscale(tenant, loginServer, opts = {}) {
     child.kill();
     throw new Error(`VPN join not completed for tenant '${tenant}' within 5 min. Re-run \`mesh vpn tunnel up\` to resume — the daemon is still up.`);
 }
-/** Log the tenant daemon out of Headscale (disconnect). Daemon process persists. */
 export function logout(tenant) {
     try {
         execFileSync(tailscaleBinPath(), ["--socket", socketPath(tenant), "logout"], { stdio: "ignore" });
     }
     catch {
-        /* best-effort */
-    }
-}
-// ============================================================================
-// Forwarder supervisor (shared per tenant) + devOutput rewrite
-// ============================================================================
-/**
- * True iff two target sets are identical down to targetIp + remotePort. A live
- * runner pins each forwarder's target at startup, so if the ELB IP rotated (or a
- * port changed) the running forwarders point at a dead address and must be
- * respawned, not reused. Pid-agnostic (a launchd runner records no supervisor pid).
- */
+    }
+}
 export function tunnelTargetsEqual(a, b) {
     const key = (ts) => ts.map((t) => `${t.name}:${t.localPort}:${t.targetIp}:${t.remotePort}`).sort().join(",");
     return key(a) === key(b);
 }
-/** True iff `state` has a supervisor pid and its target set equals `targets`. */
 export function supervisorTargetsMatch(state, targets) {
     if (!state || !state.supervisorPid)
         return false;
@@ -435,60 +308,19 @@ function pidAlive(pid) {
         return false;
     }
 }
-/**
- * SIGTERM the supervisor's whole process GROUP, not the bare pid.
- *
- * `state.supervisorPid` is the pid of the detached spawn — which, under the
- * canonical source launcher, is `bin/mesh.mjs`. That launcher blocks in
- * `execFileSync` around the *real* runner (a `node --import tsx … mesh.ts`
- * grandchild that actually binds the forwarder ports), and `execFileSync` does
- * not forward signals. So signalling the bare pid kills only the launcher and
- * ORPHANS the runner, which keeps its ports bound — the orphan then answers
- * `allForwardersListening`'s ownership-less liveness dial and silently pins
- * every tunnel to a stale target (the MESH-2169 / MESH-2014 failure class).
- *
- * The launcher is spawned `detached: true`, so it is a process-group leader
- * (`pgid === pid`); `process.kill(-pid, …)` reaps the launcher and the runner
- * together. Falls back to the bare pid for a legacy state file whose pid was
- * not a group leader, and tolerates ESRCH (already gone).
- *
- * `pid` is always recovered — from `tunnel-state.json`, `runner.json`, or a
- * `ps` scan — never constructed here, so it is guarded first. The guard rejects
- * anything below 2, which is what makes the NEGATED form safe: `pid >= 2` ⇒
- * `-pid <= -2`, a real process group, never `kill(0)` (this shell's own group)
- * or `kill(-1)` (broadcast to everything the user can signal). See utils/pid.ts.
- *
- * @throws {MeshCliError} when `pid` is unsignalable. Callers reaping SEVERAL
- * independently-recovered pids must catch per-pid (see `stopTunnelRunners`) —
- * letting one refusal propagate would skip the other pids and leave a live
- * runner holding ports.
- */
 export function killSupervisor(pid, source) {
-    // MUST be outside the try — both signals below are wrapped in catch-alls, so a
-    // guard placed inside would have its refusal swallowed and fall through to the
-    // bare-pid kill it was meant to prevent.
     assertSignalablePid(pid, source ?? { what: "tunnel supervisor pid" });
     try {
-        process.kill(-pid, "SIGTERM"); // detached spawn ⇒ pid is the group leader
+        process.kill(-pid, "SIGTERM");
     }
     catch {
         try {
-            process.kill(pid, "SIGTERM"); // not a group leader (old state file) — best effort
+            process.kill(pid, "SIGTERM");
         }
         catch {
-            /* already gone (ESRCH) */
         }
     }
 }
-/**
- * The ownership handshake for a tenant's tunnel runner (MESH-2407): manifest →
- * live pid → control endpoint → token + SOCKS port + port coverage. This is
- * the ONLY readiness/reuse signal — a bare TCP dial proves a listener exists,
- * not that it is ours, and adopting a foreign listener is exactly the
- * silent-dead-tunnel class (MESH-2169 / MESH-2014 / #2991). As a bonus the
- * handshake reads listening state from the runner's in-process servers, so it
- * opens no SOCKS→VPC data connection the way port dials do.
- */
 export async function verifyTunnelOwnership(tenant, expected) {
     return verifyRunnerOwnership({
         manifest: readRunnerManifest(runnerManifestPath(tenant)),
@@ -496,37 +328,12 @@ export async function verifyTunnelOwnership(tenant, expected) {
         expectedPorts: expected.ports,
     });
 }
-/**
- * Poll the ownership handshake until it passes or `deadlineMs` of WALL CLOCK
- * elapses (each check can cost up to the control-query timeout, so the bound
- * must be time, not rounds); returns the last check.
- */
 function awaitOwnership(tenant, expected, deadlineMs) {
     return pollOwnership(() => verifyTunnelOwnership(tenant, expected), deadlineMs);
 }
-/**
- * Tear down EVERY runner we can attribute to the tenant: the recorded
- * supervisor pid (as a process group — see `killSupervisor`), the launchd
- * agent, the manifest's process group, and any `__run`/`__supervise` process
- * discovered from argv (a runner from an older build, or one whose state file
- * was lost). This is the single teardown path — the #2991 lesson generalized:
- * no kill path may leave a grandchild with ports still bound.
- */
 export function stopTunnelRunners(tenant, prior) {
     if (prior?.managed === "launchd")
         uninstallLaunchAgent(tenant);
-    // Each pid below is RECOVERED (two state files and a ps scan), so each names
-    // its own provenance — the refusal has to point at the exact file to delete,
-    // or a corrupt state dir bricks the very command that would have cleared it.
-    //
-    // The three sources are INDEPENDENT, so a refusal on one must not skip the
-    // others or `clearRunnerManifest`. Aborting would let one corrupt integer in
-    // `tunnel-state.json` strand a live, uncorrupted runner from `runner.json`
-    // with its forwarder ports still bound — the silent-squatter class this
-    // teardown exists to prevent ("no kill path may leave a grandchild with ports
-    // still bound", MESH-2407). Refuse the bad pid, reap the rest;
-    // `assertTunnelPortsFree` is the backstop that still fails loudly if an
-    // un-reaped runner really is holding ports.
     const killOrWarn = (pid, source) => {
         try {
             killSupervisor(pid, source);
@@ -552,12 +359,6 @@ export function stopTunnelRunners(tenant, prior) {
         killOrWarn(pid, { what: `a tunnel runner pid discovered from 'ps' for tenant '${tenant}'` });
     clearRunnerManifest(runnerManifestPath(tenant));
 }
-/**
- * After teardown, wait for the tenant's forwarder ports to actually free. Any
- * port still accepting is held by a process we could not kill — a foreign
- * squatter — and spawning a runner over it would produce forwarders that
- * silently fail to bind (the false-green readiness gate). Fail LOUDLY instead.
- */
 async function assertTunnelPortsFree(tenant, ports) {
     let held = ports;
     for (let i = 0; i < 8; i++) {
@@ -574,40 +375,15 @@ async function assertTunnelPortsFree(tenant, ports) {
     const squatted = await findSquattedPorts(held, (p) => portAccepts(p, 250));
     throw new Error(buildSquatterError(tenant, squatted, "still bound after teardown"));
 }
-/**
- * Ensure the per-tenant forwarder supervisor is running for `state.tunnels`.
- * Idempotent: reuses a live runner ONLY when it passes the ownership handshake
- * (our manifest token, our SOCKS port, every target port listening in-process);
- * otherwise tears down every attributable runner, verifies the ports actually
- * freed (a still-held port is a foreign squatter → loud failure, never spawn
- * over it), and (re)spawns a fresh runner — whose readiness is again the
- * handshake, not a bare port dial. Persists the state and returns the pid.
- */
 export async function ensureForwarders(state) {
     const prior = readTunnelState(state.tenant);
     const expected = { socksPort: state.socksPort, ports: state.tunnels.map((t) => t.localPort) };
-    // Reuse-if-healthy must be mode-aware. A launchd runner records no supervisorPid
-    // (KeepAlive owns liveness), so gating reuse on pidAlive would tear down + rebind
-    // the shared tunnels on EVERY `up`/`mesh dev` — severing other concurrent sessions,
-    // the exact failure MESH-2014 exists to kill. Treat the launchd agent as "alive"
-    // when its plist is installed; keep the pid check for the detached path.
     const runnerAlive = prior?.managed === "launchd"
         ? fs.existsSync(launchAgentPath(state.tenant))
         : pidAlive(prior?.supervisorPid);
     if (prior &&
         runnerAlive &&
         tunnelTargetsEqual(prior.tunnels, state.tunnels) &&
-        // A prior supervisor spawned for a DIFFERENT SOCKS port still binds the same
-        // local ports but dials a dead upstream — reusing it silently strands every
-        // tunnel (MESH-2169). The port must match, and the runner must PROVE it is
-        // ours via the ownership handshake (liveness ≠ ownership — a port answering
-        // a dial can be another session's SSM tunnel or an orphaned runner, #2991).
-        // Poll briefly rather than sample once: `ports-not-listening` during the
-        // runner's own rebind window and `no-control-answer` under load are
-        // transient, and a single miss here would tear down a healthy runner SHARED
-        // by every concurrent session on the tenant (MESH-2014). This branch is
-        // only reached when the runner is alive with matching targets, so the
-        // retry costs nothing on cold-start or genuinely-dead paths.
         prior.socksPort === state.socksPort &&
         (await awaitOwnership(state.tenant, expected, 1000)).ok) {
         state.supervisorPid = prior.supervisorPid;
@@ -615,38 +391,17 @@ export async function ensureForwarders(state) {
         writeTunnelState(state.tenant, state);
         return prior.supervisorPid ?? 0;
     }
-    // Tear down every attributable runner (state pid group, launchd agent,
-    // manifest process group, argv-discovered strays), then require the ports to
-    // actually free — a still-held port is foreign and must fail loudly here,
-    // not surface later as a forwarder that silently failed to bind.
     stopTunnelRunners(state.tenant, prior);
     await assertTunnelPortsFree(state.tenant, expected.ports);
-    // Write state first so the runner reads the correct targets on start.
     state.supervisorPid = null;
-    // Prefer a launchd-supervised runner (survives reboot/crash); fall back to a
-    // detached runner where launchd isn't usable (e.g. sandboxed shells). Both run
-    // the same self-healing `__run`.
-    // argv[1] under the canonical source launcher is bin/mesh.ts, which plain
-    // node cannot execute (same failure class as the credential_process fix in
-    // aws-auth.ts) — resolve to the stable launcher, or the bare `mesh` fallback.
     const meshBin = resolveStableMeshBin(process.argv[1]);
     if (launchdAvailable()) {
         state.managed = "launchd";
         writeTunnelState(state.tenant, state);
-        // launchd does no PATH lookup, so the bare `mesh` fallback can't back a
-        // LaunchAgent (it would become `node mesh …`, crash-looping under KeepAlive).
-        // Require an absolute path; otherwise fall through to the detached runner,
-        // where spawn *does* resolve `mesh` on PATH.
         if (path.isAbsolute(meshBin) && installLaunchAgent(state.tenant, meshBin)) {
-            // Installing the agent proves nothing about the forwarders — wait for the
-            // runner's ownership handshake (this path used to return success blind).
             if ((await awaitOwnership(state.tenant, expected, 8000)).ok)
                 return 0;
             uninstallLaunchAgent(state.tenant);
-            // `launchctl bootout` signals the job but doesn't wait for it — spawning
-            // the detached runner immediately would race the dying launchd runner for
-            // the ports (EADDRINUSE → a transient turned into a hard failure). Every
-            // teardown path must be followed by the ports-actually-freed check.
             await assertTunnelPortsFree(state.tenant, expected.ports);
             logInfo("launchd runner did not take ownership of the tunnel ports — using a detached runner.");
         }
@@ -656,29 +411,17 @@ export async function ensureForwarders(state) {
     }
     state.managed = "detached";
     writeTunnelState(state.tenant, state);
-    // meshBin is the stable launcher, or the bare `mesh` fallback which spawn
-    // resolves on PATH here (no PATH-lookup ternary needed — that was a no-op).
     const child = spawn(meshBin, ["vpn", "tunnel", "__run", state.tenant], {
         detached: true,
         stdio: "ignore",
     });
-    // ENOENT from the bare `mesh` fallback (mesh-cli not installed globally)
-    // arrives asynchronously — without this handler an unhandled 'error' throws
-    // an uncaught exception and takes down `mesh dev` instead of degrading.
     child.on("error", (err) => logWarn(`tunnel supervisor failed to start (${err.message}) — falling back to SSM.`));
     child.unref();
     state.supervisorPid = child.pid ?? null;
     writeTunnelState(state.tenant, state);
-    // Readiness = the ownership handshake, not a port dial: the fresh runner must
-    // present its manifest token and report every forwarder listening from its
-    // own in-process servers. A dial would also pass for another session's SSM
-    // tunnel on the same 2XXXX port — the false-green this contract kills.
-    // Throwing here lands in startServices' catch → clean SSM fallback.
     const last = await awaitOwnership(state.tenant, expected, 5000);
     if (last.ok)
         return child.pid ?? -1;
-    // Diagnose before failing: a port that accepts TCP while ownership failed is
-    // held by someone else — name it and say exactly what to do.
     const squatted = await findSquattedPorts(expected.ports, (p) => portAccepts(p, 250));
     if (squatted.length > 0) {
         throw new Error(buildSquatterError(state.tenant, squatted, `ownership check: ${last.reason}`));
@@ -689,11 +432,6 @@ export async function ensureForwarders(state) {
     throw new Error(`Tailscale forwarders did not take ownership for tenant '${state.tenant}' ` +
         `(${last.reason}${bindErrors ? `; ${bindErrors}` : ""}) — see ${logPath(state.tenant)}.`);
 }
-/**
- * Rewrite `devOutput.tunnels` so each resolved target points at its local
- * forwarder (`localhost:localPort`) — the same shape `startSsmTunnels`
- * produces. Unmatched tunnels are left untouched. Pure (no mutation of input).
- */
 export function rewriteTunnelsForTargets(devOutput, targets) {
     const tunnels = { ...devOutput.tunnels };
     for (const t of targets) {
@@ -701,7 +439,6 @@ export function rewriteTunnelsForTargets(devOutput, targets) {
     }
     return { ...devOutput, tunnels };
 }
-/** True when the brew `tailscaled` binary is resolvable (Tailscale transport is usable). */
 export function tailscaleAvailable() {
     try {
         tailscaledBinPath();
@@ -711,23 +448,9 @@ export function tailscaleAvailable() {
         return false;
     }
 }
-// ============================================================================
-// Shared engine: ensure/start Tailscale tunnels (used by the command + mesh dev)
-// ============================================================================
-/**
- * Ensure the tenant's Tailscale tunnels are fully up: the shared per-tenant
- * daemon (started + OIDC-joined if needed), the resolved VPC targets, and the
- * forwarder supervisor. Idempotent (shared across worktrees/invocations of the
- * same tenant). Returns the resolved targets. Used by both `mesh vpn tunnel up`
- * and `mesh dev --transport=tailscale`.
- */
 export async function ensureTailscaleTunnels(tenant, env, opts) {
-    // Reconcile the daemon's SOCKS port — an already-running daemon may be on a
-    // different port than requested; the forwarders MUST dial the real one (MESH-2169).
     const socksPort = await ensureDaemon(tenant, { region: opts.region, socksPort: opts.socksPort });
     await joinHeadscale(tenant, opts.loginServer, { preAuthKey: opts.preAuthKey });
-    // Pass the region explicitly rather than clobbering process.env.AWS_REGION —
-    // this runs mid `mesh dev` launch and must not mutate the global env.
     const bastion = await getPlatformBastionInfo(tenant, env, opts.region);
     if (!bastion) {
         throw new Error(`Could not read the platform bastion for ${tenant}/${env} (check AWS credentials).`);
@@ -749,10 +472,6 @@ export async function ensureTailscaleTunnels(tenant, env, opts) {
     await ensureForwarders(state);
     return targets;
 }
-/**
- * `startSsmTunnels` drop-in for `mesh dev`: ensure the tenant's Tailscale
- * tunnels, then rewrite `devOutput.tunnels` to the local forwarder ports.
- */
 export async function startTailscaleTunnels(devOutput, ctx) {
     const targets = await ensureTailscaleTunnels(ctx.tenant, ctx.env, {
         region: ctx.region,
@@ -762,20 +481,15 @@ export async function startTailscaleTunnels(devOutput, ctx) {
     });
     return rewriteTunnelsForTargets(devOutput, targets);
 }
-// ============================================================================
-// launchd supervision + self-heal (Slice 2a)
-// ============================================================================
 export function launchAgentLabel(tenant) {
     return `tech.mesh.tunnel.${tenant}`;
 }
-/** Minimal XML-escape for plist string values (controlled inputs, but paths can vary). */
 function xmlEscape(s) {
     return s
         .replace(/&/g, "&amp;")
         .replace(/</g, "&lt;")
         .replace(/>/g, "&gt;");
 }
-/** Render the per-tenant LaunchAgent plist (pure). */
 export function renderLaunchAgentPlist(args) {
     const pathEnv = args.pathEnv ?? "/usr/bin:/bin:/usr/sbin:/sbin";
     return `<?xml version="1.0" encoding="UTF-8"?>
@@ -813,7 +527,6 @@ export function renderLaunchAgentPlist(args) {
 </plist>
 `;
 }
-/** Targets whose local forwarder port isn't currently accepting connections. */
 export function forwardersNeedingRebind(targets, listening) {
     return targets.filter((t) => !listening.has(t.localPort));
 }
@@ -824,7 +537,6 @@ function guiDomain() {
     return `gui/${process.getuid?.() ?? 0}`;
 }
 let _launchdAvailable;
-/** True when launchctl works for this user (blocked under the seatbelt sandbox → false). */
 export function launchdAvailable() {
     if (_launchdAvailable !== undefined)
         return _launchdAvailable;
@@ -838,32 +550,20 @@ export function launchdAvailable() {
     }
     return _launchdAvailable;
 }
-/**
- * Write + (re)load the per-tenant LaunchAgent. Returns true iff it fully
- * succeeded — any failure (plist write blocked by the sandbox, `launchctl`
- * bootstrap denied, …) returns false so the caller falls back to a detached
- * runner. Never throws.
- */
 export function installLaunchAgent(tenant, meshBin) {
     const plistPath = launchAgentPath(tenant);
     try {
-        // Resolve symlinks so the plist embeds a stable path (a since-deleted
-        // worktree symlink would leave a KeepAlive agent respawning a dead binary).
         let realMeshBin = meshBin;
         try {
             realMeshBin = fs.realpathSync(meshBin);
         }
         catch {
-            /* keep the raw path */
         }
-        // Bake a PATH that includes the tailscaled dir so the runner's daemon reheal
-        // works under launchd's minimal PATH (Intel installs live in /usr/local/bin).
         let pathEnv = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
         try {
             pathEnv = `${path.dirname(tailscaledBinPath())}:${pathEnv}`;
         }
         catch {
-            /* fall back to the default PATH */
         }
         fs.mkdirSync(path.dirname(plistPath), { recursive: true });
         fs.writeFileSync(plistPath, renderLaunchAgentPlist({
@@ -877,7 +577,6 @@ export function installLaunchAgent(tenant, meshBin) {
             execFileSync("launchctl", ["bootout", guiDomain(), plistPath], { stdio: "ignore" });
         }
         catch {
-            /* not loaded — fine */
         }
         execFileSync("launchctl", ["bootstrap", guiDomain(), plistPath], { stdio: "ignore" });
         return true;
@@ -886,50 +585,28 @@ export function installLaunchAgent(tenant, meshBin) {
         return false;
     }
 }
-/** Unload + remove the per-tenant LaunchAgent (best-effort). */
 export function uninstallLaunchAgent(tenant) {
     const plistPath = launchAgentPath(tenant);
     try {
         execFileSync("launchctl", ["bootout", guiDomain(), plistPath], { stdio: "ignore" });
     }
     catch {
-        /* not loaded */
     }
     try {
         fs.unlinkSync(plistPath);
     }
     catch {
-        /* already gone */
-    }
-}
-// ============================================================================
-// The runner (__run): forwarders + continuous self-heal
-// ============================================================================
-/**
- * Long-lived runner for a tenant's tunnels — used both under launchd and as the
- * detached fallback. Runs a forwarder per target and, every ~5s, self-heals:
- * respawns the daemon if its process died, and rebinds any forwarder whose port
- * stopped listening. As the process that actually binds the ports, it is the
- * sole author of the ownership manifest + control endpoint (MESH-2407) that
- * callers verify against. Needs no AWS (targets come from tunnel-state). Never
- * returns.
- */
+    }
+}
 export async function runTunnels(tenant) {
     const st = readTunnelState(tenant);
     if (!st) {
-        // State is gone (torn down). Under launchd's KeepAlive a non-zero exit would
-        // respawn every ~10s forever (surviving reboots) — so self-uninstall the
-        // agent (no-op when detached), drop any manifest a previous incarnation
-        // left (it describes a runner that no longer exists), and exit cleanly.
         uninstallLaunchAgent(tenant);
         clearRunnerManifest(runnerManifestPath(tenant));
         process.exit(0);
     }
     const token = mintRunnerToken();
     const servers = new Map();
-    // port → last bind error code. Surfaced through the control endpoint so a
-    // failed bind (EADDRINUSE from a squatted port) is a visible, attributable
-    // failure at the caller — never a silently-dead forwarder.
     const bindErrors = new Map();
     const spawnFor = (t) => {
         servers.get(t.localPort)?.close();
@@ -971,8 +648,6 @@ export async function runTunnels(tenant) {
         control.server.close();
         for (const s of servers.values())
             s.close();
-        // Token-guarded: never clobber the manifest of a newer runner that already
-        // replaced us (teardown kills groups, and signal delivery order is loose).
         clearRunnerManifest(runnerManifestPath(tenant), token);
         process.exit(0);
     };
@@ -987,10 +662,6 @@ export async function runTunnels(tenant) {
                     socksPort: st.socksPort,
                 });
             }
-            // Check the in-process net.Server directly — do NOT dial the forwarder.
-            // A dial makes the forwarder open a real SOCKS→VPC-target connection, and
-            // the probe's clean FIN doesn't tear the upstream leg down, leaking a
-            // connection to Temporal/RDS/etc. every 5s per target.
             const listening = new Set();
             for (const t of st.tunnels) {
                 if (servers.get(t.localPort)?.listening)
@@ -1000,8 +671,6 @@ export async function runTunnels(tenant) {
                 spawnFor(t);
         }
         catch {
-            /* keep the loop alive across transient errors */
         }
     }
 }
-//# sourceMappingURL=tailscale.js.map