minimal-agent 0.12.0 → 0.14.0

package/src/tools/webbrowser/browserControl.ts

@@ -39,34 +39,52 @@ const CAPTCHA_PATTERNS = [
   /press\s+&?\s*hold|click\s+to\s+verify|verifying\s+you/i,
   /点击验证|按住滑块|图片验证|行为验证/i,
 ];
-const OTP_PATTERNS = [/一次性密码|短信验证码|邮件验证码|动态口令|\botp\b|one[- ]time (?:password|code)/i];
+const OTP_PATTERNS = [
+  /一次性密码|短信验证码|邮件验证码|动态口令|\botp\b|one[- ]time (?:password|code)/i,
+];
 const PASSWORD_PATTERNS = [
   /请输入.{0,12}(?:密码|口令)|(?:密码|口令).{0,12}(?:必填|不能为空)/i,
   /(?:enter|type).{0,20}(?:password|passcode)|(?:password|passcode).{0,20}(?:required|cannot be empty)/i,
 ];
-const QR_LOGIN_PATTERNS = [/扫码登录|二维码登录|scan (?:the )?qr|qr code.{0,20}(?:login|sign in)/i];
-const LOGIN_PATTERNS = [/请先登录|登录后继续|扫码登录|sign in to continue|log in to continue/i,
+const QR_LOGIN_PATTERNS = [
+  /扫码登录|二维码登录|scan (?:the )?qr|qr code.{0,20}(?:login|sign in)/i,
+];
+const LOGIN_PATTERNS = [
+  /请先登录|登录后继续|扫码登录|sign in to continue|log in to continue/i,
   /please\s+(?:log|sign)\s+in/i,
 ];
-const BLOCK_PATTERNS = [/操作存在异常|访问请求.{0,8}(暂停|拦截)|请求过于频繁|访问受限|access denied|unusual traffic|temporarily blocked/i,
+const BLOCK_PATTERNS = [
+  /操作存在异常|访问请求.{0,8}(暂停|拦截)|请求过于频繁|访问受限|access denied|unusual traffic|temporarily blocked/i,
   // 403/429 必须落在 HTTP/错误语境里再判风控，避免把「售价 $429」「forbidden fruit」这类正常正文误判成拦截。
   /rate\s+limit(?:ed)?|too\s+many\s+requests|\b403\s+forbidden\b|http[^\n]{0,10}\b(?:403|429)\b|\b(?:error|status)\s*(?:code)?\s*[:：]?\s*(?:403|429)\b/i,
   /被封禁|风控拦截|系统异常/i,
 ];
-const PERMISSION_PATTERNS = [/需要授权|请求权限|permission required|allow access/i];
-const SECURITY_WARNING_PATTERNS = [/安全警告|风险提示|security warning|untrusted (?:application|site|publisher)/i];
+const PERMISSION_PATTERNS = [
+  /需要授权|请求权限|permission required|allow access/i,
+];
+const SECURITY_WARNING_PATTERNS = [
+  /安全警告|风险提示|security warning|untrusted (?:application|site|publisher)/i,
+];
 
 /** Classifies only explicit page signals. It never attempts to solve or bypass a challenge. */
 export function detectBrowserChallenge(text: string): BrowserChallenge | null {
   const normalized = text.replace(/\s+/g, ' ').slice(0, 200_000);
-  if (OTP_PATTERNS.some((pattern) => pattern.test(normalized))) return { reason: 'otp', summary: '页面需要人工输入一次性验证码' };
-  if (CAPTCHA_PATTERNS.some((pattern) => pattern.test(normalized))) return { reason: 'captcha', summary: '页面需要人工完成安全验证' };
-  if (QR_LOGIN_PATTERNS.some((pattern) => pattern.test(normalized))) return { reason: 'qr_login', summary: '页面需要人工扫码登录' };
-  if (PASSWORD_PATTERNS.some((pattern) => pattern.test(normalized))) return { reason: 'password', summary: '页面需要人工输入密码' };
-  if (LOGIN_PATTERNS.some((pattern) => pattern.test(normalized))) return { reason: 'login', summary: '页面需要人工登录' };
-  if (BLOCK_PATTERNS.some((pattern) => pattern.test(normalized))) return { reason: 'blocked', summary: '网站已暂停或拦截当前访问' };
-  if (SECURITY_WARNING_PATTERNS.some((pattern) => pattern.test(normalized))) return { reason: 'security_warning', summary: '页面需要人工处理安全警告' };
-  if (PERMISSION_PATTERNS.some((pattern) => pattern.test(normalized))) return { reason: 'permission', summary: '页面需要人工确认权限' };
+  if (OTP_PATTERNS.some((pattern) => pattern.test(normalized)))
+    return { reason: 'otp', summary: '页面需要人工输入一次性验证码' };
+  if (CAPTCHA_PATTERNS.some((pattern) => pattern.test(normalized)))
+    return { reason: 'captcha', summary: '页面需要人工完成安全验证' };
+  if (QR_LOGIN_PATTERNS.some((pattern) => pattern.test(normalized)))
+    return { reason: 'qr_login', summary: '页面需要人工扫码登录' };
+  if (PASSWORD_PATTERNS.some((pattern) => pattern.test(normalized)))
+    return { reason: 'password', summary: '页面需要人工输入密码' };
+  if (LOGIN_PATTERNS.some((pattern) => pattern.test(normalized)))
+    return { reason: 'login', summary: '页面需要人工登录' };
+  if (BLOCK_PATTERNS.some((pattern) => pattern.test(normalized)))
+    return { reason: 'blocked', summary: '网站已暂停或拦截当前访问' };
+  if (SECURITY_WARNING_PATTERNS.some((pattern) => pattern.test(normalized)))
+    return { reason: 'security_warning', summary: '页面需要人工处理安全警告' };
+  if (PERMISSION_PATTERNS.some((pattern) => pattern.test(normalized)))
+    return { reason: 'permission', summary: '页面需要人工确认权限' };
   return null;
 }
 
@@ -74,6 +92,25 @@ type HumanWaiter = {
   interventionId: string;
 };
 
+/**
+ * 判定「持有者已经死了」的阈值。
+ *
+ * 取值有依据，不是拍脑袋：单次动作的 `timeout` 在 zod schema 里是 `.max(300_000)`，
+ * 语义是**整个序列**（前置探测 + 动作 + 收尾重探）的总时长。所以任何合法的 running
+ * 都有 300s 的硬上界，取 2× 作阈值 —— 合法长动作绝不会被误接管，而泄漏的锁在一个
+ * 动作周期后自动可用，不再是「本进程剩余生命周期内浏览器永久不可用」。
+ *
+ * ⚠️ 改小之前先确认 webbrowser.ts 里 preTimer 与 runSequence 各自的计时器在最长路径上
+ * 不会叠加；`browserControl.test.ts` 用假时钟锁住了这个不变量的行为面。
+ */
+export const DEFAULT_STALE_AFTER_MS = 600_000;
+
+export interface StaleTakeover {
+  previousRunId?: string;
+  previousAction?: string;
+  heldMs: number;
+}
+
 export class BrowserControlCoordinator {
   private state: BrowserControlState = { owner: 'none', status: 'idle' };
   private listeners = new Set<(state: BrowserControlState) => void>();
@@ -82,13 +119,42 @@ export class BrowserControlCoordinator {
   private readonly interventions = new HumanInterventionCoordinator();
   private readonly defaultOwnerId: string;
   private readonly defaultConversationKey: string;
+  private readonly staleAfterMs: number;
+  private readonly now: () => number;
+  private readonly onStaleTakeover: (info: StaleTakeover) => void;
+  /** 进入 running 的时刻；由 setState 统一维护，所以 resume 之后也会重新计时。 */
+  private runningSince = 0;
 
-  constructor(input: { ownerId?: string; conversationKey?: string } = {}) {
+  constructor(
+    input: {
+      ownerId?: string;
+      conversationKey?: string;
+      /** 注入时钟：让「超过阈值」在测试里用假时钟验证，而不是真等 10 分钟。 */
+      now?: () => number;
+      staleAfterMs?: number;
+      onStaleTakeover?: (info: StaleTakeover) => void;
+    } = {},
+  ) {
     this.defaultOwnerId = input.ownerId ?? 'local-owner';
     this.defaultConversationKey = input.conversationKey ?? 'browser:default';
+    this.now = input.now ?? (() => Date.now());
+    this.staleAfterMs = input.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    // 接管**绝不能静默**：不留痕的话，「这把锁曾经泄漏过」就再也查不到了，
+    // 而下一次排查会从一个已经自愈的现场开始 —— 那比报错更难查。
+    this.onStaleTakeover =
+      input.onStaleTakeover ??
+      ((info) => {
+        process.stderr.write(
+          `[browser] 上一个持有者（runId=${info.previousRunId ?? '?'}` +
+            `${info.previousAction ? `, action=${info.previousAction}` : ''}）` +
+            `已持锁 ${Math.round(info.heldMs / 1000)}s，超过 ${Math.round(this.staleAfterMs / 1000)}s 判为泄漏，已接管。\n`,
+        );
+      });
   }
 
-  getState(): BrowserControlState { return this.state; }
+  getState(): BrowserControlState {
+    return this.state;
+  }
 
   subscribe(listener: (state: BrowserControlState) => void): () => void {
     this.listeners.add(listener);
@@ -96,17 +162,42 @@ export class BrowserControlCoordinator {
     return () => this.listeners.delete(listener);
   }
 
-  subscribeInterventions(listener: (event: HumanInterventionEvent) => void): () => void {
+  subscribeInterventions(
+    listener: (event: HumanInterventionEvent) => void,
+  ): () => void {
     return this.interventions.subscribe(listener);
   }
 
-  beginAgent(input: { runId: string; conversationKey?: string; action?: string }): void {
+  beginAgent(input: {
+    runId: string;
+    conversationKey?: string;
+    action?: string;
+  }): void {
     if (this.state.status === 'waiting_human') {
       if (this.state.runId === input.runId) return;
       throw new Error('浏览器正在等待另一个任务的人工处理');
     }
     if (this.state.status === 'running' && this.state.runId !== input.runId) {
-      throw new Error('浏览器正在执行另一个会话的原子操作');
+      const heldMs = this.now() - this.runningSince;
+      if (heldMs < this.staleAfterMs) {
+        // 带上持锁者身份与已持有时长：这把锁是进程级单例，一旦泄漏，后续每次调用都撞
+        // 同一句话，而"另一个会话"是谁、卡在哪个动作上、卡了多久，现场早就没了。
+        // 时长尤其关键 —— 它把「真并发」和「已泄漏」在报错里一眼分开。
+        throw new Error(
+          `浏览器正在执行另一个会话的原子操作（持有者 runId=${this.state.runId ?? '?'}` +
+            `${this.state.action ? `, action=${this.state.action}` : ''}` +
+            `${this.activeIdentity?.conversationKey ? `, conversation=${this.activeIdentity.conversationKey}` : ''}` +
+            `, 已持有 ${Math.round(heldMs / 1000)}s）`,
+        );
+      }
+      // 超过任何合法动作的上界 —— 持有者的 finally 没能跑（进程被外部掐断、
+      // finally 自身抛错、或将来某条还没被想到的路径）。不接管的话，这个进程里的
+      // 浏览器就永久不可用了。接管并留痕，让「失败一次」不再等于「彻底报废」。
+      this.onStaleTakeover({
+        previousRunId: this.state.runId,
+        previousAction: this.state.action,
+        heldMs,
+      });
     }
     this.activeIdentity = {
       ownerId: this.defaultOwnerId,
@@ -125,20 +216,32 @@ export class BrowserControlCoordinator {
 
   requestHuman(
     reason: BrowserHumanReason,
-    input?: { runId?: string; conversationKey?: string; ownerId?: string; summary?: string },
+    input?: {
+      runId?: string;
+      conversationKey?: string;
+      ownerId?: string;
+      summary?: string;
+    },
   ): string {
     if (this.state.status === 'waiting_human') {
-      if (!input?.runId || this.state.runId === input.runId) return this.state.resumeToken;
+      if (!input?.runId || this.state.runId === input.runId)
+        return this.state.resumeToken;
       throw new Error('另一个浏览器任务正在等待人工处理');
     }
     const running = this.state.status === 'running' ? this.state : null;
     const identity: HumanInterventionIdentity = {
-      ownerId: input?.ownerId ?? this.activeIdentity?.ownerId ?? this.defaultOwnerId,
-      conversationKey: input?.conversationKey
-        ?? this.activeIdentity?.conversationKey
-        ?? running?.conversationKey
-        ?? this.defaultConversationKey,
-      runId: input?.runId ?? this.activeIdentity?.runId ?? running?.runId ?? randomUUID(),
+      ownerId:
+        input?.ownerId ?? this.activeIdentity?.ownerId ?? this.defaultOwnerId,
+      conversationKey:
+        input?.conversationKey ??
+        this.activeIdentity?.conversationKey ??
+        running?.conversationKey ??
+        this.defaultConversationKey,
+      runId:
+        input?.runId ??
+        this.activeIdentity?.runId ??
+        running?.runId ??
+        randomUUID(),
     };
     const intervention = this.interventions.request({
       ...identity,
@@ -163,25 +266,51 @@ export class BrowserControlCoordinator {
 
   takeInteractive(input?: { runId?: string; conversationKey?: string }): void {
     if (this.activeIntervention && this.activeIdentity) {
-      this.interventions.cancel(this.credential(this.activeIntervention, this.activeIdentity));
+      this.interventions.cancel(
+        this.credential(this.activeIntervention, this.activeIdentity),
+      );
     }
     this.activeIntervention = null;
     this.activeIdentity = null;
-    this.setState({ owner: 'user', status: 'interactive', runId: input?.runId, conversationKey: input?.conversationKey });
+    this.setState({
+      owner: 'user',
+      status: 'interactive',
+      runId: input?.runId,
+      conversationKey: input?.conversationKey,
+    });
   }
 
   resume(token?: string): boolean {
-    if (this.state.status !== 'waiting_human' || !token || !this.activeIntervention || !this.activeIdentity) return false;
+    if (
+      this.state.status !== 'waiting_human' ||
+      !token ||
+      !this.activeIntervention ||
+      !this.activeIdentity
+    )
+      return false;
     const previous = this.state;
-    const ok = this.interventions.resume(this.credential(this.activeIntervention, this.activeIdentity, token));
+    const ok = this.interventions.resume(
+      this.credential(this.activeIntervention, this.activeIdentity, token),
+    );
     if (!ok) return false;
     this.activeIntervention = null;
-    this.setState({ owner: 'agent', status: 'running', runId: previous.runId, conversationKey: previous.conversationKey, action: '正在检查人工操作结果' });
+    this.setState({
+      owner: 'agent',
+      status: 'running',
+      runId: previous.runId,
+      conversationKey: previous.conversationKey,
+      action: '正在检查人工操作结果',
+    });
     return true;
   }
 
   resumeIntervention(credential: HumanInterventionCredential): boolean {
-    if (this.state.status !== 'waiting_human' || !this.activeIntervention || !this.activeIdentity) return false;
+    if (
+      this.state.status !== 'waiting_human' ||
+      !this.activeIntervention ||
+      !this.activeIdentity
+    )
+      return false;
     const previous = this.state;
     if (!this.interventions.resume(credential)) return false;
     this.activeIntervention = null;
@@ -198,8 +327,11 @@ export class BrowserControlCoordinator {
 
   stop(token?: string): boolean {
     if (this.state.status === 'waiting_human') {
-      if (!token || !this.activeIntervention || !this.activeIdentity) return false;
-      const ok = this.interventions.cancel(this.credential(this.activeIntervention, this.activeIdentity, token));
+      if (!token || !this.activeIntervention || !this.activeIdentity)
+        return false;
+      const ok = this.interventions.cancel(
+        this.credential(this.activeIntervention, this.activeIdentity, token),
+      );
       if (!ok) return false;
     }
     this.activeIntervention = null;
@@ -209,7 +341,12 @@ export class BrowserControlCoordinator {
   }
 
   cancelIntervention(credential: HumanInterventionCredential): boolean {
-    if (this.state.status !== 'waiting_human' || !this.activeIntervention || !this.activeIdentity) return false;
+    if (
+      this.state.status !== 'waiting_human' ||
+      !this.activeIntervention ||
+      !this.activeIdentity
+    )
+      return false;
     if (!this.interventions.cancel(credential)) return false;
     this.activeIntervention = null;
     this.activeIdentity = null;
@@ -218,18 +355,32 @@ export class BrowserControlCoordinator {
   }
 
   waitForHuman(signal?: AbortSignal): Promise<'resumed' | 'stopped'> {
-    if (this.state.status !== 'waiting_human') return Promise.resolve('resumed');
+    if (this.state.status !== 'waiting_human')
+      return Promise.resolve('resumed');
     const intervention = this.activeIntervention;
     if (!intervention) return Promise.resolve('stopped');
     const waiter: HumanWaiter = { interventionId: intervention.id };
-    return this.interventions.wait(waiter.interventionId, signal).then((resolution) => (
-      resolution.status === 'resumed' ? 'resumed' : 'stopped'
-    ));
+    return this.interventions
+      .wait(waiter.interventionId, signal)
+      .then((resolution) =>
+        resolution.status === 'resumed' ? 'resumed' : 'stopped',
+      );
   }
 
   private setState(state: BrowserControlState): void {
+    // 所有进入 running 的路径都在这里重新计时（beginAgent 之外，还有 resume /
+    // resumeIntervention 从人工处理回到 agent 手里）。⚠️ 少了这一条，人工处理
+    // 花掉的时间会被算进持锁时长 —— 用户认真填了十分钟验证码，恢复的瞬间就被判成
+    // 「泄漏」让别人接管，正好惩罚了最该被保护的那条路径。
+    if (state.status === 'running') this.runningSince = this.now();
     this.state = state;
-    for (const listener of this.listeners) listener(state);
+    for (const listener of this.listeners) {
+      try {
+        listener(state);
+      } catch {
+        // Observers are telemetry/UI extensions; control state must remain authoritative.
+      }
+    }
   }
 
   private credential(
@@ -249,14 +400,23 @@ export class BrowserControlCoordinator {
 
 function summaryForReason(reason: BrowserHumanReason): string {
   switch (reason) {
-    case 'captcha': return '页面需要人工完成安全验证';
-    case 'otp': return '页面需要人工输入一次性验证码';
-    case 'password': return '页面需要人工输入密码';
-    case 'qr_login': return '页面需要人工扫码登录';
-    case 'login': return '页面需要人工登录';
-    case 'permission': return '页面需要人工确认权限';
-    case 'security_warning': return '页面需要人工处理安全警告';
-    case 'blocked': return '网站已暂停或拦截当前访问';
-    case 'manual': return '用户已接管浏览器';
+    case 'captcha':
+      return '页面需要人工完成安全验证';
+    case 'otp':
+      return '页面需要人工输入一次性验证码';
+    case 'password':
+      return '页面需要人工输入密码';
+    case 'qr_login':
+      return '页面需要人工扫码登录';
+    case 'login':
+      return '页面需要人工登录';
+    case 'permission':
+      return '页面需要人工确认权限';
+    case 'security_warning':
+      return '页面需要人工处理安全警告';
+    case 'blocked':
+      return '网站已暂停或拦截当前访问';
+    case 'manual':
+      return '用户已接管浏览器';
   }
 }

package/src/tools/webbrowser/browserDaemon.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { dirname, isAbsolute } from 'node:path';
-import { resolveAgentBrowserPath, resolveBundledChromium, resolveSystemBrowser } from './agentBrowserPath.js';
+import { resolveAgentBrowserPath, resolveBundledChromium, resolveSystemBrowser, } from './agentBrowserPath.js';
 import { browserGlobalArgs, runBounded, sessionArgs, spawnRunner, } from './browser.js';
 /** Daemon 启动（拉起 Chrome + CDP 就绪）总预算：超时即掐断并抛可操作错误，绝不无限挂。 */
 export const DAEMON_BRINGUP_TIMEOUT_MS = 45_000;
@@ -50,17 +50,7 @@ export async function reclaimStaleDaemons(deps = {}) {
         const root = dir.toLowerCase().replace(/'/g, "''");
         const ps = 
         // (a) 本 App 路径下的 agent-browser daemon + 其 Chrome 子树。
-        `Get-CimInstance Win32_Process -Filter "Name='agent-browser.exe'" | ` +
-            `Where-Object { $_.ExecutablePath -and $_.ExecutablePath.ToLower().StartsWith('${root}') } | ` +
-            `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }; ` +
-            // (b) 真孤儿 agent-browser Chrome（父进程已死）。daemon 崩溃后残留、上面的 agent-browser 树
-            //     够不着，堆积起来会把新 daemon 的 Chrome 拉起拖到几十秒（实测 18 棵孤儿 → 卡 43s；
-            //     清空后同一启动仅 1s）。**只杀父进程已不在的孤儿**，绝不误伤有活父进程的正常浏览器
-            //     （安装版 App 的活浏览器父 agent-browser 健在 → 不匹配，天然豁免）。
-            `$alive=@{}; Get-CimInstance Win32_Process | ForEach-Object { $alive[[int]$_.ProcessId]=$true }; ` +
-            `Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | ` +
-            `Where-Object { ($_.CommandLine -match 'agent-browser-chrome' -or $_.CommandLine -match '\\.minimal-agent.{0,40}profiles') -and -not $alive.ContainsKey([int]$_.ParentProcessId) } | ` +
-            `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }`;
+        `Get-CimInstance Win32_Process -Filter "Name='agent-browser.exe'" | Where-Object { $_.ExecutablePath -and $_.ExecutablePath.ToLower().StartsWith('${root}') } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }; $alive=@{}; Get-CimInstance Win32_Process | ForEach-Object { $alive[[int]$_.ProcessId]=$true }; Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | Where-Object { ($_.CommandLine -match 'agent-browser-chrome' -or $_.CommandLine -match '\\.minimal-agent.{0,40}profiles') -and -not $alive.ContainsKey([int]$_.ParentProcessId) } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }`;
         await exec('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps]);
     }
     else {
@@ -94,6 +84,17 @@ export async function ensureDaemon(sessionName = 'minimal-agent', opts = {}, dep
     const bin = await deps.resolveBin();
     if (!bin)
         throw new Error('未找到 agent-browser 可执行文件');
+    if (opts.forceRestart) {
+        // The shipped wrapper may launch a daemon from a different resolved
+        // global path. In that case executable-prefix process cleanup is
+        // intentionally conservative and cannot see the daemon. Ask the
+        // session manager to close its own browser first, then apply the scoped
+        // process cleanup as a second line of defense.
+        await deps
+            .runner(bin, [...sessionArgs(sessionName), 'close', '--all'], opts.signal)
+            .catch(() => undefined);
+        await reclaimStaleDaemons(opts.reclaim);
+    }
     const status = await readStatus(bin, sessionName, { signal: opts.signal }, deps);
     if (status.port && status.connected) {
         ports.set(sessionName, status.port);
@@ -143,10 +144,17 @@ export async function ensureDaemon(sessionName = 'minimal-agent', opts = {}, dep
             ]);
             if (ac.signal.aborted)
                 throw bringUpError();
-            if (opened.code !== 0 && browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)) {
+            if (opened.code !== 0 &&
+                browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)) {
                 const chromium = resolveBundledChromium();
                 if (chromium) {
-                    opened = await run([...globals, '--executable-path', chromium, 'open', 'about:blank']);
+                    opened = await run([
+                        ...globals,
+                        '--executable-path',
+                        chromium,
+                        'open',
+                        'about:blank',
+                    ]);
                 }
                 else {
                     const installed = await run(['install']);

package/src/tools/webbrowser/browserDaemon.ts

@@ -1,13 +1,17 @@
 import { spawn } from 'node:child_process';
 import { dirname, isAbsolute } from 'node:path';
 
-import { resolveAgentBrowserPath, resolveBundledChromium, resolveSystemBrowser } from './agentBrowserPath.js';
 import {
+  resolveAgentBrowserPath,
+  resolveBundledChromium,
+  resolveSystemBrowser,
+} from './agentBrowserPath.js';
+import {
+  type AgentBrowserRunner,
   browserGlobalArgs,
   runBounded,
   sessionArgs,
   spawnRunner,
-  type AgentBrowserRunner,
 } from './browser.js';
 
 export interface BrowserDaemonInfo {
@@ -30,6 +34,8 @@ export interface EnsureDaemonOptions {
   signal?: AbortSignal;
   timeoutMs?: number;
   reclaim?: ReclaimDeps;
+  /** Forcefully rebuild a browser whose CDP endpoint has gone stale. */
+  forceRestart?: boolean;
 }
 
 /**
@@ -78,7 +84,9 @@ export interface ReclaimDeps {
  * 或系统上别处的 agent-browser 用法（对标 scripts/dev-browser.ts::reclaimStalePort）。无法作用域限定
  * （PATH 上裸二进制 / 没装）时保守放弃，不做全局杀。幂等、best-effort（失败静默）。
  */
-export async function reclaimStaleDaemons(deps: ReclaimDeps = {}): Promise<void> {
+export async function reclaimStaleDaemons(
+  deps: ReclaimDeps = {},
+): Promise<void> {
   const platform = deps.platform ?? process.platform;
   const exec = deps.exec ?? realReclaimExec;
   const resolveDir =
@@ -94,17 +102,7 @@ export async function reclaimStaleDaemons(deps: ReclaimDeps = {}): Promise<void>
     const root = dir.toLowerCase().replace(/'/g, "''");
     const ps =
       // (a) 本 App 路径下的 agent-browser daemon + 其 Chrome 子树。
-      `Get-CimInstance Win32_Process -Filter "Name='agent-browser.exe'" | ` +
-      `Where-Object { $_.ExecutablePath -and $_.ExecutablePath.ToLower().StartsWith('${root}') } | ` +
-      `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }; ` +
-      // (b) 真孤儿 agent-browser Chrome（父进程已死）。daemon 崩溃后残留、上面的 agent-browser 树
-      //     够不着，堆积起来会把新 daemon 的 Chrome 拉起拖到几十秒（实测 18 棵孤儿 → 卡 43s；
-      //     清空后同一启动仅 1s）。**只杀父进程已不在的孤儿**，绝不误伤有活父进程的正常浏览器
-      //     （安装版 App 的活浏览器父 agent-browser 健在 → 不匹配，天然豁免）。
-      `$alive=@{}; Get-CimInstance Win32_Process | ForEach-Object { $alive[[int]$_.ProcessId]=$true }; ` +
-      `Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | ` +
-      `Where-Object { ($_.CommandLine -match 'agent-browser-chrome' -or $_.CommandLine -match '\\.minimal-agent.{0,40}profiles') -and -not $alive.ContainsKey([int]$_.ParentProcessId) } | ` +
-      `ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }`;
+      `Get-CimInstance Win32_Process -Filter "Name='agent-browser.exe'" | Where-Object { $_.ExecutablePath -and $_.ExecutablePath.ToLower().StartsWith('${root}') } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }; $alive=@{}; Get-CimInstance Win32_Process | ForEach-Object { $alive[[int]$_.ProcessId]=$true }; Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | Where-Object { ($_.CommandLine -match 'agent-browser-chrome' -or $_.CommandLine -match '\\.minimal-agent.{0,40}profiles') -and -not $alive.ContainsKey([int]$_.ParentProcessId) } | ForEach-Object { taskkill /F /T /PID $_.ProcessId 2>$null | Out-Null }`;
     await exec('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps]);
   } else {
     // unix：按可执行路径前缀 pkill agent-browser（其 Chrome 子进程随之收尾）。unix 孤儿会被
@@ -121,7 +119,9 @@ function parsePort(text: string): number | null {
 }
 
 function browserRuntimeMissing(text: string): boolean {
-  return /browser\s+(?:not found|was not found)|chrom(?:e|ium).*(?:not found|missing)|executable.*(?:not found|does not exist)|run ['\"]?agent-browser install/i.test(text);
+  return /browser\s+(?:not found|was not found)|chrom(?:e|ium).*(?:not found|missing)|executable.*(?:not found|does not exist)|run ['\"]?agent-browser install/i.test(
+    text,
+  );
 }
 
 export { browserRuntimeMissing as _browserRuntimeMissing };
@@ -153,7 +153,23 @@ export async function ensureDaemon(
 ): Promise<BrowserDaemonInfo> {
   const bin = await deps.resolveBin();
   if (!bin) throw new Error('未找到 agent-browser 可执行文件');
-  const status = await readStatus(bin, sessionName, { signal: opts.signal }, deps);
+  if (opts.forceRestart) {
+    // The shipped wrapper may launch a daemon from a different resolved
+    // global path. In that case executable-prefix process cleanup is
+    // intentionally conservative and cannot see the daemon. Ask the
+    // session manager to close its own browser first, then apply the scoped
+    // process cleanup as a second line of defense.
+    await deps
+      .runner(bin, [...sessionArgs(sessionName), 'close', '--all'], opts.signal)
+      .catch(() => undefined);
+    await reclaimStaleDaemons(opts.reclaim);
+  }
+  const status = await readStatus(
+    bin,
+    sessionName,
+    { signal: opts.signal },
+    deps,
+  );
   if (status.port && status.connected) {
     ports.set(sessionName, status.port);
     return { sessionName, streamPort: status.port, alreadyRunning: true };
@@ -202,18 +218,30 @@ export async function ensureDaemon(
         'about:blank',
       ]);
       if (ac.signal.aborted) throw bringUpError();
-      if (opened.code !== 0 && browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)) {
+      if (
+        opened.code !== 0 &&
+        browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)
+      ) {
         const chromium = resolveBundledChromium();
         if (chromium) {
-          opened = await run([...globals, '--executable-path', chromium, 'open', 'about:blank']);
+          opened = await run([
+            ...globals,
+            '--executable-path',
+            chromium,
+            'open',
+            'about:blank',
+          ]);
         } else {
           const installed = await run(['install']);
-          if (installed.code === 0) opened = await run([...globals, 'open', 'about:blank']);
+          if (installed.code === 0)
+            opened = await run([...globals, 'open', 'about:blank']);
         }
         if (ac.signal.aborted) throw bringUpError();
       }
       if (opened.code !== 0) {
-        throw new Error((opened.stderr || opened.stdout || '浏览器启动失败').trim());
+        throw new Error(
+          (opened.stderr || opened.stdout || '浏览器启动失败').trim(),
+        );
       }
       const streamPort = await waitForStreamPort(sessionName, 10_000, deps);
       ports.set(sessionName, streamPort);
@@ -235,7 +263,12 @@ export async function stopDaemon(
   const bin = await deps.resolveBin();
   ports.delete(sessionName);
   if (bin) {
-    await runBounded(bin, [...sessionArgs(sessionName), 'close'], { timeoutMs: STATUS_TIMEOUT_MS }, deps.runner);
+    await runBounded(
+      bin,
+      [...sessionArgs(sessionName), 'close'],
+      { timeoutMs: STATUS_TIMEOUT_MS },
+      deps.runner,
+    );
   }
   // 优雅 close 之外再 tree-kill 一遍本 App 路径下的残留：崩溃/close 不彻底时仍杜绝临时 profile
   // 孤儿 Chrome 堆积（实测同时存活 ≥2 棵孤儿 Chrome 树的根因）。

package/src/tools/webbrowser/browserFrames.js

@@ -0,0 +1,47 @@
+/** Fixed, read-only expression for observing nested same-origin frame trees. */
+export const FRAME_INFO_EXPRESSION = `(() => { const walk = (doc, parentId = '', path = '') => Array.from(doc.querySelectorAll('iframe,frame')).flatMap((el, index) => { const id = 'dom-frame-' + (path ? path + '-' : '') + index; const item = { id, ...(parentId ? { parentId } : {}), url: el.src || '', name: el.name || undefined }; try { return [item, ...walk(el.contentDocument, id, id.replace('dom-frame-', ''))]; } catch { return [item]; } }); return walk(document); })()`;
+/** Normalize the recursive, browser-owned frame tree returned by CDP. */
+export function normalizeFrameTree(value) {
+    const frames = [];
+    const walk = (node, parentId) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const item = node;
+        if (typeof item.frame?.id !== 'string' || !item.frame.id)
+            return;
+        const id = item.frame.id;
+        frames.push({
+            id,
+            ...(parentId ? { parentId } : {}),
+            url: typeof item.frame.url === 'string' ? item.frame.url : '',
+            ...(typeof item.frame.name === 'string' && item.frame.name
+                ? { name: item.frame.name }
+                : {}),
+        });
+        for (const child of item.childFrames ?? [])
+            walk(child, id);
+    };
+    walk(value);
+    return frames;
+}
+export function normalizeFrameInfo(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        if (!item || typeof item !== 'object')
+            return [];
+        const frame = item;
+        if (typeof frame.id !== 'string' || typeof frame.url !== 'string')
+            return [];
+        return [
+            {
+                id: frame.id,
+                url: frame.url,
+                ...(typeof frame.parentId === 'string'
+                    ? { parentId: frame.parentId }
+                    : {}),
+                ...(typeof frame.name === 'string' ? { name: frame.name } : {}),
+            },
+        ];
+    });
+}