wtagent 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -13,16 +13,37 @@ WTAgent 把 GPT 网页聊天连接到本地工具，提供类似 Codex 的 CLI A
 网页 GPT 负责思考，WTAgent 在本机：
 
 - 读取和修改本地文件
-- 调用本地 Shell，运行构建、测试和开发服务
+- 调用结构化本地命令，运行构建、测试和开发服务
 
 不需要 OpenAI API Key，也不要求 ChatGPT Pro。WTAgent 使用独立的 Chrome Profile 保存你的网页登录状态，并使用该账号在网页上实际可用的模型和额度；如果账号拥有 Pro，它会成为额外优势。
 
+支持矩阵：
+
+- macOS
+- Linux
+- Windows 10 1809+ / Windows 11 x64
+- Windows ARM64 目前为预览支持
+
+边界：
+
+- 需要 Chrome 或 Chromium；首版不支持 Edge
+- Git 和 `rg` 是可选项，不是运行前提
+- WSL 不在首版支持范围内；请直接在原生 PowerShell / CMD / Windows Terminal 中运行
+
 ### 快速开始
 
 需要 Node.js 20.17+ 和 Chrome/Chromium。
 
 ```bash
-npm install -g wtagent@alpha
+npm install -g wtagent@alpha --registry=https://registry.npmjs.org/
+wtagent login
+```
+
+Windows PowerShell：
+
+```powershell
+npm install -g wtagent@alpha --registry=https://registry.npmjs.org/
+wtagent doctor
 wtagent login
 ```
 
@@ -40,10 +61,16 @@ wtagent "检查这个项目并修复测试"
 wtagent -C ./my-project "创建一个网站"
 ```
 
-之后直接在终端中继续对话。WTAgent 会把任务交给 GPT Web，并在本地执行文件和 Shell 操作。使用 `↑` / `↓` 浏览本次 CLI 会话的历史输入。
+之后直接在终端中继续对话。WTAgent 会把任务交给 GPT Web，并在本地执行文件操作和结构化本地命令。使用 `↑` / `↓` 浏览本次 CLI 会话的历史输入。
 
 按 `Ctrl+C` 或 `Ctrl+D` 可退出并关闭专用 Chrome。若上一次异常退出留下了 Chrome，WTAgent 会在验证其 CDP 身份后复用并接管它。
 
+常见说明：
+
+- `wtagent doctor` 会检查 Node、Chrome、目录权限和运行环境
+- 首次登录只会写入 WTAgent 的专用 Chrome Profile，不会接管你的日常浏览器 Profile
+- 如果系统没有 Git 或 `rg`，WTAgent 仍应保留核心文件读写与搜索能力
+
 ## English
 
 WTAgent connects GPT Web chat to local tools, providing a Codex-like CLI agent experience. The first adapter currently supports ChatGPT Web.
@@ -51,16 +78,37 @@ WTAgent connects GPT Web chat to local tools, providing a Codex-like CLI agent e
 GPT Web handles reasoning. WTAgent runs locally to:
 
 - Read and edit local files
-- Run shell commands, builds, tests, and development servers
+- Run structured local commands, builds, tests, and development servers
 
 No OpenAI API key or ChatGPT Pro subscription is required. WTAgent stores your web login in a dedicated Chrome profile and uses the models and quota actually available to that account. Pro is an optional bonus when the account has it.
 
+Support matrix:
+
+- macOS
+- Linux
+- Windows 10 1809+ / Windows 11 x64
+- Windows ARM64 is currently preview only
+
+Boundaries:
+
+- Requires Chrome or Chromium; Edge is out of scope for the first Windows release
+- Git and `rg` are optional accelerators, not runtime requirements
+- WSL is not supported in v1; run WTAgent from native PowerShell, CMD, or Windows Terminal
+
 ### Quick start
 
 Requires Node.js 20.17+ and Chrome/Chromium.
 
 ```bash
-npm install -g wtagent@alpha
+npm install -g wtagent@alpha --registry=https://registry.npmjs.org/
+wtagent login
+```
+
+Windows PowerShell:
+
+```powershell
+npm install -g wtagent@alpha --registry=https://registry.npmjs.org/
+wtagent doctor
 wtagent login
 ```
 
@@ -78,10 +126,16 @@ wtagent "inspect this project and fix the tests"
 wtagent -C ./my-project "build a website"
 ```
 
