@rubytech/create-realagent 1.0.853 → 1.0.855

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

@@ -5,11 +5,19 @@
 # token on stderr tagged `[list-cf-domains]`.
 #
 # Usage:
-#   list-cf-domains.sh [<brand>]
+#   list-cf-domains.sh <brand>
 #
-# The brand arg (default: maxy) names the `${HOME}/.${BRAND}/logs/` directory
-# where selector-drift body dumps land. The script does not read brand.json —
-# the directory is the only brand-derived path it needs.
+# Task 954: brand arg is REQUIRED — the prior silent default (string
+# fallback to "maxy" when $1 was empty) made every non-Maxy brand's CF
+# setup form fail on first use because the wrapper's child node helper
+# read the Maxy CDP port from a hardcoded fallback. Missing arg now exits
+# 1 with `phase=error reason=brand-arg-missing`.
+#
+# The wrapper also resolves and exports MAXY_PLATFORM_ROOT from its own
+# script location so the .ts helper can read `<root>/config/brand.json` for
+# the brand's `cdpPort` (Task 924's source of truth). Direct-SSH invocation
+# works because the script lives at `<install>/platform/plugins/cloudflare/
+# scripts/`, making platform root three dirs up from the resolved script.
 #
 # Runtime: Node 22's `--experimental-strip-types` runs the .ts helper
 # directly, so no tsx / playwright / ws dependency exists.
@@ -24,16 +32,29 @@ set -euo pipefail
 # Resolve symlinks before dirname — ~/list-cf-domains.sh is installed as a
 # symlink into $HOME, so the raw BASH_SOURCE[0] points at $HOME, not the
 # scripts directory where _stream-log.sh lives.
-source "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")/_stream-log.sh"
+SCRIPT_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
+source "${SCRIPT_DIR}/_stream-log.sh"
 require_stream_log_path list-cf-domains
 
-BRAND="${1:-maxy}"
+if [ "$#" -lt 1 ] || [ -z "${1:-}" ]; then
+  phase_line list-cf-domains phase=error reason=brand-arg-missing
+  exit 1
+fi
+
+BRAND="${1}"
 CONFIG_DIR=".${BRAND}"
 mkdir -p "${HOME}/${CONFIG_DIR}/logs"
 
+# MAXY_PLATFORM_ROOT is set by the systemd service when the admin server
+# spawns this script via runFormSpawn. Direct-SSH invocation has no such env
+# so derive it from the resolved script location: scripts/ → cloudflare/ →
+# plugins/ → platform → install root (three dirs up).
+if [ -z "${MAXY_PLATFORM_ROOT:-}" ]; then
+  MAXY_PLATFORM_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+fi
+
 phase_line list-cf-domains phase=script-start brand="${BRAND}" config_dir="${CONFIG_DIR}"
 
-SCRIPT_DIR="$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
 TS_ENTRY="${SCRIPT_DIR}/list-cf-domains.ts"
 
 if [ ! -f "${TS_ENTRY}" ]; then
@@ -47,15 +68,23 @@ fi
 # (124) from a helper-reported failure (1).
 HARD_TIMEOUT_SECS=30
 
-# CONFIG_DIR is consumed by the node helper when writing selector-drift dumps
-# to ~/.${BRAND}/logs/list-cf-domains-<ts>.html.
+# Env passed through:
+#  - CONFIG_DIR    — consumed by the node helper when writing selector-drift
+#                    dumps to ~/.${BRAND}/logs/list-cf-domains-<ts>.html.
+#  - BRAND         — names the brand for log lines naming the brand on
+#                    config-class failures (helper does not derive it from
+#                    CONFIG_DIR to keep the two concerns independent).
+#  - MAXY_PLATFORM_ROOT — install root the helper reads `config/brand.json`
+#                    from for `cdpPort`. Resolved above so direct-SSH
+#                    invocation matches the systemd-spawned path.
 #
 # `node --experimental-strip-types` (stable in Node 22.22) runs the .ts file
 # natively: type annotations are stripped, no enums / decorators are used, so
 # no TS type-transform is needed. `--no-warnings` suppresses the experimental
 # banner which would otherwise leak into stderr and confuse the route parser.
 set +e
