dsh-builtin-browser 0.4.0 → 0.4.2

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

@@ -19,9 +19,11 @@
  * that connection proves knowledge of the random per-spawn token (passed to
  * the child via its stdin (first line, never in argv). A local process that
  * connects to the loopback port without the token can neither impersonate the
- * child nor inject replies — it is disconnected immediately. Commands are
- * only written after the hello authenticates, so a spoofed socket never
- * sees traffic.
+ * child nor inject replies — it is disconnected as soon as its first line
+ * arrives. Commands are only written after the hello authenticates, and every
+ * other inbound op (including the fire-and-forget `userAction` / `viewClosed`
+ * notifications) is dispatched only once that check has passed, so an
+ * unauthenticated peer can neither read traffic nor drive a session.
  * @module dsh-browser/browser-electron/remote-host
  */
 
@@ -501,6 +503,9 @@ class ElectronChildClient {
       const line = `${hostStamp()} spawn error: ${String(error)} electron=${electron} hostMain=${this.hostMainPath}`
       process.stderr.write(`[dsh-browser host] ${line}\n`)
       appendHostLog(`${line}\n`)
+      // The cached availability answer is retired by `onExit` below, which this reaches
+      // through fail(): the decision needs the host's view of what is on disk, not the
+      // client's.
       this.fail(new Error(`dsh-builtin-browser: browser host failed to start: ${String(error)}`))
     })
     this.child.on('exit', (code, signal) => {
@@ -523,11 +528,37 @@ class ElectronChildClient {
     })
   }
 
