# 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](docs/implementations/chrome-profile-lock-recovery.md).