@ricsam/r5d-browser 0.0.137 → 0.0.138

package/README.md

@@ -1,43 +1,17 @@
 # r5d-browser
 
-`r5d-browser` starts stable Google Chrome with a dedicated, persistent profile on a Mac and connects it to r5d.dev. It is intended for authenticated web work on the user's behalf, such as configuring external services or reading signed-in content. Sign in to sites in the opened browser normally; agents control Chrome over a loopback-only debugging connection without moving the real system pointer or taking keyboard focus. Routine local application testing should run through Playwright on the worker instead.
+Connect a personal Chrome browser to your r5d account:
 
 ```sh
-npm install -g @ricsam/r5d-browser
+bun install --global @ricsam/r5dctl @ricsam/r5d-browser
+r5dctl auth login
 r5d-browser start
 ```
 
-Install stable [Google Chrome](https://www.google.com/chrome/) before starting the browser. `r5d-browser` resolves the executable in this order:
+For a different environment, use `r5dctl auth login --base-url https://your-environment.example` and `r5d-browser start --base-url https://your-environment.example` with that environment's credential. The client uses the private r5dctl configuration by default. `--token`, `--api-key`, `--config`, `--chrome-path`, and `--profile` are also supported.
 
-1. `--chrome-path <path>`
-2. `R5D_BROWSER_CHROME_PATH`
-3. `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
-4. `~/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
+Chrome must be installed. The client creates a separate persistent profile for each server origin, so the browser's sign-ins remain available when you reconnect. Keep the command running while using browser tools. The browser and its action receipts stay on your machine through server deployments and connection retries.
 
-For example:
+The browser connects over HTTPS using your device credential. It supports tab interaction, screenshots, uploads, downloads, and loopback port forwarding from the chat's worker to your browser machine. Forwarded listeners bind only to `127.0.0.1` and `::1`. Stop a forward in User settings or with the browser stop tool.
 
-```sh
-r5d-browser start --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
-```
-
-The profile is stored under `~/.r5d/browser/chrome-profile`. The previous Chrome for Testing profile at `~/.r5d/browser/profile` is preserved but is not migrated automatically, so sign in again the first time you use the new profile. Browser binaries previously installed under `~/.r5d/browser/browsers` are also left untouched, but new versions of `r5d-browser` do not use them. Completed downloads are retained under `~/.r5d/browser/downloads`; agents can list them and copy a selected file into the active session's artifacts. That artifact is then synchronized to every connected worker. Browser screenshots are session artifacts in r5d.dev and are not retained by the browser process.
-
-Password input values are replaced with `[redacted]` in `browser_read_page` snapshots, including values used in accessibility labels and iframe content. Reading a snapshot preserves the actual form values.
-
-Agents read pages through `browser_read_page`, an accessibility outline with stable element refs (`[ref=e12]`) on interactable elements and `[box=x,y,w,h]` viewport coordinates on everything visible. Refs feed the one-call interaction tools: `browser_mouse_click` clicks a ref (scrolled into view, with actionability checks) or an x/y point, `browser_form_input` sets values on text inputs, selects, checkboxes, and contenteditable elements with trusted events that controlled (React-style) components honor, and `browser_scroll` scrolls an element into view or dispatches trusted wheel input. Same-origin iframe content appears inline with frame-prefixed refs such as `f1e3`; cross-origin frame content may be omitted. Refs come from the most recent snapshot of a tab, so agents re-read the page after navigations or large re-renders. `browser_wait_for` waits for a selector, visible text, a URL glob, or a load state instead of sleeping, and `browser_keyboard_type` has a `keys` mode that presses each character as a real key event (up to 500 characters per call) for type-ahead widgets — characters without key codes, such as emoji, still fall back to text insertion. Screenshots capture the viewport by default; `fullPage: true` captures the scrollable page up to 4000 CSS px of height.
-
-Agents attach worker files with `browser_upload_files({ tabId, files, ref })`, or `selector` instead of `ref` for a hidden file input. `files` contains up to 100 regular-file paths on the session's bound worker: absolute paths, paths relative to the session working directory, `~/` paths, or paths using `$R5D_ROOT` and `$R5D_SESSION_ID`. The files may live outside the repository. Multiple files require an input with `multiple`; directory inputs and native file-picker dialogs are not supported.
-
-The operation reads the source files in 1 MiB chunks, relays them through r5d.dev without storing their bytes in artifacts or recovery journals, verifies size and SHA-256, and attaches them using Playwright. Browser copies live in private, generated folders under `~/.r5d/browser/uploads`, preserving filenames even when several files share a name. Completed copies remain until their tab closes or r5d-browser exits so later form submission can still read them. Failed transfers are removed; abandoned partial transfers expire after five minutes without activity, and the next browser start clears staging left after a crash. There is no per-file byte limit; one operation has a 30-minute deadline. Changed source files, disconnections, stale target elements, and session cancellation fail the operation without automatically retrying attachment. Both the worker and browser must advertise upload support.
-
-Setting a file input fires its normal input/change events, which may immediately start a site's upload. For forms that require a separate submit action, the agent submits afterwards. The result reports attached filenames and byte sizes; it does not claim the website finished processing them.
-
-Agents running JavaScript in a page can save captured text straight into the active session's artifacts by calling `r5dCreateArtifact(filename, content)`, which takes two strings and must be called before the agent's code returns. Each captured file is written to the session artifacts in r5d.dev, synchronized to every connected worker, and reported back under `$R5D_ROOT/artifacts/$R5D_SESSION_ID`; a single call may create at most 32 files totalling 4 MiB. The function is passed into the agent's code rather than assigned to `window`, so pages can neither call it nor use it to detect automation.
-
-For responsive testing that needs an existing login (for example, an app using Google login), agents can call `browser_set_viewport` with `{ tabId, width: 390, height: 844 }`. Both dimensions must be integers from 1 to 4096 CSS pixels. The override is scoped to that tab, even in a shared window: it does not resize the OS window or affect other tabs. It preserves the profile, user agent, touch support, and device pixel ratio; this is layout sizing, not mobile-device emulation. It adds no Chrome launch flags or webdriver spoofing; `navigator.webdriver` remains natively `false`.
-
-The viewport survives navigation, reloads, and r5d.dev control-connection reconnects until the agent calls `browser_set_viewport` with `{ tabId, reset: true }`, closes the tab, or exits the browser. Reset restores sizing from the current OS window; omit width/height when resetting. The tool returns the actual width and height. Re-read the page or capture a screenshot after resizing because old coordinates are stale, and reset when testing is finished. To apply a size before the first page load, open `about:blank`, set its viewport, then navigate. An outdated browser client returns an update-and-restart instruction for this tool.
-
-As an escape hatch, agents can create loopback-only TCP port forwards from this Mac to the worker bound to a chat when a local flow specifically needs this browser's authenticated state or human interaction, such as testing Google OAuth. Ordinary local application testing should use Playwright directly on the worker without a forward. For example, a forward can map Chrome's `localhost:4323` to `127.0.0.1:3232` on that worker. The relay preserves raw TCP traffic, including HTTP, HTTPS, WebSockets, HMR, and SSE; it never exposes a public listener or permits an arbitrary target host.
-
-Port forwards remain active across agent turns and r5d.dev control-connection reconnects. They are owned by the running `r5d-browser` process, so restarting that process ends them. Agents can list and stop forwards, and the user can inspect or stop them from Settings.
+Operators may also start an independently supervised keeper with `r5d-browser --config /absolute/private/browser-keeper.json`. That configuration binds the installation, user, browser factory, profile, ledger, and permitted adapter credentials.

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.137",
+  "version": "0.0.138",
   "type": "commonjs"
 }

