fix: clean up tabs owned by each CLI invocation

[kesava500]

Summary

Automatically clean up tabs owned by each browser-harness CLI invocation without touching pre-existing tabs or targets opened by another process.

This rebases and extends the approach proposed by @hamanori in #354, which is now conflicting with main.

What changed

• Track only targets created by this process through new_tab().
• Close owned targets in a finally block, including when the browser task raises an error.
• Restore a pre-existing blank tab when new_tab() reuses it instead of closing that target.
• Move the daemon onto a fresh blank keeper before closing its currently attached owned target.
• Leave the current target open if a safe session handoff fails, rather than leaving the daemon attached to a dead session.
• Support explicit persistence through keep_opened_tabs() or BH_KEEP_TABS=1.
• Document the lifecycle behavior in SKILL.md.

Why

The browser daemon intentionally survives between CLI invocations, so tabs also survive unless an agent remembers to close them. Long-running agents and scheduled research tasks therefore accumulate abandoned tabs and eventually consume substantial browser resources.

The original #354 ownership model avoids closing unrelated tabs. This version also accounts for current main reusing an existing blank tab and for the dangling-session failure described in #379 when the attached target closes.

The same lifecycle applies when the CLI is connected to a remote or cloud browser. Cleanup remains limited to targets owned by that invocation.

Verification

• uv run --with pytest python -m pytest -q (137 passed)
• uv run --with ruff ruff check tests/unit/test_tab_cleanup.py
• uv run python -m compileall -q src tests
• git diff --check
• Live Chromium check: two navigated task pages were cleaned up, the reused keeper returned to about:blank, and the next CLI invocation remained attached and usable.
• Concurrency check: an untracked target created alongside owned tabs survived cleanup.

Related work

• Builds on and credits Auto-close tabs opened by browser-harness runs #354.
• Handles the automatic-cleanup form of close_tab() on the current tab leaves dangling session state #379 without changing the public close_tab() API addressed by fix: close_tab() recovers session state when closing the currently attached tab #393.
• Incorporates the blank-target lifecycle concerns explored in Fix cdp() params-dict form and new_tab() blank-tab leak #417 and fix: reuse existing blank tab in browser harness #478 while preserving per-process ownership.
• Does not adopt feat(tabs): cap the number of open tabs #520's global tab cap because a global cap can close pre-existing or concurrently owned tabs.

---

Summary by cubic

Automatically cleans up tabs owned by each browser-harness CLI run and keeps the daemon attached to a live page. Cleanup runs after success or error and never touches unrelated tabs.

• Bug Fixes

  • Close only tabs created via new_tab() and do it in a finally block; print a warning if cleanup fails and never mask task errors.
  • Restore reused blank tabs to about:blank when not keeping; keep mode now protects reused-blank tabs too. force=True still restores/closes.
  • Move the daemon to a fresh keeper before closing an owned tab; keep the current tab if the handoff fails and retain failures for retry.
  • Never close pre-existing tabs, tabs from other processes, or indirect popups (window.open, target=_blank).
  • Added opened_tabs(), keep_opened_tabs(), and close_opened_tabs(force=False); the keep flag is scoped to one invocation. Documented lifecycle in SKILL.md and added targeted tests.

• Migration

  • To keep new tabs or reused blank tabs for a later run, call keep_opened_tabs() or set BH_KEEP_TABS=1 (case-insensitive). In keep mode, owned and reused-blank tabs are left as-is; use close_opened_tabs(force=True) to restore or close them.

^{Written for commit d57c921. Summary will update on new commits.}

[browser-harness-review]

✅ Skill review passed

Reviewed 1 file(s) — no findings.

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>