dsh-builtin-browser 0.4.8 → 0.4.9

package/CHANGELOG.md

@@ -4,6 +4,52 @@
 
 ---
 
+# 第四十五轮(2026-10-15,系统浏览器载体的启动生命周期:多开空白页 + 重启后孤儿)
+
+报告者给了一份很硬的证据链 —— CDP `/json/list` 每 200ms 采样的时序、五处建议改法、以及**一条自我更正**(他撤回的第一条建议:去掉启动参数里的 URL 会让 Chrome 变成两个窗口,更糟)。两个问题都发生"把浏览器拉起来"的那一刻,除此之外毫无关系。
+
+## 一、启动那个页面被丢弃,多出来的空白页无法关闭
+
+**现象**:每次载体启动都看到 2 个空白标签,其中一个被关掉或残留;残留的那个**不在插件的标签模型里**(`dsh_browser_list_tabs` 只报 1 个),所以 `dsh_browser_close_tab` 关不掉它,窗口长期不关时会累积。
+
+**根因两处**:
+1. `start()` 的启动参数末尾带 `about:blank`,而 Chrome 自己的启动页也在 —— 实测**干净退出后的全新启动也是 2 个页面**,所以不是崩溃恢复,是 Chrome 的固有行为(报告者做了对照实验排除,并保留了那句参数:去掉它会变成 2 个**窗口**)。
+2. `buildSession()` 用 `Target.createTarget({url:'about:blank'})` **新建**,而不是领养已经存在的那一个 → 启动那个被永久丢弃。
+
+**修法**:连上后 `Target.setDiscoverTargets({discover:true})` + `Target.getTargets`,把无人认领的空白页收成**最多 1 个**(只关 `about:blank` 与 `chrome://newtab*`,且**绝不碰已在 `sessions` 里的**);`buildSession()` 先领养那个空白页,没有再新建。**`setDiscoverTargets` 不能省** —— 不先开发现,`getTargets` 可能列不出握手前就存在的页面,而**那正是需要关掉的那个**;报告者第一版补丁就是因此静默失效。
+
+## 二、DSH 重启后旧的载体浏览器成为孤儿,下一次 open 必定失败
+
+**现象**:重启 dsh 后,上次拉起的 Chrome 仍在跑;第一次调用直接报 `exited immediately after launch (exit code 0)`,必须手动杀掉用该 profile 的进程才能恢复。
+
+**根因**:`start()` 里"杀掉上一个浏览器"只在 `this.child !== undefined` 时执行,而 **DSH 重启后新进程里 `this.child` 是空的** → 旧实例没人管 → 新实例把请求移交给它然后退出 0 → 而这个退出被判成"启动失败"。
+
+**修法**:`start()` **在 spawn 之前**先 `adoptRunningBrowser()` —— 读本 profile 的 `DevToolsActivePort`,要求端点自报家门(`/json/version` 的 `Browser` 字段 + `Browser.getVersion` 的 `product`,都必须像浏览器),通过就接管,**不 spawn**;启动回来是 hand-off(exit 0)时再试一次接管。
+
+**为什么"接管"是安全的**:启动循环刻意不信任上一次留下的端口文件,理由正当(端口号会被复用到非浏览器进程上)。但**这里多两个前提**:文件在**本插件自己的 profile 目录**里(只有用这个 `--user-data-dir` 启动的浏览器会写它),而且端点要**两次**自证是浏览器。
+
+**顺带撤销一处有害的"保护"**:spawn 前删除 `DevToolsActivePort` 被去掉了。它保护不到任何东西 —— `freshPort()` 本来就只认 spawn 之后写入的文件 —— 却销毁了"那个浏览器还在跑"的唯一记录,而那正是接管所需要的。测试里那条"过期文件必须已被删除"的断言随之反正。
+
+## 三、teardown:先请它自己关,再杀
+
+`dispose()` 原本固定超时后 `kill()`,而 Windows 上那是 `TerminateProcess`:浏览器来不及写 profile,Chrome 会把这次结束记成崩溃 —— **下一次启动因此触发会话恢复,用户看到一个多出来的窗口**。现在先发 CDP `Browser.close`,给 `CLOSE_GRACE_MS`(6s,`unref` 的定时器,不拖住进程退出)让它自己走,仍在才杀。
+
+## 四、这一轮最该记住的事:同一个位置之前碰过三次,每次只修了一层
+
+用户的疑问是"我记得之前改过类似的,怎么又犯了"。查证后:**不是回归,是一个决定从来没被做过**。
+
+| 轮次 | 当时解决的 | 当时没解决的 |
+| --- | --- | --- |
+| 第三十三轮 | "只认本次启动写下的端口"(mtime),不再误连到别的进程 | 那个**真浏览器**被留在原地没人管 |
+| 第三十六轮 | `'exited'` 的文案按退出码区分,不再把崩溃码也说成残留进程 | **它已经准确描述了 hand-off 这个现象,却仍然把它当失败报出来** |
+| 第三十七轮 | `forgetBrowserState` 覆盖"进程已退出、`this.child` 被清空"的形态,视图不再指向死浏览器 | 孤儿进程**仍然占着 profile** |
+
+三次都走到了同一个岔路口,三次都只修了自己那一面 —— **没人问"那浏览器还在跑,我们为什么不接上它"**。第三十六轮那句文案尤其值得记:它把 hand-off 描述得足够清楚,于是读到它的人和报告者都得出"去手动杀掉残留进程"的结论,而正确的结论是"这不该是一个错误"。
+
+**测试**:254 → 260(新增 6 条生命周期守卫:接管先于启动、hand-off 读作"已经在那儿"、发现先于列举、只保留一个空白、领养而非丢弃、teardown 先请后杀)。`tsc` 干净。
+
+---
+
 # 第四十四轮(2026-10-14,工具名空间:`browser_*` → `dsh_browser_*`)
 
 腾讯 BrowserSkill 的 DSH 插件(`@wxg-prc-cpg/browser-skill-dsh-plugin` @0.3.2)与本插件同装时,它六个工具一个都注册不上。根因不是它的 bug:双方都往**全局**工具层注册了 `browser_session`,宿主对重名直接抛错,而它把注册包在 `try/catch` 里只 `console.warn` —— 桌面版看不到 stdout,于是表现成"插件完全没反应"。用户先怀疑的是它坏了。

