@rubytech/create-realagent 1.0.849 → 1.0.852

package/dist/__tests__/preflight-port-classifier.test.js

@@ -0,0 +1,163 @@
+// Task 938 — acceptance grid for classifyPortHolder.
+//
+// The wrapper in index.ts owns ss(8), /proc reads, kill(2), and the operator-
+// override exit. This suite exercises only the pure decision rule: ssOutput +
+// configDir context → kind. Inputs in, decision out — no fs, no exec, no spawn.
+//
+// Cmdlines below mimic /proc/<pid>/cmdline format: argv joined by NUL bytes,
+// possibly with a trailing NUL. The classifier requires this format so it can
+// distinguish `--user-data-dir=PATH` (a real ownership claim) from a different
+// flag whose value happens to contain the profile path substring.
+//
+// Runs via Node's built-in test runner — same convention as
+// peer-brand-detect.test.ts.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { classifyPortHolder } from "../preflight-port-classifier.js";
+const ALL_BRANDS = [".maxy", ".realagent", ".maxy-2", ".maxy-3", ".maxy-4"];
+const peers = (own) => ALL_BRANDS.filter(c => c !== own);
+const SS_PID_42 = "LISTEN 0 4096  *:9222  *:*  users:((\"chrome\",pid=42,fd=12))";
+const SS_PID_99 = "LISTEN 0 4096  *:9223  *:*  users:((\"chrome\",pid=99,fd=12))";
+const cmd = (...argv) => argv.join("\0") + "\0";
+test("empty ssOutput → EMPTY", () => {
+    const r = classifyPortHolder({
+        ssOutput: "",
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: () => { throw new Error("should not be called"); },
+    });
+    assert.equal(r.kind, "EMPTY");
+});
+test("OWN_BRAND: --user-data-dir=PATH single argv", () => {
+    const cmdline = cmd("/opt/google/chrome/chrome", "--user-data-dir=/home/neo/.maxy/chromium-profile", "--remote-debugging-port=9222");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: pid => { assert.equal(pid, 42); return cmdline; },
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.pid, 42);
+    assert.equal(r.profilePath, "/home/neo/.maxy/chromium-profile");
+});
+test("OWN_BRAND: --user-data-dir PATH split across two argvs", () => {
+    const cmdline = cmd("/usr/bin/chromium", "--user-data-dir", "/home/admin/.maxy/chromium-profile", "--remote-debugging-port=9222");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.profilePath, "/home/admin/.maxy/chromium-profile");
+});
+test("PEER_BRAND: cmdline holds another known brand's profile path", () => {
+    const cmdline = cmd("/usr/bin/chromium", "--user-data-dir=/home/admin/.realagent/chromium-profile", "--remote-debugging-port=9223");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_99,
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "PEER_BRAND");
+    assert.equal(r.pid, 99);
+    assert.equal(r.profilePath, "/home/admin/.realagent/chromium-profile");
+});
+test("UNRELATED: cmdline matches no known brand profile", () => {
+    const cmdline = cmd("/usr/bin/python3", "-m", "http.server", "9222");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.pid, 42);
+    assert.equal(r.cmdline, "/usr/bin/python3 -m http.server 9222");
+});
+test("UNRELATED: ssOutput non-empty but no pid= token", () => {
+    const r = classifyPortHolder({
+        ssOutput: "Recv-Q Send-Q  Local Address:Port  Peer Address:Port",
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: () => { throw new Error("should not be called"); },
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.pid, undefined);
+});
+test("UNRELATED: getCmdline throws (race — process exited between ss and read)", () => {
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: () => { const e = new Error("ENOENT"); e.code = "ENOENT"; throw e; },
+    });
+    assert.equal(r.kind, "UNRELATED");
+    assert.equal(r.pid, 42);
+    assert.equal(r.cmdlineReadFailed, true);
+});
+test("UNRELATED: --user-data-dir absent (no profile claim)", () => {
+    // Kernel threads, GPU/zygote/utility chrome processes inherit profile via
+    // fork without re-stating --user-data-dir on their argv. They wouldn't be
+    // listening anyway, but if one ever showed up here we must classify as
+    // UNRELATED, never as OWN_BRAND on a substring fluke.
+    const cmdline = cmd("/opt/google/chrome/chrome", "--type=gpu-process", "--no-sandbox");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+});
+test("substring boundary: own=.maxy must NOT match .maxy-2 cmdline", () => {
+    const cmdline = cmd("chromium", "--user-data-dir=/home/neo/.maxy-2/chromium-profile");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "PEER_BRAND");
+    assert.equal(r.profilePath, "/home/neo/.maxy-2/chromium-profile");
+});
+test("substring boundary: own=.maxy-2 must NOT misclassify .maxy cmdline as own", () => {
+    const cmdline = cmd("chromium", "--user-data-dir=/home/neo/.maxy/chromium-profile");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownConfigDir: ".maxy-2",
+        peerConfigDirs: peers(".maxy-2"),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "PEER_BRAND");
+    assert.equal(r.profilePath, "/home/neo/.maxy/chromium-profile");
+});
+test("argv-anchor safety: marker in --load-extension value must NOT classify as OWN_BRAND", () => {
+    // Adversarial case from review: a Chrome flag whose value contains the
+    // profile-path substring, but no actual --user-data-dir claim. Naive
+    // substring matching would false-positive OWN_BRAND.
+    const cmdline = cmd("chromium", "--load-extension=/tmp/decoy/.maxy/chromium-profile", "--remote-debugging-port=9222");
+    const r = classifyPortHolder({
+        ssOutput: SS_PID_42,
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: () => cmdline,
+    });
+    assert.equal(r.kind, "UNRELATED");
+});
+test("ss header line containing 'pid=': last pid= wins", () => {
+    // If a future ss locale prepends header text containing the literal `pid=`
+    // (e.g., "Process pid="), the first-match heuristic would lift the wrong
+    // value. The LISTEN row is always last, so taking the last pid= match is
+    // the structural fix.
+    const ssOutput = `State pid= notes\nLISTEN 0 4096  *:9222 *:*  users:(("chrome",pid=42,fd=12))`;
+    const cmdline = cmd("chromium", "--user-data-dir=/home/neo/.maxy/chromium-profile");
+    const r = classifyPortHolder({
+        ssOutput,
+        ownConfigDir: ".maxy",
+        peerConfigDirs: peers(".maxy"),
+        getCmdline: pid => { assert.equal(pid, 42, "must pick the LISTEN row's pid, not the header's"); return cmdline; },
+    });
+    assert.equal(r.kind, "OWN_BRAND");
+    assert.equal(r.pid, 42);
+});

