@monoes/monobrowse 1.0.27 → 1.0.28

package/src/browser/browser-lifecycle.ts

@@ -1,8 +1,9 @@
 // Split out of browser.ts (file-size sweep). Pure move: no behaviour change.
 
 import { fetchBrowserWebSocketUrl } from './browser-discovery.js';
-import { launchedPids, launchedUserDataDirs } from './browser-state.js';
+import { launchedPids, launchedUserDataDirs, ownedUserDataDirPorts } from './browser-state.js';
 import { CdpClient, fetchTargets } from './cdp.js';
+import { removeOwnedProfileDir } from './profile-dir.js';
 import {
   listSessionRecords,
   loadSessionRecord,
@@ -41,6 +42,11 @@ const REAP_CONNECT_TIMEOUT_MS = 3000;
  * singleton lock, and if the caller's process exited first the kill never
  * happened at all. Callers reasonably read a resolved close() as "that
  * browser is gone"; on the graceful path it now means that.
+ *
+ * A profile directory monobrowse created for that browser (the default temp
+ * profile, or a CLI session's — never a caller-supplied one) is deleted once
+ * the process is gone, on both paths (#395). In a fresh process the dir and
+ * its ownership come from the persisted session record.
  */
 export async function closeBrowser(client: CdpClient, port: number): Promise<void> {
   let gracefullyClosed = false;
@@ -71,6 +77,7 @@ export async function closeBrowser(client: CdpClient, port: number): Promise<voi
   }
 
   let pid = launchedPids.get(port);
+  let profileDir = ownedUserDataDirPorts.has(port) ? launchedUserDataDirs.get(port) : undefined;
   if (pid === undefined) {
     // Fresh process (each CLI invocation is its own node process — see
     // module header) — launchedPids is per-process and empty here even
@@ -89,6 +96,7 @@ export async function closeBrowser(client: CdpClient, port: number): Promise<voi
         const age = persisted.savedAt !== undefined ? Date.now() - persisted.savedAt : undefined;
         if (age === undefined || age <= PERSISTED_PID_MAX_AGE_MS) {
           pid = persisted.pid;
+          if (persisted.ownsUserDataDir) profileDir = persisted.userDataDir;
         }
       }
     } catch {
@@ -97,6 +105,7 @@ export async function closeBrowser(client: CdpClient, port: number): Promise<voi
   }
   if (pid === undefined) return; // not a process we launched, or too stale to trust — nothing to kill
   launchedPids.delete(port);
+  ownedUserDataDirPorts.delete(port);
 
   // Liveness-check before every SIGKILL (not just the safety-net path below)
   // — process.kill(pid, 0) throws ESRCH if the PID is no longer running,
@@ -109,17 +118,18 @@ export async function closeBrowser(client: CdpClient, port: number): Promise<voi
     } catch {
       /* already exited, or never was — nothing to do */
     }
-    return;
+  } else if (!(await waitForProcessExit(pid))) {
+    // Browser.close was acknowledged — wait for the process to actually go
+    // away, then force-kill as a safety net in case it hung.
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      /* raced us to exit — expected */
+    }
   }
 
