@53able/pi-agent-browser 0.4.1 → 0.5.0

package/README.ja-JP.md

@@ -164,12 +164,12 @@ https://example.com をブラウザ経由で読み、outputs/browser/example.md
 すべての操作を無人で任せるべきではありません。適切なタイミングで人間に操作を戻すためのツールが3つあります。
 
 - **安全な境界線** — `agent_browser_handoff` は、AI自身では対応できない・すべきでない操作（2FA/OTPの入力、CAPTCHA、本人確認）の直前でエージェントを一時停止させます。スクリーンショットで状況を記録したあと、実際のUIダイアログでブロックし、人間が「対応完了」または「中止」を選ぶまで待ちます。`agent_browser_read` / `agent_browser_snapshot` も簡易なキーワード検知を行い、こうしたチェックポイントらしき内容を出力に警告として付加します（この警告自体は停止ではなく、`agent_browser_handoff` を呼ぶきっかけとして扱ってください）。
-- **インタラクティブなログイン** — `agent_browser_login_handoff` は、Google や OAuth など多くのプロバイダで sign-in がブロックされる問題を解決します。これは、agent-browser が使われた時点でオートメーション検出が起きるため、ログイン中に拒否されるというもの。このツールは CDP が接続されていない無人 Chrome プロセスを起動して人間が正常にログインできるようにし、ログイン成功後にその認証済みCookie/storageを取り出して、新しい通常のagent-browserセッションに読み込ませます。Google や OAuth の sign-in フローが期待されるタスクでは、`agent_browser_open` ではなく必ずこちらを使ってください。
+- **インタラクティブなログイン** — `agent_browser_login_handoff` は、Google や OAuth など多くのプロバイダで sign-in がブロックされる問題を解決します。これは、agent-browser が使われた時点でオートメーション検出が起きるため、ログイン中に拒否されるというもの。このツールは CDP が接続されていない無人 Chrome プロセスを起動して人間が正常にログインできるようにし、ログイン成功後に、**そのブラウザはセッションに結合され、閉じられるまで生存し続けます**—リモートデバッグポートが開いたまま表示されます。Google や OAuth の sign-in フローが期待されるタスクでは、`agent_browser_open` ではなく必ずこちらを使ってください。
 - **Commit前の停止** — `agent_browser_commit` は、決済・削除・投稿・送信といった「やり直しのきかない操作」専用の確認ゲートです。証跡を保存し、クリックの前に必ず人間の明示的な確認を求め、承認されない限りクリックは実行されません。対話的なUIが利用できない場合は、クリックせずにそのまま拒否します。こうした操作の最終確認クリックには `agent_browser_click` ではなく必ずこちらを使ってください。
 
 3つのツールすべてが対話的なセッション（TUI、またはUI対応のRPC）を必要とします。無人・headless実行では、黙って進めるのではなく拒否します。
 
-`agent_browser_open`は、各セッションが`headed: true`で起動されたかどうかを記録します。`agent_browser_handoff`が、headedで開かれていないセッションに対して呼ばれた場合、人間への警告に加えて、可視ウィンドウを開き直すための`agent_browser_open`の引数（セッション名、`headed: true`、`restore: true`、最後に開いていたURL）をそのまま提示します — どのコマンドを打ち直せばよいか推測する必要はありません。ログインや2FA、CAPTCHA、本人確認に差し掛かる可能性があるタスクでは、最初から`headed: true`で開くことを推奨します。一部の確認チャレンジは使い切り・期限付きのため、途中で開き直すとログインからやり直しになることがあります。`agent_browser_login_handoff`が作るセッションは常にheadlessです（使い捨てのログイン用ブラウザではなく、新規セッションのため）。見たい場合は`headed: true`で開き直してください。
+`agent_browser_open`は、各セッションが`headed: true`で起動されたかどうかを記録します。`agent_browser_handoff`が、headedで開かれていないセッションに対して呼ばれた場合、人間への警告に加えて、可視ウィンドウを開き直すための`agent_browser_open`の引数（セッション名、`headed: true`、`restore: true`、最後に開いていたURL）をそのまま提示します — どのコマンドを打ち直せばよいか推測する必要はありません。ログインや2FA、CAPTCHA、本人確認に差し掛かる可能性があるタスクでは、最初から`headed: true`で開くことを推奨します。一部の確認チャレンジは使い切り・期限付きのため、途中で開き直すとログインからやり直しになることがあります。`agent_browser_login_handoff`が作るセッションは`headed: true`として記録されます（ログインブラウザが表示・生存し続けるため、開き直す必要はありません）。
 
 ## Troubleshooting
 
