dsh-builtin-browser 0.4.1 → 0.4.2

package/lib/browser-electron/bridge-connection.js

@@ -18,18 +18,48 @@
  * @module dsh-browser/browser-electron/bridge-connection
  */
 import { connect } from 'node:net';
+/**
+ * Safety cap on one un-answered reply line. CDP answers from the sidebar (a screenshot's
+ * base64 is the big one) cross this socket, so the cap is generous; what it exists for is a
+ * peer that never sends a newline — `this.buffer += chunk` grew without bound, unlike the
+ * same buffer in remote-host.ts, which caps at 512 MiB.
+ */
+const MAX_BUFFER_BYTES = 128 * 1024 * 1024;
+/**
+ * Field this client adds to every request so the shell can echo it back and never relies on
+ * byte order to pair an answer with its request. Loosely named, and additive on purpose: a
+ * bridge that does not know it simply ignores it (the current shipped shell does), and the
+ * client then falls back to arrival order, which is what the protocol guaranteed before.
+ */
+const REQUEST_ID_FIELD = 'bridgeRequestId';
 /**
  * A reusable connection to the bridge.
  *
- * Requests are serialised by construction: one socket, one in-flight request at a
- * time, answered in order. A broken socket is discarded so the next call dials
- * again — a dead connection must never become a dead plugin.
+ * Requests may be in flight CONCURRENTLY, so answers are correlated by id rather than by
+ * position: `call()` stamps a unique {@link REQUEST_ID_FIELD} on the request and `onData()`
+ * resolves the entry that carries the echoed id. A bridge that does not echo it is still
+ * supported — its answer is handed to the oldest outstanding request, which is the
+ * arrival-order rule the protocol states. Once such an answer has been seen, the connection
+ * stops keeping two requests in flight (a second one re-dials), so position can never be the
+ * only thing distinguishing two callers' answers. An answer that matches nothing is never
+ * handed to whichever request happens to be first: the socket is dropped instead.
+ *
+ * A broken socket is discarded so the next call dials again — a dead connection must never
+ * become a dead plugin.
  */
 export class BridgeConnection {
     endpoint;
     socket;
     buffer = '';
+    /** Outstanding requests by id. */
+    pending = new Map();
+    /** Ids of the requests sent on the current socket, oldest first. */
     queue = [];
+    nextId = 1;
+    /** True once any reply arrived without an id: this bridge does not echo request ids. */
+    idLessBridge = false;
+    /** True once this connection may only have one request in flight at a time. */
+    serialisable = false;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
@@ -38,33 +68,67 @@ export class BridgeConnection {
     }
     /**
      * Send one request, reusing the socket if it is still healthy.
-     * @param request - the request body (the token is added here).
+     *
+     * Requests may overlap: the request is written as soon as it is queued, so two concurrent
+     * callers have two requests in flight. Each carries a unique {@link REQUEST_ID_FIELD}, and
+     * `onData()` resolves the entry that carries the echoed id — which is what makes
+     * correlation independent of arrival order. A bridge that does not echo the field (the
+     * shipped shell today) still works by arrival order; see {@link onData}.
+     * @param request - the request body (the token and the request id are added here).
      * @param timeoutMs - how long to wait for the answer before dropping the socket.
      * @returns the bridge's answer.
      */
     async call(request, timeoutMs = 20_000) {
-        const socket = this.ensureSocket();
+        // One re-dial, and only for the case this exists for: a socket that has already carried
+        // an id-less answer cannot have a second request in flight, because two outstanding
+        // requests would be matched by position — the swap this correlation prevents. It is a
+        // straight-line re-dial rather than a retry loop: an earlier revision re-entered call()
+        // from inside its own promise executor, which left an orphaned pending entry behind and,
+        // when the condition could not clear, spun until the process ran out of heap.
+        let socket = this.ensureSocket();
+        if (this.serialisable && this.queue.length > 0) {
+            this.reset(new Error('dsh-builtin-browser: bridge connection reopened so replies stay attributable'));
+            socket = this.ensureSocket();
+        }
+        const id = this.nextId++;
         return await new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                resolve: answer => { clearTimeout(timer); resolve(answer); },
+                reject: error => { clearTimeout(timer); reject(error); },
+            });
+            this.queue.push(id);
             const timer = setTimeout(() => {
-                const index = this.queue.findIndex(entry => entry.resolve === resolve);
-                if (index !== -1)
-                    this.queue.splice(index, 1);
                 const error = new Error(`dsh-builtin-browser: bridge timed out after ${timeoutMs}ms`);
-                this.reset(error);
+                // An unanswered request desynchronises the stream for an id-less bridge, and leaves one
+                // outstanding for one that echoes ids — either way the next call should start on a
+                // fresh socket. Only when THIS request's socket is still the live one: tearing down the
+                // REPLACEMENT because an abandoned request timed out would break whatever is using it.
+                //
+                // This test used to read `this.pending.has(id) && this.socket === socket`, with
+                // `forget(id)` on the line above it — and forget() is what removes the entry that `has`
+                // was looking for, so the condition was false every single time and the rebuild never
+                // ran. A timed-out call therefore left the desynchronised socket in place, and every
+                // later call inherited exactly the ambiguity this reset exists to clear. Deciding
+                // before forgetting is the whole fix; the `else` still drops the stale entry.
+                if (this.socket === socket)
+                    this.reset(error);
+                else
+                    this.forget(id);
+                // reset() already rejected this entry through its wrapper when it ran, so this is
+                // either the only rejection or a no-op that guarantees the caller settles.
                 reject(error);
             }, timeoutMs);