package/lib/browser-electron/system-browser.d.ts

@@ -111,6 +111,16 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      */
     private clientSuspect;
     private child;
+    /**
+     * True when the browser in use was adopted from a previous run rather than launched here.
+     *
+     * Worth recording because the two differ on teardown: a browser this host spawned is its to
+     * kill, while one it merely took over belongs to a process that is already gone — closing it is
+     * still right (it holds the profile nobody else can use), but it is a decision, not cleanup.
+     */
+    private adoptedRunning;
+    /** Whether this connection's surplus blank pages have been collapsed already. */
+    private blanksNormalized;
     private starting;
     /**
      * Browsers that ignored a kill.
@@ -167,6 +177,25 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      */
     private forgetBrowserState;
     private ensureClient;
+    /**
+     * Take over a browser already serving this profile, instead of racing it.
+     *
+     * A previous DSH process leaves its browser running: the child handle died with that process, so
+     * nothing here knows about it, and `start()`'s cleanup branch is skipped because it keys on
+     * `this.child`. Launching then does something worse than fail — on Windows Chrome hands the
+     * request to the instance already holding the profile and exits 0, and that exit is read as a
+     * launch failure. The user is told to go kill the leftovers by hand, on every restart, which is
+     * exactly what was reported.
+     *
+     * The launch loop deliberately refuses to trust a `<profile>/DevToolsActivePort` left by a
+     * previous launch, and it is right to: a stale port number can be reused by something that is
+     * not a browser at all. What makes adoption safe HERE is that this runs BEFORE launching, on a
+     * file that lives inside this plugin's own profile directory — only a browser started with this
+     * `--user-data-dir` writes it — and the endpoint is then asked to identify itself.
+     * @param why - a short phrase for the log, naming which attempt this is.
+     * @returns a connected client for the running browser, or undefined when there is none.
+     */
+    private adoptRunningBrowser;
     /**
      * Launch the browser with a private profile and connect over CDP.
      *
@@ -236,6 +265,37 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
     private ensureSession;
     /** Create and attach the target for one view. Serialised by {@link ensureSession}. */
     private buildSession;
+    /**
+     * Take an unclaimed blank page, if the browser has one to spare.
+     *
+     * "Unclaimed" is what matters: a blank page the plugin is already driving belongs to a view, and
+     * handing the same target to a second view would make two views share one page. The page kept by
+     * {@link normalizeBlankPages} is exactly the unclaimed one this is looking for.
+     * @param client - the connected browser.
+     * @returns the target id to reuse, or undefined when a new page has to be created.
+     */
+    private adoptBlankTarget;
+    /** Create one page, refusing to go on without an id. */
+    private createTarget;
+    /**
+     * Collapse the blank pages a freshly started browser comes with down to one.
+     *
+     * Chrome opens more than one page when it is given a URL on top of its own start page, and this
+     * is the browser's behaviour rather than a session restore: measured on a cleanly exited profile
+     * as well as a crashed one, both pages appear within a second of launch. There is nothing to
+     * configure away — by the time a client can talk to the browser, both already exist.
+     *
+     * Left alone the surplus page is invisible to the plugin's tab model and therefore unclosable
+     * through the tools, so it survives every navigation and accumulates for as long as the window
+     * lives. One is kept deliberately: {@link buildSession} adopts it instead of creating a third.
+     *
+     * `Target.setDiscoverTargets` has to come first. Without it the browser may omit pages that
+     * existed before this client connected — which is precisely the page that needs closing, and the
+     * reason the first attempt at this fix failed silently.
+     * @param client - the connected browser.
+     * @returns how many surplus blank pages were closed.
+     */
+    private normalizeBlankPages;
     /** Views whose session is being created right now, so a second caller waits for the first. */
     private readonly sessionBuilding;
     /** sessionId -> targetId, so a destroyed view can close the right page. */

package/lib/browser-electron/system-browser.js

@@ -36,6 +36,15 @@ import { join } from 'node:path';
  * exited, and that exit was reported as a bad browser path.
  */
 const EXIT_GRACE_MS = 3_000;
