Multi instance support

[visail]

Add multi-instance support for concurrent browser automation
Problem:
When multiple sub-agents (e.g., Hermes) concurrently send navigation requests to the same Firefox instance, requests queue because Firefox cannot handle simultaneous page navigation. The entire stack was deeply singleton: hardcoded ~/.tbp/daemon.sock, ~/.tbp/daemon.pid, Xvfb :99,CDP port 9222, and a single Firefox profile.

Solution:
Introduce an instance_id concept throughout the stack. Default instance is "default" so existing behavior is unchanged. Each instance gets its own daemon process, Unix socket, PID file, log file, Xvfb display,CDP port, Firefox profile, and download directory.

Key changes:

• New src/instance_config.py: Central module for instance-aware paths and resource discovery. find_free_display() scans /tmp/.X{n}-lock for display numbers 99-199. find_free_port() test-binds TCP ports 9222-9322. Both skip resources already in use.

• src/browser.py: BrowserPilot accepts instance_id, display=None, cdp_port=None. Auto-discovers free resources when not explicitly provided. Removed global os.environ["DISPLAY"] mutation; passes DISPLAY via explicit env dict to all subprocesses. Removed pkill behavior that killed existing Xvfb — now only cleans stale lock files.

• src/pilot.py: Pilot accepts instance_id and passes it to BrowserPilot and NativeFirefoxSession. Uses per-instance SessionLock.

• src/native.py: NativeFirefoxSession accepts instance_id. Download directory uses per-instance path.

• src/daemon.py: Daemon accepts instance_id. Uses _setup_instance_paths() singleton-per-process pattern to set module-level path globals per instance, avoiding refactoring of 100+ handler functions. Creates per-instance directories on startup.

• src/client.py: is_daemon_running(), ensure_daemon(), send_command() all accept instance_id parameter. Daemon spawn includes --instance flag.

• cli.py: Added global --instance / -i argument. All command handlers pass instance_id through. cmd_kill() gains --all flag to terminate every instance by scanning ~/.tbp/instances/.

• src/mcp_server.py: _send() reads TBP_INSTANCE environment variable and passes instance_id to send_command(). Socket path polling in restart logic uses per-instance paths.

• src/gpu.py: VirglManager.start() is now idempotent — checks if virgl_test_server_android is already running before starting. Multiple instances safely share one virgl server.

• src/lock.py: SessionLock uses per-instance lock path.

• tests/test_multi_instance.py: Standalone asyncio test validating path isolation, resource discovery, dual-instance concurrent navigation, backward compatibility.

• CLAUDE.md: Updated architecture docs, data directory structure, multi-instance CLI examples, and Hermes/sub-agent usage guidance.

Backward compatibility:
All instance_id parameters default to "default". Existing single-instance commands (tbp goto, tbp stop, etc.) work exactly as before without any--instance flag.

Fix Xvfb display race and TMPDIR detection for Termux

• Use tempfile.gettempdir() instead of hardcoded /tmp so lock-file detection works under Termux where TMPDIR is under /data/data/...
• Add flock-serialized display reservation (~/.tbp/.display_alloc/) to prevent two concurrent instances from picking the same :99 before Xvfb writes its lock file
• Release display reservation on BrowserPilot.stop()

Co-Authored-By: Claude Opus 4.7 noreply@anthropic.com