odysseus/docs/runtime-decomposition/wave-5a-browser-lifecycle.md

Wave 5A: deterministic browser lifecycle

Base: a46eb7f47abaf15c799275f946d7dfe27bdee516, branch feature/browser-lifecycle. Scope is browser-specific lifecycle only. Request authority, approvals, TurnContract, generic process containment (Wave 3-S), effects/provenance (Wave 4), generic process lifecycle (Wave 5B) and runtime decomposition (Wave 6) are unchanged.

Runtimes

1. private_browser (src/agent_tools/web_tools.py, PrivateBrowserTool) is the model-facing browser. It runs the agent-browser CLI per action. The CLI is a short-lived client of a detached daemon; the daemon calls setsid and launches Chrome. Identity is --session ody-<hash(namespace, session_id)>. Other entry points: src/research_navigator.py (browser_read), scripts/probe_browser_budget.py, app shutdown in app.py.
2. Playwright MCP (src/builtin_mcp.py, server builtin_browser) is one global npx @playwright/mcp --headless --isolated --no-sandbox stdio server owned by src/mcp_manager.py. Its tools are hidden from the model unless private_browser is disabled or ODYSSEUS_EXPOSE_RAW_BROWSER_MCP is set (src/agent_loop.py, _should_hide_raw_browser_mcp). The two runtimes share no code; only Chromium discovery overlaps.

Probe evidence (agent-browser 0.27.0, this host)

• Runtime files live in AGENT_BROWSER_SOCKET_DIR, else $XDG_RUNTIME_DIR/agent-browser, else $HOME/.agent-browser, as <session>.{pid,sock,stream,version,engine}. The socket path must stay under about 103 bytes.
• Every Chrome process shares the daemon's POSIX session id (sid == daemon pid).
• close removes the daemon, Chrome, the runtime files and the agent-browser-chrome-* profile.
• SIGKILL of the daemon alone (the previous timeout path) left 13 Chrome processes, the profile, a Chromium temp directory and stale pid/socket files.
• close against a session with no daemon bootstraps one.
• A Chrome launch failure ("No usable sandbox", "Chrome exited early") leaves the daemon alive; close cannot reach a browser.
• There is no read command ("Unknown command: read").
• This host blocks the Chromium sandbox for agent-browser. Tests pass AGENT_BROWSER_ARGS=--no-sandbox in the test environment only; production launch flags are unchanged.

Failure modes found and their resolution

#	Failure	Resolution
F1	Cancellation not handled; CLI, daemon and Chrome survived until idle timeout	execute catches CancelledError, kills every CLI client of the call and cleans the session tree, then re-raises
F2	Timeout/exception killed only the daemon; Chrome reparented and leaked	browser_lifecycle.force_cleanup kills the daemon's whole POSIX session, removes runtime files and the profile, and verifies no survivor
F3	Shutdown force-kill used os.environ and only the legacy layout	Shutdown uses each session's recorded launch environment, closes only verified live daemons, then force-cleans and verifies
F4	Missing session_id used agent-browser's shared default session	A sessionless call gets an ephemeral session that is closed and verified before the call returns
F5	Launch failure left the daemon alive	Launch-failure output triggers forced cleanup and a truthful error
F6	Concurrent actions on one session raced one daemon	Per-session asyncio.Lock serializes actions
F7	Observation after a failed navigation silently showed the old page	Sessions track navigation generation, page URL and failed navigation; such observations are prefixed with an explicit stale notice and flagged stale_observation. A batch's navigation outcome comes from its per-command rows; when it cannot be determined the page is treated as unknown
F8	Recovery recursed through execute with a model-visible retry flag and no overall deadline	One deadline per call (action timeout + 75s); at most one retry, only for local read-only HTML open; model-supplied _odysseus_browser_retry is ignored
F9	research_navigator passed timeout, which the tool ignored	Passes timeout_ms
F10	No lifecycle evidence	Every result carries browser_lifecycle with stages, timings, ownership, state and cleanup receipt
F11	Pid lookup assumed /run/user/<uid>; containers without XDG_RUNTIME_DIR were never cleaned	Runtime root follows agent-browser's own resolution from the launch environment
F12	Per-call timeout swept every Chrome under the runtime TMPDIR, killing other sessions	Per-call cleanup is limited to the session tree; the TMPDIR sweep only runs at runtime shutdown
F13	read used a command agent-browser does not have	read URL runs open and get text body in one batch; success requires both rows; read without URL extracts the current page
F14	Playwright MCP calls had no time bound	builtin_browser calls are bounded by ODYSSEUS_BROWSER_MCP_CALL_TIMEOUT_S (default 90) and are not retried

Lifecycle model

Session states: idle, ready, navigation_failed, navigation_unknown, reset, timed_out, failed, launch_failed, bootstrap_failed, cancelled, closed. Any state reached by forced cleanup discards the page URL so nothing earlier remains observable. Ownership is retained for a chat session (bounded by AGENT_BROWSER_IDLE_TIMEOUT_MS, default 300000, and cleaned at shutdown) or ephemeral for a sessionless call.

The browser_lifecycle result field:

{"session": "ody-...", "ownership": "retained", "state": "ready",
 "navigation_generation": 2, "page_url": "file:///...",
 "stages": [{"stage": "open", "ms": 210, "ok": true, "cold_start": true}],
 "elapsed_ms": 230, "cleanup": {"method": "forced", "verified": true, "...": "..."},
 "recovery_attempts": 1, "stale_observation": true, "closed_page_url": "..."}

Optional keys appear only when relevant.

Ownership boundary

src/browser_lifecycle.py holds the browser-specific process attribution. It claims processes only through the session's own pid file and the daemon's POSIX session; once the daemon is gone it claims only Chrome process groups whose root carries an agent-browser-chrome-* profile. Without procfs it kills nothing. kill_browser_tree is the single seam to replace with the shared process-lifecycle primitives from Wave 3-S/5B.

Files

• New: src/browser_lifecycle.py, tests/test_browser_lifecycle.py, this document.
• Changed: src/agent_tools/web_tools.py (PrivateBrowserTool and shutdown), src/research_navigator.py (timeout argument), src/mcp_manager.py (bounded builtin_browser call), scripts/generate_env_reference.py and website/configuration-reference.md (new variable), tests/test_private_browser_tool.py (shutdown and read fakes).
• Not touched: src/agent_loop.py, src/tool_execution.py, src/agent_runtime/authority.py, approvals, task and background infrastructure.

Limitations

• A retained session's browser is not closed when its chat session is deleted; it is bounded by the idle timeout and shutdown cleanup.
• The in-process session registry keeps one small record per chat session that used the browser until shutdown.
• Chromium temp directories outside the profile (org.chromium.Chromium.*) are not attributable to one session and are not removed by forced cleanup.
• Playwright MCP remains one global browser shared by all sessions. A timed-out call is abandoned but the server is not restarted, because restarting the npx server requires its owner task in builtin_mcp.py.
• The stale-observation notice marks, but does not block, an observation after a failed navigation.
• Forced cleanup waits synchronously, at most one second, for killed processes to exit, so it can run from cancellation without awaiting.
• The recovery deadline covers the action and its retry. Post-action observations (page errors, settled snapshot, screenshot) keep their own 20 second bounds outside it.