-            this.queue.push({
-                resolve: answer => { clearTimeout(timer); resolve(answer); },
-                reject: error => { clearTimeout(timer); reject(error); },
-            });
             try {
-                socket.write(JSON.stringify({ token: this.endpoint.token, ...request }) + '\n');
+                // The id is added LAST so a request body can never shadow it, and the token is
+                // added here rather than by the caller.
+                socket.write(JSON.stringify({ token: this.endpoint.token, ...request, [REQUEST_ID_FIELD]: id }) + '\n');
             }
             catch (error) {
                 clearTimeout(timer);
-                this.queue.pop();
+                this.forget(id);
                 const failure = error instanceof Error ? error : new Error(String(error));
-                this.reset(failure);
+                if (this.socket === socket)
+                    this.reset(failure);
                 reject(failure);
             }
         });
@@ -80,16 +144,33 @@ export class BridgeConnection {
         const socket = connect({ host: '127.0.0.1', port: this.endpoint.port });
         socket.setEncoding('utf8');
         socket.on('data', chunk => this.onData(String(chunk)));
-        socket.on('error', error => this.reset(error));
-        socket.on('close', () => this.reset(new Error('dsh-builtin-browser: bridge connection closed')));
+        // Both handlers pass the socket they belong to, so a late event from a socket that was
+        // already replaced cannot tear down its successor: 'close' still fires for a socket that
+        // was removed mid-recycle, and acting on it there would kill a perfectly good connection.
+        socket.on('error', error => this.socketFailed(socket, error));
+        socket.on('close', () => this.socketFailed(socket, new Error('dsh-builtin-browser: bridge connection closed')));
         this.buffer = '';
         this.socket = socket;
         socket.write(JSON.stringify({ token: this.endpoint.token }) + '\n');
         return socket;
     }
