dsh-builtin-browser 0.2.0 → 0.3.1

package/src/browser-electron/entry.ts

@@ -16,7 +16,12 @@ import z from '@deepseek-ai/schemastery'
 import type { BrowserRuntime } from '../browser/runtime.js'
 import { ElectronBrowserProvider } from './provider.js'
 import type { ElectronBrowserViewHost } from './provider.js'
+import { randomUUID } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
 import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js'
+import { DesktopBridgeViewHost } from './desktop-bridge-host.js'
+import { detectBrowser, SystemBrowserViewHost } from './system-browser.js'
 import { SettingsStore } from './settings-store.js'
 
 export {
@@ -61,30 +66,96 @@ export const Config: z<Config> = z.object({
 
 /** Register the Electron browser provider with `ctx.browser`. */
 export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config): void {
-  // External host (desktop shell) wins; otherwise self-host. The self-hosted
-  // child is disposed with the fiber, mirroring the shell's lifetime.
-  const host: ElectronBrowserViewHost = config.viewHost ?? new RemoteElectronViewHost(defaultHostMainPath())
   // One settings document per plugin instance: the settings panel writes it, the
   // provider reads it live, and both ends agree on the same file.
   const settings = new SettingsStore()
-  // Own the disposer on THIS plugin's fiber: registerBrowserProvider's effect
-  // is bound to the seam's own fiber (the browser row), so a reload of this
-  // row would otherwise collide with the still-registered provider
-  // (BROWSER_DUPLICATE_PROVIDER) or leave a stale provider behind.
-  const unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, {
+  installSettingsRoute(ctx, settings)
+
+  const providerConfig = {
     httpOnly: config.httpOnly,
     downloadDir: config.downloadDir,
     snapshotMaxElements: config.snapshotMaxElements,
     contentMaxChars: config.contentMaxChars,
     settings: () => settings.get(),
-  }))
+  }
+
+  // A host supplied by the composition (the desktop shell's own seam) wins and is
+  // synchronous, so registration stays synchronous on that path.
+  if (config.viewHost !== undefined) {
+    const external = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost as ElectronBrowserViewHost, providerConfig))
+    ctx.effect(() => () => { external() })
+    return
+  }
+
+  // Otherwise start self-hosted — a working browser from the first call, on every
+  // surface — and upgrade to the desktop sidebar if this machine has one. The
+  // upgrade is deliberately a swap of the whole provider: the two carriers own
+  // different lifetimes (a spawned child vs. the shell's view), and pretending
+  // otherwise would leave a stray window behind.
+  const selfHosted = new RemoteElectronViewHost(defaultHostMainPath())
+  let unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(selfHosted, providerConfig))
+  let upgraded = false
+
   ctx.effect(() => () => {
     unregister()
-    if (config.viewHost === undefined && host instanceof RemoteElectronViewHost) {
-      host.dispose()
-    }
+    selfHosted.dispose()
   })