@@ -177,7 +177,9 @@ https://example.com をブラウザ経由で読み、outputs/browser/example.md
 agent-browser doctor
 ```
 
-または Pi に `agent_browser_doctor` を実行させてください。
+または Pi に `agent_browser_doctor` を実行させてください。インストール、Chrome、daemon、security、provider、network、launch test を確認します。`agent_browser_login_handoff` で作ったセッションでまだ開いているログインブラウザも報告し、期限切れ追跡データを自動削除します。
+
+`agent_browser_login_handoff` で作ったセッションの中で、まだ生存しているログインブラウザがあれば、`agent_browser_doctor` がそれらを報告します（セッション名、プロセス ID、デバッグポート、最後に開いていた URL を表示）。終わったら各セッションに対して `agent_browser_close` を呼んでください — これらのセッションはブラウザを閉じるまでリモートデバッグポートが開いたままです。期限切れエントリ（実行中でなくなったプロセスの追跡データ）は、何も通知することなく自動削除されます。
 
 よくある修正:
 

package/README.md

@@ -164,12 +164,12 @@ Clear all saved states only when intentionally resetting everything:
 Not every step should run unattended. Three tools hand control back to a human at the right moments:
 
 - **Safe boundaries** — `agent_browser_handoff` pauses the agent for steps it cannot or should not perform itself: 2FA/OTP entry, CAPTCHA, identity verification. It captures a screenshot for context, then blocks on a real confirmation dialog until a human resumes or aborts. `agent_browser_read` and `agent_browser_snapshot` also run a lightweight keyword scan and flag likely checkpoints in their output as a nudge to call this tool.
-- **Interactive login flows** — `agent_browser_login_handoff` solves the problem that Google, OAuth, and similar providers block sign-in when agent-browser is used, because automation detection happens during the login step itself. This tool spawns an unattended Chrome process (with no CDP attached) so the human can log in normally, then captures the authenticated cookies/storage and loads them into a fresh, ordinary agent-browser session after login succeeds. Use this instead of `agent_browser_open` whenever a task is expected to hit an interactive Google or OAuth sign-in flow.
+- **Interactive login flows** — `agent_browser_login_handoff` solves the problem that Google, OAuth, and similar providers block sign-in when agent-browser is used, because automation detection happens during the login step itself. This tool spawns an unattended Chrome process (with no CDP attached) so the human can log in normally. After login succeeds, the still-running browser is live-attached to the named session and **kept open as the permanent backing browser**—it remains visible on screen with an open remote-debugging port until closed with `agent_browser_close`. Use this instead of `agent_browser_open` whenever a task is expected to hit an interactive Google or OAuth sign-in flow.
 - **Stop before commit** — `agent_browser_commit` is a dedicated gate for irreversible actions: payment, deletion, publishing, sending. It captures evidence, requires explicit human confirmation before clicking, and refuses outright (without clicking) if no interactive UI is available to ask. Use it instead of `agent_browser_click` for the final confirming step of any such action.
 
 All three tools require an interactive session (TUI or RPC with UI support); in headless/unattended runs they refuse rather than proceed silently.
 
-`agent_browser_open` remembers whether each named session was launched with `headed: true`. If `agent_browser_handoff` is called for a session that was not opened headed, it automatically warns the human and includes the exact `agent_browser_open` arguments (session name, `headed: true`, `restore: true`, and the last known URL) needed to reopen a visible window — no more guessing which command to rerun. Prefer `headed: true` up front for any task that might hit a login, 2FA, CAPTCHA, or identity-verification step, since some challenges are single-use and reopening mid-flow may require restarting the login. `agent_browser_login_handoff` always leaves the resulting session headless (it's a fresh session, not the disposable login browser), so reopen with `headed: true` if you need to see it.
+`agent_browser_open` remembers whether each named session was launched with `headed: true`. If `agent_browser_handoff` is called for a session that was not opened headed, it automatically warns the human and includes the exact `agent_browser_open` arguments (session name, `headed: true`, `restore: true`, and the last known URL) needed to reopen a visible window — no more guessing which command to rerun. Prefer `headed: true` up front for any task that might hit a login, 2FA, CAPTCHA, or identity-verification step, since some challenges are single-use and reopening mid-flow may require restarting the login. `agent_browser_login_handoff` records the resulting session as `headed: true` (since the login browser is visible and running); you don't need to reopen it to see it.
 
 ## Troubleshooting
 
@@ -179,7 +179,9 @@ Run:
 agent-browser doctor
 ```
 
