@rubytech/create-realagent 1.0.647 → 1.0.649

package/payload/platform/plugins/cloudflare/scripts/list-cf-domains.ts

@@ -0,0 +1,401 @@
+// Raw CDP scrape of the operator's Cloudflare dashboard to discover the
+// domains attached to the logged-in account. Output on stdout is a JSON
+// `string[]`, sorted and deduped. Every failure mode exits non-zero with
+// a `reason=<enum>` token on stderr tagged [list-cf-domains].
+//
+// Why raw CDP, not playwright:
+//   - `/json/new?about:blank` + WebSocket to the returned `webSocketDebuggerUrl`
+//     is ~120 LOC including retries and state machine.
+//   - Adds zero npm deps (Node 22 ships global `WebSocket`; no `ws`/`playwright`).
+//   - CDP is already bound to 127.0.0.1 by vnc.sh; the runtime surface is
+//     the same one setup-tunnel.sh uses for browser drive.
+//
+// Why URL-pattern extraction, not CSS selectors:
+//   - Cloudflare's SPA uses hashed, version-churning class names — a selector
+//     written today drifts within a dashboard redesign window.
+//   - The `/<accountId>/<domain>` URL shape is load-bearing for CF's own
+//     routing and cannot drift without breaking their entire dashboard; it
+//     is the most stable surface to key off.
+//
+// Contract with the caller (list-cf-domains.sh → route → form):
+//   stdout on exit 0: JSON `string[]`  (empty array means signed-in-but-empty)
+//   stderr on any path: phase_line-formatted lines, `[list-cf-domains] …`
+//   exit 1: `reason=<enum>` on stderr; scrape-empty-but-no-error is exit 0
+//            with body dump (the enum exists so the caller can distinguish
+//            "selector drift" from "empty account" — both shapes arrive via
+//            stdout).
+
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+const CDP_HOST = "127.0.0.1";
+const CDP_PORT = 9222;
+
+// Phase budgets total 30s (enforced by the shell wrapper's `timeout`).
+// Individual steps get sub-budgets so an early stall does not eat the
+// whole envelope silently.
+const CONNECT_TIMEOUT_MS = 2_000;
+const NAVIGATE_TIMEOUT_MS = 15_000;
+const SIGNED_IN_POLL_MS = 10_000;
+const SCRAPE_POLL_MS = 10_000;
+const POLL_INTERVAL_MS = 500;
+
+type Reason =
+  | "cdp-unreachable"
+  | "target-create-failed"
+  | "ws-connect-failed"
+  | "not-signed-in"
+  | "navigate-failed"
+  | "table-wait-timeout"
+  | "runtime-error";
+
+function logPhase(line: string): void {
+  // Written to stderr; shell wrapper tees to STREAM_LOG_PATH with timestamp.
+  // Keeping format parity with `_stream-log.sh phase_line` on the bash side
+  // means the tailer regex and grepping by `[list-cf-domains]` work uniformly.
+  process.stderr.write(`[list-cf-domains] ${line}\n`);
+}
+
+function die(reason: Reason, detail = ""): never {
+  logPhase(`phase=error reason=${reason}${detail ? ` detail="${detail.replace(/"/g, "'").slice(0, 300)}"` : ""}`);
+  process.exit(1);
+}
+
+async function cdpVersion(): Promise<void> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), CONNECT_TIMEOUT_MS);
+  try {
+    const res = await fetch(`http://${CDP_HOST}:${CDP_PORT}/json/version`, { signal: controller.signal });
+    if (!res.ok) die("cdp-unreachable", `HTTP ${res.status}`);
+  } catch (err) {
+    die("cdp-unreachable", err instanceof Error ? err.message : String(err));
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+interface CdpTarget {
+  id: string;
+  webSocketDebuggerUrl: string;
+}
+
+async function createTarget(): Promise<CdpTarget> {
+  // `PUT /json/new?<url>` returns JSON describing the target. The URL goes
+  // as a query-string argument (not a ?url= key), matching Chromium's CDP
+  // server. about:blank avoids a wasted navigation — the real navigate
+  // happens over WS after we attach.
+  const endpoint = `http://${CDP_HOST}:${CDP_PORT}/json/new?about:blank`;
+  let res: Response;
+  try {
+    res = await fetch(endpoint, { method: "PUT", signal: AbortSignal.timeout(CONNECT_TIMEOUT_MS) });
+  } catch (err) {
+    die("target-create-failed", err instanceof Error ? err.message : String(err));
+  }
+  if (!res.ok) die("target-create-failed", `HTTP ${res.status}`);
+  const target = (await res.json()) as Partial<CdpTarget>;
+  if (!target.id || !target.webSocketDebuggerUrl) {
+    die("target-create-failed", "response missing id or webSocketDebuggerUrl");
+  }
+  return target as CdpTarget;
+}
+
+async function closeTarget(id: string): Promise<void> {
+  try {
+    await fetch(`http://${CDP_HOST}:${CDP_PORT}/json/close/${id}`, {
+      signal: AbortSignal.timeout(CONNECT_TIMEOUT_MS),
+    });
+  } catch {
+    // Best-effort on cleanup — a leaked target is recovered by the next vnc.sh
+    // restart; surfacing it as a failure would mask the real scrape error.
+  }
+}
+
+// Minimal CDP WebSocket client. We only need three commands: Page.enable,
+// Runtime.enable, Page.navigate, Runtime.evaluate. A full client would
+// manage sessions / targets / events — we just need request/response with
+// per-id correlation and an optional event stream for Page.frameNavigated
+// (which we do not actually need because Runtime.evaluate on location.href
+// is the authoritative signal).
+class CdpClient {
+  private ws: WebSocket;
+  private nextId = 1;
+  private pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+
+  private constructor(ws: WebSocket) {
+    this.ws = ws;
+    this.ws.addEventListener("message", (ev) => this.onMessage(ev.data as string));
+    this.ws.addEventListener("error", () => {
+      for (const { reject } of this.pending.values()) reject(new Error("WebSocket error"));
+      this.pending.clear();
+    });
+    this.ws.addEventListener("close", () => {
+      for (const { reject } of this.pending.values()) reject(new Error("WebSocket closed"));
+      this.pending.clear();
+    });
+  }
+
+  static async connect(url: string): Promise<CdpClient> {
+    const ws = new WebSocket(url);
+    return await new Promise((resolvePromise, rejectPromise) => {
+      const timer = setTimeout(() => {
+        ws.close();
+        rejectPromise(new Error(`WebSocket connect timeout (${CONNECT_TIMEOUT_MS}ms)`));
+      }, CONNECT_TIMEOUT_MS);
+      ws.addEventListener("open", () => {
+        clearTimeout(timer);
+        resolvePromise(new CdpClient(ws));
+      }, { once: true });
+      ws.addEventListener("error", (ev) => {
+        clearTimeout(timer);
+        rejectPromise(new Error(`WebSocket error: ${(ev as ErrorEvent).message ?? "unknown"}`));
+      }, { once: true });
+    });
+  }
+
+  private onMessage(raw: string): void {
+    let msg: { id?: number; result?: unknown; error?: { message?: string } };
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (typeof msg.id !== "number") return;
+    const waiter = this.pending.get(msg.id);
+    if (!waiter) return;
+    this.pending.delete(msg.id);
+    if (msg.error) {
+      waiter.reject(new Error(msg.error.message ?? "CDP error"));
+    } else {
+      waiter.resolve(msg.result);
+    }
+  }
+
+  send<T = unknown>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+    const id = this.nextId++;
+    return new Promise<T>((resolvePromise, rejectPromise) => {
+      this.pending.set(id, {
+        resolve: resolvePromise as (v: unknown) => void,
+        reject: rejectPromise,
+      });
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  close(): void {
+    try { this.ws.close(); } catch { /* ws may already be closing */ }
+  }
+}
+
+interface EvaluateResult {
+  result: { type: string; value?: unknown; description?: string };
+  exceptionDetails?: { text?: string; exception?: { description?: string } };
+}
+
+async function evaluate<T = unknown>(cdp: CdpClient, expression: string): Promise<T> {
+  const res = await cdp.send<EvaluateResult>("Runtime.evaluate", {
+    expression,
+    returnByValue: true,
+    awaitPromise: false,
+  });
+  if (res.exceptionDetails) {
+    throw new Error(res.exceptionDetails.exception?.description ?? res.exceptionDetails.text ?? "evaluate threw");
+  }
+  return res.result.value as T;
+}
+
+// Detect whether the dashboard has redirected to a signed-in account path
+// (URL like `/<32-hex-accountId>/…`) or the unsigned-in `/login` flow.
+// Returns the accountId if signed in, null if still loading, false if
+// definitively signed-out.
+const ACCOUNT_ID_REGEX = /^\/([a-f0-9]{32})(?:\/|$)/;
+
+async function readAccountId(cdp: CdpClient): Promise<string | null | false> {
+  const pathname = await evaluate<string>(cdp, "location.pathname");
+  if (typeof pathname !== "string") return null;
+  if (pathname.startsWith("/login") || pathname.startsWith("/sign-in")) return false;
+  const match = pathname.match(ACCOUNT_ID_REGEX);
+  return match ? match[1] : null;
+}
+
+async function waitForSignedIn(cdp: CdpClient): Promise<string> {
+  const deadline = Date.now() + SIGNED_IN_POLL_MS;
+  while (Date.now() < deadline) {
+    const state = await readAccountId(cdp);
+    if (state === false) die("not-signed-in", "dashboard redirected to login");
+    if (typeof state === "string") {
+      logPhase(`phase=dashboard-nav-complete accountId=${state.slice(0, 8)}…`);
+      return state;
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  // Timed out without seeing either pattern — treat as not-signed-in to
+  // prompt `tunnel-login`; a genuinely-slow dashboard that later resolves
+  // would be a false-negative we accept in exchange for deterministic UX.
+  die("not-signed-in", "no /<accountId>/… path reached within budget");
+}
+
+// Extract every domain mentioned on the Domains Overview page via URL-
+// pattern match, then merge with any FQDN-shaped text found in table cells.
+// Two sources: (a) `/<accountId>/<hostname>` URL hrefs on the page; (b) any
+// text node on the page matching a valid FQDN pattern — the overview page
+// renders the zone name as both a link and a table cell, so either source
+// catches it. The merge is conservative: we require the string look like a
+// domain (2+ labels, last label 2-63 alpha) AND not be a cloudflare-owned
+// marketing host.
+const SCRAPE_EXPRESSION = `(function() {
+  const accountIdMatch = location.pathname.match(/^\\/([a-f0-9]{32})/);
+  if (!accountIdMatch) return { reason: 'no-account-id', domains: [] };
+  const accountId = accountIdMatch[1];
+
+  const out = new Set();
+  const pushIfDomain = (s) => {
+    if (typeof s !== 'string') return;
+    const t = s.trim().toLowerCase();
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/.test(t)) return;
+    if (t.endsWith('.cloudflare.com') || t === 'cloudflare.com') return;
+    out.add(t);
+  };
+
+  // Source A: /<accountId>/<host> hrefs — the canonical CF routing pattern
+  // that the overview page uses to link each zone to its management screens.
+  const hrefPrefix = '/' + accountId + '/';
+  for (const a of document.querySelectorAll('a[href]')) {
+    const href = a.getAttribute('href') || '';
+    if (!href.startsWith(hrefPrefix)) continue;
+    const tail = href.slice(hrefPrefix.length).split('?')[0].split('#')[0];
+    const firstSegment = tail.split('/')[0];
+    pushIfDomain(firstSegment);
+  }
+
+  // Source B: explicit FQDN-shaped text in the main content region. Guards
+  // against a hypothetical CF redesign that drops the link tree — the zone
+  // name still appears as rendered text in the table row.
+  const main = document.querySelector('main') || document.body;
+  if (main) {
+    const treeWalker = document.createTreeWalker(main, NodeFilter.SHOW_TEXT);
+    let node;
+    while ((node = treeWalker.nextNode())) {
+      const text = (node.nodeValue || '').trim();
+      if (text.length < 4 || text.length > 253) continue;
+      pushIfDomain(text);
+    }
+  }
+
+  return { reason: 'ok', domains: Array.from(out).sort() };
+})()`;
+
+interface ScrapeOutcome {
+  reason: "ok" | "no-account-id";
+  domains: string[];
+}
+
+async function scrapeDomains(cdp: CdpClient): Promise<string[]> {
+  const deadline = Date.now() + SCRAPE_POLL_MS;
+  let lastOutcome: ScrapeOutcome | null = null;
+  while (Date.now() < deadline) {
+    try {
+      const outcome = await evaluate<ScrapeOutcome>(cdp, SCRAPE_EXPRESSION);
+      lastOutcome = outcome;
+      if (outcome.reason === "ok" && outcome.domains.length > 0) {
+        logPhase(`phase=dom-scrape-complete result=ok count=${outcome.domains.length}`);
+        return outcome.domains;
+      }
+      // `ok` with zero domains is ambiguous during SPA hydration — keep
+      // polling in case the table renders after a data fetch. The final
+      // iteration's zero result is the empty-account signal.
+    } catch (err) {
+      logPhase(`phase=scrape-retry err="${(err instanceof Error ? err.message : String(err)).slice(0, 120)}"`);
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  // Poll exhausted. Distinguish genuine empty account from selector drift by
+  // dumping the body HTML (bounded) for manual inspection, then reporting
+  // empty with the diagnostic enum. The script still exits 0 — the caller
+  // treats empty as a valid signal and shows the "add a domain" empty state.
+  try {
+    const html = await evaluate<string>(cdp, "document.documentElement.outerHTML.slice(0, 100000)");
+    // CONFIG_DIR is set by list-cf-domains.sh before the spawn. A silent
+    // fallback would dump logs into the wrong brand's directory on a Real
+    // Agent install — a silent-miswrite masking the wrapper-side break it
+    // came from. Per Task 473 doctrine: loud-fail on absent runtime-derived
+    // values.
+    const configDir = process.env.CONFIG_DIR;
+    if (!configDir) {
+      throw new Error("CONFIG_DIR env var not set by wrapper — refusing to guess brand log directory");
+    }
+    const logDir = resolve(homedir(), configDir, "logs");
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const dumpPath = resolve(logDir, `list-cf-domains-${ts}.html`);
+    await writeFile(dumpPath, typeof html === "string" ? html : String(html), "utf-8");
+    logPhase(`phase=dom-scrape-complete result=empty-or-drift dump=${dumpPath} lastReason=${lastOutcome?.reason ?? "unknown"}`);
+  } catch (err) {
+    logPhase(`phase=dom-scrape-complete result=empty-or-drift dump=failed lastReason=${lastOutcome?.reason ?? "unknown"} err="${(err instanceof Error ? err.message : String(err)).slice(0, 120)}"`);
+  }
+  return [];
+}
+
+async function navigate(cdp: CdpClient, url: string): Promise<void> {
+  const result = await cdp.send<{ errorText?: string }>("Page.navigate", { url });
+  if (result?.errorText) die("navigate-failed", `Page.navigate errorText="${result.errorText}"`);
+}
+
+async function waitForDocumentReady(cdp: CdpClient): Promise<void> {
+  const deadline = Date.now() + NAVIGATE_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const state = await evaluate<string>(cdp, "document.readyState");
+    if (state === "complete" || state === "interactive") return;
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  die("navigate-failed", "document.readyState did not reach complete/interactive");
+}
+
+async function main(): Promise<void> {
+  logPhase(`phase=script-start cdp=${CDP_HOST}:${CDP_PORT}`);
+
+  await cdpVersion();
+  logPhase(`phase=cdp-connect result=ok`);
+
+  const target = await createTarget();
+  logPhase(`phase=target-created targetId=${target.id.slice(0, 8)}…`);
+
+  let cdp: CdpClient;
+  try {
+    cdp = await CdpClient.connect(target.webSocketDebuggerUrl);
+  } catch (err) {
+    await closeTarget(target.id);
+    die("ws-connect-failed", err instanceof Error ? err.message : String(err));
+  }
+
+  try {
+    await cdp.send("Page.enable");
+    await cdp.send("Runtime.enable");
+
+    logPhase(`phase=dashboard-nav-start url=https://dash.cloudflare.com/`);
+    await navigate(cdp, "https://dash.cloudflare.com/");
+    await waitForDocumentReady(cdp);
+
+    const accountId = await waitForSignedIn(cdp);
+
+    const overviewUrl = `https://dash.cloudflare.com/${accountId}/domains/overview`;
+    logPhase(`phase=table-wait url=${overviewUrl}`);
+    await navigate(cdp, overviewUrl);
+    await waitForDocumentReady(cdp);
+
+    const domains = await scrapeDomains(cdp);
+
+    logPhase(`phase=target-closed`);
+    process.stdout.write(JSON.stringify(domains) + "\n");
+    logPhase(`phase=script-exit code=0 count=${domains.length}`);
+  } catch (err) {
+    // Only runtime errors that escaped the typed-reason paths land here.
+    die("runtime-error", err instanceof Error ? err.message : String(err));
+  } finally {
+    cdp.close();
+    await closeTarget(target.id);
+  }
+}
+
+main().catch((err: unknown) => {
+  die("runtime-error", err instanceof Error ? err.message : String(err));
+});

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -168,11 +168,73 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
     echo "ERROR: CDP PUT /json/new?<url> returned empty — Chromium rejected the navigate." >&2
     exit 1
   fi
-  phase_line setup-tunnel step=browser-drive result=accepted
+  # Extract the CDP target id so _cdp-authorize.mjs can open a debugger
+  # WebSocket against the correct tab. The PUT response is a JSON object
+  # describing the newly-created target; `.id` is the only stable field
+  # across Chromium versions that works for `/json/list` lookup.
+  CDP_TARGET_ID="$(printf '%s' "${CDP_RESP}" | jq -r '.id // empty' 2>/dev/null || true)"
+  if [ -z "${CDP_TARGET_ID}" ]; then
+    kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+    phase_line setup-tunnel step=browser-drive result=error reason=cdp-target-id-missing \
+      resp_head="$(printf '%s' "${CDP_RESP}" | head -c 200)"
+    echo "ERROR: CDP PUT /json/new?<url> returned a body without an .id field — Chromium protocol drift?" >&2
+    exit 1
+  fi
+  phase_line setup-tunnel step=browser-drive result=accepted target_id="${CDP_TARGET_ID}"
+
+  # Task 588: drive the Authorize click via CDP WebSocket instead of waiting
+  # for a human. The helper shares a directory with this script; same
+  # readlink-resolve pattern as _stream-log.sh so the symlink install path
+  # (packages/create-maxy installs ~/setup-tunnel.sh as a symlink) doesn't
+  # point dirname at $HOME.
+  AUTH_HELPER="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_cdp-authorize.mjs"
+  if [ ! -x "${AUTH_HELPER}" ]; then
+    kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+    phase_line setup-tunnel step=browser-drive result=error reason=cdp-helper-missing \
+      path="${AUTH_HELPER}"
+    echo "ERROR: _cdp-authorize.mjs helper missing or not executable at ${AUTH_HELPER}" >&2
+    exit 1
+  fi
+  # tee_subprocess pipes the helper's cdp-authorize result= line into the
+  # stream log under the setup-tunnel:cdp-click tag so the chat UI renders
+  # the click outcome in real time. Exit code drives control flow.
+  if tee_subprocess setup-tunnel:cdp-click -- \
+      node "${AUTH_HELPER}" "${CDP_TARGET_ID}"; then
+    phase_line setup-tunnel step=oauth-login result=authorize-clicked \
+      target_id="${CDP_TARGET_ID}"
+  else
+    CLICK_RC=$?
+    kill "${CF_PIPELINE_PID}" 2>/dev/null || true
+    # Helper exit codes: 1=authorize-button-not-found (loud, expected failure
+    # mode when the VNC browser isn't signed into Cloudflare), 2=cdp-ws-unreachable,
+    # 3=target-not-found, 4=click-evaluate-threw, 5=protocol-error. All are
+    # final — no retry, no silent fallback. Map the exit code 1:1 to a reason
+    # string so the stream-log `reason=<…>` is greppable by exact cause; a
+    # single catch-all reason would defeat the observability contract.
+    case "${CLICK_RC}" in
+      1) CLICK_REASON=authorize-button-not-found ;;
+      2) CLICK_REASON=cdp-ws-unreachable ;;
+      3) CLICK_REASON=target-not-found ;;
+      4) CLICK_REASON=click-evaluate-threw ;;
+      5) CLICK_REASON=protocol-error ;;
+      *) CLICK_REASON="unknown-exit-${CLICK_RC}" ;;
+    esac
+    phase_line setup-tunnel step=browser-drive result=error \
+      reason="${CLICK_REASON}" click_rc="${CLICK_RC}"
+    echo "ERROR: CDP-driven Authorize click failed (helper exit=${CLICK_RC}, reason=${CLICK_REASON})." >&2
+    echo "       If the VNC browser is not signed into Cloudflare, sign in manually," >&2
+    echo "       close the sign-in tab, and re-run setup — or run ~/reset-tunnel.sh first." >&2
+    exit 1
+  fi
 
   # Wait for cert.pem to land — cloudflared writes to ~/.cloudflared/cert.pem
-  # regardless of --origincert, so watch the canonical location.
-  LOGIN_TIMEOUT="${SETUP_TUNNEL_LOGIN_TIMEOUT:-180}"
+  # regardless of --origincert, so watch the canonical location. Task 588
+  # collapses the pre-click 180 s human-latency window to a 20 s deterministic
+  # round-trip window (Cloudflare → cloudflared webhook after consent). The
+  # 2-second heartbeat inside the loop is the observability contract for
+  # this bounded wait — no form-spawned script is allowed a silent poll of
+  # more than ~2 s per criterion 3 of Task 588.
+  LOGIN_TIMEOUT="${SETUP_TUNNEL_LOGIN_TIMEOUT:-20}"
   LOGIN_WAIT=0
   while [ ! -f "${HOME}/.cloudflared/cert.pem" ]; do
     if ! kill -0 "${CF_PIPELINE_PID}" 2>/dev/null; then
@@ -192,6 +254,14 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
       echo "ERROR: Timed out after ${LOGIN_WAIT}s waiting for cert.pem to land." >&2
       exit 1
     fi
+    # Heartbeat every 2 s after the click. t=0 is the authorize-clicked
+    # phase line above; the first heartbeat fires at t=2. Without this line
+    # the tailer sees silence for the full 1-20 s round-trip — the exact
+    # state Task 588 forbids.
+    if [ "${LOGIN_WAIT}" -gt 0 ] && [ $((LOGIN_WAIT % 2)) -eq 0 ]; then
+      phase_line setup-tunnel step=oauth-login result=awaiting-cert \
+        elapsed="${LOGIN_WAIT}s" timeout="${LOGIN_TIMEOUT}s"
+    fi
     sleep 1
     LOGIN_WAIT=$((LOGIN_WAIT + 1))
   done

package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md

@@ -84,7 +84,9 @@ Example:
 
 ## 4. Dashboard guidance — `references/dashboard-guide.md`
 
-Use this when the operator needs to do something only the Cloudflare dashboard can do: sign in, switch accounts, add a site, edit an apex CNAME, verify zone nameservers, delete a tunnel after stopping its replicas. The guide has one numbered click-path per operation. Quote the relevant click-path verbatim — the operator follows it in the browser; no agent browser automation is involved.
+Use this when the operator needs to do something only the Cloudflare dashboard can do: sign in, switch accounts, add a site, edit an apex CNAME, verify zone nameservers, delete a tunnel after stopping its replicas. The guide has one numbered click-path per operation. Quote the relevant click-path verbatim — the operator follows it in the browser. The agent does not drive dashboard mutations via Playwright or Chrome DevTools.
+
+The single exception is `list-cf-domains.sh` (Task 589), which reads the domains attached to the logged-in account to populate the `cloudflare-setup-form` dropdowns. That script is deterministic (bash + raw CDP, no LLM in the decision path), invoked only by the `/api/admin/cloudflare/domains` route, and produces only a JSON `string[]` on stdout; no dashboard state is changed. Any dashboard scrape that is not this exact script is forbidden — the agent does not extend this carve-out to new scripts it writes, hypothesises, or finds. Adding a new sanctioned scrape surface requires a code change reviewed as a doctrine change, not an inline agent decision.
 
 ---
 
@@ -96,6 +98,6 @@ When the operator's request touches Cloudflare, the agent's permitted actions ar
 - Quote `references/manual-setup.md`, `references/reset-guide.md`, or `references/dashboard-guide.md`.
 - Verify reachability via plain HTTP (`curl -I https://<hostname>`).
 
-The agent does not drive Cloudflare's dashboard via Playwright or Chrome DevTools. The agent does not synthesise `cloudflared` flag combinations from web search or prior training. The agent does not call Cloudflare API or SDK from any language. The agent does not write or mutate `cert.pem`, `tunnel.state`, `config.yml`, or `alias-domains.json` directly — `setup-tunnel.sh` and the operator manage those files.
+The agent does not drive Cloudflare dashboard mutations via Playwright or Chrome DevTools. The single sanctioned read-only scrape is `list-cf-domains.sh`, invoked only by the `/api/admin/cloudflare/domains` route — the LLM is not in its decision path. No other dashboard-automation surface is permitted; the agent does not generalise this exception to new scripts. The agent does not synthesise `cloudflared` flag combinations from web search or prior training. The agent does not call Cloudflare API or SDK from any language. The agent does not write or mutate `cert.pem`, `tunnel.state`, `config.yml`, or `alias-domains.json` directly — `setup-tunnel.sh` and the operator manage those files.
 
 When a sanctioned surface fails, the agent reports the failure with the exact output, cites the recovery step from `references/reset-guide.md`, and stops. Improvisation — "let me try a different flag" or "let me check the dashboard myself" — is the behaviour this rule exists to prevent. See IDENTITY.md § Cloudflare operations for the unconditional form.

package/payload/platform/plugins/docs/references/cloudflare.md

@@ -8,6 +8,7 @@ Each installation has its own Cloudflare account. Sign-in is OAuth in the device
 |------|--------|
 | **Product identity** (Maxy vs Real Agent) | `brand.json` (`productName`, `configDir`) — known at install. |
 | **Cloudflare account identity** | `cert.pem` from OAuth. One account per brand per device. |
+| **Domain scope** (which zones the operator can route) | Live Cloudflare dashboard at form-render time via `list-cf-domains.sh`, not `brand.json`. Brand identity has no authority over which domains the operator's CF account holds. |
 | **Local tunnel state** | `~/{configDir}/cloudflared/` — `cert.pem`, `<UUID>.json`, `config.yml`, `tunnel.state`, `alias-domains.json`. |
 
 There is no token-based auth for the operator-owned path (Mode A). To switch Cloudflare accounts, run `reset-tunnel.sh` (which deletes the cert and every tunnel on the current account), then run `setup-tunnel.sh` again — `cloudflared tunnel login` inside the setup script will pick a fresh account when you sign in.

package/payload/platform/plugins/docs/references/deployment.md

@@ -66,6 +66,15 @@ The logs will show which service failed to start and why. Common causes:
 - **Port 19200 already in use** — check for another process: `lsof -i :19200`
 - **Claude OAuth expired** — the next admin session will prompt you to re-authenticate
 
+## Systemd units on each device
+
+Each Maxy device runs two independent `--user` systemd units:
+
+- `maxy-ui.service` — the admin + public HTTP server (default port 19200). Restarted by the upgrade flow; short downtime is expected during steps 8→12 of an upgrade.
+- `maxy-ttyd.service` — a persistent PTY over WebSocket on `127.0.0.1:7681` attached to a tmux session named `maxy-pty`. Independent of `maxy-ui` — restarting the UI does not interrupt shell work, which is exactly the property the upgrade flow relies on to survive its own admin-server restart.
+
+If the Software Update window's terminal goes blank and does not reconnect, `sudo systemctl --user status maxy-ttyd` is the first thing to check. Restarting the unit (`sudo systemctl --user restart maxy-ttyd`) is safe: the tmux session survives because `tmux new-session -A -s maxy-pty` is idempotent.
+
 ## Upgrading
 
 To upgrade Maxy to the latest version, ask Maxy: "Upgrade Maxy." The platform checks the current device identity (hostname and port via `system-status`), then re-runs the installer with explicit `--hostname` and `--port` flags to preserve them across the upgrade.
@@ -76,4 +85,6 @@ The docs plugin (this plugin) is upgraded in the same step — you always have t
 
 Maxy checks for new releases on every admin session start — whenever you log in, reload the page, or return to the admin chat. When a newer version is available, the Software Update window opens automatically showing your current and the latest version, with a one-click Upgrade button. Dismissing the window (click outside or the close button) defers the alert until your next login or reload; no alert is shown when you are already on the latest version.
 
+The upgrade runs inside a live terminal embedded in the Software Update window — you see each installation step stream as it happens, and any password prompts from `sudo` appear directly in the terminal for you to answer. Closing the window does not cancel the upgrade; re-opening it reattaches to the same shell so you can see what happened while disconnected.
+
 The header menu's version indicator still reflects real-time status: a green dot means you are up to date, and an accent-coloured dot means an upgrade is available. Opening the menu refreshes the version check, so a long-lived session can still surface an upgrade that became available after login without reloading the page.

package/payload/platform/plugins/docs/references/getting-started.md

@@ -40,6 +40,8 @@ When you first open the admin interface:
 
 This setup is resumable — if you close the browser mid-setup, Maxy picks up where you left off next time.
 
+After install, a live admin terminal is available inside the Software Update window — your Pi's shell, accessible through the admin UI, for upgrades and any other shell work without needing to SSH.
+
 ## How to Use Maxy
 
 Conversation is the only interface. Type or speak what you need:

package/payload/platform/plugins/docs/references/memory-guide.md

@@ -84,9 +84,9 @@ Ask naturally:
 
 Maxy answers relational questions — "list all my people", "how many tasks do I have", "find the person with email X", "show me the 20 most recently created nodes" — via direct read-only Cypher against your Neo4j. This is faster and more precise than semantic search when the question is "the exact set where", not "things similar to".
 
-You can also open the Neo4j Browser at any time from the burger menu → **Graph**. Sign in with your Neo4j username (`neo4j`) and password (stored in `config/.neo4j-password` on the device). Run `MATCH (n) RETURN n LIMIT 25` for a visual overview of your graph, or write your own Cypher for ad-hoc exploration.
+You can also open a visual view of your graph at any time from the burger menu → **Graph**. It renders up to 200 of your most recently updated nodes as a force-directed map, coloured by label (Person, Service, KnowledgeDocument, Task, …). Click a node to see its properties; type in the search box to highlight matches.
 
-The browser reaches only your own brand's Neo4j — a Maxy device and a Real Agent device share no graph state even when on the same laptop.
+The page reads only your own brand's Neo4j — a Maxy device and a Real Agent device share no graph state even when on the same laptop. No credentials are required; the view inherits your admin session.
 
 ## Privacy
 

package/payload/platform/plugins/docs/references/platform.md

@@ -62,6 +62,12 @@ There is no dashboard, no settings panel, no menus. Everything is done through c
 
 The chat input auto-grows as you type — it expands to fit your message and shrinks back when you delete text. You can also drag the resize handle above the input to set a custom height.
 
+## Admin Terminal
+
+The admin UI includes a live terminal surface that opens a real shell on your Pi in the browser, reached via the Software Update modal. Under the hood it's a WebSocket (`/admin/terminal/ws`) attached through `@xterm/xterm` to `ttyd` on `127.0.0.1:7681`, backed by a persistent tmux session named `maxy-pty`.
+
+The tmux session outlives admin-server restarts — running an upgrade inside this terminal means you see the live shell output continuously, even through the admin server's own restart mid-upgrade. Closing the browser tab does not kill the running work; re-opening the Software Update window reattaches to the same session and scrollback shows everything that happened in the meantime. Password-protected `sudo` prompts appear natively inside the terminal, and the password you type never leaves the Pi — the admin-server proxy is a raw byte pipe that never inspects frame payloads.
+
 ## AI Content Provenance
 
 When your public agent sends a message to someone — via email, WhatsApp, Telegram, or SMS — the platform automatically includes a brief disclosure that the content was generated by AI. This is transparent and cannot be turned off.

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -90,3 +90,19 @@ If the tunnel won't reconnect, re-run the Cloudflare setup: ask Maxy "Reconnect
 If the initial Cloudflare login fails during setup, Maxy will fall back to asking you for a connection key. You can create one in the Cloudflare dashboard (Maxy will guide you through this in the browser).
 
 **If you switched Cloudflare accounts or are stuck on the wrong one:** ask Maxy "Reset my Cloudflare login and start over." This is a clean reset — Maxy clears every stored credential, then opens a fresh browser sign-in. The next sign-in binds to whichever Cloudflare account you choose, with no risk of the previous account's stored credentials silently coming back.
+
+---
+
+## Admin Terminal Stuck Disconnected After Upgrade
+
+**Symptom:** The Software Update window's terminal goes blank, says "server restart detected — reconnecting…" and never comes back, or the window sits empty after you open it.
+
+**Check:** `sudo systemctl --user status maxy-ttyd` — the unit should be `active (running)`. If it is, the admin-server proxy should reattach automatically within a few seconds.
+
+**Fix:** Restart the unit:
+
+```bash
+sudo systemctl --user restart maxy-ttyd
+```
+
+This is safe — the tmux session survives the ttyd restart because `tmux new-session -A -s maxy-pty` is idempotent. Any upgrade or other shell command still running inside the session continues uninterrupted; ttyd simply re-attaches to it. If the session itself is wedged, you can kill it explicitly with `tmux kill-session -t maxy-pty` and the next attach will create a fresh one.

package/payload/platform/plugins/memory/references/graph-primitives.md

@@ -17,11 +17,11 @@ filter in the query.
 
 For visual exploration ("can I see this graphically?", "show me the graph"),
 tell the user to open the **Graph** menu item in the burger menu — it opens
-Neo4j Browser pointed at their own brand's graph. Do not build ad-hoc HTML
-visualizations, do not start a static file server, do not `Write` an
-`.html` file and navigate Playwright to it. The one-sentence reply
-("Open the Graph menu item in the top-right — it opens a visual browser
-for your graph") is the correct answer.
+a Maxy-native force-directed view of their own brand's subgraph (Task 587).
+Do not build ad-hoc HTML visualizations, do not start a static file server,
+do not `Write` an `.html` file and navigate Playwright to it. The one-sentence
+reply ("Open the Graph menu item in the top-right — it opens a visual view
+of your graph") is the correct answer.
 
 ## When the graph tools are absent
 

package/payload/platform/templates/dotfiles/.tmux.conf

@@ -0,0 +1 @@
+set -g history-limit 50000

package/payload/platform/templates/systemd/maxy-ttyd.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=Maxy admin terminal (ttyd + tmux) — persistent PTY for admin UI
+After=default.target
+
+[Service]
+Type=simple
+# -p 7681   listen on 127.0.0.1:7681 (same-origin proxy in maxy-ui binds to it)
+# -i 127.0.0.1   reject non-loopback connections at the ttyd layer as well
+# -W        writable (allow client → server input bytes)
+# tmux new-session -A -s maxy-pty   attach if session exists, create otherwise.
+#   Lifetime = user session / device lifetime. Outlives maxy-ui restarts because
+#   this unit has no After=maxy-ui.service and no Requires= — independent.
+# -x 200 -y 50  initial geometry; xterm.js fit-addon drives runtime resizes.
+ExecStart=/usr/bin/ttyd -p 7681 -i 127.0.0.1 -W tmux new-session -A -s maxy-pty -x 200 -y 50
+Environment=TERM=xterm-256color
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target