dsh-builtin-browser 0.4.1 → 0.4.2

package/src/browser/types.ts

@@ -266,6 +266,14 @@ export interface BrowserWaitResult {
 export interface BrowserScreenshotResult {
   /** Base64 data URL of the capture (PNG or JPEG per the request). */
   readonly dataUrl: string
+  /** Pixel size of the image in `dataUrl`, when the capture was measured and scaled.
+   *
+   * Present when the request carried `maxWidth`/`maxHeight` and the layout metrics were
+   * readable: the scaling happens inside CDP through a clip, and without this the only way to
+   * learn what came back was to decode the data URL. Undefined means "not measured", which is
+   * also what an unscaled capture reports. */
+  readonly width?: number
+  readonly height?: number
   /** File path the capture was also saved to, when the request asked for it. */
   readonly path?: string
 }
@@ -396,6 +404,14 @@ export interface BrowserA11yNode {
   readonly depth: number
   /** Element tag name (lowercase). */
   readonly tag: string
+  /**
+   * A CSS selector for this node, when one can be derived from its id or name.
+   *
+   * Empty for the many elements that have neither. Present because a role and a name are not
+   * always enough to target a node: `{by: 'text'}` matches an accessible name only loosely,
+   * and this is what lets a caller point at the exact element it was shown.
+   */
+  readonly selector: string
   /** Viewport-relative center, for coordinate fallbacks. */
   readonly x: number
   readonly y: number
@@ -499,7 +515,15 @@ export interface BrowserProvider {
   /**
    * Open a new session. The provider mints the session id and prepares its
    * backing surface (a view, a headless page, and so on). Sessions are isolated from
-   * each other; a session must not be visible to any other session's caller.
+   * each other in what they OWN — tabs, the active tab, history, the view — so one
+   * session must not be visible to any other session's caller.
+   *
+   * That isolation stops at the browser's own state, and is not meant to go further:
+   * cookies, logins and site storage are deliberately shared by every session, because
+   * every session drives the same browser and "sign in once, use it everywhere" is the
+   * point of using a real one. Reads that hand that state to a caller (see
+   * `flushAuth`) are scoped to the page in question, which is least exposure rather
+   * than a claim that the jar is per-session.
    * @param label - optional human-readable label (e.g. the calling DSH task
    * id) the provider may surface on the visible surface (window title) so a
    * human can tell which task's page is currently shown.

package/src/browser-electron/bridge-connection.ts

@@ -34,17 +34,49 @@ interface PendingCall {
   readonly reject: (error: Error) => void
 }
 
+/**
+ * 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 {
   private socket: Socket | undefined
   private buffer = ''
-  private readonly queue: PendingCall[] = []
+  /** Outstanding requests by id. */
+  private readonly pending = new Map<number, PendingCall>()
+  /** Ids of the requests sent on the current socket, oldest first. */
+  private readonly queue: number[] = []
+  private nextId = 1
+  /** True once any reply arrived without an id: this bridge does not echo request ids. */
+  private idLessBridge = false
+  /** True once this connection may only have one request in flight at a time. */
+  private serialisable = false
 
   /**
    * @param endpoint - the shell's published bridge endpoint.
@@ -53,31 +85,63 @@ 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: Record<string, unknown>, timeoutMs = 20_000): Promise<Record<string, unknown>> {
-    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<Record<string, unknown>>((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)
       }
     })
@@ -94,25 +158,60 @@ 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. */
+  private socketFailed(source: Socket, error: Error): void {
+    if (this.socket !== source) return
+    this.reset(error)
+  }
+
+  /** Resolve queued requests by id, or in order when the bridge does not echo one. */
   private onData(chunk: string): void {
     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()
       this.buffer = this.buffer.slice(newline + 1)
       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) as Record<string, unknown>
         // A rejected token means the shell restarted with a new one, so this socket
@@ -130,6 +229,13 @@ export class BridgeConnection {
     }
   }
 
+  /** Forget one request (its answer can no longer be matched). */
+  private forget(id: number): void {
+    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. */
   private reset(error: Error): void {
     if (this.socket !== undefined) {
@@ -139,7 +245,22 @@ 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: string): number | undefined {
+  try {
+    const answer = JSON.parse(line) as Record<string, unknown>
+    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/src/browser-electron/entry.ts

@@ -22,8 +22,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,
@@ -52,7 +54,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
 }
 
@@ -116,7 +118,11 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       selfHosted.dispose()
       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)})`)
@@ -152,15 +158,29 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
           `the selected ${channel} is not installed — commands will explain how to fix it`)
       }
     } 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'})`)
     }
@@ -170,17 +190,41 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: 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) return
-    adopt(sidebar, 'driving the desktop sidebar browser')
-  }).catch(() => { /* discovery never throws; keep self-hosting */ })
+  // 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: Awaited<ReturnType<typeof DesktopBridgeViewHost.discover>>
+      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
+    }
+  })()
 }
 
 /** 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'
+
 /** The host web-server surface this plugin uses, described structurally. */
 interface WebServerHost {
   readonly webServer: {
@@ -222,28 +266,9 @@ function installSettingsRoute(ctx: Context, settings: SettingsStore): void {
   }
 }
 
-/**
- * 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: IncomingMessage): boolean {
-  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.
@@ -260,11 +285,11 @@ async function handleSettingsRequest(
     })
     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/src/browser-electron/ephemeral-profile.ts

@@ -0,0 +1,152 @@
+/**
+ * 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
+
+/** 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
+}
+
+/**
+ * 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: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).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: string, id: string): string {
+  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: string, pid: number = process.pid, now: number = Date.now()): boolean {
+  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: string): number | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(join(dir, OWNER_FILE), 'utf8')) as { pid?: unknown }
+    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: string, kind: string, options: SweepOptions = {}): string[] {
+  const now = options.now ?? Date.now()
+  const alive = options.alive ?? processAlive
+  const prefix = `${kind}-profile-ephemeral-`
+  const removed: string[] = []
+  let names: string[]
+  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: number
+    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
+}