-Or ask Pi to run `agent_browser_doctor`.
+Or ask Pi to run `agent_browser_doctor`. This verifies installation, Chrome, daemon, security, providers, network, and launch tests. It also reports any live login-handoff browsers left open and cleans up stale tracking entries.
+
+If you have sessions created with `agent_browser_login_handoff`, `agent_browser_doctor` will report any that still have live login browsers running, showing the session name, process ID, debugging port, and last known URL. Call `agent_browser_close` for each session when done — these hold an open remote-debugging port until closed. Stale entries (tracking data for processes no longer running) are cleaned up automatically with no notification.
 
 Common fixes:
 

package/index.ts

@@ -43,7 +43,9 @@ const SESSION_STATE_DIR = ".pi-agent-browser";
 const SESSION_STATE_FILE = "sessions.json";
 const DEFAULT_SESSION_KEY = "__default__";
 
-type SessionState = { headed: boolean; lastUrl?: string; updatedAt: string };
+type SessionState = { headed: boolean; lastUrl?: string; loginBrowserPid?: number; loginDebugPort?: number; updatedAt: string };
+
+type SessionStatePatch = Partial<Omit<SessionState, "updatedAt">> & { clearLoginBrowserPid?: boolean };
 
 function sessionKey(params: JsonObject): string {
   return typeof params.session === "string" && params.session.trim() ? params.session.trim() : DEFAULT_SESSION_KEY;
@@ -58,7 +60,7 @@ async function readSessionStates(cwd: string): Promise<Record<string, SessionSta
   }
 }
 