-  // Browser.close was acknowledged — wait for the process to actually go away,
-  // then force-kill as a safety net in case it hung.
-  if (await waitForProcessExit(pid)) return;
-  try {
-    process.kill(pid, 'SIGKILL');
-  } catch {
-    /* raced us to exit — expected */
-  }
+  // Waits (bounded) for the killed process to be gone before deleting.
+  if (profileDir) await removeOwnedProfileDir(profileDir, { pid });
 }
 
 /** Poll until `pid` is gone or PROCESS_EXIT_TIMEOUT_MS elapses. Returns

package/src/browser/browser-state.ts

@@ -6,9 +6,12 @@
 // to (already-running browser) are never recorded here — we only ever kill
 // processes we launched ourselves.
 export const launchedPids = new Map<number, number>();
-// userDataDir per launched port — informational, persisted alongside the pid
-// so a later process could clean up the temp profile dir too if ever needed.
+// userDataDir per launched port, persisted alongside the pid so a later
+// process can clean up the temp profile dir too (#395).
 export const launchedUserDataDirs = new Map<number, string>();
+// Launched ports whose userDataDir monobrowse created itself (not one the
+// caller supplied). Only these profile dirs are ever deleted on close.
+export const ownedUserDataDirPorts = new Set<number>();
 
 /** PID of the Chrome instance *this process* launched on `port`, if any. */
 export function getLaunchedPid(port: number): number | undefined {
@@ -19,3 +22,9 @@ export function getLaunchedPid(port: number): number | undefined {
 export function getLaunchedUserDataDir(port: number): string | undefined {
   return launchedUserDataDirs.get(port);
 }
+
+/** Whether the userDataDir of the Chrome *this process* launched on `port`
+ *  was created by monobrowse, and so is deleted when that browser closes. */
+export function ownsLaunchedUserDataDir(port: number): boolean {
+  return ownedUserDataDirPorts.has(port);
+}

package/src/browser/browser.ts

@@ -14,4 +14,8 @@ export {
   openUrl,
   waitForLoad,
 } from './browser-page.js';
-export { getLaunchedPid, getLaunchedUserDataDir } from './browser-state.js';
+export {
+  getLaunchedPid,
+  getLaunchedUserDataDir,
+  ownsLaunchedUserDataDir,
+} from './browser-state.js';

package/src/browser/profile-dir.ts

@@ -0,0 +1,249 @@
+/**
+ * Temporary Chrome profile directories monobrowse creates, and their removal
+ * (#395).
+ *
+ * Every launch without a caller-supplied `userDataDir` (and every CLI
+ * session) gets a fresh `--user-data-dir` directly under `os.tmpdir()`.
+ * Nothing used to delete them, so they piled up until /tmp ran out of space
+ * (81 profiles, 4.4 GB on one machine). Two paths remove them now:
+ *
+ *   - removeOwnedProfileDir(): when monobrowse closes or kills a browser it
+ *     launched in a directory it created — after Chrome has exited, since
+ *     Chrome writes into its profile until then.
+ *   - sweepStaleProfileDirs(): at the next launch, for directories whose
+ *     owner crashed or was killed before it could close its browser.
+ *
+ * Both touch only real directories directly inside the tmp root whose name
+ * matches one of the exact patterns below. A caller-supplied `userDataDir`
+ * never matches them unless the caller copied our naming, and even then the
+ * close path also needs the explicit ownership flag launchBrowser records.
+ */
+
+import { lstat, readdir, readFile, readlink, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+
+/** `monomind-browser-<port>-<pid>-<uuid8>` (launchBrowser's default profile). */
+const LAUNCH_PROFILE_RE = /^monomind-browser-\d+-(\d+)-[0-9a-f]{8}$/;
+/** `monomind-browse-<pid>-<uuid8>` (a CLI browse session's profile). */
+const SESSION_PROFILE_RE = /^monomind-browse-(\d+)-[0-9a-f]{8}$/;
+
+/** A directory younger than this is never swept: its launch may still be
+ *  starting (Chrome has not yet put its pid anywhere we can see). */
+export const PROFILE_SWEEP_GRACE_MS = 10 * 60 * 1000;
+// Bounded waits for removeOwnedProfileDir(): for the browser pid to go, then
+// for any other process still holding the profile (Chrome's helpers).
+const EXIT_WAIT_MS = 5000;
+const HOLDER_WAIT_MS = 2000;
+const POLL_MS = 50;
+const RM_RETRY_DELAY_MS = 250;
+
+/** Name for a new default launch profile, directly under `root`. */
+export function launchProfileDirPath(port: number, id: string, root = tmpdir()): string {
+  return join(root, `monomind-browser-${port}-${process.pid}-${id}`);
+}
+
+/** Name for a new CLI session profile, directly under `root`. */
+export function sessionProfileDirPath(id: string, root = tmpdir()): string {
+  return join(root, `monomind-browse-${process.pid}-${id}`);
+}
+
+/** The pid encoded in a profile directory name we create, or null when
+ *  `name` is not one of ours. */
+export function profileDirOwnerPid(name: string): number | null {
+  const m = LAUNCH_PROFILE_RE.exec(name) ?? SESSION_PROFILE_RE.exec(name);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Whether `dir` is a directory monobrowse created: its name matches our
+ * pattern, it is a real directory (not a symlink), and its resolved parent
+ * is `root`. Anything else is never deleted.
+ */
+export async function isOwnedProfileDir(dir: string, root = tmpdir()): Promise<boolean> {
+  try {
+    if (profileDirOwnerPid(basename(dir)) === null) return false;
+    const st = await lstat(dir);
+    if (!st.isDirectory() || st.isSymbolicLink()) return false;
+    return dirname(await realpath(dir)) === (await realpath(root));
+  } catch {
+    return false;
+  }
+}
+
+/** Whether `pid` is a live process. EPERM means it exists but is not ours. */
+export function isPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/**
+ * Pids of live processes whose command line passes `--user-data-dir=<dir>`,
+ * read from `procDir` (Linux /proc). Null when it cannot be read at all, so
+ * the caller falls back to other evidence instead of reading "nobody".
+ */
+export async function profileDirHolders(dir: string, procDir = '/proc'): Promise<number[] | null> {
+  let entries: string[];
+  try {
+    entries = await readdir(procDir);
+  } catch {
+    return null;
+  }
+  const wanted = new Set([`--user-data-dir=${dir}`]);
+  try {
+    wanted.add(`--user-data-dir=${await realpath(dir)}`);
+  } catch {
+    /* gone already — the literal path is all there is to match */
+  }
+  const holders: number[] = [];
+  for (const entry of entries) {
+    if (!/^\d+$/.test(entry)) continue;
+    try {
+      const args = (await readFile(join(procDir, entry, 'cmdline'), 'utf8')).split('\0');
+      if (args.some((a) => wanted.has(a))) holders.push(Number(entry));
+    } catch {
+      /* exited while we looked, or not readable */
+    }
+  }
+  return holders;
+}
+
+/** The live pid Chrome's `SingletonLock` (a `<host>-<pid>` symlink) names,
+ *  or null when there is no lock or its pid is gone. */
+async function singletonLockHolder(dir: string): Promise<number | null> {
+  try {
+    const m = /-(\d+)$/.exec(await readlink(join(dir, 'SingletonLock')));
+    const pid = m ? Number(m[1]) : Number.NaN;
+    return isPidAlive(pid) ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether any live process still uses `dir` as its Chrome profile. `procDir`
+ *  null skips the /proc scan (non-Linux), leaving only the SingletonLock. */
+export async function isProfileDirInUse(
+  dir: string,
+  opts: { procDir?: string | null } = {},
+): Promise<boolean> {
+  const procDir = opts.procDir === undefined ? defaultProcDir() : opts.procDir;
+  if (procDir !== null) {
+    const holders = await profileDirHolders(dir, procDir);
+    if (holders?.some(isPidAlive)) return true;
+  }
+  return (await singletonLockHolder(dir)) !== null;
+}
+
+function defaultProcDir(): string | null {
+  return process.platform === 'linux' ? '/proc' : null;
+}
+
+/**
+ * Delete a profile directory monobrowse created, once the browser `pid` that
+ * used it has exited (bounded wait) and no other process still holds it.
+ * Removal is retried once — Chrome's helpers can still be flushing a file
+ * as the first attempt runs. Returns whether the directory is gone. Never
+ * throws: a directory left behind is swept at a later launch.
+ */
+export async function removeOwnedProfileDir(
+  dir: string,
+  opts: { pid?: number; root?: string; procDir?: string | null } = {},
+): Promise<boolean> {
+  try {
+    if (!(await isOwnedProfileDir(dir, opts.root))) return false;
+    if (opts.pid !== undefined && !(await waitUntil(() => !isPidAlive(opts.pid!), EXIT_WAIT_MS))) {
+      return false;
+    }
+    if (!(await waitUntil(async () => !(await isProfileDirInUse(dir, opts)), HOLDER_WAIT_MS))) {
+      return false;
+    }
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        await rm(dir, { recursive: true, force: true });
+        return true;
+      } catch {
+        await delay(RM_RETRY_DELAY_MS);
+      }
+    }
+  } catch {
+    /* best-effort */
+  }
+  return false;
+}
+
+export interface ProfileSweepOptions {
+  /** Directory to sweep. Default os.tmpdir(); tests inject their own. */
+  root?: string;
+  /** Minimum age (by mtime) before a directory may be swept. */
+  graceMs?: number;
+  /** See isProfileDirInUse. */
+  procDir?: string | null;
+  now?: number;
+}
+
+/**
+ * Delete profile directories left behind by a monobrowse process that died
+ * without closing its browser. A directory directly in `root` is removed
+ * only when ALL of these hold:
+ *   - its name matches one of our exact patterns and it is a real directory
+ *     (symlinks, files and anything else are never touched);
+ *   - its mtime is older than the grace period, so a concurrent launch that
+ *     is still starting is left alone;
+ *   - the pid in its name is not a live process;
+ *   - no live Chrome uses it (/proc command lines on Linux, plus the
+ *     profile's SingletonLock everywhere). A CLI `open` process exits right
+ *     after launching, so this check is what keeps a live session's profile.
+ *
+ * Best-effort: any error skips that entry, and the sweep never throws.
+ * Returns the directories removed.
+ */
+export async function sweepStaleProfileDirs(opts: ProfileSweepOptions = {}): Promise<string[]> {
+  const root = opts.root ?? tmpdir();
+  const cutoff = (opts.now ?? Date.now()) - (opts.graceMs ?? PROFILE_SWEEP_GRACE_MS);
+  const removed: string[] = [];
+  let entries: string[];
+  try {
+    entries = await readdir(root);
+  } catch {
+    return removed;
+  }
+  for (const name of entries) {
+    try {
+      const pid = profileDirOwnerPid(name);
+      if (pid === null) continue;
+      const dir = join(root, name);
+      const st = await lstat(dir);
+      if (!st.isDirectory() || st.mtimeMs >= cutoff) continue;
+      if (isPidAlive(pid)) continue;
+      if (!(await isOwnedProfileDir(dir, root))) continue;
+      if (await isProfileDirInUse(dir, opts)) continue;
+      await rm(dir, { recursive: true, force: true });
+      removed.push(dir);
+    } catch {
+      /* skip this entry */
+    }
+  }
+  return removed;
+}
+
+/** Poll `cond` until it holds or `ms` elapses. The timer is ref'd on purpose
+ *  (see waitForProcessExit in browser-lifecycle.ts): callers await it. */
+async function waitUntil(cond: () => boolean | Promise<boolean>, ms: number): Promise<boolean> {
+  const deadline = Date.now() + ms;
+  for (;;) {
+    if (await cond()) return true;
+    if (Date.now() >= deadline) return false;
+    await delay(POLL_MS);
+  }
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/browser/ref-cache.ts

@@ -118,6 +118,9 @@ export interface SessionRecord {
   launched: boolean;
   pid?: number;
   userDataDir?: string;
+  /** true = monobrowse created `userDataDir` itself, so closing this session
+   *  deletes it (#395). Absent for a caller-supplied or older record. */
+  ownsUserDataDir?: boolean;
   savedAt?: number;
   /** Set by `--session <name>`: only commands naming it resolve this session,
    *  and commands naming none never land on it. */
@@ -142,6 +145,7 @@ export async function saveSessionRecord(
     launched?: boolean;
     pid?: number;
     userDataDir?: string;
+    ownsUserDataDir?: boolean;
     savedAt?: number;
     name?: string;
   },
@@ -161,6 +165,7 @@ export async function saveSessionRecord(
         launched: opts?.launched !== false,
         pid: opts?.pid,
         userDataDir: opts?.userDataDir,
+        ownsUserDataDir: opts?.ownsUserDataDir === true || undefined,
         savedAt: opts?.savedAt ?? Date.now(),
         name: opts?.name,
       }),
@@ -247,6 +252,7 @@ function parseSessionRecord(raw: string): SessionRecord | null {
     launched?: unknown;
     pid?: unknown;
     userDataDir?: unknown;
+    ownsUserDataDir?: unknown;
     savedAt?: unknown;
     name?: unknown;
   };
@@ -266,6 +272,7 @@ function parseSessionRecord(raw: string): SessionRecord | null {
         ? data.pid
         : undefined,
     userDataDir: typeof data.userDataDir === 'string' ? data.userDataDir : undefined,
+    ownsUserDataDir: data.ownsUserDataDir === true || undefined,
     savedAt: typeof data.savedAt === 'number' ? data.savedAt : undefined,
     name: typeof data.name === 'string' && SESSION_NAME_RE.test(data.name) ? data.name : undefined,
   };

package/src/browser/types.ts

@@ -10,6 +10,12 @@ export interface BrowserConfig {
   headless?: boolean;
   executablePath?: string;
   userDataDir?: string;
+  /** The caller created `userDataDir` for this launch alone (the CLI's
+   *  session profile), so monobrowse deletes it when the browser closes,
+   *  like the default profile. Only honoured for a directory that matches
+   *  monobrowse's own tmpdir naming; any other `userDataDir` is never
+   *  deleted. */
+  ownsUserDataDir?: boolean;
   args?: string[];
   /** Milliseconds to wait for the launched Chrome to open its CDP port
    *  before giving up. Default 10000 — raise this for environments where

package/src/cli/commands.ts

@@ -97,6 +97,8 @@ import type { Command, CommandContext, CommandResult } from './types.js';
 // before the subcommands were split out, and the tests import them from here.
 export { deriveBoxOutput } from './commands-page.js';
 export { parseBatchCommandLine } from './commands-script.js';
+// For embedders that do not process.exit() after a subcommand (#408).
+export { disconnectSession } from './session.js';
 
 // ---------------------------------------------------------------------------
 // batch — dispatches over this file's own subcommand catalogue, which is why

package/src/cli/session.ts

@@ -34,8 +34,7 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { sessionProfileDirPath } from '../browser/profile-dir.js';
 import { SESSION_NAME_RE } from '../browser/ref-cache.js';
 import type { CdpClient, ElementRef, SessionRecord } from '../index.js';
 import { output } from './output.js';
@@ -254,6 +253,7 @@ export async function adoptLegacySession(
     launched: legacy.launched,
     pid: legacy.pid,
     userDataDir: legacy.userDataDir,
+    ownsUserDataDir: legacy.ownsUserDataDir,
     savedAt: legacy.savedAt,
   });
   await browser.removeLegacySessionRecord();
@@ -290,8 +290,10 @@ export async function launchSessionBrowser(
         port: 0,
         headless: opts.headless,
         // Chrome reports the port it bound inside this directory, so it must
-        // belong to this session alone.
-        userDataDir: join(tmpdir(), `monomind-browse-${process.pid}-${randomUUID().slice(0, 8)}`),
+        // belong to this session alone — and it is deleted when the session
+        // closes (#395).
+        userDataDir: sessionProfileDirPath(randomUUID().slice(0, 8)),
+        ownsUserDataDir: true,
       });
   await recordSession(browser, port, opts.name);
   ensureSignalCleanupHandlers();
@@ -324,6 +326,7 @@ async function recordSession(
     await browser.saveSessionRecord(port, {
       pid,
       userDataDir: browser.getLaunchedUserDataDir(port),
+      ownsUserDataDir: browser.ownsLaunchedUserDataDir(port),
       name: name ?? (await browser.loadSessionRecord(port))?.name,
     });
     return;
@@ -337,6 +340,7 @@ async function recordSession(
     launched: existing?.launched,
     pid: existing?.pid,
     userDataDir: existing?.userDataDir,
+    ownsUserDataDir: existing?.ownsUserDataDir,
     name: name ?? existing?.name,
   });
 }
@@ -373,6 +377,20 @@ export async function ensureConnected(port: number, targetId?: string) {
   return { client: session.client!, sessionId: session.sessionId, targetId: session.targetId };
 }
 
+/**
+ * Drop this process's CDP connection and nothing else: the browser, its
+ * session record and the port pin all stay, so the next command reconnects to
+ * the same session. An embedder that lets the event loop drain instead of
+ * calling process.exit() (monomind's CLI, ADR-R001) calls this once a
+ * subcommand is done — an open websocket otherwise holds the process until
+ * its force-exit watchdog (#408).
+ */
+export function disconnectSession(): void {
+  session.client?.close();
+  session.client = null;
+  session.sessionId = '';
+}
+
 // Each CLI invocation is a fresh process, so the in-memory session.refs Map built by
 // a prior `snapshot` command is gone by the time a later `find`/`click`/etc.
 // command runs. Rehydrate it from the on-disk ref cache (written by