+  /**
+   * Drop the escalation kill once there is nothing left for it to target.
+   *
+   * Without this the timer would keep the parent's event loop alive for its full grace period
+   * after exactly the ordinary exit it was armed to catch as the bad case — and the child does
+   * not need killing once `fail()` has run for it.
+   */
+  private clearKillGrace(): void {
+    if (this.killGraceTimer === undefined) return
+    clearTimeout(this.killGraceTimer)
+    this.killGraceTimer = undefined
+  }
+
+  /** Drop the "did not authenticate" deadline once it can no longer be meaningful. */
+  private clearHelloTimer(): void {
+    if (this.helloTimer === undefined) return
+    clearTimeout(this.helloTimer)
+    this.helloTimer = undefined
+  }
+
   /** Reject everything in flight, mark the client dead, and notify the host. */
   private fail(err: Error): void {
     if (this.dead) return
     this.dead = true
     this.connected = false
+    // The authentication deadline outlives the socket it was armed for otherwise: it is
+    // keyed on `awaitingHello` alone, so a client that already failed on some other path
+    // kept a live timer until it fired (harmless, but it is a dangling timer in a process
+    // that may be shutting down).
+    this.clearHelloTimer()
+    this.clearKillGrace()
     // Tag every failure as "host gone" so the view layer can tell a dead host
     // apart from a page-level error and rebuild against a fresh child.
     const wrapped = err instanceof HostGoneError ? err : new HostGoneError(err.message)
@@ -600,19 +631,34 @@ class ElectronChildClient {
         // Non-protocol line; ignore.
         continue
       }
-      if (msg.op === 'userAction') {
-        // Fire-and-forget notification from the child's own UI (toolbar):
-        // there is no reply and no pending id — route it straight to the
-        // host's user-action handler (which the provider registered).
-        this.onUserAction?.(msg.action as BrowserUserAction)
-        continue
-      }
-      if (msg.op === 'viewClosed') {
-        // Fire-and-forget notification from the child's own UI: the human closed
-        // the window, so the interface that session showed is gone. The provider
-        // decides what that ends — browsing history and login state survive on
-        // disk, only the session itself does not.
-        this.onViewClosed?.(typeof msg.windowId === 'string' ? msg.windowId : '')
+      if (msg.op === 'userAction' || msg.op === 'viewClosed') {
+        // A fire-and-forget notification from the child's own UI (toolbar). These carry no
+        // reply and no pending id, and they hand the provider a session-level verb — so they
+        // are dispatched ONLY once the peer has proved it knows the spawn token.
+        //
+        // They used to be handled before the hello check, while the module comment claimed an
+        // unauthenticated peer "is disconnected immediately … a spoofed socket never sees
+        // traffic". Both were wrong: any loopback process that won the race for the single
+        // accepted socket could inject `viewClosed` and end the human's browser session
+        // before the token check rejected it. Only the loopback interface can connect, so
+        // this is a same-machine race rather than a remote attack — which is exactly the
+        // kind of thing the token exists to close.
+        if (this.awaitingHello) {
+          this.awaitingHello = false
+          this.clearHelloTimer()
+          this.socket?.destroy()
+          this.fail(new Error('dsh-builtin-browser: browser host sent a notification before authenticating'))
+          return
+        }
+        if (msg.op === 'userAction') {
+          // Route it straight to the host's user-action handler (which the provider registered).
+          this.onUserAction?.(msg.action as BrowserUserAction)
+        } else {
+          // The human closed the window, so the interface that session showed is gone. The
+          // provider decides what that ends — browsing history and login state survive on
+          // disk, only the session itself does not.
+          this.onViewClosed?.(typeof msg.windowId === 'string' ? msg.windowId : '')
+        }
         continue
       }
       if (this.awaitingHello) {
@@ -620,10 +666,7 @@ class ElectronChildClient {
         // Anything else (or a wrong token) means a spoofed connection: drop
         // it and fail every pending call rather than trust the line.
         this.awaitingHello = false
-        if (this.helloTimer !== undefined) {
-          clearTimeout(this.helloTimer)
-          this.helloTimer = undefined
-        }
+        this.clearHelloTimer()
         if (msg.op !== 'hello' || msg.token !== this.token) {
           this.socket?.destroy()
           this.fail(new Error('dsh-builtin-browser: browser host authentication failed'))
@@ -673,10 +716,38 @@ class ElectronChildClient {
     })
   }
 
-  /** Terminate the child. */
+  /**
+   * How long the child gets to exit by itself after the socket closes, before it is killed.
+   * The child quits on that signal, so in practice this is a few dozen milliseconds; the timer
+   * exists for the case where it does not, and it is deliberately NOT unref'd — the parent must
+   * stay alive long enough to enforce it, or the escalation would be dropped with the process.
+   */
+  private static readonly KILL_GRACE_MS = 500
+  private killGraceTimer: NodeJS.Timeout | undefined
+
+  /**
+   * Terminate the child, after giving it the chance to shut down properly.
+   *
+   * The socket goes first, because that is the signal the child actually handles: its `close`
+   * listener quits the app, and a normal quit is what lets Chromium write its profile out. Only
+   * a child still alive after the grace period is killed outright.
+   *
+   * This order used to be the other way round, justified by a comment claiming the child's own
+   * path "closes its window and flushes the profile", which made killing first the safer order.
+   * Both halves of that were wrong: the path ran `app.exit(0)`, which skips before-quit/will-quit
+   * and does not flush Chromium's profile writers at all; and on Windows `child.kill()` is
+   * TerminateProcess, which lands before the child can run any handler whatsoever. So the
+   * graceful path that comment was protecting never got to start, and the profile went
+   * unflushed on every single dispose.
+   */
   kill(): void {
+    this.clearHelloTimer()
     try { this.socket?.destroy() } catch { /* already closed */ }
-    this.child.kill()
+    const child = this.child
+    this.clearKillGrace()
+    this.killGraceTimer = setTimeout(() => {
+      try { child.kill() } catch { /* already gone */ }
+    }, ElectronChildClient.KILL_GRACE_MS)
   }
 }
 
@@ -730,6 +801,30 @@ const PROBE_RETRY_MS = (() => {
   return Number.isFinite(raw) && raw >= 0 ? raw : 30000
 })()
 
+/**
+ * Retry schedule for a browser host that will not stay up, in milliseconds, indexed by the
+ * number of consecutive failed starts (see {@link RemoteElectronViewHost.noteStartFailure}).
+ *
+ * The first entry is 0 on purpose: an ordinary one-off death must still heal on the very
+ * next call, which is the behaviour remote-host-recovery.test.mjs pins. From the second
+ * failure on, each attempt is spaced. `available()` can only answer "is there a binary",
+ * so a binary that exists and crashes on every launch (`code=1` with empty stderr) would
+ * otherwise produce an endless crash loop, one window per tool call, with nothing to make
+ * it stop.
+ */
+const START_RETRY_SCHEDULE_MS: readonly number[] = [0, 500, 2_000, 8_000, 30_000]
+
+/** Attempts after which the host stops retrying immediately and keeps the longest delay. */
+const START_FAILURES_MAX = START_RETRY_SCHEDULE_MS.length
+
+/** Two reports within this window describe the same dying child, not two attempts. */
+const START_FAILURE_DEDUPE_MS = 1_000
+
+/** Render a delay for a human-readable log line. */
+function formatDelay(ms: number): string {
+  return ms >= 1_000 ? `${(ms / 1_000).toFixed(1)}s` : `${String(ms)}ms`
+}
+
 /**
  * Self-hosted view host: spawns the plugin's Electron child on first use and
  * keeps it alive until dispose(). Fallback when no desktop shell provides
@@ -747,6 +842,12 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   private electronAvailable: boolean | undefined
   /** Earliest time the next probe may run after a negative one. */
   private nextProbeAt = 0
+  /** Consecutive child starts that did not survive; drives {@link startRetryAt}. */
+  private startFailures = 0
+  /** Earliest time `ready()` may spawn another child after a failed start. */
+  private startRetryAt: number | undefined
+  /** When the last start failure was reported, used to keep one death to one log line. */
+  private lastStartFailureAt = 0
   /** Window groups (windowId per view), re-sent on every materialization so
    *  a restarted child still places views in the right windows. */
   private readonly groups = new Map<string, { windowId: string; label?: string }>()
@@ -799,6 +900,38 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     return this.electronAvailable
   }
 
+  /**
+   * Retire the cached "an Electron binary is here" answer.
+   *
+   * A success is cached for the host's lifetime because rescanning on every tool call was
+   * the original bug — but the probe reads the FILESYSTEM, so it cannot see a binary that
+   * stops being usable afterwards. Only a real spawn attempt can observe that, which is why
+   * the two failure paths in {@link RemoteElectronViewHost.start} call this: the next
+   * `available()` rescans and reports what is actually on disk, instead of advertising a
+   * provider that cannot start.
+   */
+  private forgetBinary(): void {
+    this.electronAvailable = undefined
+    this.nextProbeAt = 0
+  }
+
+  /**
+   * Whether the binary the host would spawn — or the entry it needs — is no longer there.
+   *
+   * Only asked after a launch actually failed, so a healthy path never pays for it. The
+   * entry script counts because Electron exits 1 with empty stderr when it cannot load it,
+   * and resolution itself throws exactly when it can find nothing, which is the same answer.
+   * @returns true when the next `available()` must rescan instead of reusing its cache.
+   */
+  private binaryIsGone(): boolean {
+    if (!existsSync(this.hostMainPath)) return true
+    try {
+      return !existsSync(this.spawnExecutable ?? resolveElectronPath())
+    } catch {
+      return true
+    }
+  }
+
   /**
    * Ensure the child is up and ready (lazy on first use; restarts after a crash).
    *
@@ -821,25 +954,105 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
       return gone
     }
     if (this.readyPromise !== undefined) return this.readyPromise
+    // Backoff gate for a host that keeps failing to START (see START_RETRY_SCHEDULE_MS).
+    // The client is undefined exactly when the previous child is gone — a start failure, or
+    // a child that died after it came up — so this only delays restarts, never first use.
+    const retryAt = this.startRetryAt
+    if (retryAt !== undefined && Date.now() < retryAt && this.client === undefined) {
+      const waitMs = retryAt - Date.now()
+      const waiting = Promise.reject(new HostGoneError(
+        `browser host did not start; retrying in ${formatDelay(waitMs)} `
+        + `(attempt ${String(this.startFailures)}${this.startFailures >= START_FAILURES_MAX ? ', start attempts are now spaced out rather than immediate' : ''})`,
+      ))
+      // Keep the rejection observable to callers while marking it handled here: the
+      // fire-and-forget callers that drive this path attach their own handler, but one that
+      // forgets must not turn the recovery gate into an unhandled rejection.
+      waiting.catch(() => undefined)
+      return waiting
+    }
     const started = this.start()
-    const wrapped = started.catch(error => {
-      // A failed startup must not poison the host forever: tear down whatever
-      // was half-created and let the next call retry from scratch.
-      if (this.readyPromise === wrapped) {
-        this.readyPromise = undefined
-        this.client?.kill()
-        this.client = undefined
-        this.server?.close()
-        this.server = undefined
-        this.pendingSocket?.destroy()
-        this.pendingSocket = undefined
-      }
-      throw error
-    })
+    const wrapped = started.then(
+      () => {
+        // A child that came up clears the record: the next death is a new failure, not
+        // another entry in this run of them.
+        this.startFailures = 0
+        this.startRetryAt = undefined
+      },
+      error => {
+        // Record the failure BEFORE tearing anything down, and gate the teardown on the
+        // retry state being gone rather than on readyPromise alone. Ordering matters: a
+        // child that exits while the readiness call is still in flight fires the client's
+        // 'exit' handler first (onChildExit invalidates this promise and starts the retry
+        // clock), and the rejection then lands here — at which point clearing startRetryAt
+        // would erase the very backoff that was just armed, so every tool call spawned
+        // another dying child. noteStartFailure's dedupe window counts that pair once.
+        this.noteStartFailure(error)
+        // A failed startup must not poison the host forever: tear down whatever
+        // was half-created and let the next call retry from scratch.
+        if (this.readyPromise === wrapped) {
+          this.readyPromise = undefined
+          this.client?.kill()
+          this.client = undefined
+          this.server?.close()
+          this.server = undefined
+          this.pendingSocket?.destroy()
+          this.pendingSocket = undefined
+        }
+        throw error
+      },
+    )
     this.readyPromise = wrapped
     return wrapped
   }
 
+  /**
+   * Record one child that did not survive, and set the earliest retry time.
+   *
+   * `available()` answers "is there a binary to spawn" from the FILESYSTEM, and a success
+   * there is cached for the host's lifetime (correctly — rescanning on every tool call was
+   * the bug). That probe therefore cannot see the failure mode where the binary exists and
+   * crashes on every launch: the signature `code=1` with empty stderr that host-log.test.mjs
+   * asserts. Each browser call then spawned a child that died within milliseconds, with no
+   * backoff and nothing that ever gives up — an endless crash loop, each iteration a window
+   * flashing on screen.
+   *
+   * The first retry is immediate, so the ordinary transient death (the DSH restart in
+   * remote-host-recovery.test.mjs) still heals on the very next call. After that the delay
+   * grows: once {@link START_FAILURES_MAX} attempts have failed, every later attempt is
+   * spaced by the table's last entry — the host keeps trying, but a permanently broken
+   * install now costs one spawn per 30s instead of one per tool call. Nothing is marked
+   * dead for good: a repaired installation heals on the next attempt, and `dispose()`
+   * still stops everything immediately.
+   * @param error - what the failed attempt reported.
+   */
+  private noteStartFailure(error: unknown): void {
+    // The same death arrives twice: the child's exit reports it, and ready() rejecting
+    // reports it again. Counting both pushed the first retry to the 500ms step and made
+    // the log say "attempt 2" for a first failure, while START_RETRY_SCHEDULE_MS[0] = 0
+    // exists precisely so an ordinary death heals on the next call. So a report inside the
+    // window is dropped ENTIRELY — the count and the log line alike.
+    //
+    // That last part used to be split in two: the guard below, and a second dedupe that only
+    // suppressed the LOG. The second one read `now - this.lastStartFailureAt` after the line
+    // above had already stored `failureAt` into that same field, so its window was 0-1ms wide
+    // and the comparison was unconditionally true — the log line was never written at all.
+    // Nothing noticed, because this function exists to make a silent failure visible and its
+    // only output was the thing being dropped: a child that exists and dies instantly (code=1,
+    // empty stderr) left no trace anywhere.
+    const failureAt = Date.now()
+    if (this.lastStartFailureAt !== undefined && failureAt - this.lastStartFailureAt < START_FAILURE_DEDUPE_MS) return
+    this.lastStartFailureAt = failureAt
+    this.startFailures += 1
+    const index = Math.min(this.startFailures, START_RETRY_SCHEDULE_MS.length) - 1
+    const delayMs = START_RETRY_SCHEDULE_MS[index] ?? 0
+    this.startRetryAt = delayMs > 0 ? failureAt + delayMs : undefined
+    const line = `${hostStamp()} browser host start failed (attempt ${String(this.startFailures)}`
+      + `${this.startFailures >= START_FAILURES_MAX ? ', giving up on immediate retries' : ''}): ${String(error)}`
+      + `${delayMs > 0 ? ` — next attempt in ${formatDelay(delayMs)}` : ''}`
+    process.stderr.write(`[dsh-browser host] ${line}\n`)
+    appendHostLog(`${line}\n`)
+  }
+
   private async start(): Promise<void> {
     // Listen on an ephemeral loopback port; the child connects back. The
     // server accepts exactly one connection: the child's. Any further
@@ -912,6 +1125,18 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     // ever kill it. Only the restart is suppressed, not the cleanup.
     const wasDisposed = this.disposed
     if (!wasDisposed) process.stderr.write('[dsh-browser host] browser host gone; will restart on next use\n')
+    // A child that started and then died is also a failed start, and it is the shape a crash
+    // loop takes (the child comes up far enough to be pending on `ping`, then exits): count
+    // it so the restart is spaced instead of attempted on every single tool call.
+    if (!wasDisposed) this.noteStartFailure('the browser host process exited')
+    // The cached `available()` answer came from the FILESYSTEM, so only a real attempt can
+    // contradict it. A binary that stops being usable after the probe said yes — an
+    // interrupted reinstall, a removed mount, a wiped cache — kept the provider advertised
+    // as available for the rest of the process's life, because provider selection reads
+    // that same cached yes; every later call then paid a doomed spawn. Both failure routes
+    // (a spawn error, and a child that exits) arrive here, so this is the one place that
+    // observes the loss, and it costs two stats on a path that is already failing.
+    if (this.binaryIsGone()) this.forgetBinary()
     this.client = undefined
     this.server?.close()
     this.server = undefined

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

@@ -0,0 +1,46 @@
+/**
+ * Admission for the settings route: who may read the document, and who may write it.
+ *
+ * Its own module for a blunt reason — `entry.ts` imports the host's peer packages (cordis, the
+ * tools registry) and therefore cannot be loaded by the test suite, while this is precisely the
+ * logic whose failure is invisible in a browser: too strict and the panel silently stops being
+ * able to save, too loose and any process on the machine can rewrite the operator's switches.
+ *
+ * It is NOT authentication, and cannot be. The plugin has no credential to check: DSH hands
+ * plugin routes the raw request (`packages/host/webserver/src/index.ts` registers handlers with
+ * no gate of its own), so the strongest same-origin evidence available is what a browser
+ * reliably sends — `Sec-Fetch-Site`, plus `Origin` on every write, same-origin included.
+ *
+ * What that buys and what it does not:
+ *   - a plain HTTP client (curl, a script, another process) cannot WRITE any more, because it
+ *     sends no `Origin`;
+ *   - a page of THIS origin still can, because a browser sending a same-origin write looks
+ *     exactly like the panel. That is inherent to exposing an HTTP endpoint at all, and it is
+ *     why the settings panel's own text must not promise a lock that does not exist.
+ */
+import type { IncomingMessage } from 'node:http'
+
+/**
+ * Whether a request may touch the settings document.
+ * @param request - the incoming request.
+ * @param writing - true for PUT/POST, which is held to the stricter rule.
+ * @returns whether the request is admitted.
+ */
+export function sameOrigin(request: IncomingMessage, writing = false): boolean {
+  const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase()
+  // `cross-site` is another origin entirely; `same-site` is another origin of the same site
+  // (a.example.com -> b.example.com), which is not this panel either. Both are refused.
+  if (site === 'cross-site' || site === 'same-site') return false
+  const origin = String(request.headers.origin ?? '').trim()
+  // `Origin: null` is what a sandboxed or opaque-origin document sends. Never this panel.
+  if (origin === 'null') return false
+  // Reads are let through without an Origin: they return the document the panel is already
+  // showing, and refusing them would only break hand-inspection of a file that sits readable
+  // on disk anyway. Writes are not: a browser always sends `Origin` on one.
+  if (origin === '') return !writing
+  try {
+    return new URL(origin).host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase()
+  } catch {
+    return false
+  }
+}

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

@@ -9,7 +9,7 @@
  * @module dsh-browser/browser-electron/settings-store
  */
 
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import type { BrowserChannel } from './system-browser.js'
@@ -50,6 +50,22 @@ export interface BrowserSettings {
   readonly credentials: {
     readonly allowRead: boolean
   }
+  /**
+   * What the agent is allowed to DO, as opposed to what it may look at.
+   *
+   * These are OPERATOR switches: the settings panel is not reachable from the model, so a
+   * value here refuses whatever the model asks for, and no tool can lift it. That is what
+   * separates them from `browser_restrict`, which is the model's own soft guardrail. All
+   * three default to on, which is the documented out-of-the-box behaviour.
+   */
+  readonly actions: {
+    /** Run arbitrary page scripts in the active tab (`browser_execute`). */
+    readonly allowExecute: boolean
+    /** Download a URL to disk (`browser_download`). */
+    readonly allowDownload: boolean
+    /** Write cookies — importing login state (`browser_auth` restore). */
+    readonly allowCredentialWrite: boolean
+  }
 }
 
 /** Defaults for every switch: the documented out-of-the-box behaviour. */
@@ -63,6 +79,7 @@ export const DEFAULT_SETTINGS: BrowserSettings = {
   // it starts a real Chrome/Edge with its own profile.
   browser: { channel: 'bundled' },
   credentials: { allowRead: true },
+  actions: { allowExecute: true, allowDownload: true, allowCredentialWrite: true },
 }
 
 /**
@@ -80,6 +97,38 @@ function bool(value: unknown, fallback: boolean): boolean {
   return typeof value === 'boolean' ? value : fallback
 }
 
+/**
+ * Coerce one boolean field that GATES A CAPABILITY.
+ *
+ * The difference from {@link bool} is what a mistyped value means. Absent still takes the
+ * default — a document written before the switch existed is the documented behaviour. But
+ * present-and-not-a-boolean is a document this code cannot read, and for a switch that gates
+ * something the operator chose to limit, unreadable resolves to OFF. `bool`'s fallback made
+ * `"false"` (a string), `null` (a truncated write) and `1` all mean the same as `true`, so a
+ * single dropped byte reopened every capability that had been turned off.
+ * @param value - the raw value from the settings document.
+ * @param fallback - the default, used only when the field is absent.
+ * @returns the value when it is a boolean, `false` when it is anything else.
+ */
+function gate(value: unknown, fallback: boolean): boolean {
+  if (value === undefined) return fallback
+  return value === true
+}
+
+/**
+ * What an unreadable document resolves to.
+ *
+ * Only the capability gates are refused; everything else keeps its default. The distinction is
+ * deliberate: refusing history, presentation or browser choice would punish the user for a
+ * corrupt file without protecting anything, while refusing the gates is the whole point —
+ * "the operator's intent cannot be read" must not resolve to "the operator permits".
+ */
+const SETTINGS_WHEN_UNREADABLE: BrowserSettings = {
+  ...DEFAULT_SETTINGS,
+  credentials: { allowRead: false },
+  actions: { allowExecute: false, allowDownload: false, allowCredentialWrite: false },
+}
+
 /**
  * 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.
@@ -118,6 +167,7 @@ export function resolveSettings(raw: unknown): BrowserSettings {
   const vision = section(source, 'vision')
   const credentials = section(source, 'credentials')
   const browser = section(source, 'browser')
+  const actions = section(source, 'actions')
   return {
     history: {
       enabled: bool(history.enabled, DEFAULT_SETTINGS.history.enabled),
@@ -132,7 +182,12 @@ export function resolveSettings(raw: unknown): BrowserSettings {
     },
     vision: { strategy: vision.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
     browser: { channel: resolveChannel(browser.channel) },
-    credentials: { allowRead: bool(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
+    credentials: { allowRead: gate(credentials.allowRead, DEFAULT_SETTINGS.credentials.allowRead) },
+    actions: {
+      allowExecute: gate(actions.allowExecute, DEFAULT_SETTINGS.actions.allowExecute),
+      allowDownload: gate(actions.allowDownload, DEFAULT_SETTINGS.actions.allowDownload),
+      allowCredentialWrite: gate(actions.allowCredentialWrite, DEFAULT_SETTINGS.actions.allowCredentialWrite),
+    },
   }
 }
 
@@ -163,18 +218,33 @@ export class SettingsStore {
    */
   get(): BrowserSettings {
     let mtimeMs = -1
-    let text: string | undefined
     try {
-      if (existsSync(this.file)) {
-        mtimeMs = statSync(this.file).mtimeMs
-        text = readFileSync(this.file, 'utf8')
-      }
+      // stat directly: existsSync costs about thirteen times what the stat does, and the
+      // stat already throws when the file is missing — which the catch below handles.
+      mtimeMs = statSync(this.file).mtimeMs
     } catch {
       // Unreadable file: fall through to defaults below.
       mtimeMs = -1
-      text = undefined
     }
+    // Return the cache BEFORE reading. The read used to happen first "just in case", which
+    // made the cache pointless: every call paid for a synchronous read of the whole file and
+    // then discarded it. This is on the path of every tool call that consults a setting, so
+    // it was a stat plus a read per call where a single stat will do.
     if (this.cached !== undefined && mtimeMs === this.cachedMtimeMs) return this.cached
+
+    let text: string | undefined
+    if (mtimeMs !== -1) {
+      try {
+        text = readFileSync(this.file, 'utf8')
+      } catch {
+        // It was there a moment ago (the stat above) and cannot be read now: permissions, a
+        // lock, a directory in the way. That is not "no document" — the file is not absent, so
+        // what it said is unknown, and unknown resolves to the refusing document.
+        this.cached = SETTINGS_WHEN_UNREADABLE
+        this.cachedMtimeMs = mtimeMs
+        return this.cached
+      }
+    }
     try {
       // A leading BOM is what ordinary Windows editors (Notepad, PowerShell's
       // `Set-Content -Encoding utf8`) leave behind, and `JSON.parse` rejects it.
@@ -184,8 +254,12 @@ export class SettingsStore {
       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
+      // A document that EXISTS but cannot be parsed is not the same as no document at all: the
+      // first is a corrupted or half-written file whose contents were the operator's decisions,
+      // the second is a first run. Resolving both to the defaults meant a kill during the write,
+      // or one stray character, silently reopened the capabilities that had been switched off —
+      // so this side refuses them instead (see SETTINGS_WHEN_UNREADABLE).
+      this.cached = SETTINGS_WHEN_UNREADABLE
     }
     this.cachedMtimeMs = mtimeMs
     return this.cached
@@ -201,7 +275,7 @@ export class SettingsStore {
     const merged = resolveSettings(deepMerge(current as unknown as Record<string, unknown>, patch))
     try {
       mkdirSync(dirname(this.file), { recursive: true })
-      writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`)
+      writeFileAtomic(this.file, `${JSON.stringify(merged, null, 2)}\n`)
     } catch (error) {
       // Do NOT publish the new value as cached, and do not pretend the file changed: a
       // reader compares the file's mtime against this stamp, so stamping "now" on a failed
@@ -218,6 +292,42 @@ export class SettingsStore {
   }
 }
 
+/**
+ * Replace a file's contents atomically: write a sibling temporary file, then rename it over
+ * the target.
+ *
+ * `writeFileSync(target, …)` truncates and rewrites in place, so a crash, a full disk or an
+ * antivirus lock in the middle leaves HALF a JSON document. That used to be silent: the reader
+ * resolved an unparseable file to the defaults, so a torn write flipped `credentials.allowRead`
+ * and the action switches back ON, and the next successful update wrote those defaults to disk
+ * for good. The read side no longer does that (see {@link SETTINGS_WHEN_UNREADABLE}) — but the
+ * write side still has to stop producing torn files at all, because half a document is not
+ * something this plugin should ever leave behind.
+ *
+ * The rename is the commit point: a reader sees either the old document or the new one,
+ * never a partial one. It stays in the same directory so the rename is atomic on Windows
+ * as well as POSIX (`renameSync` maps to MoveFileEx there: same-volume replaces are
+ * atomic, cross-volume ones are not supported at all).
+ *
+ * The temporary is written with a unique suffix rather than a fixed `.tmp`, so two writers
+ * (the settings panel and a second DSH process) cannot rename each other's half-written
+ * file into place. Shared with the history store, which had the same hole.
+ * @param file - the target path.
+ * @param contents - the complete new document.
+ */
+export function writeFileAtomic(file: string, contents: string): void {
+  const temporary = `${file}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`
+  try {
+    writeFileSync(temporary, contents)
+    renameSync(temporary, file)
+  } catch (error) {
+    // The rename is the commit point, so a failure before it leaves the target untouched —
+    // only the temporary has to go, and it must not be left behind as garbage.
+    try { rmSync(temporary, { force: true }) } catch { /* the temp is already the least of it */ }
+    throw error
+  }
+}
+
 /** One-level-deep merge over the settings sections (patch wins). */
 function deepMerge(base: Record<string, unknown>, patch: unknown): Record<string, unknown> {
   if (typeof patch !== 'object' || patch === null) return base