@remcp/runtime 0.2.147 → 0.2.149

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.149 — 2026-10-14
+
+- Automatically snapshot raw, local-only Chromium session files on crashed ReMCP CDP profiles before browser auto-launch; preserve orphaned tabs and prior snapshots without leaking URLs.
+- Fail closed if session evidence cannot be backed up safely, and cap file sizes, total data and snapshot count.
+- Add seven unit tests and document restoration limitations. No new runtime operations or MCP schema changes.
+
+## 0.2.148 — 2026-10-14
+
+- Request Chromium-native `--restore-last-session` only when the dedicated ReMCP browser profile has a crashed exit marker and persisted tab session files.
+- Preserve intentional clean browser shutdown and first-run behavior; avoid following symlinked session directories or files.
+- Use atomic file-descriptor validation for local session metadata to avoid check-then-open file races (CodeQL TOCTOU).
+- Add cross-platform regression coverage for interrupted, clean, missing, malformed, new, and symlinked browser session profiles.
+- No new tools or MCP schema changes.
+
 ## 0.2.147 — 2026-10-14
 
 - Accelerated Chrome CDP tab discovery by validating existing page URLs with eight concurrent, bounded DNS/safety workers instead of sequential lookups.

package/README.md

@@ -64,6 +64,8 @@ discovery for new clients.
 
 For browser typing, `browser_text` is the visible DOM locator while `text` is the Unicode payload. `browser_action(action="scroll")` accepts page/element deltas or direction/wheel steps and scrolls the page or nearest scrollable ancestor; `scroll_into_view` remains the separate semantic reveal operation.
 
+When ReMCP auto-launches Chrome/Edge for local CDP, it uses a dedicated ReMCP browser profile. If that browser was interrupted (for example during an agent upgrade), and Chromium has saved tabs in that profile, the next launch requests Chromium's own last-session restoration instead of opening a new `about:blank` tab. A clean browser shutdown never triggers automatic reopening. This inspects only local session metadata, never reads or transmits tab URLs to ReMCP's relay. The browser itself controls which tabs can actually be recovered. On an interrupted profile, ReMCP now saves a private, local-only snapshot of `Session_*` and `Tabs_*` files before Chromium can rotate them on startup, even when only tab files remain. Recovery snapshots are adjacent to the dedicated browser profile in a `browser-cdp-recovery/` directory (owner-only on Unix); existing snapshots are never deleted automatically. Copy limits are 16 regular files, 32 MiB per file, 64 MiB per snapshot and 12 distinct snapshots. If evidence cannot be protected safely (for example due to symlinks, storage exhaustion or the snapshot limit), browser auto-launch fails rather than silently overwriting its only recoverable copy. No session URLs are parsed, returned through tools, or uploaded. You can review and manage those local snapshots yourself.
+
 For frontend QA, use semantic data to operate the page and rendered pixels to verify it: `browser_action(action="set_viewport")` sets an exact responsive-test viewport, `browser_wait` waits for the real application state, and `browser_snapshot(include_screenshot=true, selector=...)` recenters the component, returns its bounds, and attaches the real CDP-rendered viewport PNG. This intentionally treats screenshots as the visual oracle without making screenshot-driven coordinate guessing the primary control path.
 
 `set_config_value` remains deliberately narrow: it can change only `telemetryEnabled`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.147",
+  "version": "0.2.149",
   "description": "First-party ReMCP local device runtime: filesystem, terminal, computer-use, browser, diagnostics and document tools over MCP.",
   "type": "module",
   "license": "MIT",

