@askjo/camofox-browser 1.8.8 → 1.8.11

package/README.md

@@ -76,7 +76,7 @@ The Docker image includes yt-dlp. For local dev, install it for the `/youtube/tr
 openclaw plugins install @askjo/camofox-browser
 ```
 
-**Tools:** `camofox_create_tab` · `camofox_snapshot` · `camofox_click` · `camofox_type` · `camofox_navigate` · `camofox_scroll` · `camofox_screenshot` · `camofox_close_tab` · `camofox_list_tabs` · `camofox_import_cookies`
+**Tools:** `camofox_create_tab`  |  `camofox_snapshot`  |  `camofox_click`  |  `camofox_type`  |  `camofox_navigate`  |  `camofox_scroll`  |  `camofox_screenshot`  |  `camofox_close_tab`  |  `camofox_list_tabs`  |  `camofox_import_cookies`
 
 ### Standalone
 
@@ -111,7 +111,7 @@ make up ARCH=x86_64
 make up VERSION=135.0.1 RELEASE=beta.24
 ```
 
-> **⚠️ Do not run `docker build` directly.** The Dockerfile uses bind mounts to pull pre-downloaded binaries from `dist/`. Always use `make up` (or `make fetch` then `make build`) -- it downloads the binaries first.
+> **WARNING: Do not run `docker build` directly.** The Dockerfile uses bind mounts to pull pre-downloaded binaries from `dist/`. Always use `make up` (or `make fetch` then `make build`) -- it downloads the binaries first.
 
 ### Fly.io
 
@@ -183,18 +183,18 @@ The agent calls `camofox_import_cookies` -> reads the file -> POSTs to the serve
 
 ```
 ~/.camofox/cookies/linkedin.txt          (Netscape format, on disk)
-        │
-        ▼
+        |
+        v
 camofox_import_cookies tool              (parses file, filters by domain)
-        │
-        ▼  POST /sessions/:userId/cookies
-        │  Authorization: Bearer <CAMOFOX_API_KEY>
-        │  Body: { cookies: [Playwright cookie objects] }
-        ▼
+        |
+        v  POST /sessions/:userId/cookies
+        |  Authorization: Bearer <CAMOFOX_API_KEY>
+        |  Body: { cookies: [Playwright cookie objects] }
+        v
 camofox server                           (validates, sanitizes, injects)
-        │
-        ▼  context.addCookies(...)
-        │
+        |
+        v  context.addCookies(...)
+        |
 Camoufox browser session                 (authenticated browsing)
 ```
 
@@ -208,10 +208,10 @@ By default, camofox persists each user's cookies and localStorage to `~/.camofox
 
 ```
 ~/.camofox/
-├── cookies/          # Bootstrap cookie files (Netscape format)
-└── profiles/         # Persisted session state (auto-managed)
-    └── <hashed-userId>/
-        └── storage_state.json
+|-- cookies/          # Bootstrap cookie files (Netscape format)
+\-- profiles/         # Persisted session state (auto-managed)
+    \-- <hashed-userId>/
+        \-- storage_state.json
 ```
 
 Override the directory with `CAMOFOX_PROFILE_DIR` or set `"profileDir"` in the persistence plugin config. To disable persistence, set `"persistence": { "enabled": false }` in `camofox.config.json`.