-  installSettingsRoute(ctx, settings)
+
+  /**
+   * Swap the provider to another carrier, releasing the previous one.
+   * @param host - the carrier to adopt.
+   * @param note - a one-line description for the log.
+   */
+  const adopt = (host: ElectronBrowserViewHost, note: string): void => {
+    if (upgraded) { host.dispose?.(); return }
+    upgraded = true
+    try {
+      unregister()
+      unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, providerConfig))
+      selfHosted.dispose()
+      ctx.logger?.info?.(`dsh-builtin-browser: ${note}`)
+    } catch (error) {
+      // Never leave the surface without a provider.
+      unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(
+        new RemoteElectronViewHost(defaultHostMainPath()), providerConfig))
+      ctx.logger?.warn?.(`dsh-builtin-browser: could not adopt ${note} (${String(error)})`)
+    }
+  }
+
+  // A browser the user explicitly asked for outranks every automatic choice: the
+  // whole point of the setting is that they know which browser they want. It is
+  // launched with a plugin-owned profile, so their own windows are untouched.
+  //
+  // Registration is INERT: constructing the host starts nothing. The browser only
+  // launches when a command actually needs a page, so merely running DSH never
+  // spawns a browser window. (An earlier version launched it here, which meant a
+  // browser appeared the moment the plugin loaded — reported and fixed.)
+  const channel = settings.get().browser.channel
+  if (channel !== 'bundled') {
+    const detected = detectBrowser(channel)
+    if (detected === undefined) {
+      ctx.logger?.warn?.(`dsh-builtin-browser: ${channel} was requested but no installation was found; using the bundled browser`)
+    } else {
+      const home = process.env.DSH_HOME ?? homedir()
+      // Login state lives in the browser profile, so the cookies setting decides where
+      // that profile goes: a stable directory keeps the user signed in across restarts
+      // (the point of using their own browser), while turning persistence off gets a
+      // throwaway directory that is removed when the browser is released.
+      const persist = settings.get().cookies.persist
+      const profileDir = persist
+        ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
+        : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`)
+      adopt(new SystemBrowserViewHost(detected, profileDir, [], persist ? undefined : profileDir),
+        `will drive the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`)
+    }
+  }
+
+  void DesktopBridgeViewHost.discover().then(sidebar => {
+    // No bridge (plain `dsh web`, an older desktop build, or a shell that already
+    // exited): keep self-hosting, which is what every surface has always done.
+    if (sidebar === undefined) return
+    adopt(sidebar, 'driving the desktop sidebar browser')
+  }).catch(() => { /* discovery never throws; keep self-hosting */ })
 }
 
 /** Route the settings panel reads and writes. */

package/src/browser-electron/history-store.ts

@@ -89,15 +89,24 @@ export class HistoryStore {
   /**
    * Read visits, newest first. Unparseable lines are skipped; entries older
    * than the age limit are filtered out but left on disk until the next prune.
-   * @param options - optional result cap and domain filter.
+   * @param options - optional result cap plus three filters: `domain` (hostname),
+   *   `query` (substring of the URL or title) and `session` (the task that visited
+   *   it). Filters compose, so "the pages THIS task opened on that host" is one call.
    * @returns the matching visits, newest first.
    */
-  list(options: { readonly limit?: number; readonly domain?: string } = {}): VisitedPage[] {
+  list(options: { readonly limit?: number; readonly domain?: string; readonly query?: string; readonly session?: string } = {}): VisitedPage[] {
     const all = this.readAll()
     const cutoff = Date.now() - this.maxAgeMs
     const domain = options.domain?.toLowerCase()
+    const query = options.query?.toLowerCase()
+    const session = options.session
     const matches = all.filter(page => {
       if (page.at < cutoff) return false
+      if (session !== undefined && page.session !== session) return false
+      if (query !== undefined) {
+        const haystack = `${page.url}\n${page.title ?? ''}`.toLowerCase()
+        if (!haystack.includes(query)) return false
+      }
       if (domain === undefined) return true
       try {
         return new URL(page.url).hostname.toLowerCase().includes(domain)

package/src/browser-electron/provider.ts

@@ -13,7 +13,7 @@ import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
 import { HistoryStore, type VisitedPage } from './history-store.js'
 import type { BrowserSettings } from './settings-store.js'
-import { paintCursor, type CursorAction } from './virtual-cursor.js'
+import { forgetCursor, paintCursor, type CursorAction } from './virtual-cursor.js'
 import type {
   BrowserA11yRequest,
   BrowserA11yResult,
@@ -185,6 +185,31 @@ export interface ElectronBrowserViewHost {
    * @param handler - called with the group (session) key; must not throw.
    */
   onViewClosed?(handler: (windowId: string) => void): void
+  /**
+   * Release the service's page(s) without ending the plugin's own lifetime.
+   *
+   * Only carriers that outlive a browser session need this. A self-hosted window
+   * dies with its view, but the desktop shell's sidebar keeps running no matter
+   * what the plugin does — so "release the browser when the session ends"
+   * (settings: ui.closeWithSession) has to be asked for explicitly there.
+   * @returns a promise that settles once the release was attempted.
+   */
+  releasePage?(): Promise<void>
+  /**
+   * Fold the carrier's presentation away while keeping the page alive.
+   *
+   * The desktop sidebar keeps running regardless of the plugin, so "do not take
+   * over the screen" (settings: ui.autoExpandOnce = false) can only be honoured by
+   * asking the shell to fold it. A self-hosted window has no such state and simply
+   * does not implement this.
+   * @returns a promise that settles once the fold was attempted.
+   */
+  collapse?(): Promise<void>
+  /**
+   * Release everything the carrier owns (a spawned browser, a socket, a child).
+   * Called when the plugin stops using it, never while it is still in service.
+   */
+  dispose?(): void
 }
 
 /**
@@ -670,6 +695,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
   private async settleDocument(handle: ElectronViewHandle, before: string, signal?: AbortSignal): Promise<void> {
     const started = Date.now()
     const deadline = started + SETTLE_TIMEOUT_MS
+    // The document is being replaced, so the synthetic pointer drawn into the old one
+    // is gone. Dropping the remembered position is what lets it be painted again:
+    // without this, a paint at coincidentally identical coordinates would be skipped
+    // and the pointer would never come back after a navigation.
+    forgetCursor(handle)
     for (;;) {
       if (signal?.aborted === true) return
       // A probe failure is expected while the navigation commits (the context is
@@ -1180,21 +1210,39 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // iframes stay opaque — the browser forbids reading them).
       let content = ''
       if (fmt === 'txt') {
-        const parts = []
-        const textWalk = (node) => {
-          if (node.nodeType === Node.TEXT_NODE) { const t = (node.textContent || '').trim(); if (t) parts.push(t); return }
-          if (node.nodeType !== Node.ELEMENT_NODE) return
-          const tag = node.tagName.toLowerCase()
-          if (tag === 'script' || tag === 'style' || tag === 'noscript') return
-          if (tag === 'iframe') {
-            try { const d = node.contentDocument; if (d && d.body) for (const c of d.body.childNodes) textWalk(c) } catch { /* cross-origin */ }
-            return
+        // Prefer the browser's own rendered text.
+        //
+        // Walking text nodes and joining them is not equivalent: pages that wrap
+        // every character in its own element — one-character spans for a
+        // per-character animation, which is common — produce one text node per
+        // letter, and joining those with spaces turns every word into a column of
+        // letters. The rendered text reassembles them the way a reader sees them,
+        // and it also honours visibility, so hidden text does not leak out.
+        // (No backticks in this comment: it lives inside a template literal.)
+        const rendered = typeof root.innerText === 'string' ? root.innerText : ''
+        if (rendered.trim() !== '') {
+          content = rendered
+        } else {
+          // Fallback for nodes without layout (a detached root, or a fragment):
+          // collect text directly, still piercing shadow roots and same-origin
+          // iframes, and join without inventing separators beyond what the markup
+          // already implies.
+          const parts = []
+          const textWalk = (node) => {
+            if (node.nodeType === Node.TEXT_NODE) { const t = (node.textContent || '').trim(); if (t) parts.push(t); return }
+            if (node.nodeType !== Node.ELEMENT_NODE) return
+            const tag = node.tagName.toLowerCase()
+            if (tag === 'script' || tag === 'style' || tag === 'noscript') return
+            if (tag === 'iframe') {
+              try { const d = node.contentDocument; if (d && d.body) for (const c of d.body.childNodes) textWalk(c) } catch { /* cross-origin */ }
+              return
+            }
+            if (node.shadowRoot) for (const c of node.shadowRoot.childNodes) textWalk(c)
+            for (const child of node.childNodes) textWalk(child)
           }
-          if (node.shadowRoot) for (const c of node.shadowRoot.childNodes) textWalk(c)
-          for (const child of node.childNodes) textWalk(child)
+          textWalk(root)
+          content = parts.join(' ')
         }
-        textWalk(root)
-        content = parts.join(' ')
       }
       else if (fmt === 'html') content = root.outerHTML || ''
       else if (fmt === 'json') content = JSON.stringify(root)
@@ -1270,6 +1318,18 @@ export class ElectronBrowserProvider implements BrowserProvider {
       x = Number(out.x)
       y = Number(out.y)
     } else {
+      // A coordinate only exists because somebody read a picture. Under the
+      // non-visual strategy the plugin must not accept one: a model that cannot
+      // see cannot have produced it, so the coordinates are either copied from an
+      // earlier vision pass or invented, and honouring them turns a silent
+      // mis-click into a mystery. Refusing here, with a message that says what to
+      // do instead, converts that into a usable instruction.
+      if (this.settingsSource !== undefined && this.settingsSource().vision.strategy === 'nonVisual') {
+        throw new BrowserError(
+          'browser: the configured non-visual strategy refuses coordinate clicks — pass a semantic target instead, e.g. target { by: "text", value: "Sign in" }, which locates the element from the DOM and clicks its centre',
+          'BROWSER_NON_VISUAL_COORDINATES',
+        )
+      }
       x = request.x
       y = request.y
     }
@@ -1298,7 +1358,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
     // Paint before the press so the ripple is already on screen when the click
     // lands — the cursor exists to show the human WHERE the agent acts.
-    this.showCursor(handle, x, y, 'click')
+    // Name the operation in the overlay: the pointer is the "agent is driving this
+    // tab" signal, so the bubble is what lets a human follow along without the log.
+    this.showCursor(handle, x, y, 'click', 'click', true)
     const release = (): void => {
       void handle
         .sendCommand('Input.dispatchMouseEvent', {
@@ -1351,7 +1413,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       const locateTab = this.activeTab(s)
       const out = await this.runTargetScript(locateTab, script, locateMs, signal, 'BROWSER_TYPE_FAILED', 'browser: type')
       const cursorPoint = scriptPoint(out)
-      if (cursorPoint !== undefined) this.showCursor(locateTab.handle, cursorPoint.x, cursorPoint.y, 'click')
+      if (cursorPoint !== undefined) this.showCursor(locateTab.handle, cursorPoint.x, cursorPoint.y, 'click', 'type', true)
     }
     const text = 'text' in request ? request.text : ''
     const timeoutMs = 30_000
@@ -2274,7 +2336,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * @param options - result cap and an optional hostname filter.
    * @returns the matching visits, or an empty list when history is disabled.
    */
-  visited(options: { readonly limit?: number; readonly domain?: string } = {}): readonly VisitedPage[] {
+  visited(options: { readonly limit?: number; readonly domain?: string; readonly query?: string; readonly session?: string } = {}): readonly VisitedPage[] {
     return this.historyStore?.list(options) ?? []
   }
 
@@ -2287,10 +2349,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * @param x - viewport x in CSS pixels.
    * @param y - viewport y in CSS pixels.
    * @param action - click pulses a ripple; move only relocates.
+   * @param label - short description of the operation, shown beside the pointer.
+   * @param force - paint even when the pointer is already there (a click ripple must
+   *   always play; a bare move need not repeat).
    */
-  private showCursor(handle: ElectronViewHandle, x: number, y: number, action: CursorAction): void {
+  private showCursor(handle: ElectronViewHandle, x: number, y: number, action: CursorAction, label?: string, force = false): void {
     if (this.settingsSource !== undefined && !this.settingsSource().ui.virtualCursor) return
-    paintCursor(handle, x, y, action, (target, expression) => handleSendEvaluate(target, expression))
+    paintCursor(handle, x, y, action, (target, expression) => handleSendEvaluate(target, expression), label, force)
   }
 
   /**
@@ -2370,6 +2435,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (existing !== undefined) {
       this.sessions.delete(session)
       for (const tab of existing.tabs) this.host.destroyView(tab.handle)
+      // Releasing the browser at session end is a setting, not fixed behaviour
+      // (requirements §3). A self-hosted carrier already tore its window down with
+      // the views above; the desktop's sidebar does not, so it is asked explicitly
+      // — and its cookies plus the browsing history outlive the page either way.
+      if (this.settingsSource !== undefined && this.settingsSource().ui.closeWithSession) {
+        void this.host.releasePage?.().catch(() => undefined)
+      }
     }
     return Promise.resolve()
   }
@@ -2481,19 +2553,46 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
   }
 
-  /** Report a failed user action to the host UI (toolbar), when supported. */
+  /**
+   * Report a failed user action to the host UI (toolbar), when supported.
+   *
+   * Two properties matter here, because this runs inside the catch of an async
+   * handler (issue #16):
+   *  - the receiver must be preserved. Reading the method off the host and calling
+   *    it unbound runs the host's implementation with `this === undefined`, so its
+   *    very first statement (`void this.ready()`) throws, the throw escapes the
+   *    async catch as an unhandled rejection, and the whole DSH host exits;
+   *  - this method must be incapable of throwing. Reporting a failed action is
+   *    diagnostics: it can never be allowed to become the failure.
+   */
   private notifyUserActionError(action: BrowserUserAction, error: unknown): void {
-    const notify = (this.host as { notifyUserActionError?(windowId: string, message: string): void }).notifyUserActionError
     const message = `action ${action.type} failed: ${String(error)}`
-    if (typeof notify === 'function') {
-      notify(action.windowId, message)
-    } else {
-      process.stderr.write(`[dsh-browser] user action failed: ${message}\n`)
+    let reported = false
+    try {
+      const host = this.host as { notifyUserActionError?(windowId: string, message: string): void }
+      const notify = host.notifyUserActionError
+      if (typeof notify === 'function') {
+        // Called on its owner: an unbound call here kills the host process.
+        notify.call(host, action.windowId, message)
+        reported = true
+      }
+    } catch (notifyError) {
+      // Contained on purpose; the log line below still carries the original cause.
+      process.stderr.write(`[dsh-browser] host notify failed: ${String(notifyError)}\n`)
     }
+    if (!reported) process.stderr.write(`[dsh-browser] user action failed: ${message}\n`)
   }
 
   /** Ask the host to show the active tab's view, carrying the session label. */
   private showActive(s: Session): void {
+    // §3: whether the agent's page takes over the screen is the user's choice, not
+    // a fixed behaviour. With auto-expand off the page still exists and is still
+    // driven — it is simply folded away, so the agent works without claiming the
+    // sidebar. Carriers that own no presentation (self-hosted) ignore the call.
+    if (this.settingsSource !== undefined && !this.settingsSource().ui.autoExpandOnce) {
+      void this.host.collapse?.().catch(() => undefined)
+      return
+    }
     this.host.showView?.(this.activeTab(s).handle, s.label)
   }
 

package/src/browser-electron/remote-host.ts

@@ -799,12 +799,27 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     return this.electronAvailable
   }
 
-  /** Ensure the child is up and ready (lazy on first use; restarts after a crash). */
+  /**
+   * Ensure the child is up and ready (lazy on first use; restarts after a crash).
+   *
+   * Never throws synchronously. Callers are fire-and-forget
+   * (`void this.ready().then(…).catch(…)`), and a synchronous throw escapes their
+   * `.catch` entirely — the shape that let a failed toolbar report take the whole
+   * DSH host down (issue #16). A disposed host is reported as a rejected promise
+   * instead, which those callers already handle.
+   */
   private ready(): Promise<void> {
     // Fail fast on a disposed host: a recovery path can re-enter ready() after
     // dispose() cleared its state, and starting fresh here would spawn a child
     // nobody will ever kill.
-    if (this.disposed) throw new HostGoneError('browser host disposed')
+    if (this.disposed) {
+      const gone = Promise.reject(new HostGoneError('browser host disposed'))
+      // Keep the rejection observable to callers while marking it handled here:
+      // a fire-and-forget caller that forgot to attach a handler must not turn
+      // this into an unhandled rejection either.
+      gone.catch(() => undefined)
+      return gone
+    }
     if (this.readyPromise !== undefined) return this.readyPromise
     const started = this.start()
     const wrapped = started.catch(error => {

package/src/browser-electron/settings-store.ts

@@ -12,6 +12,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
+import type { BrowserChannel } from './system-browser.js'
 
 /** Vision/operation strategy the provider prefers when the model can see. */
 export type VisionStrategy = 'auto' | 'nonVisual'
@@ -41,6 +42,10 @@ export interface BrowserSettings {
   readonly vision: {
     readonly strategy: VisionStrategy
   }
+  /** Which browser binary carries the agent's pages. */
+  readonly browser: {
+    readonly channel: BrowserChannel
+  }
   /** Whether the agent may read cookies / export login state. */
   readonly credentials: {
     readonly allowRead: boolean
@@ -53,6 +58,10 @@ export const DEFAULT_SETTINGS: BrowserSettings = {
   cookies: { persist: true },
   ui: { autoExpandOnce: true, closeWithSession: false, virtualCursor: true },
   vision: { strategy: 'auto' },
+  // Bundled by default: it needs nothing installed, and on the desktop the carrier
+  // is the sidebar anyway. Choosing a system browser is an explicit opt-in because
+  // it starts a real Chrome/Edge with its own profile.
+  browser: { channel: 'bundled' },
   credentials: { allowRead: true },
 }
 
@@ -71,6 +80,18 @@ function bool(value: unknown, fallback: boolean): boolean {
   return typeof value === 'boolean' ? value : fallback
 }
 
+/**
+ * Coerce the browser channel, keeping the default when it is not one of the
+ * known choices. A hand-edited typo must not silently select a different browser.
+ * @param value - the raw value from the settings document.
+ * @returns a valid channel.
+ */
+function resolveChannel(value: unknown): BrowserChannel {
+  return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled'
+    ? value
+    : DEFAULT_SETTINGS.browser.channel
+}
+
 /** Coerce one positive-integer field, keeping the default when invalid. */
 function count(value: unknown, fallback: number): number {
   return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback
@@ -96,6 +117,7 @@ export function resolveSettings(raw: unknown): BrowserSettings {
   const ui = section(source, 'ui')
   const vision = section(source, 'vision')
   const credentials = section(source, 'credentials')
+  const browser = section(source, 'browser')
   return {
     history: {
       enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
@@ -109,6 +131,7 @@ export function resolveSettings(raw: unknown): BrowserSettings {
       virtualCursor: bool(ui.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
     },
     vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
+    browser: { channel: resolveChannel(browser.channel) },
     credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
   }
 }
@@ -153,7 +176,13 @@ export class SettingsStore {
     }
     if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs) return this.cached
     try {
-      this.cached = text === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(text))
+      // A leading BOM is what ordinary Windows editors (Notepad, PowerShell's
+      // `Set-Content -Encoding utf8`) leave behind, and `JSON.parse` rejects it.
+      // Without this strip, hand-editing the settings file silently discarded every
+      // value in it: the document looked correct, and the plugin quietly ran on
+      // defaults — including switches the user had just turned off.
+      const body = text?.replace(/^\uFEFF/, '')
+      this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body))
     } catch {
       // Malformed JSON: behave as defaults rather than fail startup.
       this.cached = DEFAULT_SETTINGS