package/src/extended/browser-session-backup.mjs

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import process from 'node:process';
+import { closeSync, fchmodSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+
+const MAX_FILE_BYTES = 32 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const MAX_FILES = 16;
+const MAX_SNAPSHOTS = 12;
+const NOFOLLOW = constants.O_NOFOLLOW || 0;
+const DIRECTORY = constants.O_DIRECTORY || 0;
+
+function ownedRegularFile(file, maxBytes) {
+  let fd;
+  try {
+    if (process.platform === 'win32' && lstatSync(file).isSymbolicLink()) return null;
+    fd = openSync(file, constants.O_RDONLY | NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size <= 0 || stat.size > maxBytes) return null;
+    return { size: stat.size, mtimeMs: stat.mtimeMs };
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function sessionMetadata(profile) {
+  const file = path.join(profile, 'Default', 'Preferences');
+  let fd;
+  try {
+    if (process.platform === 'win32' && lstatSync(file).isSymbolicLink()) return null;
+    fd = openSync(file, constants.O_RDONLY | NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > 4 * 1024 * 1024) return null;
+    return JSON.parse(readFileSync(fd, 'utf8'))?.profile?.exit_type || null;
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function safeDirectory(dir) {
+  try { mkdirSync(dir, { recursive: false, mode: 0o700 }); }
+  catch (error) { if (error?.code !== 'EEXIST') throw error; }
+  // Open first and validate the handle, not the path: an lstat-then-open
+  // check would leave a filesystem race at the recovery destination.
+  if (process.platform === 'win32' && lstatSync(dir).isSymbolicLink()) throw new Error('Unsafe recovery directory');
+  const fd = openSync(dir, constants.O_RDONLY | DIRECTORY | NOFOLLOW);
+  try {
+    if (!fstatSync(fd).isDirectory()) throw new Error('Unsafe recovery directory');
+    if (process.platform !== 'win32') fchmodSync(fd, 0o700);
+  } finally { closeSync(fd); }
+}
+
+function rawCopy(from, to, expected) {
+  let source;
+  let destination;
+  try {
+    source = openSync(from, constants.O_RDONLY | NOFOLLOW);
+    const before = fstatSync(source);
+    if (!before.isFile() || before.size !== expected.size || before.mtimeMs !== expected.mtimeMs) {
+      throw new Error('Browser session changed while preparing the snapshot');
+    }
+    destination = openSync(to, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | NOFOLLOW, 0o600);
+    const buffer = Buffer.alloc(128 * 1024);
+    let total = 0;
+    while (total < expected.size) {
+      const count = readSync(source, buffer, 0, Math.min(buffer.length, expected.size - total), null);
+      if (count === 0) throw new Error('Browser session was truncated during snapshot');
+      let written = 0;
+      while (written < count) {
+        const next = writeSync(destination, buffer, written, count - written);
+        if (!next) throw new Error('Could not finish session backup write');
+        written += next;
+      }
+      total += count;
+    }
+    const after = fstatSync(source);
+    if (after.size !== before.size || after.mtimeMs !== before.mtimeMs) {
+      throw new Error('Browser session changed during snapshot');
+    }
+    fsyncSync(destination);
+  } finally {
+    if (source !== undefined) closeSync(source);
+    if (destination !== undefined) closeSync(destination);
+  }
+}
+
+// Called only before auto-launch of a *crashed* dedicated ReMCP CDP profile.
+// The source data stays on the user's computer; no tab URLs are parsed or sent
+// across the MCP connection. Never delete prior snapshots automatically.
+export function preserveInterruptedBrowserSession(profile) {
+  if (sessionMetadata(profile) !== 'Crashed') return { saved: false, reason: 'clean-or-missing' };
+  const sessionDir = path.join(profile, 'Default', 'Sessions');
+  let dirFd;
+  try {
+    if (process.platform !== 'win32') {
+      try { dirFd = openSync(sessionDir, constants.O_RDONLY | DIRECTORY | NOFOLLOW); }
+      catch (error) { if (error?.code === 'ENOENT') return { saved: false, reason: 'no-sessions' }; throw error; }
+      if (!fstatSync(dirFd).isDirectory()) throw new Error('Session directory is unsafe');
+    }
+    const readableDir = dirFd === undefined ? sessionDir : `${process.platform === 'darwin' ? '/dev/fd' : '/proc/self/fd'}/${dirFd}`;
+    const files = [];
+    let total = 0;
+    for (const name of readdirSync(readableDir).sort()) {
+      if (!/^(?:Session|Tabs)_\d+$/.test(name)) continue;
+      const details = ownedRegularFile(path.join(readableDir, name), MAX_FILE_BYTES);
+      if (!details) throw new Error('Session file is unsafe, empty or oversized');
+      total += details.size;
+      files.push({ name, ...details });
+      if (files.length > MAX_FILES || total > MAX_TOTAL_BYTES) throw new Error('Session data exceeds safe snapshot limits');
+    }
+    if (!files.some(file => file.name.startsWith('Tabs_'))) return { saved: false, reason: 'no-tabs' };
+
+    const recoveryDir = path.join(path.dirname(profile), `${path.basename(profile)}-recovery`);
+    safeDirectory(recoveryDir);
+    const fingerprint = JSON.stringify(files);
+    const snapshots = readdirSync(recoveryDir).filter(name => /^snapshot-[A-Za-z0-9]+$/.test(name));
+    for (const name of snapshots) {
+      const manifest = path.join(recoveryDir, name, 'manifest.json');
+      try {
+        const fd = openSync(manifest, constants.O_RDONLY | NOFOLLOW);
+        let content;
+        try { if (fstatSync(fd).size > 8192) continue; content = JSON.parse(readFileSync(fd, 'utf8')); }
+        finally { closeSync(fd); }
+        if (content?.fingerprint === fingerprint) return { saved: false, reason: 'already-saved' };
+      } catch { /* Ignore incomplete previous attempts; never overwrite them. */ }
+    }
+    if (snapshots.length >= MAX_SNAPSHOTS) throw new Error('Session recovery snapshot limit reached');
+    const snapshotDir = mkdtempSync(path.join(recoveryDir, 'snapshot-'));
+    try {
+      for (const file of files) rawCopy(path.join(readableDir, file.name), path.join(snapshotDir, file.name), file);
+      writeFileSync(path.join(snapshotDir, 'manifest.json'), JSON.stringify({ fingerprint, count: files.length, hasWindowSession: files.some(f => f.name.startsWith('Session_')) }), { flag: 'wx', mode: 0o600 });
+      return { saved: true, reason: 'saved', count: files.length, bytes: total };
+    } catch (error) {
+      rmSync(snapshotDir, { recursive: true, force: true });
+      throw error;
+    }
+  } finally { if (dirFd !== undefined) closeSync(dirFd); }
+}

package/src/extended/browser.mjs

@@ -3,8 +3,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { isIP } from 'node:net';
 import { lookup } from 'node:dns/promises';
-import { existsSync, mkdirSync } from 'node:fs';
+import { closeSync, constants as fsConstants, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readdirSync } from 'node:fs';
 import { resolveSafePath } from '../util.mjs';
+import { preserveInterruptedBrowserSession } from './browser-session-backup.mjs';
 import { clamp, commandExists, jsonResult, optionalString, requireEnum, spawnDetached, unavailable } from './common.mjs';
 
 const DEFAULT_ENDPOINT = 'http://127.0.0.1:9222';
@@ -60,6 +61,75 @@ function browserDataDir() {
   return path.join(process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'), 'remcp', 'browser-cdp');
 }
 
+// Browser sessions belong to the local user, not to the lifetime of the ReMCP
+// agent. The agent can be restarted by an npm update while Chrome is open.
+// If Chrome was interrupted and already persisted tabs, ask Chromium itself to
+// restore the session. Never parse, persist, or relay the sensitive tab URLs.
+// A clean user-initiated quit must not resurrect a deliberately closed session.
+export function shouldRestoreBrowserSession(profile) {
+  let prefsFd;
+  let sessionFd;
+  try {
+    const defaultProfile = path.join(profile, 'Default');
+    // Open first, then validate the file descriptor: checking the path with
+    // lstat before reading it creates a symlink-swap TOCTOU vulnerability.
+    prefsFd = openSync(path.join(defaultProfile, 'Preferences'),
+      fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
+    const prefsStat = fstatSync(prefsFd);
+    if (!prefsStat.isFile() || prefsStat.size > 4 * 1024 * 1024) return false;
+    const prefs = JSON.parse(readFileSync(prefsFd, 'utf8'));
+    if (prefs?.profile?.exit_type !== 'Crashed') return false;
+
+    const sessionDir = path.join(defaultProfile, 'Sessions');
+    let readableDir = sessionDir;
+    if (process.platform !== 'win32') {
+      // Use the opened directory even if another process renames the path.
+      // O_NOFOLLOW refuses a linked Sessions directory on Unix platforms.
+      sessionFd = openSync(sessionDir,
+        fsConstants.O_RDONLY | (fsConstants.O_DIRECTORY || 0) | (fsConstants.O_NOFOLLOW || 0));
+      if (!fstatSync(sessionFd).isDirectory()) return false;
+      readableDir = `${process.platform === 'darwin' ? '/dev/fd' : '/proc/self/fd'}/${sessionFd}`;
+    }
+    return readdirSync(readableDir).some(name => {
+      if (!/^Tabs_\d+$/.test(name)) return false;
+      let tabFd;
+      try {
+        tabFd = openSync(path.join(readableDir, name),
+          fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0));
+        const stat = fstatSync(tabFd);
+        return stat.isFile() && stat.size > 0;
+      } catch { return false; }
+      finally { if (tabFd !== undefined) closeSync(tabFd); }
+    });
+  } catch {
+    // A new, malformed or inaccessible profile must start fresh, not fail CDP.
+    return false;
+  } finally {
+    if (sessionFd !== undefined) closeSync(sessionFd);
+    if (prefsFd !== undefined) closeSync(prefsFd);
+  }
+}
+
+export function browserAutoLaunchArgs(profile, {
+  platform = process.platform,
+  display = process.env.DISPLAY,
+  waylandDisplay = process.env.WAYLAND_DISPLAY,
+} = {}) {
+  const restore = shouldRestoreBrowserSession(profile);
+  const args = [
+    '--remote-debugging-address=127.0.0.1',
+    '--remote-debugging-port=9222',
+    `--user-data-dir=${profile}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    // --restore-last-session only for an interrupted, persisted local profile.
+    // An explicit about:blank startup URL would suppress the normal restore.
+    ...(restore ? ['--restore-last-session'] : ['about:blank']),
+  ];
+  if (platform === 'linux' && !display && !waylandDisplay) args.unshift('--headless=new');
+  return args;
+}
+
 async function waitForBrowserEndpoint(timeoutMs = 5000) {
   const deadline = Date.now() + timeoutMs;
   do {
@@ -79,16 +149,10 @@ async function ensureBrowserEndpoint(endpoint) {
       if (!executable) throw new Error('Browser control is unavailable: no supported Chrome, Edge, or Chromium executable was found');
       const profile = browserDataDir();
       mkdirSync(profile, { recursive:true, mode:0o700 });
-      const args = [
-        '--remote-debugging-address=127.0.0.1',
-        '--remote-debugging-port=9222',
-        `--user-data-dir=${profile}`,
-        '--no-first-run',
-        '--no-default-browser-check',
-        'about:blank',
-      ];
-      if (process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) args.unshift('--headless=new');
-      spawnDetached(executable, args);
+      // Chrome rotates its Sessions/ files on startup. Protect existing local
+      // evidence before a restart, including profiles with only Tabs_* left.
+      preserveInterruptedBrowserSession(profile);
+      spawnDetached(executable, browserAutoLaunchArgs(profile));
       if (!await waitForBrowserEndpoint(5000)) throw new Error('ReMCP launched a browser but its local CDP endpoint did not become ready');
     })().finally(() => { browserLaunchPromise = null; });
   }