minimal-agent 0.10.0 → 0.12.0

package/src/tools/webbrowser/browserControl.ts

@@ -0,0 +1,262 @@
+import { randomUUID } from 'node:crypto';
+import {
+  HumanInterventionCoordinator,
+  type HumanInterventionCredential,
+  type HumanInterventionEvent,
+  type HumanInterventionIdentity,
+  type HumanInterventionReason,
+  type PendingHumanIntervention,
+} from '../../humanIntervention.js';
+
+export type BrowserHumanReason = HumanInterventionReason;
+
+/**
+ * 控制权状态的**定义已搬进 `src/web/protocol.ts`**（线路协议自持形状），
+ * 这里只 re-export，工具侧既有 import 路径一律不变。
+ *
+ * 为什么搬：desktop 与 server 都从 `minimal-agent/protocol` 取线路类型，
+ * 若协议反过来 import 这个工具模块，本工具的任何重构都会顺着协议波及两个
+ * 外部消费方。方向必须是工具依赖协议。`test/kernelPurity.test.ts` 守这条线
+ * ——它正是靠这条规则把本处揪出来的。
+ */
+// 注意是 import + 再 export 两步：单写 `export type { X } from '...'` 只做
+// **再导出**，不会把名字带进本文件的作用域，而下面有五处内部引用要用到它。
+import type { BrowserControlState } from '../../web/protocol.js';
+export type { BrowserControlState };
+
+export interface BrowserChallenge {
+  reason: Exclude<BrowserHumanReason, 'manual'>;
+  summary: string;
+}
+
+const CAPTCHA_PATTERNS = [
+  /captcha/i,
+  /验证码|安全验证|人机验证|完成.{0,8}验证|拖动.{0,12}(滑块|拼图)|滑动.{0,12}(滑块|拼图)/i,
+  /verify\s+(?:you are|that you are)\s+(?:a\s+)?human/i,
+  // Additional patterns: reCAPTCHA / hCaptcha / Turnstile / Cloudflare / etc.
+  /i\s*'?m\s+not\s+a\s+robot/i,
+  /checking\s+your\s+browser/i,
+  /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 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,
+  /please\s+(?:log|sign)\s+in/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];
+
+/** 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: '页面需要人工确认权限' };
+  return null;
+}
+
+type HumanWaiter = {
+  interventionId: string;
+};
+
+export class BrowserControlCoordinator {
+  private state: BrowserControlState = { owner: 'none', status: 'idle' };
+  private listeners = new Set<(state: BrowserControlState) => void>();
+  private activeIdentity: HumanInterventionIdentity | null = null;
+  private activeIntervention: PendingHumanIntervention | null = null;
+  private readonly interventions = new HumanInterventionCoordinator();
+  private readonly defaultOwnerId: string;
+  private readonly defaultConversationKey: string;
+
+  constructor(input: { ownerId?: string; conversationKey?: string } = {}) {
+    this.defaultOwnerId = input.ownerId ?? 'local-owner';
+    this.defaultConversationKey = input.conversationKey ?? 'browser:default';
+  }
+
+  getState(): BrowserControlState { return this.state; }
+
+  subscribe(listener: (state: BrowserControlState) => void): () => void {
+    this.listeners.add(listener);
+    listener(this.state);
+    return () => this.listeners.delete(listener);
+  }
+
+  subscribeInterventions(listener: (event: HumanInterventionEvent) => void): () => void {
+    return this.interventions.subscribe(listener);
+  }
+
+  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('浏览器正在执行另一个会话的原子操作');
+    }
+    this.activeIdentity = {
+      ownerId: this.defaultOwnerId,
+      conversationKey: input.conversationKey ?? this.defaultConversationKey,
+      runId: input.runId,
+    };
+    this.setState({ owner: 'agent', status: 'running', ...input });
+  }
+
+  finishAgent(runId: string): void {
+    if (this.state.status === 'running' && this.state.runId === runId) {
+      this.activeIdentity = null;
+      this.setState({ owner: 'none', status: 'idle' });
+    }
+  }
+
+  requestHuman(
+    reason: BrowserHumanReason,
+    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;
+      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(),
+    };
+    const intervention = this.interventions.request({
+      ...identity,
+      surface: 'browser',
+      reason,
+      sanitizedSummary: input?.summary ?? summaryForReason(reason),
+    });
+    this.activeIdentity = identity;
+    this.activeIntervention = intervention;
+    this.setState({
+      owner: 'user',
+      status: 'waiting_human',
+      runId: identity.runId,
+      conversationKey: identity.conversationKey,
+      reason,
+      interventionId: intervention.id,
+      resumeToken: intervention.resumeToken,
+      ownerId: identity.ownerId,
+    });
+    return intervention.resumeToken;
+  }
+
+  takeInteractive(input?: { runId?: string; conversationKey?: string }): void {
+    if (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 });
+  }
+
+  resume(token?: string): boolean {
+    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));
+    if (!ok) return false;
+    this.activeIntervention = null;
+    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;
+    const previous = this.state;
+    if (!this.interventions.resume(credential)) return false;
+    this.activeIntervention = null;
+    this.activeIdentity = null;
+    this.setState({
+      owner: 'agent',
+      status: 'running',
+      runId: previous.runId,
+      conversationKey: previous.conversationKey,
+      action: '正在检查人工操作结果',
+    });
+    return true;
+  }
+
+  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 (!ok) return false;
+    }
+    this.activeIntervention = null;
+    this.activeIdentity = null;
+    this.setState({ owner: 'user', status: 'interactive' });
+    return true;
+  }
+
+  cancelIntervention(credential: HumanInterventionCredential): boolean {
+    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;
+    this.setState({ owner: 'user', status: 'interactive' });
+    return true;
+  }
+
+  waitForHuman(signal?: AbortSignal): Promise<'resumed' | 'stopped'> {
+    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'
+    ));
+  }
+
+  private setState(state: BrowserControlState): void {
+    this.state = state;
+    for (const listener of this.listeners) listener(state);
+  }
+
+  private credential(
+    intervention: PendingHumanIntervention,
+    identity: HumanInterventionIdentity,
+    resumeToken = intervention.resumeToken,
+  ): HumanInterventionCredential {
+    return {
+      id: intervention.id,
+      resumeToken,
+      ownerId: identity.ownerId,
+      conversationKey: identity.conversationKey,
+      runId: identity.runId,
+    };
+  }
+}
+
+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 '用户已接管浏览器';
+  }
+}

package/src/tools/webbrowser/browserDaemon.js

@@ -1,7 +1,74 @@
+import { spawn } from 'node:child_process';
+import { dirname, isAbsolute } from 'node:path';
 import { resolveAgentBrowserPath, resolveBundledChromium, resolveSystemBrowser } from './agentBrowserPath.js';
-import { browserGlobalArgs, sessionArgs, spawnRunner } from './browser.js';
+import { browserGlobalArgs, runBounded, sessionArgs, spawnRunner, } from './browser.js';
+/** Daemon 启动（拉起 Chrome + CDP 就绪）总预算：超时即掐断并抛可操作错误，绝不无限挂。 */
+export const DAEMON_BRINGUP_TIMEOUT_MS = 45_000;
+/** 单次 `stream status` 探测预算：daemon socket 卡死时不拖累调用方。 */
+export const STATUS_TIMEOUT_MS = 8_000;
 const ports = new Map();
 const starts = new Map();