-Continue chatting in the terminal. WTAgent sends tasks to GPT Web and executes file and shell operations locally. Use `↑` / `↓` to browse input history from the current CLI session.
+Continue chatting in the terminal. WTAgent sends tasks to GPT Web and executes file operations and structured local commands. Use `↑` / `↓` to browse input history from the current CLI session.
 
 Press `Ctrl+C` or `Ctrl+D` to exit and close the dedicated Chrome. If an abnormal exit leaves Chrome running, WTAgent verifies and adopts that CDP instance on the next start.
 
+Notes:
+
+- `wtagent doctor` checks Node, Chrome, writable data paths, and runtime support
+- WTAgent always uses its own Chrome profile and does not reuse your daily browsing profile
+- Core file and search capabilities must continue to work even when Git or `rg` is missing
+
 ## License
 
 [MIT](./LICENSE)

package/docs/technical-design.md

@@ -11,11 +11,20 @@
 - 双方通过普通聊天文本中的自定义 XML 交换工具调用和结果。
 - Runtime 循环执行“网页回复 → 解析工具 → 本地执行 → 回填结果”，直到任务完成。
 
+原生 Windows 支持约束：
+
+- 发布目标是 Windows 10 1809+ / Windows 11 x64；ARM64 先作为预览
+- 支持从 PowerShell、CMD 或 Windows Terminal 启动
+- 仅支持 Chrome / Chromium，不把 Edge 计入首版兼容矩阵
+- Git、`rg`、Codex、Claude Code 都不是运行依赖
+- WSL 不在首版范围内，需要从原生 Windows 终端直接运行
+- Windows 上仍保持同一个结构化执行协议：`program + argv + cwd`
+
 建议的首版技术组合：
 
 | 领域 | 选择 |
 | --- | --- |
-| 运行时 | Node.js 22+，JavaScript ESM |
+| 运行时 | Node.js 20.17+，JavaScript ESM |
 | CLI | `commander` + `@inquirer/prompts`，终端渲染可选 `ink` |
 | 浏览器控制 | `playwright-core`，使用用户已安装的 Chrome，非 headless |
 | XML | `saxes` 或 `fast-xml-parser`；工具参数按注册 Schema 二次校验 |
@@ -50,6 +59,12 @@
 - V1 支持 macOS、Windows、Linux。
 - V1 是 CLI，不做桌面 GUI 和远程控制台。
 
+其中 Windows 的产品边界需要额外强调：
+
+- `.cmd` / `.bat` 兼容属于运行时适配层职责，不能暴露为新的 shell-string 工具
+- `wtagent doctor` 需要明确区分“必需失败”“可选缺失”“能力降级”和“不支持的 WSL”
+- 打包发布必须经过原生 Windows 全局安装 smoke、路径带空格/中文、以及 Chrome 专用 Profile 验证
+
 ### 2.3 一个必须正视的技术事实
 
 普通 ChatGPT 网页聊天没有真正的 system message、tool schema 或 tool result channel。所谓“system prompt”“工具调用”“工具结果”都是由 CLI 作为普通用户文本发送。因此：
@@ -519,11 +534,18 @@ V1 不需要把 `cd` 暴露给模型；每个命令都有显式 `cwd`，且必
 
 - `cwd` 解析后必须位于项目根目录。
 - stdout/stderr 分开捕获并流式展示。
-- 达到上限后保留头尾并标记截断。
+- stdout 与 stderr 回填给网页模型的合计上限为 4 KiB；达到上限后按 UTF-8 字节安全地保留约 1 KiB 头部和 3 KiB 尾部，并标记原始与省略字节数。
+- 工具说明要求模型优先使用 `fs.search`、分页 `fs.read`、窄路径、子命令和测试过滤参数缩小输出；不假设系统已安装 Git、`rg` 或 Unix 文本工具。`terminal.exec` 不提供管道、重定向或其他 Shell 运算符。
+- 单次调用流式写入本地 `tool-output.jsonl` 的原始命令日志最多保留 4 MiB，超过后停止记录剩余日志，但不因此终止命令。
 - 超时先优雅终止，再强制终止进程树。
 - Windows 必须处理子进程树终止。
 - 返回 exit code、signal、duration 和截断信息。
 