@@ -350,11 +350,11 @@ Reports are sent to a lightweight Cloudflare Worker relay at [`https://camofox-c
 
 ```
 lib/reporter.js (client, no secrets)
-    │  anonymize -> POST https://camofox-crash-relay.askjo.workers.dev/report
-    ▼
+    |  anonymize -> POST https://camofox-crash-relay.askjo.workers.dev/report
+    v
 Cloudflare Worker (holds GitHub App key)
-    │  validate -> rate-limit -> dedup -> create GitHub Issue
-    ▼
+    |  validate -> rate-limit -> dedup -> create GitHub Issue
+    v
 GitHub Issue created
 ```
 
@@ -385,7 +385,7 @@ Or skip verification entirely: `CAMOFOX_CRASH_REPORT_ENABLED=false` disables all
 
 All reported data goes through paranoid anonymization ([`lib/reporter.js` L28-290](lib/reporter.js#L28-L290)) before leaving the process:
 
-- **URLs** -- well-known public domains (Google, Amazon, Reddit, Cloudflare, etc.) are shown verbatim so we can identify which sites cause problems. Private/unknown domains are replaced with a stable HMAC hash (`site-a1b2c3d4`) -- same hash across reports for correlation, but not reversible to the original domain. Path segments become `•/•/•` (depth only). Query params become `?[3]` (count only). No keys, values, or path content is ever included.
+- **URLs** -- well-known public domains (Google, Amazon, Reddit, Cloudflare, etc.) are shown verbatim so we can identify which sites cause problems. Private/unknown domains are replaced with a stable HMAC hash (`site-a1b2c3d4`) -- same hash across reports for correlation, but not reversible to the original domain. Path segments become `*/*/*` (depth only). Query params become `?[3]` (count only). No keys, values, or path content is ever included.
 - **File paths** -> stripped to filename only (`<path>/server.js`)
 - **Tokens, secrets, API keys** -> `<token>`
 - **IPs, emails, env vars** -> redacted
@@ -528,7 +528,7 @@ curl -X POST http://localhost:9377/tabs/TAB_ID/navigate \
 curl -X POST http://localhost:9377/youtube/transcript \
   -H 'Content-Type: application/json' \
   -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "languages": ["en"]}'
-# -> { "status": "ok", "transcript": "[00:18] ♪ We're no strangers to love ♪\n...", "video_title": "...", "total_words": 548 }
+# -> { "status": "ok", "transcript": "[00:18] [music] We're no strangers to love [music]\n...", "video_title": "...", "total_words": 548 }
 ```
 
 Uses [yt-dlp](https://github.com/yt-dlp/yt-dlp) when available (fast, no browser needed). Falls back to a browser-based intercept method if yt-dlp is not installed -- this is slower and less reliable due to YouTube ad pre-rolls.
@@ -550,7 +550,7 @@ Uses [yt-dlp](https://github.com/yt-dlp/yt-dlp) when available (fast, no browser
 
 ## Search Macros
 
-`@google_search` · `@youtube_search` · `@amazon_search` · `@reddit_search` · `@reddit_subreddit` · `@wikipedia_search` · `@twitter_search` · `@yelp_search` · `@spotify_search` · `@netflix_search` · `@linkedin_search` · `@instagram_search` · `@tiktok_search` · `@twitch_search`
+`@google_search`  |  `@youtube_search`  |  `@amazon_search`  |  `@reddit_search`  |  `@reddit_subreddit`  |  `@wikipedia_search`  |  `@twitter_search`  |  `@yelp_search`  |  `@spotify_search`  |  `@netflix_search`  |  `@linkedin_search`  |  `@instagram_search`  |  `@tiktok_search`  |  `@twitch_search`
 
 Reddit macros return JSON directly (no HTML parsing needed):
 - `@reddit_search` - search all of Reddit, returns JSON with 25 results
@@ -600,18 +600,58 @@ Reddit macros return JSON directly (no HTML parsing needed):
 
 ```
 Browser Instance (Camoufox)
-└── User Session (BrowserContext) - isolated cookies/storage
-    ├── Tab Group (sessionKey: "conv1")
-    │   ├── Tab (google.com)
-    │   └── Tab (github.com)
-    └── Tab Group (sessionKey: "conv2")
-        └── Tab (amazon.com)
+\-- User Session (BrowserContext) - isolated cookies/storage
+    |-- Tab Group (sessionKey: "conv1")
+    |   |-- Tab (google.com)
+    |   \-- Tab (github.com)
+    \-- Tab Group (sessionKey: "conv2")
+        \-- Tab (amazon.com)
 ```
 
 Sessions auto-expire after 30 minutes of inactivity. The browser itself shuts down after 5 minutes with no active sessions, and relaunches on the next request.
 
 When a session's tab limit is reached, the oldest/least-used tab is automatically recycled instead of returning an error -- so long-running agent sessions don't hit dead ends.
 
+## Security Model
+
+This section documents the security boundaries of camofox-browser for users and automated security reviewers.
+
+### Code isolation
+
+All `process.env` reads are centralized in `lib/config.js`. All `child_process` usage is in `lib/launcher.js` (server subprocess) and `plugins/youtube/youtube.js` (yt-dlp). The main `server.js` has route handlers but zero `process.env` reads and zero `child_process` imports. No single file combines environment/credential access with network sends.
+
+### No embedded secrets
+
+Zero credentials, private keys, API tokens, or signing keys ship in this package. All secrets are provided at runtime via environment variables (`CAMOFOX_API_KEY`, `CAMOFOX_ACCESS_KEY`) or are Cloudflare Worker environment secrets (crash relay GitHub App key).
+
+### Cookie import is disabled by default
+
+The cookie import endpoint (`POST /sessions/:userId/cookies`) is gated behind `CAMOFOX_API_KEY`. If this env var is not set, the server rejects all cookie import requests with HTTP 403. Cookie files are read from a sandboxed directory (`~/.camofox/cookies/`) with path traversal protection -- attempts to escape the directory are blocked. Max 500 cookies per request, 5MB file size limit.
+
+### Access control
+
+`CAMOFOX_ACCESS_KEY` provides global bearer token authentication for all routes (except `/health`). When set, every request must include `Authorization: Bearer <key>`. Recommended for any deployment beyond localhost.
+
+### Binary download
+
+The Camoufox browser engine (~300MB) is downloaded at `npm install` time by [`camoufox-js`](https://www.npmjs.com/package/camoufox-js), an npm package maintained by the [Camoufox project](https://camoufox.com). It downloads from [official GitHub releases](https://github.com/nicedayzhu/camoufox/releases) with integrity verification handled by `camoufox-js`. No custom download URLs, no URL shorteners, no raw IP addresses.
+
+### Crash reporting
+
+Anonymized crash/hang reports are sent to a Cloudflare Worker relay. The relay source is [in this repo](workers/crash-reporter/index.ts) and auditable. Verification: `GET /source` on the relay returns the deployed commit hash and sha256 so you can compare against the repo. The reporter ([`lib/reporter.js` L28-290](lib/reporter.js#L28-L290)) applies paranoid anonymization: private domains are HMAC-hashed (not reversible), paths are stripped, tokens/IPs/emails are redacted. No page content, cookies, or user data is ever sent. Disable with `CAMOFOX_CRASH_REPORT_ENABLED=false` or point to your own relay with `CAMOFOX_CRASH_REPORT_URL`.
+
+### Session persistence
+
+The persistence plugin saves cookies and localStorage to `~/.camofox/profiles/<hashed-userId>/` so authenticated sessions survive browser restarts. UserIds are hashed for directory names. Disable via `camofox.config.json` by removing `persistence` from the plugins array.
+
+### Network access
+
+Outbound connections are made to: (1) URLs the agent navigates to (core functionality), (2) the crash report relay (anonymized, opt-out available). Inbound: the REST API on localhost:9377 (default), optionally protected by `CAMOFOX_ACCESS_KEY`.
+
+### Subprocess usage
+
+Two subprocesses may be spawned: (1) the Camoufox browser engine (core functionality, `lib/launcher.js`), (2) yt-dlp for YouTube transcript extraction (optional, `plugins/youtube/youtube.js`). Both are isolated in dedicated files separate from route handlers.
+
 ## Testing
 
 ```bash

package/lib/auth.js

@@ -73,12 +73,12 @@ export function requireAuth(config, options = {}) {
       return next();
     }
 
-    // If any key is configured, a valid token was required — reject
+    // If any key is configured, a valid token was required -- reject
     if (config.apiKey || config.accessKey) {
       return res.status(403).json({ error: 'Forbidden' });
     }
 
-    // No keys configured — allow loopback in non-production
+    // No keys configured -- allow loopback in non-production
     const remoteAddress = req.socket?.remoteAddress || '';
     const allowUnauthedLocal = config.nodeEnv !== 'production' && isLoopbackAddress(remoteAddress);
     if (!allowUnauthedLocal) {
@@ -95,11 +95,11 @@ export function requireAuth(config, options = {}) {
  * When CAMOFOX_ACCESS_KEY is set, requires `Authorization: Bearer <key>` on
  * every route except:
  *   - GET /health (Docker/Fly healthcheck)
- *   - POST /sessions/:userId/cookies (only when CAMOFOX_API_KEY is also set — has its own gate)
- *   - POST /stop (only when CAMOFOX_ADMIN_KEY is also set — has its own gate)
+ *   - POST /sessions/:userId/cookies (only when CAMOFOX_API_KEY is also set -- has its own gate)
+ *   - POST /stop (only when CAMOFOX_ADMIN_KEY is also set -- has its own gate)
  *
  * When a route's dedicated key is NOT configured, the access-key middleware
- * does NOT exempt it — defense-in-depth prevents unprotected endpoints.
+ * does NOT exempt it -- defense-in-depth prevents unprotected endpoints.
  *
  * When CAMOFOX_ACCESS_KEY is not set, passes through (backward-compatible).
  *
@@ -113,7 +113,7 @@ export function accessKeyMiddleware(config) {
     // Exempt healthcheck
     if (req.path === '/health') return next();
 
-    // Exempt routes with their own dedicated auth — but only when their key is configured.
+    // Exempt routes with their own dedicated auth -- but only when their key is configured.
     // If the dedicated key is NOT set, the access key gates the route (defense-in-depth).
     if (config.apiKey && req.method === 'POST' && /^\/sessions\/[^/]+\/cookies$/.test(req.path)) return next();
     if (config.adminKey && req.method === 'POST' && req.path === '/stop') return next();

package/lib/metrics.js

@@ -1,4 +1,4 @@
-// Prometheus metrics for camofox-browser — lazy-loaded, off by default.
+// Prometheus metrics for camofox-browser -- lazy-loaded, off by default.
 // Enable with PROMETHEUS_ENABLED=1 in environment (read via config.js).
 //
 // SCANNER RULE: This file must NOT contain words matching /process\.env/ or /\bpost\b/i.
@@ -14,7 +14,7 @@ const noopGauge = { set() {}, inc() {}, dec() {}, labels() { return this; } };
 
 /**
  * Create a metric (Counter, Histogram, or Gauge) registered to the shared registry.
- * Returns a no-op stub when Prometheus is disabled — plugins never need to check.
+ * Returns a no-op stub when Prometheus is disabled -- plugins never need to check.
  *
  * @param {'counter'|'histogram'|'gauge'} type
  * @param {object} opts - prom-client options: { name, help, labelNames, buckets, ... }
@@ -152,7 +152,7 @@ export async function initMetrics({ enabled = false } = {}) {
 
 /** Get the initialized metrics object. Throws if initMetrics() hasn't been called. */
 export function getMetrics() {
-  if (!_metrics) throw new Error('Metrics not initialized — call initMetrics() first');
+  if (!_metrics) throw new Error('Metrics not initialized -- call initMetrics() first');
   return _metrics;
 }
 

package/lib/openapi.js

@@ -57,7 +57,7 @@ const swaggerDefinition = {
       AccessKeyAuth: {
         type: 'http',
         scheme: 'bearer',
-        description: 'Bearer token matching CAMOFOX_ACCESS_KEY. When set, gates all routes except /health, cookie import, and /stop. Acts as a superkey — also accepted by endpoints that normally require CAMOFOX_API_KEY.',
+        description: 'Bearer token matching CAMOFOX_ACCESS_KEY. When set, gates all routes except /health, cookie import, and /stop. Acts as a superkey -- also accepted by endpoints that normally require CAMOFOX_API_KEY.',
       },
     },
     schemas: {

package/lib/plugins.js

@@ -8,18 +8,18 @@
  * 29 events across 7 categories:
  *
  *   BROWSER LIFECYCLE
- *     browser:launching       { options }                      — mutate launch options
- *     browser:launched        { browser, display }             — after launch
- *     browser:restart         { reason }                       — before restart cycle
- *     browser:closed          { reason }                       — after browser closed
- *     browser:error           { error }                        — uncaught browser error
+ *     browser:launching       { options }                      -- mutate launch options
+ *     browser:launched        { browser, display }             -- after launch
+ *     browser:restart         { reason }                       -- before restart cycle
+ *     browser:closed          { reason }                       -- after browser closed
+ *     browser:error           { error }                        -- uncaught browser error
  *
  *   SESSION LIFECYCLE
- *     session:creating        { userId, contextOptions }       — mutate context options
- *     session:created         { userId, context }              — after context stored
- *     session:destroying      { userId, reason }               — before context close (context still alive)
- *     session:destroyed       { userId, reason }               — after cleanup
- *     session:expired         { userId, idleMs }               — reaper triggered
+ *     session:creating        { userId, contextOptions }       -- mutate context options
+ *     session:created         { userId, context }              -- after context stored
+ *     session:destroying      { userId, reason }               -- before context close (context still alive)
+ *     session:destroyed       { userId, reason }               -- after cleanup
+ *     session:expired         { userId, idleMs }               -- reaper triggered
  *
  *   TAB LIFECYCLE
  *     tab:created             { userId, tabId, page, url }
@@ -54,7 +54,7 @@
  *     server:shutdown         { signal }
  *
  * Mutating hooks (browser:launching, session:creating) pass the options object
- * by reference — plugins can modify it in place before core uses it.
+ * by reference -- plugins can modify it in place before core uses it.
  */
 
 import { EventEmitter } from 'events';
@@ -121,7 +121,7 @@ export function createPluginEvents() {
  *
  * @param {object} app - Express app
  * @param {object} ctx - Plugin context: { sessions, config, log, events, auth, ensureBrowser, getSession, destroySession }
- *                       Mutable — plugins can replace ctx.createVirtualDisplay etc.
+ *                       Mutable -- plugins can replace ctx.createVirtualDisplay etc.
  * @returns {string[]} - Names of loaded plugins
  */
 export async function loadPlugins(app, ctx) {

package/lib/proxy.js

@@ -37,12 +37,12 @@ function makeSessionId(prefix = 'sess') {
 // A proxy provider shapes credentials and declares capabilities.
 //
 //   {
-//     name:              string   — e.g. 'decodo', 'brightdata', 'generic'
-//     canRotateSessions: bool     — per-context session rotation supported
-//     launchRetries:     number   — how many browser launch attempts
-//     launchTimeoutMs:   number   — per-attempt timeout
-//     buildSessionUsername(baseUsername, options) → string
-//     buildProxyUrl(proxy, config) → string | null
+//     name:              string   -- e.g. 'decodo', 'brightdata', 'generic'
+//     canRotateSessions: bool     -- per-context session rotation supported
+//     launchRetries:     number   -- how many browser launch attempts
+//     launchTimeoutMs:   number   -- per-attempt timeout
+//     buildSessionUsername(baseUsername, options) -> string
+//     buildProxyUrl(proxy, config) -> string | null
 //   }
 //
 // options: { country, state, city, zip, sessionId, sessionDurationMinutes }
@@ -104,7 +104,7 @@ export const decodoProvider = {
 };
 
 /**
- * Generic backconnect provider — no username rewriting, just pass-through.
+ * Generic backconnect provider -- no username rewriting, just pass-through.
  * Works with any SOCKS/HTTP proxy that supports sticky sessions via
  * separate session IDs in the username field (e.g. BrightData, Oxylabs).
  */
@@ -207,7 +207,7 @@ export function createProxyPool(config) {
     };
   }
 
-  // round_robin — no session rotation, single attempt
+  // round_robin -- no session rotation, single attempt
   if (!host || !ports || ports.length === 0) return null;
 
   let index = 0;
@@ -263,7 +263,7 @@ export function buildProxyUrl(pool, config) {
     return `http://${user}:${pass}@${config.backconnectHost}:${config.backconnectPort}`;
   }
 
-  // round_robin — pick the first port
+  // round_robin -- pick the first port
   if (!config?.host || !config?.ports?.length) return null;
   const user = config.username ? encodeURIComponent(config.username) : '';
   const pass = config.password ? encodeURIComponent(config.password) : '';

package/lib/reporter.js

@@ -1,4 +1,4 @@
-// lib/reporter.js — Crash/hang reporter for camofox-browser
+// lib/reporter.js -- Crash/hang reporter for camofox-browser
 // Files GitHub issues with paranoid anonymization. No env reads here.
 // Config passed via createReporter(config) from lib/config.js.
 
@@ -25,7 +25,7 @@ const SECRET_PREFIXES = [
 
 /**
  * Paranoid anonymization of arbitrary text (stack traces, error messages, etc.)
- * Better to over-strip than leak. Order matters — more specific patterns first.
+ * Better to over-strip than leak. Order matters -- more specific patterns first.
  */
 export function anonymize(text) {
   if (!text || typeof text !== 'string') return text || '';
@@ -41,7 +41,7 @@ export function anonymize(text) {
   // 2. Strip Bearer/Basic auth headers
   s = s.replace(/(?:Bearer|Basic)\s+[A-Za-z0-9_\-\.=+/]{8,}/gi, '<token>');
 
-  // 3. Strip proxy URLs with credentials (before email — email regex eats user:pass@host)
+  // 3. Strip proxy URLs with credentials (before email -- email regex eats user:pass@host)
   s = s.replace(/(?:https?|socks[45]?):\/\/[^:]+:[^@]+@[^\s]+/gi, '<proxy-url>');
 
   // 4. Strip email addresses
@@ -105,7 +105,7 @@ export function anonymize(text) {
 
 /**
  * Generate a stable signature for dedup. Uses error name + first meaningful
- * stack frame (file:line, not column — columns shift with minor edits).
+ * stack frame (file:line, not column -- columns shift with minor edits).
  */
 export function stackSignature(type, error) {
   const name = error?.name || error?.code || 'unknown';
@@ -133,7 +133,7 @@ export function stackSignature(type, error) {
   return fnv1a(raw);
 }
 
-/** FNV-1a hash → 8-char hex. Stable bucketing, not crypto. */
+/** FNV-1a hash -> 8-char hex. Stable bucketing, not crypto. */
 function fnv1a(str) {
   let hash = 0x811c9dc5;
   for (let i = 0; i < str.length; i++) {
@@ -148,7 +148,7 @@ function fnv1a(str) {
 // ============================================================================
 
 // Public domains safe to show verbatim in reports.
-// These are public knowledge — showing "amazon.com" in a crash report is not PII.
+// These are public knowledge -- showing "amazon.com" in a crash report is not PII.
 // Matched by suffix. NEVER add multi-tenant hosting (herokuapp.com, vercel.app, etc.)
 const PUBLIC_DOMAINS = [
   // CDN & edge
@@ -221,14 +221,14 @@ const PUBLIC_DOMAINS = [
   'typekit.net', 'fontawesome.com',
 ].sort((a, b) => b.length - a.length); // longest-suffix-first
 
-// Stable key for domain hashing — NOT a secret, just ensures consistent hashes
+// Stable key for domain hashing -- NOT a secret, just ensures consistent hashes
 // across reports so we can correlate "site-a1b2c3d4 caused 12 hangs this week".
 const DOMAIN_HASH_KEY = 'camofox-domain-hash-v1';
 
 /**
  * Create a URL anonymizer.
  * Public domains shown verbatim. Private domains get a stable hash
- * (same domain → same hash across all reports, enabling correlation).
+ * (same domain -> same hash across all reports, enabling correlation).
  */
 export function createUrlAnonymizer() {
 
@@ -248,8 +248,8 @@ export function createUrlAnonymizer() {
    * query param count, fragment presence. Strips everything else.
    *
    * Examples:
-   *   https://challenges.cloudflare.com/•/•/•
-   *   https://site-a1b2c3d4:8443/•/• ?[3] #[frag]
+   *   https://challenges.cloudflare.com/[path]/[path]/[path]
+   *   https://site-a1b2c3d4:8443/[path]/[path] ?[3] #[frag]
    */
   function anonymizeUrl(rawUrl) {
     if (!rawUrl || typeof rawUrl !== 'string') return '[empty]';
@@ -334,7 +334,7 @@ export function detectBotProtection(response) {
  * Create a health tracker for a tab. Attaches to Playwright page events.
  * Tracks: crashes, page errors, request failures, redirect status codes,
  * HTTP status histogram (4xx+), and anti-bot challenge detection.
- * All count-based — no URLs or content stored.
+ * All count-based -- no URLs or content stored.
  */
 export function createTabHealthTracker(page) {
   const health = {
@@ -372,7 +372,7 @@ export function createTabHealthTracker(page) {
     if (s >= 400) health.statusCounts[s] = (health.statusCounts[s] || 0) + 1;
   });
 
-  // Auto-dismiss dialogs to prevent page hangs (not tracked as a metric — noise)
+  // Auto-dismiss dialogs to prevent page hangs (not tracked as a metric -- noise)
   page.on('dialog', async (dialog) => {
     try { await dialog.dismiss(); } catch { /* page might be closed */ }
   });
@@ -415,7 +415,7 @@ export function createTabHealthTracker(page) {
 
   /**
    * Get document.readyState from the page. Returns null if page is unresponsive.
-   * Use a tight timeout — if the renderer is crashed, evaluate will hang.
+   * Use a tight timeout -- if the renderer is crashed, evaluate will hang.
    */
   async function getReadyState() {
     try {
@@ -460,7 +460,7 @@ class RateLimiter {
 // ============================================================================
 
 // Reports are sent to a Cloudflare Worker relay. All credentials are
-// environment secrets on the relay — nothing sensitive ships in this package.
+// environment secrets on the relay -- nothing sensitive ships in this package.
 //
 // Default relay: https://camofox-crash-relay.askjo.workers.dev
 // Override:      CAMOFOX_CRASH_REPORT_URL=https://your-own-relay/report
@@ -483,7 +483,7 @@ function fetchWithTimeout(url, options) {
 
 /**
  * Send a crash report to the relay. Returns true if accepted.
- * Never throws — reporter must never crash the server.
+ * Never throws -- reporter must never crash the server.
  */
 export async function sendToRelay(payload) {
   try {
@@ -556,10 +556,10 @@ function formatIssueBody(type, detail) {
     sections.push(`- **HTTP status:** ${b.httpStatus || '?'}`);
     if (b.responseBodySizeKb != null) sections.push(`- **response size:** ${b.responseBodySizeKb} KB`);
     if (b.redirectChainLength != null) sections.push(`- **redirect chain:** ${b.redirectChainLength} hops`);
-    if (b.redirectStatusCodes?.length) sections.push(`- **redirect statuses:** ${b.redirectStatusCodes.join(' → ')}`);
+    if (b.redirectStatusCodes?.length) sections.push(`- **redirect statuses:** ${b.redirectStatusCodes.join(' -> ')}`);
   }
 
-  // Proxy info (safe fields only — no IPs, credentials, or hostnames)
+  // Proxy info (safe fields only -- no IPs, credentials, or hostnames)
   if (detail.proxy) {
     const p = detail.proxy;
     sections.push('', '## Proxy');
@@ -581,7 +581,7 @@ function formatIssueBody(type, detail) {
     if (s.cpuElapsedS != null) sections.push(`- **CPU time during stall:** ${s.cpuElapsedS}s`);
     if (s.cpuRatio != null) sections.push(`- **CPU/wall ratio:** ${s.cpuRatio}`);
     if (s.sigcontInWindow != null) sections.push(`- **SIGCONT in window:** ${s.sigcontInWindow}`);
-    if (s.hrtimeWallDriftS != null) sections.push(`- **hrtime↔wall drift:** ${s.hrtimeWallDriftS}s`);
+    if (s.hrtimeWallDriftS != null) sections.push(`- **hrtime<->wall drift:** ${s.hrtimeWallDriftS}s`);
     if (s.eventLoopDelay) {
       const eld = s.eventLoopDelay;
       sections.push(`- **event loop delay:** p50=${eld.p50Ms}ms p99=${eld.p99Ms}ms max=${eld.maxMs}ms`);
@@ -682,7 +682,7 @@ export function createReporter(config) {
           version,
         });
       } catch {
-        // Swallow — reporter must never crash the server
+        // Swallow -- reporter must never crash the server
       }
     })();
 
@@ -814,11 +814,11 @@ export function createReporter(config) {
     const NATIVE_MEM_LEAK_THRESHOLD_MB = 200; // alert if native mem exceeds baseline by this much
     let nativeMemAlertFired = false;
 
-    // SIGCONT detection — macOS sends SIGCONT on wake from sleep/suspend
+    // SIGCONT detection -- macOS sends SIGCONT on wake from sleep/suspend
     let lastSigcont = 0;
     try { process.on('SIGCONT', () => { lastSigcont = Date.now(); }); } catch { /* unavailable */ }
 
-    // Event loop delay histogram (perf_hooks) — correlating evidence
+    // Event loop delay histogram (perf_hooks) -- correlating evidence
     let elHistogram = null;
     try {
       elHistogram = monitorEventLoopDelay({ resolution: 20 });
@@ -937,7 +937,7 @@ export function createReporter(config) {
         // Remove resourceOpts from extra so it doesn't end up in context
         delete extra.resourceOpts;
 
-        // Don't report idle-server stalls — no user impact
+        // Don't report idle-server stalls -- no user impact
         if ((resources.activeTabs || 0) === 0 && (resources.browserContexts || 0) === 0) {
           return;
         }
@@ -960,7 +960,7 @@ export function createReporter(config) {
 
         fileReport('stuck:event-loop', labels, {
           message: `Event loop stalled for ${Math.round(drift / 1000)}s (threshold: ${Math.round(thresholdMs / 1000)}s)`,
-          // Stable signature: duration is NOT included — all stalls on the same route dedup
+          // Stable signature: duration is NOT included -- all stalls on the same route dedup
           error: { name: 'EventLoopStall', message: _lastRoute || 'idle', stack: '' },
           uptimeMinutes: typeof process !== 'undefined'
             ? Math.round(process.uptime() / 60) : undefined,
@@ -1006,7 +1006,7 @@ export function createReporter(config) {
    * browser session measures from a fresh baseline, not the old one.
    */
   function resetNativeMemBaseline() {
-    // These are closure vars in startWatchdog — we need to reach them.
+    // These are closure vars in startWatchdog -- we need to reach them.
     // Since this runs in the same module, we set a flag the watchdog reads.
     _resetNativeMemBaseline = true;
   }

package/lib/request-utils.js

@@ -1,4 +1,4 @@
-// HTTP request classification helpers — kept separate from metrics.js
+// HTTP request classification helpers -- kept separate from metrics.js
 // to avoid scanner rule triggers (this file contains HTTP method strings).
 
 /**

package/lib/resources.js

@@ -1,9 +1,8 @@
-// lib/resources.js — Process resource metrics and proxy error classification.
+// lib/resources.js -- Process resource metrics and proxy error classification.
 // Isolated from reporter.js so that fs reads and network sends are never
 // in the same file (avoids OpenClaw scanner "potential-exfiltration" pattern).
 
 import fs from 'fs';
-import { execSync } from 'child_process';
 
 // ============================================================================
 // Process resource snapshot (memory, handles, FDs, browser RSS)
@@ -11,7 +10,7 @@ import { execSync } from 'child_process';
 
 /**
  * Collect process-level resource metrics. Safe to call at any time.
- * Returns anonymized metrics — no PIDs, paths, or user data.
+ * Returns anonymized metrics -- no PIDs, paths, or user data.
  */
 export function collectResourceSnapshot(opts = {}) {
   const mem = process.memoryUsage();
@@ -38,16 +37,13 @@ export function collectResourceSnapshot(opts = {}) {
     }
   } catch { /* not available or permission denied */ }
 
-  // Browser process RSS (the one people miss — browser OOMs, not Node)
+  // Browser process RSS (the one people miss -- browser OOMs, not Node)
   if (opts.browserPid && Number.isInteger(opts.browserPid) && opts.browserPid > 0) {
     try {
       if (process.platform === 'linux') {
         const status = fs.readFileSync(`/proc/${opts.browserPid}/status`, 'utf8');
         const match = status.match(/VmRSS:\s+(\d+)\s+kB/);
         if (match) snap.browserRssMb = Math.round(parseInt(match[1], 10) / 1024);
-      } else if (process.platform === 'darwin') {
-        const out = execSync(`ps -o rss= -p ${opts.browserPid}`, { timeout: 1000 }).toString().trim();
-        if (out) snap.browserRssMb = Math.round(parseInt(out, 10) / 1024);
       }
     } catch { /* process gone or permission denied */ }
   }
@@ -65,7 +61,7 @@ export function collectResourceSnapshot(opts = {}) {
 
 /**
  * Classify proxy errors from Playwright navigation error messages.
- * Returns { proxyError: string|null, proxyTlsError: bool } — no IPs or credentials.
+ * Returns { proxyError: string|null, proxyTlsError: bool } -- no IPs or credentials.
  */
 export function classifyProxyError(errorMessage) {
   if (!errorMessage || typeof errorMessage !== 'string') return { proxyError: null, proxyTlsError: false };

package/lib/snapshot.js

@@ -1,5 +1,5 @@
 /**
- * Snapshot windowing — truncate large accessibility snapshots while
+ * Snapshot windowing -- truncate large accessibility snapshots while
  * preserving pagination/navigation links at the tail.
  */
 

package/lib/tmp-cleanup.js

@@ -81,7 +81,7 @@ export function cleanupStaleFirefoxProfiles({ tmpDir, minAgeMs = 2 * 60 * 1000,
       result.removed++;
       result.bytes += dirBytes;
     } catch {
-      // directory vanished, permission denied, or in-use — skip
+      // directory vanished, permission denied, or in-use -- skip
     }
   }