@rubytech/create-realagent 1.0.847 → 1.0.850

package/dist/__tests__/port-canonicalisation.test.js

@@ -32,6 +32,7 @@ function makeUnitFile(port, internal) {
         rfbPort: 5900,
         websockifyPort: 6080,
         cdpPort: 9222,
+        chromiumBin: "/usr/bin/chromium",
     });
 }
 function makeEdgeFile(edgePort) {

package/dist/__tests__/snap-chromium.test.js

@@ -0,0 +1,115 @@
+// Task 929 — pure-decision grid for snap-chromium.ts.
+//
+// Locks the resolver branches that decide whether the laptop installer must
+// replace snap-confined Chromium with Google Chrome stable. Inputs are passed
+// directly so no spawn/fs mocking is needed — every test exercises the pure
+// decision with realpath fixtures captured from real devices (Ubuntu Noble
+// laptop and Debian Bookworm Pi).
+//
+// Runs via Node's built-in test runner; no vitest dependency. Compiles to
+// dist/__tests__/snap-chromium.test.js alongside the rest of the package so
+// `node --test dist/__tests__/*.test.js` picks it up after build.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { decideChromiumAction, isSnapConfinedPath } from "../snap-chromium.js";
+// ---------------------------------------------------------------------------
+// isSnapConfinedPath — `readlink -f` outputs from real devices.
+// ---------------------------------------------------------------------------
+test("isSnapConfinedPath: laptop noble realpath /usr/bin/snap is snap-confined", () => {
+    assert.equal(isSnapConfinedPath("/usr/bin/snap"), true);
+});
+test("isSnapConfinedPath: nested snap revision path is snap-confined", () => {
+    assert.equal(isSnapConfinedPath("/snap/chromium/2924/usr/lib/chromium/chromium"), true);
+});
+test("isSnapConfinedPath: snap wrapper bin path is snap-confined", () => {
+    assert.equal(isSnapConfinedPath("/snap/bin/chromium"), true);
+});
+test("isSnapConfinedPath: bookworm /usr/bin/chromium realpath is non-snap", () => {
+    assert.equal(isSnapConfinedPath("/usr/lib/chromium/chromium"), false);
+});
+test("isSnapConfinedPath: google-chrome-stable realpath is non-snap", () => {
+    assert.equal(isSnapConfinedPath("/opt/google/chrome/google-chrome"), false);
+});
+test("isSnapConfinedPath: empty / null guards return false", () => {
+    assert.equal(isSnapConfinedPath(""), false);
+});
+// ---------------------------------------------------------------------------
+// decideChromiumAction — the six branches.
+// ---------------------------------------------------------------------------
+test("darwin: action=skip-non-linux, no resolvedPath", () => {
+    const out = decideChromiumAction({
+        platform: "darwin",
+        whichChromium: "/usr/bin/chromium",
+        realpathChromium: "/usr/bin/chromium",
+        whichGoogleChrome: null,
+        realpathGoogleChrome: null,
+    });
+    assert.equal(out.action, "skip-non-linux");
+    assert.equal(out.resolvedPath, null);
+});
+test("linux + non-snap chromium (Pi Bookworm): action=use chromium realpath", () => {
+    const out = decideChromiumAction({
+        platform: "linux",
+        whichChromium: "/usr/bin/chromium",
+        realpathChromium: "/usr/lib/chromium/chromium",
+        whichGoogleChrome: null,
+        realpathGoogleChrome: null,
+    });
+    assert.equal(out.action, "use");
+    assert.equal(out.resolvedPath, "/usr/bin/chromium");
+});
+test("linux + snap-confined chromium (laptop Noble), no google-chrome: action=install-google-chrome", () => {
+    const out = decideChromiumAction({
+        platform: "linux",
+        whichChromium: "/usr/bin/chromium",
+        realpathChromium: "/usr/bin/snap",
+        whichGoogleChrome: null,
+        realpathGoogleChrome: null,
+    });
+    assert.equal(out.action, "install-google-chrome");
+    assert.equal(out.resolvedPath, null);
+    assert.match(out.reason, /snap/);
+});
+test("linux + snap chromium + google-chrome already installed: action=use google-chrome", () => {
+    const out = decideChromiumAction({
+        platform: "linux",
+        whichChromium: "/usr/bin/chromium",
+        realpathChromium: "/usr/bin/snap",
+        whichGoogleChrome: "/usr/bin/google-chrome-stable",
+        realpathGoogleChrome: "/opt/google/chrome/google-chrome",
+    });
+    assert.equal(out.action, "use");
+    assert.equal(out.resolvedPath, "/usr/bin/google-chrome-stable");
+});
+test("linux + chromium absent + no google-chrome: action=fail", () => {
+    const out = decideChromiumAction({
+        platform: "linux",
+        whichChromium: null,
+        realpathChromium: null,
+        whichGoogleChrome: null,
+        realpathGoogleChrome: null,
+    });
+    assert.equal(out.action, "fail");
+    assert.equal(out.resolvedPath, null);
+});
+test("linux + chromium absent + google-chrome present: action=use google-chrome", () => {
+    const out = decideChromiumAction({
+        platform: "linux",
+        whichChromium: null,
+        realpathChromium: null,
+        whichGoogleChrome: "/usr/bin/google-chrome-stable",
+        realpathGoogleChrome: "/opt/google/chrome/google-chrome",
+    });
+    assert.equal(out.action, "use");
+    assert.equal(out.resolvedPath, "/usr/bin/google-chrome-stable");
+});
+test("linux + snap chromium + google-chrome installed but ALSO under /snap (defensive): action=install-google-chrome", () => {
+    const out = decideChromiumAction({
+        platform: "linux",
+        whichChromium: "/usr/bin/chromium",
+        realpathChromium: "/usr/bin/snap",
+        whichGoogleChrome: "/snap/bin/google-chrome",
+        realpathGoogleChrome: "/snap/google-chrome/current/usr/bin/google-chrome",
+    });
+    assert.equal(out.action, "install-google-chrome");
+});

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, readdirSync, appendFileSync, openSync, closeSync, chmodSync, symlinkSync, unlinkSync, lstatSync, statSync, readlinkSync, accessSync, constants as fsConstants } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, readdirSync, appendFileSync, openSync, closeSync, chmodSync, symlinkSync, unlinkSync, lstatSync, statSync, readlinkSync, realpathSync, accessSync, constants as fsConstants } from "node:fs";
 import { resolve, join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import { resolveInstallPortFromFs, buildMaxyUnitFile } from "./port-resolution.js";
@@ -10,6 +10,7 @@ import { requireSupportedPlatform } from "./platform-detect.js";
 import { renderPlist } from "./launchd-plist.js";
 import { installAllBrewPackages } from "./brew-install.js";
 import { parseSwVers, isSupportedMacosVersion } from "./macos-version.js";
+import { decideChromiumAction, isSnapConfinedPath } from "./snap-chromium.js";
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive all brand-specific installation values.
 // The bundler stamps brand.json into the payload at build time.
@@ -42,6 +43,17 @@ const KNOWN_BRAND_HOSTNAMES = ["maxy", "realagent", "maxy-2", "maxy-3", "maxy-4"
 // The device's actual hostname — may differ from BRAND.hostname if the user customized it.
 // Updated by installSystemDeps() after hostname setup; used for user-facing URLs.
 let DEVICE_HOSTNAME = BRAND.hostname;
+// Task 929 — absolute path to the non-snap Chromium binary chosen during
+// installSystemDeps(). Defaults to /usr/bin/chromium so non-Linux installs
+// (which never call ensureNonSnapChromium) and the systemd unit's
+// PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH still see a sensible value. On Linux,
+// installSystemDeps() always overwrites this — either /usr/bin/chromium (Pi
+// Bookworm: real .deb) or /usr/bin/google-chrome-stable (Ubuntu Noble laptop:
+// snap-confined chromium replaced). Read by writeChromiumBinaryPathFile()
+// and threaded into buildMaxyUnitFile() so the chromium-binary.path config
+// file, the systemd unit's PLAYWRIGHT env var, and vnc.sh's runtime resolver
+// all agree on one absolute path.
+let RESOLVED_CHROMIUM_BIN = "/usr/bin/chromium";
 // npm flags tuned for Raspberry Pi — reduce parallelism, increase patience
 const NPM_NET_FLAGS = [
     "--fetch-retries=5",
@@ -397,6 +409,179 @@ function setMacosHostnameViaScutil(hostname) {
     }
     console.log(`  [scutil] HostName=${hostname} LocalHostName=${hostname} ComputerName=${hostname} set ok`);
 }
+/**
+ * Task 929 — detect snap-confined Chromium on Linux and install Google Chrome
+ * stable as the non-snap replacement. Runs after `installAptGroup("VNC stack")`
+ * inside `installSystemDeps`. Resolution rules live in `snap-chromium.ts`
+ * (pure decision); this wrapper does the spawnSync + apt-repo writes + post-
+ * install gate. Skipped on darwin (Maxy uses Playwright-managed Chromium per
+ * brew-install.ts) — RESOLVED_CHROMIUM_BIN keeps its `/usr/bin/chromium`
+ * default which is unused on darwin (no systemd unit).
+ *
+ * Detection: `command -v chromium` + `realpath`; an extra probe for
+ * `google-chrome-stable` covers re-run installs where a previous run already
+ * landed Chrome. Snap detection is the literal `snap` segment in the realpath
+ * (see isSnapConfinedPath in snap-chromium.ts) — covers the three real-world
+ * shapes (`/snap/bin/chromium`, `/snap/<rev>/usr/...`, `/usr/bin/snap` which
+ * is the snap launcher binary that `readlink -f` terminates at on Noble).
+ *
+ * Replacement: Google's signed apt repo (cryptographic verification via
+ * `signed-by=` GPG key) — the canonical pinned-deterministic source for
+ * Chrome stable. Pinning a specific Chrome version would require an out-of-
+ * band SHA-bump cadence and contradicts the apt-repo trust model.
+ *
+ * Post-install gate: spawn the resolved binary headless against a throwaway
+ * profile dir under persistDir, assert exit 0. The AppArmor denial that
+ * triggered Task 929 was on SingletonLock writes which `--headless=new` still
+ * attempts, so the headless probe fires the same EACCES path that production
+ * VNC headed launches do — closing the post-fix-sibling-audit-skipped gap.
+ */
+function ensureNonSnapChromium() {
+    if (process.platform !== "linux") {
+        logFile(`  ensureNonSnapChromium skipped: platform=${process.platform}`);
+        return;
+    }
+    const which = (cmd) => {
+        const r = spawnSync("command", ["-v", cmd], { stdio: "pipe", encoding: "utf-8", shell: "/bin/bash", timeout: 5_000 });
+        if (r.status !== 0)
+            return null;
+        const out = (r.stdout ?? "").trim();
+        return out || null;
+    };
+    const realpath = (path) => {
+        if (!path)
+            return null;
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return null;
+        }
+    };
+    const whichChromium = which("chromium");
+    const whichGoogleChrome = which("google-chrome-stable");
+    const decision = decideChromiumAction({
+        platform: "linux",
+        whichChromium,
+        realpathChromium: realpath(whichChromium),
+        whichGoogleChrome,
+        realpathGoogleChrome: realpath(whichGoogleChrome),
+    });
+    logFile(`  [snap-chromium] decision: ${decision.action} reason="${decision.reason}"`);
+    if (decision.action === "fail") {
+        throw new Error(`ensureNonSnapChromium: ${decision.reason}. apt install of \`chromium\` ran in installAptGroup(VNC stack) above; if its post-check passed but no chromium binary is on PATH, the system PATH is misconfigured.`);
+    }
+    if (decision.action === "install-google-chrome") {
+        console.log("  Detected snap-confined Chromium (Task 929) — installing Google Chrome stable...");
+        logFile(`  [snap-chromium] installing google-chrome-stable from Google's signed apt repo`);
+        // Fetch + dearmor the signing key, write to /etc/apt/trusted.gpg.d/. Pipe
+        // composition runs through bash -c so the curl|gpg pipeline is one
+        // privileged command rather than two separate sudo escalations.
+        console.log("  [privileged] curl + gpg --dearmor (Google Chrome signing key)");
+        shell("bash", ["-c",
+            "set -euo pipefail; " +
+                "curl -fsSL https://dl.google.com/linux/linux_signing_key.pub | " +
+                "gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/google-chrome.gpg",
+        ], { sudo: true });
+        // Add the apt source list with `signed-by=` scoping so the key only
+        // verifies google-chrome-* packages, not arbitrary repo overrides. arch
+        // pinned to amd64 — Google does not ship arm64 Chrome for Linux.
+        console.log("  [privileged] tee /etc/apt/sources.list.d/google-chrome.list");
+        shell("bash", ["-c",
+            "echo 'deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/google-chrome.gpg] " +
+                "http://dl.google.com/linux/chrome/deb/ stable main' " +
+                "> /etc/apt/sources.list.d/google-chrome.list",
+        ], { sudo: true });
+        console.log("  [privileged] apt-get update");
+        shell("apt-get", ["update"], { sudo: true });
+        installAptGroup("Google Chrome stable (Task 929)", ["google-chrome-stable"]);
+        // Re-resolve after install to capture the now-installed absolute path.
+        const postInstallWhich = which("google-chrome-stable");
+        if (!postInstallWhich) {
+            throw new Error("ensureNonSnapChromium: apt install of google-chrome-stable returned 0 and dpkg -s passed, but `command -v google-chrome-stable` is empty — PATH is broken.");
+        }
+        RESOLVED_CHROMIUM_BIN = postInstallWhich;
+    }
+    else {
+        // action === "use" — decision.resolvedPath is the existing non-snap binary
+        // (chromium or google-chrome-stable already installed).
+        if (!decision.resolvedPath) {
+            throw new Error(`ensureNonSnapChromium: action=use returned without resolvedPath — bug in snap-chromium.ts (input: chromium=${whichChromium} google-chrome=${whichGoogleChrome})`);
+        }
+        RESOLVED_CHROMIUM_BIN = decision.resolvedPath;
+    }
+    // Defensive: never persist a snap-confined path. If realpath of the resolved
+    // binary still lands under /snap/ (e.g. apt landed a snap package by mistake
+    // on a misconfigured device), throw before writeChromiumBinaryPathFile sees
+    // it — the runtime gate in vnc.sh would refuse anyway, but failing here
+    // surfaces the contract breach with the install context still in scope.
+    const finalRealpath = realpath(RESOLVED_CHROMIUM_BIN);
+    if (isSnapConfinedPath(finalRealpath)) {
+        throw new Error(`ensureNonSnapChromium: resolved Chromium binary ${RESOLVED_CHROMIUM_BIN} realpaths to ${finalRealpath} which is under /snap/ — refusing to persist (Task 929).`);
+    }
+    console.log(`  Chromium binary: ${RESOLVED_CHROMIUM_BIN} (realpath=${finalRealpath ?? "?"})`);
+    logFile(`  [snap-chromium] resolved bin=${RESOLVED_CHROMIUM_BIN} realpath=${finalRealpath ?? "null"}`);
+    runChromiumPostInstallGate(RESOLVED_CHROMIUM_BIN);
+}
+/**
+ * Task 929 post-install gate. Spawns the resolved Chromium binary headless
+ * against a throwaway profile dir under persistDir (`~/.{brand}/chromium-
+ * gate-profile/`). The AppArmor denial that triggered the task was on
+ * SingletonLock writes which `--headless=new` still attempts, so this probe
+ * fires the same EACCES path the headed VNC stack would. Cleans up the gate
+ * profile afterward — the live profile (`chromium-profile/`) is owned by
+ * vnc.sh's start_chrome and not touched here.
+ */
+function runChromiumPostInstallGate(chromiumBin) {
+    const persistDir = resolve(process.env.HOME ?? "/root", BRAND.configDir);
+    const gateProfileDir = join(persistDir, "chromium-gate-profile");
+    mkdirSync(gateProfileDir, { recursive: true });
+    console.log(`  Verifying ${chromiumBin} can write to ${gateProfileDir} (Task 929 post-install gate)...`);
+    const r = spawnSync(chromiumBin, [
+        `--user-data-dir=${gateProfileDir}`,
+        "--headless=new",
+        "--disable-gpu",
+        "--no-sandbox",
+        "--disable-dev-shm-usage",
+        "--dump-dom",
+        "about:blank",
+    ], { stdio: "pipe", encoding: "utf-8", timeout: 30_000 });
+    // Cleanup before throwing on failure so successive runs start clean.
+    try {
+        rmSync(gateProfileDir, { recursive: true, force: true });
+    }
+    catch { /* best-effort */ }
+    if (r.status !== 0) {
+        const stderr = (r.stderr ?? "").slice(-2000);
+        const eaccesHit = /Permission denied/i.test(stderr) || /EACCES/i.test(stderr);
+        const taskRef = eaccesHit
+            ? "Task 929: chromium-profile not writable (likely AppArmor denial on snap-confined binary). "
+            : "";
+        throw new Error(`${taskRef}Chromium post-install gate failed: ${chromiumBin} exited ${r.status} signal=${r.signal ?? "none"}. stderr:\n${stderr}`);
+    }
+    console.log("  Chromium post-install gate passed.");
+    logFile(`  [snap-chromium] post-install gate ok: ${chromiumBin} exit=0`);
+}
+/**
+ * Task 929 — write the resolved Chromium absolute path to
+ * `<INSTALL_DIR>/platform/config/chromium-binary.path` so vnc.sh,
+ * writeChromiumWrapper, and setup-tunnel.sh all read the same value. Called
+ * after deployPayload so the platform/config/ directory exists. Idempotent:
+ * re-running the installer with the same RESOLVED_CHROMIUM_BIN is a no-op
+ * write (writeFileSync overwrites in place).
+ */
+function writeChromiumBinaryPathFile() {
+    if (process.platform !== "linux") {
+        logFile(`  writeChromiumBinaryPathFile skipped: platform=${process.platform}`);
+        return;
+    }
+    const configDir = resolve(INSTALL_DIR, "platform/config");
+    mkdirSync(configDir, { recursive: true });
+    const target = join(configDir, "chromium-binary.path");
+    writeFileSync(target, RESOLVED_CHROMIUM_BIN + "\n", { mode: 0o644 });
+    console.log(`  Wrote ${target} → ${RESOLVED_CHROMIUM_BIN}`);
+    logFile(`  [snap-chromium] wrote ${target} contents=${RESOLVED_CHROMIUM_BIN}`);
+}
 function installSystemDeps() {
     log("1", TOTAL, "System dependencies and network...");
     const platform = requireSupportedPlatform(process.platform);
@@ -475,6 +660,15 @@ function installSystemDeps() {
         installAptGroup("VNC stack", VNC_DEPS);
         installAptGroup("WiFi AP", WIFI_DEPS);
     }
+    // Task 929 — replace snap-confined Chromium with Google Chrome stable on
+    // Linux laptops (Ubuntu Noble) where `/usr/bin/chromium` realpaths to the
+    // snap launcher. The snap AppArmor profile denies writes to hidden top-level
+    // paths under $HOME, so any write to `~/.{brand}/chromium-profile/SingletonLock`
+    // hits EACCES and Chromium never starts the CDP listener. Always sets
+    // RESOLVED_CHROMIUM_BIN even on Pi Bookworm (where the path is unchanged),
+    // so deployPayload's writeChromiumBinaryPathFile and installService's
+    // buildMaxyUnitFile both have a real absolute path to thread through.
+    ensureNonSnapChromium();
     // Hostname resolution — four sources, in priority order:
     //   1. --hostname flag (unconditional — the caller is the authority)
     //   2. OS detection on same-brand upgrade (service exists → keep whatever is currently set)
@@ -2307,6 +2501,7 @@ function installService() {
         rfbPort: RFB_PORT,
         websockifyPort: WEBSOCKIFY_PORT_BRAND,
         cdpPort: CDP_PORT_BRAND,
+        chromiumBin: RESOLVED_CHROMIUM_BIN, // Task 929
     });
     writeFileSync(join(serviceDir, BRAND.serviceName), serviceFile);
     // Task 647 — the edge service: always-on front door that owns the public
@@ -2801,6 +2996,11 @@ try {
     installCloudflared();
     installWhisperCpp();
     deployPayload(); // Must happen before ensureNeo4jPassword — restores config backup
+    // Task 929: write the resolved Chromium absolute path into the deployed
+    // platform/config/ so vnc.sh, writeChromiumWrapper, and setup-tunnel.sh
+    // all read the same value. Must run after deployPayload (config dir is
+    // a payload subdirectory). Linux-only; no-op on darwin/non-linux.
+    writeChromiumBinaryPathFile();
     // Task 744: scrub plaintext neo4j passwords from any pre-fix install-*.log.
     // Idempotent — re-running on already-redacted logs is a no-op. Runs after
     // payload deploy so the bundled redact-install-logs.sh is on disk.

package/dist/port-resolution.js

@@ -99,7 +99,7 @@ Environment=DISPLAY=:${o.vncDisplay}
 Environment=RFB_PORT=${o.rfbPort}
 Environment=WEBSOCKIFY_PORT=${o.websockifyPort}
 Environment=CDP_PORT=${o.cdpPort}
-Environment=PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=/usr/bin/chromium
+Environment=PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH=${o.chromiumBin}
 Environment=MAXY_PLATFORM_ROOT=${o.installDir}/platform
 Environment=CLAUDE_CONFIG_DIR=${o.persistDir}/.claude
 Environment=PATH=%h/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin

package/dist/snap-chromium.js

@@ -0,0 +1,89 @@
+// Task 929 — pure decision: should the laptop installer replace snap-confined
+// Chromium with Google Chrome stable, and which absolute binary path should
+// vnc.sh / writeChromiumWrapper / setup-tunnel.sh / the Playwright env var
+// resolve to?
+//
+// Mirrors apt-resolve.ts (Task 638) and port-resolution.ts (Task 666): inputs
+// in, decision out, no I/O. The installer wraps this with the actual
+// `command -v` and `realpath` spawnSync calls and the side-effecting
+// apt-repo-add → apt-get install → writeFileSync sequence.
+//
+// Snap detection: on Ubuntu Noble (the only currently-supported snap-confined
+// distro for Maxy/Real Agent) `readlink -f /usr/bin/chromium` resolves to
+// `/usr/bin/snap` — the snap launcher binary, which then re-execs into
+// `/snap/chromium/<rev>/usr/lib/chromium/chromium` under AppArmor. The
+// AppArmor `home` interface profile excludes hidden top-level paths under
+// `$HOME`, so any write to `~/.maxy/chromium-profile/SingletonLock` (and the
+// equivalent realagent path) hits EACCES regardless of UID. The fix is binary
+// replacement at install time; runtime patches are forbidden by
+// `feedback_no_admin_upgrade_path.md`.
+/**
+ * True iff the realpath resolves to the snap launcher (`/usr/bin/snap`) or
+ * lives anywhere under `/snap/`. Splitting on `/` and checking for a literal
+ * `snap` segment catches all three real-world shapes:
+ *   - `/snap/bin/chromium`               (intermediate snap wrapper symlink)
+ *   - `/snap/chromium/2924/usr/...`      (squashfs-mounted snap revision)
+ *   - `/usr/bin/snap`                    (snap launcher — `readlink -f` terminus on Noble)
+ *
+ * Empty / null inputs return false so callers can pass through `realpathSync`
+ * results without an explicit guard.
+ */
+export function isSnapConfinedPath(realpath) {
+    if (!realpath)
+        return false;
+    return realpath.split("/").includes("snap");
+}
+/**
+ * Pure decision. Resolution order:
+ *   1. Non-linux platform → skip-non-linux. Darwin Maxy uses Playwright's
+ *      managed Chromium (brew-install.ts), Pi-only chromium-binary.path
+ *      logic does not apply. No file is written.
+ *   2. A non-snap `google-chrome-stable` is on PATH → use it. Covers re-run
+ *      installs on a previously-fixed laptop and operator-supplied Chrome.
+ *   3. A non-snap `chromium` is on PATH → use it. Covers Pi Bookworm where
+ *      `apt-get install chromium` lands a real .deb, not a snap symlink.
+ *   4. `chromium` is on PATH but realpath is snap-confined, and no
+ *      google-chrome-stable is present → install-google-chrome. The caller
+ *      adds Google's signed apt repo + installs google-chrome-stable, then
+ *      writes the resolved path.
+ *   5. Neither chromium nor google-chrome-stable is on PATH → fail. The VNC
+ *      apt step ran before this decision, so chromium absence here means
+ *      `apt-get install chromium` did not land its binary — a contract
+ *      breach the installer must surface loudly.
+ */
+export function decideChromiumAction(input) {
+    const { platform, whichChromium, realpathChromium, whichGoogleChrome, realpathGoogleChrome } = input;
+    if (platform !== "linux") {
+        return {
+            action: "skip-non-linux",
+            resolvedPath: null,
+            reason: `platform=${platform} — chromium-binary.path is linux-only`,
+        };
+    }
+    if (whichGoogleChrome && !isSnapConfinedPath(realpathGoogleChrome)) {
+        return {
+            action: "use",
+            resolvedPath: whichGoogleChrome,
+            reason: `google-chrome-stable already installed (realpath=${realpathGoogleChrome})`,
+        };
+    }
+    if (whichChromium && !isSnapConfinedPath(realpathChromium)) {
+        return {
+            action: "use",
+            resolvedPath: whichChromium,
+            reason: `chromium is non-snap (realpath=${realpathChromium})`,
+        };
+    }
+    if (whichChromium && isSnapConfinedPath(realpathChromium)) {
+        return {
+            action: "install-google-chrome",
+            resolvedPath: null,
+            reason: `chromium is snap-confined (realpath=${realpathChromium}) — installing google-chrome-stable per Task 929`,
+        };
+    }
+    return {
+        action: "fail",
+        resolvedPath: null,
+        reason: "neither chromium nor google-chrome-stable is on PATH after VNC apt install — contract breach",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.847",
+  "version": "1.0.850",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/plugins/admin/skills/onboarding/SKILL.md

@@ -112,7 +112,7 @@ Present the admin SOUL via `render-component` with `name: "document-editor"` and
 
 After the admin SOUL is written and approved, call `onboarding-complete-step` with step 6.
 
-**Document ingestion.** If the user uploaded any documents during Step 6 (or earlier in the session), dispatch the `database-operator` subagent (via the universal `document-ingest` skill) to ingest them AFTER calling `onboarding-complete-step` — not before. Use the Agent tool with `run_in_background: true`. The critical path (SOUL file, step completion) must not depend on document ingestion succeeding. Include the document path, the document subject (typically the account owner's UserProfile or the LocalBusiness depending on the doc), and the scope in the brief. If no documents were uploaded, skip this step.
+**Document ingestion.** If the user uploaded any documents during Step 6 (or earlier in the session), dispatch the `specialists:database-operator` subagent (via the universal `document-ingest` skill) to ingest them AFTER calling `onboarding-complete-step` — not before. Use the Agent tool with `run_in_background: true`. The critical path (SOUL file, step completion) must not depend on document ingestion succeeding. Include the document path, the document subject (typically the account owner's UserProfile or the LocalBusiness depending on the doc), and the scope in the brief. If no documents were uploaded, skip this step.
 
 **Next steps.** After completing onboarding, let the user know that everything configured during onboarding — plugins, WiFi, output style, thinking view, timezone, and personality — can be changed at any time through conversation. Then suggest three things the user can do next — all optional and available whenever they are ready:
 

package/payload/platform/plugins/admin/skills/public-agent-manager/SKILL.md

@@ -195,7 +195,7 @@ After creation, no template metadata persists in the agent's files. The resultin
 9. **KNOWLEDGE.md generation** — populate from the now-tagged set plus keyword matches using the `update-knowledge` skill workflow
 10. Write `config.json` with selected model, plugins, status "active", `liveMemory`, and `knowledgeKeywords`. This is the last gated write — placed after IDENTITY.md, SOUL.md, and KNOWLEDGE.md to prevent cascade failure if one gate stalls.
 11. Check context budget — auto-summarise if over threshold
-12. **Project the agent into the graph** — delegate to the `database-operator` specialist with the instruction: "Project public agent `{slug}` into the graph by POSTing to `/api/admin/agents/{slug}/project`." The route reads the on-disk files and idempotently MERGEs the `:Agent` node, the four owned `:KnowledgeDocument` projections (IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY when present, namespaced `attachmentId="agent:<slug>:<role>"`), the `HAS_*` edges, and the `USES_KNOWLEDGE` edges to every operator-tagged doc. Loud-fail: if the route returns non-2xx, surface the error to the user verbatim — the agent's files exist on disk but its graph projection is incomplete, which means the operator's /graph view will not show this agent. Re-running the projection is safe; it is the same idempotent MERGE.
+12. **Project the agent into the graph** — delegate to the `specialists:database-operator` specialist with the instruction: "Project public agent `{slug}` into the graph by POSTing to `/api/admin/agents/{slug}/project`." The route reads the on-disk files and idempotently MERGEs the `:Agent` node, the four owned `:KnowledgeDocument` projections (IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY when present, namespaced `attachmentId="agent:<slug>:<role>"`), the `HAS_*` edges, and the `USES_KNOWLEDGE` edges to every operator-tagged doc. Loud-fail: if the route returns non-2xx, surface the error to the user verbatim — the agent's files exist on disk but its graph projection is incomplete, which means the operator's /graph view will not show this agent. Re-running the projection is safe; it is the same idempotent MERGE.
 13. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
 
 ### List
@@ -232,7 +232,7 @@ For knowledge scope changes:
 - Allow toggling `liveMemory` on/off (update `config.json`).
 - After changes, offer to refresh KNOWLEDGE.md using the `update-knowledge` skill.
 
-**After every Edit operation that touches IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY/`config.json` (including `liveMemory`, `knowledgeKeywords`, or direct-tag mutations), delegate to `database-operator` to re-project: POST `/api/admin/agents/{slug}/project`.** Without re-projection the on-disk files diverge from the graph state — the operator sees stale `:Agent` properties and stale `USES_KNOWLEDGE` edges in /graph. Loud-fail: surface non-2xx errors verbatim.
+**After every Edit operation that touches IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY/`config.json` (including `liveMemory`, `knowledgeKeywords`, or direct-tag mutations), delegate to `specialists:database-operator` to re-project: POST `/api/admin/agents/{slug}/project`.** Without re-projection the on-disk files diverge from the graph state — the operator sees stale `:Agent` properties and stale `USES_KNOWLEDGE` edges in /graph. Loud-fail: surface non-2xx errors verbatim.
 
 ### Delete
 

package/payload/platform/plugins/cloudflare/PLUGIN.md

@@ -30,7 +30,7 @@ The plugin registers no agent-facing MCP tools. Every Cloudflare operation is dr
 
 | Script | Purpose |
 |---|---|
-| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel resolve (operator-supplied identity), DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Required env: `STREAM_LOG_PATH`, `ACCOUNT_DIR`, AND exactly one of `TUNNEL_ID` (operator selected an existing tunnel from `/api/admin/cloudflare/tunnels`) or `TUNNEL_NAME` (operator typed a name to create) per the operator-selected-tunnel fix. The pre-fix derivation `${BRAND}-$(hostname -s)` is removed — the operator's logged-in Cloudflare account is the source of truth for which tunnel exists. Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. Step 1 (wrappers faithfully relay third-party CLI) spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, mechanically opens it on the Pi VNC chromium (`DISPLAY=${DISPLAY:-:99} /usr/bin/chromium <url> &`), then polls for `~/.cloudflared/cert.pem` while the operator clicks the zone row + Authorize on the VNC. 180 s budget with a 2-second `step=oauth-login result=awaiting-cert` heartbeat. No CDP auto-click, no DOM matcher. |
+| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel resolve (operator-supplied identity), DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Required env: `STREAM_LOG_PATH`, `ACCOUNT_DIR`, AND exactly one of `TUNNEL_ID` (operator selected an existing tunnel from `/api/admin/cloudflare/tunnels`) or `TUNNEL_NAME` (operator typed a name to create) per the operator-selected-tunnel fix. The pre-fix derivation `${BRAND}-$(hostname -s)` is removed — the operator's logged-in Cloudflare account is the source of truth for which tunnel exists. Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. Step 1 (wrappers faithfully relay third-party CLI) spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, mechanically opens it on the brand's VNC chromium using the install-time-resolved binary (`DISPLAY=${DISPLAY:-${BRAND_VNC_DISPLAY}} "${SETUP_TUNNEL_CHROMIUM_BIN}" <url> &` — `SETUP_TUNNEL_CHROMIUM_BIN` is read from `${MAXY_PLATFORM_ROOT}/config/chromium-binary.path` at script start so Ubuntu Noble laptop's snap-replaced Google Chrome is honoured by the install-time chromium resolver), then polls for `~/.cloudflared/cert.pem` while the operator clicks the zone row + Authorize on the VNC. 180 s budget with a 2-second `step=oauth-login result=awaiting-cert` heartbeat. No CDP auto-click, no DOM matcher. |
 | [`scripts/reset-tunnel.sh`](scripts/reset-tunnel.sh) | Deletes every tunnel on the brand's CF account and wipes `${CFG_DIR}`. Does not touch the platform service, stray CNAMEs, or token-mode connectors — those require dashboard cleanup or `pkill`. Invocation: `~/reset-tunnel.sh <brand>`. No polling blocks — every long-wait is bounded by `cloudflared`'s network round-trip, so no heartbeat contract applies. |
 
 ### Skills

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

@@ -80,6 +80,23 @@ if [ -n "${SETUP_TUNNEL_BRAND_JSON}" ] && command -v jq >/dev/null 2>&1; then
   fi
 fi
 
+# Task 929 — read the install-time-resolved non-snap Chromium binary path so
+# the OAuth-URL spawn below uses the same binary vnc.sh's start_chrome runs.
+# Hardcoded `/usr/bin/chromium` would re-introduce the snap-AppArmor failure
+# on Ubuntu Noble laptop. The installer writes this file under platform/config/
+# during installSystemDeps; the spawn at step=browser-spawn fails loud if the
+# file is absent rather than silently falling back to /usr/bin/chromium.
+SETUP_TUNNEL_CHROMIUM_BIN=""
+if [ -n "${MAXY_PLATFORM_ROOT:-}" ] && [ -r "${MAXY_PLATFORM_ROOT}/config/chromium-binary.path" ]; then
+  SETUP_TUNNEL_CHROMIUM_BIN="$(head -n1 "${MAXY_PLATFORM_ROOT}/config/chromium-binary.path" | tr -d '[:space:]')"
+fi
+if [ -z "${SETUP_TUNNEL_CHROMIUM_BIN}" ] || [ ! -x "${SETUP_TUNNEL_CHROMIUM_BIN}" ]; then
+  echo "ERROR: setup-tunnel.sh cannot resolve a non-snap Chromium binary." >&2
+  echo "       Expected: \${MAXY_PLATFORM_ROOT}/config/chromium-binary.path → executable absolute path." >&2
+  echo "       Re-run the installer to provision Chromium (Task 929)." >&2
+  exit 1
+fi
+
 # --------------------------------------------------------------------------
 # Step 1: OAuth login. Corresponds to runbook Step 1.
 #
@@ -231,7 +248,7 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
 
   # Mechanically open the URL on the Pi VNC chromium (Task 858). Chromium
   # is already running on this brand's ${BRAND_VNC_DISPLAY} with CDP enabled
-  # (vnc.sh start_chrome at boot); invoking `/usr/bin/chromium <url>` against
+  # (vnc.sh start_chrome at boot); invoking the resolved binary <url> against
   # a running instance IPCs the URL into it as a new tab. Fire-and-forget —
   # the spawn is intentionally NOT tracked in cleanup_oauth's EXIT trap
   # because it is a sibling open, not a child of cloudflared, and an
@@ -239,12 +256,13 @@ if [ ! -f "${CFG_DIR}/cert.pem" ]; then
   # optimistic xdg-open, which does not reliably target the brand's VNC
   # display in this environment.
   #
-  # Binary path: /usr/bin/chromium is the canonical runtime binary on every
-  # supported distro (Bookworm + Noble — see vnc.sh and packages/create-maxy/
-  # src/apt-resolve.ts). The Ubuntu transitional `chromium-browser` does not
-  # exist on Bookworm Pis, so using the absolute path is the only spelling
-  # that survives both distros.
-  DISPLAY="${DISPLAY:-${BRAND_VNC_DISPLAY}}" /usr/bin/chromium "${AUTH_URL}" >/dev/null 2>&1 &
+  # Binary path: SETUP_TUNNEL_CHROMIUM_BIN is read at startup from
+  # ${MAXY_PLATFORM_ROOT}/config/chromium-binary.path — `/usr/bin/chromium`
+  # on Pi Bookworm and `/usr/bin/google-chrome-stable` on Ubuntu Noble laptop
+  # where the system chromium is snap-confined (Task 929). Hardcoding
+  # `/usr/bin/chromium` here would re-introduce the AppArmor SingletonLock
+  # failure on the laptop.
+  DISPLAY="${DISPLAY:-${BRAND_VNC_DISPLAY}}" "${SETUP_TUNNEL_CHROMIUM_BIN}" "${AUTH_URL}" >/dev/null 2>&1 &
   phase_line setup-tunnel step=browser-spawn result=ok \
     display="${DISPLAY:-${BRAND_VNC_DISPLAY}}" url_extracted=1
   phase_line setup-tunnel step=browser-drive mode=operator-click url="${AUTH_URL}"

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

@@ -22,7 +22,7 @@ Any Cloudflare action outside these four surfaces is a discipline violation —
 
 Use this when the operator wants Cloudflare set up (or re-set up) end-to-end on the device. The script handles OAuth login, tunnel creation, DNS routing for each subdomain, config.yml + tunnel.state, and dispatches the `${BRAND}.service` restart to a transient `systemd-run` unit — all in one invocation. The restart fires a few seconds after the script exits so the script does not kill its own cgroup when invoked via the Bash tool; the chat UI receives a `server_shutdown` SSE frame and reconnects automatically. Post-restart hostname verification is out of scope for the script (connector is not up when the script exits) — verify via the next admin turn or manually with `curl -I https://<hostname>`. Apex hostnames cannot be routed by the CLI; when one is passed, the script prints an `ACTION REQUIRED` block naming the exact dashboard record to edit.
 
-Step 1's OAuth flow is a state machine over two observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`) and the OAuth-default cert path (`~/.cloudflared/cert.pem`). When the brand-scoped cert is missing but the default-path cert is present from any prior partial run, the wrapper promotes it (`mv`) and emits `step=oauth-login result=ok reason=cert-promoted-from-default-path` without re-spawning cloudflared. When both are missing, the wrapper spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and the instant the URL surfaces, mechanically opens it on the Pi's VNC chromium (`DISPLAY=${DISPLAY:-:99} /usr/bin/chromium <url> &`) — emitting `step=browser-spawn result=ok` and `step=browser-drive mode=operator-click`. The operator clicks the zone row + Authorize on the VNC; cloudflared's callback writes `~/.cloudflared/cert.pem`; the wrapper's cert-poll (180 s budget) picks it up and `mv`s it to the brand-scoped path. There is no CDP auto-click, no DOM matcher, no consent-page driver — the wrapper's job is to faithfully relay `cloudflared tunnel login`, never to layer automation on top.
+Step 1's OAuth flow is a state machine over two observable variables: the brand-scoped cert path (`${CFG_DIR}/cert.pem`) and the OAuth-default cert path (`~/.cloudflared/cert.pem`). When the brand-scoped cert is missing but the default-path cert is present from any prior partial run, the wrapper promotes it (`mv`) and emits `step=oauth-login result=ok reason=cert-promoted-from-default-path` without re-spawning cloudflared. When both are missing, the wrapper spawns `cloudflared tunnel login`, extracts the argotunnel URL from its stdout, and the instant the URL surfaces, mechanically opens it on the brand's VNC chromium using the install-time-resolved binary (`DISPLAY=${DISPLAY:-${BRAND_VNC_DISPLAY}} "${SETUP_TUNNEL_CHROMIUM_BIN}" <url> &` — `SETUP_TUNNEL_CHROMIUM_BIN` is read from `${MAXY_PLATFORM_ROOT}/config/chromium-binary.path` so Ubuntu Noble laptop's snap-replaced Google Chrome is honoured per Task 929) — emitting `step=browser-spawn result=ok` and `step=browser-drive mode=operator-click`. The operator clicks the zone row + Authorize on the VNC; cloudflared's callback writes `~/.cloudflared/cert.pem`; the wrapper's cert-poll (180 s budget) picks it up and `mv`s it to the brand-scoped path. There is no CDP auto-click, no DOM matcher, no consent-page driver — the wrapper's job is to faithfully relay `cloudflared tunnel login`, never to layer automation on top.
 
 ### How inputs reach the script
 

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

@@ -93,6 +93,6 @@ The constraint is computed once per turn at the top of `invokeAgent` and frozen
 
 ## Limits and deferrals
 
-v1 covers the admin agent only. Specialist subagents (`personal-assistant`, `project-manager`, `research-assistant`, `content-producer`, `database-operator`) do not receive their own ledger injection yet — their `.md` templates load via `--plugin-dir` and have no TS-side assembly site. Follow-up task filed.
+v1 covers the admin agent only. Specialist subagents (`specialists:personal-assistant`, `specialists:project-manager`, `specialists:research-assistant`, `specialists:content-producer`, `specialists:database-operator`) do not receive their own ledger injection yet — their `.md` templates load via `--plugin-dir` and have no TS-side assembly site. Follow-up task filed.
 
 No cross-agent rule inheritance, no user-visible correction-ack signal, no blocking-critic retry loop in v1 — each is a separate follow-up task. See [`.docs/agents.md`](../../../../.docs/agents.md) § Adherence Fidelity for the full deferral list with task numbers.

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

@@ -107,6 +107,14 @@ sudo rm -f /usr/local/bin/ttyd
 systemctl --user daemon-reload
 ```
 
+## Linux laptops: snap-confined Chromium replacement
+
+On Ubuntu 24.04 (Noble) the system Chromium binary at `/usr/bin/chromium` is a symlink into the snap. Snap's AppArmor profile denies writes to hidden directories under your home folder, so the per-brand Chromium profile at `~/.{brand}/chromium-profile/` is unwritable and the VNC browser never starts. Pi installs (Debian Bookworm) are unaffected because Bookworm ships a real `.deb` chromium.
+
+The installer detects this case during system-dependency setup and replaces the snap binary with Google Chrome stable, installed from Google's signed apt repo. The chosen binary's absolute path is recorded in `<INSTALL_DIR>/platform/config/chromium-binary.path` and used by every Chromium call site (the VNC service, the in-page Chromium wrapper, the Cloudflare tunnel OAuth spawn, and the Playwright server). If you ever see `chromium-binary.path missing` or `Chromium ... resolves to ... which is snap-confined` in `~/.{brand}/logs/vnc-boot.log`, re-run the installer to re-provision.
+
+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`.
+
 ## 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.