+const realDaemonDeps = {
+    resolveBin: resolveAgentBrowserPath,
+    runner: spawnRunner,
+};
+const realReclaimExec = (file, args) => new Promise((resolve) => {
+    try {
+        const child = spawn(file, args, { stdio: 'ignore', windowsHide: true });
+        child.on('close', () => resolve());
+        child.on('error', () => resolve());
+    }
+    catch {
+        resolve();
+    }
+});
+/**
+ * 回收「本仓库/本 App 的」残留 agent-browser daemon + 其 Chrome 子树（Windows `taskkill /F /T`）。
+ *
+ * 根因：agent-browser 的 daemon 是「黏」的后台进程，`--profile`/`--executable-path` 等 launch-only
+ * flag 首次启动即固化、之后忽略（见 readStatus 头注）。一次无 profile 的启动就毒化整个 session，
+ * 之后复用继承临时 profile、重启 App 也不解，且孤儿 Chrome 堆积。宿主（Desktop runtime）在启动时
+ * 调用一次本函数，把上一轮残留清干净，下次 bring-up 便以我们的持久 `--profile` 干净重启。
+ *
+ * 安全：**仅**按「已解析二进制所在目录前缀」作用域匹配 agent-browser.exe，绝不误伤安装版桌面 App
+ * 或系统上别处的 agent-browser 用法（对标 scripts/dev-browser.ts::reclaimStalePort）。无法作用域限定
+ * （PATH 上裸二进制 / 没装）时保守放弃，不做全局杀。幂等、best-effort（失败静默）。
+ */
+export async function reclaimStaleDaemons(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const exec = deps.exec ?? realReclaimExec;
+    const resolveDir = deps.binDir ??
+        (async () => {
+            const bin = await resolveAgentBrowserPath();
+            return bin && isAbsolute(bin) ? dirname(bin) : null;
+        });
+    const dir = await resolveDir();
+    if (!dir)
+        return;
+    ports.clear();
+    if (platform === 'win32') {
+        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 }`;
+        await exec('powershell', ['-NoProfile', '-NonInteractive', '-Command', ps]);
+    }
+    else {
+        // unix：按可执行路径前缀 pkill agent-browser（其 Chrome 子进程随之收尾）。unix 孤儿会被
+        // reparent 到 init，无「父已死」信号，故此处不做等价的孤儿 Chrome 清扫（Windows 才是主战场）。
+        await exec('pkill', ['-f', `${dir}/agent-browser`]);
+    }
+}
 function parsePort(text) {
     const match = text.match(/ws:\/\/(?:127\.0\.0\.1|localhost):([0-9]+)/i);
     if (!match)
@@ -13,82 +80,123 @@ function browserRuntimeMissing(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 };
-async function readStatus(bin, sessionName) {
+async function readStatus(bin, sessionName, opts = {}, deps = realDaemonDeps) {
     // Profile/executable flags are launch-only. Repeating them against a running
     // daemon makes agent-browser ignore the profile and emit misleading warnings.
-    const result = await spawnRunner(bin, [...sessionArgs(sessionName), 'stream', 'status']);
+    // 有界：daemon socket 卡死时不把 status 探测拖成无限挂（getStreamPort/ensureDaemon 都靠它）。
+    const result = await runBounded(bin, [...sessionArgs(sessionName), 'stream', 'status'], { signal: opts.signal, timeoutMs: opts.timeoutMs ?? STATUS_TIMEOUT_MS }, deps.runner);
     if (result.code !== 0)
         return { port: null, connected: false };
     const text = `${result.stdout}\n${result.stderr}`;
     return { port: parsePort(text), connected: /Connected:\s*true/i.test(text) };
 }
-export async function ensureDaemon(sessionName = 'minimal-agent') {
-    const bin = await resolveAgentBrowserPath();
+export async function ensureDaemon(sessionName = 'minimal-agent', opts = {}, deps = realDaemonDeps) {
+    const bin = await deps.resolveBin();
     if (!bin)
         throw new Error('未找到 agent-browser 可执行文件');
-    const status = await readStatus(bin, sessionName);
+    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 };
     }
+    // 半死 daemon（socket 端口在、但 Chrome 已亡 connected:false）：对谁都没用，先回收再重启，
+    // 否则新 open 可能连到无 Chrome 的僵尸 daemon 上卡死。回收对健康的共享 daemon 无影响（那会
+    // 走上面的 connected 分支直接复用）。
+    if (status.port && !status.connected) {
+        await reclaimStaleDaemons(opts.reclaim);
+    }
     const pending = starts.get(sessionName);
     if (pending)
         return pending;
+    const budget = opts.timeoutMs ?? DAEMON_BRINGUP_TIMEOUT_MS;
     const start = (async () => {
-        const globals = await browserGlobalArgs(sessionName);
-        // Prefer a stable system browser executable, but always use KakadeAI's
-        // isolated profile. Bundled Chromium remains an offline fallback.
-        const systemBrowser = resolveSystemBrowser();
-        let opened = await spawnRunner(bin, [
-            ...globals,
-            ...(systemBrowser ? ['--executable-path', systemBrowser] : []),
-            'open',
-            'about:blank',
-        ]);
-        if (opened.code !== 0 && browserRuntimeMissing(`${opened.stderr}\n${opened.stdout}`)) {
-            const chromium = resolveBundledChromium();
-            if (chromium) {
-                opened = await spawnRunner(bin, [...globals, '--executable-path', chromium, 'open', 'about:blank']);
+        // Bring-up 边界：父级 signal abort 或超预算即掐断所有内部子进程。旧缺陷是 ensureDaemon
+        // 全程无 timeout、不接 signal —— Chrome/CDP 起不来时无限挂、用户 stop/ESC 也掐不断
+        // （「访问网站卡 5m53s」的根因）。这里统一一个控制器兜住整段启动。
+        const ac = new AbortController();
+        let timedOut = false;
+        const onParent = () => ac.abort(opts.signal?.reason);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            ac.abort();
+        }, budget);
+        if (opts.signal) {
+            if (opts.signal.aborted)
+                ac.abort(opts.signal.reason);
+            else
+                opts.signal.addEventListener('abort', onParent, { once: true });
+        }
+        const bringUpError = () => new Error(timedOut
+            ? `内置浏览器启动超时：Chrome 未在 ${Math.round(budget / 1000)}s 内就绪（可能被残留浏览器进程占用）。可稍后重试，或改用 WebFetch 读取网页。`
+            : '内置浏览器启动已被中断。');
+        const run = (args) => deps.runner(bin, args, ac.signal);
+        try {
+            const globals = await browserGlobalArgs(sessionName);
+            // Prefer a stable system browser executable, but always use KakadeAI's
+            // isolated profile. Bundled Chromium remains an offline fallback.
+            const systemBrowser = resolveSystemBrowser();
+            let opened = await run([
+                ...globals,
+                ...(systemBrowser ? ['--executable-path', systemBrowser] : []),
+                'open',
+                'about:blank',
+            ]);
+            if (ac.signal.aborted)
+                throw bringUpError();
+            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']);
+                }
+                else {
+                    const installed = await run(['install']);
+                    if (installed.code === 0)
+                        opened = await run([...globals, 'open', 'about:blank']);
+                }
+                if (ac.signal.aborted)
+                    throw bringUpError();
             }
-            else {
-                const installed = await spawnRunner(bin, ['install']);
-                if (installed.code === 0)
-                    opened = await spawnRunner(bin, [...globals, 'open', 'about:blank']);
+            if (opened.code !== 0) {
+                throw new Error((opened.stderr || opened.stdout || '浏览器启动失败').trim());
             }
+            const streamPort = await waitForStreamPort(sessionName, 10_000, deps);
+            ports.set(sessionName, streamPort);
+            return { sessionName, streamPort, alreadyRunning: false };
         }
-        if (opened.code !== 0) {
-            throw new Error((opened.stderr || opened.stdout || '浏览器启动失败').trim());
+        finally {
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', onParent);
         }
-        const streamPort = await waitForStreamPort(sessionName, 10_000);
-        ports.set(sessionName, streamPort);
-        return { sessionName, streamPort, alreadyRunning: false };
     })().finally(() => starts.delete(sessionName));
     starts.set(sessionName, start);
     return start;
 }
-export async function stopDaemon(sessionName = 'minimal-agent') {
-    const bin = await resolveAgentBrowserPath();
+export async function stopDaemon(sessionName = 'minimal-agent', deps = realDaemonDeps, reclaim) {
+    const bin = await deps.resolveBin();
     ports.delete(sessionName);
-    if (!bin)
-        return;
-    await spawnRunner(bin, [...sessionArgs(sessionName), 'close']);
+    if (bin) {
+        await runBounded(bin, [...sessionArgs(sessionName), 'close'], { timeoutMs: STATUS_TIMEOUT_MS }, deps.runner);
+    }
+    // 优雅 close 之外再 tree-kill 一遍本 App 路径下的残留：崩溃/close 不彻底时仍杜绝临时 profile
+    // 孤儿 Chrome 堆积（实测同时存活 ≥2 棵孤儿 Chrome 树的根因）。
+    await reclaimStaleDaemons(reclaim);
 }
-export async function getStreamPort(sessionName = 'minimal-agent') {
+export async function getStreamPort(sessionName = 'minimal-agent', deps = realDaemonDeps) {
     const cached = ports.get(sessionName);
     if (cached)
         return cached;
-    const bin = await resolveAgentBrowserPath();
+    const bin = await deps.resolveBin();
     if (!bin)
         return null;
-    const port = (await readStatus(bin, sessionName)).port;
+    const port = (await readStatus(bin, sessionName, {}, deps)).port;
     if (port)
         ports.set(sessionName, port);
     return port;
 }
-export async function waitForStreamPort(sessionName = 'minimal-agent', timeoutMs = 10_000) {
+export async function waitForStreamPort(sessionName = 'minimal-agent', timeoutMs = 10_000, deps = realDaemonDeps) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        const port = await getStreamPort(sessionName);
+        const port = await getStreamPort(sessionName, deps);
         if (port)
             return port;
         await new Promise((resolve) => setTimeout(resolve, 120));