@poolzin/pool-bot 2026.2.0 → 2026.2.1

package/dist/infra/bonjour-discovery.js

@@ -1,14 +1,15 @@
 import { runCommandWithTimeout } from "../process/exec.js";
-import { WIDE_AREA_DISCOVERY_DOMAIN } from "./widearea-dns.js";
+import { resolveWideAreaDiscoveryDomain } from "./widearea-dns.js";
 const DEFAULT_TIMEOUT_MS = 2000;
-const DEFAULT_DOMAINS = ["local.", WIDE_AREA_DISCOVERY_DOMAIN];
+const GATEWAY_SERVICE_TYPE = "_poolbot-gw._tcp";
 function decodeDnsSdEscapes(value) {
     let decoded = false;
     const bytes = [];
     let pending = "";
     const flush = () => {
-        if (!pending)
+        if (!pending) {
             return;
+        }
         bytes.push(...Buffer.from(pending, "utf8"));
         pending = "";
     };
@@ -31,18 +32,21 @@ function decodeDnsSdEscapes(value) {
         }
         pending += ch;
     }
-    if (!decoded)
+    if (!decoded) {
         return value;
+    }
     flush();
     return Buffer.from(bytes).toString("utf8");
 }
 function isTailnetIPv4(address) {
     const parts = address.split(".");
-    if (parts.length !== 4)
+    if (parts.length !== 4) {
         return false;
+    }
     const octets = parts.map((p) => Number.parseInt(p, 10));
-    if (octets.some((n) => !Number.isFinite(n) || n < 0 || n > 255))
+    if (octets.some((n) => !Number.isFinite(n) || n < 0 || n > 255)) {
         return false;
+    }
     // Tailscale IPv4 range: 100.64.0.0/10
     const [a, b] = octets;
     return a === 100 && b >= 64 && b <= 127;
@@ -59,8 +63,9 @@ function parseDigTxt(stdout) {
     const tokens = [];
     for (const raw of stdout.split("\n")) {
         const line = raw.trim();
-        if (!line)
+        if (!line) {
             continue;
+        }
         const matches = Array.from(line.matchAll(/"([^"]*)"/g), (m) => m[1] ?? "");
         for (const m of matches) {
             const unescaped = m.replaceAll("\\\\", "\\").replaceAll('\\"', '"').replaceAll("\\n", "\n");
@@ -75,35 +80,43 @@ function parseDigSrv(stdout) {
         .split("\n")
         .map((l) => l.trim())
         .find(Boolean);
-    if (!line)
+    if (!line) {
         return null;
+    }
     const parts = line.split(/\s+/).filter(Boolean);
-    if (parts.length < 4)
+    if (parts.length < 4) {
         return null;
+    }
     const port = Number.parseInt(parts[2] ?? "", 10);
     const hostRaw = parts[3] ?? "";
-    if (!Number.isFinite(port) || port <= 0)
+    if (!Number.isFinite(port) || port <= 0) {
         return null;
+    }
     const host = hostRaw.replace(/\.$/, "");
-    if (!host)
+    if (!host) {
         return null;
+    }
     return { host, port };
 }
 function parseTailscaleStatusIPv4s(stdout) {
     const parsed = stdout ? JSON.parse(stdout) : {};
     const out = [];
     const addIps = (value) => {
-        if (!value || typeof value !== "object")
+        if (!value || typeof value !== "object") {
             return;
+        }
         const ips = value.TailscaleIPs;
-        if (!Array.isArray(ips))
+        if (!Array.isArray(ips)) {
             return;
+        }
         for (const ip of ips) {
-            if (typeof ip !== "string")
+            if (typeof ip !== "string") {
                 continue;
+            }
             const trimmed = ip.trim();
-            if (trimmed && isTailnetIPv4(trimmed))
+            if (trimmed && isTailnetIPv4(trimmed)) {
                 out.push(trimmed);
+            }
         }
     };
     addIps(parsed.Self);
@@ -116,8 +129,9 @@ function parseTailscaleStatusIPv4s(stdout) {
     return [...new Set(out)];
 }
 function parseIntOrNull(value) {
-    if (!value)
+    if (!value) {
         return undefined;
+    }
     const parsed = Number.parseInt(value, 10);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
@@ -125,12 +139,14 @@ function parseTxtTokens(tokens) {
     const txt = {};
     for (const token of tokens) {
         const idx = token.indexOf("=");
-        if (idx <= 0)
+        if (idx <= 0) {
             continue;
+        }
         const key = token.slice(0, idx).trim();
         const value = decodeDnsSdEscapes(token.slice(idx + 1).trim());
-        if (!key)
+        if (!key) {
             continue;
+        }
         txt[key] = value;
     }
     return txt;
@@ -139,10 +155,12 @@ function parseDnsSdBrowse(stdout) {
     const instances = new Set();
     for (const raw of stdout.split("\n")) {
         const line = raw.trim();
-        if (!line || !line.includes("_poolbot-gw._tcp"))
+        if (!line || !line.includes(GATEWAY_SERVICE_TYPE)) {
             continue;
-        if (!line.includes("Add"))
+        }
+        if (!line.includes("Add")) {
             continue;
+        }
         const match = line.match(/_poolbot-gw\._tcp\.?\s+(.+)$/);
         if (match?.[1]) {
             instances.add(decodeDnsSdEscapes(match[1].trim()));
@@ -156,8 +174,9 @@ function parseDnsSdResolve(stdout, instanceName) {
     let txt = {};
     for (const raw of stdout.split("\n")) {
         const line = raw.trim();
-        if (!line)
+        if (!line) {
             continue;
+        }
         if (line.includes("can be reached at")) {
             const match = line.match(/can be reached at\s+([^\s:]+):(\d+)/i);
             if (match?.[1]) {
@@ -174,49 +193,59 @@ function parseDnsSdResolve(stdout, instanceName) {
         }
     }
     beacon.txt = Object.keys(txt).length ? txt : undefined;
-    if (txt.displayName)
+    if (txt.displayName) {
         beacon.displayName = decodeDnsSdEscapes(txt.displayName);
-    if (txt.lanHost)
+    }
+    if (txt.lanHost) {
         beacon.lanHost = txt.lanHost;
-    if (txt.tailnetDns)
+    }
+    if (txt.tailnetDns) {
         beacon.tailnetDns = txt.tailnetDns;
-    if (txt.cliPath)
+    }
+    if (txt.cliPath) {
         beacon.cliPath = txt.cliPath;
+    }
     beacon.gatewayPort = parseIntOrNull(txt.gatewayPort);
     beacon.sshPort = parseIntOrNull(txt.sshPort);
     if (txt.gatewayTls) {
         const raw = txt.gatewayTls.trim().toLowerCase();
         beacon.gatewayTls = raw === "1" || raw === "true" || raw === "yes";
     }
-    if (txt.gatewayTlsSha256)
+    if (txt.gatewayTlsSha256) {
         beacon.gatewayTlsFingerprintSha256 = txt.gatewayTlsSha256;
-    if (txt.role)
+    }
+    if (txt.role) {
         beacon.role = txt.role;
-    if (txt.transport)
+    }
+    if (txt.transport) {
         beacon.transport = txt.transport;
-    if (!beacon.displayName)
+    }
+    if (!beacon.displayName) {
         beacon.displayName = decodedInstanceName;
+    }
     return beacon;
 }
 async function discoverViaDnsSd(domain, timeoutMs, run) {
-    const browse = await run(["dns-sd", "-B", "_poolbot-gw._tcp", domain], {
+    const browse = await run(["dns-sd", "-B", GATEWAY_SERVICE_TYPE, domain], {
         timeoutMs,
     });
     const instances = parseDnsSdBrowse(browse.stdout);
     const results = [];
     for (const instance of instances) {
-        const resolved = await run(["dns-sd", "-L", instance, "_poolbot-gw._tcp", domain], {
+        const resolved = await run(["dns-sd", "-L", instance, GATEWAY_SERVICE_TYPE, domain], {
             timeoutMs,
         });
         const parsed = parseDnsSdResolve(resolved.stdout, instance);
-        if (parsed)
+        if (parsed) {
             results.push({ ...parsed, domain });
+        }
     }
     return results;
 }
 async function discoverWideAreaViaTailnetDns(domain, timeoutMs, run) {
-    if (domain !== WIDE_AREA_DISCOVERY_DOMAIN)
+    if (!domain || domain === "local.") {
         return [];
+    }
     const startedAt = Date.now();
     const remainingMs = () => timeoutMs - (Date.now() - startedAt);
     const tailscaleCandidates = ["tailscale", "/Applications/Tailscale.app/Contents/MacOS/Tailscale"];
@@ -227,20 +256,23 @@ async function discoverWideAreaViaTailnetDns(domain, timeoutMs, run) {
                 timeoutMs: Math.max(1, Math.min(700, remainingMs())),
             });
             ips = parseTailscaleStatusIPv4s(res.stdout);
-            if (ips.length > 0)
+            if (ips.length > 0) {
                 break;
+            }
         }
         catch {
             // ignore
         }
     }
-    if (ips.length === 0)
+    if (ips.length === 0) {
         return [];
-    if (remainingMs() <= 0)
+    }
+    if (remainingMs() <= 0) {
         return [];
+    }
     // Keep scans bounded: this is a fallback and should not block long.
     ips = ips.slice(0, 40);
-    const probeName = `_poolbot-gw._tcp.${domain.replace(/\.$/, "")}`;
+    const probeName = `${GATEWAY_SERVICE_TYPE}.${domain.replace(/\.$/, "")}`;
     const concurrency = 6;
     let nextIndex = 0;
     let nameserver = null;
@@ -248,20 +280,24 @@ async function discoverWideAreaViaTailnetDns(domain, timeoutMs, run) {
     const worker = async () => {
         while (nameserver === null) {
             const budget = remainingMs();
-            if (budget <= 0)
+            if (budget <= 0) {
                 return;
+            }
             const i = nextIndex;
             nextIndex += 1;
-            if (i >= ips.length)
+            if (i >= ips.length) {
                 return;
+            }
             const ip = ips[i] ?? "";
-            if (!ip)
+            if (!ip) {
                 continue;
+            }
             try {
                 const probe = await run(["dig", "+short", "+time=1", "+tries=1", `@${ip}`, probeName, "PTR"], { timeoutMs: Math.max(1, Math.min(250, budget)) });
                 const lines = parseDigShortLines(probe.stdout);
-                if (lines.length === 0)
+                if (lines.length === 0) {
                     continue;
+                }
                 nameserver = ip;
                 ptrs = lines;
                 return;
@@ -272,26 +308,31 @@ async function discoverWideAreaViaTailnetDns(domain, timeoutMs, run) {
         }
     };
     await Promise.all(Array.from({ length: Math.min(concurrency, ips.length) }, () => worker()));
-    if (!nameserver || ptrs.length === 0)
+    if (!nameserver || ptrs.length === 0) {
         return [];
-    if (remainingMs() <= 0)
+    }
+    if (remainingMs() <= 0) {
         return [];
+    }
     const nameserverArg = `@${String(nameserver)}`;
     const results = [];
     for (const ptr of ptrs) {
         const budget = remainingMs();
-        if (budget <= 0)
+        if (budget <= 0) {
             break;
+        }
         const ptrName = ptr.trim().replace(/\.$/, "");
-        if (!ptrName)
+        if (!ptrName) {
             continue;
+        }
         const instanceName = ptrName.replace(/\.?_poolbot-gw\._tcp\..*$/, "");
         const srv = await run(["dig", "+short", "+time=1", "+tries=1", nameserverArg, ptrName, "SRV"], {
             timeoutMs: Math.max(1, Math.min(350, budget)),
         }).catch(() => null);
         const srvParsed = srv ? parseDigSrv(srv.stdout) : null;
-        if (!srvParsed)
+        if (!srvParsed) {
             continue;
+        }
         const txtBudget = remainingMs();
         if (txtBudget <= 0) {
             results.push({
@@ -324,12 +365,15 @@ async function discoverWideAreaViaTailnetDns(domain, timeoutMs, run) {
             const raw = txtMap.gatewayTls.trim().toLowerCase();
             beacon.gatewayTls = raw === "1" || raw === "true" || raw === "yes";
         }
-        if (txtMap.gatewayTlsSha256)
+        if (txtMap.gatewayTlsSha256) {
             beacon.gatewayTlsFingerprintSha256 = txtMap.gatewayTlsSha256;
-        if (txtMap.role)
+        }
+        if (txtMap.role) {
             beacon.role = txtMap.role;
-        if (txtMap.transport)
+        }
+        if (txtMap.transport) {
             beacon.transport = txtMap.transport;
+        }
         results.push(beacon);
     }
     return results;
@@ -339,12 +383,14 @@ function parseAvahiBrowse(stdout) {
     let current = null;
     for (const raw of stdout.split("\n")) {
         const line = raw.trimEnd();
-        if (!line)
+        if (!line) {
             continue;
-        if (line.startsWith("=") && line.includes("_poolbot-gw._tcp")) {
-            if (current)
+        }
+        if (line.startsWith("=") && line.includes(GATEWAY_SERVICE_TYPE)) {
+            if (current) {
                 results.push(current);
-            const marker = " _poolbot-gw._tcp";
+            }
+            const marker = ` ${GATEWAY_SERVICE_TYPE}`;
             const idx = line.indexOf(marker);
             const left = idx >= 0 ? line.slice(0, idx).trim() : line;
             const parts = left.split(/\s+/);
@@ -355,53 +401,64 @@ function parseAvahiBrowse(stdout) {
             };
             continue;
         }
-        if (!current)
+        if (!current) {
             continue;
+        }
         const trimmed = line.trim();
         if (trimmed.startsWith("hostname =")) {
             const match = trimmed.match(/hostname\s*=\s*\[([^\]]+)\]/);
-            if (match?.[1])
+            if (match?.[1]) {
                 current.host = match[1];
+            }
             continue;
         }
         if (trimmed.startsWith("port =")) {
             const match = trimmed.match(/port\s*=\s*\[(\d+)\]/);
-            if (match?.[1])
+            if (match?.[1]) {
                 current.port = parseIntOrNull(match[1]);
+            }
             continue;
         }
         if (trimmed.startsWith("txt =")) {
             const tokens = Array.from(trimmed.matchAll(/"([^"]*)"/g), (m) => m[1]);
             const txt = parseTxtTokens(tokens);
             current.txt = Object.keys(txt).length ? txt : undefined;
-            if (txt.displayName)
+            if (txt.displayName) {
                 current.displayName = txt.displayName;
-            if (txt.lanHost)
+            }
+            if (txt.lanHost) {
                 current.lanHost = txt.lanHost;
-            if (txt.tailnetDns)
+            }
+            if (txt.tailnetDns) {
                 current.tailnetDns = txt.tailnetDns;
-            if (txt.cliPath)
+            }
+            if (txt.cliPath) {
                 current.cliPath = txt.cliPath;
+            }
             current.gatewayPort = parseIntOrNull(txt.gatewayPort);
             current.sshPort = parseIntOrNull(txt.sshPort);
             if (txt.gatewayTls) {
                 const raw = txt.gatewayTls.trim().toLowerCase();
                 current.gatewayTls = raw === "1" || raw === "true" || raw === "yes";
             }
-            if (txt.gatewayTlsSha256)
+            if (txt.gatewayTlsSha256) {
                 current.gatewayTlsFingerprintSha256 = txt.gatewayTlsSha256;
-            if (txt.role)
+            }
+            if (txt.role) {
                 current.role = txt.role;
-            if (txt.transport)
+            }
+            if (txt.transport) {
                 current.transport = txt.transport;
+            }
         }
     }
-    if (current)
+    if (current) {
         results.push(current);
+    }
     return results;
 }
 async function discoverViaAvahi(domain, timeoutMs, run) {
-    const args = ["avahi-browse", "-rt", "_poolbot-gw._tcp"];
+    const args = ["avahi-browse", "-rt", GATEWAY_SERVICE_TYPE];
     if (domain && domain !== "local.") {
         // avahi-browse wants a plain domain (no trailing dot)
         args.push("-d", domain.replace(/\.$/, ""));
@@ -416,8 +473,10 @@ export async function discoverGatewayBeacons(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     const platform = opts.platform ?? process.platform;
     const run = opts.run ?? runCommandWithTimeout;
+    const wideAreaDomain = resolveWideAreaDiscoveryDomain({ configDomain: opts.wideAreaDomain });
     const domainsRaw = Array.isArray(opts.domains) ? opts.domains : [];
-    const domains = (domainsRaw.length > 0 ? domainsRaw : [...DEFAULT_DOMAINS])
+    const defaultDomains = ["local.", ...(wideAreaDomain ? [wideAreaDomain] : [])];
+    const domains = (domainsRaw.length > 0 ? domainsRaw : defaultDomains)
         .map((d) => String(d).trim())
         .filter(Boolean)
         .map((d) => (d.endsWith(".") ? d : `${d}.`));
@@ -425,10 +484,12 @@ export async function discoverGatewayBeacons(opts = {}) {
         if (platform === "darwin") {
             const perDomain = await Promise.allSettled(domains.map(async (domain) => await discoverViaDnsSd(domain, timeoutMs, run)));
             const discovered = perDomain.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
-            const wantsWideArea = domains.includes(WIDE_AREA_DISCOVERY_DOMAIN);
-            const hasWideArea = discovered.some((b) => b.domain === WIDE_AREA_DISCOVERY_DOMAIN);
-            if (wantsWideArea && !hasWideArea) {
-                const fallback = await discoverWideAreaViaTailnetDns(WIDE_AREA_DISCOVERY_DOMAIN, timeoutMs, run).catch(() => []);
+            const wantsWideArea = wideAreaDomain ? domains.includes(wideAreaDomain) : false;
+            const hasWideArea = wideAreaDomain
+                ? discovered.some((b) => b.domain === wideAreaDomain)
+                : false;
+            if (wantsWideArea && !hasWideArea && wideAreaDomain) {
+                const fallback = await discoverWideAreaViaTailnetDns(wideAreaDomain, timeoutMs, run).catch(() => []);
                 return [...discovered, ...fallback];
             }
             return discovered;

package/dist/infra/control-ui-assets.js

@@ -1,17 +1,34 @@
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { runCommandWithTimeout } from "../process/exec.js";
 import { defaultRuntime } from "../runtime.js";
+import { resolvePoolBotPackageRoot, resolvePoolBotPackageRootSync } from "./poolbot-root.js";
+const CONTROL_UI_DIST_PATH_SEGMENTS = ["dist", "control-ui", "index.html"];
+export function resolveControlUiDistIndexPathForRoot(root) {
+    return path.join(root, ...CONTROL_UI_DIST_PATH_SEGMENTS);
+}
+export async function resolveControlUiDistIndexHealth(opts = {}) {
+    const indexPath = opts.root
+        ? resolveControlUiDistIndexPathForRoot(opts.root)
+        : await resolveControlUiDistIndexPath(opts.argv1 ?? process.argv[1]);
+    return {
+        indexPath,
+        exists: Boolean(indexPath && fs.existsSync(indexPath)),
+    };
+}
 export function resolveControlUiRepoRoot(argv1 = process.argv[1]) {
-    if (!argv1)
+    if (!argv1) {
         return null;
+    }
     const normalized = path.resolve(argv1);
     const parts = normalized.split(path.sep);
     const srcIndex = parts.lastIndexOf("src");
     if (srcIndex !== -1) {
         const root = parts.slice(0, srcIndex).join(path.sep);
-        if (fs.existsSync(path.join(root, "ui", "vite.config.ts")))
+        if (fs.existsSync(path.join(root, "ui", "vite.config.ts"))) {
             return root;
+        }
     }
     let dir = path.dirname(normalized);
     for (let i = 0; i < 8; i++) {
@@ -20,36 +37,141 @@ export function resolveControlUiRepoRoot(argv1 = process.argv[1]) {
             return dir;
         }
         const parent = path.dirname(dir);
-        if (parent === dir)
+        if (parent === dir) {
             break;
+        }
         dir = parent;
     }
     return null;
 }
-export function resolveControlUiDistIndexPath(argv1 = process.argv[1]) {
-    if (!argv1)
+export async function resolveControlUiDistIndexPath(argv1 = process.argv[1]) {
+    if (!argv1) {
         return null;
+    }
     const normalized = path.resolve(argv1);
+    // Case 1: entrypoint is directly inside dist/ (e.g., dist/entry.js)
     const distDir = path.dirname(normalized);
-    if (path.basename(distDir) !== "dist")
+    if (path.basename(distDir) === "dist") {
+        return path.join(distDir, "control-ui", "index.html");
+    }
+    const packageRoot = await resolvePoolBotPackageRoot({ argv1: normalized });
+    if (packageRoot) {
+        return path.join(packageRoot, "dist", "control-ui", "index.html");
+    }
+    // Fallback: traverse up and find package.json with name "poolbot" + dist/control-ui/index.html
+    // This handles global installs where path-based resolution might fail.
+    let dir = path.dirname(normalized);
+    for (let i = 0; i < 8; i++) {
+        const pkgJsonPath = path.join(dir, "package.json");
+        const indexPath = path.join(dir, "dist", "control-ui", "index.html");
+        if (fs.existsSync(pkgJsonPath) && fs.existsSync(indexPath)) {
+            try {
+                const raw = fs.readFileSync(pkgJsonPath, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (parsed.name === "poolbot") {
+                    return indexPath;
+                }
+            }
+            catch {
+                // Invalid package.json, continue searching
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return null;
+}
+function addCandidate(candidates, value) {
+    if (!value) {
+        return;
+    }
+    candidates.add(path.resolve(value));
+}
+export function resolveControlUiRootOverrideSync(rootOverride) {
+    const resolved = path.resolve(rootOverride);
+    try {
+        const stats = fs.statSync(resolved);
+        if (stats.isFile()) {
+            return path.basename(resolved) === "index.html" ? path.dirname(resolved) : null;
+        }
+        if (stats.isDirectory()) {
+            const indexPath = path.join(resolved, "index.html");
+            return fs.existsSync(indexPath) ? resolved : null;
+        }
+    }
+    catch {
         return null;
-    return path.join(distDir, "control-ui", "index.html");
+    }
+    return null;
+}
+export function resolveControlUiRootSync(opts = {}) {
+    const candidates = new Set();
+    const argv1 = opts.argv1 ?? process.argv[1];
+    const cwd = opts.cwd ?? process.cwd();
+    const moduleDir = opts.moduleUrl ? path.dirname(fileURLToPath(opts.moduleUrl)) : null;
+    const argv1Dir = argv1 ? path.dirname(path.resolve(argv1)) : null;
+    const execDir = (() => {
+        try {
+            const execPath = opts.execPath ?? process.execPath;
+            return path.dirname(fs.realpathSync(execPath));
+        }
+        catch {
+            return null;
+        }
+    })();
+    const packageRoot = resolvePoolBotPackageRootSync({
+        argv1,
+        moduleUrl: opts.moduleUrl,
+        cwd,
+    });
+    // Packaged app: control-ui lives alongside the executable.
+    addCandidate(candidates, execDir ? path.join(execDir, "control-ui") : null);
+    if (moduleDir) {
+        // dist/<bundle>.js -> dist/control-ui
+        addCandidate(candidates, path.join(moduleDir, "control-ui"));
+        // dist/gateway/control-ui.js -> dist/control-ui
+        addCandidate(candidates, path.join(moduleDir, "../control-ui"));
+        // src/gateway/control-ui.ts -> dist/control-ui
+        addCandidate(candidates, path.join(moduleDir, "../../dist/control-ui"));
+    }
+    if (argv1Dir) {
+        // poolbot.mjs or dist/<bundle>.js
+        addCandidate(candidates, path.join(argv1Dir, "dist", "control-ui"));
+        addCandidate(candidates, path.join(argv1Dir, "control-ui"));
+    }
+    if (packageRoot) {
+        addCandidate(candidates, path.join(packageRoot, "dist", "control-ui"));
+    }
+    addCandidate(candidates, path.join(cwd, "dist", "control-ui"));
+    for (const dir of candidates) {
+        const indexPath = path.join(dir, "index.html");
+        if (fs.existsSync(indexPath)) {
+            return dir;
+        }
+    }
+    return null;
 }
 function summarizeCommandOutput(text) {
     const lines = text
         .split(/\r?\n/g)
         .map((l) => l.trim())
         .filter(Boolean);
-    if (!lines.length)
+    if (!lines.length) {
         return undefined;
+    }
     const last = lines.at(-1);
-    if (!last)
+    if (!last) {
         return undefined;
+    }
     return last.length > 240 ? `${last.slice(0, 239)}…` : last;
 }
 export async function ensureControlUiAssetsBuilt(runtime = defaultRuntime, opts) {
-    const indexFromDist = resolveControlUiDistIndexPath(process.argv[1]);
-    if (indexFromDist && fs.existsSync(indexFromDist)) {
+    const health = await resolveControlUiDistIndexHealth({ argv1: process.argv[1] });
+    const indexFromDist = health.indexPath;
+    if (health.exists) {
         return { ok: true, built: false };
     }
     const repoRoot = resolveControlUiRepoRoot(process.argv[1]);
@@ -63,7 +185,7 @@ export async function ensureControlUiAssetsBuilt(runtime = defaultRuntime, opts)
             message: `${hint}. Build them with \`pnpm ui:build\` (auto-installs UI deps).`,
         };
     }
-    const indexPath = path.join(repoRoot, "dist", "control-ui", "index.html");
+    const indexPath = resolveControlUiDistIndexPathForRoot(repoRoot);
     if (fs.existsSync(indexPath)) {
         return { ok: true, built: false };
     }

package/dist/infra/errors.js

@@ -8,6 +8,18 @@ export function extractErrorCode(err) {
         return String(code);
     return undefined;
 }
+/**
+ * Type guard for NodeJS.ErrnoException (any error with a `code` property).
+ */
+export function isErrno(err) {
+    return Boolean(err && typeof err === "object" && "code" in err);
+}
+/**
+ * Check if an error has a specific errno code.
+ */
+export function hasErrnoCode(err, code) {
+    return isErrno(err) && err.code === code;
+}
 export function formatErrorMessage(err) {
     if (err instanceof Error) {
         return err.message || err.name || "Error";