package/dist/mjs/browser-input.mjs

@@ -1,3 +1,4 @@
+import { parseUploadTarget } from "@ricsam/r5d-api/browser-upload";
 const browserInputFields = {
   list_tabs: { required: [], optional: [] },
   list_downloads: { required: [], optional: [] },
@@ -54,8 +55,62 @@ function normalizeBrowserInput(action, input) {
   }
   return normalized;
 }
+function preflightBrowserInput(action, raw) {
+  const input = normalizeBrowserInput(action, raw);
+  const ref = () => {
+    if (typeof input.ref !== "string" || !/^(f\d+)?e\d+$/.test(input.ref))
+      throw new Error('ref must look like "e12" or "f1e3", exactly as printed by browser_read_page ([ref=e12]).');
+  };
+  const coordinates = (message) => {
+    if (!Number.isFinite(Number(input.x)) || !Number.isFinite(Number(input.y))) throw new Error(message);
+  };
+  if (action === "port_forward") {
+    for (const name of ["workerPort", "browserPort"])
+      if ((name === "workerPort" || input[name] !== void 0) && (!Number.isInteger(input[name]) || Number(input[name]) < 1 || Number(input[name]) > 65535))
+        throw new Error(`${name} must be an integer from 1 to 65535.`);
+    if (Object.keys(input).some((name) => !["workerPort", "browserPort"].includes(name))) throw new Error("port_forward accepts only workerPort and browserPort.");
+  }
+  if (action === "stop_port_forward" && (typeof input.forwardId !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,199}$/.test(input.forwardId)))
+    throw new Error("stop_port_forward requires a valid forwardId.");
+  if (action === "set_viewport") parseViewportInput(input);
+  if (action === "move_mouse") coordinates("move_mouse requires numeric x and y coordinates.");
+  if (action === "mouse_click") {
+    if (input.ref !== void 0) {
+      if (input.x !== void 0 || input.y !== void 0) throw new Error("mouse_click accepts ref or x/y, not both.");
+      ref();
+    } else if (input.x !== void 0 || input.y !== void 0) coordinates("mouse_click by coordinates requires numeric x and y.");
+  }
+  if (action === "scroll") {
+    if (input.ref !== void 0) {
+      if (input.direction !== void 0) throw new Error("scroll accepts ref or direction, not both.");
+      ref();
+    } else {
+      if (!["up", "down", "left", "right"].includes(String(input.direction)))
+        throw new Error('scroll requires ref, or direction "up", "down", "left", or "right".');
+      if (input.x !== void 0 || input.y !== void 0) coordinates("scroll requires numeric x and y when provided.");
+    }
+  }
+  if (action === "upload_files" || action === "upload_begin") parseUploadTarget(input);
+  if (action === "wait_for") {
+    const provided = ["selector", "text", "url", "loadState"].filter((key) => input[key] !== void 0);
+    if (provided.length !== 1) throw new Error("wait_for requires exactly one of selector, text, url, or loadState.");
+    if (provided[0] === "loadState") {
+      if (!["load", "domcontentloaded", "networkidle"].includes(String(input.loadState)))
+        throw new Error('wait_for loadState must be "load", "domcontentloaded", or "networkidle".');
+    } else if (typeof input[provided[0]] !== "string") throw new Error(`wait_for ${provided[0]} must be a string.`);
+  }
+  if (action === "form_input") {
+    ref();
+    const provided = ["value", "values", "checked"].filter((key) => input[key] !== void 0);
+    if (provided.length !== 1) throw new Error("form_input requires exactly one of value, values, or checked.");
+    if (provided[0] === "values" && (!Array.isArray(input.values) || input.values.some((value) => typeof value !== "string")))
+      throw new Error("form_input values must be an array of strings.");
+  }
+  return input;
+}
 export {
   MAX_VIEWPORT_DIMENSION,
   normalizeBrowserInput,
-  parseViewportInput
+  parseViewportInput,
+  preflightBrowserInput
 };