-    /** Resolve queued requests in order as answers arrive. */
+    /** Tear the connection down for an event raised by `source`, unless it is already gone. */
+    socketFailed(source, error) {
+        if (this.socket !== source)
+            return;
+        this.reset(error);
+    }
+    /** Resolve queued requests by id, or in order when the bridge does not echo one. */
     onData(chunk) {
         this.buffer += chunk;
+        // A peer that never sends a newline must not grow this buffer without bound. Failing
+        // the connection is the honest outcome: the caller gets an error naming the cap, while
+        // the next call dials a fresh socket.
+        if (this.buffer.length > MAX_BUFFER_BYTES) {
+            this.buffer = '';
+            this.reset(new Error(`dsh-builtin-browser: bridge reply exceeded ${String(MAX_BUFFER_BYTES)} bytes`));
+            return;
+        }
         let newline = this.buffer.indexOf('\n');
         while (newline !== -1) {
             const line = this.buffer.slice(0, newline).trim();
@@ -97,9 +178,28 @@ export class BridgeConnection {
             newline = this.buffer.indexOf('\n');
             if (line === '')
                 continue;
-            const entry = this.queue.shift();
+            const echoed = echoOf(line);
+            const id = echoed ?? this.queue[0];
+            if (id === undefined) {
+                // Nothing is waiting for this answer: the peer is answering something this socket
+                // never asked (or answered twice). Drop the socket rather than trust the stream.
+                this.reset(new Error('dsh-builtin-browser: bridge answered with no request outstanding'));
+                return;
+            }
+            const index = this.queue.indexOf(id);
+            if (index !== -1)
+                this.queue.splice(index, 1);
+            const entry = this.pending.get(id);
             if (entry === undefined)
                 continue;
+            this.pending.delete(id);
+            // Id-less bridges pair by order, so a reply for the WRONG request cannot be told apart
+            // from the right one. Remember that this bridge does not echo ids, and serialise every
+            // later call so the ambiguity cannot arise again.
+            if (echoed === undefined) {
+                this.idLessBridge = true;
+                this.serialisable = true;
+            }
             try {
                 const answer = JSON.parse(line);
                 // A rejected token means the shell restarted with a new one, so this socket
@@ -117,6 +217,13 @@ export class BridgeConnection {
             }
         }
     }
+    /** Forget one request (its answer can no longer be matched). */
+    forget(id) {
+        this.pending.delete(id);
+        const index = this.queue.indexOf(id);
+        if (index !== -1)
+            this.queue.splice(index, 1);
+    }
     /** Tear the socket down, failing pending work. */
     reset(error) {
         if (this.socket !== undefined) {
@@ -126,8 +233,23 @@ export class BridgeConnection {
             socket.destroy();
         }
         this.buffer = '';
-        const pending = this.queue.splice(0, this.queue.length);
+        this.queue.length = 0;
+        const pending = [...this.pending.values()];
+        this.pending.clear();
         for (const entry of pending)
             entry.reject(error);
     }
 }
+/** The request id a raw answer line echoes back, when it carries one. */
+function echoOf(line) {
+    try {
+        const answer = JSON.parse(line);
+        const value = answer[REQUEST_ID_FIELD];
+        return typeof value === 'number' && Number.isSafeInteger(value) ? value : undefined;
+    }
+    catch {
+        // A malformed line cannot be matched by id; the caller consumes it in order and
+        // reports the parse failure itself.
+        return undefined;
+    }
+}

package/lib/browser-electron/entry.d.ts

@@ -34,7 +34,7 @@ export interface Config {
     readonly downloadDir?: string;
     /** Maximum snapshot elements before truncation. Default 60. */
     readonly snapshotMaxElements?: number;
-    /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
+    /** Maximum content characters before truncation when no maxChars is given. No longer read: the cap is per format (html and json 50 000, otherwise 20 000). */
     readonly contentMaxChars?: number;
 }
 export declare const Config: z<Config>;

package/lib/browser-electron/entry.js

@@ -17,8 +17,10 @@ import { join } from 'node:path';
 import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js';
 import { DesktopBridgeViewHost } from './desktop-bridge-host.js';
 import { detectBrowser, searchSummary, SystemBrowserViewHost } from './system-browser.js';
+import { claimEphemeralProfile, ephemeralProfileName, sweepAbandonedEphemeralProfiles } from './ephemeral-profile.js';
 import { MissingSystemBrowserHost } from './missing-system-browser.js';
 import { SettingsStore } from './settings-store.js';
+import { sameOrigin } from './settings-route.js';
 export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from './provider.js';
 export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.js';
 /** Cordis plugin name used by loader diagnostics. */
@@ -83,7 +85,14 @@ export function apply(ctx, config) {
             ctx.logger?.info?.(`dsh-builtin-browser: ${note}`);
         }
         catch (error) {
-            // Never leave the surface without a provider.
+            // Never leave the surface without a provider. The half-built host is disposed FIRST: an
+            // adopt that got as far as constructing it may already hold a socket, a listener or a child
+            // process, and dropping it on the floor is how a failed upgrade becomes a leak that only
+            // shows up as a stray Electron in the task manager.
+            try {
+                host.dispose?.();
+            }
+            catch { /* the fallback below matters more than this */ }
             unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(new RemoteElectronViewHost(defaultHostMainPath()), providerConfig));
             ctx.logger?.warn?.(`dsh-builtin-browser: could not adopt ${note} (${String(error)})`);
         }
@@ -118,15 +127,29 @@ export function apply(ctx, config) {
             }
         }
         else {
-            const home = process.env.DSH_HOME ?? homedir();
+            // Same profile root as settings-store, history-store and desktop-bridge-host: the
+            // `?.dsh` component used to be missing HERE only, so a desktop launched from a
+            // shortcut (no DSH_HOME in the environment) put its browser profile in
+            // `C:\Users\<user>\dsh-builtin-browser-host\` while its settings and history lived in
+            // `~/.dsh/dsh-builtin-browser-host/` — two half-profiles that never met, and a
+            // settings panel whose switches appeared not to apply.
+            const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
             // Login state lives in the browser profile, so the cookies setting decides where
             // that profile goes: a stable directory keeps the user signed in across restarts
             // (the point of using their own browser), while turning persistence off gets a
             // throwaway directory that is removed when the browser is released.
             const persist = settings.get().cookies.persist;
+            const profileRoot = join(home, BROWSER_PROFILE_DIR);
             const profileDir = persist
-                ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
-                : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`);
+                ? join(profileRoot, `${detected.kind}-profile`)
+                : join(profileRoot, ephemeralProfileName(detected.kind, randomUUID()));
+            if (!persist) {
+                // A process killed outright never runs its own cleanup (see ephemeral-profile.ts),
+                // so the sweep happens HERE — at the only moment that can still act on a profile
+                // whose owner is gone — and before this run claims a directory of its own.
+                sweepAbandonedEphemeralProfiles(profileRoot, detected.kind);
+                claimEphemeralProfile(profileDir);
+            }
             adopt(new SystemBrowserViewHost(detected, profileDir, [], persist ? undefined : profileDir), `will drive the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`);
         }
     }
@@ -134,16 +157,41 @@ export function apply(ctx, config) {
     // replace it, which is exactly what this guard prevents.
     if (explicitChoice)
         return;
-    void DesktopBridgeViewHost.discover().then(sidebar => {
-        // No bridge (plain `dsh web`, an older desktop build, or a shell that already
-        // exited): keep self-hosting, which is what every surface has always done.
-        if (sidebar === undefined)
+    // The shell may not be up yet. `dsh web` starts before — or entirely without — the desktop app
+    // that hosts the bridge, and a one-shot discovery meant a bridge that appeared a second later
+    // was never adopted for the rest of the process's life. Retry a handful of times over roughly
+    // half a minute, then stop: this is a convenience, not a promise, and the session the user is
+    // already driving in the self-hosted window is not worth replacing minutes into their work.
+    // `adopt` is itself one-shot (its `upgraded` guard), so the only possible effect of a retry
+    // that lands late is adopting a bridge that showed up just after startup.
+    void (async () => {
+        for (const delay of [0, 2_000, 5_000, 15_000]) {
+            if (delay > 0)
+                await new Promise(resolve => setTimeout(resolve, delay));
+            let sidebar;
+            try {
+                sidebar = await DesktopBridgeViewHost.discover();
+            }
+            catch {
+                sidebar = undefined; // discovery is documented not to throw; never let it stop the retries
+            }
+            if (sidebar === undefined)
+                continue;
+            adopt(sidebar, 'driving the desktop sidebar browser');
             return;
-        adopt(sidebar, 'driving the desktop sidebar browser');
-    }).catch(() => { });
+        }
+    })();
 }
 /** Route the settings panel reads and writes. */
 const SETTINGS_ROUTE = '/dsh-builtin-browser/settings';
+/**
+ * The directory under the DSH home that holds this plugin's browser profile.
+ *
+ * Named once, because every consumer of it must agree: `settingsPath()` and the history
+ * store resolve their own copy from `$DSH_HOME`, and a profile written under a different
+ * root than the settings document is a pair that silently never meets.
+ */
+const BROWSER_PROFILE_DIR = 'dsh-builtin-browser-host';
 /**
  * Expose the settings document over the host's web server, which is how the
  * settings panel reads and writes it. A host without that service (headless /
@@ -169,31 +217,9 @@ function installSettingsRoute(ctx, settings) {
         // No web server on this surface: the settings file remains the interface.
     }
 }
-/**
- * Same-origin guard. Settings are machine-local configuration, so a page loaded
- * elsewhere must not be able to read or rewrite them.
- * @param request - the incoming request.
- * @returns whether the request may touch the settings document.
- */
-function sameOrigin(request) {
-    const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase();
-    if (site === 'cross-site')
-        return false;
-    const origin = String(request.headers.origin ?? '').trim();
-    if (origin === 'null')
-        return false;
-    if (origin === '')
-        return true;
-    try {
-        return new URL(origin).host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase();
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * One settings round-trip: `GET` reads the document, `PUT`/`POST` merges a
- * partial patch into it.
+ * partial patch into it. Admission lives in `settings-route.ts` so it can be tested.
  * @param request - the incoming request.
  * @param response - the response to write.
  * @param settings - the settings document.
@@ -206,11 +232,11 @@ async function handleSettingsRequest(request, response, settings) {
         });
         response.end(JSON.stringify(body));
     };
-    if (!sameOrigin(request)) {
+    const method = request.method ?? 'GET';
+    if (!sameOrigin(request, method !== 'GET')) {
         json(403, { ok: false, error: 'cross-origin request refused' });
         return;
     }
-    const method = request.method ?? 'GET';
     if (method === 'GET') {
         json(200, { ok: true, settings: settings.get(), path: settings.path() });
         return;

package/lib/browser-electron/ephemeral-profile.d.ts

@@ -0,0 +1,37 @@
+/** Test seams; production passes neither. */
+export interface SweepOptions {
+    /** The clock, for the age check. */
+    readonly now?: number;
+    /** Liveness test for an owner pid. */
+    readonly alive?: (pid: number) => boolean;
+}
+/**
+ * The directory name an ephemeral profile for `kind` gets, before it is claimed.
+ *
+ * The sweep matches on the same shape, so the two must agree: a name built anywhere else
+ * is a directory the sweep will never find.
+ * @param kind - the detected browser product (`chrome`, `edge`, ...).
+ * @param id - a per-run unique suffix.
+ * @returns the directory NAME, not a path.
+ */
+export declare function ephemeralProfileName(kind: string, id: string): string;
+/**
+ * Mark an ephemeral profile directory as this process's, so a later run can tell whether
+ * the process that created it is still there.
+ * @param dir - the profile directory (created if it does not exist yet).
+ * @param pid - the claiming process, defaulting to this one.
+ * @param now - the claim time, defaulting to the current clock.
+ * @returns true when the marker was written.
+ */
+export declare function claimEphemeralProfile(dir: string, pid?: number, now?: number): boolean;
+/**
+ * Delete the ephemeral profiles under `root` that belong to processes which are gone.
+ *
+ * Called before a new one is claimed, because that is the only moment that can still act
+ * on a profile whose owner was killed: nothing runs when the signal lands.
+ * @param root - the plugin's profile root (`<DSH_HOME>/dsh-builtin-browser-host`).
+ * @param kind - the browser product, which selects the directory-name prefix.
+ * @param options - test seams for the clock and the liveness test.
+ * @returns the names of the directories that were removed.
+ */
+export declare function sweepAbandonedEphemeralProfiles(root: string, kind: string, options?: SweepOptions): string[];

package/lib/browser-electron/ephemeral-profile.js

@@ -0,0 +1,146 @@
+/**
+ * The ephemeral browser profile: a throwaway directory under the DSH home, used when the
+ * user has turned profile persistence off, and deleted when the browser is released.
+ *
+ * Deleting on release is not enough by itself. A process killed outright — a DSH restart
+ * that ends in SIGKILL, "End task" in a task manager, a crashed host — never runs its
+ * cleanup, so the profile it was using survives on disk: the user asked for no profile to
+ * be kept and the machine keeps one anyway, holding cookies and history. Nothing can run
+ * at SIGKILL time, so the cleanup has to happen on the NEXT run instead, which is what
+ * this module provides.
+ *
+ * Ownership is a marker file inside the directory naming the process that claimed it. A
+ * directory whose owner is gone AND which has not been written to for a while is
+ * abandoned. The age check is what keeps the sweep away from a profile an orphaned
+ * browser (a child that outlived the parent which was killed) may still be using: a live
+ * Chromium writes to its profile continuously, so a directory that has not changed in an
+ * hour is not in use.
+ */
+import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** The marker file, named once because both the claim and the sweep read it. */
+const OWNER_FILE = '.dsh-ephemeral-owner';
+/**
+ * How long a profile is left alone regardless of ownership. An orphaned browser keeps
+ * writing to its profile, so this is what distinguishes "abandoned" from "in use by a
+ * process this one did not start".
+ */
+const ABANDONED_AFTER_MS = 60 * 60 * 1000;
+/**
+ * Whether a process with this pid exists.
+ *
+ * A signal of 0 performs the permission and existence checks without delivering anything.
+ * EPERM is a live process owned by someone else — alive, not gone.
+ * @param pid - the pid to test.
+ * @returns true when the process exists.
+ */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/**
+ * The directory name an ephemeral profile for `kind` gets, before it is claimed.
+ *
+ * The sweep matches on the same shape, so the two must agree: a name built anywhere else
+ * is a directory the sweep will never find.
+ * @param kind - the detected browser product (`chrome`, `edge`, ...).
+ * @param id - a per-run unique suffix.
+ * @returns the directory NAME, not a path.
+ */
+export function ephemeralProfileName(kind, id) {
+    return `${kind}-profile-ephemeral-${id}`;
+}
+/**
+ * Mark an ephemeral profile directory as this process's, so a later run can tell whether
+ * the process that created it is still there.
+ * @param dir - the profile directory (created if it does not exist yet).
+ * @param pid - the claiming process, defaulting to this one.
+ * @param now - the claim time, defaulting to the current clock.
+ * @returns true when the marker was written.
+ */
+export function claimEphemeralProfile(dir, pid = process.pid, now = Date.now()) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, OWNER_FILE), JSON.stringify({ pid, at: now }));
+        return true;
+    }
+    catch {
+        // The browser creates the directory itself when this fails, and cleanup is best
+        // effort throughout: a marker that could not be written must not stop the launch.
+        return false;
+    }
+}
+/**
+ * The claimed owner of an ephemeral profile, when it has one.
+ * @param dir - the profile directory.
+ * @returns the owner pid, or undefined when there is no readable marker.
+ */
+function readOwner(dir) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(dir, OWNER_FILE), 'utf8'));
+        return typeof parsed.pid === 'number' ? parsed.pid : undefined;
+    }
+    catch {
+        // No marker: a run from before this existed, or one killed before it wrote one. The
+        // age check has already applied, and a directory with no claimant that old is
+        // abandoned by any reading.
+        return undefined;
+    }
+}
+/**
+ * Delete the ephemeral profiles under `root` that belong to processes which are gone.
+ *
+ * Called before a new one is claimed, because that is the only moment that can still act
+ * on a profile whose owner was killed: nothing runs when the signal lands.
+ * @param root - the plugin's profile root (`<DSH_HOME>/dsh-builtin-browser-host`).
+ * @param kind - the browser product, which selects the directory-name prefix.
+ * @param options - test seams for the clock and the liveness test.
+ * @returns the names of the directories that were removed.
+ */
+export function sweepAbandonedEphemeralProfiles(root, kind, options = {}) {
+    const now = options.now ?? Date.now();
+    const alive = options.alive ?? processAlive;
+    const prefix = `${kind}-profile-ephemeral-`;
+    const removed = [];
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        // No profile root yet: nothing has ever been written here, so nothing to sweep.
+        return removed;
+    }
+    for (const name of names) {
+        if (!name.startsWith(prefix))
+            continue;
+        const dir = join(root, name);
+        let ageMs;
+        try {
+            ageMs = now - statSync(dir).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        // Recent writes mean a browser is still working in there. A killed DSH can leave its
+        // Chromium child running, and that child's profile is not garbage.
+        if (ageMs < ABANDONED_AFTER_MS)
+            continue;
+        const owner = readOwner(dir);
+        if (owner !== undefined && alive(owner))
+            continue;
+        try {
+            rmSync(dir, { recursive: true, force: true });
+            removed.push(name);
+        }
+        catch {
+            // In use, or not ours to remove. Leaving it is the safe outcome and the next run
+            // tries again — the alternative is deleting a profile out from under a live browser.
+        }
+    }
+    return removed;
+}

package/lib/browser-electron/history-store.d.ts

@@ -34,6 +34,22 @@ export declare function visitedHistoryPath(): string;
  */
 export declare class HistoryStore {
     private readonly file;
+    /**
+     * File size at which the next rewrite happens.
+     *
+     * Advanced after each rewrite so the cost is paid once per PRUNE_SLACK appends
+     * rather than on every append: asking "is it over the cap?" was true from the first
+     * over-cap write onwards, which is what made every later navigation rewrite the file.
+     */
+    private pruneThreshold;
+    /**
+     * Appends since the last rewrite.
+     *
+     * prune() runs after every navigation, and the answer is almost always "nothing to
+     * do" — but working that out from the file costs a full parse. Counting instead makes
+     * the common case a comparison.
+     */
+    private appendedSincePrune;
     private readonly maxEntries;
     private readonly maxAgeMs;
     /**
@@ -69,6 +85,15 @@ export declare class HistoryStore {
      * the count cap. Cheap no-op until the file grows past the cap, so callers can
      * run it after every append.
      */
+    /**
+     * How far past the cap the file may grow before it is rewritten.
+     *
+     * Scaled to the cap rather than fixed: a fixed 500 was meaningless when the cap is
+     * small (a caller asking for three entries would never reach 503), and the slack is
+     * there to batch rewrites, not to overrule the caller's bound.
+     * @returns the number of extra entries tolerated before a rewrite.
+     */
+    private slack;
     prune(): void;
     /** Parse the whole file, skipping blank and damaged lines. */
     private readAll;