+文件读取与网页传输另有两层硬限制：
+
+- `fs.read` 单次最多读取 16 KiB，通过返回的 `nextOffset` 继续读取；分段边界不得切断 UTF-8 字符。
+- 最终发送到浏览器的单条工具结果，包括 XML、续跑信息和 `<system_reminder>`，不得超过 24 KiB。Runtime 在字段级截断后生成完整 XML，Browser Adapter 在写入 composer 前再次按 UTF-8 字节数校验；禁止直接截断已经序列化的 XML。
+
 ### 7.4 长运行进程
 
 网站场景离不开 dev server，不能让 `terminal.exec` 永久阻塞。
@@ -593,7 +615,7 @@ sessions/<session-id>/
   tool-output.jsonl
 ```
 
-`session.json` 保存项目根目录、ChatGPT 会话 URL、当前 run phase、最近 turn、等待回填的工具结果和副作用恢复日志。它没有不可继续的 `completed task` 状态；`done=true` 只结束当前 run，Session 回到 `idle`。
+`session.json` 保存项目根目录、ChatGPT 会话 URL、最近确认的 assistant message ID、最近确认的实际模式、当前 run phase、最近 turn、等待回填的工具结果和副作用恢复日志。它没有不可继续的 `completed task` 状态；`done=true` 只结束当前 run，Session 回到 `idle`。
 
 `rollout-*.jsonl` 从创建时起直接使用 **Codex rollout 风格**：首行 `session_meta`，后续每行 `{timestamp, type: "response_item", payload}`，payload 采用 OpenAI Responses 形状（`message` / `function_call` / `function_call_output`）。
 
@@ -628,6 +650,8 @@ sessionId + assistantMessageIdentity + normalizedToolCall
 
 - Chrome 仍在：根据专用 Profile、PID、CDP 端口和健康检查验证身份，复用浏览器并创建新的 Page。
 - Chrome 崩溃：用相同 Profile 重启并打开会话 URL。
+- 同一 CLI 进程中的 follow-up 保持在当前会话 Page，不重复导航；跨进程恢复需要等待本地记录的最近 assistant message ID 出现在 DOM 后才能发送。
+- 每次发送记录已有消息 ID 和新 user turn，只接受位于该 user turn 之后的新 assistant turn；无法建立可靠消息身份时超时并保存诊断，禁止退化为基于数量或文本变化猜测。
 - 同一 Profile 同时只允许一个 WTAgent CLI Session；启动和接管过程使用 Profile 级互斥锁。
 - 登录失效或出现验证：进入 `AUTH_REQUIRED`/`PAUSED`，让用户接管。
 - 会话页面丢失：从本地记录打开原会话；无法恢复时创建新的本地 Session 和新的网页对话，不向旧 rollout 继续追加。
@@ -640,6 +664,8 @@ sessionId + assistantMessageIdentity + normalizedToolCall
 2. 当前可用工具及参数 Schema。
 3. 用户任务、项目根目录语义和执行边界。
 
+同一网页会话中的普通 follow-up 只发送新的用户输入，并在末尾追加短 `<system_reminder>`；不得重复发送完整 `<agent_protocol>`、工具目录或初始任务。只有没有新用户输入的中断恢复流程可以发送完整 resume scaffold。
+
 关键规则：
 
 - 一轮最多一个工具调用。
@@ -816,7 +842,7 @@ macOS、Windows、Linux 都运行：
 | ChatGPT DOM 变化 | Provider Adapter 隔离、集中 Locator、Fixture 和诊断截图 |
 | 网页模型不遵守 XML | 简单协议、单工具/轮、确定性解析、有限重发 |
 | 重复执行工具 | assistant 指纹、call ledger、两阶段事件记录 |
-| 大输出塞满聊天 | 本地保存、截断回填、按需读取 |
+| 大输出塞满聊天 | 文件按 16 KiB 分段读取；命令结果回填 4 KiB；浏览器工具消息硬限制 24 KiB；本地命令日志限制 4 MiB |
 | dev server 阻塞 | 独立 Process Manager |
 | 跨平台 Shell 差异 | `program + argv + cwd`，复杂 Shell 单独审批 |
 | 路径逃逸 | realpath、符号链接检查、项目根策略 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtagent",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "Turn your own web AI session into a local tool-using agent.",
   "repository": {
     "type": "git",
@@ -25,12 +25,14 @@
   "files": [
     "src",
     "README.md",
-    "docs/technical-design.md"
+    "docs/technical-design.md",
+    "LICENSE"
   ],
   "scripts": {
     "test": "node --test",
     "test:unit": "node --test test/protocol.test.js test/policy.test.js test/tools.test.js test/prompt-builder.test.js test/session-export.test.js test/platform.test.js test/cli.test.js test/at-files.test.js",
     "test:integration": "node --test test/runtime.test.js",
+    "test:windows": "node --test test/windows-command-launcher.test.js test/windows-diagnostics.test.js test/windows-search-path.test.js test/atomic-write.test.js test/process-utils.test.js test/cdp-state.test.js test/windows-fixtures.test.js test/windows-package-smoke.test.js",
     "check": "node scripts/check-syntax.js",
     "doctor": "node src/cli/main.js doctor",
     "login": "node src/cli/main.js login",

package/src/browser/cdp-browser.js

@@ -7,6 +7,7 @@ import {
   discoverReusableCdpState,
   fetchCdpVersion,
   processMatchesCdpState,
+  reapStaleProfileChrome,
   removeCdpState,
   saveCdpState,
   waitForProcessExit,
@@ -45,6 +46,33 @@ async function settleWithin(promise, timeoutMs) {
   }
 }
 
+// Races a promise against a timeout. On timeout the returned promise rejects
+// with a TIMEOUT-tagged error. Used to bound connectOverCDP + the first CDP
+// round-trip: a Chrome whose profile is locked by a stale instance answers the
+// WS handshake but never finishes protocol init, so an unbounded connect hangs
+// for the full Playwright default (30s) before failing.
+class CdpTimeoutError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CdpTimeoutError";
+    this.code = "CDP_CONNECT_TIMEOUT";
+  }
+}
+
+async function withTimeout(promise, timeoutMs, message) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new CdpTimeoutError(message)), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function waitForCdp({
   endpoint,
   child,
@@ -116,12 +144,14 @@ export async function launchAndConnectCdpChrome({
   fetchVersion = fetchCdpVersion,
   killTree = killProcessTree,
   matchesState = processMatchesCdpState,
+  reapStale = reapStaleProfileChrome,
   removeState = removeCdpState,
   reserveCdpPort = reservePort,
   saveState = saveCdpState,
   spawnChrome = spawn,
   waitForExit = waitForProcessExit,
   waitForReady = waitForCdp,
+  connectTimeoutMs = 20_000,
 } = {}) {
   const releaseProfileLock = await acquireProfileLock(profileDir);
   let child = null;
@@ -140,6 +170,11 @@ export async function launchAndConnectCdpChrome({
       reused = true;
     } else {
       await removeState(profileDir);
+      // A prior instance may have died leaving renderer children (and Chrome's
+      // SingletonLock) still holding this profile. Reap those stale holders
+      // before launching, or the new Chrome hangs during profile init and
+      // connectOverCDP times out.
+      await reapStale(profileDir, { fetchVersion, killTree }).catch(() => null);
       const port = await reserveCdpPort();
       const endpoint = `http://127.0.0.1:${port}`;
       child = spawnChrome(
@@ -192,8 +227,41 @@ export async function launchAndConnectCdpChrome({
       }
     }
 
-    browser = await connectOverCDP(state.endpoint);
-    const context = browser.contexts()[0];
+    // Bound the connect + first CDP round-trip. If Chrome's profile is held by
+    // a stale instance, the WS connects but protocol init never completes;
+    // without this guard Playwright hangs ~30s and leaves a dirty CDP state.
+    let context;
+    try {
+      browser = await withTimeout(
+        connectOverCDP(state.endpoint),
+        connectTimeoutMs,
+        `Timed out connecting to Chrome CDP at ${state.endpoint} after ${connectTimeoutMs}ms.`,
+      );
+      // contexts() forces a real protocol round-trip, so it hangs too when the
+      // browser main thread is stuck — keep it inside the timeout budget.
+      const contexts = await withTimeout(
+        Promise.resolve().then(() => browser.contexts()),
+        connectTimeoutMs,
+        `Timed out reading Chrome browser context at ${state.endpoint}.`,
+      );
+      context = contexts[0];
+    } catch (error) {
+      if (error instanceof CdpTimeoutError) {
+        // The verified-but-unusable instance we launched is a dead end. Kill it
+        // (only if we own it) and drop its CDP state so the next run starts
+        // clean instead of trying to reuse a hung endpoint.
+        await browser?.close().catch(() => null);
+        if (!reused && child?.pid) {
+          await killTree(child.pid).catch(() => null);
+        }
+        await removeState(profileDir, state).catch(() => null);
+        throw new Error(
+          `${error.message} The Chrome profile may be held by another instance. `
+          + "Close other windows using this profile, or run `wtagent logout` to reset it, then retry.",
+        );
+      }
+      throw error;
+    }
     if (!context) {
       throw new Error("Chrome CDP connection did not expose a browser context.");
     }

package/src/browser/cdp-state.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { promisify } from "node:util";
+import { replaceFileAtomic } from "../shared/atomic-write.js";
 
 const execFileAsync = promisify(execFile);
 const CDP_STATE_FILE = ".wtagent-cdp.json";
@@ -37,7 +38,7 @@ async function writeJsonAtomic(filePath, value) {
       `${JSON.stringify(value, null, 2)}\n`,
       { mode: 0o600 },
     );
-    await fs.rename(temporary, filePath);
+    await replaceFileAtomic(temporary, filePath);
   } finally {
     await fs.rm(temporary, { force: true }).catch(() => {});
   }
