devtools-fleet-mcp 0.1.0

package/src/lib/lock.js

@@ -0,0 +1,54 @@
+import { mkdirSync, rmSync, writeFileSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { PATHS } from './config.js';
+import { ensurePrivateDir, isPidAlive, sleep } from './fs-utils.js';
+
+const STALE_MS = 30_000;
+
+/**
+ * Run fn while holding a cross-process lock. mkdir is atomic on every
+ * filesystem we care about, so the lock is a directory. A lock whose holder
+ * died, or that is older than STALE_MS, is taken over.
+ */
+export async function withLock(name, fn, { timeoutMs = 20_000 } = {}) {
+  ensurePrivateDir(PATHS.locks);
+  const dir = join(PATHS.locks, `${name}.lock`);
+  const deadline = Date.now() + timeoutMs;
+  let delay = 10;
+  for (;;) {
+    try {
+      mkdirSync(dir);
+      writeFileSync(join(dir, 'owner'), String(process.pid));
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      if (isStale(dir)) {
+        rmSync(dir, { recursive: true, force: true });
+        continue;
+      }
+      if (Date.now() > deadline) throw new Error(`Timed out waiting for lock "${name}" (${dir})`, { cause: err });
+      await sleep(delay + Math.random() * delay);
+      delay = Math.min(delay * 2, 200);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function isStale(dir) {
+  try {
+    const owner = Number(readFileSync(join(dir, 'owner'), 'utf8'));
+    if (owner && !isPidAlive(owner)) return true;
+    return Date.now() - statSync(dir).mtimeMs > STALE_MS;
+  } catch {
+    // Owner file not written yet: the holder is mid-acquire. Only stale if old.
+    try {
+      return Date.now() - statSync(dir).mtimeMs > STALE_MS;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/lib/lockdown.js

@@ -0,0 +1,38 @@
+// Strict mode's network lock, enforced by Chrome itself rather than over CDP.
+//
+// A strict browser gets a proxy that goes nowhere (port 0 can't be connected
+// to), with the allowed origins on the bypass list. Anything else fails in
+// Chrome's network stack: fetch, XHR, beacons, workers, WebSockets, QUIC. It
+// holds with no CDP client attached, so a detached browser stays locked, and
+// hostnames outside the list are never even resolved (the proxy would do that).
+//
+// Findings that shaped the flags (Chrome 154, see test/integration):
+// - <-loopback> must come first, or it overrides the rules before it.
+// - Rules are host:port without a scheme: "http://host:port" doesn't match
+//   ws:// to the same origin. So at this layer http and https on one port are
+//   the same; the CDP guard still tells them apart for navigations.
+// - --webrtc-ip-handling-policy stops non-proxied UDP; the "force-" variant
+//   of the flag does nothing.
+
+const DEFAULT_PORTS = { 'http:': '80', 'https:': '443' };
+
+function bypassRule(pattern) {
+  const wildcard = /^(https?:)\/\/\*\.(.+)$/.exec(pattern);
+  if (wildcard) {
+    const url = new URL(`${wildcard[1]}//${wildcard[2]}`);
+    return `*.${url.hostname}:${url.port || DEFAULT_PORTS[url.protocol]}`;
+  }
+  const url = new URL(pattern);
+  return `${url.hostname}:${url.port || DEFAULT_PORTS[url.protocol]}`;
+}
+
+/** Chrome flags that confine all network traffic to the allowlist. */
+export function lockdownArgs(allowlist) {
+  const rules = [...new Set(allowlist.map(bypassRule))];
+  return [
+    '--proxy-server=http://127.0.0.1:0',
+    `--proxy-bypass-list=<-loopback>;${rules.join(';')}`,
+    '--webrtc-ip-handling-policy=disable_non_proxied_udp',
+    '--dns-prefetch-disable',
+  ];
+}

package/src/lib/login.js

@@ -0,0 +1,177 @@
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { PATHS } from './config.js';
+import { CdpConnection } from './cdp.js';
+import { launchChrome, closeChrome, browserWsUrl, resolveChromePath } from './chrome.js';
+import { newBrowserId, writeEntry, updateEntry, removeEntry } from './registry.js';
+import { ensureReaper } from './reaper.js';
+import { captureStorage, toPlaywrightCookie, openOrigins, PLACEHOLDER_PATH } from './storage.js';
+import { writeState, stateExists, assertStateName } from './states.js';
+import { normalizeOriginPatterns, checkUrl, cookieMatchesAllowlist } from './origins.js';
+
+// `devtools-fleet login <name> <url>`: a person logs in by hand in a visible
+// window (2FA, SSO, captchas all fine), fleet records every origin they pass
+// through, and saves cookies + localStorage as a state.
+
+const COOKIE_POLL_MS = 3000;
+
+export async function login({ name, url, allow = [], strict = false, overwrite = false, yes = false, headless = false, config, io = defaultIo() }) {
+  assertStateName(name);
+  if (stateExists(name) && !overwrite) throw new Error(`State "${name}" already exists. Use --overwrite to replace it.`);
+  const start = new URL(url);
+  if (!['http:', 'https:'].includes(start.protocol)) throw new Error('The login URL must be http(s)');
+  const extraAllow = normalizeOriginPatterns(allow);
+
+  const id = newBrowserId();
+  const entry = {
+    id,
+    kind: 'login',
+    chromePid: null,
+    port: null,
+    wsPath: null,
+    profileDir: join(PATHS.profiles, id),
+    headless,
+    viewport: null,
+    channel: config.channel,
+    // The CLI is both driver and owner: if it dies, the reaper closes the window.
+    fleetPid: process.pid,
+    anchorPid: process.pid,
+    anchorLabel: 'devtools-fleet login',
+    cwd: process.cwd(),
+    state: name,
+    allowedOrigins: null,
+    strict,
+    createdAt: Date.now(),
+    lastSeen: Date.now(),
+  };
+  writeEntry(entry);
+  ensureReaper();
+
+  let cdp = null;
+  let current = entry;
+  let browserGone = false;
+  let lastCookies = null;
+  try {
+    const chrome = await launchChrome({
+      executablePath: resolveChromePath({ chromePath: config.chromePath, channel: config.channel }),
+      profileDir: entry.profileDir,
+      onSpawn: (pid) => { current = updateEntry(id, { chromePid: pid }) ?? current; },
+      headless,
+      viewport: null,
+      extraArgs: config.chromeArgs,
+      url,
+      timeoutMs: config.launchTimeoutSeconds * 1000,
+    });
+    current = updateEntry(id, { chromePid: chrome.pid, port: chrome.port, wsPath: chrome.wsPath });
+    cdp = await CdpConnection.connect(browserWsUrl(chrome));
+    cdp.on('__close', () => { browserGone = true; });
+
+    // Every top-level origin the person passes through (login page, SSO provider, the app).
+    const visited = [start.origin];
+    const note = (targetInfo) => {
+      if (targetInfo.type !== 'page') return;
+      try {
+        const u = new URL(targetInfo.url);
+        if ((u.protocol === 'http:' || u.protocol === 'https:') && u.pathname !== PLACEHOLDER_PATH && !visited.includes(u.origin)) {
+          visited.push(u.origin);
+        }
+      } catch {
+        // about:blank etc.
+      }
+    };
+    cdp.on('Target.targetCreated', ({ targetInfo }) => note(targetInfo));
+    cdp.on('Target.targetInfoChanged', ({ targetInfo }) => note(targetInfo));
+    await cdp.send('Target.setDiscoverTargets', { discover: true });
+
+    // Closing the last window quits Chrome on Linux and Windows; keep a recent
+    // cookie snapshot so that still saves something.
+    const poll = setInterval(async () => {
+      try {
+        lastCookies = (await cdp.send('Storage.getCookies')).cookies;
+      } catch {
+        // browser going away
+      }
+    }, COOKIE_POLL_MS);
+    poll.unref();
+
+    io.print(`\nA Chrome window is open at ${url}.`);
+    io.print('Log in there (2FA and SSO are fine). When you are done, come back here and press Enter. Ctrl+C cancels.\n');
+    await io.waitForEnter(() => browserGone);
+    clearInterval(poll);
+
+    // Default: where the login started and where it ended up (tabs still open),
+    // plus --allow. Origins only passed through (an SSO provider, usually) are
+    // left out: saving their cookies would hand agents the whole SSO session.
+    const landed = browserGone ? [] : await openOrigins(cdp).catch(() => []);
+    const proposed = normalizeOriginPatterns([start.origin, ...landed, ...extraAllow]);
+    const passedThrough = visited.filter((o) => !checkUrl(proposed, o).allowed);
+    let allowedOrigins = proposed;
+    io.print(`\nThis state will only be usable on:\n${proposed.map((o) => `  ${o}`).join('\n')}`);
+    if (passedThrough.length) {
+      io.print(`Also visited during login, not included (add with --allow, or type your own list below):\n${passedThrough.map((o) => `  ${o}`).join('\n')}`);
+    }
+    if (!yes) {
+      const answer = (await io.ask('Save with these allowed origins? [Y/n, or type a comma-separated list instead] ')).trim();
+      if (/^n(o)?$/i.test(answer)) throw new Error('Cancelled; nothing saved.');
+      if (answer && !/^y(es)?$/i.test(answer)) {
+        allowedOrigins = normalizeOriginPatterns(answer.split(',').map((s) => s.trim()).filter(Boolean));
+      }
+    }
+
+    let snapshot;
+    if (!browserGone) {
+      const storageOrigins = [...new Set([
+        ...allowedOrigins.filter((p) => !p.includes('*')),
+        ...visited.filter((o) => checkUrl(allowedOrigins, o).allowed),
+      ])];
+      snapshot = await captureStorage(cdp, { cookieAllowlist: allowedOrigins, storageOrigins });
+    } else {
+      if (!lastCookies) throw new Error('The browser closed before anything could be saved. Run login again and press Enter before closing the window.');
+      io.print('The browser was closed, so localStorage could not be read. Saving cookies only.');
+      snapshot = storageFromCookies(lastCookies, allowedOrigins);
+    }
+
+    const summary = writeState({ name, cookies: snapshot.cookies, origins: snapshot.origins, allowedOrigins, strict, createdBy: 'cli' });
+    io.print(`\nSaved state "${summary.name}": ${summary.cookies} cookie(s), localStorage for ${summary.localStorageOrigins.length} origin(s)${summary.strict ? ', strict' : ''}.`);
+    if (summary.cookies === 0) io.print('Warning: no cookies were saved for these origins. Did the login finish?');
+    io.print(`Agents can now call browser_start({ state: "${summary.name}" }).`);
+    return summary;
+  } finally {
+    await closeChrome(current, { cdp }).catch(() => {});
+    cdp?.close();
+    removeEntry(id);
+    rmSync(entry.profileDir, { recursive: true, force: true });
+  }
+}
+
+function storageFromCookies(cookies, allowedOrigins) {
+  return {
+    cookies: cookies.filter((c) => cookieMatchesAllowlist(c.domain, allowedOrigins)).map(toPlaywrightCookie),
+    origins: [],
+  };
+}
+
+function defaultIo() {
+  const rl = () => createInterface({ input: process.stdin, output: process.stdout });
+  return {
+    print: (line) => console.log(line),
+    ask: (question) => new Promise((resolve) => {
+      const r = rl();
+      r.question(question, (answer) => { r.close(); resolve(answer); });
+    }),
+    waitForEnter: (isGone) => new Promise((resolve) => {
+      const r = rl();
+      const timer = setInterval(() => {
+        if (isGone()) {
+          console.log('\nThe browser window was closed.');
+          clearInterval(timer);
+          r.close();
+          resolve();
+        }
+      }, 500);
+      r.once('line', () => { clearInterval(timer); r.close(); resolve(); });
+    }),
+  };
+}
+

package/src/lib/origins.js

@@ -0,0 +1,104 @@
+// Origin patterns for allowlists.
+//
+//   https://app.example.com      exact origin (scheme + host + port)
+//   http://127.0.0.1:3000        ports matter
+//   https://*.example.com        any subdomain of example.com (not example.com itself)
+//
+// No paths, no bare hosts: an allowlist entry is always a full origin, so
+// "http vs https" and "which port" are never ambiguous.
+
+// Never blocked: internal and inline pages that can't reach the network.
+const ALWAYS_ALLOWED_SCHEMES = new Set(['about:', 'data:', 'blob:', 'chrome-error:', 'devtools:', 'javascript:']);
+
+export function normalizeOriginPattern(input) {
+  const raw = String(input).trim();
+  const wildcard = /^(https?):\/\/\*\.(.+)$/i.exec(raw);
+  if (wildcard) {
+    const url = parseUrl(`${wildcard[1]}://${wildcard[2]}`, input);
+    assertBareOrigin(url, input);
+    if (url.hostname.split('.').length < 2) throw new Error(`Wildcard too broad: "${input}"`);
+    return `${url.protocol}//*.${url.host}`;
+  }
+  const url = parseUrl(raw, input);
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error(`Origin must be http(s): "${input}"`);
+  assertBareOrigin(url, input);
+  return url.origin;
+}
+
+export function normalizeOriginPatterns(list) {
+  return [...new Set(list.map(normalizeOriginPattern))];
+}
+
+function parseUrl(value, original) {
+  try {
+    return new URL(value);
+  } catch {
+    throw new Error(`Not an origin: "${original}" (expected e.g. https://app.example.com)`);
+  }
+}
+
+function assertBareOrigin(url, original) {
+  if ((url.pathname && url.pathname !== '/') || url.search || url.hash || url.username || url.password) {
+    throw new Error(`Origin must not have a path, query or credentials: "${original}"`);
+  }
+}
+
+/** Does one pattern cover this origin ("https://a.example.com")? */
+export function patternMatchesOrigin(pattern, origin) {
+  if (!pattern.includes('*')) return pattern === origin;
+  const { scheme, host } = splitWildcard(pattern);
+  let url;
+  try {
+    url = new URL(origin);
+  } catch {
+    return false;
+  }
+  return url.protocol === scheme && url.host.endsWith(`.${host}`);
+}
+
+function splitWildcard(pattern) {
+  const [scheme, rest] = pattern.split('//*.');
+  return { scheme, host: rest };
+}
+
+/** @returns {{ allowed: boolean, origin?: string }} */
+export function checkUrl(allowlist, url) {
+  if (!allowlist) return { allowed: true };
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { allowed: false, origin: String(url) };
+  }
+  if (ALWAYS_ALLOWED_SCHEMES.has(parsed.protocol)) return { allowed: true };
+  if (!['http:', 'https:', 'ws:', 'wss:'].includes(parsed.protocol)) return { allowed: false, origin: parsed.protocol };
+  // WebSockets follow the page's http(s) origin rules.
+  const origin = parsed.origin.replace(/^ws(s?):/, 'http$1:');
+  return { allowed: allowlist.some((p) => patternMatchesOrigin(p, origin)), origin };
+}
+
+/** Is every pattern in `narrower` covered by `wider`? (used so agents can't widen an allowlist) */
+export function isSubset(narrower, wider) {
+  return narrower.every((p) => {
+    if (!p.includes('*')) return wider.some((w) => patternMatchesOrigin(w, p));
+    // A wildcard is only covered by an equal or broader wildcard.
+    const { scheme, host } = splitWildcard(p);
+    return wider.some((w) => {
+      if (!w.includes('*')) return false;
+      const ww = splitWildcard(w);
+      return ww.scheme === scheme && (host === ww.host || host.endsWith(`.${ww.host}`));
+    });
+  });
+}
+
+/** Does a cookie's domain belong to an allowlist? Cookies are only kept (and restored) if so. */
+export function cookieMatchesAllowlist(cookieDomain, allowlist) {
+  const domain = cookieDomain.replace(/^\./, '').toLowerCase();
+  return allowlist.some((pattern) => {
+    const host = pattern.includes('*')
+      ? splitWildcard(pattern).host.split(':')[0]
+      : new URL(pattern).hostname;
+    // Cookie set for a parent domain (example.com) is sent to app.example.com; one set for the host itself too.
+    return host === domain || host.endsWith(`.${domain}`) || (pattern.includes('*') && domain.endsWith(`.${host}`));
+  });
+}

package/src/lib/policy.js

@@ -0,0 +1,82 @@
+import { realpathSync } from 'node:fs';
+import { dirname, resolve, sep, basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PATHS } from './config.js';
+import { checkUrl } from './origins.js';
+
+// Checks on arguments an agent passes to chrome-devtools-mcp's tools, before
+// fleet forwards the call. The in-browser guard (guard.js) is the second
+// layer for navigations; these catch what it can't see.
+
+const NAVIGATION_TOOLS = new Set(['new_page', 'navigate_page']);
+const OK_SCHEMES = new Set(['about:', 'data:', 'blob:']);
+
+/** @returns {string|null} a reason to refuse the call, or null */
+export function checkToolCall(name, args, { allowlist, stateName = null }) {
+  if (NAVIGATION_TOOLS.has(name) && typeof args.url === 'string') {
+    const reason = checkNavigation(args.url, allowlist, stateName);
+    if (reason) return reason;
+  }
+  // A page in a separate browser context isn't covered by the guard's
+  // auto-attach, so with an allowlist there are no extra contexts.
+  if (name === 'new_page' && args.isolatedContext !== undefined && allowlist) {
+    return 'isolatedContext is not available in a browser with an allowlist. Open the page in the normal context.';
+  }
+  for (const [key, value] of Object.entries(args)) {
+    if (!/path/i.test(key)) continue;
+    for (const p of Array.isArray(value) ? value : [value]) {
+      if (typeof p === 'string' && isInsideFleetHome(p)) {
+        return `${key} points inside ${PATHS.home}, which holds saved logins and browser profiles. Use another location.`;
+      }
+    }
+  }
+  return null;
+}
+
+function checkNavigation(url, allowlist, stateName) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return `Not a valid URL: ${url}`;
+  }
+  if (['http:', 'https:'].includes(parsed.protocol)) {
+    const { allowed, origin } = checkUrl(allowlist, url);
+    const whose = stateName ? `this browser's allowlist (state "${stateName}")` : "this browser's allowlist";
+    return allowed ? null : `${url} is blocked. ${origin} is not in ${whose}: ${allowlist.join(', ')}.`;
+  }
+  if (OK_SCHEMES.has(parsed.protocol)) return null;
+  if (parsed.protocol === 'file:') {
+    if (allowlist) return `file: URLs are not available in a browser with an allowlist.`;
+    let path;
+    try {
+      path = fileURLToPath(parsed);
+    } catch {
+      return `Not a valid file URL: ${url}`;
+    }
+    return isInsideFleetHome(path) ? `${url} is inside ${PATHS.home}, which holds saved logins and browser profiles.` : null;
+  }
+  return `${parsed.protocol} URLs can't be opened through devtools-fleet.`;
+}
+
+/** Resolve symlinks as far as the path exists, so a link into the fleet home doesn't slip past. */
+function canonical(path) {
+  let current = resolve(path);
+  const rest = [];
+  for (;;) {
+    try {
+      return join(realpathSync(current), ...rest.reverse());
+    } catch {
+      const parent = dirname(current);
+      if (parent === current) return resolve(path);
+      rest.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
+export function isInsideFleetHome(path) {
+  const home = canonical(PATHS.home);
+  const target = canonical(path);
+  return target === home || target.startsWith(home + sep);
+}

package/src/lib/process-tree.js

@@ -0,0 +1,109 @@
+import { execFileSync } from 'node:child_process';
+import { readlinkSync } from 'node:fs';
+import { basename } from 'node:path';
+import { isPidAlive } from './fs-utils.js';
+
+// Which AI client session owns this fleet process?
+//
+// MCP clients start servers through wrappers (npx → npm exec → node, sometimes
+// a shell), and restart the whole chain on reconnect. The session itself (the
+// `claude` process, Cursor's extension host, ...) survives the reconnect. So
+// the anchor is the nearest ancestor that isn't a wrapper. A reconnect inside
+// the same session finds the same anchor and re-adopts its browser; a second
+// session in the same directory finds a different one and never shares.
+//
+// The anchor's start time is stored with its pid, so a recycled pid is never
+// mistaken for the session.
+//
+// DEVTOOLS_FLEET_SESSION overrides the lookup (a stable label of your choice).
+// On Windows there is no ps; the anchor falls back to this process, which
+// means no re-adoption but everything else works.
+
+const SHELLS_AND_LAUNCHERS = new Set([
+  'npm', 'npx', 'pnpm', 'pnpx', 'yarn', 'bunx', 'sh', 'bash', 'zsh', 'dash', 'fish', 'ksh', 'env', 'uv', 'uvx',
+  'devtools-fleet-mcp',
+]);
+// A runtime (node, bun, deno) is only a wrapper when it's running a launcher
+// or this package. A client written in Node (`node .../claude/cli.js`, an
+// Agent SDK orchestrator) is a session, not a wrapper.
+const RUNTIMES = new Set(['node', 'nodejs', 'bun', 'deno']);
+const LAUNCHER_ARGS = /\b(npx|npm|pnpm|pnpx|yarn|bunx|npx-cli|npm-cli)\b|devtools-fleet|\/_npx\//;
+
+export function isWrapper(comm, args = '') {
+  const exe = basename(comm).replace(/^-/, '').toLowerCase();
+  const first = basename(args.trim().split(/\s+/)[0] || '').replace(/^-/, '').toLowerCase();
+  if (SHELLS_AND_LAUNCHERS.has(exe) || SHELLS_AND_LAUNCHERS.has(first)) return true;
+  // npm rewrites its process title ("npm exec foo").
+  if (/^npm (exec|run|x)\b/.test(args)) return true;
+  if (RUNTIMES.has(exe) || RUNTIMES.has(first)) return LAUNCHER_ARGS.test(args);
+  return false;
+}
+
+function ps(pid, field) {
+  return execFileSync('ps', ['-o', `${field}=`, '-p', String(pid)], { encoding: 'utf8', timeout: 2000 }).trim();
+}
+
+export function readProcess(pid) {
+  try {
+    // One field per call: with several, ps prints a header unless every field has "=".
+    const ppid = Number(ps(pid, 'ppid'));
+    const comm = linuxExe(pid) || ps(pid, 'comm');
+    if (!Number.isInteger(ppid) || !comm) return null;
+    return { ppid, comm, args: ps(pid, 'args') };
+  } catch {
+    return null;
+  }
+}
+
+// On Linux, ps's comm is the main thread's name, and Node 24 renames its main
+// thread to "MainThread". The executable is the reliable name there.
+function linuxExe(pid) {
+  if (process.platform !== 'linux') return null;
+  try {
+    return basename(readlinkSync(`/proc/${pid}/exe`).replace(/ \(deleted\)$/, ''));
+  } catch {
+    return null;
+  }
+}
+
+/** Process start time as ps reports it; stable for the life of the process. */
+export function processStartTime(pid) {
+  if (process.platform === 'win32' || !pid) return null;
+  try {
+    return ps(pid, 'lstart') || null;
+  } catch {
+    return null;
+  }
+}
+
+/** @returns {{ pid: number, start: string|null, label: string }} */
+export function findSessionAnchor({ readProc = readProcess, startTime = processStartTime, startPid = process.ppid } = {}) {
+  const override = process.env.DEVTOOLS_FLEET_SESSION;
+  if (override) return { pid: 0, start: null, label: `session:${override}` };
+  if (process.platform === 'win32') return { pid: process.pid, start: null, label: 'self' };
+
+  let pid = startPid;
+  for (let depth = 0; depth < 12 && pid > 1; depth++) {
+    const proc = readProc(pid);
+    if (!proc) break;
+    if (!isWrapper(proc.comm, proc.args)) return { pid, start: startTime(pid), label: basename(proc.comm) };
+    pid = proc.ppid;
+  }
+  // Only wrappers all the way up (or ps failed): treat our parent as the anchor.
+  return { pid: startPid, start: startTime(startPid), label: 'parent' };
+}
+
+/** Is the session a registry entry belongs to still running? */
+export function anchorAlive(entry) {
+  if (entry.anchorPid === 0) return true; // label-based: no process to watch
+  if (!isPidAlive(entry.anchorPid)) return false;
+  if (!entry.anchorStart) return true;
+  const now = processStartTime(entry.anchorPid);
+  return now === null || now === entry.anchorStart;
+}
+
+/** Does a registry entry belong to this session? */
+export function anchorMatches(entry, anchor) {
+  if (anchor.pid === 0) return entry.anchorPid === 0 && entry.anchorLabel === anchor.label;
+  return entry.anchorPid === anchor.pid && (entry.anchorStart ?? null) === (anchor.start ?? null) && anchorAlive(entry);
+}