package/dist/index.js

@@ -11,6 +11,7 @@ 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";
+import { classifyPortHolder } from "./preflight-port-classifier.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.
@@ -2452,39 +2453,141 @@ function installService() {
     const RFB_PORT = BRAND.rfbPort ?? 5900 + VNC_OFFSET;
     const WEBSOCKIFY_PORT_BRAND = BRAND.websockifyPort ?? 6080 + VNC_OFFSET;
     const CDP_PORT_BRAND = BRAND.cdpPort ?? 9222 + VNC_OFFSET;
-    // Task 924 pre-flight — refuse to write service files if any of the
-    // three brand-scoped ports is already held by a process that is NOT a
-    // peer brand's edge service. Collisions with peer brands' Xtigervnc or
-    // websockify on this device are normal in concurrent multi-brand
-    // installs and harmless because each brand's port set is disjoint by
-    // construction. Anything else (a stale pre-924 unit, an external VNC,
-    // or operator misconfiguration) is a structural collision the operator
-    // must resolve before service start.
-    const checkInstallPortFree = (label, port) => {
+    // Task 924/938 pre-flight — refuse to write service files if any of the
+    // three brand-scoped ports is already held by a process that is NOT this
+    // brand's own on-demand browser nor a peer brand's edge stack.
+    //
+    // Classification (Task 938) reads `/proc/<pid>/cmdline` and matches on the
+    // user-data-dir profile path, not on `comm` regex. The previous
+    // `comm`-regex approach (`/Xtigervnc|websockify|chromium/`) failed on the
+    // laptop where Task 929 selects google-chrome-stable: comm is `chrome`,
+    // so the brand's own browser was misclassified UNRELATED and the install
+    // aborted against a port it could legitimately reclaim.
+    //
+    // Decisions per holder:
+    //   OWN_BRAND  — SIGTERM, recheck, SIGKILL on stragglers, exit-1 only if
+    //                the port is still held after both signals.
+    //   PEER_BRAND — log OK and return (per-brand port sets are disjoint).
+    //   UNRELATED  — refuse to write service files; emit operator override.
+    // macOS dev hosts (no ss) fall through the catch and skip pre-flight
+    // entirely — the runtime check in vnc.sh covers Linux production.
+    const peerConfigDirs = KNOWN_BRAND_HOSTNAMES
+        .filter(h => h !== BRAND.hostname)
+        .map(h => `.${h}`);
+    const ssReadHolder = (port) => {
+        return execFileSync("ss", ["-tlnpH", `sport = :${port}`], {
+            encoding: "utf-8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
+        });
+    };
+    // Pass raw NUL-separated cmdline to the classifier so it can argv-anchor
+    // on `--user-data-dir=`. Replacing NUL with space here would defeat that.
+    const readCmdline = (pid) => readFileSync(`/proc/${pid}/cmdline`, "utf-8");
+    const sleepMs = (ms) => { spawnSync("sleep", [(ms / 1000).toString()]); };
+    // Tightly scoped variant for retry-path ss reads. Failures here (timeout,
+    // ENOMEM, signal) are structural — never the macOS-no-ss case (we already
+    // succeeded once) — so they get a structured exit, not a stack trace.
+    const ssReadOrAbort = (label, port) => {
         try {
-            const out = execFileSync("ss", ["-tlnpH", `sport = :${port}`], {
-                encoding: "utf-8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"],
-            });
-            const heldBy = out.trim();
-            if (!heldBy)
-                return;
-            const isPeerBrandStack = /Xtigervnc/.test(heldBy) || /websockify/.test(heldBy) || /chromium/.test(heldBy);
-            if (isPeerBrandStack) {
-                logFile(`  [preflight] ${label}=${port} held by a peer brand's stack — OK (per-brand ports are disjoint by construction)`);
-                return;
-            }
-            console.error(`  ERROR: [preflight:collision] brand=${BRAND.hostname} ${label}=${port} held by an unrelated process:`);
-            console.error(`         ${heldBy}`);
-            console.error(`         Refusing to write service files; resolve the collision before retrying.`);
-            console.error(`         Operator override: edit brands/${BRAND.hostname}/brand.json and set ${label}=<free port>, re-bundle, re-install.`);
+            return ssReadHolder(port);
+        }
+        catch (err) {
+            console.error(`  ERROR: [preflight] ${label}=${port} ss recheck failed: ${err instanceof Error ? err.message : String(err)}`);
+            console.error(`         Resolve manually before retrying.`);
             process.exit(1);
         }
+    };
+    // Distinguish ESRCH (process already gone — expected) from EPERM/EINVAL
+    // (alarming — signals we can't deliver, possibly a recycled pid). Returns
+    // true for clean kill or ESRCH, false otherwise (caller logs a warning).
+    const killNoThrow = (pid, signal) => {
+        try {
+            process.kill(pid, signal);
+            return true;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ESRCH")
+                return true;
+            logFile(`  [preflight] kill(${pid}, ${signal}) failed code=${code ?? "unknown"}`);
+            return false;
+        }
+    };
+    const classify = (ssOutput) => classifyPortHolder({
+        ssOutput, ownConfigDir: BRAND.configDir, peerConfigDirs, getCmdline: readCmdline,
+    });
+    const checkInstallPortFree = (label, port) => {
+        let firstSsOutput;
+        try {
+            firstSsOutput = ssReadHolder(port);
+        }
         catch (err) {
             // ss may not be present on macOS dev hosts — skip the pre-flight there
             // rather than abort the install. The runtime check in vnc.sh covers
-            // production-like Linux installs where this matters.
+            // production-like Linux installs where this matters. This catch is
+            // narrow on purpose: only the first ss invocation may legitimately
+            // fail (binary missing); retry-path failures use ssReadOrAbort.
             logFile(`  [preflight] ${label}=${port} check skipped: ${err instanceof Error ? err.message : String(err)}`);
+            return;
         }
+        let r = classify(firstSsOutput);
+        // ENOENT race — process exited between ss and cmdline read. Port is
+        // probably free now; one re-check resolves it deterministically.
+        if (r.cmdlineReadFailed)
+            r = classify(ssReadOrAbort(label, port));
+        if (r.kind === "EMPTY")
+            return;
+        if (r.kind === "PEER_BRAND") {
+            logFile(`  [preflight] ${label}=${port} held by a peer brand's stack — OK (per-brand ports are disjoint by construction)`);
+            return;
+        }
+        if (r.kind === "OWN_BRAND" && r.pid !== undefined) {
+            logFile(`  [preflight] ${label}=${port} held by OWN brand process pid=${r.pid} profile=${r.profilePath} — sending SIGTERM`);
+            killNoThrow(r.pid, "SIGTERM");
+            sleepMs(300);
+            const after = classify(ssReadOrAbort(label, port));
+            if (after.kind === "EMPTY") {
+                logFile(`  [preflight] ${label}=${port} freed`);
+                return;
+            }
+            if (after.kind === "OWN_BRAND" && after.pid === r.pid) {
+                logFile(`  [preflight] ${label}=${port} survived SIGTERM — sending SIGKILL`);
+                killNoThrow(r.pid, "SIGKILL");
+                sleepMs(300);
+                const final = classify(ssReadOrAbort(label, port));
+                if (final.kind === "EMPTY") {
+                    logFile(`  [preflight] ${label}=${port} freed`);
+                    return;
+                }
+                console.error(`  ERROR: [preflight] ${label}=${port} OWN_BRAND auto-kill failed pid=${r.pid} — resolve manually before retrying.`);
+                process.exit(1);
+            }
+            // A different OWN_BRAND pid took the port. The brand's user services
+            // are respawning Chromium — installer cannot win this race. Stop the
+            // services, then retry.
+            if (after.kind === "OWN_BRAND") {
+                console.error(`  ERROR: [preflight] ${label}=${port} brand respawned a new OWN_BRAND pid (was ${r.pid}, now ${after.pid}).`);
+                console.error(`         Stop the brand's user services first: \`systemctl --user stop ${BRAND.hostname}-edge ${BRAND.hostname}\`, then re-run the installer.`);
+                process.exit(1);
+            }
+            // PEER_BRAND or UNRELATED took the port post-kill — fall through to
+            // those branches by re-classifying the surviving holder.
+            r = after;
+            if (r.kind === "EMPTY")
+                return;
+            if (r.kind === "PEER_BRAND") {
+                logFile(`  [preflight] ${label}=${port} now held by a peer brand's stack — OK`);
+                return;
+            }
+            // r.kind === "UNRELATED" — fall through to the operator-override block.
+        }
+        // UNRELATED — preserve the operator-override path verbatim.
+        console.error(`  ERROR: [preflight:collision] brand=${BRAND.hostname} ${label}=${port} held by an unrelated process:`);
+        console.error(`         ${firstSsOutput.trim()}`);
+        if (r.cmdline)
+            console.error(`         cmdline: ${r.cmdline}`);
+        console.error(`         Refusing to write service files; resolve the collision before retrying.`);
+        console.error(`         Operator override: edit brands/${BRAND.hostname}/brand.json, set/add \`${label}\` to a free port, re-bundle, re-install.`);
+        process.exit(1);
     };
     checkInstallPortFree("rfbPort", RFB_PORT);
     checkInstallPortFree("websockifyPort", WEBSOCKIFY_PORT_BRAND);
@@ -2631,8 +2734,8 @@ WantedBy=multi-user.target
         console.log("  [cdp-check] skipped reason=native-display (on-demand Chromium)");
     }
     else {
-        console.log("  Verifying browser automation (CDP on port 9222)...");
-        const cdpCheck = spawnSync("curl", ["-sf", "http://127.0.0.1:9222/json/version", "-o", "/dev/null"], {
+        console.log(`  Verifying browser automation (CDP on port ${CDP_PORT_BRAND})...`);
+        const cdpCheck = spawnSync("curl", ["-sf", `http://127.0.0.1:${CDP_PORT_BRAND}/json/version`, "-o", "/dev/null"], {
             timeout: 5000,
             stdio: "pipe",
         });
@@ -2649,8 +2752,8 @@ WantedBy=multi-user.target
                 vncLog = `(no boot log found at ${vncLogPath})`;
             }
             console.error("");
-            console.error("Setup failed: Browser automation unavailable — CDP port 9222 not responding");
-            console.error("  ERROR: Browser automation unavailable — CDP port 9222 not responding.");
+            console.error(`Setup failed: Browser automation unavailable — CDP port ${CDP_PORT_BRAND} not responding`);
+            console.error(`  ERROR: Browser automation unavailable — CDP port ${CDP_PORT_BRAND} not responding.`);
             console.error("  Chromium should be started by vnc.sh (ExecStartPre). Check the boot log:");
             console.error("");
             console.error(vncLog);

package/dist/preflight-port-classifier.js

@@ -0,0 +1,87 @@
+// Task 938 — pure classifier for the install-time port collision pre-flight.
+// Extracted from index.ts so the OWN_BRAND / PEER_BRAND / UNRELATED decision
+// can be unit-tested without ss(8), /proc, or kill(2). Mirrors the
+// peer-brand-detect.ts pattern: inputs in, classification out, no I/O.
+//
+// The wrapper in index.ts owns the side effects: ss read, /proc/<pid>/cmdline
+// read, SIGTERM/SIGKILL escalation, and the operator-override exit. This
+// module owns only the classification rule.
+//
+// Rule, in order of precedence:
+//   1. ssOutput is empty                              → EMPTY
+//   2. No `pid=N` token in ssOutput                   → UNRELATED (pid undef)
+//   3. getCmdline(pid) throws                         → UNRELATED (cmdlineReadFailed)
+//   4. argv has --user-data-dir=PATH where PATH contains
+//      `/<ownConfigDir>/chromium-profile`             → OWN_BRAND
+//   5. same for any `<peerConfigDir>`                 → PEER_BRAND
+//   6. otherwise                                       → UNRELATED
+//
+// Why argv parsing instead of substring matching: `cmdline.includes('/.maxy/
+// chromium-profile')` would false-match `--load-extension=/tmp/.maxy/chromium-
+// profile` (or any other flag whose value happens to contain the profile path
+// component). Anchoring on `--user-data-dir=` is the only signal that this
+// process actually owns that profile directory.
+//
+// Why "last pid=" instead of "first pid=": ss with `-tlnpH sport = :PORT`
+// emits the LISTEN row last; if a future ss locale or release prepends a
+// header line that contains `pid=` text, the first-match heuristic would
+// lift the wrong pid. The last `pid=` is always inside the LISTEN row's
+// `users:((…))` segment.
+/**
+ * `cmdline` should be the raw `/proc/<pid>/cmdline` contents — NUL-separated
+ * argv as the kernel emits it. Do NOT replace NUL with space before passing:
+ * the argv boundaries are what disambiguate `--user-data-dir=PATH` from a
+ * different flag whose value happens to contain `--user-data-dir=`.
+ */
+export function classifyPortHolder(args) {
+    const { ssOutput, ownConfigDir, peerConfigDirs, getCmdline } = args;
+    if (ssOutput.trim() === "")
+        return { kind: "EMPTY" };
+    // Take the LAST pid= match. ss -tlnpH puts the LISTEN row (which contains
+    // `users:((…,pid=N,fd=…))`) last, so the last pid= is always the listener.
+    const pidMatches = [...ssOutput.matchAll(/pid=(\d+)/g)];
+    if (pidMatches.length === 0)
+        return { kind: "UNRELATED" };
+    const pid = Number(pidMatches[pidMatches.length - 1][1]);
+    let cmdline;
+    try {
+        cmdline = getCmdline(pid);
+    }
+    catch {
+        return { kind: "UNRELATED", pid, cmdlineReadFailed: true };
+    }
+    // Pretty cmdline (NULs → spaces) for log output. The argv-aware matching
+    // operates on the raw NUL-separated form.
+    const prettyCmdline = cmdline.replace(/\0/g, " ").trim();
+    const argv = cmdline.split("\0").filter(s => s.length > 0);
+    const userDataDir = findUserDataDir(argv);
+    if (userDataDir === null) {
+        return { kind: "UNRELATED", pid, cmdline: prettyCmdline };
+    }
+    const ownSuffix = `/${ownConfigDir}/chromium-profile`;
+    if (userDataDir.includes(ownSuffix)) {
+        return { kind: "OWN_BRAND", pid, cmdline: prettyCmdline, profilePath: userDataDir };
+    }
+    for (const peerCD of peerConfigDirs) {
+        const peerSuffix = `/${peerCD}/chromium-profile`;
+        if (userDataDir.includes(peerSuffix)) {
+            return { kind: "PEER_BRAND", pid, cmdline: prettyCmdline, profilePath: userDataDir };
+        }
+    }
+    return { kind: "UNRELATED", pid, cmdline: prettyCmdline };
+}
+// Find the value of `--user-data-dir`, supporting both `--user-data-dir=PATH`
+// (single argv) and `--user-data-dir PATH` (split across two argvs). Returns
+// null if the flag is absent.
+function findUserDataDir(argv) {
+    const FLAG = "--user-data-dir";
+    const PREFIX = `${FLAG}=`;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith(PREFIX))
+            return a.slice(PREFIX.length);
+        if (a === FLAG && i + 1 < argv.length)
+            return argv[i + 1];
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.849",
+  "version": "1.0.852",
   "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/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/linkedin-import/PLUGIN.md

@@ -10,11 +10,11 @@ metadata: {"platform":{"optional":true,"pluginKey":"linkedin-import"}}
 
 # LinkedIn Import
 
-Ingests a LinkedIn Basic Data Export (unzipped directory of CSVs + subdirectories) into the Maxy Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `database-operator` specialist, which owns external-archive ingestion and ad-hoc graph operations.
+Ingests a LinkedIn Basic Data Export (unzipped directory of CSVs + subdirectories) into the Maxy Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `specialists:database-operator` specialist, which owns external-archive ingestion and ad-hoc graph operations.
 
 ## When this applies
 
-The admin agent delegates to `database-operator` when the operator drops a `Basic_LinkedInDataExport_*` directory (or references one by path) into chat. The specialist runs the skill's archive-owner confirmation flow before any CSV is read, then ingests the CSVs the skill has references for.
+The admin agent delegates to `specialists:database-operator` when the operator drops a `Basic_LinkedInDataExport_*` directory (or references one by path) into chat. The specialist runs the skill's archive-owner confirmation flow before any CSV is read, then ingests the CSVs the skill has references for.
 
 ## Intra-plugin growth
 

package/payload/platform/plugins/linkedin-import/skills/linkedin-import/references/connections.md

@@ -110,7 +110,7 @@ Rows missing a position but present with a company produce a `WORKS_FOR` edge wi
 
 ## Post-import verification (operator-side, not agent-side)
 
-After ingest, the operator can verify counts via the `database-operator` specialist's read tools — `mcp__memory__memory-search` with `labels: ["Person"]` plus a filter, or a direct read query through `mcp__graph__maxy-graph-read_neo4j_cypher`:
+After ingest, the operator can verify counts via the `specialists:database-operator` specialist's read tools — `mcp__memory__memory-search` with `labels: ["Person"]` plus a filter, or a direct read query through `mcp__graph__maxy-graph-read_neo4j_cypher`:
 
 ```cypher
 // Owner → connections count
@@ -132,4 +132,4 @@ These are **read queries**, not writes. Cypher writes from the agent are forbidd
 | Tool error "row connectedOn is not ISO 8601" | Parser left `Connected On` in `"23 Apr 2026"` form | Convert to `YYYY-MM-DD` before passing to the tool |
 | Tool error "ownerNodeId not found" | Owner-confirmation flow not run, or operator typed the wrong id | Re-run owner confirmation; pass the resulting `elementId` as `ownerNodeId` |
 | `WORKS_FOR` count « connection count | Many rows have blank company | Expected — LinkedIn doesn't force connections to list a current employer |
-| Tool not present in `init` frame | `database-operator` spawned without the `mcp__memory__memory-archive-write` token | Loud-fail per database-operator's prerogatives. Do not improvise via Bash. Operator must remediate (re-seed specialist templates) |
+| Tool not present in `init` frame | `specialists:database-operator` spawned without the `mcp__memory__memory-archive-write` token | Loud-fail per database-operator's prerogatives. Do not improvise via Bash. Operator must remediate (re-seed specialist templates) |

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

@@ -109,7 +109,7 @@ Before any structured write, load `references/schema-base.md` via `plugin-read`.
 
 ## Document Ingestion
 
-Document ingestion of any kind — PDFs, text, transcripts, web pages, single files — routes to the `database-operator` specialist, which loads the universal `document-ingest` skill at `skills/document-ingest/SKILL.md`. The admin agent never calls `memory-ingest` directly; it dispatches with the document path, the document subject (the anchor node), and the visibility scope.
+Document ingestion of any kind — PDFs, text, transcripts, web pages, single files — routes to the `specialists:database-operator` specialist, which loads the universal `document-ingest` skill at `skills/document-ingest/SKILL.md`. The admin agent never calls `memory-ingest` directly; it dispatches with the document path, the document subject (the anchor node), and the visibility scope.
 
 ### Pipeline
 

package/payload/platform/plugins/memory/references/schema-base.md

@@ -206,7 +206,7 @@ The classifier returns `kind` strings from the closed enumeration above. `kind`
 | `TO` | `KnowledgeDocument` → `Person` or `Organization` | Email direct recipient — written from `documentEdges` per recipient. |
 | `CC` | `KnowledgeDocument` → `Person` or `Organization` | Email cc'd recipient — written from `documentEdges` per cc. |
 | `SPEAKER` | `KnowledgeDocument` → `Person` | Voice-note / single-speaker transcript speaker — written from `documentEdges`. |
-| `MENTIONS` | `KnowledgeDocument` → `Person`, `Organization`, `Service`, `Task`, `Event`, `KnowledgeDocument`, `BrandingData` | Catch-all for entities the dispatch brief named that the document references but for which no document-shape-specific edge applies — written by `database-operator` in the `wire-brief-entities` pipeline step. |
+| `MENTIONS` | `KnowledgeDocument` → `Person`, `Organization`, `Service`, `Task`, `Event`, `KnowledgeDocument`, `BrandingData` | Catch-all for entities the dispatch brief named that the document references but for which no document-shape-specific edge applies — written by `specialists:database-operator` in the `wire-brief-entities` pipeline step. |
 | `DEFINES` | `Section:Definitions` → `DefinedTerm` | Contract definitions — written from per-section `related`. |
 
 **Ontology-growth review query.** When a document accumulates several `:Section:Other` nodes, the operator (or admin agent) can run the following Cypher to surface candidate ontology additions:

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

@@ -79,7 +79,7 @@ The executor can access these capabilities through agentic steps:
 
 | Capability | MCP Server | Infrastructure |
 |---|---|---|
-| Browser automation | `@playwright/mcp` | Chromium with CDP on port 9222 (started by `vnc.sh`, always running) |
+| Browser automation | `@playwright/mcp` | Chromium with CDP on the brand's `cdpPort` from `brand.json` (started by `vnc.sh`, always running) |
 | Any MCP-compatible tool | Declared in step's `mcpServers` | Command must be in PATH on the device |
 
 The executor cannot:

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -255,6 +255,10 @@ The platform also operates an api-wait-ping liveness gate: a heartbeat-driven st
 
 In managed context mode, conversation history is provided within `<conversation-history>` tags. Use `session-compact-status` to retrieve older archived context if needed.
 
+## Thread resumption after a sub-flow
+
+A "sub-flow" is a self-contained run of tool calls — identity repair, LEARNINGS edit, schema audit, attachment unzip — whose subject is not the operator's last stated intent. After the sub-flow returns, the conversation history still holds the operator's earlier request in full. Resume that thread yourself: name what they were asking, then pick it back up. Do not ask the operator to restate, remind, or repeat the intent. Phrases like "What were you originally asking …", "What did you want me to …", or "Remind me what …" delegate the work of holding the thread to the operator and signal that you have treated the prior turn as if it were wiped — when it was not. The exhibit for this rule is the L:2611 turn in stream-4683bd3f, where an OWNS-edge repair returned successfully and the next sentence asked the operator to restate the calendar question they had been pursuing for a thousand prior lines. The platform emits a `[thread-resumption] kind=restate-request` log line when the post-tool assistant text matches one of those phrases, so this regression class is now visible in operations logs even when the operator does not flag it.
+
 ## Tasks
 
 Tasks live in the graph — not in files. The tasks plugin manages them.