package/dist/mjs/cli-options.mjs

@@ -32,6 +32,7 @@ function parseBrowserArgs(argv) {
       ["--api-key", "apiKey"],
       ["--config", "configPath"],
       ["--profile", "profilePath"],
+      ["--root", "rootPath"],
       ["--chrome-path", "chromePath"]
     ];
     let matched = false;

package/dist/mjs/main.mjs

@@ -1,404 +1,33 @@
 #!/usr/bin/env bun
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import WebSocket from "ws";
-import { BrowserRuntime } from "./browser-runtime.mjs";
+import { startConfiguredBrowserKeeper } from "./runtime/main.mjs";
 import { parseBrowserArgs } from "./cli-options.mjs";
-import { defaultChromeLockPath, defaultChromeProfilePath, launchStableChrome } from "./chrome-launcher.mjs";
-import { BrowserPortForwardManager } from "./port-forward-manager.mjs";
-const DEFAULT_BASE_URL = "https://r5d.dev";
-const PACKAGE_NAME = "@ricsam/r5d-browser";
-const RECONNECT_DELAY_MS = 2e3;
-const SERVER_HEARTBEAT_TIMEOUT_MS = 45e3;
-const CHROME_DISCONNECT_EXIT_GRACE_MS = 2e3;
-function browserRoot() {
-  return path.join(os.homedir(), ".r5d", "browser");
-}
-function printHelp() {
-  process.stdout.write(`Usage:
-  r5d-browser start [--base-url <url>] [--token <token>] [--api-key <key>]
-  r5d-browser --version
-
-Options:
-  --base-url <url>      r5d.dev base URL (default from r5dctl config or ${DEFAULT_BASE_URL})
-  --token <token>       r5d device credential
-  --api-key <key>       r5d API key
-  --config <path>       Shared r5dctl config path
-  --profile <path>      Google Chrome profile path (default ~/.r5d/browser/chrome-profile)
-  --chrome-path <path>  Google Chrome executable (default: auto-detect stable Chrome)
-  -v, --version         Show r5d-browser version
-  -h, --help            Show this help
-`);
-}
-function findVersion() {
-  let current = process.argv[1] ? path.dirname(path.resolve(process.argv[1])) : process.cwd();
-  for (let index = 0; index < 12; index += 1) {
-    try {
-      const parsed = JSON.parse(fs.readFileSync(path.join(current, "package.json"), "utf8"));
-      if (parsed.name === PACKAGE_NAME && parsed.version) return parsed.version;
-    } catch {
-    }
-    try {
-      const sourceVersion = fs.readFileSync(path.join(current, "VERSION.txt"), "utf8").trim();
-      if (sourceVersion && path.basename(current) === "packages") return sourceVersion;
-    } catch {
-    }
-    const parent = path.dirname(current);
-    if (parent === current) break;
-    current = parent;
-  }
-  return "unknown";
-}
-function readConfig(configPath) {
-  if (!fs.existsSync(configPath)) return {};
-  const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
-  return {
-    baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : void 0,
-    token: typeof parsed.token === "string" ? parsed.token : void 0,
-    apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0
-  };
-}
-function resolveConnection(options) {
-  const config = readConfig(options.configPath);
-  const token = options.token ?? process.env.R5D_BROWSER_TOKEN ?? process.env.R5D_TOKEN ?? process.env.R5DCTL_TOKEN ?? config.token ?? options.apiKey ?? process.env.R5D_API_KEY ?? process.env.R5DCTL_API_KEY ?? config.apiKey;
-  if (!token) throw new Error("Authentication required. Run `r5dctl auth login` or pass --token/--api-key.");
-  return {
-    baseUrl: (options.baseUrl ?? process.env.R5D_BASE_URL ?? process.env.R5DCTL_BASE_URL ?? config.baseUrl ?? DEFAULT_BASE_URL).replace(
-      /\/+$/,
-      ""
-    ),
-    token
-  };
-}
-function loadInstanceId() {
-  const instancePath = path.join(browserRoot(), "instance-id");
-  fs.mkdirSync(path.dirname(instancePath), { recursive: true });
-  try {
-    const id2 = fs.readFileSync(instancePath, "utf8").trim();
-    if (id2) return id2;
-  } catch {
-  }
-  const id = crypto.randomUUID();
-  fs.writeFileSync(instancePath, `${id}
-`, { mode: 384 });
-  return id;
-}
-async function waitForReconnectDelay(signal) {
-  if (signal.aborted) return;
-  await new Promise((resolve) => {
-    const finish = () => {
-      clearTimeout(timer);
-      signal.removeEventListener("abort", finish);
-      resolve();
-    };
-    const timer = setTimeout(finish, RECONNECT_DELAY_MS);
-    signal.addEventListener("abort", finish, { once: true });
-  });
-}
-async function connectLoop(params) {
-  while (!params.signal.aborted) {
-    const url = new URL("/browser/ws", params.baseUrl);
-    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-    url.searchParams.set("instance", params.instanceId);
-    url.searchParams.set("version", findVersion());
-    let socket = null;
-    let watchdog;
-    const closeForAbort = () => socket?.close(1e3, "r5d-browser shutting down");
-    try {
-      socket = new WebSocket(url, { headers: { Authorization: `Bearer ${params.token}` } });
-      socket.on("error", () => void 0);
-      params.signal.addEventListener("abort", closeForAbort, { once: true });
-      await new Promise((resolve, reject) => {
-        socket.addEventListener("open", () => resolve(), { once: true });
-        socket.addEventListener("error", () => reject(new Error("WebSocket connection failed.")), { once: true });
-        socket.addEventListener("close", () => reject(new Error("WebSocket closed before connecting.")), { once: true });
-      });
-      if (params.signal.aborted) break;
-      process.stdout.write(`[r5d-browser] connected to ${params.baseUrl}
-`);
-      socket.send(
-        JSON.stringify({
-          type: "hello",
-          hostInfo: {
-            hostname: os.hostname(),
-            platform: process.platform,
-            arch: process.arch,
-            version: findVersion(),
-            chromiumVersion: params.chromiumVersion,
-            profilePath: params.profilePath,
-            capabilities: {
-              portForwarding: true,
-              runJsArtifacts: true,
-              readPage: true,
-              passwordRedaction: true,
-              refActions: true,
-              waitFor: true,
-              formInput: true,
-              typedKeys: true,
-              screenshotFullPage: true,
-              viewportSizing: true,
-              fileUploads: true
-            }
-          },
-          tabs: await params.runtime.listTabs(),
-          portForwards: params.portForwards.list()
-        })
-      );
-      let lastServerMessageAt = Date.now();
-      watchdog = setInterval(() => {
-        if (Date.now() - lastServerMessageAt >= SERVER_HEARTBEAT_TIMEOUT_MS) socket?.close();
-      }, 5e3);
-      await new Promise((resolve) => {
-        socket.addEventListener("message", (event) => {
-          if (params.signal.aborted) return;
-          lastServerMessageAt = Date.now();
-          void (async () => {
-            const message = JSON.parse(String(event.data));
-            if (message.type === "ping") {
-              socket?.send(JSON.stringify({ type: "pong" }));
-              return;
-            }
-            if (message.type === "port_forward_start") {
-              try {
-                await params.portForwards.start(message.forward);
-                socket?.send(JSON.stringify({ type: "port_forward_result", requestId: message.requestId, forward: message.forward }));
-              } catch (error) {
-                socket?.send(
-                  JSON.stringify({
-                    type: "port_forward_result",
-                    requestId: message.requestId,
-                    error: error instanceof Error ? error.message : String(error)
-                  })
-                );
-              }
-              return;
-            }
-            if (message.type === "port_forward_stop") {
-              try {
-                await params.portForwards.stop(message.forwardId);
-                socket?.send(JSON.stringify({ type: "port_forward_result", requestId: message.requestId }));
-              } catch (error) {
-                socket?.send(
-                  JSON.stringify({
-                    type: "port_forward_result",
-                    requestId: message.requestId,
-                    error: error instanceof Error ? error.message : String(error)
-                  })
-                );
-              }
-              return;
-            }
-            if (message.type !== "operation") return;
-            try {
-              if (["upload_begin", "upload_chunk", "upload_abort"].includes(message.action)) {
-                const result2 = await params.runtime.execute(message.action, message.input);
-                socket?.send(JSON.stringify({ type: "operation_result", requestId: message.requestId, result: result2 }));
-                return;
-              }
-              const beforeTabs = await params.runtime.listTabs();
-              const operationResult = await params.runtime.execute(message.action, message.input);
-              const tabs = await params.runtime.listTabs();
-              const beforeIds = new Set(beforeTabs.map((tab) => tab.tabId));
-              const openedTabs = tabs.filter((tab) => !beforeIds.has(tab.tabId));
-              const result = operationResult && typeof operationResult === "object" ? { ...operationResult, openedTabs } : { result: operationResult, openedTabs };
-              socket?.send(JSON.stringify({ type: "operation_result", requestId: message.requestId, result }));
-              socket?.send(JSON.stringify({ type: "tabs_snapshot", tabs }));
-            } catch (error) {
-              socket?.send(
-                JSON.stringify({
-                  type: "operation_result",
-                  requestId: message.requestId,
-                  error: error instanceof Error ? error.message : String(error)
-                })
-              );
-            }
-          })();
-        });
-        socket.addEventListener("close", () => resolve(), { once: true });
-      });
-    } catch (error) {
-      if (!params.signal.aborted) process.stderr.write(`[r5d-browser] ${error instanceof Error ? error.message : String(error)}
-`);
-    } finally {
-      if (watchdog) clearInterval(watchdog);
-      params.signal.removeEventListener("abort", closeForAbort);
-      socket?.close();
-    }
-    if (params.signal.aborted) break;
-    process.stdout.write(`[r5d-browser] disconnected; reconnecting...
-`);
-    await waitForReconnectDelay(params.signal);
-  }
-}
-function isProcessAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return error.code === "EPERM";
-  }
-}
-async function waitUpTo(promise, timeoutMs) {
-  let timer;
-  try {
-    return await Promise.race([
-      promise.then(() => true),
-      new Promise((resolve) => {
-        timer = setTimeout(() => resolve(false), timeoutMs);
-      })
-    ]);
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
-async function resultWithin(promise, timeoutMs) {
-  let timer;
-  try {
-    return await Promise.race([
-      promise,
-      new Promise((resolve) => {
-        timer = setTimeout(() => resolve(void 0), timeoutMs);
-      })
-    ]);
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
-async function start(options) {
-  if (process.platform !== "darwin") throw new Error("r5d-browser currently supports macOS only.");
-  const { baseUrl, token } = resolveConnection(options);
-  const requestedProfilePath = path.resolve(options.profilePath ?? defaultChromeProfilePath());
-  const downloadsPath = path.join(browserRoot(), "downloads");
-  const playwrightDownloadsPath = path.join(downloadsPath, ".playwright");
-  fs.mkdirSync(playwrightDownloadsPath, { recursive: true, mode: 448 });
-  let requestedSignalOutcome;
-  let requestStop = () => void 0;
-  const requestedStop = new Promise((resolve) => {
-    requestStop = resolve;
-  });
-  const signalHandlers = /* @__PURE__ */ new Map();
-  const processEvents = process;
-  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-    const handler = () => {
-      requestedSignalOutcome ??= { exitCode: 0 };
-      requestStop(requestedSignalOutcome);
-    };
-    signalHandlers.set(signal, handler);
-    process.on(signal, handler);
-  }
-  let launch;
-  try {
-    launch = await launchStableChrome({
-      chromePath: options.chromePath,
-      profilePath: requestedProfilePath,
-      playwrightDownloadsPath,
-      lockPath: defaultChromeLockPath(),
-      onLaunchAttemptFailed: (attempt, attempts, error) => {
-        process.stderr.write(
-          `[r5d-browser] Chrome launch attempt ${attempt}/${attempts} failed: ${error instanceof Error ? error.message : String(error)}
-`
-        );
-      }
-    });
-  } catch (error) {
-    for (const [signal, handler] of signalHandlers) processEvents.off(signal, handler);
-    throw error;
+import { startPersonalBrowser } from "./personal-main.mjs";
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--version")) {
+    console.log(`r5d-browser ${true ? "0.0.138" : "development"}`);
+    return;
   }
-  if (requestedSignalOutcome) {
-    try {
-      await launch.close();
-    } finally {
-      for (const [signal, handler] of signalHandlers) processEvents.off(signal, handler);
-    }
+  if (!args.length || args.includes("--help")) {
+    console.log("Usage: r5d-browser start [--base-url https://r5d.dev] [--token credential] [--config r5dctl-config] [--profile path] [--root <path>] [--chrome-path <path>]\n       r5d-browser --config /absolute/private/browser-keeper.json\n\nConnects your persistent Google Chrome profile to your r5d account. Sign in with r5dctl auth login first.\n--root sets the private r5d state base directory (an environment-specific subdirectory is added). It does not change Chrome's HOME.");
     return;
   }
-  try {
-    const profilePath = launch.profilePath;
-    const uploadsPath = path.join(browserRoot(), "uploads");
-    fs.rmSync(uploadsPath, { recursive: true, force: true });
-    const runtime = new BrowserRuntime(launch.context, downloadsPath, uploadsPath);
-    const instanceId = loadInstanceId();
-    const portForwards = new BrowserPortForwardManager(baseUrl, token, instanceId);
-    process.stdout.write(`[r5d-browser] profile: ${profilePath}
-`);
-    process.stdout.write(`[r5d-browser] downloads: ${downloadsPath}
-`);
-    process.stdout.write(`[r5d-browser] Google Chrome ${launch.chromeVersion}; navigator.webdriver is disabled.
-`);
-    process.stdout.write(`[r5d-browser] agents use synthetic Chrome input; your system pointer and keyboard stay untouched.
-`);
-    const abortController = new AbortController();
-    const controlLoop = connectLoop({
-      runtime,
-      portForwards,
-      baseUrl,
-      token,
-      instanceId,
-      profilePath,
-      chromiumVersion: launch.chromeVersion,
-      signal: abortController.signal
-    });
-    const controlStopped = controlLoop.then(
-      () => ({ exitCode: abortController.signal.aborted ? 0 : 1, message: "The r5d.dev browser control loop stopped unexpectedly." }),
-      (error) => ({
-        exitCode: 1,
-        message: `The r5d.dev browser control loop failed: ${error instanceof Error ? error.message : String(error)}`
-      })
-    );
-    const chromeExited = launch.exited.then(({ code, signal }) => ({
-      exitCode: code === 0 ? 0 : 1,
-      message: code === 0 ? void 0 : `Google Chrome exited unexpectedly (${signal ? `signal ${signal}` : `code ${code ?? "unknown"}`}).`
-    }));
-    const chromeDisconnected = launch.disconnected.then(async () => {
-      const exitOutcome = await resultWithin(chromeExited, CHROME_DISCONNECT_EXIT_GRACE_MS);
-      if (exitOutcome) return exitOutcome;
-      if (!isProcessAlive(launch.chromePid)) return await chromeExited;
-      return { exitCode: 1, message: "The Google Chrome control connection closed unexpectedly." };
-    });
-    const outcome = await Promise.race([requestedStop, chromeExited, chromeDisconnected, controlStopped]);
-    abortController.abort();
-    let cleanupError;
-    try {
-      await portForwards.close();
-    } catch (error) {
-      cleanupError = error;
-    }
-    try {
-      if (!await waitUpTo(runtime.drainDownloads(), 5e3)) {
-        process.stderr.write("[r5d-browser] timed out waiting for active downloads during shutdown.\n");
-      }
-    } catch (error) {
-      cleanupError ??= error;
-    }
-    try {
-      await launch.close();
-    } catch (error) {
-      cleanupError ??= error;
-    }
-    runtime.closeUploads();
-    await controlStopped;
-    for (const [signal, handler] of signalHandlers) processEvents.off(signal, handler);
-    if (outcome.exitCode !== 0) throw new Error(outcome.message ?? "Google Chrome stopped unexpectedly.");
-    if (cleanupError) throw cleanupError;
-  } catch (error) {
-    try {
-      await launch.close().catch(() => void 0);
-    } finally {
-      for (const [signal, handler] of signalHandlers) processEvents.off(signal, handler);
-    }
-    throw error;
+  if (args[0] === "start") {
+    await startPersonalBrowser(parseBrowserArgs(args).options, true ? "0.0.138" : "development");
+    return;
   }
+  if (args.length !== 2 || args[0] !== "--config" || !args[1]?.startsWith("/")) throw new Error("An absolute private browser keeper configuration is required");
+  const service = await startConfiguredBrowserKeeper(args[1]);
+  let closing = false;
+  const close = () => {
+    if (closing) return;
+    closing = true;
+    void service.close().then(() => process.exit(0), () => process.exit(1));
+  };
+  process.once("SIGTERM", close);
+  process.once("SIGINT", close);
 }
-async function main() {
-  const { command, options } = parseBrowserArgs(process.argv.slice(2));
-  if (command === "help") return printHelp();
-  if (command === "version") return void process.stdout.write(`r5d-browser ${findVersion()}
-`);
-  await start(options);
-}
-main().catch((error) => {
-  process.stderr.write(`r5d-browser: ${error instanceof Error ? error.message : String(error)}
-`);
-  process.exit(1);
+void main().catch(() => {
+  console.error("Browser keeper startup failed; check private configuration and exclusive ownership");
+  process.exitCode = 1;
 });

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.137",
+  "version": "0.0.138",
   "type": "module"
 }

package/dist/mjs/personal-diagnostics.mjs

@@ -0,0 +1,24 @@
+function browserErrorCategory(error) {
+  const message = error instanceof Error ? error.message : "";
+  if (/timeout|timed out/i.test(message)) return "timeout";
+  if (/closed|disconnect|ECONNRESET|ECONNREFUSED/i.test(message)) return "disconnected";
+  if (/required|invalid|must be|must look|ref or x\/y/i.test(message)) return "invalid-input";
+  return "other";
+}
+function personalBrowserDiagnosticObserver(enabled, write = (line) => process.stderr.write(line)) {
+  return (event) => {
+    if (!enabled) return;
+    const { phase, method, bytes, status, category } = event;
+    const code = event.code && /^[a-z_]{1,100}$/.test(event.code) ? event.code : void 0;
+    const action = event.action && /^[a-z_]{1,32}$/.test(event.action) ? event.action : void 0;
+    try {
+      write(`[r5d-browser-diagnostic] ${JSON.stringify({ phase, method, bytes, status, code, action, category })}
+`);
+    } catch {
+    }
+  };
+}
+export {
+  browserErrorCategory,
+  personalBrowserDiagnosticObserver
+};