-CONFIG_DIR="${CONFIG_DIR}" timeout --preserve-status --signal=TERM "${HARD_TIMEOUT_SECS}" \
+CONFIG_DIR="${CONFIG_DIR}" BRAND="${BRAND}" MAXY_PLATFORM_ROOT="${MAXY_PLATFORM_ROOT}" \
+  timeout --preserve-status --signal=TERM "${HARD_TIMEOUT_SECS}" \
   node --experimental-strip-types --no-warnings "${TS_ENTRY}"
 EXIT_CODE=$?
 set -e

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

@@ -42,19 +42,29 @@
 //            "selector drift" from "empty account" — both shapes arrive via
 //            stdout).
 
-import { appendFileSync } from "node:fs";
+import { appendFileSync, readFileSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 
-// CDP host/port default to the VNC Chromium's localhost bind; env overrides
-// exist solely so the vitest regression under platform/ui/__tests__ can force
-// a deterministic ECONNREFUSED (point at 127.0.0.1:1 — RFC 6335 reserved,
-// guaranteed-refused on every platform) without depending on whether a dev
-// machine happens to have VNC Chromium running on 9222.
-const CDP_HOST = process.env.LIST_CF_DOMAINS_CDP_HOST ?? "127.0.0.1";
-const CDP_PORT = Number(process.env.LIST_CF_DOMAINS_CDP_PORT ?? 9222);
+// CDP endpoint is resolved lazily inside `main()` so importing this module
+// for in-process tests (`scrapeCurrentPage` / `scrapeDomains` under JSDOM)
+// does not require an installed brand on disk.
+//
+// Task 954 source-of-truth contract:
+//   Runtime: brand.json `cdpPort` at `${MAXY_PLATFORM_ROOT}/config/brand.json`
+//     is authoritative. Wrapper exports MAXY_PLATFORM_ROOT and BRAND. Missing
+//     env / file / field → loud-fail with one of three named reasons. The
+//     pre-Task-954 silent CDP-port default made every non-Maxy brand fail
+//     `cdp-unreachable` because the helper hit Maxy's port instead of the
+//     brand's; Task 787 / NEO4J_URI sets the precedent that runtime config
+//     never falls back silently.
+//
+//   Test overrides: when BOTH `LIST_CF_DOMAINS_CDP_HOST` and
+//     `LIST_CF_DOMAINS_CDP_PORT` are set, they win over brand.json. The
+//     existing ECONNREFUSED vitest forces `127.0.0.1:1` (RFC 6335-reserved)
+//     this way without an installed brand. Production never sets these.
 
 // Phase budgets total 30s (enforced by the shell wrapper's `timeout`).
 // Individual steps get sub-budgets so an early stall does not eat the
@@ -72,7 +82,14 @@ type Reason =
   | "not-signed-in"
   | "navigate-failed"
   | "table-wait-timeout"
-  | "runtime-error";
+  | "runtime-error"
+  // Task 954 — config-class failures. The first three short-circuit before
+  // any CDP work begins; the route maps them to `field='config'` so the
+  // form renders a config-card naming the brand + path instead of a Retry
+  // button (retrying re-fires the same wrongly-resolved spawn — Task 787
+  // pattern).
+  | "brand-config-missing"
+  | "cdp-port-unresolved";
 
 // Sticky flag: once a stream-log write fails (EACCES, ENOENT, …), skip
 // subsequent file writes for the rest of this process. Repeated appends to an
@@ -120,11 +137,85 @@ function die(reason: Reason, detail = ""): never {
   process.exit(1);
 }
 
-async function cdpVersion(): Promise<void> {
+interface CdpEndpoint {
+  host: string;
+  port: number;
+  source: "env-override" | "brand.json";
+}
+
+// Task 954 — single source of truth for the CDP endpoint. Called once from
+// `main()` so the JSDOM scrape test (which imports `scrapeCurrentPage`
+// directly without invoking `main`) does not need an installed brand.
+function resolveCdpEndpoint(): CdpEndpoint {
+  const envHost = process.env.LIST_CF_DOMAINS_CDP_HOST;
+  const envPortRaw = process.env.LIST_CF_DOMAINS_CDP_PORT;
+  if (envHost !== undefined && envPortRaw !== undefined) {
+    const envPort = Number(envPortRaw);
+    if (!Number.isInteger(envPort) || envPort <= 0 || envPort > 65535) {
+      die(
+        "cdp-port-unresolved",
+        `LIST_CF_DOMAINS_CDP_PORT="${envPortRaw}" is not a valid integer port`,
+      );
+    }
+    return { host: envHost, port: envPort, source: "env-override" };
+  }
+
+  const brand = process.env.BRAND;
+  if (!brand) {
+    die(
+      "brand-config-missing",
+      "BRAND env var not set by wrapper — refusing to guess brand identity",
+    );
+  }
+  const platformRoot = process.env.MAXY_PLATFORM_ROOT;
+  if (!platformRoot) {
+    die(
+      "brand-config-missing",
+      "MAXY_PLATFORM_ROOT env var not set — wrapper must export it before spawn",
+    );
+  }
+  const brandPath = resolve(platformRoot, "config", "brand.json");
+  let raw: string;
+  try {
+    raw = readFileSync(brandPath, "utf-8");
+  } catch (err) {
+    // Distinct emission (not via `die`) so the path is named on the same line
+    // — config-card rendering on the route side keys off it.
+    logPhase(
+      `phase=error reason=brand-config-missing path=${brandPath} detail="${(err instanceof Error ? err.message : String(err)).replace(/"/g, "'").slice(0, 200)}"`,
+    );
+    process.exit(1);
+  }
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(raw) as Record<string, unknown>;
+  } catch (err) {
+    logPhase(
+      `phase=error reason=brand-config-missing path=${brandPath} detail="parse failed: ${(err instanceof Error ? err.message : String(err)).replace(/"/g, "'").slice(0, 160)}"`,
+    );
+    process.exit(1);
+  }
+  const cdpPort = parsed.cdpPort;
+  if (typeof cdpPort !== "number" || !Number.isInteger(cdpPort) || cdpPort <= 0 || cdpPort > 65535) {
+    // Names the keys actually present so a schema-drift incident surfaces
+    // immediately ("oh, brand.json renamed `cdpPort` to `cdp_port` in r123").
+    const keys = Object.keys(parsed).join(",");
+    logPhase(
+      `phase=error reason=cdp-port-unresolved brand=${brand} json_keys=${keys}`,
+    );
+    process.exit(1);
+  }
+  // Host stays 127.0.0.1 on the runtime path — vnc.sh binds Chromium's CDP
+  // server to localhost only, by construction. brand.json carries the port,
+  // not the host, because the host has never varied across brands.
+  return { host: "127.0.0.1", port: cdpPort, source: "brand.json" };
+}
+
+async function cdpVersion(host: string, port: number): 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 });
+    const res = await fetch(`http://${host}:${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));
@@ -138,12 +229,12 @@ interface CdpTarget {
   webSocketDebuggerUrl: string;
 }
 
-async function createTarget(): Promise<CdpTarget> {
+async function createTarget(host: string, port: number): 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`;
+  const endpoint = `http://${host}:${port}/json/new?about:blank`;
   let res: Response;
   try {
     res = await fetch(endpoint, { method: "PUT", signal: AbortSignal.timeout(CONNECT_TIMEOUT_MS) });
@@ -158,9 +249,9 @@ async function createTarget(): Promise<CdpTarget> {
   return target as CdpTarget;
 }
 
-async function closeTarget(id: string): Promise<void> {
+async function closeTarget(host: string, port: number, id: string): Promise<void> {
   try {
-    await fetch(`http://${CDP_HOST}:${CDP_PORT}/json/close/${id}`, {
+    await fetch(`http://${host}:${port}/json/close/${id}`, {
       signal: AbortSignal.timeout(CONNECT_TIMEOUT_MS),
     });
   } catch {
@@ -602,19 +693,20 @@ async function waitForDocumentReady(cdp: CdpClient): Promise<void> {
 }
 
 async function main(): Promise<void> {
-  logPhase(`phase=script-start cdp=${CDP_HOST}:${CDP_PORT}`);
+  const endpoint = resolveCdpEndpoint();
+  logPhase(`phase=script-start cdp=${endpoint.host}:${endpoint.port} source=${endpoint.source}`);
 
-  await cdpVersion();
+  await cdpVersion(endpoint.host, endpoint.port);
   logPhase(`phase=cdp-connect result=ok`);
 
-  const target = await createTarget();
+  const target = await createTarget(endpoint.host, endpoint.port);
   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);
+    await closeTarget(endpoint.host, endpoint.port, target.id);
     die("ws-connect-failed", err instanceof Error ? err.message : String(err));
   }
 
@@ -643,7 +735,7 @@ async function main(): Promise<void> {
     die("runtime-error", err instanceof Error ? err.message : String(err));
   } finally {
     cdp.close();
-    await closeTarget(target.id);
+    await closeTarget(endpoint.host, endpoint.port, target.id);
   }
 }
 

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

@@ -9,6 +9,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. When the scrape returns an unexpected count (e.g. 1 on a two-zone account), the stream log's per-poll `phase=dom-scrape-poll n=<k> count=<n> domains=[…]` trajectory + the on-disk HTML dump at `~/{configDir}/logs/list-cf-domains-<ts>-count<n>-<mode>-pid<pid>.html` (earlier platform fixes — written on every scrape outcome, not just empty ones) give the operator everything they need to triage the cause without re-running. |
+| **CDP port the scrape attaches to** | `brand.json` (`cdpPort`, stamped at install time) — the same brand-scoped port `vnc.sh` binds Chromium to. `list-cf-domains.sh <brand>` requires the brand arg; the helper reads `${MAXY_PLATFORM_ROOT}/config/brand.json` (no silent default). Missing brand arg, missing brand.json, or missing `cdpPort` field each exit 1 with one of three named reasons (`brand-arg-missing`, `brand-config-missing`, `cdp-port-unresolved`); the route maps all three to `field=config` so the form renders a config card naming the brand instead of a Retry button — retrying would re-fire the same wrongly-resolved spawn. |
 | **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

@@ -115,6 +115,8 @@ The installer detects this case during system-dependency setup and replaces the
 
 The post-install acceptance gate at `platform/scripts/test-laptop-vnc-boot.sh` runs four checks: the configured Chromium realpath is non-snap, the path is absolute and executable, the per-brand CDP port returns Chromium version JSON, and the VNC boot log ends with `VNC + browser stack running` with no preceding `Chromium failed to start`. The gate runs automatically at the end of every install on Linux; manual invocation is `MAXY_PLATFORM_ROOT=<install-dir>/platform <install-dir>/platform/scripts/test-laptop-vnc-boot.sh`.
 
+A separate operator-side harness at `platform/scripts/installer-device-verify.sh <published-version>` runs after every npm publish to confirm the installer reaches a terminal-success marker on each device in the operator's manifest. Two markers are accepted because the installer's CDP probe behaves differently per `DISPLAY_MODE`: `Browser automation ready (CDP connected)` on Pi (virtual display, persistent Chromium) and `[cdp-check] skipped reason=native-display` on laptop (native display, on-demand Chromium). Either is a pass. The harness is operator-only — end users do not run it.
+
 ## Running multiple brands on one device
 
 A single Pi or laptop can host more than one brand (for example Maxy and Real Agent) side by side. Each brand runs as its own service on its own port, with its own install directory and its own data. Installing one brand does not touch the other.

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

@@ -60,6 +60,8 @@ When the text field is empty, a microphone button appears in place of the send b
 
 Voice recording requires a secure connection (HTTPS). When accessing {{productName}} over the local network via HTTP, use the tunnel URL for voice notes.
 
+You can also drop, paste, or pick an audio file (`.opus`, `.ogg`, `.m4a`, `.mp3`, `.wav`, `.webm`) into the chat composer — for example a voice note forwarded from WhatsApp. The file is transcribed the same way the in-browser recording is, and only the transcript reaches {{productName}}; the audio itself is discarded after transcription.
+
 ## What {{productName}} Remembers
 
 {{productName}} maintains a memory graph of everything important: contacts, conversations, preferences, relationships, and context. When you tell {{productName}} something, it stores it. When you ask about something later, it retrieves it.

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

@@ -65,7 +65,7 @@ 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.
 
-The admin interface is a three-pane layout: a sidebar on the left with your brand mark, navigation (Chat, People, Agents, Projects, Tasks, Artefacts), and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu — holding the surface side-by-side with the conversation so the chat stays live while you work in it. The sidebar's nav rows swap the list view in place — Chat shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). The People, Agents, and Tasks rows are graph shortcuts: clicking each opens the artefact-pane Graph filtered to every Person, every public Agent, or every Task in your account respectively, with no side-list — the graph itself is the result. Public agents become first-class graph entities the moment you create them, with edges to their IDENTITY/SOUL/KNOWLEDGE files, edges to every knowledge document they have access to, and edges from every conversation they have handled, so a single Agents click reveals the whole shape of who knows what and who has been talking to whom. Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable — type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood — clicking a second project swaps the focus rather than stacking on top. The chat / artefact divider is drag-resizable — drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat / artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On phones (<720px) the sidebar slides in as a drawer from the left when you tap the menu icon in the chat header.
+The admin interface is a three-pane layout: a sidebar on the left with your brand mark, navigation (Chat, People, Agents, Projects, Tasks, Artefacts), and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu — holding the surface side-by-side with the conversation so the chat stays live while you work in it. The sidebar's nav rows swap the list view in place — Chat shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). The People, Agents, and Tasks rows are graph shortcuts: clicking each opens the artefact-pane Graph filtered to every Person, every public Agent, or every Task in your account respectively, with no side-list — the graph itself is the result. Public agents become first-class graph entities the moment you create them, with edges to their IDENTITY/SOUL/KNOWLEDGE files, edges to every knowledge document they have access to, and edges from every conversation they have handled, so a single Agents click reveals the whole shape of who knows what and who has been talking to whom. Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable — type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood — clicking a second project swaps the focus rather than stacking on top. The chat / artefact divider is drag-resizable — drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat / artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On phones (<720px) the sidebar slides in as a drawer from the left when you tap the menu icon in the chat header. When the sidebar is collapsed to the 56px icon rail, clicking the Artefacts icon expands the rail back open so the artefact list is visible — the row was previously a silent no-op in collapsed state.
 
 Page titles are brand-aware: the browser tab shows your product name (e.g. `Real Agent` instead of `Maxy`) on every shell — chat, graph, and data — so a non-default brand never leaks the default name in tab strips or browser history.
 

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

@@ -1,5 +1,13 @@
 # Troubleshooting
 
+## Browser navigation to a local file (`file://`) used to time out for two minutes
+
+**Symptom:** Older versions of the platform's admin agent would attempt `browser_navigate file:///path/to.html`, hit Playwright's silent two-minute timeout, then guess fixed ports (8080 / 3000 / 8000 / 9000) and report `ERR_CONNECTION_REFUSED` for each before someone manually started a local HTTP server.
+
+**Resolution shipped:** The `playwright-file-guard` PreToolUse hook (admin plugin) intercepts `file://` URLs, picks a free loopback port, backgrounds `python3 -m http.server` rooted at the file's parent directory, connect-verifies the server within one second, and rewrites the tool call's URL to `http://127.0.0.1:<port>/<basename>` before Playwright sees it. The agent never sees the rewrite. Stale server processes are reaped opportunistically on every hook invocation (1 h threshold, gated by a `ps` cmdline check that won't kill a reused PID).
+
+**Diagnose if it ever recurs:** grep the per-conversation stream log for `[playwright-file-guard] action=`. One `action=rewrite original=file://… port=<n> pid=<m>` line per file:// navigate is the healthy signal. `action=fail reason=<r>` indicates the hook tried to rewrite but failed open (Playwright handled the original URL); the reason field names the cause (`python3-missing`, `port-pick-failed`, `server-not-ready`, `file-not-found`, `spawn-failed`). The `cleanup` argv on the hook script can be invoked manually to sweep `/tmp/playwright-file-guard.*.pid`; the suite at `platform/plugins/admin/hooks/__tests__/playwright-file-guard.test.sh` exercises every path.
+
 ## First user-domain write rejected by `[graph-write-gate] reject reason=no-admin-user`
 
 **Symptom:** Admin chat reports "couldn't save that — set up your business profile first" or `[graph-write-gate] reject reason=no-admin-user` appears in `server.log` on the operator's first non-bootstrap write (a website, service, opening hours, etc.). Reproduces on Minimal-onboarded installs from before the seed-stamping fix shipped.
@@ -64,6 +72,8 @@ tail -200 ~/.maxy/logs/maxy-ui.log | rg '\[remote-auth\].*resolvedKind='
 
 **Agent searches the filesystem after uploading a zip.** If you uploaded a zip and the agent burns several turns running `find` / `Glob` instead of unzipping, that is the symptom of the recovery-retry attachment-context regression (now closed by the recovery context preservation contract in `.docs/agents.md`). Greppable confirmation is the `[context-overflow-recovery] retry … attachmentsCarried=<n>` line in the conversation stream log. If you see `[context-overflow-recovery] WARN attachment-context-lost`, the regression has returned — surface to support.
 
+
+**A turn rendered in chat is missing on next page-refresh.** Pre-the 2026-05-07 mandate this was a class of silent failure — Neo4j persists were wrapped in a no-op error catch and a write that threw left the artefact "rendered then disappeared on resume". The 2026-05-07 mandate makes JSONL canonical: the resume route reads the SDK transcript file at `~/.claude/projects/<project-key>/<sessionId>.jsonl` first, supplements from Neo4j, and triggers async heal-on-resume writes for any turn the JSONL has but Neo4j does not. So a refreshed conversation always renders what the SDK saw, regardless of write outcome. If a heal write itself fails, the chat shows a top-of-conversation banner naming the count; if every heal succeeds the resume is silent and the missing rows are quietly restored to Neo4j. Greppable post-deploy invariants in the per-conversation stream log (`logs/claude-agent-stream-<conversationId>.log`): `[admin-resume] reason=<…> source=<jsonl|jsonl-missing|neo4j-only>` (one per resume), `[admin-persist] convId=<8> writer=<…> outcome=<ok|fail|skip>` (per persist site), `[admin-persist-heal] convId=<8> turnIndex=<n> outcome=<ok|fail>` (per heal write). To force-audit a specific conversation against its Neo4j projection without re-executing it, run `tsx platform/scripts/admin-persist-audit.ts --conversation-id=<uuid> --account-id=<uuid> --session-id=<uuid>` — non-zero exit + per-divergence `[admin-persist-audit] expected=<message|component> missing reason=neo4j-row-absent` lines name what would have been silently lost pre-mandate.
 **Wrong Claude account answering on a multi-brand device.** On a host running both Maxy and Real Agent, each brand's admin agent reads its own `~/${brand.configDir}/.claude/.credentials.json`; there is no longer a shared `~/.claude/` thrashing them against one another. If a brand reports auth failures or appears to be operating against the wrong subscription, check three things:
 1. `grep "\[claude-auth\] init" ~/.${brand}/logs/server.log | tail -1` — the resolved path must end with `~/.${brand}/.claude/.credentials.json`. If a `[claude-auth] WARN cross-brand-path-detected` line is present, the runtime is still pointing at `~/.claude/`; the brand main service did not pick up the `Environment=CLAUDE_CONFIG_DIR=` setting (re-run the brand installer to refresh the unit file).
 2. `diff <(jq .claudeAiOauth.accessToken ~/.maxy/.claude/.credentials.json) <(jq .claudeAiOauth.accessToken ~/.realagent/.claude/.credentials.json)` — must be non-empty after each brand's operator has run `claude /login` against distinct Anthropic accounts; if it's empty, both brands are still logged in to the same account (operator action, not a code bug).

package/payload/platform/scripts/admin-persist-audit.ts

@@ -0,0 +1,191 @@
+#!/usr/bin/env -S node --loader tsx
+/**
+ * Task 940 — admin persist audit harness.
+ *
+ * Compares JSONL canonical state against Neo4j projection for a given
+ * conversationId. Prints one [admin-persist-audit] divergence line per
+ * (sdkTurnUuid, expected) gap; non-zero exit on any mismatch. Designed to
+ * run against an operator-supplied stream log fixture WITHOUT re-executing
+ * the live session — JSONL is the only ground truth this script consults.
+ *
+ * Usage:
+ *   tsx platform/scripts/admin-persist-audit.ts \
+ *       --conversation-id=<uuid> \
+ *       --account-id=<uuid> \
+ *       --jsonl=<path>            # optional override; otherwise resolved from accountId+sessionId
+ *       --session-id=<uuid>       # required if --jsonl not provided
+ *
+ * Exit codes:
+ *   0 = no divergences
+ *   1 = at least one Message or Component absent from Neo4j
+ *   2 = invocation error (missing args, file unreadable, Neo4j unreachable)
+ *
+ * Why audit-only and not also auto-heal: the heal-on-resume writer at
+ * server/routes/admin/sessions.ts handles the live path. This harness exists
+ * for forensic investigation against operator-supplied JSONLs (e.g. the
+ * 2026-05-07 stream log that motivated this task) where the live session
+ * has long since terminated.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import process from "node:process";
+
+import { replayJsonl, resolveJsonlPath } from "../ui/app/lib/claude-agent/jsonl-replay";
+import { ACCOUNTS_DIR } from "../ui/app/lib/claude-agent/account";
+import { getRecentMessages, getSession } from "../ui/app/lib/neo4j-store";
+import { PERSISTENT_COMPONENTS } from "../lib/persistent-components/src/index";
+
+interface Args {
+  conversationId: string;
+  accountId: string;
+  jsonlPath: string;
+}
+
+function parseArgs(argv: string[]): Args | { error: string } {
+  const out: Partial<Args> = {};
+  let sessionId: string | undefined;
+  let jsonlOverride: string | undefined;
+  for (const a of argv) {
+    const m = a.match(/^--([a-z-]+)=(.+)$/);
+    if (!m) continue;
+    const [, key, val] = m;
+    if (key === "conversation-id") out.conversationId = val;
+    else if (key === "account-id") out.accountId = val;
+    else if (key === "session-id") sessionId = val;
+    else if (key === "jsonl") jsonlOverride = val;
+  }
+  if (!out.conversationId) return { error: "--conversation-id required" };
+  if (!out.accountId) return { error: "--account-id required" };
+  if (jsonlOverride) {
+    out.jsonlPath = resolve(jsonlOverride);
+  } else if (sessionId) {
+    const accountDir = resolve(ACCOUNTS_DIR, out.accountId);
+    out.jsonlPath = resolveJsonlPath(homedir(), accountDir, sessionId);
+  } else {
+    return { error: "either --jsonl or --session-id required" };
+  }
+  return out as Args;
+}
+
+async function main(): Promise<number> {
+  const parsed = parseArgs(process.argv.slice(2));
+  if ("error" in parsed) {
+    console.error(`[admin-persist-audit] usage error: ${parsed.error}`);
+    return 2;
+  }
+  const { conversationId, jsonlPath } = parsed;
+
+  if (!existsSync(jsonlPath)) {
+    console.error(`[admin-persist-audit] jsonl absent path=${jsonlPath} convId=${conversationId.slice(0, 8)}`);
+    return 2;
+  }
+
+  // JSONL replay — derives the canonical message stream and the expected
+  // component side-effects.
+  const replay = replayJsonl(jsonlPath);
+  if (replay.malformedLines > 0) {
+    console.error(`[admin-persist-audit] jsonl-malformed-lines convId=${conversationId.slice(0, 8)} count=${replay.malformedLines}`);
+  }
+
+  // Neo4j projection — what the resume route would have rendered pre-940.
+  let neo4j: Awaited<ReturnType<typeof getRecentMessages>>;
+  try {
+    neo4j = await getRecentMessages(conversationId, 1000);
+  } catch (err) {
+    console.error(`[admin-persist-audit] neo4j-read-failed convId=${conversationId.slice(0, 8)} reason=${err instanceof Error ? err.message : String(err)}`);
+    return 2;
+  }
+
+  // Build a set of (role, content) keys present in Neo4j for fast lookup.
+  // Same matching key the resume route uses, for parity.
+  const neo4jByKey = new Map<string, typeof neo4j[number]>();
+  for (const n of neo4j) neo4jByKey.set(`${n.role}\x1f${n.content}`, n);
+
+  let divergences = 0;
+  for (const j of replay.messages) {
+    const key = `${j.role}\x1f${j.content}`;
+    const match = neo4jByKey.get(key);
+    if (!match) {
+      // Whole message absent from Neo4j.
+      console.log(`[admin-persist-audit] convId=${conversationId.slice(0, 8)} sdkTurnUuid=${j.messageId.slice(0, 8)} expected=message missing reason=neo4j-row-absent`);
+      divergences += 1;
+      // Each missing message implies its components are also missing — emit
+      // one divergence line per absent component for forensic completeness.
+      for (const c of j.components) {
+        console.log(`[admin-persist-audit] convId=${conversationId.slice(0, 8)} sdkTurnUuid=${j.messageId.slice(0, 8)} expected=component component_name=${c.name} ordinal=${c.ordinal} missing reason=neo4j-row-absent`);
+        divergences += 1;
+      }
+      continue;
+    }
+    // Message exists; cross-check component count (Neo4j carries components
+    // as siblings of :Message via :HAS_COMPONENT).
+    const neoComps = match.components ?? [];
+    if (neoComps.length < j.components.length) {
+      for (let i = neoComps.length; i < j.components.length; i++) {
+        const c = j.components[i];
+        console.log(`[admin-persist-audit] convId=${conversationId.slice(0, 8)} sdkTurnUuid=${j.messageId.slice(0, 8)} expected=component component_name=${c.name} ordinal=${c.ordinal} missing reason=neo4j-row-absent`);
+        divergences += 1;
+      }
+    }
+  }
+
+  // Task 942 — every PERSISTENT_COMPONENTS :Component row must have a
+  // sibling :KnowledgeDocument with a matching attachmentId. Two failure
+  // modes: (a) live writer succeeded the :Component CREATE but the
+  // sibling :KnowledgeDocument MERGE didn't fire (theoretical — they're
+  // in the same tx, so this is only possible if the row is pre-942 or if
+  // the FOREACH ran on a null attachmentId); (b) the disk-write failed
+  // mid-render and `c.attachmentId` is null but the artefact bytes might
+  // be recoverable from `c.data`. Both cases are surfaced as `kd-row-absent`
+  // — the operator runs component-knowledgedoc-backfill.ts to materialise
+  // the projection.
+  const projectionSession = getSession();
+  try {
+    const componentRowsResult = await projectionSession.run(
+      `MATCH (m:Message {conversationId: $conversationId})-[:HAS_COMPONENT]->(c:Component)
+       WHERE c.name IN $names
+       OPTIONAL MATCH (k:KnowledgeDocument {accountId: c.accountId, attachmentId: c.attachmentId})
+         WHERE c.attachmentId IS NOT NULL
+       RETURN c.componentId AS componentId,
+              c.name AS componentName,
+              c.accountId AS accountId,
+              c.attachmentId AS attachmentId,
+              k IS NOT NULL AS hasProjection`,
+      { conversationId, names: Array.from(PERSISTENT_COMPONENTS) },
+    );
+
+    for (const record of componentRowsResult.records) {
+      const componentId = record.get("componentId") as string;
+      const componentName = record.get("componentName") as string;
+      const attachmentId = record.get("attachmentId") as string | null;
+      const hasProjection = record.get("hasProjection") === true;
+      if (!attachmentId) {
+        console.log(`[admin-persist-audit] convId=${conversationId.slice(0, 8)} componentId=${componentId.slice(0, 8)} expected=knowledgedoc component_name=${componentName} missing reason=empty-attachment-id`);
+        divergences += 1;
+        continue;
+      }
+      if (!hasProjection) {
+        console.log(`[admin-persist-audit] convId=${conversationId.slice(0, 8)} componentId=${componentId.slice(0, 8)} expected=knowledgedoc component_name=${componentName} missing reason=kd-row-absent attachmentId=${attachmentId.slice(0, 8)}`);
+        divergences += 1;
+      }
+    }
+  } finally {
+    await projectionSession.close();
+  }
+
+  if (divergences === 0) {
+    console.log(`[admin-persist-audit] convId=${conversationId.slice(0, 8)} jsonlMessages=${replay.messages.length} neo4jMessages=${neo4j.length} divergences=0 status=ok`);
+    return 0;
+  }
+  console.log(`[admin-persist-audit] convId=${conversationId.slice(0, 8)} jsonlMessages=${replay.messages.length} neo4jMessages=${neo4j.length} divergences=${divergences} status=mismatch`);
+  return 1;
+}
+
+main()
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(`[admin-persist-audit] crashed: ${err instanceof Error ? err.stack : String(err)}`);
+    process.exit(2);
+  });