dsh-builtin-browser 0.1.16 → 0.1.17

package/README.en.md

@@ -217,7 +217,7 @@ agent (browser_* tools)
 
 **The self-hosted browser IS a real browser**: every task (DSH session) gets its **own browser window** with a full toolbar — address bar, back/forward/reload buttons, and a tab strip (new/switch/close tabs). A human can use it exactly like Chrome: type a URL in the address bar (https:// is added automatically), click tabs, open new ones. Keyboard focus follows your clicks — **click the address bar to type, click the page to interact** (Windows focus routing; fixes the case where clicks did not move focus and the address bar could not receive typed URLs). Human and agent actions feed the **same session model** (same tabs, history, and navigation); the window title always shows the task label plus the page title/URL, and views follow the window size on resize. A window closes automatically with its session when the task ends.
 
-**Electron lookup order**: ① `require('electron')` (peer dependency) → ② `ELECTRON_PATH` (explicit override) → ③ the newest among DSH install anchors and pnpm virtual stores. A clear error tells you when none is found.
+**Electron lookup order**: ① the current process IS Electron (DSH Desktop main process) → reuse the host binary directly; ② walk the process ancestry for the host's Electron binary (covers hosts that run the plugin in a child Node process, e.g. DSH Desktop; PowerShell CIM on Windows, last resort only); ③ `require('electron')` (peer dependency); ④ `ELECTRON_PATH` (explicit override); ⑤ the newest among DSH install anchors and pnpm virtual stores. **Zero extra install on DSH Desktop**; when nothing is found a clear error tells you what to do (including the per-profile install command).
 
 ## Division of labor with the desktop shell
 
@@ -225,8 +225,10 @@ The browser's **visible view**, the **browser column layout**, and the **column-
 
 ## Requirements
 
-- DeepSeek Harness (dsh) with the `web` profile
-- **Electron runtime** (optional peer dependency): the desktop shell carries it; on plain `dsh web` the plugin locates an Electron binary automatically (see above; ≥ 40 recommended)
+- DeepSeek Harness (dsh) with the matching profile (`web` / `desktop`, etc.)
+- **Electron runtime** (optional peer dependency):
+  - **DSH Desktop**: the host itself runs on Electron — the plugin reuses the host binary automatically, **zero extra install**;
+  - **plain `dsh web` self-hosted**: an Electron binary is required and located automatically (see above; ≥ 40 recommended; 44+ downloads its binary on first use, needs network)
 
 ### Verified versions
 
@@ -235,7 +237,7 @@ The browser's **visible view**, the **browser column layout**, and the **column-
 | DeepSeek Harness (dsh) | `0.1.1-rc.2` (peer range `^0.1.1-rc.2`) |
 | Electron | `44.0.0` (≥ 40 recommended; 33.x has a compositor defect) |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.16` |
+| dsh-builtin-browser | `0.1.17` |
 | OS | Windows 10 (10.0.26200) |
 
 > The plugin declares `electron >= 30`; it has **only been verified on Windows** (macOS/Linux untested, not yet promised).
@@ -288,6 +290,8 @@ Code layout:
 | 6 | 2026-08 | **Windows handshake & tab lookup**: the Electron GUI process never receives piped stdin → RPC token now flows over **stdin + env var**; `browser_switch_tab`/`browser_close_tab` locate tabs across sessions (`locateTab`), `browser_close_tab` no longer fakes success, unknown ids error with the session's actual tab list |
 | 7 | 2026-08 | **Toolbar interaction (Windows focus routing)**: keyboard input only reaches the focused view and the page view grabbed it, so the address bar could not receive input → added `wireFocusRouting` (clicking a view focuses it) + window refocus restores the last-clicked view; verified with real OS input probes |
 | **0.1.16** | 2026-08-26 | **Release**: all seven rounds ship as **0.1.16** (build clean, 21/21 tests pass, `v0.1.16`) |
+| 8 | 2026-08-27 | **DSH Desktop host-Electron reuse**: running inside an Electron process reuses the host binary directly; when the host runs the plugin in a child Node process, walk the process ancestry to find the host's Electron (PowerShell CIM on Windows, last resort only) — **DSH Desktop works with zero install**; error now hints per active profile; electron shim completed to fix the CI typecheck; docs updated |
+| **0.1.17** | 2026-08-27 | **Release**: round 8 ships as **0.1.17** (build clean, 21/21 tests pass) |
 
 ## Acknowledgements
 

package/README.md

@@ -217,7 +217,7 @@ agent (browser_* 工具)
 
 **自托管浏览器就是一台真正的浏览器**:每个任务(DSH 会话)拥有**独立的浏览器窗口**,窗口自带完整工具栏——地址栏、后退/前进/刷新按钮、标签条(新建/切换/关闭标签)。人可以直接像用 Chrome 一样使用它:在地址栏输入网址(自动补 `https://`)、点标签切换页面、开新标签;键盘焦点跟随点击——**点地址栏即可输入、点页面即可操作**(Windows 焦点路由,修复了点击不转移焦点导致地址栏无法输入的问题)。agent 与人的操作都汇入**同一个会话模型**(同一套标签、历史与导航),窗口标题实时显示当前任务标识与页面标题/URL,窗口缩放时视图自动跟随。任务结束后窗口随会话自动关闭。
 
-**Electron 定位顺序**:① `require('electron')`(peer 依赖)→ ② `ELECTRON_PATH`(显式覆盖)→ ③ DSH 安装锚点与 pnpm 虚拟仓库中**版本最新**者。找不到时工具会报清晰的错误提示。
+**Electron 定位顺序**:① 插件运行在 Electron 进程内(DSH Desktop 主进程)时直接复用宿主二进制 → ② 进程祖先树中的宿主 Electron 二进制(DSH Desktop 把插件跑在子 Node 进程时的兜底)→ ③ `require('electron')`(peer 依赖)→ ④ `ELECTRON_PATH`(显式覆盖)→ ⑤ DSH 安装锚点与 pnpm 虚拟仓库中**版本最新**者。**DSH Desktop 上零额外安装**;找不到时工具会报清晰的错误提示(含按当前 profile 的安装命令)。
 
 ## 与桌面外壳的分工
 
@@ -225,8 +225,10 @@ agent (browser_* 工具)
 
 ## 环境要求
 
-- DeepSeek Harness(dsh)且安装了 `web` profile
-- **Electron 运行时**(可选 peer 依赖):桌面外壳自带;纯 `dsh web` 下插件自动定位 Electron 二进制(见上,建议 ≥ 40)
+- DeepSeek Harness(dsh),已安装对应 profile(`web` / `desktop` 等)
+- **Electron 运行时**(可选 peer 依赖):
+  - **DSH Desktop**:宿主本身基于 Electron,**插件自动复用宿主二进制,零额外安装**;
+  - **纯 `dsh web` 自托管**:需要 Electron 二进制,插件自动定位(见上,建议 ≥ 40;44+ 首次使用自动下载,需网络)
 
 ### 验证过的版本
 
@@ -235,7 +237,7 @@ agent (browser_* 工具)
 | DeepSeek Harness(dsh) | `0.1.1-rc.2`(peer 声明 `^0.1.1-rc.2`) |
 | Electron | `44.0.0`(推荐 ≥ 40;33.x 存在合成器缺陷) |
 | Node.js | `22.20.0` |
-| dsh-builtin-browser | `0.1.16` |
+| dsh-builtin-browser | `0.1.17` |
 | 操作系统 | Windows 10 (10.0.26200) |
 
 > 插件声明 `electron >= 30`;**当前仅在 Windows 环境实测**(macOS/Linux 未验证,暂不承诺)。
@@ -288,6 +290,8 @@ npm run build
 | 第六轮 | 2026-08 | **Windows 握手与标签定位**:Electron GUI 进程收不到 piped stdin → RPC token 改 **stdin + 环境变量双通道**;`browser_switch_tab`/`browser_close_tab` 跨会话按 id 定位(`locateTab`),`browser_close_tab` 不再静默假成功,未知 id 报错附带现有标签列表 |
 | 第七轮 | 2026-08 | **工具栏交互(Windows 焦点路由)**:键盘输入只进有焦点的 view,页面 view 抢占焦点导致地址栏无法输入 → 新增 `wireFocusRouting`(点击即聚焦该 view)+ 窗口 refocus 恢复上次点击的 view;真机 OS 输入探针验证 |
 | **0.1.16** | 2026-08-26 | **发布**:以上七轮全部随 **0.1.16** 发布(构建零错误、21 项测试全绿,`v0.1.16`) |
+| 第八轮 | 2026-08-27 | **DSH Desktop 宿主 Electron 复用**:插件运行在 Electron 进程内直接复用宿主二进制;插件跑在宿主子 Node 进程时沿进程祖先树找到宿主 Electron 兜底(Windows 用 PowerShell CIM,仅最后手段)——DSH Desktop **零安装开箱可用**;报错按当前 profile 动态提示;补齐 electron shim 修复 CI 类型检查;文档同步 |
+| **0.1.17** | 2026-08-27 | **发布**:第八轮修复随 **0.1.17** 发布(构建零错误、21 项测试全绿) |
 
 ## 特别感谢
 

package/docs/architecture.md

@@ -60,7 +60,7 @@ RemoteElectronViewHost  ──TCP JSON-RPC──▶  host-main.js
 
 - **协议**:本机 loopback TCP,每行一个 JSON(`{ id, op, ... }` ↔ `{ id, ok, result|err }`);
 - **认证**:每次 spawn 生成随机 token(经 `--rpc-token` 传入),子进程首条消息必须回传该 token(`hello`);服务端只接受**一个**连接,其余连接直接断开——本机其他进程无法伪冒子进程或注入回复;
-- **Electron 定位**:① peer 依赖 → ② `ELECTRON_PATH` → ③ 锚点与 pnpm store 中**版本最新**者(33.x 有合成器缺陷,建议 ≥ 40);
+- **Electron 定位**:① 插件运行在 Electron 进程内(DSH Desktop 主进程)时直接复用宿主二进制(`process.execPath`);② 进程祖先树中的宿主 Electron 二进制(DSH Desktop 把插件跑在子 Node 进程时的兜底,Windows 用 PowerShell CIM 查询,仅在其它路径全部落空时才执行)→ ③ peer 依赖 → ④ `ELECTRON_PATH` → ⑤ 锚点与 pnpm store 中**版本最新**者(33.x 有合成器缺陷,建议 ≥ 40);
 - **稳健性**:子进程/套接字都有 `error` 监听(否则未捕获事件会炸掉整个 DSH 进程);子进程退出自动重启;物化失败可重试;下载仅限 HTTP(S)、`savePath` 必须绝对路径(默认限定 `~/Downloads`,可配置 `downloadDir` 覆盖)、流式限流 + Content-Length 提前拒绝、256MB 上限与 60s 超时,文件由**子进程直接落盘**(临时文件 + rename,不再经 RPC 传 base64);cookie 导出/恢复有 30s 超时;
 - **视图可见性**:多标签/多会话时,`showView` 隐藏其他视图并把目标视图置顶(remove+re-add),确保用户看到的是活动标签;目标是当前可见视图时**跳过** remove/re-add(否则每次操作都闪烁);窗口标题实时显示当前可见会话的任务标识 + 页面标题/URL(`showView` 携带会话 label,子进程读 `getTitle`/`getURL`);窗口 resize 时视图 bounds 自动跟随;
 - **孤儿防护**:父进程断开时子进程自动退出,不留僵尸窗口;

package/docs/user-guide.md

@@ -2,13 +2,15 @@
 
 ## 环境要求
 
-- DeepSeek Harness(dsh)且安装了 `web` profile
-- **Electron 运行时**(可选 peer 依赖):桌面外壳自带;纯 `dsh web` 下插件自动定位 Electron 二进制(建议 ≥ 40,33.x 存在截图合成器缺陷)
+- DeepSeek Harness(dsh),已安装对应 profile(`web` / `desktop` 等)
+- **Electron 运行时**(可选 peer 依赖):
+  - **DSH Desktop**:宿主本身基于 Electron,**插件自动复用宿主二进制,零额外安装**;
+  - **纯 `dsh web` 自托管**:需要 Electron 二进制,插件自动定位(建议 ≥ 40,33.x 存在截图合成器缺陷;44+ 首次使用自动下载,需网络),找不到时按下文 FAQ 安装即可。
 
 ## 安装
 
 ```sh
-# 从 npm 安装(已发布)
+# 从 npm 安装(已发布);`--profile` 换成你实际使用的 profile(DSH Desktop 为 `desktop`)
 dsh plugin --profile web add dsh-builtin-browser
 
 # 或从源码目录(独立仓库,一插件一仓库)
@@ -72,7 +74,9 @@ dsh plugin --profile web add <本仓库路径>
 能。插件自托管:自己拉起 Electron 窗口,无需桌面外壳。
 
 **Q:找不到 Electron?**
-插件按顺序自动定位:① peer 依赖 `require('electron')` → ② `ELECTRON_PATH` 环境变量 → ③ DSH 锚点与 pnpm 虚拟仓库中版本最新者。都找不到时报清晰错误,可 `dsh plugin --profile web add electron` 或设置 `ELECTRON_PATH`。
+插件按顺序自动定位:① 插件运行在 Electron 进程内(DSH Desktop 主进程)时直接复用宿主二进制 → ② 进程祖先树中的宿主 Electron 二进制(DSH Desktop 把插件跑在子 Node 进程时的兜底)→ ③ peer 依赖 `require('electron')`(仅二进制已就绪时)→ ④ `ELECTRON_PATH` 环境变量 → ⑤ DSH 锚点与 pnpm 虚拟仓库中版本最新者。
+
+DSH Desktop 上①②任一命中即开箱可用,无需任何安装。纯 `dsh web` 下全部落空时,报错会给出指引:可 `dsh plugin --profile <你的-profile> add electron`(DSH Desktop 的 profile 是 `desktop`)或设置 `ELECTRON_PATH`。
 
 **Q:截图失败或挂起?**
 确保 Electron ≥ 40(33.x 有合成器缺陷)。自托管截图优先走原生 `capturePage`,多视图/窗口未激活时自动兜底到 CDP。

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

@@ -24,11 +24,11 @@
  * sees traffic.
  * @module dsh-browser/browser-electron/remote-host
  */
-import { spawn } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { createRequire } from 'node:module';
-import { existsSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync, readFileSync, readdirSync, readlinkSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
 import { createServer } from 'node:net';
 import { fileURLToPath } from 'node:url';
 /** How long to wait for the child to signal readiness before failing. */
@@ -45,7 +45,9 @@ const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024;
  *   3. every DSH install anchor + pnpm virtual store candidate, choosing the
  *      NEWEST version found. Older Electron releases (e.g. 33.x) have a
  *      compositor defect that intermittently breaks page capture, so prefer
- *      the newest binary available in the environment.
+ *      the newest binary available in the environment,
+ *   4. last resort: the process ancestry, for hosts that run this plugin in a
+ *      child Node process of their own Electron main process (DSH Desktop).
  * @returns the path to the Electron executable.
  */
 function resolveElectronPath() {
@@ -137,17 +139,99 @@ function resolveElectronPath() {
             dir = parent;
         }
     }
-    if (candidates.length > 0) {
-        candidates.sort((a, b) => compareVersions(b.version, a.version));
-        const best = candidates[0];
-        if (best !== undefined)
-            return best.path;
-    }
+    // 4. Last resort for Electron hosts. DSH Desktop may run the agent runtime
+    //    (and thus this plugin) in a plain Node child of its Electron main
+    //    process — step 0 does not fire there, and there is no electron package
+    //    anywhere to find. The host's own binary IS an Electron runtime and is
+    //    guaranteed present (it is running us), so walk the process ancestry
+    //    and reuse the first Electron executable found. Zero extra install;
+    //    this is what makes the plugin work on DSH Desktop without `add
+    //    electron`, no matter how the host loads plugins.
+    const hostExe = hostElectronViaProcessTree();
+    if (hostExe !== undefined)
+        return hostExe;
     throw new Error('dsh-builtin-browser: cannot locate the Electron binary. Options: (1) if you are on DSH Desktop, ' +
         'this should never appear — the plugin reuses the host Electron automatically; (2) install electron ' +
-        'into the active profile (`dsh plugin --profile <your-profile> add electron`); (3) set ELECTRON_PATH ' +
-        'to the electron executable. Note: Electron 44+ downloads its binary on first use, so if the package ' +
-        'is installed but the binary is missing, run `npx install-electron` once (needs network) and retry.');
+        'into the active profile (`dsh plugin --profile <your-profile> add electron`; on DSH Desktop the ' +
+        'profile is `desktop`); (3) set ELECTRON_PATH to the electron executable. Note: Electron 44+ downloads ' +
+        'its binary on first use, so if the package is installed but the binary is missing, run ' +
+        '`npx install-electron` once (needs network) and retry.');
+}
+/**
+ * Last-resort Electron discovery: walk this process's ancestry looking for a
+ * parent process whose executable is itself an Electron binary. Covers hosts
+ * that run the plugin in a child Node process of their own Electron main
+ * process (e.g. DSH Desktop): the host binary is already on disk and running,
+ * so reusing it needs no extra install. Filesystem-only on POSIX (/proc); on
+ * Windows a best-effort PowerShell CIM query is used — this path only runs
+ * when every other lookup failed, so its latency never touches the happy
+ * path, and a missing/blocked powershell simply yields nothing.
+ */
+function hostElectronViaProcessTree() {
+    let pid = process.ppid;
+    for (let depth = 0; depth < 6 && pid !== undefined && pid > 1; depth++) {
+        const exe = processExecutable(pid);
+        if (exe !== undefined && isElectronBinary(exe))
+            return exe;
+        pid = processParent(pid);
+    }
+    return undefined;
+}
+/** The executable path of a running process, or undefined when unknown. */
+function processExecutable(pid) {
+    try {
+        if (process.platform === 'win32') {
+            const out = execFileSync('powershell.exe', [
+                '-NoProfile', '-NonInteractive', '-Command',
+                `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").ExecutablePath`,
+            ], { encoding: 'utf8', windowsHide: true, timeout: 3000 });
+            const line = out.trim().split(/\r?\n/)[0] ?? '';
+            return line.length > 0 ? line : undefined;
+        }
+        const exe = readlinkSync(`/proc/${pid}/exe`);
+        return exe.length > 0 ? exe : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The parent pid of a running process, or undefined when unknown. */
+function processParent(pid) {
+    try {
+        if (process.platform === 'win32') {
+            const out = execFileSync('powershell.exe', [
+                '-NoProfile', '-NonInteractive', '-Command',
+                `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").ParentProcessId`,
+            ], { encoding: 'utf8', windowsHide: true, timeout: 3000 });
+            const n = Number(out.trim().split(/\r?\n/)[0]);
+            return Number.isInteger(n) && n > 1 ? n : undefined;
+        }
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        // Format: pid (comm) state ppid ... — comm is parenthesized and may
+        // itself contain spaces/parens, so parse from the LAST ')'; ppid is the
+        // second field after it.
+        const fields = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/);
+        const n = Number(fields[1]);
+        return Number.isInteger(n) && n > 1 ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when the given executable is an Electron binary. The name match
+ * covers dev binaries (electron, electron.exe); the resources marker covers
+ * packaged apps whose exe carries the product name (e.g. "DSH Desktop.exe") —
+ * every Electron distribution ships `resources/electron.asar`,
+ * `resources/app.asar`, or `resources/default_app.asar` beside the binary.
+ */
+function isElectronBinary(exe) {
+    if (basename(exe).toLowerCase().includes('electron'))
+        return true;
+    const resources = join(dirname(exe), 'resources');
+    return existsSync(join(resources, 'electron.asar'))
+        || existsSync(join(resources, 'app.asar'))
+        || existsSync(join(resources, 'default_app.asar'));
 }
 /** Extract an electron version like "43.4.0" from a path containing it. */
 function versionOf(path) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",

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

@@ -25,11 +25,11 @@
  * @module dsh-browser/browser-electron/remote-host
  */
 
-import { spawn, type ChildProcessByStdio } from 'node:child_process'
+import { execFileSync, spawn, type ChildProcessByStdio } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
 import { createRequire } from 'node:module'
-import { existsSync, readdirSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { existsSync, readFileSync, readdirSync, readlinkSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
 import { createServer, type Server, type Socket } from 'node:net'
 import { fileURLToPath } from 'node:url'
 import type { BrowserUserAction, ElectronBrowserViewHost, ElectronViewHandle, ScreenshotOptions } from './provider.js'
@@ -51,7 +51,9 @@ const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024
  *   3. every DSH install anchor + pnpm virtual store candidate, choosing the
  *      NEWEST version found. Older Electron releases (e.g. 33.x) have a
  *      compositor defect that intermittently breaks page capture, so prefer
- *      the newest binary available in the environment.
+ *      the newest binary available in the environment,
+ *   4. last resort: the process ancestry, for hosts that run this plugin in a
+ *      child Node process of their own Electron main process (DSH Desktop).
  * @returns the path to the Electron executable.
  */
 function resolveElectronPath(): string {
@@ -136,20 +138,102 @@ function resolveElectronPath(): string {
       dir = parent
     }
   }
-  if (candidates.length > 0) {
-    candidates.sort((a, b) => compareVersions(b.version, a.version))
-    const best = candidates[0]
-    if (best !== undefined) return best.path
-  }
+  // 4. Last resort for Electron hosts. DSH Desktop may run the agent runtime
+  //    (and thus this plugin) in a plain Node child of its Electron main
+  //    process — step 0 does not fire there, and there is no electron package
+  //    anywhere to find. The host's own binary IS an Electron runtime and is
+  //    guaranteed present (it is running us), so walk the process ancestry
+  //    and reuse the first Electron executable found. Zero extra install;
+  //    this is what makes the plugin work on DSH Desktop without `add
+  //    electron`, no matter how the host loads plugins.
+  const hostExe = hostElectronViaProcessTree()
+  if (hostExe !== undefined) return hostExe
   throw new Error(
     'dsh-builtin-browser: cannot locate the Electron binary. Options: (1) if you are on DSH Desktop, ' +
     'this should never appear — the plugin reuses the host Electron automatically; (2) install electron ' +
-    'into the active profile (`dsh plugin --profile <your-profile> add electron`); (3) set ELECTRON_PATH ' +
-    'to the electron executable. Note: Electron 44+ downloads its binary on first use, so if the package ' +
-    'is installed but the binary is missing, run `npx install-electron` once (needs network) and retry.',
+    'into the active profile (`dsh plugin --profile <your-profile> add electron`; on DSH Desktop the ' +
+    'profile is `desktop`); (3) set ELECTRON_PATH to the electron executable. Note: Electron 44+ downloads ' +
+    'its binary on first use, so if the package is installed but the binary is missing, run ' +
+    '`npx install-electron` once (needs network) and retry.',
   )
 }
 
+/**
+ * Last-resort Electron discovery: walk this process's ancestry looking for a
+ * parent process whose executable is itself an Electron binary. Covers hosts
+ * that run the plugin in a child Node process of their own Electron main
+ * process (e.g. DSH Desktop): the host binary is already on disk and running,
+ * so reusing it needs no extra install. Filesystem-only on POSIX (/proc); on
+ * Windows a best-effort PowerShell CIM query is used — this path only runs
+ * when every other lookup failed, so its latency never touches the happy
+ * path, and a missing/blocked powershell simply yields nothing.
+ */
+function hostElectronViaProcessTree(): string | undefined {
+  let pid: number | undefined = process.ppid
+  for (let depth = 0; depth < 6 && pid !== undefined && pid > 1; depth++) {
+    const exe = processExecutable(pid)
+    if (exe !== undefined && isElectronBinary(exe)) return exe
+    pid = processParent(pid)
+  }
+  return undefined
+}
+
+/** The executable path of a running process, or undefined when unknown. */
+function processExecutable(pid: number): string | undefined {
+  try {
+    if (process.platform === 'win32') {
+      const out = execFileSync('powershell.exe', [
+        '-NoProfile', '-NonInteractive', '-Command',
+        `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").ExecutablePath`,
+      ], { encoding: 'utf8', windowsHide: true, timeout: 3000 })
+      const line = out.trim().split(/\r?\n/)[0] ?? ''
+      return line.length > 0 ? line : undefined
+    }
+    const exe = readlinkSync(`/proc/${pid}/exe`)
+    return exe.length > 0 ? exe : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** The parent pid of a running process, or undefined when unknown. */
+function processParent(pid: number): number | undefined {
+  try {
+    if (process.platform === 'win32') {
+      const out = execFileSync('powershell.exe', [
+        '-NoProfile', '-NonInteractive', '-Command',
+        `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").ParentProcessId`,
+      ], { encoding: 'utf8', windowsHide: true, timeout: 3000 })
+      const n = Number(out.trim().split(/\r?\n/)[0])
+      return Number.isInteger(n) && n > 1 ? n : undefined
+    }
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    // Format: pid (comm) state ppid ... — comm is parenthesized and may
+    // itself contain spaces/parens, so parse from the LAST ')'; ppid is the
+    // second field after it.
+    const fields = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/)
+    const n = Number(fields[1])
+    return Number.isInteger(n) && n > 1 ? n : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * True when the given executable is an Electron binary. The name match
+ * covers dev binaries (electron, electron.exe); the resources marker covers
+ * packaged apps whose exe carries the product name (e.g. "DSH Desktop.exe") —
+ * every Electron distribution ships `resources/electron.asar`,
+ * `resources/app.asar`, or `resources/default_app.asar` beside the binary.
+ */
+function isElectronBinary(exe: string): boolean {
+  if (basename(exe).toLowerCase().includes('electron')) return true
+  const resources = join(dirname(exe), 'resources')
+  return existsSync(join(resources, 'electron.asar'))
+    || existsSync(join(resources, 'app.asar'))
+    || existsSync(join(resources, 'default_app.asar'))
+}
+
 /** Extract an electron version like "43.4.0" from a path containing it. */
 function versionOf(path: string): string {
   const match = /electron@(\d+\.\d+\.\d+)/.exec(path)

package/src/types/electron-shim.d.ts

@@ -57,10 +57,15 @@ declare module 'electron' {
     loadURL(url: string): Promise<void>
     loadFile(path: string): Promise<void>
     send(channel: string, payload: unknown): void
+    focus(): void
     setWindowOpenHandler(handler: (details: { url: string }) => { action: 'deny' } | { action: 'allow' }): void
     getTitle(): string
     getURL(): string
     on(event: 'ipc-message', listener: (event: unknown, channel: string, ...args: unknown[]) => void): this
+    // Windows keyboard focus routing: clicks reach any view, but keyboard
+    // events go only to the focused webContents (electron#28163). `input` is
+    // the raw input event; only its `type` is consumed here.
+    on(event: 'input-event', listener: (event: unknown, input: { type: string }) => void): this
     on(event: 'page-title-updated' | 'did-navigate' | 'did-navigate-in-page' | 'dom-ready', listener: (event: unknown, ...args: unknown[]) => void): this
   }
   export interface WebContentsView {
@@ -88,8 +93,10 @@ declare module 'electron' {
     setTitle(title: string): void
     on(event: 'closed', listener: () => void): this
     on(event: 'resize', listener: () => void): this
+    on(event: 'focus', listener: () => void): this
     off(event: 'closed', listener: () => void): this
     off(event: 'resize', listener: () => void): this
+    off(event: 'focus', listener: () => void): this
   }
   export const app: {
     whenReady(): Promise<void>