@operatingtag/dsh-unclesam 0.0.0-stage → 1.0.0

package/lib/engine.mjs

@@ -0,0 +1,1412 @@
+/**
+ * The engine: turn "a prompt" into "a streamed reply" using chat.deepseek.com in a real browser.
+ *
+ * @file    engine.mjs
+ * @version 3.9.11
+ * @author  Operating Tag (@operatingtag)
+ * @license CC-BY-NC-ND-4.0
+ *
+ * THE ONE DECISION THIS FILE ENCODES
+ *     The site requires a proof-of-work challenge per message and is fronted by Cloudflare Turnstile.
+ *     Re-implementing those outside the page is a losing game: they change, they are obfuscated, and
+ *     getting them wrong looks exactly like a network failure. So this engine never touches the API.
+ *     It drives the page, and the page solves its own challenges the same way it does for a person.
+ *     The cost is a DOM read every poll; the gain is that auth, PoW and Turnstile are simply not our
+ *     problem and cannot break independently of the site itself.
+ *
+ * WHY EVERY CALL STARTS A NEW CHAT
+ *     DSH sends the full conversation in `messages` on every call, because a provider is expected to be
+ *     stateless. If this engine reused the open chat, the page would also keep its own history and the
+ *     model would see every turn twice, growing on each call until the request was absurd. A fresh chat
+ *     per call keeps the two models of state agreeing.
+ *
+ * WHY COMPLETION IS DETECTED BY STABILITY, NOT BY A BUTTON
+ *     The generating state is indicated by a control whose class names are generated and change on
+ *     deploy. Text that has stopped growing for a couple of seconds is a much more durable signal, and
+ *     it degrades gracefully: a slow stream just takes longer to settle rather than hanging forever.
+ */
+
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, appendFileSync } from 'node:fs';
+import { Cdp, waitFor } from './cdp.mjs';
+
+const BRAVE_PATHS = [
+  'C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
+  'C:\\Program Files (x86)\\BraveSoftware\\Brave-Browser\\Application\\brave.exe',
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+];
+
+const CHAT_URL = 'https://chat.deepseek.com/';
+const ASSISTANT = '.ds-assistant-message-main-content';
+
+/**
+ * How long the reply text must stop changing before it counts as finished.
+ *
+ * This is pure added latency: every reply pays it in full, after the last character has already arrived.
+ * The page offers no trustworthy "still generating" marker to read instead - a probe of the live document
+ * found the candidate classes flipping at the wrong moment - so silence is the only signal available.
+ *
+ * The tension is real: shorter means faster, but a mid-reply pause longer than the window would cut an
+ * answer in half, which is far worse than waiting. 600 ms is short enough to feel immediate and long
+ * enough to absorb the stream's normal gaps, and the reply loop polls at 70 ms so the window is measured
+ * accurately rather than overshooting.
+ */
+const SETTLE_MS = 600;
+/**
+ * A reply that produces nothing for this long is a failure, not a slow answer.
+ *
+ * Overridable so a test can fail fast instead of sitting through the production grace period. Ninety seconds
+ * is right for a person waiting on a real answer; it is a waste of an evening when the question is "does the
+ * send land at all". `DSH_FIRST_TOKEN_TIMEOUT_MS` is honoured only when it parses to a positive number, so a
+ * typo cannot silently disable the guard.
+ */
+const FIRST_TOKEN_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.DSH_FIRST_TOKEN_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw >= 1000 ? raw : 90000;
+})();
+
+/**
+ * A PAUSE longer than this means the page has stopped, so the call is abandoned.
+ *
+ * Rule set by the person after three runs stalled: "any time you detect a long pause more than 5 seconds,
+ * kill tests, kill browsers, stop and report". A pause is time since the last sign of life - a character of
+ * the answer, or the page becoming ready - not time since the call began, because starting a browser is
+ * legitimately slow and must not be mistaken for a hang.
+ *
+ *     default          5000 ms
+ *     DSH_STALL_MS     overrides it, floored at 1000 ms; a non-number is ignored rather than trusted
+ *     production use   leave it alone - 5 s of utter silence is already abnormal
+ */
+export const STALL_MS = (() => {
+  const raw = Number(process.env.DSH_STALL_MS);
+  return Number.isFinite(raw) && raw >= 1000 ? raw : 5000;
+})();
+
+/**
+ * The same limit, for a call that searched the web.
+ *
+ * A search fetches before it writes anything, so silence is the page working rather than the page dead.
+ * Measured: the first live search test was killed at 5.1 s with nothing on screen, which would abort every
+ * search if the ordinary limit applied. Thirty seconds of nothing is still a fault.
+ */
+export const SEARCH_STALL_MS = (() => {
+  const raw = Number(process.env.DSH_SEARCH_STALL_MS);
+  return Number.isFinite(raw) && raw >= 5000 ? raw : 30_000;
+})();
+const TOTAL_TIMEOUT_MS = 600000;
+/**
+ * How long one call may hold the serialisation slot before it is treated as leaked.
+ *
+ * Comfortably longer than TOTAL_TIMEOUT_MS, so a genuinely slow turn is never cut short, but finite so a
+ * dropped generator cannot freeze the plugin until the harness is restarted.
+ */
+const WATCHDOG_MS = 20 * 60_000;
+/**
+ * How often the reply text is sampled.
+ *
+ * This is the resolution of the settle measurement: at 110 ms, a 600 ms window could be read as anywhere
+ * between 600 and 710 ms and the reply is handed over late by that much. At 70 ms the overshoot is small
+ * enough to be invisible, and one extra DOM read every 70 ms is nothing.
+ */
+const POLL_MS = 70;
+
+export class WebChatError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'WebChatError';
+    this.code = code;
+  }
+}
+
+/** Where each supported Chromium keeps its everyday profile. */
+const PROFILE_ROOTS = {
+  brave: `${process.env.LOCALAPPDATA}\\BraveSoftware\\Brave-Browser\\User Data`,
+  edge: `${process.env.LOCALAPPDATA}\\Microsoft\\Edge\\User Data`,
+};
+
+/**
+ * Choose the browser, preferring Brave and never failing when it is absent.
+ *
+ * Brave is preferred because it blocks ad and tracking scripts by default, which protects the person and
+ * keeps the page this plugin drives predictable. But requiring it would lose every user who does not
+ * already have it, and installing it on their behalf would be indefensible - so Edge, which every Windows
+ * machine already has, is the guaranteed fallback. The plugin therefore always works and never blocks an
+ * install on a missing browser.
+ *
+ * Headless is not considered at all: chat.deepseek.com answers headless clients with a 403 from
+ * CloudFront, measured with a clean profile and both headless flags, so that path cannot succeed.
+ */
+function chooseBrowser() {
+  for (const p of BRAVE_PATHS) {
+    if (existsSync(p)) return { kind: 'brave', exe: p, profile: PROFILE_ROOTS.brave };
+  }
+  for (const p of EDGE_PATHS) {
+    if (existsSync(p)) return { kind: 'edge', exe: p, profile: PROFILE_ROOTS.edge };
+  }
+  return undefined;
+}
+
+/**
+ * Build the launch arguments.
+ *
+ * `--start-minimized` is deliberately NOT used: measured on this machine it produced a normal, visible,
+ * non-minimised window, because Chromium treats it as a hint and drops it when it hands off to an already
+ * running browser. Minimising is performed as an action once the window exists, which is the only
+ * approach that can be verified rather than hoped for.
+ */
+function launchArgs(port, browser) {
+  return [
+    `--remote-debugging-port=${port}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    `--user-data-dir=${browser.profile}`,
+    '--profile-directory=Default',
+
+    /*
+     * NEVER THROTTLE. This is the fix for "the answer only arrives when I open the window".
+     *
+     * MEASURED, BY THE PERSON USING IT
+     *     A message was sent, the elapsed timer climbed past a minute, and nothing came back. The reply
+     *     appeared the instant the browser window was raised. That is not a network problem - it is
+     *     Chromium backgrounding a window nobody is looking at.
+     *
+     * WHY IT BREAKS THIS PLUGIN SPECIFICALLY
+     *     The page streams its answer into the DOM and this client reads it by polling every 70ms. Chromium
+     *     throttles timers and rendering in a minimised or occluded window - timers can drop to once a
+     *     minute - so the answer finishes inside the page while this reader is not allowed to see it.
+     *     Raising the window lifts the throttle, which is exactly what was reported.
+     *
+     *     The plugin minimises the window on purpose, so being throttled is the NORMAL state here, not an
+     *     edge case. These flags are not an optimisation: without them the default configuration is broken.
+     */
+    '--disable-background-timer-throttling',
+    '--disable-backgrounding-occluded-windows',
+    '--disable-renderer-backgrounding',
+    '--disable-background-mode',
+    // Rendering-related throttles. A page that stops painting stops writing the DOM we poll.
+    '--run-all-compositor-stages-before-draw',
+    '--disable-new-content-rendering-timeout',
+    // `CalculateNativeWinOcclusion` is what tells Chromium the window is hidden; `IntensiveWakeUpThrottling`
+    // is the one-minute timer clamp. Both are removed deliberately.
+    '--disable-features=Translate,MediaRouter,CalculateNativeWinOcclusion,IntensiveWakeUpThrottling',
+
+    CHAT_URL,
+  ];
+}
+
+/**
+ * Tell the page it is foregrounded, whatever the window is doing.
+ *
+ * The launch flags above stop the timers being clamped, but Chromium also marks a page `hidden` when its
+ * window is occluded, and some frameworks stop rendering work entirely on that signal. `Page.
+ * setWebLifecycleState('active')` overrides it, which is the state a person watching the window would
+ * produce anyway. Best-effort: an older build without the method must not stop a call.
+ */
+async function keepPageActive(cdp) {
+  try {
+    await cdp.send('Page.enable', {}, 5000);
+    await cdp.send('Page.setWebLifecycleState', { state: 'active' }, 5000);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The process listening on a port, found SYNCHRONOUSLY.
+ *
+ * Needed by the exit hook, which runs where no promise can resolve. `netstat -ano` is the one tool present on
+ * every Windows machine; the PID is the last column of a LISTENING line. Returns null when nothing is
+ * listening, which is the ordinary "already stopped" case rather than an error.
+ */
+function ownerOfPortSync(port) {
+  try {
+    const out = execFileSync('netstat', ['-ano'], { encoding: 'utf8', timeout: 3000 });
+    for (const line of out.split('\n')) {
+      if (!line.includes('LISTENING')) continue;
+      const cols = line.trim().split(/\s+/);
+      if (cols.length < 5) continue;
+      // The local address column is "<ip>:<port>"; match the port exactly, not a substring of it.
+      const [, localPort] = String(cols[1]).match(/:(\d+)$/) ?? [];
+      if (localPort !== String(port)) continue;
+      const pid = Number(cols[cols.length - 1]);
+      if (Number.isInteger(pid) && pid > 0) return pid;
+    }
+  } catch {
+    /* netstat missing or refused: nothing we can do from an exit handler */
+  }
+  return null;
+}
+
+/**
+ * Minimise the browser window that owns a debugging port.
+ *
+ * The window is found by asking the browser itself which process serves the port, then locating that
+ * process's top-level window. Asking the browser is what keeps this safe: the plugin only ever touches
+ * the window it launched, never a Brave window the person is using.
+ *
+ * Returns the measured result, because "minimise requested" and "minimise happened" are different facts
+ * and only the second one matters to somebody who does not want a window in front of them.
+ */
+export async function minimiseBrowserWindow(port) {
+  try {
+    const ps = `
+$ErrorActionPreference = 'Stop'
+Add-Type -Namespace W -Name U -MemberDefinition @"
+[DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int c);
+[DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
+[DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
+"@
+$pidOwner = (Get-NetTCPConnection -State Listen -LocalPort ${port} -ErrorAction SilentlyContinue |
+             Select-Object -First 1).OwningProcess
+if (-not $pidOwner) { '{"ok":false,"why":"nothing listening"}' ; exit }
+$proc = Get-Process -Id $pidOwner -ErrorAction SilentlyContinue
+$h = [IntPtr]$proc.MainWindowHandle
+if ($h -eq [IntPtr]::Zero) { '{"ok":false,"why":"no window on that process","pid":' + $pidOwner + '}' ; exit }
+[void][W.U]::ShowWindow($h, 6)   # SW_MINIMIZE
+Start-Sleep -Milliseconds 250
+$iconic = [W.U]::IsIconic($h)
+'{"ok":' + $iconic.ToString().ToLower() + ',"minimised":' + $iconic.ToString().ToLower() +
+  ',"visible":' + [W.U]::IsWindowVisible($h).ToString().ToLower() + ',"pid":' + $pidOwner + '}'
+`;
+    
+    const out = execFileSync('pwsh', ['-NoProfile', '-Command', ps], {
+      encoding: 'utf8',
+      timeout: 15000,
+    }).trim();
+    const parsed = JSON.parse(out.split(/\r?\n/).filter(Boolean).pop());
+    return parsed;
+  } catch (err) {
+    return { ok: false, why: err?.message ?? String(err) };
+  }
+}
+
+async function portOpen(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, {
+      signal: AbortSignal.timeout(1500),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read the newest assistant reply, but only if it is new.
+ *
+ * WHY THE BASELINE IS NOT JUST A COUNT ANY MORE
+ *     The old version decided "is this reply new?" by comparing the number of assistant blocks with the count
+ *     taken before sending. That is wrong for a conversation that has been going for a few turns: the site
+ *     recycles or unmounts earlier messages, so the block count can stop growing even though a brand new
+ *     answer has appeared.
+ *
+ *     MEASURED, by the person watching the browser: the fourth message in a chat was answered on screen -
+ *     they read it - while this reader reported no text at all and the call was abandoned as a stall. Three
+ *     separate runs stalled on the fourth message and only the fourth; different questions, same position.
+ *     A page that answered cannot be a page that stalled, so the fault was here.
+ *
+ *     The baseline therefore records the shape of the last reply as well as how many there are: a new reply is
+ *     either an extra block, or the same number of blocks with different text. Length and tail are enough to
+ *     tell them apart, and they keep the injected expression small - the whole previous answer would be
+ *     several kilobytes posted to the page on every 70 ms poll.
+ */
+const readReply = (base) => `(() => {
+  const nodes = [...document.querySelectorAll('${ASSISTANT}')];
+  const last = nodes[nodes.length - 1];
+  const text = last ? (last.innerText || '') : '';
+  const tail = text.length > 48 ? text.slice(-48) : text;
+  const grew = nodes.length > ${base.count};
+  const replaced = text.length > 0 && (text.length !== ${base.len} || tail !== ${JSON.stringify(base.tail)});
+  /*
+   * A second, cruder signal: how much text the whole page holds.
+   *
+   * MEASURED, by the person reading Brave: a 1000-word request was answered, but the plugin abandoned it after
+   * five silent seconds. The page was not silent at all - it was writing its reasoning into a Thinking block,
+   * which is a different element from the answer this reader looks at. From here that looked exactly like a
+   * dead page.
+   *
+   * The answer element is the only thing worth EMITTING, but it is not the only thing worth WATCHING. Growth
+   * anywhere in the document means the page is working, so the pause limit is reset by it. This is deliberately
+   * blunt: it needs no knowledge of the reasoning element's class name, which the site can rename at will.
+   */
+  const alive = document.body ? document.body.innerText.length : 0;
+  return {
+    text,
+    found: nodes.length,
+    isNew: grew || replaced,
+    grew,
+    replaced,
+    alive,
+  };
+})()`;
+
+/** How many assistant blocks are on screen, and the shape of the last one. The baseline for one call. */
+const READ_BASELINE = `(() => {
+  const nodes = [...document.querySelectorAll('${ASSISTANT}')];
+  const last = nodes[nodes.length - 1];
+  const text = last ? (last.innerText || '') : '';
+  return { count: nodes.length, len: text.length, tail: text.length > 48 ? text.slice(-48) : text };
+})()`;
+
+const FIND_COMPOSER = `(() => {
+  const vis = (el) => {
+    const r = el.getBoundingClientRect();
+    const s = getComputedStyle(el);
+    return r.width > 4 && r.height > 4 && s.visibility !== 'hidden' && s.display !== 'none';
+  };
+  const el = [...document.querySelectorAll('textarea,[contenteditable="true"]')].filter(vis)[0];
+  if (!el) return null;
+  return { tag: el.tagName.toLowerCase(), placeholder: el.getAttribute('placeholder') || '' };
+})()`;
+
+const TYPE_TEXT = (text) => `(() => {
+  const vis = (el) => {
+    const r = el.getBoundingClientRect();
+    const s = getComputedStyle(el);
+    return r.width > 4 && r.height > 4 && s.visibility !== 'hidden' && s.display !== 'none';
+  };
+  const el = [...document.querySelectorAll('textarea,[contenteditable="true"]')].filter(vis)[0];
+  if (!el) return { ok: false, why: 'no composer' };
+  el.focus();
+  const t = ${JSON.stringify(text)};
+  if (el.tagName === 'TEXTAREA') {
+    const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value').set;
+    setter.call(el, t);
+  } else {
+    el.textContent = t;
+  }
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+  el.dispatchEvent(new Event('change', { bubbles: true }));
+  return { ok: true, len: (el.value || el.textContent || '').length };
+})()`;
+
+/**
+ * Click the control that starts a blank conversation.
+ *
+ * The class names on this control are generated and change between deploys, but the element that is
+ * actually clickable is the one carrying `tabindex="0"` and the label - the outer wrappers are not.
+ * Clicking a wrapper is what made the first version silently fail and leave the old transcript up.
+ */
+const CLICK_NEW_CHAT = `(() => {
+  const vis = (el) => {
+    const r = el.getBoundingClientRect();
+    return r.width > 2 && r.height > 2;
+  };
+  const candidates = [...document.querySelectorAll('[tabindex="0"],button,a')].filter(vis);
+  const hit = candidates.find((el) => {
+    const t = (el.innerText || '').trim().toLowerCase();
+    if (t !== 'new chat' && t !== 'new conversation') return false;
+    return el.querySelectorAll('[tabindex="0"]').length === 0;
+  });
+  if (!hit) return false;
+  hit.click();
+  return true;
+})()`;
+
+/**
+ * Read the composer's two switches.
+ *
+ * `DeepThink` turns on the reasoning pass; `Search` lets it read the live web. Both are per-conversation
+ * and both reset with a new chat, which is exactly why they must be set AFTER the chat is reset and
+ * before the prompt is typed - setting them first would have them cleared a moment later.
+ */
+const READ_TOGGLES = `(() => {
+  const out = {};
+  for (const el of document.querySelectorAll('.ds-toggle-button')) {
+    const label = (el.innerText || '').trim();
+    if (!label) continue;
+    out[label] = String(el.className || '').indexOf('ds-toggle-button--selected') >= 0;
+  }
+  return out;
+})()`;
+
+const clickToggle = (label) => `(() => {
+  const want = ${JSON.stringify(label)}.toLowerCase();
+  const el = [...document.querySelectorAll('.ds-toggle-button')].find(
+    (n) => (n.innerText || '').trim().toLowerCase() === want,
+  );
+  if (!el) return false;
+  el.click();
+  return true;
+})()`;
+
+/**
+ * Read the sources a search answer was built from.
+ *
+ * The page never writes the query it used into the DOM, and it does not expose a source list as text.
+ * What it does leave behind is a row of favicons whose URLs are `cdn.deepseek.com/site-icons/<domain>`,
+ * plus citation anchors pointing at the articles. The domain in that URL IS the source, so the search
+ * output is recoverable even though the panel that produced it is gone by the time the answer settles.
+ */
+const READ_SOURCES = `(() => {
+  const domains = new Set();
+  for (const img of document.querySelectorAll('img[src*="site-icons/"]')) {
+    const m = /site-icons\\/([^/?#]+)/.exec(img.getAttribute('src') || '');
+    if (m && m[1]) domains.add(m[1]);
+  }
+  const links = new Set();
+  for (const a of document.querySelectorAll('a[href^="http"]')) {
+    const h = a.getAttribute('href') || '';
+    if (!h) continue;
+    if (h.indexOf('chat.deepseek.com') >= 0) continue;
+    if (h.indexOf('cdn.deepseek.com') >= 0) continue;
+    links.add(h);
+  }
+  return { domains: [...domains], links: [...links].slice(0, 12) };
+})()`;
+
+/**
+ * One conversation with the web UI.
+ *
+ * A `ChatSession` owns the browser page. Calls are serialised deliberately: the site is a single
+ * document with one composer, so two concurrent prompts would type over each other and one caller
+ * would receive the other's answer.
+ */
+export class ChatSession {
+  #port;
+  #cdp = null;
+  #queue = Promise.resolve();
+  /** Which harness conversation the browser chat currently holds. See #askInner for why this exists. */
+  #ownerKey = null;
+  /**
+   * True from the moment THIS object launches a browser until that browser is gone.
+   *
+   * The distinction matters on exit: a browser we started is ours to kill, and one we merely attached to
+   * belongs to somebody else. Guessing after the fact is impossible, so it is recorded at the launch.
+   */
+  #launchedByUs = false;
+  #exitHookInstalled = false;
+  /**
+   * Switches THIS plugin turned on for a call, so they can be put back afterwards.
+   *
+   * A search call used to leave the site's Search toggle on, so the next ordinary message searched the web
+   * without anybody asking - slower, and a silent change of behaviour. Recorded per call, restored at the end
+   * of it, and restored again at the start of the next call in case the previous one threw.
+   */
+  #turnedOn = [];
+  /** Whether to minimise the window after it launches. The only display choice left. */
+  autoMinimise = true;
+  /** Result of the last minimise attempt: `{ ok, minimised, visible, pid }`. Reported by the setup panel. */
+  lastMinimise = null;
+
+  constructor({ port = 9222, autoMinimise = true } = {}) {
+    this.#port = port;
+    this.autoMinimise = autoMinimise;
+  }
+
+  get port() {
+    return this.#port;
+  }
+
+  /** Which browser this machine will use: 'brave' when present, otherwise 'edge'. */
+  get browserKind() {
+    return chooseBrowser()?.kind ?? null;
+  }
+
+  /**
+   * Close the browser this session is driving.
+   *
+   * Only the browser on this session's own port is closed, so a window the person is using is never
+   * touched. Used when a launch has to be replaced, for example to bring the site forward for signing in.
+   */
+  async stop() {
+    this.#cdp?.close();
+    this.#cdp = null;
+    try {
+      const res = await fetch(`http://127.0.0.1:${this.#port}/json/version`, {
+        signal: AbortSignal.timeout(1200),
+      });
+      if (res.ok) {
+        // Ask the browser to exit through its own automation endpoint where possible; fall back to the
+        // page-level close below when that endpoint is unavailable.
+        await fetch(`http://127.0.0.1:${this.#port}/json/list`).catch(() => {});
+      }
+    } catch {
+      /* nothing listening: already stopped */
+    }
+    // Kill by port owner so a stale headless process cannot hold the profile lock.
+    try {
+      const { execSync } = await import('node:child_process');
+      const out = execSync(`netstat -ano | findstr :${this.#port}`, { encoding: 'utf8' });
+      const pids = new Set([...out.matchAll(/\s(\d+)\s*$/gm)].map((m) => m[1]));
+      for (const pid of pids) {
+        try {
+          execSync(`taskkill /PID ${pid} /F`, { stdio: 'ignore' });
+        } catch {
+          /* already gone */
+        }
+      }
+    } catch {
+      /* no process on that port */
+    }
+    await new Promise((r) => setTimeout(r, 800));
+  }
+
+  async #connect() {
+    if (this.#cdp && !this.#cdp.closed) return this.#cdp;
+
+    if (!(await portOpen(this.#port))) {
+      /*
+       * RECORD WHO ASKED FOR THIS, BEFORE LAUNCHING.
+       *
+       * A browser has appeared on the person's desktop four times tonight with the route set to API, and each
+       * time the only answer available was a theory: the route handler is guarded, inspect() is read-only, the
+       * parent process had already exited. Theories cost the person three rounds of their evening.
+       *
+       * So the caller is captured here, where the launch actually happens, and written to a file as well as
+       * stderr. A file survives the process, which matters because the interesting case is a launcher that
+       * exits. `DSH_WEB_LAUNCH_LOG` overrides the path; the default sits beside the plugin so it is easy to
+       * find. Best-effort throughout: a diagnostic must never be able to stop a call.
+       */
+      try {
+        const stack = new Error('launch trace').stack ?? '';
+        /*
+         * Keep the first frames that belong to neither this engine nor Node itself - that is what names the
+         * caller.
+         *
+         * A flat `slice(1, 12)` was not enough: one recorded launch produced ONLY
+         * `processTicksAndRejections`, because ten Node-internal frames pushed the real caller past the cut.
+         * The chain here is webserver -> host -> llm -> adapter -> ask -> connect, easily twelve frames.
+         */
+        const lines = stack
+          .split('\n')
+          .slice(1)
+          .map((l) => l.trim())
+          .filter(Boolean);
+        const isEngine = (l) => l.includes('lib/engine.mjs');
+        const isNodeInternal = (l) => l.includes('node:internal');
+        const appFrames = lines.filter((l) => !isEngine(l) && !isNodeInternal(l)).slice(0, 5);
+        const note = lines.length > appFrames.length ? `\n    (+${lines.length} frames seen)` : '';
+        const line = `\n=== browser launch ${new Date().toISOString()} port ${this.#port}\n    ${appFrames.join('\n    ')}${note}\n`;
+        if (process.env.DEBUG_WEB_CHAT) console.error(`[launch]${line}`);
+        const logPath =
+          process.env.DSH_WEB_LAUNCH_LOG ||
+          // One level up from lib/ is the package root. Two levels put the file outside the package.
+          new URL('../browser-launches.log', import.meta.url).pathname.replace(/^\//, '');
+        appendFileSync(logPath, line, 'utf8');
+      } catch {
+        /* a diagnostic that fails must not block the launch it is describing */
+      }
+
+      const browser = chooseBrowser();
+      if (!browser) {
+        throw new WebChatError(
+          'no Chromium browser found. Brave is recommended; Edge ships with Windows and is used ' +
+            'automatically when Brave is absent.',
+          'NO_BROWSER',
+        );
+      }
+      spawn(browser.exe, launchArgs(this.#port, browser), {
+        detached: true,
+        stdio: 'ignore',
+      }).unref();
+      // From here on this browser is ours: it is killed if this process dies without stopping it first.
+      this.#launchedByUs = true;
+      this.#claimOnExit();
+      await waitFor(() => portOpen(this.#port), {
+        timeout: 90000,
+        interval: 600,
+        label: 'the browser debug port',
+      });
+
+      // Wait for the page before deciding whether to hide the window. A page that still needs a sign-in
+      // has to stay visible - hiding it would leave the person with no way to log in and nothing on
+      // screen to explain it. The decision is therefore made from what the page actually shows.
+      await waitFor(() => Cdp.findTarget(this.#port, 'chat.deepseek.com'), {
+        timeout: 60000,
+        interval: 500,
+        label: 'a chat.deepseek.com tab',
+      });
+
+      if (this.autoMinimise) {
+        const signedOut = await this.#needsSignIn().catch(() => false);
+        if (signedOut) {
+          // Leave it visible and on top: the person has something to do.
+          this.lastMinimise = { ok: false, skipped: 'waiting for sign-in' };
+          await this.#raiseWindow().catch(() => {});
+        } else {
+          this.lastMinimise = await minimiseBrowserWindow(this.#port);
+          // The window just became minimised, which is the signal that starts throttling. Re-assert the
+          // page is active so the reply that follows is not the one that has to wait for a human.
+          if (this.#cdp && !this.#cdp.closed) await keepPageActive(this.#cdp);
+        }
+      }
+    }
+
+    const target = await waitFor(() => Cdp.findTarget(this.#port, 'chat.deepseek.com'), {
+      timeout: 60000,
+      interval: 500,
+      label: 'a chat.deepseek.com tab',
+    });
+    this.#cdp = await Cdp.attach(this.#port, target.id);
+    await this.#cdp.send('Runtime.enable', {}, 10000);
+    /*
+     * Claim the page is foregrounded, every time a connection is made.
+     *
+     * The launch flags stop the timer clamp, but a page whose window is minimised is still marked hidden,
+     * and a page that believes it is hidden may defer rendering work. This says "active" - the state a
+     * person watching the window would have produced - so the answer streams whether the window is up or
+     * not. Best-effort: a build without the method must not stop a call.
+     */
+    await keepPageActive(this.#cdp);
+    return this.#cdp;
+  }
+
+  /**
+   * Is this page waiting for a sign-in?
+   *
+   * Read from the document itself rather than from a stored token: the token can be present and stale,
+   * which is exactly how a sign-in screen was mistaken for a ready page earlier. The sign-in route and the
+   * absence of a composer are the two things that mean "a human has to act here".
+   */
+  async #needsSignIn() {
+    const cdp = this.#cdp;
+    if (!cdp || cdp.closed) {
+      const target = await Cdp.findTarget(this.#port, 'chat.deepseek.com');
+      if (!target) return true;
+      this.#cdp = await Cdp.attach(this.#port, target.id);
+      await this.#cdp.send('Runtime.enable', {}, 10000);
+      await keepPageActive(this.#cdp);
+    }
+    const info = await this.#cdp.evaluate(
+      `(() => ({
+        url: location.href,
+        onSignIn: location.pathname.indexOf('sign_in') >= 0,
+        hasComposer: Boolean(document.querySelector('textarea')),
+      }))()`,
+      { timeout: 8000 },
+    );
+    return Boolean(info?.onSignIn || !info?.hasComposer);
+  }
+
+  /** Bring the browser window to the front so a sign-in form is actually visible. */
+  async #raiseWindow() {
+    
+    const ps = `
+$ErrorActionPreference = 'Stop'
+Add-Type -Namespace W -Name U -MemberDefinition @"
+[DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int c);
+[DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h);
+"@
+$pidOwner = (Get-NetTCPConnection -State Listen -LocalPort ${this.#port} -ErrorAction SilentlyContinue |
+             Select-Object -First 1).OwningProcess
+if (-not $pidOwner) { exit }
+$proc = Get-Process -Id $pidOwner -ErrorAction SilentlyContinue
+$h = [IntPtr]$proc.MainWindowHandle
+if ($h -eq [IntPtr]::Zero) { exit }
+[void][W.U]::ShowWindow($h, 9)   # SW_RESTORE
+[void][W.U]::SetForegroundWindow($h)
+`;
+    execFileSync('pwsh', ['-NoProfile', '-Command', ps], { encoding: 'utf8', timeout: 15000 });
+  }
+
+  /**
+   * Report what the browser is doing, without changing anything.
+   *
+   * Separated from `ensureReady` because setup needs to ASK before acting: a person opening the plugin
+   * panel should see the current state, not trigger a browser launch just by looking. `ensureReady`
+   * navigates and waits; this only reads.
+   */
+  async inspect() {
+    /*
+     * READ, NEVER LAUNCH.
+     *
+     * This used to go through #connect(), which starts the browser when the debug port is closed. That
+     * meant opening the Settings panel silently spawned a window - the exact opposite of the promise this
+     * method's contract makes: "looking must not act". When nothing is listening, the honest answer is
+     * "nothing to inspect", and the panel's launch button is the only thing that starts a browser.
+     */
+    if (!(await portOpen(this.#port))) {
+      return { ok: false, error: `no browser is listening on port ${this.#port}` };
+    }
+    try {
+      const cdp = await this.#connect();
+      const info = await cdp.evaluate(
+        `(() => ({
+          url: location.href,
+          signedIn: Boolean(localStorage.getItem('userToken')),
+          hasComposer: Boolean(document.querySelector('textarea')),
+          onSignInPage: location.pathname.indexOf('sign_in') >= 0,
+        }))()`,
+        { timeout: 8000 },
+      );
+      return { ok: true, ...info };
+    } catch (err) {
+      return { ok: false, error: err?.message ?? String(err) };
+    }
+  }
+
+  /**
+   * Bring the site up in front so a person can sign in once.
+   *
+   * The plugin deliberately does not hold a password. A Chromium profile keeps the session for weeks
+   * after a single sign-in, and storing a credential would put it in plaintext on disk for a benefit
+   * measured in one avoided login. This method exists to make that one login effortless: it launches
+   * the browser if needed, navigates to the site and raises the window.
+   */
+  async openSignIn() {
+    const cdp = await this.#connect();
+    await cdp.navigate(CHAT_URL);
+    await cdp.bringToFront();
+    return { ok: true };
+  }
+
+  /**
+   * Reset the browser to a blank conversation.
+   *
+   * This is the one thing a person cannot reach from inside the harness. When a chat drifts, fills up, or
+   * starts answering the wrong subject, the only way back to a clean slate is the site's own "New chat" -
+   * which is exactly what this clicks, so it looks to the site like ordinary use.
+   *
+   * The reset is verified rather than assumed: newChat() re-reads the transcript and fails if a previous
+   * conversation survived. A click that merely looked successful would leave the next prompt inheriting the
+   * old subject, which is the bug this exists to avoid.
+   */
+  async startFresh() {
+    const cdp = await this.ensureReady();
+    await this.newChat(cdp);
+    // Any conversation the session thought it owned is gone now.
+    this.#ownerKey = null;
+    return { ok: true };
+  }
+
+  /** Raise the browser window so a person can look at the page. */
+  async showWindow() {
+    await this.#connect();
+    await this.#raiseWindow();
+    return { ok: true };
+  }
+
+  /** Load the site and confirm the composer exists and a session is present. */
+  async ensureReady() {
+    const cdp = await this.#connect();
+    const composer = await waitFor(() => cdp.evaluate(FIND_COMPOSER, { timeout: 8000 }), {
+      timeout: 45000,
+      interval: 500,
+      label: 'the message composer',
+    }).catch(() => null);
+
+    if (!composer) {
+      // Either still loading or signed out. A reload settles both cases.
+      await cdp.navigate(CHAT_URL);
+      const again = await waitFor(() => cdp.evaluate(FIND_COMPOSER, { timeout: 8000 }), {
+        timeout: 60000,
+        interval: 600,
+        label: 'the message composer after reload',
+      }).catch(() => null);
+      if (!again) {
+        const signedIn = await cdp
+          .evaluate(`Boolean(localStorage.getItem('userToken'))`, { timeout: 5000 })
+          .catch(() => false);
+        throw new WebChatError(
+          signedIn
+            ? 'chat.deepseek.com loaded but the composer never appeared'
+            : 'not signed in to chat.deepseek.com - open the browser and sign in once',
+          signedIn ? 'COMPOSER_MISSING' : 'NOT_SIGNED_IN',
+        );
+      }
+    }
+    await cdp.bringToFront();
+    return cdp;
+  }
+
+  /**
+   * Start a blank conversation and PROVE it is blank.
+   *
+   * Clicking is not evidence. The click is followed by a check that no assistant blocks remain, because
+   * a silent failure here does not raise - it just sends the next prompt into the previous conversation
+   * and returns an answer with the old one glued to the front.
+   */
+  async newChat(cdp) {
+    // A blank chat has no assistant blocks at all, so a bare count is the right test here.
+    const empty = async () => (await cdp.evaluate(`document.querySelectorAll('${ASSISTANT}').length`, { timeout: 8000 })) === 0;
+
+    if (await cdp.evaluate(CLICK_NEW_CHAT, { timeout: 8000 }).catch(() => false)) {
+      const cleared = await waitFor(empty, {
+        timeout: 8000,
+        interval: 200,
+        label: 'the transcript to clear',
+      }).catch(() => false);
+      if (cleared) return;
+    }
+
+    await cdp.navigate(CHAT_URL);
+    await waitFor(() => cdp.evaluate(FIND_COMPOSER, { timeout: 8000 }), {
+      timeout: 45000,
+      interval: 400,
+      label: 'the composer after navigating to a new chat',
+    });
+    const cleared = await waitFor(empty, {
+      timeout: 10000,
+      interval: 250,
+      label: 'the transcript to clear after navigation',
+    }).catch(() => false);
+    if (!cleared) {
+      throw new WebChatError(
+        'could not start a blank conversation - chat.deepseek.com restored a previous chat, so the ' +
+          'prompt would be sent with earlier turns still in context',
+        'NEW_CHAT_FAILED',
+      );
+    }
+  }
+
+  /**
+   * Send one prompt and stream the reply.
+   *
+   * `options` carries `signal` plus the two switch states (`deepThink`, `search`).
+   * Yields `{ text }` deltas while the answer is being written, then `{ done: true, text }`.
+   *
+   * WHY THERE IS A WATCHDOG AND NOT A DELAY
+   *     Runs are serialised through a promise queue so two callers cannot share one composer. That queue
+   *     has one failure mode: if the caller stops consuming this generator - the harness abandons the
+   *     stream on a cancel, or an exception escapes between `yield`s - the `finally` never runs, the
+   *     release is never called, and every later request waits on a promise that will never settle. From
+   *     outside it looks like the plugin has frozen and only a harness restart fixes it.
+   *
+   *     So a held slot is released by force after WATCHDOG_MS. Nothing legitimate holds one that long:
+   *     the slowest real turn is a few minutes, and TOTAL_TIMEOUT_MS caps a single call well below this.
+   *
+   * WHY THERE IS NO MINIMUM INTERVAL
+   *     Other plugins in this space insert a random 2-4 second gap between requests, because the web API
+   *     is stateless and they re-send the whole transcript every turn - a session can reach hundreds of
+   *     thousands of tokens and accounts get muted. Uncle Sam continues the conversation inside the page
+   *     and sends only the newest message, so its per-turn load is a small fraction of that. The gap is
+   *     the single largest source of latency in those plugins, and it buys them nothing here.
+   */
+  async *ask(prompt, options = {}) {
+    const previous = this.#queue;
+    let release;
+    let released = false;
+    this.#queue = new Promise((r) => {
+      release = r;
+    });
+
+    const releaseOnce = () => {
+      if (released) return;
+      released = true;
+      clearTimeout(watchdog);
+      release();
+    };
+
+    // A slot held past this is leaked, not busy.
+    const watchdog = setTimeout(() => {
+      if (released) return;
+      released = true;
+      release();
+    }, WATCHDOG_MS);
+    // The timer must not keep the host process alive by itself.
+    watchdog.unref?.();
+
+    await previous;
+    try {
+      yield* this.#askInner(prompt, options);
+    } finally {
+      releaseOnce();
+    }
+  }
+
+  /**
+   * Force one switch to a wanted state, and prove it took.
+   *
+   * Clicking is a request, not a result: a stale element or a mis-hit leaves the switch as it was, and
+   * the call would then silently run in the wrong mode - answering from memory when Search was asked
+   * for, or spending a reasoning pass when it was not. So the state is re-read until it matches.
+   */
+  async setToggle(cdp, label, want) {
+    const state = await cdp.evaluate(READ_TOGGLES, { timeout: 8000 });
+    if (state?.[label] === undefined) {
+      throw new WebChatError(
+        `the "${label}" switch is not present on the page - the composer may have changed shape`,
+        'TOGGLE_MISSING',
+      );
+    }
+    if (state[label] === want) return false;
+
+    const clicked = await cdp.evaluate(clickToggle(label), { timeout: 8000 });
+    if (!clicked) {
+      throw new WebChatError(`could not click the "${label}" switch`, 'TOGGLE_CLICK_FAILED');
+    }
+    await waitFor(
+      async () => {
+        const now = await cdp.evaluate(READ_TOGGLES, { timeout: 6000 });
+        return now?.[label] === want ? now : null;
+      },
+      { timeout: 6000, interval: 150, label: `the "${label}" switch to become ${want ? 'on' : 'off'}` },
+    );
+    return true;
+  }
+
+  /**
+   * Apply switch states, but only where the plugin actually has an opinion.
+   *
+   * THIS USED TO FIGHT THE PERSON
+   *     Every call passed `deepThink: false, search: false` for an ordinary model, and those were treated
+   *     as instructions to turn both switches OFF. So somebody who turned DeepThink on in the browser - the
+   *     visible, deliberate act of asking for a better answer - had it silently switched off by the next
+   *     message. Recorded happening live: both toggles lit by hand, both dark again after the plugin sent.
+   *
+   *     `undefined` now means "leave it as the person left it", and only an explicit `true` asks for a
+   *     change. Turning something ON is the plugin's business; turning it OFF is the person's.
+   */
+  async applyToggles(cdp, { deepThink, search } = {}) {
+    const changed = [];
+    if (deepThink === true) {
+      if (await this.setToggle(cdp, 'DeepThink', true)) changed.push('DeepThink');
+    }
+    if (search === true) {
+      if (await this.setToggle(cdp, 'Search', true)) changed.push('Search');
+    }
+    return changed;
+  }
+
+  /**
+   * Put back any switch this plugin turned on for one call.
+   *
+   * WHY THIS EXISTS
+   *     A search call turned the site's Search toggle on and left it there. The next ordinary message then
+   *     searched the web without anybody asking - slower, and a silent change of behaviour: the person picks
+   *     "fast chat" and gets a web lookup. The toggle is per-conversation state on the site, so leaving it on
+   *     changes what later turns do.
+   *
+   *     Only switches THIS plugin turned on are restored. If the person had already enabled Search, it was
+   *     never in the changed list, so it stays exactly as they left it - the plugin must not fight a
+   *     deliberate choice.
+   *
+   *     Best-effort: failing to restore must not fail a call that already succeeded.
+   */
+  async restoreToggles(cdp, names) {
+    const restored = [];
+    for (const name of names ?? []) {
+      try {
+        await this.setToggle(cdp, name, false);
+        restored.push(name);
+      } catch {
+        /* the page may have moved on; the next call tries again */
+      }
+    }
+    return restored;
+  }
+
+  async *#askInner(prompt, options = {}) {
+    const { signal, deepThink = false, search = false, continueChat = false, conversationKey } = options;
+    const cdp = await this.ensureReady();
+
+    /**
+     * One browser chat per harness conversation.
+     *
+     * There is exactly ONE browser tab, so every harness session on the web route would otherwise share
+     * the same conversation in it. That is not cosmetic: session A asks about a plugin, session B asks
+     * something unrelated, and B's message lands in A's chat - so the browser continues the wrong subject
+     * and answers a question nobody in that conversation asked.
+     *
+     * The harness also makes internal calls to generate session titles and to compact history, and those
+     * were being typed into the same chat too. That is the odd extra traffic appearing in the browser.
+     *
+     * The key decides which conversation the browser is holding. When it changes, the chat is reset
+     * before anything is typed, so no other session's words are ever sent as context.
+     */
+    const key = String(conversationKey ?? 'default');
+    if (!continueChat || this.#ownerKey !== key) {
+      await this.newChat(cdp);
+      this.#ownerKey = key;
+    }
+
+    /*
+     * Restore anything the PREVIOUS call turned on and could not put back.
+     *
+     * The normal path restores at the end of the call, but a call that throws or is abandoned leaves the
+     * switch on. Catching it here means a failure costs one turn of leftover state rather than persisting
+     * until somebody notices their messages are secretly searching the web.
+     */
+    if (this.#turnedOn.length) {
+      await this.restoreToggles(cdp, this.#turnedOn);
+      this.#turnedOn = [];
+    }
+
+    // Switches are per-conversation, so they are set after any reset and before sending.
+    this.#turnedOn = await this.applyToggles(cdp, { deepThink, search });
+
+    /*
+     * What is already on screen is history: how many assistant blocks there are, and the shape of the last
+     * one. The count alone was not enough - the site recycles blocks, so the count can stay the same while a
+     * new answer appears. See readReply for the measurement that proved it.
+     */
+    const baseline = (await cdp.evaluate(READ_BASELINE, { timeout: 8000 })) ?? { count: 0, len: 0, tail: '' };
+
+    const typed = await cdp.evaluate(TYPE_TEXT(prompt), { timeout: 15000 });
+    if (!typed?.ok) {
+      throw new WebChatError(
+        `could not type into the composer: ${typed?.why ?? 'unknown'}`,
+        'TYPE_FAILED',
+      );
+    }
+    await new Promise((r) => setTimeout(r, 250));
+
+    /**
+     * Submit the message, retrying until the composer actually clears.
+     *
+     * Enter alone is not reliable here. Measured: a 16-character message was typed in full and Enter did
+     * nothing, while the very next attempt on the same page succeeded. The site is a React app that
+     * re-renders the composer after each reply, and a synthesised Enter can land while focus is elsewhere
+     * or before the handler is attached - so the keypress is delivered and ignored, with no error anywhere.
+     *
+     * Three attempts, each escalating:
+     *   1. a real CDP Enter, which is what a person pressing the key produces
+     *   2. a DOM Enter dispatched on the focused element, in case the page listens on the node rather than
+     *      on the document
+     *   3. a click on the send button, which is the one path that cannot depend on keyboard focus
+     *
+     * Success is judged only by the composer emptying. Anything else is a failure to send, and saying so
+     * immediately beats waiting 90 seconds for an answer that was never asked for.
+     */
+    const composerEmpty = async () =>
+      Number(
+        await cdp
+          .evaluate(
+            `(() => { const t = [...document.querySelectorAll('textarea')]
+               .filter((e) => e.getBoundingClientRect().width > 4)[0];
+               return t ? t.value.length : 0; })()`,
+            { timeout: 5000 },
+          )
+          .catch(() => -1),
+      ) === 0;
+
+    const pressEnter = async () => {
+      await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13 }, 8000);
+      await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13 }, 8000);
+    };
+
+    const pressEnterInPage = async () =>
+      cdp
+        .evaluate(
+          `(() => {
+             const vis = (el) => { const r = el.getBoundingClientRect(); return r.width > 4 && r.height > 4; };
+             const el = [...document.querySelectorAll('textarea,[contenteditable="true"]')].filter(vis)[0];
+             if (!el) return false;
+             el.focus();
+             for (const type of ['keydown', 'keypress', 'keyup']) {
+               el.dispatchEvent(new KeyboardEvent(type, {
+                 key: 'Enter', code: 'Enter', keyCode: 13, which: 13, bubbles: true, cancelable: true,
+               }));
+             }
+             return true;
+           })()`,
+          { timeout: 8000 },
+        )
+        .catch(() => false);
+
+    const clickSend = async () =>
+      cdp
+        .evaluate(
+          `(() => {
+             const vis = (el) => { const r = el.getBoundingClientRect(); return r.width > 4 && r.height > 4; };
+             const send = [...document.querySelectorAll('button,[role="button"],div[class*="send"],[aria-label*="end"]')]
+               .filter(vis)
+               .find((el) => /send|submit/i.test((el.getAttribute('aria-label') || '') + ' ' + (el.className || '')));
+             if (!send) return false;
+             send.click();
+             return true;
+           })()`,
+          { timeout: 8000 },
+        )
+        .catch(() => false);
+
+    let sent = false;
+    const attempts = [
+      ['Enter', pressEnter],
+      ['Enter (in page)', pressEnterInPage],
+      ['send button', clickSend],
+      ['Enter (retry)', pressEnter],
+    ];
+    for (const [name, attempt] of attempts) {
+      await attempt().catch(() => {});
+      /**
+       * Poll for the composer clearing instead of sleeping a fixed time.
+       *
+       * A flat 1,400 ms wait after every attempt added that delay to EVERY message, including the common
+       * case where the first Enter worked. Polling exits as soon as the send lands - typically 120-250 ms -
+       * and only spends the full budget when something is genuinely wrong.
+       */
+      const cleared = await waitFor(
+        async () => ((await composerEmpty()) ? true : undefined),
+        { timeout: 1500, interval: 120, label: 'the composer to clear' },
+      ).catch(() => false);
+      if (cleared) {
+        sent = true;
+        break;
+      }
+    }
+
+    if (!sent) {
+      const stuck = Number(
+        await cdp
+          .evaluate(
+            `(() => { const t = [...document.querySelectorAll('textarea')]
+               .filter((e) => e.getBoundingClientRect().width > 4)[0];
+               return t ? t.value.length : 0; })()`,
+            { timeout: 5000 },
+          )
+          .catch(() => -1),
+      );
+      // Clear it, so the next attempt starts from a clean box instead of appending to the wreckage.
+      await cdp
+        .evaluate(
+          `(() => {
+             const t = document.querySelector('textarea');
+             if (!t) return false;
+             const set = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set;
+             set.call(t, '');
+             t.dispatchEvent(new Event('input', { bubbles: true }));
+             return true;
+           })()`,
+          { timeout: 5000 },
+        )
+        .catch(() => {});
+      throw new WebChatError(
+        `the message was typed but never sent after four attempts; the composer still holds ${stuck} ` +
+          `characters. This is the site ignoring Enter rather than a size problem. The box has been ` +
+          `cleared, so the next message can be tried.`,
+        'SEND_FAILED',
+      );
+    }
+
+    const started = Date.now();
+    let emitted = '';
+    let lastChange = Date.now();
+    let sawAnyText = false;
+    /** The page's total text length at the last poll, so growth can be noticed even outside the answer. */
+    let lastAlive = 0;
+    /*
+     * A throttle detector, so a stalled read is REPORTED instead of waited out.
+     *
+     * The launch flags should make this impossible, but if the page is still throttled the symptom is
+     * indistinguishable from a slow answer: the poll returns the same snapshot forever and the person
+     * watches a timer climb. Counting consecutive no-change reads turns that into a sentence they can act
+     * on, and re-asserting the active state once mid-wait gives a throttled page a second chance before
+     * the call is blamed.
+     */
+    let staleReads = 0;
+    let nudged = false;
+
+    while (Date.now() - started < TOTAL_TIMEOUT_MS) {
+      if (signal?.aborted) {
+        throw new WebChatError('cancelled', 'ABORTED');
+      }
+      await new Promise((r) => setTimeout(r, POLL_MS));
+
+      let snap;
+      try {
+        snap = await cdp.evaluate(readReply(baseline), { timeout: 8000 });
+      } catch {
+        continue; // the page may be mid-navigation; a missed poll is not a failure
+      }
+
+      /*
+       * A BLOCK THAT EXISTS BUT STAYS EMPTY IS NOT A REPLY.
+       *
+       * MEASURED: a test call hung for over eight minutes. The page had created the assistant block - so
+       * `isNew` was true - but never put a character in it. The no-reply guard used to live INSIDE the
+       * `!isNew` branch, so that shape skipped it entirely and the loop ran to the ten-minute cap. A person
+       * watching that sees a spinner and no explanation, which is the exact failure this guard exists to
+       * prevent.
+       *
+       * So the guard is evaluated on "has any text arrived", independently of whether a block exists.
+       */
+      const text = snap?.isNew ? String(snap.text ?? '') : '';
+      const progressed = text.length > emitted.length && text.startsWith(emitted);
+
+      /*
+       * A THINKING PAGE IS NOT A DEAD PAGE.
+       *
+       * MEASURED, by the person reading Brave: a 1000-word request was answered, but this call abandoned it
+       * after five silent seconds with "no text arrived". The page had been writing its reasoning into a
+       * Thinking block the whole time - a different element from the answer, so nothing this reader watches
+       * had changed. Three earlier theories blamed the site; the person's screenshot showed the answer.
+       *
+       * So the page's total text length is sampled as a sign of life. It never decides what to EMIT - the
+       * answer element does that - but any growth in it resets the pause clock, because it means work is
+       * happening.
+       */
+      const aliveNow = Number(snap?.alive) || 0;
+      if (aliveNow !== lastAlive) {
+        lastAlive = aliveNow;
+        lastChange = Date.now();
+      }
+
+      /*
+       * THE PAUSE RULE.
+       *
+       * A pause is measured from the last sign of life, not from the start of the call: launching a browser or
+       * opening a fresh chat takes seconds and is not a hang. Once something has been sent, five silent
+       * seconds is already abnormal - the page either answered or it did not.
+       *
+       * Reported as its own error code so a test can tell "the page stalled" apart from "the page was slow",
+       * and can stop and clean up rather than carrying on to the next case.
+       */
+      const sinceProgress = Date.now() - lastChange;
+      /*
+       * A search call needs a longer budget, and that is not a loophole.
+       *
+       * MEASURED: the first live search test stalled at 5.1 seconds with nothing to show. A web search
+       * legitimately spends time fetching before it writes any answer text, so a five-second silence is the
+       * page working, not the page dead. Applying the plain-chat rule here would abort every search.
+       *
+       * The rule is kept for what it was made for - an ordinary message that produces nothing - and a search
+       * that produces nothing for thirty seconds is still treated as dead.
+       */
+      const stallBudget = search ? Math.max(STALL_MS, SEARCH_STALL_MS) : STALL_MS;
+      if (sinceProgress > stallBudget) {
+        if (process.env.DEBUG_WEB_CHAT) {
+          console.error(`[stall] no progress for ${sinceProgress}ms (limit ${stallBudget}ms) - abandoning the call`);
+        }
+        throw new WebChatError(
+          `the page went silent for ${(sinceProgress / 1000).toFixed(1)}s after the message was sent ` +
+            `(limit ${(stallBudget / 1000).toFixed(1)}s). No text arrived, so this was abandoned rather than waited out.`,
+          'STALLED',
+        );
+      }
+
+      if (!progressed) {
+        if (process.env.DEBUG_WEB_CHAT) {
+          console.error(`[poll] no progress (found=${snap?.found} isNew=${Boolean(snap?.isNew)} len=${text.length})`);
+        }
+        staleReads += 1;
+        /*
+         * Nothing has changed for a while and the answer has not started. Either the page is throttled or the
+         * site is not generating. Re-assert the active state once before blaming anything - that is the one
+         * action available from this side.
+         */
+        if (!nudged && !sawAnyText && staleReads * POLL_MS > 6000) {
+          nudged = true;
+          await keepPageActive(cdp);
+          // The nudge is a sign of life: it must not itself count towards the pause budget.
+          lastChange = Date.now();
+          continue;
+        }
+      } else {
+        staleReads = 0;
+      }
+
+      if (!sawAnyText && Date.now() - started > FIRST_TOKEN_TIMEOUT_MS) {
+        const secs = Math.round(FIRST_TOKEN_TIMEOUT_MS / 1000);
+        throw new WebChatError(
+          nudged
+            ? `chat.deepseek.com produced no text within ${secs}s even after being told the page is active. ` +
+              'The account may be rate limited, or a proof-of-work challenge is being shown - open the ' +
+              'browser window once and look at the page.'
+            : `chat.deepseek.com produced no text within ${secs}s (the account may be rate limited, or a ` +
+              'proof-of-work challenge is being shown)',
+          'NO_FIRST_TOKEN',
+        );
+      }
+
+      if (!snap?.isNew) continue;
+
+      if (progressed) {
+        const delta = text.slice(emitted.length);
+        emitted = text;
+        lastChange = Date.now();
+        sawAnyText = true;
+        yield { text: delta };
+      } else if (text !== emitted) {
+        // The block changed in a way that is not a pure append: a re-render mid-stream, or a replaced
+        // answer. Emit ONLY the characters not yet sent, found by the longest common prefix.
+        //
+        // An earlier version re-emitted the entire text on this path, and the consumer - which appends
+        // every chunk - produced the answer twice over. A streaming adapter may never send text twice.
+        let n = 0;
+        const max = Math.min(emitted.length, text.length);
+        while (n < max && emitted[n] === text[n]) n += 1;
+        const tail = text.slice(n);
+        emitted = text;
+        lastChange = Date.now();
+        sawAnyText = true;
+        if (tail) yield { text: tail };
+      }
+
+      const quiet = Date.now() - lastChange;
+      if (sawAnyText && quiet >= SETTLE_MS) break;
+    }
+
+    // With search on, the sources are only readable once the answer has settled, so they are collected
+    // at the end and returned alongside the text rather than streamed.
+    let sources = { domains: [], links: [] };
+    if (search) {
+      sources = await cdp.evaluate(READ_SOURCES, { timeout: 8000 }).catch(() => sources);
+    }
+
+    /*
+     * Put the switches back before handing over the answer.
+     *
+     * Done here rather than in a finally because a generator that is abandoned mid-yield never reaches one,
+     * and the next call restores leftovers at its start. Between the two, a leftover switch survives at most
+     * one turn.
+     */
+    if (this.#turnedOn.length) {
+      await this.restoreToggles(cdp, this.#turnedOn);
+      this.#turnedOn = [];
+    }
+
+    yield { done: true, text: emitted, sources, switches: { deepThink, search } };
+  }
+
+  /**
+   * Detach from the page, leaving the browser running.
+   *
+   * This is what the HOST wants on dispose: the person's browser tab and session survive a plugin reload.
+   * It is NOT what a one-shot script wants, which is the bug that produced this comment - see the exit hook
+   * installed in #connect().
+   */
+  close() {
+    this.#cdp?.close();
+    this.#cdp = null;
+  }
+
+  /**
+   * Take ownership of the browser this session launches, and give it back on exit.
+   *
+   * THE BUG THIS FIXES
+   *     Scripts that drive the engine call close() when they finish, which detaches but leaves Brave running.
+   *     Measured: of the twenty-three dev scripts that construct this class, twenty-three leaked a browser.
+   *     A window would appear on the person's desktop minutes after a test had "finished", with nothing to
+   *     explain it - and it looks like the plugin is spying on them.
+   *
+   *     So a browser this object LAUNCHED is killed when the process exits, and only that one: a browser it
+   *     merely attached to belongs to somebody else and is left alone. The distinction is recorded when the
+   *     launch happens, not guessed afterwards.
+   */
+  #claimOnExit() {
+    if (this.#exitHookInstalled) return;
+    this.#exitHookInstalled = true;
+    const kill = () => {
+      if (!this.#launchedByUs) return;
+      this.#launchedByUs = false;
+      /*
+       * Synchronous, because an exit handler gets no chance to await anything.
+       *
+       * `taskkill /F /T` takes the child processes with it - a Chromium launch is a tree, and killing only
+       * the parent leaves the renderer holding the profile lock.
+       */
+      try {
+        const pid = ownerOfPortSync(this.#port);
+        if (pid) execFileSync('taskkill', ['/PID', String(pid), '/F', '/T'], { stdio: 'ignore', timeout: 4000 });
+      } catch {
+        /* already gone, or not permitted: nothing else to try */
+      }
+    };
+    process.once('exit', kill);
+    // Ctrl-C in a terminal does not always reach 'exit'; these make it reliable.
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      try {
+        process.once(signal, () => {
+          kill();
+          process.exit(130);
+        });
+      } catch {
+        /* a signal this platform does not have */
+      }
+    }
+  }
+}