-async function writeSessionState(cwd: string, session: string, patch: Partial<Omit<SessionState, "updatedAt">>): Promise<void> {
+async function writeSessionState(cwd: string, session: string, patch: SessionStatePatch): Promise<void> {
   const dir = join(cwd, SESSION_STATE_DIR);
   await mkdir(dir, { recursive: true });
   const states = await readSessionStates(cwd);
@@ -66,6 +68,8 @@ async function writeSessionState(cwd: string, session: string, patch: Partial<Om
   states[session] = {
     headed: patch.headed ?? previous?.headed ?? false,
     lastUrl: patch.lastUrl ?? previous?.lastUrl,
+    loginBrowserPid: patch.clearLoginBrowserPid ? undefined : (patch.loginBrowserPid ?? previous?.loginBrowserPid),
+    loginDebugPort: patch.clearLoginBrowserPid ? undefined : (patch.loginDebugPort ?? previous?.loginDebugPort),
     updatedAt: new Date().toISOString(),
   };
   await writeFile(join(dir, SESSION_STATE_FILE), JSON.stringify(states, null, 2), "utf8");
@@ -266,6 +270,20 @@ async function findFreePort(): Promise<number> {
   });
 }
 
+function killPidBestEffort(pid?: number): void {
+  if (!pid) return;
+  try { process.kill(pid); } catch { /* already gone / not ours */ }
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0); // signal 0 = no-op existence/permission check, does not actually kill
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code !== "ESRCH"; // ESRCH = no such process (dead); any other error (e.g. EPERM) means it exists
+  }
+}
+
 function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise((resolveDelay) => {
     if (signal?.aborted) {
@@ -673,12 +691,28 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
     parameters: CloseSchema,
     async execute(_id, rawParams, signal, onUpdate, ctx) {
       const params = rawParams as JsonObject;
+      const states = await readSessionStates(ctx.cwd);
       const args: string[] = [];
       pushCommonArgs(args, params);
       args.push("close");
       if (params.all === true) args.push("--all");
       pushExtraArgs(args, params);
       const result = await runAgentBrowser(args, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
+
+      // agent-browser close only detaches an externally-spawned login Chrome; kill the tracked pid(s) ourselves.
+      if (params.all === true) {
+        for (const [name, st] of Object.entries(states)) {
+          if (!st.loginBrowserPid) continue;
+          killPidBestEffort(st.loginBrowserPid);
+          await writeSessionState(ctx.cwd, name, { clearLoginBrowserPid: true });
+        }
+      } else {
+        const session = sessionKey(params);
+        if (states[session]?.loginBrowserPid) {
+          killPidBestEffort(states[session]?.loginBrowserPid);
+          await writeSessionState(ctx.cwd, session, { clearLoginBrowserPid: true });
+        }
+      }
       return buildTextResult(result);
     },
   });
@@ -764,12 +798,13 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
   pi.registerTool({
     name: "agent_browser_login_handoff",
     label: "Agent Browser Login Handoff",
-    description: "Launch a real, non-CDP-attached Chrome for an interactive login (e.g. Google sign-in) that automation frameworks get blocked from. Once the human confirms login is complete, captures the authenticated cookies/storage and loads them into a fresh, ordinary agent-browser session. Blocks until the human confirms or aborts.",
+    description: "Launch a real, non-CDP-attached Chrome for an interactive login (e.g. Google sign-in) that automation frameworks get blocked from. Once the human confirms login is complete, live-attaches that still-running browser to the named agent-browser session and keeps it open as the session's backing browser (no cookie/state export). Blocks until the human confirms or aborts.",
     promptSnippet: "Use agent_browser_login_handoff (not agent_browser_open) whenever a task requires an interactive Google/OAuth-style login.",
     promptGuidelines: [
       "Never attempt an interactive Google/OAuth-style login via agent_browser_open, agent_browser_click, or agent_browser_fill — those attach CDP immediately, and Google blocks sign-in for CDP-attached sessions regardless of profile or cookies.",
       "Call this tool instead whenever a task is expected to require signing into a Google account or a similarly automation-hostile login flow.",
       "After this tool reports success, take a fresh agent_browser_snapshot before continuing — do not assume page state.",
+      "On success the login browser stays open and IS the session's live backing browser; drive it with the normal agent_browser_* tools by session name, and call agent_browser_close when done to shut it down (it holds an open remote-debugging port until then).",
       "If this tool reports no interactive UI, a decline, or a failure, stop the task and report back; do not retry via agent_browser_open.",
     ],
     parameters: LoginHandoffSchema,
@@ -805,6 +840,10 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
 
       const port = await findFreePort();
 
+      // Supersede an older live login browser for this session so re-running doesn't leak it.
+      const prior = (await readSessionStates(ctx.cwd))[session];
+      killPidBestEffort(prior?.loginBrowserPid);
+
       let spawnError: Error | undefined;
       const child = spawn(executablePath, [
         `--remote-debugging-port=${port}`,
@@ -889,42 +928,27 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
         };
       }
 
-      // Do NOT keep driving the live --cdp connection as the ongoing session: `agent-browser
-      // --cdp <port> ... open` (no url) opens a brand-new blank page/context in the connected
-      // browser rather than reusing the tab the human actually authenticated in, leaving the
-      // "attached" session on about:blank with no auth. Instead follow agent-browser's own
-      // documented pattern for this exact scenario (see its authentication.md "Import Auth
-      // from Your Browser" / "Two-Factor Authentication" sections): extract the authenticated
-      // cookies/storage from the login browser via `state save`, close the disposable login
-      // browser, then load that state into a normal, freshly-launched session via `--state`.
-      const authStatePath = join(profileDir, "auth-state.json");
-      const saveArgs = ["--cdp", String(port), "state", "save", authStatePath];
-      const saveResult = await runAgentBrowser(saveArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
-      try { child.kill(); } catch { /* best-effort; the login browser is disposable once we've extracted its auth state */ }
-
-      if (!saveResult.ok) {
-        return {
-          content: [{
-            type: "text",
-            text: [
-              "Login browser was confirmed by the human, but extracting its authenticated state via `state save` failed. Do not assume the session is usable.",
-              `Command: ${saveResult.command} ${saveResult.args.map((a) => JSON.stringify(a)).join(" ")}`,
-            ].join("\n"),
-          }],
-          details: { ...saveResult, artifactPaths: [] },
-          terminate: true,
-        };
-      }
+      // Human confirmed login. Bind the STILL-RUNNING login Chrome into the named session
+      // via CDP, WITHOUT navigating (snapshot binds + verifies in one shot; open would
+      // re-navigate away from the authenticated landing page). Keep the browser ALIVE —
+      // it is now the backing browser this session drives from here on.
+
+      // Defensive: surface multi-tab situations (OAuth popups) without failing.
+      const tabArgs = ["--cdp", String(port), "tab", "list"];
+      const tabResult = await runAgentBrowser(tabArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
 
-      const loadArgs = ["--session", session, "--restore", "--state", authStatePath, "open", url];
-      const result = await runAgentBrowser(loadArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
+      const bindArgs = ["--session", session, "--cdp", String(port), "snapshot"];
+      const result = await runAgentBrowser(bindArgs, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
 
       if (!result.ok) {
+        // Bind failed: the login browser is still alive but unusable by the session.
+        // Best-effort kill so we don't leak a debug-port Chrome, and report.
+        killPidBestEffort(child.pid);
         return {
           content: [{
             type: "text",
             text: [
-              "Login state was captured from the human's browser, but loading it into a fresh agent-browser session failed. Do not assume the session is usable.",
+              "Human confirmed login, but attaching the live browser to the agent-browser session failed. Do not assume the session is usable.",
               `Command: ${result.command} ${result.args.map((a) => JSON.stringify(a)).join(" ")}`,
             ].join("\n"),
           }],
@@ -933,16 +957,25 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
         };
       }
 
-      await writeSessionState(ctx.cwd, session, { headed: false, lastUrl: url });
+      // Persist backing-browser identity + the fact that a VISIBLE window exists (headed:true).
+      await writeSessionState(ctx.cwd, session, {
+        headed: true,
+        lastUrl: url,
+        loginBrowserPid: child.pid,
+        loginDebugPort: port,
+      });
 
+      const multiTab = /\bt2\b/.test(tabResult.stdout) || (tabResult.stdout.match(/\[t\d+\]/g)?.length ?? 0) > 1;
       return {
         content: [{
           type: "text",
           text: [
-            "Login handoff complete: the human's authenticated cookies/storage were captured and loaded into a fresh agent-browser session.",
+            "Login handoff complete: the browser you signed in with is now live-attached to the agent-browser session and stays open.",
             `Session: ${session === DEFAULT_SESSION_KEY ? "(default)" : session}`,
-            "Take a fresh agent_browser_snapshot before continuing.",
-          ].join("\n"),
+            multiTab ? `Note: multiple tabs are open — verify the active tab before acting:\n${tabResult.stdout.trim()}` : undefined,
+            "The session drives this real browser window directly. Take a fresh agent_browser_snapshot before continuing.",
+            "This login browser has an open remote-debugging port and will stay open until agent_browser_close is called for this session (or the window is closed manually).",
+          ].filter(Boolean).join("\n"),
         }],
         details: { ...result, artifactPaths: [] },
         terminate: true,
@@ -1028,15 +1061,43 @@ export default function agentBrowserExtension(pi: ExtensionAPI) {
   pi.registerTool({
     name: "agent_browser_doctor",
     label: "Agent Browser Doctor",
-    description: "Run agent-browser doctor to verify installation, Chrome, daemon, security, providers, network, and launch tests.",
-    promptSnippet: "Use agent_browser_doctor when browser automation fails or before relying on agent-browser in a workflow.",
+    description: "Run agent-browser doctor to verify installation, Chrome, daemon, security, providers, network, and launch tests. Also reports and cleans up tracked login-handoff browsers (see agent_browser_login_handoff).",
+    promptSnippet: "Use agent_browser_doctor when browser automation fails or before relying on agent-browser in a workflow. It also flags any live login-handoff browsers left open and cleans up stale tracking entries.",
     parameters: DoctorSchema,
     async execute(_id, rawParams, signal, onUpdate, ctx) {
       const params = rawParams as JsonObject;
       const args = ["doctor"];
       if (params.fix === true) args.push("--fix");
       const result = await runAgentBrowser(args, { signal, timeoutMs: params.timeoutMs as number | undefined, cwd: ctx.cwd, onUpdate });
-      return buildTextResult(result);
+      const textResult = buildTextResult(result);
+
+      const states = await readSessionStates(ctx.cwd);
+      const liveBrowsers: { session: string; pid: number; port: number | undefined; lastUrl?: string }[] = [];
+      for (const [session, state] of Object.entries(states)) {
+        if (!state.loginBrowserPid) continue;
+        if (!isPidAlive(state.loginBrowserPid)) {
+          await writeSessionState(ctx.cwd, session, { clearLoginBrowserPid: true });
+          continue;
+        }
+        liveBrowsers.push({
+          session: session === DEFAULT_SESSION_KEY ? "(default)" : session,
+          pid: state.loginBrowserPid,
+          port: state.loginDebugPort,
+          lastUrl: state.lastUrl,
+        });
+      }
+
+      if (liveBrowsers.length > 0) {
+        const lines = [
+          "",
+          "Live login browsers (from agent_browser_login_handoff) still open:",
+          ...liveBrowsers.map((b) => `- ${b.session}: pid ${b.pid}, debug port ${b.port ?? "?"}${b.lastUrl ? `, last url ${b.lastUrl}` : ""}`),
+          "Call agent_browser_close for each session when done — these hold an open remote-debugging port until closed.",
+        ];
+        textResult.content[0].text += lines.join("\n");
+      }
+
+      return textResult;
     },
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@53able/pi-agent-browser",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Typed Pi tools for browser automation, rendered-page context extraction, screenshots, and saved session state via agent-browser.",
   "type": "module",
   "license": "MIT",

package/skills/agent-browser/SKILL.md

@@ -44,7 +44,7 @@ Two tools exist so the agent stops and hands control back to a human instead of
 
 `agent_browser_login_handoff` solves a specific problem: Google and similar OAuth providers block sign-in when `agent-browser open` is used, because agent-browser attaches a remote debugging protocol (CDP) session the instant Chrome launches, and Google detects this automation marker and rejects the login attempt regardless of profile, cookies, or executable.
 
-This tool spawns a plain, un-instrumented Chrome process (not through `agent-browser open`) with a remote debugging port and a dedicated persistent profile, so no CDP client is attached while the human logs in. Chrome behaves like an ordinary browser to Google during sign-in. After the human confirms login is complete, the tool captures the authenticated cookies and storage from that browser (`agent-browser state save`), closes the disposable login browser, and loads that captured state into a fresh, ordinary agent-browser session (`agent-browser state load`) for all subsequent automated snapshot, read, and click operations. (An earlier version tried to keep driving the login browser live over CDP; that opened a disconnected blank tab instead of reusing the authenticated one, so state capture-and-load is used instead.)
+This tool spawns a plain, un-instrumented Chrome process (not through `agent-browser open`) with a remote debugging port and a dedicated persistent profile, so no CDP client is attached while the human logs in. Chrome behaves like an ordinary browser to Google during sign-in. After the human confirms login is complete, the still-running login browser is **live-attached to the named agent-browser session** (via `agent-browser --session <name> --cdp <port> snapshot`, not `open`, to avoid navigating away from the authenticated page) and **kept open as the permanent backing browser for that session**. All subsequent automated snapshot, read, click, and other operations continue to work against it via `--session <name>` alone, unchanged.
 
 **Important:** this is an architecture fix, not detection evasion. The tool does not hide webdriver flags or automation fingerprints — it simply avoids having a CDP session attached during the interactive login moment itself.
 
@@ -60,7 +60,13 @@ Example call:
 }
 ```
 
-After the human confirms login is complete, subsequent `agent_browser_open`, `agent_browser_snapshot`, `agent_browser_click`, and other calls with the same `session` name will reuse the authenticated browser state and operate normally. This new session runs headless by default (it is a fresh agent-browser session, not the disposable login browser, which is closed once its auth state is captured); reopen it with `headed: true` if you need to see it.
+After the human confirms login is complete, subsequent `agent_browser_open`, `agent_browser_snapshot`, `agent_browser_click`, and other calls with the same `session` name will reuse the authenticated browser and operate normally. **The login browser window remains visible and open indefinitely** — this is a real, user-visible Chrome window with an open remote-debugging port on `127.0.0.1` that any local process can access. The session is recorded as `headed: true` (since the authenticated browser is still running).
+
+**Security note:** The login browser's `--remote-debugging-port` remains open on localhost for as long as the session is alive. This gives any local process full browser control — the same caveat agent-browser's own docs give about `--remote-debugging-port`. Call `agent_browser_close` when done with a session that went through login handoff, rather than leaving it open indefinitely. `agent_browser_close` will terminate the tracked login Chrome process and clean up its debugging port.
+
+Run `agent_browser_doctor` to see which sessions still have live login browsers open. It reports any that are still running (session name, process ID, debugging port, and last known URL) with a reminder to call `agent_browser_close`. Stale tracking entries for processes no longer running are cleaned up silently with no user notification.
+
+Re-running `agent_browser_login_handoff` for the same session name will terminate any previous live login browser for that session before spawning a new one.
 
 ## Common examples