@@ -114,7 +115,7 @@ function normalizeCandidate(candidate, profileDir) {
   }
   if (
     candidate.profileDir
-    && path.resolve(candidate.profileDir) !== profileDir
+    && !profileDirsMatch(candidate.profileDir, profileDir)
   ) {
     return null;
   }
@@ -128,6 +129,21 @@ function normalizeCandidate(candidate, profileDir) {
   };
 }
 
+function normalizeProfilePath(value, platform = process.platform) {
+  const input = String(value ?? "");
+  const resolved = platform === "win32"
+    ? path.win32.resolve(input)
+    : path.resolve(input);
+  if (platform !== "win32") {
+    return resolved;
+  }
+  return path.win32.normalize(resolved).replaceAll("/", "\\").toLowerCase();
+}
+
+function profileDirsMatch(left, right, platform = process.platform) {
+  return normalizeProfilePath(left, platform) === normalizeProfilePath(right, platform);
+}
+
 async function probeCandidate(candidate, profileDir, {
   isAlive = isProcessAlive,
   fetchVersion = fetchCdpVersion,
@@ -202,7 +218,7 @@ async function readProcessTable() {
         "-Command",
         "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress",
       ],
-      { maxBuffer: 10 * 1024 * 1024 },
+      { maxBuffer: 10 * 1024 * 1024, windowsHide: true },
     );
     const parsed = JSON.parse(stdout || "[]");
     return (Array.isArray(parsed) ? parsed : [parsed]).map((entry) => ({
@@ -219,24 +235,25 @@ async function readProcessTable() {
   return stdout.split("\n").flatMap((line) => {
     const match = line.match(/^\s*(\d+)\s+(.+)$/);
     return match
-      ? [{ pid: Number(match[1]), command: match[2] }]
+      ? [{ pid: Number(match[1]), command: match[2].trim() }]
       : [];
   });
 }
 
-function commandUsesProfile(command, profileDir) {
-  return (
-    command.includes(`--user-data-dir=${profileDir}`)
-    || command.includes(`--user-data-dir="${profileDir}"`)
-    || command.includes(`--user-data-dir='${profileDir}'`)
-  );
+function commandUsesProfile(command, profileDir, platform = process.platform) {
+  const inline = command.match(/--user-data-dir=(?:"([^"]+)"|'([^']+)'|(\S+))/i);
+  const separated = command.match(/--user-data-dir\s+(?:"([^"]+)"|'([^']+)'|(\S+))/i);
+  const raw = inline?.[1] ?? inline?.[2] ?? inline?.[3]
+    ?? separated?.[1] ?? separated?.[2] ?? separated?.[3]
+    ?? null;
+  return raw ? profileDirsMatch(raw, profileDir, platform) : false;
 }
 
-function candidateFromProcess(entry, profileDir) {
+function candidateFromProcess(entry, profileDir, platform = process.platform) {
   if (
     !entry.command
     || entry.command.includes("--type=")
-    || !commandUsesProfile(entry.command, profileDir)
+    || !commandUsesProfile(entry.command, profileDir, platform)
   ) {
     return null;
   }
@@ -246,6 +263,16 @@ function candidateFromProcess(entry, profileDir) {
     : null;
 }
 
+function profileHolderFromProcess(entry, profileDir, platform = process.platform) {
+  if (!entry.command || !commandUsesProfile(entry.command, profileDir, platform)) {
+    return null;
+  }
+  const pid = Number(entry.pid);
+  return Number.isSafeInteger(pid) && pid > 0
+    ? { pid, command: entry.command }
+    : null;
+}
+
 async function singletonOwnerPid(profileDir) {
   if (process.platform === "win32") {
     return null;
@@ -259,13 +286,17 @@ async function singletonOwnerPid(profileDir) {
   }
 }
 
-export async function processMatchesCdpState(state) {
-  const profileDir = path.resolve(state.profileDir);
+export async function processMatchesCdpState(state, {
+  listProcesses = readProcessTable,
+  platform = process.platform,
+} = {}) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const profileDir = pathApi.resolve(state.profileDir);
   const port = Number(state.port);
   try {
-    const processes = await readProcessTable();
+    const processes = await listProcesses();
     return processes.some((entry) => {
-      const candidate = candidateFromProcess(entry, profileDir);
+      const candidate = candidateFromProcess(entry, profileDir, platform);
       return (
         candidate?.pid === Number(state.pid)
         && candidate.port === port
@@ -276,30 +307,61 @@ export async function processMatchesCdpState(state) {
   }
 }
 
+function processTableContainsState(
+  processes,
+  state,
+  profileDir,
+  platform = process.platform,
+) {
+  const port = Number(state.port);
+  const pid = Number(state.pid);
+  return processes.some((entry) => {
+    const candidate = candidateFromProcess(entry, profileDir, platform);
+    return candidate?.pid === pid && candidate.port === port;
+  });
+}
+
 export async function discoverReusableCdpState(profileDir, {
   isAlive = isProcessAlive,
   fetchVersion = fetchCdpVersion,
   listProcesses = readProcessTable,
+  platform = process.platform,
 } = {}) {
   const resolvedProfile = path.resolve(profileDir);
+  const requireVerifiedProcessTable = platform === "win32";
   const saved = await readCdpState(resolvedProfile);
+  let processes;
+  try {
+    processes = await listProcesses();
+  } catch {
+    if (requireVerifiedProcessTable) {
+      return null;
+    }
+    processes = null;
+  }
+
   const savedHealthy = await probeCandidate(saved, resolvedProfile, {
     isAlive,
     fetchVersion,
   });
-  if (savedHealthy) {
+  if (
+    savedHealthy
+    && (!requireVerifiedProcessTable || processTableContainsState(
+      processes ?? [],
+      savedHealthy,
+      resolvedProfile,
+      platform,
+    ))
+  ) {
     return await saveCdpState(resolvedProfile, savedHealthy);
   }
 
-  let processes;
-  try {
-    processes = await listProcesses();
-  } catch {
+  if (!processes) {
     return null;
   }
 
   const rawCandidates = processes
-    .map((entry) => candidateFromProcess(entry, resolvedProfile))
+    .map((entry) => candidateFromProcess(entry, resolvedProfile, platform))
     .filter(Boolean);
   const uniqueCandidates = [...new Map(
     rawCandidates.map((candidate) => [
@@ -335,6 +397,150 @@ export async function discoverReusableCdpState(profileDir, {
   );
 }
 
+// Kills Chrome processes bound to this profile whose CDP endpoint is dead, and
+// clears Chrome's singleton guard files. A half-dead prior instance (main
+// process gone or unresponsive, but renderer children still holding the
+// profile) makes a freshly launched Chrome hang during profile initialization:
+// the new CDP port answers HTTP/WS, but the browser main thread never becomes
+// usable, so connectOverCDP times out. Reaping those stale holders first
+// prevents the hang. Only ever touches processes that use THIS profile dir, and
+// never a live/healthy CDP instance. Best-effort.
+export async function reapStaleProfileChrome(profileDir, {
+  isAlive = isProcessAlive,
+  fetchVersion = fetchCdpVersion,
+  listProcesses = readProcessTable,
+  killTree = null,
+  platform = process.platform,
+} = {}) {
+  const resolvedProfile = path.resolve(profileDir);
+  let processes;
+  try {
+    processes = await listProcesses();
+  } catch {
+    return { killed: [] };
+  }
+
+  const holders = processes
+    .map((entry) => profileHolderFromProcess(entry, resolvedProfile, platform))
+    .filter(Boolean);
+  const candidates = processes
+    .map((entry) => candidateFromProcess(entry, resolvedProfile, platform))
+    .filter(Boolean);
+
+  // A healthy main browser owns every helper/renderer using this profile.
+  // Never reap individual children from a verified live instance.
+  let hasHealthyCdpOwner = false;
+  for (const candidate of candidates) {
+    try {
+      await fetchVersion(`http://127.0.0.1:${candidate.port}`);
+      hasHealthyCdpOwner = true;
+      break;
+    } catch {
+      // Continue until one verified owner is found.
+    }
+  }
+  if (hasHealthyCdpOwner) {
+    return { killed: [] };
+  }
+
+  const killed = [];
+  for (const holder of holders) {
+    if (isAlive(holder.pid) && typeof killTree === "function") {
+      await killTree(holder.pid).catch(() => {});
+    }
+    killed.push(holder.pid);
+  }
+
+  // Chrome's singleton profile guard is a symlink; a crashed instance can leave
+  // it dangling and block the next launch. Clear it when we reaped holders or
+  // when it points at a dead pid.
+  const ownerPid = await singletonOwnerPid(resolvedProfile);
+  if (killed.length > 0 || (ownerPid && !isAlive(ownerPid))) {
+    for (const name of ["SingletonLock", "SingletonCookie", "SingletonSocket"]) {
+      await fs.rm(path.join(resolvedProfile, name), { force: true })
+        .catch(() => {});
+    }
+  }
+
+  return { killed };
+}
+
+export async function inspectCdpProfileState(profileDir, {
+  isAlive = isProcessAlive,
+  fetchVersion = fetchCdpVersion,
+  listProcesses = readProcessTable,
+  platform = process.platform,
+} = {}) {
+  const resolvedProfile = path.resolve(profileDir);
+  const diagnostics = [];
+
+  const lock = await readJson(lockPath(resolvedProfile));
+  if (lock?.pid) {
+    const alive = isAlive(Number(lock.pid));
+    diagnostics.push(
+      alive
+        ? `profile lock held by live pid=${lock.pid}`
+        : `stale profile lock references dead pid=${lock.pid}`,
+    );
+  } else {
+    diagnostics.push("no WTAgent profile lock");
+  }
+
+  const saved = await readJson(statePath(resolvedProfile));
+  if (!saved) {
+    diagnostics.push("no saved CDP state");
+    return {
+      status: "pass",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  const savedHealthy = await probeCandidate(saved, resolvedProfile, {
+    isAlive,
+    fetchVersion,
+  });
+  if (!savedHealthy) {
+    diagnostics.push(`saved CDP state for pid=${saved.pid} is stale or unhealthy`);
+    return {
+      status: "degraded",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  if (platform !== "win32") {
+    diagnostics.push(`saved CDP state is healthy for pid=${savedHealthy.pid}`);
+    return {
+      status: "pass",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  let processes;
+  try {
+    processes = await listProcesses();
+  } catch (error) {
+    diagnostics.push(`cannot verify saved CDP state against PowerShell CIM: ${error.message}`);
+    return {
+      status: "degraded",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  if (!processTableContainsState(processes, savedHealthy, resolvedProfile, platform)) {
+    diagnostics.push(`saved CDP state for pid=${savedHealthy.pid} could not be verified against the current process table`);
+    return {
+      status: "degraded",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  diagnostics.push(`saved CDP state is verified for pid=${savedHealthy.pid}`);
+  return {
+    status: "pass",
+    detail: diagnostics.join("; "),
+  };
+}
+
 export async function acquireCdpProfileLock(profileDir, {
   ownerPid = process.pid,
   isAlive = isProcessAlive,