@repo-os/repoos 0.5.45

package/dist/commands/tunnel.js

@@ -0,0 +1,1271 @@
+/**
+ * `repoos tunnel ...` — Cloudflare Tunnel + Zero Trust publishing.
+ *
+ * RepoOS orchestrates `cloudflared` (it never reimplements the tunnel
+ * protocol) and reconciles Cloudflare Access policies from RepoOS's own
+ * `[tunnel]` state in repoos.toml. One machine runs one tunnel with many
+ * hostname → local service ingress routes; every published app is protected by
+ * an Access policy restricted to its email allowlist.
+ *
+ * `cloudflared` is one system service reading one config file per machine —
+ * it has no notion of "repo." So `repoos tunnel` commands are machine-global,
+ * not repo-local: `repoos.toml [tunnel.apps.*]` stays each repo's own,
+ * git-tracked source of truth for the apps IT publishes, but `install`/
+ * `start` always render the ingress from the UNION of every repo's apps on
+ * this box, tracked in the machine-level registry
+ * (`~/.config/repoos/tunnel-apps.toml`, see `../core/tunnel-registry.ts` and
+ * docs/tunnel-registry.md). Running `install` from any one repo therefore
+ * serves every app published by any repo, and never clobbers another repo's
+ * routes the way overwriting the ingress from a single repo's config used to.
+ *
+ * No Cloudflare credentials or tunnel secrets are ever written to the repo —
+ * the API token lives in the OS keychain / secret storage (or
+ * `CLOUDFLARE_API_TOKEN`), and the tunnel credential file stays in
+ * `~/.cloudflared/` exactly as cloudflared already does.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir, hostname } from "node:os";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { c } from "../cli/colors.js";
+import { loadConfig } from "../core/config.js";
+import { resolveBinary } from "../core/detect.js";
+import { ACCESS_POLICY_NAME, DEFAULT_TUNNEL_NAME, addEmail, buildAccessAppBody, buildAccessPolicyBody, hostnameWarning, inferHostname, isValidAppName, isValidBaseDomain, isValidEmail, parseEmailList, readTunnelConfig, removeEmail, renderCloudflaredConfig, writeTunnelConfig, } from "../core/tunnel.js";
+import { annotateStale, readRegistry, reconcileIdentity, registryPath, removeApp, syncFromRepo, unionApps, upsertApp, withRegistryLock, writeRegistry, } from "../core/tunnel-registry.js";
+import { originPort, portListening } from "../core/net-probe.js";
+const CF_API = "https://api.cloudflare.com/client/v4";
+function fail(msg) {
+    console.error(c.red("  " + msg));
+    const err = new Error(msg);
+    err.repoosTunnel = true;
+    throw err;
+}
+function parseArgs(args) {
+    const positionals = [];
+    const flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--") {
+            positionals.push(...args.slice(i + 1));
+            break;
+        }
+        if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            if (eq !== -1) {
+                flags.set(a.slice(2, eq), a.slice(eq + 1));
+            }
+            else {
+                flags.set(a.slice(2), args[++i]);
+            }
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { positionals, flags };
+}
+// ── Interactive input ────────────────────────────────────────────────────────
+async function prompt(query) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(query)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function confirm(query, defaultYes = true) {
+    const suffix = defaultYes ? " [Y/n]" : " [y/N]";
+    const answer = (await prompt(query + suffix)).toLowerCase();
+    if (!answer)
+        return defaultYes;
+    return answer === "y" || answer === "yes";
+}
+/** Run a command attached to the user's terminal (foreground, interactive). */
+function runInteractive(bin, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: "inherit" });
+        child.on("error", (err) => reject(err));
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+}
+// ── cloudflared discovery ────────────────────────────────────────────────────
+function cloudflaredHomeDir() {
+    return join(homedir(), ".cloudflared");
+}
+/**
+ * Default tunnel name for a fresh setup: `repoos-<machine hostname>`. A tunnel
+ * is per-machine (one connector per box), so a machine-derived name is both
+ * legible in the Cloudflare dashboard and makes every repo on the same machine
+ * converge on one shared tunnel. Falls back to the legacy `repoos-local` when
+ * the hostname sanitizes to nothing usable.
+ */
+function defaultTunnelName() {
+    const host = hostname()
+        .split(".")[0]
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/g, "");
+    return host ? `repoos-${host}` : DEFAULT_TUNNEL_NAME;
+}
+function repoosConfigDir() {
+    return join(homedir(), ".config", "repoos");
+}
+function cloudflaredBin() {
+    const bin = resolveBinary("cloudflared", process.env.PATH ?? "");
+    if (bin)
+        return bin;
+    return fail("cloudflared is not installed or not on PATH.\n" +
+        "    Install it (`brew install cloudflared` on macOS, or see\n" +
+        "    https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/)\n" +
+        "    then run `repoos tunnel setup`.");
+}
+/** `cloudflared tunnel list`, tolerant of JSON and legacy text output. */
+function cloudflaredList(bin) {
+    try {
+        const out = execFileSync(bin, ["tunnel", "list", "--output", "json"], {
+            encoding: "utf8",
+            timeout: 30_000,
+        });
+        const data = JSON.parse(out);
+        if (Array.isArray(data)) {
+            return data.map((t) => ({
+                id: String(t.id ?? ""),
+                name: String(t.name ?? ""),
+                accountTag: t.account_tag ? String(t.account_tag) : undefined,
+            }));
+        }
+    }
+    catch {
+        // fall through to legacy text parsing
+    }
+    try {
+        const out = execFileSync(bin, ["tunnel", "list"], {
+            encoding: "utf8",
+            timeout: 30_000,
+        });
+        const rows = [];
+        for (const line of out.split("\n")) {
+            const m = line.match(/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\s+(\S+)/);
+            if (m)
+                rows.push({ id: m[1], name: m[2] });
+        }
+        return rows;
+    }
+    catch {
+        return [];
+    }
+}
+function tunnelCredentialsPath(tunnelId) {
+    return join(cloudflaredHomeDir(), `${tunnelId}.json`);
+}
+/**
+ * Regenerate cloudflared's ingress YAML from the machine-wide app set (the
+ * UNION of every repo's apps on this box, not just this repo's) into a
+ * RepoOS-owned location (`~/.config/repoos/cloudflared.yml`) used by
+ * `repoos tunnel start`.
+ */
+function writeDerivedConfig(tunnel, apps) {
+    const path = join(repoosConfigDir(), "cloudflared.yml");
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, renderCloudflaredConfig({ ...tunnel, apps }, tunnelCredentialsPath(tunnel.tunnelId)), { encoding: "utf8", mode: 0o600 });
+    return path;
+}
+/**
+ * Write the derived config to `~/.cloudflared/config.yml` — where
+ * `cloudflared service install` expects it. Rendered from the machine-wide
+ * app set (the union of every repo's apps on this box), so installing the
+ * service from any one repo serves every app published by any repo. An
+ * existing hand-maintained file that isn't RepoOS-generated is backed up
+ * once before being replaced.
+ */
+function writeUserCloudflaredConfig(tunnel, apps) {
+    const dir = cloudflaredHomeDir();
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, "config.yml");
+    if (existsSync(path)) {
+        const existing = readFileSync(path, "utf8");
+        if (!existing.includes("repoos.toml [tunnel]")) {
+            const backup = `${path}.repoos-backup`;
+            if (!existsSync(backup))
+                renameSync(path, backup);
+        }
+    }
+    writeFileSync(path, renderCloudflaredConfig({ ...tunnel, apps }, tunnelCredentialsPath(tunnel.tunnelId)), { encoding: "utf8", mode: 0o600 });
+    return path;
+}
+/**
+ * Run `mutate` against the machine registry inside an exclusive lock: reads
+ * it fresh, reconciles this repo's tunnel identity against it (failing
+ * loudly on a conflicting `tunnelId` rather than silently picking one),
+ * syncs this repo's own apps in from repoos.toml (seed new / update changed
+ * / drop ones this repo no longer declares — see `syncFromRepo`), lets
+ * `mutate` make its own change against the same in-memory registry, then
+ * persists the result. Every mutating tunnel subcommand (`create`,
+ * `destroy`, `install`, `start`, `rename`, `allow`, `deny`) goes through this
+ * so the registry never drifts from repoos.toml, and the whole
+ * read-reconcile-write cycle is serialized against any other `repoos tunnel`
+ * process on the machine racing the same file.
+ */
+function mutateRegistry(root, tunnel, mutate = () => { }) {
+    return withRegistryLock(registryPath(), () => {
+        const registry = readRegistry();
+        const conflict = reconcileIdentity(registry, tunnel);
+        if (conflict)
+            fail(conflict);
+        const seeded = syncFromRepo(registry, tunnel, root);
+        if (seeded.length) {
+            console.log(c.dim(`  · seeded machine tunnel registry with ${seeded.join(", ")} → ${registryPath()}`));
+        }
+        mutate(registry);
+        writeRegistry(registry);
+        return registry;
+    });
+}
+/**
+ * Read-only merged view of the registry for DISPLAY commands (`list`,
+ * `status`): same reconcile + sync as {@link mutateRegistry}, but never
+ * persists, never locks (nothing is written), and never fails on an
+ * identity conflict — it reports the conflict instead so the command can
+ * show it.
+ */
+function readRegistryForDisplay(root, tunnel) {
+    const registry = readRegistry();
+    const conflict = reconcileIdentity(registry, tunnel);
+    syncFromRepo(registry, tunnel, root);
+    return { registry, conflict };
+}
+async function installCloudflared() {
+    if (process.platform === "darwin") {
+        console.log(c.dim("  · installing cloudflared via Homebrew …"));
+        try {
+            return (await runInteractive("brew", ["install", "cloudflared"])) === 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (process.platform === "linux") {
+        const arch = process.arch === "arm64" ? "aarch64" : process.arch === "x64" ? "amd64" : null;
+        if (!arch)
+            return false;
+        const dir = join(homedir(), ".local", "bin");
+        mkdirSync(dir, { recursive: true });
+        const target = join(dir, "cloudflared");
+        const url = `https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${arch}`;
+        console.log(c.dim("  · downloading cloudflared (GitHub releases) …"));
+        try {
+            execFileSync("curl", ["-fsSL", url, "-o", target], { stdio: "inherit", timeout: 120_000 });
+            chmodSync(target, 0o755);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+// ── Cloudflare API token (keychain / secret storage — never in the repo) ────
+function tokenStoreCmds() {
+    if (process.platform === "darwin") {
+        return {
+            get: [
+                "security",
+                "find-generic-password",
+                "-a",
+                "repoos",
+                "-s",
+                "repoos:cloudflare-token",
+                "-w",
+            ],
+            set: (token) => [
+                "security",
+                "add-generic-password",
+                "-U",
+                "-a",
+                "repoos",
+                "-s",
+                "repoos:cloudflare-token",
+                "-w",
+                token,
+            ],
+        };
+    }
+    if (process.platform === "linux") {
+        return {
+            get: ["secret-tool", "lookup", "service", "repoos:cloudflare-token", "user", "repoos"],
+            set: () => [
+                "secret-tool",
+                "store",
+                "--label=RepoOS Cloudflare API token",
+                "service",
+                "repoos:cloudflare-token",
+                "user",
+                "repoos",
+            ],
+        };
+    }
+    return null;
+}
+function getStoredToken() {
+    const cmds = tokenStoreCmds();
+    if (!cmds)
+        return null;
+    try {
+        const out = execFileSync(cmds.get[0], cmds.get.slice(1), { encoding: "utf8", timeout: 10_000 });
+        return out.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+function storeToken(token) {
+    const cmds = tokenStoreCmds();
+    if (!cmds)
+        return false;
+    try {
+        execFileSync(cmds.set(token)[0], cmds.set(token).slice(1), {
+            input: token,
+            encoding: "utf8",
+            timeout: 10_000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveApiToken() {
+    if (process.env.CLOUDFLARE_API_TOKEN)
+        return process.env.CLOUDFLARE_API_TOKEN;
+    const stored = getStoredToken();
+    if (stored)
+        return stored;
+    const entered = await prompt("  Cloudflare API token (needs `Access: Apps and Policies` + `DNS` + `Cloudflare Tunnel` edit permissions, blank to skip): ");
+    if (entered)
+        storeToken(entered);
+    return entered || null;
+}
+// ── Cloudflare API ───────────────────────────────────────────────────────────
+async function cfFetch(token, path, method = "GET", body) {
+    let res;
+    try {
+        const init = {
+            method,
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+            signal: AbortSignal.timeout(15_000),
+        };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        res = await fetch(CF_API + path, init);
+    }
+    catch (e) {
+        throw new Error("Cloudflare API unreachable: " + e.message);
+    }
+    const text = await res.text();
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        json = { success: false, errors: [{ message: `HTTP ${res.status}: ${text.slice(0, 160)}` }] };
+    }
+    if (json.success !== true) {
+        const errors = Array.isArray(json.errors) ? json.errors : [];
+        const detail = errors
+            .map((e) => e.message ?? "")
+            .filter(Boolean)
+            .join("; ");
+        throw new Error(`Cloudflare API error (${res.status}): ${detail || "request failed"}`);
+    }
+    return json;
+}
+async function resolveAccountId(token, bin) {
+    if (bin) {
+        for (const row of cloudflaredList(bin)) {
+            if (row.accountTag)
+                return row.accountTag;
+        }
+    }
+    try {
+        const json = await cfFetch(token, "/accounts?per_page=50", "GET");
+        const result = json.result;
+        if (Array.isArray(result) && result.length) {
+            return String(result[0].id ?? "");
+        }
+    }
+    catch {
+        // token may not have account:read — caller can prompt for the account id
+    }
+    return null;
+}
+async function findAccessApp(token, accountId, hostname) {
+    const json = await cfFetch(token, `/accounts/${accountId}/access/apps?per_page=100`, "GET");
+    const apps = Array.isArray(json.result)
+        ? json.result
+        : [];
+    return apps.find((a) => a.domain === hostname) ?? null;
+}
+async function findAccessPolicy(token, accountId, appId) {
+    const json = await cfFetch(token, `/accounts/${accountId}/access/apps/${appId}/policies?per_page=100`, "GET");
+    const policies = Array.isArray(json.result)
+        ? json.result
+        : [];
+    return policies.find((p) => p.name === ACCESS_POLICY_NAME) ?? null;
+}
+/**
+ * Reconcile the Cloudflare Access application + allowlist policy for a
+ * hostname: create or reuse the self-hosted app, then create or update the
+ * single "repoos allowlist" policy with exactly the configured emails.
+ */
+async function reconcileAccessPolicy(token, accountId, hostname, emails) {
+    let app = await findAccessApp(token, accountId, hostname);
+    if (!app) {
+        const created = await cfFetch(token, `/accounts/${accountId}/access/apps`, "POST", buildAccessAppBody(hostname));
+        app = created.result;
+    }
+    const appId = String(app.id ?? "");
+    if (!appId)
+        throw new Error("created Access app has no id");
+    const body = buildAccessPolicyBody(emails);
+    const existing = await findAccessPolicy(token, accountId, appId);
+    if (existing && existing.id) {
+        await cfFetch(token, `/accounts/${accountId}/access/apps/${appId}/policies/${existing.id}`, "PUT", body);
+    }
+    else {
+        await cfFetch(token, `/accounts/${accountId}/access/apps/${appId}/policies`, "POST", body);
+    }
+}
+/** Resolve the API token + account id required to manage Access for an app. */
+async function accessClient() {
+    const token = await resolveApiToken();
+    if (!token) {
+        fail("No Cloudflare API token found. Set CLOUDFLARE_API_TOKEN or store one via `repoos tunnel setup` — it is required to create the Access policy that protects your app from public access.");
+    }
+    let bin = null;
+    try {
+        bin = cloudflaredBin();
+    }
+    catch {
+        bin = null;
+    }
+    let accountId = await resolveAccountId(token, bin);
+    if (!accountId) {
+        const entered = await prompt("  Cloudflare account ID (not auto-detectable with this token): ");
+        if (entered)
+            accountId = entered;
+    }
+    if (!accountId)
+        fail("Could not determine your Cloudflare account ID — check the API token permissions.");
+    return { token, accountId };
+}
+// ── Subcommands ──────────────────────────────────────────────────────────────
+async function cmdTunnelSetup(_args) {
+    let bin = resolveBinary("cloudflared", process.env.PATH ?? "");
+    if (!bin) {
+        console.log(c.bold(c.cyan("\n  RepoOS Tunnel · cloudflared is not installed")));
+        if (await confirm("  Install cloudflared now?")) {
+            const ok = await installCloudflared();
+            if (!ok) {
+                fail("cloudflared install failed — install it manually (see the downloads page) and re-run `repoos tunnel setup`.");
+            }
+            bin = resolveBinary("cloudflared", process.env.PATH ?? "");
+        }
+        else {
+            console.log(c.dim("  Install it yourself, then re-run `repoos tunnel setup`."));
+            return;
+        }
+        if (!bin) {
+            fail("cloudflared is not on PATH yet — open a new shell and re-run `repoos tunnel setup`.");
+        }
+    }
+    const cfg = loadConfig();
+    // 1. Authenticate cloudflared (idempotent — cert.pem persists).
+    const certPem = join(cloudflaredHomeDir(), "cert.pem");
+    if (existsSync(certPem)) {
+        console.log(c.dim("  ✔ cloudflared is already logged in") + c.dim(` (${certPem})`));
+    }
+    else {
+        console.log(c.bold("\n  Sign in to Cloudflare: ") +
+            c.dim("a browser window will open — authorize the account and zones you want to publish under."));
+        let code;
+        try {
+            code = await runInteractive(bin, ["tunnel", "login"]);
+        }
+        catch (e) {
+            fail("failed to launch `cloudflared tunnel login`: " + e.message);
+        }
+        if (code !== 0)
+            fail("`cloudflared tunnel login` did not complete — re-run `repoos tunnel setup`.");
+    }
+    // 2. Cloudflare API token (for Access + DNS reconciliation) — stored in the
+    //    OS keychain / secret storage, never in the repo.
+    const existingToken = await resolveApiToken();
+    if (existingToken) {
+        console.log(c.dim("  ✔ Cloudflare API token " +
+            (process.env.CLOUDFLARE_API_TOKEN
+                ? "(from CLOUDFLARE_API_TOKEN)"
+                : "(stored in keychain)")));
+    }
+    // 3. Create or reuse one tunnel per machine.
+    const tunnel = readTunnelConfig(cfg.root);
+    const tunnels = cloudflaredList(bin);
+    // Brand-new setup (no tunnel recorded in this repo yet): default to a
+    // machine-identifiable name — `repoos-<hostname>` — instead of the legacy
+    // generic `repoos-local`, so it's recognizable in the Cloudflare dashboard
+    // and every repo on this machine converges on the same shared tunnel. If a
+    // `repoos-local` tunnel already exists on the account, keep using it rather
+    // than stranding it beside a new name. An existing setup (tunnelId already
+    // recorded) always keeps whatever name it has.
+    if (!tunnel.tunnelId && (!tunnel.name || tunnel.name === DEFAULT_TUNNEL_NAME)) {
+        const hasLegacy = tunnels.some((t) => t.name === DEFAULT_TUNNEL_NAME);
+        tunnel.name = hasLegacy ? DEFAULT_TUNNEL_NAME : defaultTunnelName();
+    }
+    let tunnelId = tunnel.tunnelId;
+    const byName = tunnels.find((t) => t.name === tunnel.name);
+    const byId = tunnelId ? tunnels.some((t) => t.id === tunnelId) : false;
+    if (byName) {
+        tunnelId = byName.id;
+        console.log(c.dim("  ✔ reusing existing tunnel ") + c.cyan(tunnel.name) + c.dim(` (${byName.id})`));
+    }
+    else if (byId) {
+        console.log(c.dim("  ✔ tunnel already registered ") + c.cyan(tunnel.name) + c.dim(` (${tunnelId})`));
+    }
+    else {
+        console.log(c.bold(`\n  Creating tunnel `) + c.cyan(tunnel.name) + c.dim(" …"));
+        let code;
+        try {
+            code = await runInteractive(bin, ["tunnel", "create", tunnel.name]);
+        }
+        catch (e) {
+            fail("failed to run `cloudflared tunnel create`: " + e.message);
+        }
+        if (code !== 0)
+            fail("`cloudflared tunnel create` failed.");
+        const created = cloudflaredList(bin).find((t) => t.name === tunnel.name);
+        if (!created)
+            fail("Tunnel created but not found in `cloudflared tunnel list`.");
+        tunnelId = created.id;
+    }
+    // 4. Base domain for hostname inference.
+    let domain = tunnel.domain;
+    if (!domain) {
+        for (;;) {
+            const entered = await prompt("  Base domain for publishing (e.g. repoos.org, blank to skip): ");
+            if (!entered || isValidBaseDomain(entered)) {
+                domain = entered;
+                break;
+            }
+            console.log(c.yellow(`  "${entered}" doesn't look like a domain (need at least one dot, e.g. repoos.org) — try again, or leave blank to skip.`));
+        }
+    }
+    tunnel.name = tunnel.name || DEFAULT_TUNNEL_NAME;
+    tunnel.domain = domain;
+    tunnel.tunnelId = tunnelId;
+    writeTunnelConfig(cfg.root, tunnel);
+    console.log("\n  " + c.green("✔ Tunnel configured."));
+    console.log(c.dim("  tunnel:  ") + c.cyan(tunnel.name) + c.dim(`  (${tunnelId})`));
+    if (tunnel.domain)
+        console.log(c.dim("  domain:  ") + c.cyan(tunnel.domain));
+    console.log(c.dim("  publish: ") +
+        c.cyan("repoos tunnel create <name> --port <port> --allow alice@example.com"));
+}
+async function cmdTunnelCreate(args) {
+    const { positionals, flags } = parseArgs(args);
+    const name = positionals[0];
+    if (!name) {
+        fail("Usage: repoos tunnel create <name> --port <port> [--domain <hostname>] [--allow <emails>] [--no-access]");
+    }
+    if (!isValidAppName(name))
+        fail(`Invalid app name "${name}" — use letters, digits, hyphens and underscores only.`);
+    const cfg = loadConfig();
+    const tunnel = readTunnelConfig(cfg.root);
+    if (!tunnel.tunnelId)
+        fail("Tunnel not set up yet — run `repoos tunnel setup` first.");
+    // Peek the registry (read-only — the real seed/sync/write happens later,
+    // right before this app is actually persisted) so both a plain name clash
+    // and a pre-existing cross-repo collision fail fast, before any DNS/Access
+    // API calls, with a message that tells the truth about which one it is.
+    const registryPeek = readRegistry();
+    const earlyConflict = reconcileIdentity(registryPeek, tunnel);
+    if (earlyConflict)
+        fail(earlyConflict);
+    const elsewhere = registryPeek.apps[name];
+    const collision = !!elsewhere && !!elsewhere.ownerRoot && elsewhere.ownerRoot !== cfg.root;
+    if (tunnel.apps[name]) {
+        if (collision) {
+            fail(`App "${name}" exists in this repo's repoos.toml AND is already published by a ` +
+                `different repo on this machine (${elsewhere.ownerRoot}) — app names are shared ` +
+                `machine-wide. This looks like a naming collision from before the machine registry ` +
+                `existed; rename one of them (destroy and re-create it under a new name, here or there).`);
+        }
+        fail(`App "${name}" already exists — use \`repoos tunnel allow/deny\` to manage its allowlist.`);
+    }
+    if (collision) {
+        fail(`App "${name}" is already published by another repo on this machine (${elsewhere.ownerRoot}) — app names are shared machine-wide. Pick a different name.`);
+    }
+    const port = flags.get("port");
+    if (!port || !/^\d+$/.test(port))
+        fail("--port is required and must be a number.");
+    const portNum = Number(port);
+    if (portNum < 1 || portNum > 65535)
+        fail("--port must be between 1 and 65535.");
+    let hostname = flags.get("domain") ?? "";
+    if (!hostname) {
+        if (!tunnel.domain) {
+            fail("No base domain configured and no --domain given — run `repoos tunnel setup` or pass --domain.");
+        }
+        hostname = inferHostname(name, tunnel.domain);
+    }
+    if (hostname.includes("://") || hostname.includes("/"))
+        fail(`Invalid hostname "${hostname}".`);
+    // --no-access skips Cloudflare Access entirely: the app is fully public at
+    // Cloudflare's edge, relying solely on RepoOS's own native auth to reject
+    // unauthenticated requests. That's only safe if native auth is actually on
+    // — refuse otherwise rather than silently publish an unprotected app.
+    const noAccess = flags.has("no-access");
+    if (noAccess && flags.has("allow")) {
+        fail("--no-access and --allow are mutually exclusive — --no-access means there is no Access allowlist to configure.");
+    }
+    if (noAccess && cfg.auth?.enabled !== true) {
+        fail("--no-access requires RepoOS native auth to be on first (auth.enabled = true in repoos.toml) — " +
+            "without it OR Cloudflare Access, the app would be fully public with no login at all. See docs/native-auth.md.");
+    }
+    const emails = noAccess ? [] : parseEmailList(flags.get("allow"));
+    for (const email of emails) {
+        if (!isValidEmail(email))
+            fail(`Invalid email address "${email}".`);
+    }
+    const warn = hostnameWarning(hostname, tunnel.domain);
+    if (warn)
+        console.log(c.yellow("  ⚠ " + warn));
+    const bin = cloudflaredBin();
+    const creds = tunnelCredentialsPath(tunnel.tunnelId);
+    if (!existsSync(creds)) {
+        const known = cloudflaredList(bin).some((t) => t.id === tunnel.tunnelId);
+        if (!known)
+            fail(`Tunnel ${tunnel.name} is not in this Cloudflare account — re-run \`repoos tunnel setup\`.`);
+    }
+    // Resolve Access credentials BEFORE mutating config so a missing token can't
+    // leave a half-configured (unprotected) app behind. Skipped entirely for
+    // --no-access, which never touches Access at all.
+    const accessCreds = noAccess ? null : await accessClient();
+    tunnel.apps[name] = {
+        hostname,
+        // 127.0.0.1, not "localhost": when `repoos serve` binds 0.0.0.0 (which it
+        // does whenever Tailscale is detected) it listens on IPv4 only, but
+        // "localhost" resolves to ::1 first on a dual-stack host — cloudflared then
+        // dials [::1]:<port> and gets connection-refused even though the origin is
+        // up. An explicit IPv4 loopback always reaches a 0.0.0.0/127.0.0.1 bind.
+        service: `http://127.0.0.1:${portNum}`,
+        access: emails,
+        noAccess,
+    };
+    writeTunnelConfig(cfg.root, tunnel);
+    const registry = mutateRegistry(cfg.root, tunnel, (registry) => {
+        upsertApp(registry, name, tunnel.apps[name], cfg.root);
+    });
+    console.log(c.green("  ✔ configured ") +
+        c.cyan(name) +
+        c.dim(` → `) +
+        hostname +
+        c.dim(` → http://localhost:${portNum}`));
+    try {
+        console.log(c.dim("  · routing DNS ") + hostname + c.dim(" …"));
+        execFileSync(bin, ["tunnel", "route", "dns", "--overwrite-dns", tunnel.name, hostname], {
+            stdio: "inherit",
+            timeout: 60_000,
+        });
+    }
+    catch {
+        console.log(c.yellow("  ⚠ DNS routing failed — authorize the zone in `cloudflared tunnel login`, then run:") +
+            "\n    " +
+            c.cyan(`cloudflared tunnel route dns --overwrite-dns ${tunnel.name} ${hostname}`));
+    }
+    const derived = writeDerivedConfig(tunnel, unionApps(registry));
+    console.log(c.dim("  · wrote ingress config → ") + derived);
+    if (accessCreds) {
+        await reconcileAccessPolicy(accessCreds.token, accessCreds.accountId, hostname, emails);
+        console.log(c.green("  ✔ Access policy updated — ") +
+            (emails.length ? emails.join(", ") : "deny all (no emails yet)"));
+    }
+    else {
+        console.log(c.yellow("  ⚠ No Cloudflare Access policy — this app is fully public at the edge. RepoOS native auth is its only gate."));
+    }
+    console.log("\n  " + c.green("✔ App published."));
+    console.log(c.dim("  URL:     ") + c.cyan("https://" + hostname));
+    if (noAccess) {
+        console.log(c.dim("  access:  ") + c.yellow("none (--no-access) — native auth only"));
+    }
+    else if (!emails.length) {
+        console.log(c.dim("  allow:   ") +
+            c.yellow("nobody yet — `repoos tunnel allow " + name + " <email>`") +
+            c.dim(" to let someone in"));
+    }
+    else {
+        console.log(c.dim("  allow:   ") + emails.join(", "));
+    }
+    console.log(c.dim("  run:     ") +
+        c.cyan("repoos tunnel start") +
+        c.dim("  ·  server: ") +
+        c.cyan("repoos tunnel install"));
+}
+/** Delete an app's Cloudflare Access app + policy, if it has one. Shared by both `destroy` paths. */
+async function deleteAccessAppFor(app) {
+    if (app.noAccess)
+        return;
+    try {
+        const { token, accountId } = await accessClient();
+        const existing = await findAccessApp(token, accountId, app.hostname);
+        if (existing?.id) {
+            await cfFetch(token, `/accounts/${accountId}/access/apps/${existing.id}`, "DELETE");
+            console.log(c.green("  ✔ deleted Cloudflare Access app for ") + c.cyan(app.hostname));
+        }
+        else {
+            console.log(c.dim("  · no Cloudflare Access app found for ") +
+                app.hostname +
+                c.dim(" — nothing to delete there."));
+        }
+    }
+    catch (e) {
+        console.log(c.yellow(`  ⚠ Failed to delete the Access app: ${e.message}`));
+        console.log(c.dim("    Continuing to remove it from repoos.toml anyway — clean up the stale Access app in the Cloudflare dashboard if needed."));
+    }
+}
+/**
+ * `destroy` for a name that isn't in THIS repo's own repoos.toml at all: the
+ * only legitimate reason to reach here is a registry entry whose owning
+ * checkout has been deleted (stale) — the normal path needs that repo's own
+ * toml to remove the app from, which no longer exists. Without this, a
+ * stale entry could only ever be cleared by hand-editing the registry file,
+ * despite its own header saying not to. A checkout that's still on disk is
+ * never touched from here — that repo is the only place its app can be
+ * destroyed from.
+ */
+async function destroyStaleRegistryApp(root, name) {
+    const registry = readRegistry();
+    const entry = registry.apps[name];
+    if (!entry)
+        fail(`No app named "${name}" — see \`repoos tunnel list\`.`);
+    if (existsSync(entry.ownerRoot)) {
+        fail(`"${name}" isn't in this repo's repoos.toml — it's owned by another repo checkout still ` +
+            `on disk (${entry.ownerRoot}). Run \`repoos tunnel destroy ${name}\` from there.`);
+    }
+    const localTunnel = readTunnelConfig(root);
+    const tunnelId = localTunnel.tunnelId || registry.tunnelId;
+    if (!tunnelId)
+        fail("Tunnel not set up yet — run `repoos tunnel setup` first.");
+    if (!(await confirm(`  Destroy stale registry entry "${name}" (${entry.hostname})? Its owning repo checkout ` +
+        `(${entry.ownerRoot}) no longer exists on disk, so this only removes it from the ` +
+        `machine registry — there is no repoos.toml left to remove it from.`, false))) {
+        console.log(c.dim("  cancelled."));
+        return;
+    }
+    await deleteAccessAppFor(entry);
+    const registryAfter = withRegistryLock(registryPath(), () => {
+        const reg = readRegistry();
+        removeApp(reg, name);
+        writeRegistry(reg);
+        return reg;
+    });
+    const renderTunnel = {
+        ...localTunnel,
+        tunnelId,
+        name: localTunnel.name || registryAfter.tunnelName || DEFAULT_TUNNEL_NAME,
+        domain: localTunnel.domain || registryAfter.domain,
+    };
+    const derived = writeDerivedConfig(renderTunnel, unionApps(registryAfter));
+    console.log(c.green(`  ✔ removed stale "${name}" from the machine tunnel registry`) +
+        c.dim(" · ingress config rewritten → " + derived));
+    console.log(c.dim("  DNS record for ") +
+        entry.hostname +
+        c.dim(" was left as-is — delete it in the Cloudflare dashboard if you don't plan to recreate this app."));
+}
+/**
+ * Remove a published app: deletes its Cloudflare Access app + policy (if it
+ * has one), drops it from repoos.toml, and rewrites the ingress config. The
+ * DNS CNAME is left alone — it's harmless to leave pointed at the tunnel
+ * (matches nothing once the ingress route is gone → falls through to the
+ * 404 catch-all), and re-creating the app under the same hostname later
+ * needs it to still exist anyway.
+ */
+async function cmdTunnelDestroy(args) {
+    const [name] = args;
+    if (!name)
+        fail("Usage: repoos tunnel destroy <name>");
+    const cfg = loadConfig();
+    const tunnel = readTunnelConfig(cfg.root);
+    const app = tunnel.apps[name];
+    if (!app) {
+        await destroyStaleRegistryApp(cfg.root, name);
+        return;
+    }
+    if (!(await confirm(`  Destroy "${name}" (${app.hostname})? This removes its Cloudflare Access policy and RepoOS's record of it.`, false))) {
+        console.log(c.dim("  cancelled."));
+        return;
+    }
+    await deleteAccessAppFor(app);
+    delete tunnel.apps[name];
+    writeTunnelConfig(cfg.root, tunnel);
+    const registry = mutateRegistry(cfg.root, tunnel, (registry) => removeApp(registry, name));
+    const derived = writeDerivedConfig(tunnel, unionApps(registry));
+    console.log(c.green(`  ✔ removed "${name}" from repoos.toml and the machine tunnel registry`) +
+        c.dim(" · ingress config rewritten → " + derived));
+    console.log(c.dim("  DNS record for ") +
+        app.hostname +
+        c.dim(" was left as-is — delete it in the Cloudflare dashboard if you don't plan to recreate this app."));
+    console.log(c.dim("  Restart `repoos tunnel start`/reinstall the service to pick up the ingress change."));
+}
+/**
+ * Rename the machine's tunnel (e.g. the legacy `repoos-local` → `repoos-bee`).
+ *
+ * There is no `cloudflared tunnel rename` subcommand (never has been), so this
+ * goes straight to the Cloudflare API — `PATCH /accounts/:id/cfd_tunnel/:uuid`
+ * with the new name — then updates `[tunnel].name` in repoos.toml and the
+ * machine registry.
+ *
+ * Nothing else needs to move: the running connector routes by UUID, the
+ * `<uuid>.cfargotunnel.com` DNS targets are UUID-based, and Access policies key
+ * off hostname. So the rename is a pure label change — no restart, no DNS
+ * re-pointing, no traffic interruption.
+ */
+async function cmdTunnelRename(args) {
+    const [newName] = args;
+    if (!newName)
+        fail("Usage: repoos tunnel rename <new-name>");
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(newName)) {
+        fail(`Invalid tunnel name "${newName}" — start with a letter or digit; letters, digits, dots, hyphens and underscores only.`);
+    }
+    const cfg = loadConfig();
+    const tunnel = readTunnelConfig(cfg.root);
+    if (!tunnel.tunnelId)
+        fail("Tunnel not set up yet — run `repoos tunnel setup` first.");
+    if (tunnel.name === newName) {
+        console.log(c.dim(`  Tunnel is already named "${newName}" — nothing to do.`));
+        return;
+    }
+    // Fail fast before touching Cloudflare — the persisted repoos.toml + registry
+    // update happens after the API call, below, in one locked read-modify-write.
+    const earlyConflict = reconcileIdentity(readRegistry(), tunnel);
+    if (earlyConflict)
+        fail(earlyConflict);
+    const oldName = tunnel.name || "(unnamed)";
+    const { token, accountId } = await accessClient();
+    try {
+        await cfFetch(token, `/accounts/${accountId}/cfd_tunnel/${tunnel.tunnelId}`, "PATCH", {
+            name: newName,
+        });
+    }
+    catch (e) {
+        fail(`Cloudflare rejected the rename: ${e.message}\n` +
+            `  The API token needs Account / Cloudflare Tunnel / Edit.`);
+    }
+    tunnel.name = newName;
+    writeTunnelConfig(cfg.root, tunnel);
+    const registry = mutateRegistry(cfg.root, tunnel, (registry) => {
+        registry.tunnelName = newName;
+    });
+    writeDerivedConfig(tunnel, unionApps(registry));
+    console.log(c.green("  ✔ renamed ") + c.cyan(oldName) + c.dim(" → ") + c.cyan(newName));
+    console.log("  " +
+        c.green("✔ Tunnel renamed.") +
+        c.dim(" The connector routes by UUID (unchanged), so no restart is needed and traffic is not interrupted."));
+}
+async function cmdTunnelAllow(args) {
+    await mutateAllowlist("allow", args);
+}
+async function cmdTunnelDeny(args) {
+    await mutateAllowlist("deny", args);
+}
+async function mutateAllowlist(op, args) {
+    const [name, email] = args;
+    if (!name || !email)
+        fail(`Usage: repoos tunnel ${op} <name> <email>`);
+    if (!isValidEmail(email))
+        fail(`Invalid email address "${email}".`);
+    const cfg = loadConfig();
+    const tunnel = readTunnelConfig(cfg.root);
+    const app = tunnel.apps[name];
+    if (!app)
+        fail(`No app named "${name}" — see \`repoos tunnel list\`.`);
+    if (app.noAccess) {
+        fail(`"${name}" was created with --no-access — there is no Access allowlist to manage. It relies on RepoOS native auth only.`);
+    }
+    const next = op === "allow" ? addEmail(app.access, email) : removeEmail(app.access, email);
+    if (next.length === app.access.length) {
+        console.log(c.dim(`  ${email} is already ${op === "allow" ? "allowed" : "not on the allowlist"} for ${name} — no change.`));
+        return;
+    }
+    app.access = next;
+    writeTunnelConfig(cfg.root, tunnel);
+    // Same conflict gate + seed/sync as every other mutating subcommand — this
+    // used to bypass the conflict check entirely and silently drop the change
+    // on an unseeded registry instead of keeping it in sync with repoos.toml.
+    mutateRegistry(cfg.root, tunnel);
+    console.log(c.green(`  ✔ ${op === "allow" ? "allowed" : "denied"} `) +
+        c.cyan(email) +
+        c.dim(` on ${name} (${next.length} on allowlist)`));
+    const { token, accountId } = await accessClient();
+    await reconcileAccessPolicy(token, accountId, app.hostname, app.access);
+    console.log(c.green("  ✔ Access policy reconciled for ") + c.cyan(app.hostname));
+}
+async function cmdTunnelStart(_args) {
+    const cfg = loadConfig();
+    const tunnel = readTunnelConfig(cfg.root);
+    if (!tunnel.tunnelId)
+        fail("Tunnel not set up yet — run `repoos tunnel setup` first.");
+    const registry = mutateRegistry(cfg.root, tunnel);
+    const apps = unionApps(registry);
+    if (Object.keys(apps).length === 0) {
+        console.log(c.yellow("  ⚠ no apps configured on this machine — the tunnel will serve 404s until you `repoos tunnel create` one."));
+    }
+    const bin = cloudflaredBin();
+    const configPath = writeDerivedConfig(tunnel, apps);
+    console.log(c.dim("  · running cloudflared in the foreground (Ctrl-C to stop)…\n"));
+    let code;
+    try {
+        code = await runInteractive(bin, ["tunnel", "--config", configPath, "run", tunnel.tunnelId]);
+    }
+    catch (e) {
+        fail("failed to start cloudflared: " + e.message);
+    }
+    process.exitCode = code;
+}
+async function cmdTunnelInstall(_args) {
+    const cfg = loadConfig();
+    const tunnel = readTunnelConfig(cfg.root);
+    if (!tunnel.tunnelId)
+        fail("Tunnel not set up yet — run `repoos tunnel setup` first.");
+    const registry = mutateRegistry(cfg.root, tunnel);
+    const apps = unionApps(registry);
+    if (Object.keys(apps).length === 0) {
+        console.log(c.yellow("  ⚠ no apps configured yet on this machine — the service will start but serve 404s. `repoos tunnel create` one first."));
+    }
+    const bin = cloudflaredBin();
+    writeDerivedConfig(tunnel, apps);
+    const userConfig = writeUserCloudflaredConfig(tunnel, apps);
+    if (process.platform === "darwin") {
+        let code;
+        try {
+            code = await runInteractive(bin, ["service", "install"]);
+        }
+        catch (e) {
+            fail("failed to run `cloudflared service install`: " + e.message);
+        }
+        if (code !== 0)
+            fail("`cloudflared service install` failed — see output above.");
+        try {
+            execFileSync("launchctl", ["start", "com.cloudflare.cloudflared"], {
+                stdio: "inherit",
+                timeout: 15_000,
+            });
+        }
+        catch {
+            // already started by the installer
+        }
+        console.log(c.green("  ✔ installed as a launch agent — the tunnel starts when you log in."));
+    }
+    else if (process.platform === "linux") {
+        const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+        const run = (argv) => isRoot ? runInteractive(argv[0], argv.slice(1)) : runInteractive("sudo", argv);
+        // `cloudflared service install` aborts on any prior install — a leftover
+        // /etc/systemd/system/cloudflared.service unit ("service is already
+        // installed"), or, because its own Linux installer copies the config into
+        // /etc/cloudflared, a stale /etc/cloudflared/config.yml alongside
+        // ~/.cloudflared/config.yml ("possible conflicting configuration"). So the
+        // first `repoos tunnel install` worked and every re-run failed on what the
+        // first one left behind. Tear down any prior install first — best-effort,
+        // a missing one is fine — so re-running is idempotent.
+        if (existsSync("/etc/systemd/system/cloudflared.service") ||
+            existsSync("/etc/cloudflared/config.yml")) {
+            console.log(c.dim("  · clearing a previous cloudflared service install…"));
+            await run([bin, "service", "uninstall"]).catch(() => 0);
+            await run(["rm", "-rf", "/etc/cloudflared"]).catch(() => 0);
+            await run(["systemctl", "daemon-reload"]).catch(() => 0);
+        }
+        console.log(c.dim("  · installing cloudflared as a systemd service (may prompt for your password)…"));
+        let code;
+        try {
+            code = await run([bin, "--config", userConfig, "service", "install"]);
+        }
+        catch (e) {
+            fail("failed to run cloudflared service install: " + e.message);
+        }
+        if (code !== 0) {
+            fail(`\`cloudflared service install\` failed. Try it manually:\n    sudo cloudflared --config ${userConfig} service install`);
+        }
+        try {
+            execFileSync("systemctl", ["start", "cloudflared"], { stdio: "inherit", timeout: 15_000 });
+        }
+        catch {
+            // installer already started it
+        }
+        console.log(c.green("  ✔ installed as a systemd service — the tunnel survives reboots."));
+    }
+    else {
+        fail("Persistent service install is only supported on macOS and Linux.");
+    }
+}
+async function cmdTunnelStop(_args) {
+    const bin = resolveBinary("cloudflared", process.env.PATH ?? "");
+    let stoppedService = false;
+    if (process.platform === "darwin") {
+        try {
+            execFileSync("launchctl", ["stop", "com.cloudflare.cloudflared"], {
+                stdio: "inherit",
+                timeout: 15_000,
+            });
+            stoppedService = true;
+        }
+        catch {
+            console.log(c.yellow("  ⚠ launchctl stop failed — try `sudo launchctl stop com.cloudflare.cloudflared`"));
+        }
+    }
+    else if (process.platform === "linux") {
+        try {
+            execFileSync("systemctl", ["stop", "cloudflared"], { stdio: "inherit", timeout: 15_000 });
+            stoppedService = true;
+        }
+        catch {
+            console.log(c.yellow("  ⚠ systemctl stop failed — try `sudo systemctl stop cloudflared`"));
+        }
+    }
+    if (bin) {
+        try {
+            execFileSync("pkill", ["-f", "cloudflared.*tunnel.*run"], { timeout: 5_000 });
+            stoppedService = true;
+        }
+        catch {
+            // no foreground process was running
+        }
+    }
+    console.log(stoppedService ? c.green("  ✔ tunnel stopped.") : c.dim("  No running tunnel process to stop."));
+}
+/**
+ * `repoos tunnel list` is a MACHINE view, not a per-repo one: it shows every
+ * app any repo on this box has published (via the registry), each annotated
+ * with which repo owns it and whether that owner checkout is still on disk.
+ */
+function cmdTunnelList(_args) {
+    const cfg = loadConfig();
+    const tunnel = readTunnelConfig(cfg.root);
+    const { registry, conflict } = readRegistryForDisplay(cfg.root, tunnel);
+    const tunnelId = registry.tunnelId || tunnel.tunnelId;
+    if (!tunnelId) {
+        console.log(c.dim("  No tunnel configured yet — run `repoos tunnel setup`."));
+        return;
+    }
+    console.log(c.bold("\n  " + c.cyan(registry.tunnelName || tunnel.name)) + c.dim(`  (${tunnelId})`));
+    const domain = registry.domain || tunnel.domain;
+    if (domain)
+        console.log(c.dim("  base domain:  ") + domain);
+    if (conflict)
+        console.log(c.yellow("  ⚠ " + conflict));
+    const rows = annotateStale(registry);
+    if (!rows.length) {
+        console.log(c.dim("  No apps published yet on this machine — `repoos tunnel create <name> --port 3000 --allow alice@example.com`\n"));
+        return;
+    }
+    for (const { name, app, stale } of rows) {
+        console.log("\n  " + c.cyan(name) + (app.ownerRoot === cfg.root ? c.dim("  (this repo)") : ""));
+        console.log("    " + c.dim("hostname: ") + app.hostname);
+        console.log("    " + c.dim("service:  ") + app.service);
+        console.log("    " +
+            c.dim("owner:    ") +
+            (app.ownerRoot || c.dim("(unknown)")) +
+            (stale ? c.yellow("  [stale — checkout missing]") : ""));
+        console.log("    " +
+            c.dim("allow:    ") +
+            (app.noAccess
+                ? c.yellow("none (--no-access) — native auth only")
+                : app.access.length
+                    ? app.access.join(", ")
+                    : c.yellow("(none — deny all)")));
+    }
+    console.log("");
+}
+async function cmdTunnelStatus(_args) {
+    const cfg = loadConfig();
+    const tunnel = readTunnelConfig(cfg.root);
+    const { registry, conflict } = readRegistryForDisplay(cfg.root, tunnel);
+    const bin = resolveBinary("cloudflared", process.env.PATH ?? "");
+    const rows = [];
+    rows.push(["cloudflared", bin ? c.green("installed") : c.red("not installed")]);
+    const tunnelId = registry.tunnelId || tunnel.tunnelId;
+    if (!tunnelId) {
+        rows.push(["tunnel", c.yellow("not configured — run `repoos tunnel setup`")]);
+    }
+    else {
+        rows.push(["tunnel", c.cyan(registry.tunnelName || tunnel.name) + c.dim(` (${tunnelId})`)]);
+        if (conflict)
+            rows.push(["tunnel conflict", c.red(conflict)]);
+        let serviceInstalled = false;
+        let serviceActive = false;
+        if (process.platform === "darwin") {
+            try {
+                const out = execFileSync("launchctl", ["list"], { encoding: "utf8", timeout: 10_000 });
+                const line = out.split("\n").find((l) => l.includes("com.cloudflare.cloudflared"));
+                if (line) {
+                    serviceInstalled = true;
+                    serviceActive = /^\s*\d+\s+/.test(line); // PID column is a number when running
+                }
+            }
+            catch {
+                // launchctl unavailable
+            }
+        }
+        else if (process.platform === "linux") {
+            try {
+                const out = execFileSync("systemctl", ["is-active", "cloudflared"], {
+                    encoding: "utf8",
+                    timeout: 10_000,
+                }).trim();
+                serviceInstalled = out !== "inactive" && out !== "unknown" && out !== "";
+                serviceActive = out === "active";
+            }
+            catch {
+                // systemd unavailable
+            }
+        }
+        let devRunning = false;
+        try {
+            const out = execFileSync("pgrep", ["-f", "cloudflared.*tunnel.*run"], {
+                encoding: "utf8",
+                timeout: 10_000,
+            });
+            devRunning = out.trim() !== "";
+        }
+        catch {
+            // no dev process
+        }
+        rows.push([
+            "service",
+            serviceInstalled
+                ? serviceActive
+                    ? "installed + running"
+                    : "installed (stopped)"
+                : "not installed",
+        ]);
+        rows.push(["running", devRunning || serviceActive ? c.green("yes") : c.red("no")]);
+        const appRows = annotateStale(registry);
+        if (appRows.length) {
+            console.log(c.dim("  per-app health (machine-wide)"));
+            // Each app needs an origin-port probe (up to 800ms) and a hostname
+            // fetch (up to 8s) — for several apps, doing those serially one app at
+            // a time can take tens of seconds. Run every app's pair of probes
+            // concurrently instead; `Promise.all` preserves `appRows`' order.
+            const healthRows = await Promise.all(appRows.map(async ({ name, app, stale }) => {
+                const port = originPort(app.service);
+                const [originUp, status] = await Promise.all([
+                    port !== null ? portListening(port) : Promise.resolve(null),
+                    probeApp(app.hostname),
+                ]);
+                const originTag = originUp === null ? "" : originUp ? c.green(" · origin up") : c.red(" · origin down");
+                const ownerTag = app.ownerRoot === cfg.root ? "this repo" : app.ownerRoot || "unknown repo";
+                const staleTag = stale ? c.yellow(" · stale, checkout missing") : "";
+                return [
+                    "  " + name,
+                    `${app.hostname} → ` + status + originTag + staleTag + c.dim(` [${ownerTag}]`),
+                ];
+            }));
+            rows.push(...healthRows);
+        }
+    }
+    const width = Math.max(...rows.map(([k]) => k.length));
+    console.log("\n  " + c.bold("Tunnel status"));
+    for (const [k, v] of rows) {
+        console.log("  " + c.dim(k.padEnd(width)) + "  " + v);
+    }
+    console.log("");
+}
+async function probeApp(hostname) {
+    try {
+        const res = await fetch("https://" + hostname, {
+            method: "HEAD",
+            redirect: "manual",
+            signal: AbortSignal.timeout(8_000),
+        });
+        if (res.status === 301 || res.status === 302 || res.status === 303)
+            return c.yellow(`reachable (redirects to Access)`);
+        if (res.status >= 200 && res.status < 400)
+            return c.green(`healthy (${res.status})`);
+        if ([502, 504, 522, 523].includes(res.status))
+            return c.red(`origin down (${res.status})`);
+        return c.yellow(`responds ${res.status}`);
+    }
+    catch {
+        return c.red("unreachable");
+    }
+}
+function tunnelHelp() {
+    console.log(`
+  ${c.bold(c.cyan("repoos tunnel"))} — publish local apps behind Cloudflare Tunnel + Zero Trust
+
+  A machine runs ONE tunnel shared by every RepoOS repo on it. ${c.cyan("create")}/${c.cyan("destroy")}
+  write to both this repo's repoos.toml and the machine-wide app registry
+  (${c.dim("~/.config/repoos/tunnel-apps.toml")}); ${c.cyan("install")}/${c.cyan("start")}, ${c.cyan("list")} and ${c.cyan("status")} always
+  reflect every app published by any repo, not just this one — see docs/tunnel-registry.md.
+
+  ${c.bold("USAGE")}
+    repoos tunnel <subcommand> [args]
+
+  ${c.bold("SUBCOMMANDS")}
+    ${c.cyan("setup")}                 One-time machine setup: install/check cloudflared, log in, create the tunnel, store the API token
+    ${c.cyan("create")} <name>         Publish a local app  ${c.dim('flags: --port N --domain H --allow "a@x,b@y" | --no-access (requires auth.enabled)')}
+    ${c.cyan("destroy")} <name>        Remove a published app (deletes its Access policy, drops it from repoos.toml + the machine registry)
+    ${c.cyan("rename")} <new-name>     Rename this machine's tunnel in Cloudflare (e.g. repoos-local → repoos-bee) — label only, no restart
+    ${c.cyan("allow")} <name> <email>  Add an email to an app's allowlist
+    ${c.cyan("deny")} <name> <email>   Remove an email from an app's allowlist
+    ${c.cyan("start")}                 Run cloudflared in the foreground (dev), serving every app on the machine
+    ${c.cyan("install")}               Install cloudflared as a persistent service (launchd/systemd), serving every app on the machine
+    ${c.cyan("stop")}                  Stop the running tunnel (service or dev process)
+    ${c.cyan("list")}                  Show every app published on this machine (any repo), hostnames, services, owners and allowlists
+    ${c.cyan("status")}                Tunnel install/running state + per-app health for every app on the machine
+
+  ${c.bold("EXAMPLES")}
+    ${c.dim("$")} repoos tunnel setup
+    ${c.dim("$")} repoos tunnel create dashboard --port 3000 --allow alice@example.com,bob@example.com
+    ${c.dim("$")} repoos tunnel allow dashboard carol@example.com
+    ${c.dim("$")} repoos tunnel start
+`);
+}
+// ── Dispatch ────────────────────────────────────────────────────────────────
+export async function cmdTunnel(args) {
+    const [sub, ...rest] = args;
+    const handlers = {
+        setup: cmdTunnelSetup,
+        create: cmdTunnelCreate,
+        destroy: cmdTunnelDestroy,
+        rename: cmdTunnelRename,
+        allow: cmdTunnelAllow,
+        deny: cmdTunnelDeny,
+        start: cmdTunnelStart,
+        install: cmdTunnelInstall,
+        stop: cmdTunnelStop,
+        list: cmdTunnelList,
+        status: cmdTunnelStatus,
+    };
+    if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+        tunnelHelp();
+        return;
+    }
+    const fn = handlers[sub];
+    if (!fn) {
+        console.error(c.red(`  Unknown tunnel subcommand: ${sub}`));
+        tunnelHelp();
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        await fn(rest);
+    }
+    catch (e) {
+        const err = e;
+        if (!err.repoosTunnel)
+            console.error(c.red("  " + err.message));
+        process.exitCode = 1;
+    }
+}