failproofai 1.0.0-beta.2 → 1.0.0-beta.21

package/.next/standalone/app/settings/settings-client.tsx

@@ -0,0 +1,487 @@
+"use client";
+
+/**
+ * /settings client — two sections (scheduled audit, email reports) plus the
+ * degraded states that are most of the real screens: daemon not installed /
+ * stopped / unsupported, no scan ever run, a scan running now, a last run that
+ * failed, signed out, and not cloud-enrolled. Each is shown explicitly, because
+ * a missing control reads as a bug.
+ *
+ * Visual conventions are the site chrome's, matched to /policies: the brutalist
+ * `.report`/`.section`/`.panel`/`.btn` classes from globals.css, the same
+ * emerald switch /policies uses (PolicyToggle), inline `var(--…)` colours, and
+ * the shared `toast()`. No new design language, colour, or component library.
+ *
+ * All writes go through server actions that call `updateConfig` — never a raw
+ * file write — so the CLI and dashboard cannot diverge. The parity mapping is
+ * documented on each action module.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { getScheduledAuditAction, type ScheduledAuditView } from "@/app/actions/get-scheduled-audit";
+import { setAutoAuditAction, setAuditIntervalAction } from "@/app/actions/update-scheduled-audit";
+import { triggerRun, RerunError } from "@/app/audit/_components/rerun-button";
+import { toast } from "@/app/components/toast";
+import { fetchWithTimeout } from "@/lib/fetch-with-timeout";
+import { formatRelativeTime } from "@/lib/format-duration";
+
+// ── formatting helpers ───────────────────────────────────────────────────────
+
+function fmtAbsolute(ms: number): string {
+  return new Date(ms).toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/** "in 6d" / "in 3h" / "in 12m" / "now". formatRelativeTime only speaks past. */
+function fmtFuture(ms: number): string {
+  const diff = ms - Date.now();
+  if (diff <= 0) return "now";
+  if (diff < 3_600_000) return `in ${Math.max(1, Math.floor(diff / 60_000))}m`;
+  if (diff < 86_400_000) return `in ${Math.floor(diff / 3_600_000)}h`;
+  return `in ${Math.floor(diff / 86_400_000)}d`;
+}
+
+// ── shared primitives (match /policies) ──────────────────────────────────────
+
+/** The exact switch /policies uses — copied shape, not a new control. */
+function Toggle({
+  enabled,
+  onChange,
+  disabled,
+  label,
+}: {
+  enabled: boolean;
+  onChange: () => void;
+  disabled?: boolean;
+  label: string;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onChange}
+      disabled={disabled}
+      role="switch"
+      aria-checked={enabled}
+      aria-label={label}
+      className={`relative inline-flex h-4 w-7 shrink-0 items-center rounded-full transition-colors disabled:opacity-40 ${
+        enabled ? "bg-emerald-500" : "bg-muted-foreground/30"
+      }`}
+    >
+      <span
+        className={`inline-block h-3 w-3 rounded-full bg-white shadow transition-transform ${
+          enabled ? "translate-x-3.5" : "translate-x-0.5"
+        }`}
+      />
+    </button>
+  );
+}
+
+type PillTone = "ok" | "warn" | "bad" | "muted";
+const PILL_TONE: Record<PillTone, { fg: string; bg: string; bd: string }> = {
+  ok: { fg: "var(--accent-green)", bg: "rgba(102,209,181,0.10)", bd: "rgba(102,209,181,0.30)" },
+  warn: { fg: "var(--amber)", bg: "rgba(232,196,106,0.10)", bd: "rgba(232,196,106,0.30)" },
+  bad: { fg: "var(--accent-pink)", bg: "rgba(228,88,124,0.10)", bd: "rgba(228,88,124,0.30)" },
+  muted: { fg: "var(--ink-2)", bg: "transparent", bd: "var(--line-2)" },
+};
+
+function Pill({ tone, children }: { tone: PillTone; children: React.ReactNode }) {
+  const t = PILL_TONE[tone];
+  return (
+    <span
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 6,
+        padding: "3px 9px",
+        fontFamily: "var(--font-mono)",
+        fontSize: 11,
+        letterSpacing: "0.04em",
+        color: t.fg,
+        background: t.bg,
+        border: `1px solid ${t.bd}`,
+        textTransform: "uppercase",
+      }}
+    >
+      {children}
+    </span>
+  );
+}
+
+const SECTION_TITLE: React.CSSProperties = {
+  fontFamily: "var(--font-mono)",
+  fontSize: 16,
+  fontWeight: 600,
+  letterSpacing: "-0.01em",
+  color: "var(--ink)",
+  margin: "0 0 4px",
+};
+const BODY: React.CSSProperties = {
+  fontFamily: "var(--font-mono)",
+  fontSize: 13,
+  color: "var(--ink-2)",
+  lineHeight: 1.65,
+  margin: 0,
+};
+const MUTED: React.CSSProperties = { ...BODY, color: "var(--dim)", fontSize: 12 };
+const CODE: React.CSSProperties = { color: "var(--ink)", fontVariantLigatures: "none" };
+
+/** A monospace inline command the user can copy by eye. */
+function Cmd({ children }: { children: React.ReactNode }) {
+  return (
+    <code
+      style={{
+        fontFamily: "var(--font-mono)",
+        fontSize: 12,
+        color: "var(--accent-green)",
+        background: "var(--bg-2)",
+        border: "1px solid var(--line-2)",
+        padding: "1px 6px",
+        whiteSpace: "nowrap",
+      }}
+    >
+      {children}
+    </code>
+  );
+}
+
+// ── scheduled audit section ──────────────────────────────────────────────────
+
+function ScheduledAuditSection({
+  view,
+  onReload,
+}: {
+  view: ScheduledAuditView;
+  onReload: () => Promise<void>;
+}) {
+  const [auto, setAuto] = useState(view.auto);
+  const [interval, setIntervalDays] = useState(view.intervalDays);
+  const [savingAuto, setSavingAuto] = useState(false);
+  const [savingInterval, setSavingInterval] = useState(false);
+  const [running, setRunning] = useState(false);
+  const [runningNow, setRunningNow] = useState(false);
+
+  // Keep local state honest if a background reload brought new server truth
+  // (e.g. someone toggled via CLI, or the interval clamp changed the value).
+  useEffect(() => setAuto(view.auto), [view.auto]);
+  useEffect(() => setIntervalDays(view.intervalDays), [view.intervalDays]);
+
+  // Reflect a scan already in flight (started here or from /audit) so the button
+  // and status line don't claim the machine is idle when it isn't.
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const res = await fetchWithTimeout("/api/audit/status", { cache: "no-store" });
+        if (res.ok && !cancelled) {
+          const s = (await res.json()) as { running?: boolean };
+          setRunning(Boolean(s.running));
+        }
+      } catch {
+        /* status is best-effort; a missing poll just means we assume idle */
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const daemonInactive = view.daemon !== "running";
+  const daemonUnsupported = view.daemon === "unsupported-platform";
+
+  const onToggleAuto = useCallback(async () => {
+    const next = !auto;
+    setAuto(next); // optimistic
+    setSavingAuto(true);
+    try {
+      const res = await setAutoAuditAction(next);
+      setAuto(res.auto);
+      toast(res.auto ? "Scheduled scanning on." : "Scheduled scanning off.");
+      await onReload();
+    } catch {
+      setAuto(!next); // revert
+      toast("Could not save that.");
+    } finally {
+      setSavingAuto(false);
+    }
+  }, [auto, onReload]);
+
+  const commitInterval = useCallback(
+    async (raw: number) => {
+      setSavingInterval(true);
+      try {
+        // The config owns the 1..90 clamp; we reflect whatever it stored.
+        const res = await setAuditIntervalAction(raw);
+        setIntervalDays(res.intervalDays);
+        toast(`Scanning every ${res.intervalDays} day${res.intervalDays === 1 ? "" : "s"}.`);
+      } catch {
+        setIntervalDays(view.intervalDays);
+        toast("Could not save that.");
+      } finally {
+        setSavingInterval(false);
+      }
+    },
+    [view.intervalDays],
+  );
+
+  const onRunNow = useCallback(async () => {
+    if (runningNow || running) return;
+    setRunningNow(true);
+    setRunning(true);
+    try {
+      await triggerRun({ cli: [], since: "all", noCache: false });
+      toast("Audit complete.");
+      await onReload();
+    } catch (err) {
+      const msg =
+        err instanceof RerunError && err.kind === "timeout"
+          ? "The scan is taking a while — it will finish in the background."
+          : "The scan could not be completed.";
+      toast(msg);
+    } finally {
+      setRunningNow(false);
+      setRunning(false);
+    }
+  }, [runningNow, running, onReload]);
+
+  const sched = view.schedule;
+  const lastExitBad =
+    sched?.lastExitCode != null && sched.lastExitCode !== 0 && sched.lastExitCode !== 75;
+
+  return (
+    <div className="panel" style={{ padding: 20, marginBottom: 20 }}>
+      <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12, flexWrap: "wrap" }}>
+        <div>
+          <h3 style={SECTION_TITLE}>Scheduled audit</h3>
+          <p style={MUTED}>Scan this machine on a timer, in the background.</p>
+        </div>
+        <div style={{ display: "flex", alignItems: "center", gap: 10 }}>
+          {view.daemon === "running" && <Pill tone="ok">daemon running</Pill>}
+          {view.daemon === "stopped" && <Pill tone="warn">daemon stopped</Pill>}
+          {view.daemon === "not-installed" && <Pill tone="warn">daemon not installed</Pill>}
+          {view.daemon === "unsupported-platform" && <Pill tone="muted">daemon unavailable</Pill>}
+        </div>
+      </div>
+
+      {/* Enable toggle + the plain statement about what the scan reads. */}
+      <div style={{ display: "flex", alignItems: "flex-start", gap: 12, marginTop: 18 }}>
+        <div style={{ marginTop: 2 }}>
+          <Toggle
+            enabled={auto}
+            onChange={onToggleAuto}
+            disabled={savingAuto || daemonUnsupported}
+            label={auto ? "Turn off scheduled scanning" : "Turn on scheduled scanning"}
+          />
+        </div>
+        <div style={{ minWidth: 0 }}>
+          <p style={{ ...BODY, color: "var(--ink)" }}>
+            {auto ? "Scanning this machine on a schedule." : "Scan this machine on a schedule."}
+          </p>
+          <p style={{ ...BODY, marginTop: 6 }}>
+            The scan reads the <span style={CODE}>contents</span> of every session transcript on
+            disk across all installed agent CLIs — your prompts, the files they read and wrote,
+            and command output. It runs entirely on this machine. Nothing is sent anywhere unless
+            you also turn on emailed reports below.
+          </p>
+        </div>
+      </div>
+
+      {/* Interval. The number bounds mirror the config's own 1..90 clamp as a UX
+          hint; the config remains the authority and we reflect what it stored. */}
+      <div style={{ display: "flex", alignItems: "center", gap: 10, marginTop: 16, flexWrap: "wrap" }}>
+        <label htmlFor="scan-interval" style={{ ...BODY }}>
+          Scan every
+        </label>
+        <input
+          id="scan-interval"
+          type="number"
+          min={1}
+          max={90}
+          step={1}
+          value={interval}
+          disabled={savingInterval || daemonUnsupported}
+          onChange={(e) => setIntervalDays(Number(e.target.value))}
+          onBlur={(e) => {
+            const v = Number(e.target.value);
+            // A cleared/garbage field must not persist NaN — snap back to the
+            // stored value and let the config keep owning the real bounds.
+            if (!Number.isFinite(v)) {
+              setIntervalDays(view.intervalDays);
+              return;
+            }
+            if (v !== view.intervalDays) void commitInterval(v);
+          }}
+          style={{
+            width: 64,
+            padding: "6px 8px",
+            background: "var(--bg)",
+            border: "1px solid var(--line-2)",
+            color: "var(--ink)",
+            fontFamily: "var(--font-mono)",
+            fontSize: 13,
+            textAlign: "center",
+          }}
+        />
+        <span style={BODY}>day{interval === 1 ? "" : "s"}.</span>
+        <span style={MUTED}>1–90; the config keeps it in range.</span>
+      </div>
+
+      {/* Last run / next due — read from the daemon-written schedule file. */}
+      <div
+        style={{
+          marginTop: 18,
+          paddingTop: 16,
+          borderTop: "1px dashed var(--line)",
+          display: "flex",
+          flexDirection: "column",
+          gap: 6,
+        }}
+      >
+        {running && (
+          <p style={{ ...BODY, color: "var(--accent-green)" }}>A scan is running now…</p>
+        )}
+
+        {/* Last run */}
+        {sched?.lastRunAtMs != null ? (
+          <p style={BODY}>
+            Last scheduled scan:{" "}
+            <span style={CODE}>{fmtAbsolute(sched.lastRunAtMs)}</span>{" "}
+            <span style={MUTED}>({formatRelativeTime(sched.lastRunAtMs)})</span>
+          </p>
+        ) : view.lastResultAt ? (
+          <p style={BODY}>
+            Last audit result:{" "}
+            <span style={CODE}>{fmtAbsolute(new Date(view.lastResultAt).getTime())}</span>{" "}
+            <span style={MUTED}>(no scheduled scan has run yet)</span>
+          </p>
+        ) : (
+          <p style={BODY}>No scan has run yet.</p>
+        )}
+
+        {/* Next due */}
+        {auto ? (
+          sched?.nextDueAtMs != null ? (
+            <p style={BODY}>
+              Next scan due:{" "}
+              <span style={CODE}>{fmtAbsolute(sched.nextDueAtMs)}</span>{" "}
+              <span style={MUTED}>({fmtFuture(sched.nextDueAtMs)})</span>
+            </p>
+          ) : (
+            <p style={BODY}>
+              Next scan:{" "}
+              <span style={MUTED}>the daemon will schedule it shortly.</span>
+            </p>
+          )
+        ) : (
+          <p style={MUTED}>Scheduled scanning is off — no scan is scheduled.</p>
+        )}
+
+        {lastExitBad && (
+          <p style={{ ...BODY, color: "var(--amber)" }}>
+            The last scheduled scan exited with code {sched?.lastExitCode}. It will retry on the
+            next tick.
+          </p>
+        )}
+        {sched?.schemaAhead && (
+          <p style={MUTED}>
+            A newer daemon wrote this schedule; some fields may not be shown.
+          </p>
+        )}
+      </div>
+
+      {/* Degraded daemon guidance — say plainly why "on" may still not run. */}
+      {auto && daemonInactive && (
+        <p style={{ ...BODY, color: "var(--amber)", marginTop: 14 }}>
+          {daemonUnsupported ? (
+            <>The background daemon isn&apos;t available on this platform, so scheduled scans
+            can&apos;t run here. You can still run one now, and use the audit page.</>
+          ) : view.daemon === "not-installed" ? (
+            <>Scheduled scanning is on, but the background service isn&apos;t installed, so nothing
+            will run on the timer yet. Install it with <Cmd>failproofai config</Cmd>.</>
+          ) : (
+            <>Scheduled scanning is on, but the background service is stopped, so nothing will run
+            until it starts. Reinstall or repair it with <Cmd>failproofai config</Cmd>.</>
+          )}
+        </p>
+      )}
+
+      {/* Run now — reuses the existing /api/audit/run route via triggerRun. */}
+      <div style={{ marginTop: 18 }}>
+        <button
+          type="button"
+          className="btn"
+          onClick={onRunNow}
+          disabled={runningNow || running}
+        >
+          {runningNow || running ? "[ scanning… ]" : "[ run a scan now ]"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// ── page ─────────────────────────────────────────────────────────────────────
+
+export default function SettingsClient() {
+  const [scheduled, setScheduled] = useState<ScheduledAuditView | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(false);
+  const mounted = useRef(true);
+
+  const reload = useCallback(async () => {
+    const s = await getScheduledAuditAction();
+    if (!mounted.current) return;
+    setScheduled(s);
+  }, []);
+
+  useEffect(() => {
+    mounted.current = true;
+    (async () => {
+      try {
+        await reload();
+      } catch {
+        if (mounted.current) setError(true);
+      } finally {
+        if (mounted.current) setLoading(false);
+      }
+    })();
+    return () => {
+      mounted.current = false;
+    };
+  }, [reload]);
+
+  return (
+    <main className="report">
+      <section className="section" data-screen-label="settings">
+        <h2
+          style={{
+            fontFamily: "var(--font-mono)",
+            fontSize: 24,
+            fontWeight: 600,
+            letterSpacing: "-0.01em",
+            color: "var(--ink)",
+            margin: "0 0 8px",
+          }}
+        >
+          Settings
+        </h2>
+        <p style={{ ...BODY, maxWidth: 720, margin: "0 0 24px" }}>
+          Machine-level controls for scheduled scanning and emailed reports.
+        </p>
+
+        {loading ? (
+          <p style={MUTED}>Loading…</p>
+        ) : error || !scheduled ? (
+          <p style={{ ...BODY, color: "var(--accent-pink)" }}>
+            Could not load settings. Refresh to try again.
+          </p>
+        ) : (
+          <ScheduledAuditSection view={scheduled} onReload={reload} />
+        )}
+      </section>
+    </main>
+  );
+}

package/.next/standalone/components/navbar.tsx

@@ -19,6 +19,7 @@ const NAV_LINKS = [
   { href: "/projects", label: "projects" },
   { href: "/policies", label: "policies" },
   { href: "/audit", label: "audit" },
+  { href: "/settings", label: "settings" },
 ];
 
 const REMOTE_LOGO_URL =
@@ -59,6 +60,7 @@ export const Navbar: React.FC<{
   const sectionLabel = (() => {
     if (pathname.startsWith("/policies")) return "policies";
     if (pathname.startsWith("/audit")) return "audit";
+    if (pathname.startsWith("/settings")) return "settings";
     if (pathname.startsWith("/projects") || pathname.startsWith("/project/")) return "projects";
     return "";
   })();

package/.next/standalone/lib/auth/api-server-client.ts

@@ -1,9 +1,8 @@
 /**
  * Low-level HTTP client for the FailproofAI api-server's /v0/auth/* endpoints.
  *
- * Shared by both the CLI (failproofai auth ...) and the dashboard's Next.js
- * API route proxies. Has no filesystem access — token persistence lives in
- * `./auth-store.ts`.
+ * Used by the dashboard's Next.js API route proxies. Has no filesystem access
+ * — token persistence lives in `./auth-store.ts`.
  *
  * The base URL is resolved from FAILPROOF_API_URL (preferred) or the legacy
  * FAILPROOFAI_API_URL, falling back to the hosted api-server. Local-dev

package/.next/standalone/lib/auth/auth-store.ts

@@ -2,16 +2,15 @@
  * Persistence layer for the FailproofAI auth.json file.
  *
  * Tokens live at ~/.failproofai/auth.json with mode 0600. The dashboard's
- * Next.js API routes and the CLI both read/write through here so the user's
- * session survives across `failproofai` (dashboard) and `failproofai auth`
- * (CLI) invocations.
+ * Next.js API routes read and write through here, so a session survives across
+ * dashboard runs.
  */
 
 import { existsSync, readFileSync, rmSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { writeJsonAtomically } from "../atomic-write";
+import { failproofaiHome } from "../../src/hooks/fp-home";
 import {
   AuthApiError,
   decodeJwt,
@@ -31,7 +30,7 @@ export interface StoredAuth {
 export function getAuthDir(): string {
   const override = process.env.FAILPROOFAI_AUTH_DIR;
   if (override) return override;
-  return join(homedir(), ".failproofai");
+  return failproofaiHome();
 }
 
 export function getAuthFilePath(): string {

package/.next/standalone/lib/codex-sessions.ts

@@ -33,10 +33,11 @@ import {
   type LogSource,
 } from "./log-entries";
 import { formatDuration } from "./format-duration";
+import { codexSessionPathsFile } from "../src/hooks/fp-home";
 
 // ── Transcript discovery ──
 
-const CACHE_PATH = join(homedir(), ".failproofai", "cache", "codex-session-paths.json");
+const CACHE_PATH = codexSessionPathsFile();
 
 function readCache(): Record<string, string> {
   try {

package/.next/standalone/lib/dashboard-host.ts

@@ -0,0 +1,101 @@
+/**
+ * Where the local dashboard binds, and which `Host` headers it will answer to.
+ *
+ * Shared by `scripts/launch.ts` (which chooses the bind address) and `proxy.ts`
+ * (which enforces it per request), because the two drifting apart is exactly how
+ * a lockdown quietly stops working.
+ *
+ * ## Why this exists
+ *
+ * The dashboard is a WRITE surface for this machine's security configuration —
+ * it can toggle policies and uninstall failproofai's hooks from every agent CLI
+ * — and it has no authentication of any kind. It used to bind `0.0.0.0`
+ * unconditionally, so every peer on the network could do all of that.
+ *
+ * Binding loopback is necessary but NOT sufficient. A malicious page can still
+ * reach `http://localhost:8020` from the victim's own browser, and DNS
+ * rebinding (a domain that resolves to 127.0.0.1 after first load) defeats an
+ * `Origin === Host` comparison, because both then read as the attacker's
+ * domain. So the defence is three layers, and all three are load-bearing:
+ *
+ *   1. bind loopback by default (kills every off-machine caller);
+ *   2. answer only to a loopback `Host` (kills DNS rebinding, whose whole trick
+ *      is arriving with an attacker-controlled Host);
+ *   3. reject cross-origin mutating requests by `Origin` (kills the ordinary
+ *      drive-by, which arrives with a perfectly valid `Host: localhost:8020`
+ *      and an `Origin` of the attacker's site).
+ *
+ * Layer 2 is what makes layer 3 trustworthy: without it, a rebound page is
+ * same-origin by the browser's own reckoning and layer 3 waves it through.
+ */
+
+/** The default bind address. Loopback — never the wildcard. */
+export const DEFAULT_DASHBOARD_HOST = "127.0.0.1";
+
+/**
+ * Hostnames that mean "this machine". `[::1]` is the bracketed form as it
+ * appears in a `Host` header; `::1` is the bare form as it appears in a bind
+ * address.
+ */
+const LOOPBACK_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0:0:0:0:0:0:0:1"]);
+
+/**
+ * True for any address that only this machine can reach.
+ *
+ * The whole 127.0.0.0/8 block is loopback, not just 127.0.0.1 — some setups
+ * bind 127.0.0.2 to separate services, and treating that as external would
+ * refuse a request the user deliberately arranged.
+ */
+export function isLoopbackHostname(hostname: string): boolean {
+  const h = hostname.trim().toLowerCase();
+  if (!h) return false;
+  if (LOOPBACK_HOSTNAMES.has(h)) return true;
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(h);
+}
+
+/**
+ * The hostname part of a `Host` header, with the port removed.
+ *
+ * IPv6 literals are bracketed (`[::1]:8020`), so the port cannot be found by
+ * looking for the last colon without handling the brackets first — `[::1]`
+ * is all colons.
+ */
+export function hostnameFromHostHeader(hostHeader: string): string {
+  const raw = hostHeader.trim();
+  if (raw.startsWith("[")) {
+    const end = raw.indexOf("]");
+    return end === -1 ? raw : raw.slice(0, end + 1);
+  }
+  const colon = raw.indexOf(":");
+  return colon === -1 ? raw : raw.slice(0, colon);
+}
+
+/** The hostname part of an `Origin` header (`http://localhost:8020` -> `localhost`). */
+export function hostnameFromOrigin(origin: string): string | null {
+  const raw = origin.trim();
+  // "null" is a real Origin value (sandboxed iframes, some redirects). It is
+  // never ours, so it must not parse into something permissive.
+  if (!raw || raw === "null") return null;
+  try {
+    const url = new URL(raw);
+    // `URL.hostname` KEEPS the brackets on an IPv6 literal ("[::1]"), which is
+    // already the form a Host header carries — so it passes through untouched.
+    // Bracketing it again would produce "[[::1]]" and never match anything.
+    return url.hostname || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the bind address from an explicit flag, then the environment, then
+ * the safe default.
+ *
+ * An explicit non-loopback value is honoured — someone running the dashboard in
+ * a container or on a remote dev box has a real need — but it is a deliberate
+ * act, and `launch.ts` says so out loud when it happens.
+ */
+export function resolveDashboardHost(flagHost?: string, envHost?: string): string {
+  const chosen = (flagHost ?? envHost ?? "").trim();
+  return chosen || DEFAULT_DASHBOARD_HOST;
+}