dsh-inner-browser-use 0.27.0 → 0.34.28

package/sidecar.js

@@ -5,11 +5,29 @@
  * and a page keeps working while the person looks somewhere else. The column
  * shows it as a screencast, so the tab is a viewer, not the browser.
  */
-import { spawn } from 'node:child_process'
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { execFileSync, spawn, spawnSync } from 'node:child_process'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, appendFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
+/**
+ * Windows keeps a browser under Program Files (machine-wide) or LocalAppData
+ * (per-user), and Edge is Chromium too, so it speaks the same DevTools
+ * protocol. Chrome is still preferred: the list is read in order.
+ * @returns {string[]} candidates, most preferred first.
+ */
+function windowsBrowserCandidates() {
+  const roots = [
+    process.env['PROGRAMFILES'],
+    process.env['PROGRAMFILES(X86)'],
+    process.env['LOCALAPPDATA'],
+  ].filter((root) => typeof root === 'string' && root !== '')
+  const out = []
+  for (const root of roots) out.push(join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'))
+  for (const root of roots) out.push(join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'))
+  return out
+}
+
 /** Chrome builds this machine may have, most preferred first. */
 const CHROME_BINARIES = [
   '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
@@ -17,11 +35,15 @@ const CHROME_BINARIES = [
   '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
   '/usr/bin/google-chrome',
   '/usr/bin/chromium',
+  ...(process.platform === 'win32' ? windowsBrowserCandidates() : []),
 ]
 
 /** Viewport the screencast and the pointer share. Nothing here is a user-agent detail. */
 export const VIEW = { width: 1440, height: 900 }
 
+/** What a person's Chrome on this machine sends. */
+export const DESKTOP_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/156.0.0.0 Safari/537.36'
+
 /**
  * Pixels the mirror actually sends. The viewport is never downscaled: a
  * half-size JPEG turns 12px body text into mush in a column this narrow, and
@@ -44,6 +66,12 @@ function firstBinary() {
   return CHROME_BINARIES.find((path) => existsSync(path))
 }
 
+/* A chat's tab address outlives a plugin reload: the browser is still running
+   with that tab, and the chat that returns should get its page back, not a
+   blank one. */
+const tabsDir = process.env.DSH_INNER_BROWSER_STATE_DIR || join(homedir(), '.dsh', 'inner-browser-use')
+const tabsFile = join(tabsDir, 'tabs.json')
+
 /** Root of everything this plugin keeps for the sidecar. */
 function rootDir() {
   const dir = join(homedir(), '.dsh', 'inner-browser-use', 'chrome')
@@ -51,6 +79,177 @@ function rootDir() {
   return dir
 }
 
+/**
+ * Whether a target is not this page's to take: its own tab or one another chat
+ * is driving.
+ * @param {string} targetId - candidate target.
+ * @param {string} mine - the asking page's own target.
+ * @param {string[]} [foreign] - targets other chats drive.
+ * @returns {boolean} true when the candidate must be left alone.
+ */
+export function isForeign(targetId, mine, foreign = []) {
+  const id = String(targetId ?? '')
+  if (id === '') return true
+  if (id === String(mine ?? '')) return true
+  return foreign.map(String).includes(id)
+}
+
+/**
+ * Where the cookies of a profile are kept in the browser's own storage.
+ */
+/**
+ * The topmost process this plugin lives in: the application itself, not the
+ * node instance a reload replaces. A reload changes `process.pid`, so a watcher
+ * keyed to it kills the shared browser the moment the old instance goes — which
+ * is how the mirror went blank after a reload.
+ * @returns {number} the application pid, or 0 when it cannot be walked.
+ */
+function appPid() {
+  let pid = process.pid
+  let top = pid
+  for (let hop = 0; hop < 12; hop += 1) {
+    let parent = 0
+    try {
+      parent = Number(String(execFileSync('ps', ['-o', 'ppid=', '-p', String(pid)], { encoding: 'utf8' })).trim())
+    } catch {
+      break
+    }
+    if (!Number.isInteger(parent) || parent <= 1) break
+    top = parent
+    pid = parent
+  }
+  return top === process.pid ? 0 : top
+}
+
+/**
+ * Whether a process command line is the application itself, rather than the node
+ * instance a reload replaces. A watcher keyed to the node instance would kill
+ * the shared browser on every reload, which is exactly what made the column go
+ * blank; a command line with `--expose-internals` is that instance.
+ * @param {string} command - what `ps -o command=` said.
+ * @returns {boolean} true for the app binary itself.
+ */
+export function looksLikeApp(command) {
+  const line = String(command ?? '')
+  if (line.includes('--expose-internals')) return false
+  return line.includes('.app/Contents/MacOS/')
+}
+
+/**
+ * @param {number} pid - a process.
+ * @returns {string} its command line, or '' when it is gone.
+ */
+function commandOf(pid) {
+  if (!Number.isInteger(pid) || pid <= 1) return ''
+  try {
+    return String(execFileSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' })).trim()
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Whether this run may arm the watcher at all: never on Windows, where the
+ * browser tree ends with the application through `taskkill /T`, and only inside
+ * the application itself, since a note keyed to anything else would close the
+ * shared browser on a plugin reload.
+ * @returns {boolean} true when `handoff()` can write a watcher note.
+ */
+export function canArmWatcher() {
+  if (process.platform === 'win32') return false
+  const app = appPid()
+  return app !== 0 && looksLikeApp(commandOf(app)) === true
+}
+
+/** The watcher that closes the browser when the app goes: one per app run. */
+function watcherFile(dir) {
+  return join(dir, 'watcher.json')
+}
+
+/**
+ * One line describing a browser that went away by itself, so the next person to
+ * look knows whether it was asked to stop, crashed, or was killed from outside.
+ * @param {{pid?: number, code?: number|null, signal?: string|null, profile?: string}} gone - what the child reported.
+ * @returns {string} a line without a newline.
+ */
+export function deathNote(gone) {
+  const at = new Date().toISOString()
+  const code = gone.code === null || gone.code === undefined ? 'none' : String(gone.code)
+  return `${at} browser pid ${String(gone.pid ?? 0)} profile ${String(gone.profile ?? 'default')} exit code ${code} signal ${String(gone.signal ?? 'none')}`
+}
+
+/**
+ * Appends one line to the browser log and never troubles the caller, because a
+ * browser that died while nothing was watching should not also break the call
+ * that noticed.
+ * @param {{pid?: number, code?: number|null, signal?: string|null, profile?: string, asked?: boolean}} gone - what happened.
+ * @param {string} [dir] - where the log lives; the state directory by default.
+ * @returns {void}
+ */
+export function noteDeath(gone, dir = tabsDir) {
+  if (gone.asked === true) return
+  try {
+    mkdirSync(dir, { recursive: true })
+    appendFileSync(join(dir, 'browser.log'), `${deathNote(gone)}\n`)
+  } catch {
+    /* a log is a convenience, not a promise */
+  }
+}
+
+const COOKIE_FILES = ['Default/Cookies', 'Local State']
+
+/**
+ * @param {string} dir - a profile directory.
+ * @returns {string} where its cookie snapshots live.
+ */
+export function loginBackupDir(dir) {
+  // A Windows profile path has no '/', so splitting on it returned the whole
+  // path and the backup landed at `.../login/C:\Users\…` — a mkdir that fails.
+  const last = dir.split(/[\\/]/u).filter(Boolean).pop() ?? 'default'
+  return join(tabsDir, 'login', last)
+}
+
+/**
+ * Copies the cookie store aside while it is still good, so a profile that loses
+ * its cookies another way can be handed the ones that were working.
+ * @param {string} dir - a profile directory.
+ * @returns {number} how many snapshots are kept.
+ */
+export function snapshotLogin(dir) {
+  const files = COOKIE_FILES.map((name) => ({ name, from: join(dir, name) })).filter((row) => existsSync(row.from))
+  if (files.length === 0) return 0
+  const to = loginBackupDir(dir)
+  mkdirSync(to, { recursive: true })
+  const stamp = String(Date.now())
+  for (const row of files) copyFileSync(row.from, join(to, `${stamp}-${row.name.replace(/\//g, '_')}`))
+  const mine = readdirSync(to).filter((name) => name.startsWith(`${stamp}-`))
+  const older = readdirSync(to).filter((name) => !mine.includes(name)).sort()
+  const generations = 5
+  const keep = older.slice(-generations * files.length)
+  for (const name of older) if (!keep.includes(name)) rmSync(join(to, name), { force: true })
+  return older.length + mine.length
+}
+
+/**
+ * Puts the newest snapshot back when the profile has no cookie store at all.
+ * @param {string} dir - a profile directory.
+ * @returns {boolean} whether anything was restored.
+ */
+export function restoreLogin(dir) {
+  const cookie = join(dir, 'Default/Cookies')
+  if (existsSync(cookie) && statSync(cookie).size > 1000) return false
+  const from = loginBackupDir(dir)
+  if (!existsSync(from)) return false
+  const names = readdirSync(from).sort()
+  const newest = names.filter((name) => name.includes('-Default_Cookies')).slice(-1)[0]
+  const state = names.filter((name) => name.includes('-Local_State')).slice(-1)[0]
+  if (newest === undefined) return false
+  mkdirSync(join(dir, 'Default'), { recursive: true })
+  copyFileSync(join(from, newest), cookie)
+  if (state !== undefined) copyFileSync(join(from, state), join(dir, 'Local State'))
+  return true
+}
+
 /** @param {string} name - profile name. @returns {string} its directory. */
 function profileDir(name) {
   const dir = join(rootDir(), String(name || 'default').replace(/[^\w.-]/g, '_'))
@@ -156,6 +355,7 @@ export class SidecarPage {
     this.pointerSinks = new Set()
     this.latest = ''
     this.seq = 0
+    this.lastFrameAt = 0
     /* Total JPEG bytes seen, for the bench and for noticing when a page got
        expensive to watch. */
     this.bytes = 0
@@ -185,6 +385,11 @@ export class SidecarPage {
        follows it, because a person looking at the column expects that too. */
     this.children = new Map()
     this.opened = null
+    /* The tab this page drives, and the tabs other chats drive. A tab another
+       chat owns is never a popup of this one: closing it, or navigating this
+       page to its address, would take a page away from somebody else. */
+    this.targetId = ''
+    this.siblings = () => []
     this.port = Number(port ?? 0) // ui-copy-ignore
   }
 
@@ -307,13 +512,15 @@ export class SidecarPage {
    * one exists and where it went.
    * @returns {Promise<{targetId: string, url: string}|null>} the popup.
    */
-  async findPopup() {
+  async findPopup(foreign = []) {
     if (this.port <= 0) return null // ui-copy-ignore
-    const main = await this.cdp.send('Target.getTargetInfo').then((info) => String(info?.targetInfo?.targetId ?? '')).catch(() => '')
+    const mine = await this.cdp.send('Target.getTargetInfo').then((info) => String(info?.targetInfo?.targetId ?? '')).catch(() => '')
+    const main = mine !== '' ? mine : this.targetId
+    const theirs = new Set(foreign.map(String))
     const list = await fetch(`http://127.0.0.1:${this.port}/json/list`, { signal: AbortSignal.timeout(1200) }) // ui-copy-ignore
       .then((response) => (response.ok ? response.json() : []))
       .catch(() => [])
-    const pages = (Array.isArray(list) ? list : []).filter((item) => item.type === 'page' && String(item.id ?? '') !== main)
+    const pages = (Array.isArray(list) ? list : []).filter((item) => item.type === 'page' && String(item.id ?? '') !== main && !theirs.has(String(item.id ?? '')))
     const popup = pages.find((item) => /^https?:|^file:/.test(String(item.url ?? '')))
     if (popup !== undefined) return { targetId: String(popup.id), url: String(popup.url) }
     const blank = pages[0]
@@ -343,14 +550,17 @@ export class SidecarPage {
    * @returns {Promise<string>} what happened, for the tool result.
    */
   async adoptOpened() {
+    const foreign = typeof this.siblings === 'function' ? this.siblings().map(String) : []
+    const theirs = new Set(foreign)
     let target = this.opened === null || this.opened === undefined ? null : { targetId: this.opened.targetId, url: this.opened.url }
     this.opened = null
+    if (target !== null && isForeign(target.targetId, this.targetId, foreign)) target = null
     if (target === null) {
       /* The target list is written before the popup finished loading, so give a
          click that opens one a moment to say where it is going. */
       for (let attempt = 0; attempt < 3 && target === null; attempt += 1) {
         if (attempt > 0) await new Promise((resolve) => setTimeout(resolve, 150))
-        const found = await this.findPopup()
+        const found = await this.findPopup(foreign)
         if (found !== null && found.url !== '') target = found
         else if (found !== null && attempt === 2) target = found
       }
@@ -456,16 +666,14 @@ export class SidecarPage {
 
   /** Keep one listener that fans frames out to every viewer. */
   async start() {
-    await this.cdp.send('Network.enable').catch(() => {})
+    this.targetId = String(
+      await this.cdp.send('Target.getTargetInfo').then((info) => info?.targetInfo?.targetId ?? '').catch(() => ''),
+    )
     /* A click that downloads should leave a file, not nothing: point downloads
        at the profile so the driver can report where they went. */
     const folder = downloadsDir(profileDir(this.profile))
     mkdirSync(folder, { recursive: true })
     this.downloadsFolder = folder
-    await this.cdp.send('Browser.setDownloadBehavior', { behavior: 'allow', downloadPath: folder }).catch(() => {})
-    /* Popups and out-of-process frames are separate targets. Attaching without
-       waiting keeps them usable, and lets the mirror follow a new tab. */
-    await this.cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true }).catch(() => {})
     this.cdp.on((message) => {
       this.watch(message)
       if (message.method !== 'Page.screencastFrame') return
@@ -473,6 +681,7 @@ export class SidecarPage {
       void this.cdp.send('Page.screencastFrameAck', { sessionId }).catch(() => {})
       if (typeof data !== 'string' || data === '') return
       this.latest = data
+      this.lastFrameAt = Date.now()
       this.seq += 1
       this.bytes += data.length
       if (metadata?.timestamp !== undefined && metadata.timestamp * 1000 < this.touched - 60_000) return
@@ -503,23 +712,39 @@ export class SidecarPage {
       }
       if (message.method === 'Page.loadEventFired') void this.readTitle()
     })
-    await this.cdp.send('Page.enable')
+    /* None of these settings depends on another: asking for all of them at
+       once is one round trip instead of four, and a cold start is where it
+       shows. */
+    await Promise.all([
+      this.cdp.send('Page.enable'),
+      this.cdp.send('Network.enable').catch(() => {}),
+      this.cdp.send('Browser.setDownloadBehavior', { behavior: 'allow', downloadPath: folder }).catch(() => {}),
+      /* Popups and out-of-process frames are separate targets. Attaching without
+         waiting keeps them usable, and lets the mirror follow a new tab. */
+      this.cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: true, flatten: true }).catch(() => {}),
+    ])
     /* An instance left behind by a stopped app can still be sitting on a
        dialog; a paused renderer answers nothing, so clear it first. */
     await Promise.race([
       this.cdp.send('Page.handleJavaScriptDialog', { accept: false }).catch(() => {}),
       new Promise((resolve) => setTimeout(resolve, 800)),
     ])
-    await this.cdp.send('Runtime.enable')
-    await this.cdp.send('Emulation.setDeviceMetricsOverride', {
-      width: VIEW.width, // ui-copy-ignore
-      height: VIEW.height, // ui-copy-ignore
-      deviceScaleFactor: 1,
-      mobile: false, // ui-copy-ignore
-    })
+    /* The metrics and the version string are independent too: the UA override
+       only needs the version, not a turn of its own. */
+    const [, version] = await Promise.all([
+      this.cdp.send('Runtime.enable').then(() =>
+        this.cdp.send('Emulation.setDeviceMetricsOverride', {
+          width: VIEW.width, // ui-copy-ignore
+          height: VIEW.height, // ui-copy-ignore
+          deviceScaleFactor: 1,
+          mobile: false, // ui-copy-ignore
+        }),
+      ),
+      this.cdp.send('Browser.getVersion').catch(() => ({ product: '' })),
+    ])
     /* A headless build announces itself in the UA, and some sites refuse that
        string outright. The page is a normal Chrome here, so it says so. */
-    const { product } = await this.cdp.send('Browser.getVersion').catch(() => ({ product: '' }))
+    const product = String(version?.product ?? '')
     if (String(product).includes('HeadlessChrome')) {
       const version = String(product).replace(/.*HeadlessChrome\//, '')
       await this.cdp.send('Emulation.setUserAgentOverride', {
@@ -550,7 +775,12 @@ export class SidecarPage {
 
   /** @returns {Promise<void>} resolves once the page is casting. */
   async cast() {
-    if (this.casting) return
+    if (this.casting) {
+      /* A page nobody repaints still owes the pane a picture, so silence for a
+         few seconds means the cast died rather than being idle. */
+      if (Date.now() - this.lastFrameAt < 3000) return
+      this.casting = false
+    }
     this.casting = true
     /* Full-resolution mirror at a quality that keeps small text readable;
        `optimizeForSpeed` keeps the encoder from adding to the round trip. */
@@ -564,6 +794,38 @@ export class SidecarPage {
     }).catch(() => {
       this.casting = false
     })
+    void this.still()
+  }
+
+  /** Sends one full-frame picture now: a mirror that waits for motion shows an empty pane on a page that is not moving. */
+  async still() {
+    let data = ''
+    try {
+      const shot = await this.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 72, fromSurface: true })
+      data = String(shot?.data ?? '')
+    } catch {
+      return
+    }
+    if (data === '' || this.frames.size === 0) return
+    this.latest = data
+    this.lastFrameAt = Date.now()
+    this.seq += 1
+    const frame = {
+      seq: this.seq, // ui-copy-ignore
+      w: VIEW.width, // ui-copy-ignore
+      h: VIEW.height, // ui-copy-ignore
+      jpeg: data, // ui-copy-ignore
+      url: this.url, // ui-copy-ignore
+      title: this.title, // ui-copy-ignore
+      pointer: this.pointer, // ui-copy-ignore
+    }
+    for (const sink of this.frames) {
+      try {
+        sink(frame)
+      } catch {
+        /* a closed viewer is dropped by its own stream handler */
+      }
+    }
   }
 
   async stopCast() {
@@ -580,12 +842,34 @@ export class SidecarPage {
     this.touched = Date.now()
     this.lastUrl = String(url)
     await this.cdp.send('Page.navigate', { url })
+    /* A blank page is where the wait ends, not a place still to arrive: asking
+       for about:blank and then waiting for a non-blank address spent the whole
+       20 s budget, which is how a brand-new chat's first tab took forever. */
+    if (String(url) === '' || String(url) === 'about:blank') {
+      await wait(80)
+      await this.readTitle()
+      return { url: this.url, title: this.title }
+    }
     for (let i = 0; i < 200; i += 1) {
       await wait(100)
       await this.readTitle()
       if (this.url !== '' && this.url !== 'about:blank') break
     }
-    return { url: this.url, title: this.title }
+    /* A brand-new browser sometimes answers the very first navigation with its
+       own error page: the network stack is still coming up. One reload of that
+       address is the difference between the chat seeing the site and the chat
+       seeing a browser error in the mirror. */
+    if (this.url.startsWith('chrome-error://')) {
+      await wait(300)
+      await this.cdp.send('Page.reload', {}).catch(() => {})
+      for (let i = 0; i < 80; i += 1) {
+        await wait(100)
+        await this.readTitle()
+        if (this.url !== '' && !this.url.startsWith('chrome-error://') && this.url !== 'about:blank') break
+      }
+    }
+    const bad = this.url.startsWith('chrome-error://') ? 'the page did not load' : ''
+    return bad === '' ? { url: this.url, title: this.title } : { url: this.url, title: this.title, bad }
   }
 
   /**
@@ -749,6 +1033,56 @@ export class SidecarPage {
     })
   }
 
+  /**
+   * Type the way a person does: one character at a time, uneven gaps, a longer
+   * pause where a person would think, and no clipboard paste at all. Paste is
+   * the single event that tells a site a machine filled the box; per-character
+   * key events do not. Longer messages are typed in small bursts so a whole
+   * page of text does not take a minute.
+   * @param {string} text - any unicode, including Chinese.
+   * @param {{burst?: number, min?: number, max?: number}} [options] - pacing.
+   * @returns {Promise<void>} resolves once the last character was accepted.
+   */
+  async humanType(text, options = {}) {
+    this.touched = Date.now()
+    const chars = Array.from(String(text))
+    /* A long message is typed faster per burst: the opening still looks like
+       fingers, but nobody wants to wait fifteen seconds for a paragraph. */
+    const long = chars.length > 160
+    const burst = Math.max(1, Number(options.burst ?? (long ? 8 : 3)))
+    const min = Number(options.min ?? (long ? 10 : 26))
+    const max = Math.max(min + 1, Number(options.max ?? (long ? 46 : 110)))
+    const gap = () => min + Math.random() * (max - min)
+    let at = 0
+    while (at < chars.length) {
+      const size = at < 12 ? 1 : burst
+      const chunk = chars.slice(at, at + size).join('')
+      /* One key event per character is what a keyboard produces. A multi-letter
+         key event would only deliver its first letter, so a run of Latin text
+         is pressed key by key; a run of Chinese arrives as an input-method
+         commit, which is one event for a whole phrase. */
+      if (size > 1 && /[\u3040-\u9fff\uac00-\ud7af]/.test(chunk)) {
+        await this.input('Input.insertText', { text: chunk })
+      } else {
+        for (const one of Array.from(chunk)) {
+          await this.input('Input.dispatchKeyEvent', {
+            type: 'keyDown', // ui-copy-ignore
+            key: one, // ui-copy-ignore
+            text: one, // ui-copy-ignore
+            unmodifiedText: one, // ui-copy-ignore
+            windowsVirtualKeyCode: 0,
+            nativeVirtualKeyCode: 0,
+          }).catch(() => {})
+        }
+      }
+      at += size
+      const last = chars[at - 1] ?? ''
+      /* Stop longer after a full stop or a comma, the way a person does. */
+      const pause = /[。！？，、；：\n.,!?;:]/.test(last) ? gap() * 2.2 + 90 : gap()
+      await wait(at < chars.length ? pause : 0)
+    }
+  }
+
   /** @param {string} text - any unicode, including Chinese. @returns {Promise<void>} resolves when typed. */
   async insertText(text) {
     this.touched = Date.now()
@@ -900,8 +1234,15 @@ export class Sidecar {
   constructor(options = {}) {
     this.logger = options.logger
     this.child = null
+    this.stopping = false
     this.cdp = null
     this.page = null
+    /* One tab per chat: a second chat opening an address gets a tab of its
+       own, so neither can navigate the other's page away. */
+    this.pages = new Map()
+    /* A tab being opened for a chat: a second call for the same chat waits for
+       it instead of opening a twin. */
+    this.opening = new Map()
     /* A measurement or a test may want a profile of its own; the person's
        browser keeps the default one. */
     this.profile = String(options.profile ?? 'default')
@@ -971,10 +1312,159 @@ export class Sidecar {
   }
 
   /**
-   * @param {{profile?: string, headless?: boolean, url?: string}} [options] - how to start.
+   * The tab a chat drives. A named chat gets a tab of its own, made once and
+   * kept; an unnamed caller (a test, a screenshot script) drives the first tab.
+   * @param {string} session - chat id, empty for the default tab.
+   * @returns {SidecarPage | null} the tab, if the browser is up.
+   */
+  pageFor(session) {
+    const id = String(session ?? '')
+    if (id === '') return this.page
+    const mine = this.pages.get(id)
+    if (mine !== undefined && mine.cdp?.closed !== true) return mine
+    if (mine !== undefined) this.pages.delete(id)
+    return null
+  }
+
+  /**
+   * Keep a chat's tab address on disk, so a reload can bring the page back.
+   * @param {string} session - chat id.
+   * @param {string} url - address that chat's tab is showing.
+   */
+  rememberTab(session, url) {
+    const id = String(session ?? '')
+    const address = String(url ?? '')
+    /* Only chats, and only addresses: a stray key from a probe or an older run
+       must not sit in this file pretending to be a chat that can be restored. */
+    if (!/^session-/.test(id) || address === '' || address === 'about:blank') return
+    let saved = {}
+    try {
+      saved = JSON.parse(readFileSync(tabsFile, 'utf8')) ?? {}
+    } catch {
+      saved = {}
+    }
+    if (saved[id] === address) return
+    saved[id] = address
+    try {
+      mkdirSync(tabsDir, { recursive: true })
+      writeFileSync(tabsFile, JSON.stringify(saved))
+    } catch {
+      /* a browser that cannot write its note still works */
+    }
+  }
+
+  /**
+   * @param {string} session - a chat id.
+   * @returns {string} the address that chat last had, or '' when it never had one.
+   */
+  rememberedTab(session) {
+    const id = String(session ?? '')
+    if (!/^session-/.test(id)) return ''
+    try {
+      const saved = JSON.parse(readFileSync(tabsFile, 'utf8'))
+      return String(saved?.[id] ?? '')
+    } catch {
+      return ''
+    }
+  }
+
+  /**
+   * Give a chat its own tab, on the same browser: logins are shared, addresses
+   * are not.
+   * @param {string} session - chat id.
+   * @param {string} [url] - address to open in it.
+   * @returns {Promise<SidecarPage>} its tab.
+   */
+  async tabFor(session, url) {
+    const id = String(session ?? '')
+    const had = this.pageFor(id)
+    if (had !== null) {
+      if (url !== undefined && url !== '') await had.navigate(url)
+      return had
+    }
+    /* Two calls that start together are one chat, and a chat has one tab: the
+       second waits for the first tab instead of opening a twin nobody holds. */
+    const underway = this.opening?.get(id)
+    if (underway !== undefined) {
+      const page = await underway
+      const want = String(url ?? '')
+      if (want !== '' && String(page.url ?? '') !== want) await page.navigate(want)
+      return page
+    }
+    const work = this.openTab(id, url).finally(() => {
+      this.opening?.delete(id)
+    })
+    this.opening?.set(id, work)
+    return work
+  }
+
+  /**
+   * @param {string} id - chat id.
+   * @param {string} [url] - address to open in it.
+   * @returns {Promise<SidecarPage>} a new tab for that chat.
+   */
+  async openTab(id, url) {
+    const had = this.pageFor(id)
+    if (had !== null) {
+      if (url !== undefined && url !== '') await had.navigate(url)
+      return had
+    }
+    if (this.page === null) await this.ensure()
+    const port = this.page?.port ?? 0 // ui-copy-ignore
+    if (port === 0) throw new Error('sidecar: no browser to open a tab in') // ui-copy-ignore
+    /* A chat that was given a tab without an address keeps looking at what the
+       browser was already showing, rather than at a blank page nobody asked for. */
+    const remembered = this.rememberedTab(id)
+    const address = url === undefined || url === '' ? String(remembered !== '' ? remembered : this.page?.lastUrl ?? this.lastUrl ?? 'about:blank') : String(url)
+    const created = await fetch(`http://127.0.0.1:${port}/json/new?${encodeURIComponent(address)}`, { method: 'PUT', signal: AbortSignal.timeout(3000) }) // ui-copy-ignore
+    if (!created.ok) throw new Error('sidecar: could not open a tab')
+    const target = await created.json()
+    if (typeof target.webSocketDebuggerUrl !== 'string') throw new Error('sidecar: new tab has no socket')
+    const cdp = new Cdp(target.webSocketDebuggerUrl)
+    await cdp.ready
+    const page = await this.bind(await new SidecarPage(cdp, this.profile, port).start()) // ui-copy-ignore
+    this.pages.set(id, page)
+    this.touch()
+    this.rememberTab(id, address)
+    return page
+  }
+
+  /**
+   * @param {{profile?: string, headless?: boolean, url?: string, session?: string}} [options] - how to start.
    * @returns {Promise<SidecarPage>} the page being driven.
    */
   async ensure(options = {}) {
+    const page = await this.ensurePage(options)
+    const id = String(options.session ?? '')
+    if (id === '') return page
+    const mine = this.pageFor(id)
+    if (mine !== null) {
+      /* A chat's tab can die on its own: a crash, a browser another call
+         restarted, a tab closed by hand. Handing that corpse back leaves the
+         mirror on a blank picture forever, so it has to answer before it is
+         trusted again. */
+      const alive = await mine.ping()
+      if (alive.ok) {
+        /* A blank tab after a restart is not where this chat was: the address it
+           last had is on disk, and that is the one worth returning to. */
+        if (String(mine.url ?? '') === 'about:blank') {
+          const back = this.rememberedTab(id)
+          if (back !== '') await mine.navigate(back)
+        }
+        const wanted = String(options.url ?? '')
+        if (wanted !== '' && String(mine.url) !== wanted) await mine.navigate(wanted)
+        this.rememberTab(id, String(mine.url ?? wanted))
+        return mine
+      }
+      this.pages.delete(id)
+      return this.tabFor(id, options.url === undefined || options.url === '' ? this.rememberedTab(id) : options.url)
+    }
+    /* A new tab for a chat that had one before opens where that chat was: a
+       blank mirror is not a place, and the first call should not land on one. */
+    return this.tabFor(id, options.url === undefined || options.url === '' ? this.rememberedTab(id) : options.url)
+  }
+
+  async ensurePage(options = {}) {
     if (options.profile !== undefined) this.profile = options.profile
     const wanted = options.headless === undefined ? this.headless : options.headless !== false
     const modeChanged = wanted !== this.headless
@@ -1011,6 +1501,12 @@ export class Sidecar {
         }
       }
       this.touch()
+      const id = String(options.session ?? '')
+      if (id !== '') {
+        /* Another chat may be looking at another tab: this one gets its own. */
+        const mine = await this.tabFor(id, options.url)
+        return mine
+      }
       if (options.url !== undefined && options.url !== '') await this.page.navigate(options.url)
       return this.page
     }
@@ -1038,18 +1534,28 @@ export class Sidecar {
   /** @param {string | undefined} url - first address. @returns {Promise<SidecarPage>} the page. */
   async launch(url) {
     const dir = profileDir(this.profile)
+    /* A profile whose cookie store went missing would look signed out at the
+       next step even though the person never signed out, so the working copy
+       is put back before the browser is asked to read it. */
+    restoreLogin(dir)
     let port = await this.runningPort(dir) // ui-copy-ignore
     if (port === 0) port = await this.spawnChrome(dir) // ui-copy-ignore
     const ws = await this.pageSocket(port) // ui-copy-ignore
     const cdp = new Cdp(ws)
     await cdp.ready
     this.cdp = cdp
-    this.page = await new SidecarPage(cdp, this.profile, port).start() // ui-copy-ignore
+    this.page = await this.bind(await new SidecarPage(cdp, this.profile, port).start()) // ui-copy-ignore
     if (url !== undefined && url !== '') this.lastUrl = String(url)
     await this.restoreSessionCookies()
     await this.page.cast()
     if (url !== undefined && url !== '') await this.page.navigate(url)
     this.touch()
+    /* Sign-ins outlive this browser: what works now is worth a copy, taken
+       while the cookies are known good rather than after they are lost. */
+    snapshotLogin(dir)
+    this.backup?.()
+    this.backup = setInterval(() => snapshotLogin(dir), 10 * 60_000)
+    this.backup.unref?.()
     this.logger?.info?.('dsh-inner-browser-use: sidecar up on port %s (%s)', port, this.headless ? 'headless' : 'windowed') // ui-copy-ignore
     return this.page
   }
@@ -1113,11 +1619,25 @@ export class Sidecar {
       '--password-store=basic',
       '--lang=zh-CN',
       `--window-size=${VIEW.width},${VIEW.height}`,
+      /* A windowless build says "HeadlessChrome" in every request, and a site
+         that checks for it answers the whole browser with a parked page. The
+         browser is windowless, not a robot: say what a person's Chrome says. */
+      `--user-agent=${DESKTOP_UA}`,
+      /* A site that refuses a headless build still gets a window, but never on
+         the desktop: the mirror in the column is the only thing to look at. */
+      '--window-position=-3000,-3000',
       'about:blank',
     ]
     if (this.headless) args.unshift('--headless=new')
+    /* A browser started again after a stop is a new one: its death is news
+       again, and the flag left behind by the stop must not silence it. */
+    this.stopping = false
     const child = spawn(binary, args, { detached: false, stdio: 'ignore' })
-    child.on('exit', () => {
+    const born = Date.now()
+    child.on('exit', (code, signal) => {
+      /* A browser that ends without being asked is the one case nobody can see:
+         Chrome's own stderr goes nowhere, so leave a line behind. */
+      noteDeath({ pid: child.pid, code, signal, profile: this.profile, asked: this.stopping === true || Date.now() - born < 3000 })
       if (this.child === child) {
         this.child = null
         this.cdp?.close()
@@ -1149,8 +1669,9 @@ export class Sidecar {
    * The browser's pages, in the order the browser lists them.
    * @returns {Promise<Array<{targetId: string, title: string, url: string, current: boolean}>>} the tabs.
    */
-  async tabs() {
-    return this.page === null ? [] : this.page.tabs()
+  async tabs(session = '') {
+    const page = this.pageFor(session) ?? this.page
+    return page === null ? [] : page.tabs()
   }
 
   /**
@@ -1158,15 +1679,47 @@ export class Sidecar {
    * @param {number} index - a row from `tabs()`.
    * @returns {Promise<SidecarPage>} the page now being driven.
    */
-  async useTab(index) {
-    const list = await this.tabs()
+  /**
+   * Tells a page which targets belong to other chats, so a popup lookup cannot
+   * pick somebody else's tab.
+   * @param {SidecarPage} page - a page this browser drives.
+   * @returns {SidecarPage} the same page.
+   */
+  bind(page) {
+    page.siblings = () =>
+      [...this.pages.values(), this.page]
+        .filter((other) => other !== null && other !== undefined && other !== page)
+        .map((other) => String(other.targetId ?? ''))
+        .filter((id) => id !== '')
+    return page
+  }
+
+  async useTab(index, session = '') {
+    const list = await this.tabs(session)
     const tab = list[Number(index)]
     if (tab === undefined) throw new Error(`sidecar: no tab ${String(index)}`)
+    const owned = String(session ?? '') !== ''
+    const mine = owned ? this.pageFor(session) : null
+    if (tab.current && mine !== null) return mine
+    if (tab.current && !owned) return this.page
     if (tab.current) return this.page
-    const was = this.page
+    const was = mine ?? this.page
+    /* A chat that owns a tab keeps owning one: switching moves the chat, not
+       the browser's first tab that a different chat may be driving. */
+    if (mine !== null) {
+      const cdp = new Cdp(tab.webSocketUrl)
+      await cdp.ready
+      const page = await this.bind(await new SidecarPage(cdp, this.profile, mine.port).start()) // ui-copy-ignore
+      this.pages.set(String(session), page)
+      mine.cdp.send('Page.stopScreencast').catch(() => {})
+      mine.cdp.close()
+      await page.cast()
+      this.touch()
+      return page
+    }
     const cdp = new Cdp(tab.webSocketUrl)
     await cdp.ready
-    const page = await new SidecarPage(cdp, this.profile, was.port).start() // ui-copy-ignore
+    const page = await this.bind(await new SidecarPage(cdp, this.profile, was.port).start()) // ui-copy-ignore
     this.cdp = cdp
     this.page = page
     this.lastUrl = tab.url
@@ -1181,18 +1734,25 @@ export class Sidecar {
    * Close a tab; the mirror moves to a neighbour when the closed one was shown.
    * @param {number} index - a row from `tabs()`.
    */
-  async closeTab(index) {
-    const list = await this.tabs()
+  async closeTab(index, session = '') {
+    const list = await this.tabs(session)
     const tab = list[Number(index)]
     if (tab === undefined) throw new Error(`sidecar: no tab ${String(index)}`)
-    let port = this.page?.port ?? 0 // ui-copy-ignore
+    const mine = String(session ?? '') === '' ? null : this.pageFor(session)
+    let port = (mine ?? this.page)?.port ?? 0 // ui-copy-ignore
     let alone = true
     if (tab.current) {
       const other = list.findIndex((item) => !item.current)
       alone = other < 0
-      if (!alone) await this.useTab(other)
+      if (!alone) await this.useTab(other, session)
     }
     if (port > 0) await fetch(`http://127.0.0.1:${port}/json/close/${tab.targetId}`, { signal: AbortSignal.timeout(1000) }).catch(() => {}) // ui-copy-ignore
+    if (alone && mine !== null) {
+      /* The chat still needs somewhere to go: a fresh tab in the same browser. */
+      this.pages.delete(String(session))
+      await this.tabFor(String(session), 'about:blank')
+      return
+    }
     if (alone) {
       await this.shutdown()
       await this.ensure()
@@ -1210,7 +1770,7 @@ export class Sidecar {
     const cdp = new Cdp(target.webSocketDebuggerUrl)
     await cdp.ready
     this.cdp = cdp
-    this.page = await new SidecarPage(cdp, this.profile, port).start() // ui-copy-ignore
+    this.page = await this.bind(await new SidecarPage(cdp, this.profile, port).start()) // ui-copy-ignore
     await this.page.cast()
     this.touch()
     return this.page
@@ -1241,8 +1801,8 @@ export class Sidecar {
    * @param {(frame: any) => void} sink - called per frame.
    * @returns {Promise<() => void>} detach.
    */
-  async watch(sink) {
-    const page = await this.ensure()
+  async watch(sink, session = '') {
+    const page = await this.ensure({ session })
     page.frames.add(sink)
     page.pointerSinks.add(sink)
     await page.cast()
@@ -1259,7 +1819,9 @@ export class Sidecar {
       this.idle = null
       /* Someone is watching the mirror: the page stays up, and the clock starts
          again so the browser is closed only once it is truly unused. */
-      if ((this.page?.frames.size ?? 0) > 0) {
+      let watched = this.page?.frames.size ?? 0
+      for (const page of this.pages.values()) watched += page.frames?.size ?? 0
+      if (watched > 0) {
         this.touch()
         return
       }
@@ -1269,20 +1831,104 @@ export class Sidecar {
   }
 
   /** @returns {Promise<void>} resolves once Chrome is gone. */
+  /**
+   * Leaves the browser running for whoever loads this plugin next, and puts the
+   * sign-in on disk first. A plugin reload used to close Chrome, so the column
+   * lost the page and every sign-in paid for a fresh launch; the browser is
+   * meant to outlive the driver. A detached watcher closes the browser once
+   * this app is really gone, so nothing is left behind.
+   * @returns {Promise<void>} done, with the browser still up.
+   */
+  async handoff() {
+    this.stopping = true
+    if (this.page !== null) await this.saveSessionCookies()
+    if (this.backup !== undefined) clearInterval(this.backup)
+    this.backup = undefined
+    try {
+      snapshotLogin(profileDir(this.profile))
+    } catch {
+      /* a profile that cannot be copied is not a reason to drop the browser */
+    }
+    const chrome = Number(this.child?.pid ?? 0)
+    if (chrome === 0) return
+    /* One watcher per application run, watching the application rather than
+       this instance: a plugin reload is not the app closing. */
+    /* Read at call time, so a test can point the note somewhere harmless. */
+    const dir = process.env.DSH_INNER_BROWSER_STATE_DIR || tabsDir
+    const app = appPid()
+    /* A watcher may only watch the application: one keyed to the node instance
+       a reload replaces closes the browser at that reload. When the walk cannot
+       name the app, no watcher is armed at all rather than a wrong one. */
+    if (app === 0 || looksLikeApp(commandOf(app)) === false) return
+    try {
+      const said = JSON.parse(readFileSync(watcherFile(dir), 'utf8'))
+      const watching = Number(said?.appPid ?? 0)
+      const alive = (() => {
+        try {
+          process.kill(Number(said?.pid ?? 0), 0)
+          return true
+        } catch {
+          return false
+        }
+      })()
+      /* Same run and same browser: the watcher already covers it. A browser
+         that was restarted needs the note pointed at the new pid, or the app
+         going away would leave the new one running. */
+      if (alive && Number(said?.chrome ?? 0) === chrome && watching === Number(said?.appPid) && (app === 0 || watching === app)) return
+      if (alive) {
+        try {
+          process.kill(Number(said?.pid ?? 0))
+        } catch {
+          /* a watcher that already left needs no goodbye */
+        }
+      }
+    } catch {
+      /* no watcher yet, or one whose note is unreadable */
+    }
+    /* Detached and unref'd: the app must not wait for this, and it must outlive
+       the plugin instance it was started for. Windows has no `/bin/sh`, so there
+       the lifetime rides on the browser itself: `taskkill /T` already ends the
+       whole tree when this process is gone, and spawning a POSIX watcher here
+       would only throw ENOENT and be swallowed. */
+    if (process.platform === 'win32') return
+    try {
+      const guard = spawn('/bin/sh', ['-c', `while kill -0 ${app} 2>/dev/null; do sleep 5; done; kill ${chrome} 2>/dev/null`], {
+        detached: true,
+        stdio: 'ignore',
+      })
+      guard.unref()
+      mkdirSync(dir, { recursive: true })
+      writeFileSync(watcherFile(dir), JSON.stringify({ appPid: app, pid: guard.pid ?? 0, chrome, at: Date.now() }))
+    } catch {
+      /* a watcher that cannot start only means the browser outlives the app */
+    }
+  }
+
   async shutdown() {
     /* Ask Chrome to close first: a browser that is killed outright may lose the
        last minute of cookies, and keeping the person signed in is the point. */
     if (this.page !== null) await this.saveSessionCookies()
+    if (this.backup !== undefined) clearInterval(this.backup)
+    this.backup = undefined
+    snapshotLogin(profileDir(this.profile))
     if (this.cdp !== null) {
       await this.cdp.send('Browser.close').catch(() => {})
       await new Promise((resolve) => setTimeout(resolve, 400))
     }
     this.page = null
+    this.pages.clear()
     this.cdp?.close()
     this.cdp = null
     if (this.child !== null) {
       try {
-        this.child.kill('SIGTERM')
+        /* A browser on Windows is a process tree: terminating the launcher alone
+           leaves renderers and the profile lock behind. Browser.close above is
+           the graceful path; this is the one for a browser that ignored it. */
+        if (process.platform === 'win32' && Number.isInteger(this.child.pid)) {
+          spawnSync('taskkill', ['/pid', String(this.child.pid), '/T', '/F'], { stdio: 'ignore' })
+        } else {
+          this.child.kill('SIGTERM')
+        }
       } catch {
         /* already gone */
       }
@@ -1319,9 +1965,20 @@ export class Sidecar {
       return
     }
     if (!Array.isArray(jar)) return
+    /* A cookie the browser already holds is newer than the note: the site may
+       have rotated its session id since the note was written, and putting the
+       old value back is exactly how a working sign-in turns into a logout. */
+    let live = []
+    try {
+      live = await this.page.cookies()
+    } catch {
+      live = []
+    }
+    const held = new Set(live.map((c) => `${String(c.domain ?? '').replace(/^\./, '')}|${String(c.path ?? '/')}|${String(c.name ?? '')}`))
     for (const cookie of jar.slice(0, 200)) {
       const domain = String(cookie?.domain ?? '').replace(/^\./, '')
       if (domain === '') continue
+      if (held.has(`${domain}|${String(cookie?.path ?? '/')}|${String(cookie.name)}`)) continue
       try {
         await this.page.setCookie({
           name: String(cookie.name),
@@ -1339,6 +1996,22 @@ export class Sidecar {
   }
 
   /** @returns {Promise<Record<string, unknown>>} what the sidecar is doing. */
+  /**
+   * What the browser holds for one chat, when the caller names it.
+   * @param {string} [session] - chat id.
+   * @returns {{url: string, title: string, viewers: number, alive: boolean, remembered: string}} its page.
+   */
+  async chatState(session = '') {
+    const id = String(session ?? '')
+    /* A chat whose tab is gone still knows where it was: that address is what
+       the pane offers to bring back, so a lost picture is one click, not a
+       question about which site it used to be. */
+    const remembered = this.rememberedTab(id)
+    const page = id === '' ? null : this.pageFor(id)
+    if (page === null || page === undefined) return { url: '', title: '', viewers: 0, alive: false, remembered } // ui-copy-ignore
+    return { url: String(page.url ?? ''), title: String(page.title ?? ''), viewers: page.frames?.size ?? 0, alive: true, remembered } // ui-copy-ignore
+  }
+
   async state() {
     const profiles = (() => {
       try {
@@ -1352,8 +2025,12 @@ export class Sidecar {
       profile: this.profile, // ui-copy-ignore
       headless: this.headless, // ui-copy-ignore
       url: this.page?.url ?? '', // ui-copy-ignore
+      pages: this.pages.size,
       title: this.page?.title ?? '',
       viewers: this.page?.frames.size ?? 0,
+      /* Everyone watching any chat's picture: the pane in the right column is
+         one of these, so 0 means no column is attached right now. */
+      watchers: [...this.pages.values()].reduce((sum, page) => sum + (page.frames?.size ?? 0), 0),
       frames: this.page?.seq ?? 0,
       crashed: this.page?.crashed === true,
       pointer: this.page?.pointer ?? null,