+/**
+ * How long a browser is given to close itself after being asked, before it is killed.
+ *
+ * Long enough for Chrome to flush its profile, which is what keeps the next launch from reading
+ * the profile as crashed and offering a session restore. Deliberately not the same knob as
+ * {@link EXIT_GRACE_MS}: that one waits for a browser to die because a NEW one cannot start until
+ * it does, this one merely prefers a graceful exit to a kill.
+ */
+const CLOSE_GRACE_MS = 6_000;
 /**
  * Ceiling on one attempt to ask a discovered CDP port who it is.
  *
@@ -147,6 +156,21 @@ const INSTALL_LOCATIONS = {
  * @param env - the environment to resolve against.
  * @returns the path with %NAME% references replaced, or the entry unchanged when unknown.
  */
+/**
+ * Whether a target URL is one of the blanks a browser opens by itself.
+ *
+ * Deliberately narrow: `about:blank` and Chrome's own new-tab pages, and nothing else. A wider
+ * test ("has no path", "starts with chrome://") would sooner or later match a page the user is
+ * reading, and the caller closes what this returns.
+ * @param url - the target's reported URL.
+ */
+function isBlankUrl(url) {
+    if (typeof url !== 'string')
+        return false;
+    return url === 'about:blank'
+        || url.startsWith('chrome://newtab')
+        || url.startsWith('chrome://new-tab-page');
+}
 function expandLocation(location, env) {
     return location.replace(/%([^%]+)%/g, (whole, name) => env[name] ?? env[name.toUpperCase()] ?? env[name.toLowerCase()] ?? whole);
 }
@@ -385,6 +409,16 @@ export class SystemBrowserViewHost {
      */
     clientSuspect = false;
     child;
+    /**
+     * True when the browser in use was adopted from a previous run rather than launched here.
+     *
+     * Worth recording because the two differ on teardown: a browser this host spawned is its to
+     * kill, while one it merely took over belongs to a process that is already gone — closing it is
+     * still right (it holds the profile nobody else can use), but it is a decision, not cleanup.
+     */
+    adoptedRunning = false;
+    /** Whether this connection's surplus blank pages have been collapsed already. */
+    blanksNormalized = false;
     starting;
     /**
      * Browsers that ignored a kill.
@@ -468,6 +502,10 @@ export class SystemBrowserViewHost {
     forgetBrowserState() {
         this.views.clear();
         this.sessions.clear();
+        // A new browser comes with its own surplus pages, so the tidy-up runs again for it. Without
+        // this, a restart would inherit the previous connection's "already handled" and leave the new
+        // browser's extra blank page in place for the rest of the session.
+        this.blanksNormalized = false;
     }
     async ensureClient() {
         // A disposed host must never start a browser: doing so would spawn a process
@@ -501,7 +539,78 @@ export class SystemBrowserViewHost {
         }
         // Concurrent first calls share one startup rather than racing two browsers.
         this.starting ??= this.start().finally(() => { this.starting = undefined; });
-        return await this.starting;
+        const client = await this.starting;
+        // Once per connection. A browser opens more than one page when it starts, and the surplus is
+        // invisible to the plugin's tab model — see normalizeBlankPages for why that matters.
+        if (!this.blanksNormalized) {
+            this.blanksNormalized = true;
+            await this.normalizeBlankPages(client);
+        }
+        return client;
+    }
+    /**
+     * Take over a browser already serving this profile, instead of racing it.
+     *
+     * A previous DSH process leaves its browser running: the child handle died with that process, so
+     * nothing here knows about it, and `start()`'s cleanup branch is skipped because it keys on
+     * `this.child`. Launching then does something worse than fail — on Windows Chrome hands the
+     * request to the instance already holding the profile and exits 0, and that exit is read as a
+     * launch failure. The user is told to go kill the leftovers by hand, on every restart, which is
+     * exactly what was reported.
+     *
+     * The launch loop deliberately refuses to trust a `<profile>/DevToolsActivePort` left by a
+     * previous launch, and it is right to: a stale port number can be reused by something that is
+     * not a browser at all. What makes adoption safe HERE is that this runs BEFORE launching, on a
+     * file that lives inside this plugin's own profile directory — only a browser started with this
+     * `--user-data-dir` writes it — and the endpoint is then asked to identify itself.
+     * @param why - a short phrase for the log, naming which attempt this is.
+     * @returns a connected client for the running browser, or undefined when there is none.
+     */
+    async adoptRunningBrowser(why) {
+        const portFile = join(this.profileDir, 'DevToolsActivePort');
+        let port;
+        try {
+            if (!existsSync(portFile))
+                return undefined;
+            const value = Number(readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '');
+            if (!Number.isInteger(value) || value <= 0)
+                return undefined;
+            port = value;
+        }
+        catch {
+            return undefined;
+        }
+        try {
+            const version = await (await fetch(`http://127.0.0.1:${port}/json/version`, {
+                signal: AbortSignal.timeout(PORT_PROBE_MS),
+            })).json();
+            if (typeof version.webSocketDebuggerUrl !== 'string')
+                return undefined;
+            // The port number alone proves nothing — it can be reused once the browser that owned it
+            // exits. The endpoint's own answer is the evidence, and it has to name a browser.
+            if (typeof version.Browser !== 'string' || !/chrome|chromium|edge/i.test(version.Browser))
+                return undefined;
+            const client = new CdpClient(version.webSocketDebuggerUrl);
+            await client.whenReady();
+            // Asked through the protocol too, so a websocket that merely accepts connections is not
+            // mistaken for a browser that answers.
+            const info = await client.send('Browser.getVersion', {});
+            if (typeof info?.product !== 'string' || !/chrome|chromium|edge/i.test(info.product)) {
+                client.close();
+                return undefined;
+            }
+            if (this.disposed) {
+                client.close();
+                return undefined;
+            }
+            this.client = client;
+            this.adoptedRunning = true;
+            return client;
+        }
+        catch {
+            // No endpoint, nothing listening, or not a browser: all of them mean "launch one".
+            return undefined;
+        }
     }
     /**
      * Launch the browser with a private profile and connect over CDP.
@@ -512,6 +621,12 @@ export class SystemBrowserViewHost {
      * @returns the connected client.
      */
     async start() {
+        // Before spawning anything: is a browser for THIS profile already running? A DSH restart
+        // leaves one behind, and launching into it is the failure reported as "exited immediately
+        // after launch (exit code 0)" that required killing seven processes by hand.
+        const adopted = await this.adoptRunningBrowser('before launch');
+        if (adopted !== undefined)
+            return adopted;
         const args = [
             '--remote-debugging-port=0',
             `--user-data-dir=${this.profileDir}`,
@@ -569,15 +684,14 @@ export class SystemBrowserViewHost {
                 });
             });
         }
