dsh-builtin-browser 0.4.1 → 0.4.2

package/lib/browser-electron/remote-host.d.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
  */
 import type { BrowserUserAction, ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
@@ -113,6 +115,12 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     private electronAvailable;
     /** Earliest time the next probe may run after a negative one. */
     private nextProbeAt;
+    /** Consecutive child starts that did not survive; drives {@link startRetryAt}. */
+    private startFailures;
+    /** Earliest time `ready()` may spawn another child after a failed start. */
+    private startRetryAt;
+    /** When the last start failure was reported, used to keep one death to one log line. */
+    private lastStartFailureAt;
     /** Window groups (windowId per view), re-sent on every materialization so
      *  a restarted child still places views in the right windows. */
     private readonly groups;
@@ -145,6 +153,26 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
      * on a cooldown heals it by itself while keeping the scan off the hot path.
      */
     available(): boolean;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * Ensure the child is up and ready (lazy on first use; restarts after a crash).
      *
@@ -155,6 +183,27 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
      * instead, which those callers already handle.
      */
     private ready;
+    /**
+     * 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;
     private start;
     /** The child died: tear down so the next use starts a fresh child. */
     private onChildExit;

package/lib/browser-electron/remote-host.js

@@ -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
  */
 import { execFileSync, spawn } from 'node:child_process';
@@ -458,6 +460,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) => {
@@ -479,12 +484,38 @@ class ElectronChildClient {
             this.fail(new Error(`dsh-builtin-browser: ${line}`));
         });
     }
+    /**
+     * 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.
+     */
+    clearKillGrace() {
+        if (this.killGraceTimer === undefined)
+            return;
+        clearTimeout(this.killGraceTimer);
+        this.killGraceTimer = undefined;
+    }
+    /** Drop the "did not authenticate" deadline once it can no longer be meaningful. */
+    clearHelloTimer() {
+        if (this.helloTimer === undefined)
+            return;
+        clearTimeout(this.helloTimer);
+        this.helloTimer = undefined;
+    }
     /** Reject everything in flight, mark the client dead, and notify the host. */
     fail(err) {
         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);
@@ -557,19 +588,35 @@ 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);
-                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);
+                }
+                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) {
@@ -577,10 +624,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'));
@@ -635,13 +679,43 @@ 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.
+     */
+    static KILL_GRACE_MS = 500;
+    killGraceTimer;
+    /**
+     * 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() {
+        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);
     }
 }
 /** One view in the child: its id, used for every command. */
@@ -691,6 +765,26 @@ const PROBE_RETRY_MS = (() => {
     const raw = Number(process.env.DSH_BROWSER_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 = [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) {
+    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
@@ -711,6 +805,12 @@ export class RemoteElectronViewHost {
     electronAvailable;
     /** Earliest time the next probe may run after a negative one. */
     nextProbeAt = 0;
+    /** Consecutive child starts that did not survive; drives {@link startRetryAt}. */
+    startFailures = 0;
+    /** Earliest time `ready()` may spawn another child after a failed start. */
+    startRetryAt;
+    /** When the last start failure was reported, used to keep one death to one log line. */
+    lastStartFailureAt = 0;
     /** Window groups (windowId per view), re-sent on every materialization so
      *  a restarted child still places views in the right windows. */
     groups = new Map();
@@ -765,6 +865,38 @@ export class RemoteElectronViewHost {
         }
         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.
+     */
+    forgetBinary() {
+        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.
+     */
+    binaryIsGone() {
+        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).
      *
@@ -788,8 +920,35 @@ export class RemoteElectronViewHost {
         }
         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 => {
+        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) {
@@ -806,6 +965,54 @@ export class RemoteElectronViewHost {
         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.
+     */
+    noteStartFailure(error) {
+        // 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`);
+    }
     async start() {
         // Listen on an ephemeral loopback port; the child connects back. The
         // server accepts exactly one connection: the child's. Any further
@@ -874,6 +1081,20 @@ export class RemoteElectronViewHost {
         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/lib/browser-electron/settings-route.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function sameOrigin(request: IncomingMessage, writing?: boolean): boolean;

package/lib/browser-electron/settings-route.js

@@ -0,0 +1,28 @@
+/**
+ * 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, writing = false) {
+    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/lib/browser-electron/settings-store.d.ts

@@ -44,6 +44,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. */
 export declare const DEFAULT_SETTINGS: BrowserSettings;
@@ -90,3 +106,27 @@ export declare class SettingsStore {
      */
     update(patch: unknown): BrowserSettings;
 }
+/**
+ * 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 declare function writeFileAtomic(file: string, contents: string): void;