dsh-builtin-browser 0.4.1 → 0.4.5

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,44 @@ class ElectronChildClient {
             this.fail(new Error(`dsh-builtin-browser: ${line}`));
         });
     }
+    /**
+     * Drop the escalation kill once there is nothing left for it to target.
+     *
+     * Called on the paths where the child is known to be gone — after an observed exit, and on
+     * release. It is deliberately NOT called from `fail()`: a dead socket says nothing about the
+     * process on the other end, and the timer exists for exactly the case where the child ignores
+     * the socket closing. Clearing it there disarmed the only escalation there was, which is how
+     * a child that ignored its socket could outlive dispose() and keep holding the profile.
+     */
+    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();
+        // NOT clearKillGrace(): this path runs when the SOCKET died, which says nothing about
+        // whether the process did. Clearing the escalation here disarmed it for exactly the case it
+        // exists for — a child that ignores its socket closing — so dispose() could return with the
+        // child still running and still holding the profile. The timer clears itself when the child
+        // exits, and `kill()` replaces it on an explicit release.
         // 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 +594,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 +630,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 +685,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 +771,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 +811,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 +871,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 +926,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 +971,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 +1087,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;
@@ -1024,11 +1251,18 @@ class DeferredRemoteView {
     materializeOnce() {
         if (this.materialized === undefined) {
             const pending = this.materialize();
-            this.materialized = pending.catch(error => {
-                if (this.materialized === pending)
+            // Compare against the promise actually stored — the derived one — not against `pending`.
+            // Storing `pending.catch(...)` and comparing `this.materialized === pending` compared two
+            // different objects, so the test was never true and the reset never ran: a materialization
+            // that failed with anything other than a HostGoneError (the child alive but not answering
+            // a ping, say) poisoned the handle for good, and the retry the comment below promises was
+            // unreachable.
+            const guarded = pending.catch(error => {
+                if (this.materialized === guarded)
                     this.materialized = undefined;
                 throw error;
             });
+            this.materialized = guarded;
         }
         return this.materialized;
     }

package/lib/browser-electron/rpc-ops.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The RPC operation vocabulary, in one place.
+ *
+ * The child (`host-main.ts`) switches on these names and the parent (`remote-host.ts`) sends
+ * them. Both spelled them out independently and nothing connected the two, so a rename on one
+ * side compiled fine and failed at run time as "unknown op" — and this pair has already
+ * produced one silent failure of that shape (`noteStartFailure`'s dedupe comparison, which was
+ * never true and meant a log line that never appeared).
+ *
+ * The lists are the source of truth for a test that reads both switch statements and asserts
+ * they agree, which is what makes a one-sided rename fail loudly instead of at run time.
+ */
+/** Operations the parent asks the child to perform. */
+export declare const RPC_OPS: readonly ["ping", "createView", "destroyView", "showView", "groupView", "focus", "command", "capture", "download", "flushAuth", "restoreAuth", "navigate", "new-tab", "activate", "close", "back", "forward", "reload", "userActionError"];
+/** Notifications the child sends the parent, which carry no reply. */
+export declare const RPC_NOTIFICATIONS: readonly ["userAction", "viewClosed"];
+/** One operation name. */
+export type RpcOp = (typeof RPC_OPS)[number];

package/lib/browser-electron/rpc-ops.js

@@ -0,0 +1,36 @@
+/**
+ * The RPC operation vocabulary, in one place.
+ *
+ * The child (`host-main.ts`) switches on these names and the parent (`remote-host.ts`) sends
+ * them. Both spelled them out independently and nothing connected the two, so a rename on one
+ * side compiled fine and failed at run time as "unknown op" — and this pair has already
+ * produced one silent failure of that shape (`noteStartFailure`'s dedupe comparison, which was
+ * never true and meant a log line that never appeared).
+ *
+ * The lists are the source of truth for a test that reads both switch statements and asserts
+ * they agree, which is what makes a one-sided rename fail loudly instead of at run time.
+ */
+/** Operations the parent asks the child to perform. */
+export const RPC_OPS = [
+    'ping',
+    'createView',
+    'destroyView',
+    'showView',
+    'groupView',
+    'focus',
+    'command',
+    'capture',
+    'download',
+    'flushAuth',
+    'restoreAuth',
+    'navigate',
+    'new-tab',
+    'activate',
+    'close',
+    'back',
+    'forward',
+    'reload',
+    'userActionError',
+];
+/** Notifications the child sends the parent, which carry no reply. */
+export const RPC_NOTIFICATIONS = ['userAction', 'viewClosed'];

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.
+ *
+ * What that buys and what it does not:
+ *   - a plain HTTP client (curl, a script, another process) cannot WRITE, because it sends no
+ *     `user-agent` and no `accept-language`;
+ *   - a page of THIS origin 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,68 @@
+/** The shell's own URL schemes. Only the shell can mint a document on one of these. */
+const APP_SCHEMES = ['dsh-app:', 'dsh-desktop:'];
+/**
+ * The scheme of a header value, when it names a URL.
+ * @param value - a raw header value.
+ * @returns the scheme, or undefined when the value is absent, opaque or unparseable.
+ */
+function schemeOf(value) {
+    if (value === '' || value === 'null')
+        return undefined;
+    try {
+        return new URL(value).protocol;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 origin = String(request.headers.origin ?? '').trim();
+    const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase();
+    // A shell URL, in either the Origin or the referrer: the strongest evidence there is.
+    if (APP_SCHEMES.includes(schemeOf(origin) ?? ''))
+        return true;
+    if (APP_SCHEMES.includes(schemeOf(String(request.headers.referer ?? '')) ?? ''))
+        return true;
+    // MEASURED on the running desktop, and what three earlier attempts each guessed wrong: a
+    // request from the shell's own settings panel carries NO origin, NO sec-fetch-site and NO
+    // referer. It is not "dsh-app://app" and it is not "null" — the headers are simply absent,
+    // because Chromium attaches no cross-origin metadata to a request leaving a custom scheme.
+    //
+    // So the rule for that shape cannot be "a request without an Origin is a script", which is
+    // what refused every desktop save, and it cannot lean on `Sec-Fetch-Site` either. It has to
+    // test what a hand-rolled client does not send:
+    //   - a renderer sends a full Mozilla-compatible `user-agent` AND an `accept-language`;
+    //   - curl sends neither unless told to, and a local process that forges both can also read
+    //     the settings document directly — it sits readable on disk, as the panel's own text
+    //     says. This was never the boundary it looked like.
+    if (origin === '') {
+        const agent = String(request.headers['user-agent'] ?? '');
+        const language = String(request.headers['accept-language'] ?? '');
+        if (/^Mozilla\/5\.0/.test(agent) && language !== '')
+            return true;
+        // Reads stay open: 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.
+        return !writing;
+    }
+    // `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;
+    // `Origin: null` is a sandboxed or opaque-origin document. Never this panel.
+    if (origin === 'null')
+        return false;
+    try {
+        const parsed = new URL(origin);
+        // The host comparison is for http(s), where a page and its route share one host.
+        return parsed.host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}