-        // The port file belongs to the browser that just died, and it is NOT removed when the
-        // process is killed: nothing gives a terminated browser a chance to clean up. The launch
-        // loop below reads it to learn the port, so a stale file means connecting to whatever else
-        // holds that port — or to the previous instance — and publishing a client this host does
-        // not own and dispose() can never kill.
-        try {
-            rmSync(join(this.profileDir, 'DevToolsActivePort'), { force: true });
-        }
-        catch { /* nothing to remove */ }
+        // The port file is deliberately NOT deleted here, and that is a reversal.
+        //
+        // It used to be removed so the launch loop below could not read a previous browser's port. But
+        // the loop already refuses any file older than the spawn (`freshPort` compares mtimes), so the
+        // deletion never protected it — while it DID destroy the only record of a browser that may
+        // still be running for this profile. That record is what `adoptRunningBrowser` needs when the
+        // launch comes back as a hand-off: the browser was alive the whole time, and without the file
+        // there is no way to find it again.
         const spawnedAt = Date.now();
         let child;
         try {
@@ -728,6 +842,14 @@ export class SystemBrowserViewHost {
             const code = child.exitCode;
             const signal = child.signalCode;
             const clean = code === 0 && signal === null;
+            // Exit code 0 IS the hand-off: the request went to an instance already holding this profile,
+            // so that instance is our browser and it is running right now. Adopting it turns the
+            // reported "kill the leftovers by hand, on every restart" into a call that just works.
+            if (clean) {
+                const recovered = await this.adoptRunningBrowser('after a hand-off');
+                if (recovered !== undefined)
+                    return recovered;
+            }
             throw new Error(clean
                 ? `dsh-builtin-browser: ${target} exited immediately after launch (exit code 0). `
                     + 'That means it handed the request to an instance already using this profile '
@@ -892,20 +1014,39 @@ export class SystemBrowserViewHost {
         if (this.disposed)
             return;
         this.disposed = true;
+        const client = this.client;
         this.forgetBrowserState();
-        this.client?.close();
-        try {
-            this.child?.kill();
-        }
-        catch { /* already gone */ }
-        // And anything that ignored an earlier kill. They hold this profile, so leaving them
-        // running means the next launch contends with a browser nobody owns.
-        for (const leftover of this.stubborn.splice(0)) {
+        this.client = undefined;
+        // Ask before killing. `kill()` on Windows is TerminateProcess, which gives the browser no
+        // chance to flush its profile — and Chrome records how it ended in that profile, so a
+        // hard kill leaves it marked as a crash and the NEXT launch offers to restore a session.
+        // That is a visible symptom (an extra window) traced all the way back to this line.
+        if (client !== undefined) {
             try {
-                leftover.kill();
+                void client.send('Browser.close', {}).catch(() => { });
             }
             catch { /* already gone */ }
         }
+        // Both the browser we launched and anything that ignored an earlier kill. They hold this
+        // profile, so leaving them running means the next launch contends with a browser nobody owns.
+        const doomed = [this.child, ...this.stubborn.splice(0)].filter((entry) => entry !== undefined);
+        this.child = undefined;
+        for (const dying of doomed) {
+            /**
+             * A bounded reprieve, then the kill we used to do immediately.
+             *
+             * The timer is unref'd so it never holds the process open: a DSH shutdown that is itself
+             * ending does not wait for this, and the browser — having been asked to close — generally
+             * gets there on its own. If it does not, the kill still lands while the process lives.
+             */
+            const force = () => { try {
+                dying.kill();
+            }
+            catch { /* already gone */ } };
+            const timer = setTimeout(force, CLOSE_GRACE_MS);
+            timer.unref?.();
+            dying.once('exit', () => { clearTimeout(timer); });
+        }
         const ephemeral = this.ephemeralDir;
         if (ephemeral !== undefined && this.child !== undefined) {
             // The browser flushes its profile while shutting down, so deleting later avoids
@@ -957,10 +1098,15 @@ export class SystemBrowserViewHost {
     /** Create and attach the target for one view. Serialised by {@link ensureSession}. */
     async buildSession(viewId) {
         const client = await this.ensureClient();
-        const created = await client.send('Target.createTarget', { url: 'about:blank' });
-        const targetId = created?.targetId;
-        if (typeof targetId !== 'string')
-            throw new Error('dsh-builtin-browser: the browser did not create a page');
+        // Adopt a blank page the browser opened on its own before creating another one.
+        //
+        // Chrome starts with more than one page when handed a URL on top of its own start page, so
+        // creating a target here discarded the original and left it behind as a tab that is not in
+        // the plugin's tab model — invisible to `dsh_browser_list_tabs`, and therefore unclosable
+        // through the tools. Taking the blank instead makes the page the browser already opened the
+        // one the caller gets.
+        const adopted = await this.adoptBlankTarget(client);
+        const targetId = adopted ?? await this.createTarget(client);
         const attached = await client.send('Target.attachToTarget', { targetId, flatten: true });
         const sessionId = attached?.sessionId;
         if (typeof sessionId !== 'string')
@@ -970,6 +1116,94 @@ export class SystemBrowserViewHost {
         this.views.set(viewId, { session: sessionId, client });
         return sessionId;
     }
+    /**
+     * Take an unclaimed blank page, if the browser has one to spare.
+     *
+     * "Unclaimed" is what matters: a blank page the plugin is already driving belongs to a view, and
+     * handing the same target to a second view would make two views share one page. The page kept by
+     * {@link normalizeBlankPages} is exactly the unclaimed one this is looking for.
+     * @param client - the connected browser.
+     * @returns the target id to reuse, or undefined when a new page has to be created.
+     */
+    async adoptBlankTarget(client) {
+        try {
+            const listed = await client.send('Target.getTargets', {});
+            const claimed = new Set(this.sessions.values());
+            for (const entry of listed?.targetInfos ?? []) {
+                if (entry.type !== 'page' || typeof entry.targetId !== 'string')
+                    continue;
+                if (!isBlankUrl(entry.url))
+                    continue;
+                if (claimed.has(entry.targetId))
+                    continue;
+                return entry.targetId;
+            }
+            return undefined;
+        }
+        catch {
+            // Discovery is best-effort; creating a page is the behaviour this replaced.
+            return undefined;
+        }
+    }
+    /** Create one page, refusing to go on without an id. */
+    async createTarget(client) {
+        const created = await client.send('Target.createTarget', { url: 'about:blank' });
+        const targetId = created?.targetId;
+        if (typeof targetId !== 'string')
+            throw new Error('dsh-builtin-browser: the browser did not create a page');
+        return targetId;
+    }
+    /**
+     * Collapse the blank pages a freshly started browser comes with down to one.
+     *
+     * Chrome opens more than one page when it is given a URL on top of its own start page, and this
+     * is the browser's behaviour rather than a session restore: measured on a cleanly exited profile
+     * as well as a crashed one, both pages appear within a second of launch. There is nothing to
+     * configure away — by the time a client can talk to the browser, both already exist.
+     *
+     * Left alone the surplus page is invisible to the plugin's tab model and therefore unclosable
+     * through the tools, so it survives every navigation and accumulates for as long as the window
+     * lives. One is kept deliberately: {@link buildSession} adopts it instead of creating a third.
+     *
+     * `Target.setDiscoverTargets` has to come first. Without it the browser may omit pages that
+     * existed before this client connected — which is precisely the page that needs closing, and the
+     * reason the first attempt at this fix failed silently.
+     * @param client - the connected browser.
+     * @returns how many surplus blank pages were closed.
+     */
+    async normalizeBlankPages(client) {
+        try {
+            await client.send('Target.setDiscoverTargets', { discover: true });
+            const listed = await client.send('Target.getTargets', {});
+            const blanks = (listed?.targetInfos ?? []).filter(entry => entry.type === 'page' && typeof entry.targetId === 'string' && isBlankUrl(entry.url));
+            const claimed = new Set(this.sessions.values());
+            let closed = 0;
+            // Keep the first unclaimed blank (that is the one buildSession will adopt) and close the rest.
+            let kept = false;
+            for (const entry of blanks) {
+                const targetId = entry.targetId;
+                if (claimed.has(targetId))
+                    continue;
+                if (!kept) {
+                    kept = true;
+                    continue;
+                }
+                try {
+                    await client.send('Target.closeTarget', { targetId });
+                    closed += 1;
+                }
+                catch {
+                    // It may already be gone; one failure must not stop the rest.
+                }
+            }
+            return closed;
+        }
+        catch {
+            // A browser that will not answer Target commands has a real problem, and the next command
+            // will report it. Turning a tidy-up into a functional error here would hide that.
+            return 0;
+        }
+    }
     /** Views whose session is being created right now, so a second caller waits for the first. */
     sessionBuilding = new Map();
     /** sessionId -> targetId, so a destroyed view can close the right page. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "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 (dsh_browser_auth), CAPTCHA detection, batch form fill (dsh_browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",

package/src/browser-electron/system-browser.ts

@@ -38,6 +38,15 @@ import { join } from 'node:path'
  * exited, and that exit was reported as a bad browser path.
  */
 const EXIT_GRACE_MS = 3_000
+/**
+ * How long a browser is given to close itself after being asked, before it is killed.
+ *
+ * Long enough for Chrome to flush its profile, which is what keeps the next launch from reading
+ * the profile as crashed and offering a session restore. Deliberately not the same knob as
+ * {@link EXIT_GRACE_MS}: that one waits for a browser to die because a NEW one cannot start until
+ * it does, this one merely prefers a graceful exit to a kill.
+ */
+const CLOSE_GRACE_MS = 6_000
 
 /**
  * Ceiling on one attempt to ask a discovered CDP port who it is.
@@ -178,6 +187,21 @@ const INSTALL_LOCATIONS: Record<DetectedBrowser['kind'], Partial<Record<NodeJS.P
  * @param env - the environment to resolve against.
  * @returns the path with %NAME% references replaced, or the entry unchanged when unknown.
  */
+/**
+ * Whether a target URL is one of the blanks a browser opens by itself.
+ *
+ * Deliberately narrow: `about:blank` and Chrome's own new-tab pages, and nothing else. A wider
+ * test ("has no path", "starts with chrome://") would sooner or later match a page the user is
+ * reading, and the caller closes what this returns.
+ * @param url - the target's reported URL.
+ */
+function isBlankUrl(url: unknown): boolean {
+  if (typeof url !== 'string') return false
+  return url === 'about:blank'
+    || url.startsWith('chrome://newtab')
+    || url.startsWith('chrome://new-tab-page')
+}
+
 function expandLocation(location: string, env: NodeJS.ProcessEnv): string {
   return location.replace(/%([^%]+)%/g, (whole, name: string) =>
     env[name] ?? env[name.toUpperCase()] ?? env[name.toLowerCase()] ?? whole)
@@ -415,6 +439,16 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
    */
   private clientSuspect = false
   private child: ChildProcess | undefined
+  /**
+   * True when the browser in use was adopted from a previous run rather than launched here.
+   *
+   * Worth recording because the two differ on teardown: a browser this host spawned is its to
+   * kill, while one it merely took over belongs to a process that is already gone — closing it is
+   * still right (it holds the profile nobody else can use), but it is a decision, not cleanup.
+   */
+  private adoptedRunning = false
+  /** Whether this connection's surplus blank pages have been collapsed already. */
+  private blanksNormalized = false
   private starting: Promise<CdpClient> | undefined
 
   /**
@@ -503,6 +537,10 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   private forgetBrowserState(): void {
     this.views.clear()
     this.sessions.clear()
+    // A new browser comes with its own surplus pages, so the tidy-up runs again for it. Without
+    // this, a restart would inherit the previous connection's "already handled" and leave the new
+    // browser's extra blank page in place for the rest of the session.
+    this.blanksNormalized = false
   }
 
   private async ensureClient(): Promise<CdpClient> {
@@ -535,7 +573,70 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     }
     // Concurrent first calls share one startup rather than racing two browsers.
     this.starting ??= this.start().finally(() => { this.starting = undefined })
-    return await this.starting
+    const client = await this.starting
+    // Once per connection. A browser opens more than one page when it starts, and the surplus is
+    // invisible to the plugin's tab model — see normalizeBlankPages for why that matters.
+    if (!this.blanksNormalized) {
+      this.blanksNormalized = true
+      await this.normalizeBlankPages(client)
+    }
+    return client
+  }
+
+  /**
+   * Take over a browser already serving this profile, instead of racing it.
+   *
+   * A previous DSH process leaves its browser running: the child handle died with that process, so
+   * nothing here knows about it, and `start()`'s cleanup branch is skipped because it keys on
+   * `this.child`. Launching then does something worse than fail — on Windows Chrome hands the
+   * request to the instance already holding the profile and exits 0, and that exit is read as a
+   * launch failure. The user is told to go kill the leftovers by hand, on every restart, which is
+   * exactly what was reported.
+   *
+   * The launch loop deliberately refuses to trust a `<profile>/DevToolsActivePort` left by a
+   * previous launch, and it is right to: a stale port number can be reused by something that is
+   * not a browser at all. What makes adoption safe HERE is that this runs BEFORE launching, on a
+   * file that lives inside this plugin's own profile directory — only a browser started with this
+   * `--user-data-dir` writes it — and the endpoint is then asked to identify itself.
+   * @param why - a short phrase for the log, naming which attempt this is.
+   * @returns a connected client for the running browser, or undefined when there is none.
+   */
+  private async adoptRunningBrowser(why: string): Promise<CdpClient | undefined> {
+    const portFile = join(this.profileDir, 'DevToolsActivePort')
+    let port: number
+    try {
+      if (!existsSync(portFile)) return undefined
+      const value = Number(readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '')
+      if (!Number.isInteger(value) || value <= 0) return undefined
+      port = value
+    } catch {
+      return undefined
+    }
+    try {
+      const version = await (await fetch(`http://127.0.0.1:${port}/json/version`, {
+        signal: AbortSignal.timeout(PORT_PROBE_MS),
+      })).json() as { webSocketDebuggerUrl?: string; Browser?: string }
+      if (typeof version.webSocketDebuggerUrl !== 'string') return undefined
+      // The port number alone proves nothing — it can be reused once the browser that owned it
+      // exits. The endpoint's own answer is the evidence, and it has to name a browser.
+      if (typeof version.Browser !== 'string' || !/chrome|chromium|edge/i.test(version.Browser)) return undefined
+      const client = new CdpClient(version.webSocketDebuggerUrl)
+      await client.whenReady()
+      // Asked through the protocol too, so a websocket that merely accepts connections is not
+      // mistaken for a browser that answers.
+      const info = await client.send('Browser.getVersion', {}) as { product?: string }
+      if (typeof info?.product !== 'string' || !/chrome|chromium|edge/i.test(info.product)) {
+        client.close()
+        return undefined
+      }
+      if (this.disposed) { client.close(); return undefined }
+      this.client = client
+      this.adoptedRunning = true
+      return client
+    } catch {
+      // No endpoint, nothing listening, or not a browser: all of them mean "launch one".
+      return undefined
+    }
   }
 
   /**
@@ -547,6 +648,11 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
    * @returns the connected client.
    */
   private async start(): Promise<CdpClient> {
+    // Before spawning anything: is a browser for THIS profile already running? A DSH restart
+    // leaves one behind, and launching into it is the failure reported as "exited immediately
+    // after launch (exit code 0)" that required killing seven processes by hand.
+    const adopted = await this.adoptRunningBrowser('before launch')
+    if (adopted !== undefined) return adopted
     const args = [
       '--remote-debugging-port=0',
       `--user-data-dir=${this.profileDir}`,
@@ -598,12 +704,14 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
         })
       })
     }
-    // The port file belongs to the browser that just died, and it is NOT removed when the
-    // process is killed: nothing gives a terminated browser a chance to clean up. The launch
-    // loop below reads it to learn the port, so a stale file means connecting to whatever else
-    // holds that port — or to the previous instance — and publishing a client this host does
-    // not own and dispose() can never kill.
-    try { rmSync(join(this.profileDir, 'DevToolsActivePort'), { force: true }) } catch { /* nothing to remove */ }
+    // The port file is deliberately NOT deleted here, and that is a reversal.
+    //
+    // It used to be removed so the launch loop below could not read a previous browser's port. But
+    // the loop already refuses any file older than the spawn (`freshPort` compares mtimes), so the
+    // deletion never protected it — while it DID destroy the only record of a browser that may
+    // still be running for this profile. That record is what `adoptRunningBrowser` needs when the
+    // launch comes back as a hand-off: the browser was alive the whole time, and without the file
+    // there is no way to find it again.
     const spawnedAt = Date.now()
     let child: ReturnType<typeof spawn>
     try {
@@ -723,6 +831,13 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       const code = child.exitCode
       const signal = child.signalCode
       const clean = code === 0 && signal === null
+      // Exit code 0 IS the hand-off: the request went to an instance already holding this profile,
+      // so that instance is our browser and it is running right now. Adopting it turns the
+      // reported "kill the leftovers by hand, on every restart" into a call that just works.
+      if (clean) {
+        const recovered = await this.adoptRunningBrowser('after a hand-off')
+        if (recovered !== undefined) return recovered
+      }
       throw new Error(
         clean
           ? `dsh-builtin-browser: ${target} exited immediately after launch (exit code 0). `
@@ -892,13 +1007,34 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   dispose(): void {
     if (this.disposed) return
     this.disposed = true
+    const client = this.client
     this.forgetBrowserState()
-    this.client?.close()
-    try { this.child?.kill() } catch { /* already gone */ }
-    // And anything that ignored an earlier kill. They hold this profile, so leaving them
-    // running means the next launch contends with a browser nobody owns.
-    for (const leftover of this.stubborn.splice(0)) {
-      try { leftover.kill() } catch { /* already gone */ }
+    this.client = undefined
+    // Ask before killing. `kill()` on Windows is TerminateProcess, which gives the browser no
+    // chance to flush its profile — and Chrome records how it ended in that profile, so a
+    // hard kill leaves it marked as a crash and the NEXT launch offers to restore a session.
+    // That is a visible symptom (an extra window) traced all the way back to this line.
+    if (client !== undefined) {
+      try { void client.send('Browser.close', {}).catch(() => { /* it is closing, not talking */ }) } catch { /* already gone */ }
+    }
+    // Both the browser we launched and anything that ignored an earlier kill. They hold this
+    // profile, so leaving them running means the next launch contends with a browser nobody owns.
+    const doomed = [this.child, ...this.stubborn.splice(0)].filter(
+      (entry): entry is ChildProcess => entry !== undefined,
+    )
+    this.child = undefined
+    for (const dying of doomed) {
+      /**
+       * A bounded reprieve, then the kill we used to do immediately.
+       *
+       * The timer is unref'd so it never holds the process open: a DSH shutdown that is itself
+       * ending does not wait for this, and the browser — having been asked to close — generally
+       * gets there on its own. If it does not, the kill still lands while the process lives.
+       */
+      const force = (): void => { try { dying.kill() } catch { /* already gone */ } }
+      const timer = setTimeout(force, CLOSE_GRACE_MS)
+      timer.unref?.()
+      dying.once('exit', () => { clearTimeout(timer) })
     }
     const ephemeral = this.ephemeralDir
     if (ephemeral !== undefined && this.child !== undefined) {
@@ -945,9 +1081,15 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   /** Create and attach the target for one view. Serialised by {@link ensureSession}. */
   private async buildSession(viewId: string): Promise<string> {
     const client = await this.ensureClient()
-    const created = await client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
-    const targetId = created?.targetId
-    if (typeof targetId !== 'string') throw new Error('dsh-builtin-browser: the browser did not create a page')
+    // Adopt a blank page the browser opened on its own before creating another one.
+    //
+    // Chrome starts with more than one page when handed a URL on top of its own start page, so
+    // creating a target here discarded the original and left it behind as a tab that is not in
+    // the plugin's tab model — invisible to `dsh_browser_list_tabs`, and therefore unclosable
+    // through the tools. Taking the blank instead makes the page the browser already opened the
+    // one the caller gets.
+    const adopted = await this.adoptBlankTarget(client)
+    const targetId = adopted ?? await this.createTarget(client)
     const attached = await client.send('Target.attachToTarget', { targetId, flatten: true }) as { sessionId?: string }
     const sessionId = attached?.sessionId
     if (typeof sessionId !== 'string') throw new Error('dsh-builtin-browser: the browser did not attach to the new page')
@@ -957,6 +1099,92 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     return sessionId
   }
 
+  /**
+   * Take an unclaimed blank page, if the browser has one to spare.
+   *
+   * "Unclaimed" is what matters: a blank page the plugin is already driving belongs to a view, and
+   * handing the same target to a second view would make two views share one page. The page kept by
+   * {@link normalizeBlankPages} is exactly the unclaimed one this is looking for.
+   * @param client - the connected browser.
+   * @returns the target id to reuse, or undefined when a new page has to be created.
+   */
+  private async adoptBlankTarget(client: CdpClient): Promise<string | undefined> {
+    try {
+      const listed = await client.send('Target.getTargets', {}) as {
+        targetInfos?: Array<{ targetId?: string; type?: string; url?: string }>
+      }
+      const claimed = new Set(this.sessions.values())
+      for (const entry of listed?.targetInfos ?? []) {
+        if (entry.type !== 'page' || typeof entry.targetId !== 'string') continue
+        if (!isBlankUrl(entry.url)) continue
+        if (claimed.has(entry.targetId)) continue
+        return entry.targetId
+      }
+      return undefined
+    } catch {
+      // Discovery is best-effort; creating a page is the behaviour this replaced.
+      return undefined
+    }
+  }
+
+  /** Create one page, refusing to go on without an id. */
+  private async createTarget(client: CdpClient): Promise<string> {
+    const created = await client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
+    const targetId = created?.targetId
+    if (typeof targetId !== 'string') throw new Error('dsh-builtin-browser: the browser did not create a page')
+    return targetId
+  }
+
+  /**
+   * Collapse the blank pages a freshly started browser comes with down to one.
+   *
+   * Chrome opens more than one page when it is given a URL on top of its own start page, and this
+   * is the browser's behaviour rather than a session restore: measured on a cleanly exited profile
+   * as well as a crashed one, both pages appear within a second of launch. There is nothing to
+   * configure away — by the time a client can talk to the browser, both already exist.
+   *
+   * Left alone the surplus page is invisible to the plugin's tab model and therefore unclosable
+   * through the tools, so it survives every navigation and accumulates for as long as the window
+   * lives. One is kept deliberately: {@link buildSession} adopts it instead of creating a third.
+   *
+   * `Target.setDiscoverTargets` has to come first. Without it the browser may omit pages that
+   * existed before this client connected — which is precisely the page that needs closing, and the
+   * reason the first attempt at this fix failed silently.
+   * @param client - the connected browser.
+   * @returns how many surplus blank pages were closed.
+   */
+  private async normalizeBlankPages(client: CdpClient): Promise<number> {
+    try {
+      await client.send('Target.setDiscoverTargets', { discover: true })
+      const listed = await client.send('Target.getTargets', {}) as {
+        targetInfos?: Array<{ targetId?: string; type?: string; url?: string }>
+      }
+      const blanks = (listed?.targetInfos ?? []).filter(
+        entry => entry.type === 'page' && typeof entry.targetId === 'string' && isBlankUrl(entry.url),
+      )
+      const claimed = new Set(this.sessions.values())
+      let closed = 0
+      // Keep the first unclaimed blank (that is the one buildSession will adopt) and close the rest.
+      let kept = false
+      for (const entry of blanks) {
+        const targetId = entry.targetId as string
+        if (claimed.has(targetId)) continue
+        if (!kept) { kept = true; continue }
+        try {
+          await client.send('Target.closeTarget', { targetId })
+          closed += 1
+        } catch {
+          // It may already be gone; one failure must not stop the rest.
+        }
+      }
+      return closed
+    } catch {
+      // A browser that will not answer Target commands has a real problem, and the next command
+      // will report it. Turning a tidy-up into a functional error here would hide that.
+      return 0
+    }
+  }
+
   /** Views whose session is being created right now, so a second caller waits for the first. */
   private readonly sessionBuilding = new Map<string, Promise<string>>()