docs/implementations/chrome-files.md

Chrome User Data Directories & Profiles

PinchTab manages Chrome instances using dedicated User Data Directories (profiles). This document explains how these directories are resolved, how locks are managed, and how to handle parallel browser instances.

Profile Resolution

PinchTab determines the Chrome --user-data-dir (profile) using the following precedence:

1. Explicit ProfileDir: If a specific path is provided in the configuration or as a flag, PinchTab uses that exact directory.
2. Named Profile: If a profile name is provided (e.g., via the dashboard or CLI), PinchTab resolves it to a subdirectory within the ProfilesBaseDir.
3. Default Profile: If no profile is specified, it defaults to ~/.config/pinchtab/profiles/default (on Linux/macOS).

The Singleton Model

Chrome enforces a Singleton model per User Data Directory. This means:

• Only one Chrome process can use a specific profile directory at any given time.
• If a second process attempts to use the same directory, Chrome will either fail to start or (in some configurations) attempt to open a new window in the existing process.

PinchTab adds an additional layer of protection using a pinchtab.pid file within the profile directory to ensure that only one PinchTab instance manages a specific profile.

New Headless & Parallel Instances

With the introduction of New Headless mode (--headless=new), Chrome's profile sharing behavior has become stricter:

• No Sharing: You cannot reuse the same --user-data-dir across multiple concurrent instances.
• Separate Directories Required: Parallel browsers must use separate directories to avoid random startup errors and lock conflicts.

Headless Auto-Fallback

To support parallel automation tasks, PinchTab implements an automatic fallback for headless instances:

1. If a headless instance tries to start using a profile that is already locked by another PinchTab process, it will automatically create a unique temporary directory (e.g., /tmp/pinchtab-profile-*).
2. This allows you to run multiple headless tasks in parallel without manually managing profile paths.

Manual Parallelism (Headed Mode)

In headed mode, PinchTab does not automatically fall back to a temporary directory (to avoid losing user session data unexpectedly). If you need to run multiple headed browsers in parallel, you must:

• Use different named profiles.
• Explicitly provide a unique --user-data-dir for each instance.

Best Practices for AI Agents

When building agents that use PinchTab, follow these guidelines:

• Persistence: Use named profiles (e.g., agent-alpha, agent-beta) if you need the browser to remember logins, cookies, or history across sessions.
• Isolation: For one-off tasks or high-concurrency scraping, rely on the default headless mode which handles directory isolation automatically if conflicts occur.
• Cleanup: If you manually create temporary directories, ensure they are cleaned up after the task is complete to avoid filling up disk space.

Troubleshooting

If you see the error "The profile appears to be in use by another Chromium process":

1. Check for active instances: Ensure you don't have another PinchTab or Chrome process already using that profile.
2. Stale Locks: If no process is active, PinchTab will attempt to automatically clear stale SingletonLock files on the next startup.
3. Manual Fix: In rare cases, you may need to manually remove the SingletonLock file from the profile directory.

For more details on how PinchTab recovers from crashes, see Chrome Profile Lock Recovery.