# Supervisor process and presence file

> Tie browser lifetime to a launcher process or a local presence file, or receive a notification instead of exiting.

Source: https://console.getchrovia.com/en/docs/sdk-supervisor-process

**Entitlement:** `supervisorProcess`. **Launch switches:** `--supervisor-process-id` and `--supervisor-presence-file`. **EP:** `internal.supervisor_process.exit_browser_on_exit`.

## Choose the supervisor signal

| Signal | Supported platforms | Meaning |
| --- | --- | --- |
| `--supervisor-process-id=<pid>` | Windows and macOS | Observe a running external process |
| `--supervisor-presence-file=<absolute-path>` | Windows, macOS, Linux | Observe continued presence of a local file |

Both switches can be used together. For example, a launcher process handles crash/exit supervision while deleting a presence file handles explicit logout or access revocation without exiting the launcher.

## Exit automatically

The default is to request browser exit when the watched supervisor ends. This EP makes the setting explicit:

```json
{
  "internal": {
    "supervisor_process": {
      "exit_browser_on_exit": true
    }
  }
}
```

A Node.js launcher can pass its own PID to the browser on Windows/macOS. Replace the executable and profile paths:

```js
import { spawn } from 'node:child_process';
const child = spawn('/absolute/path/to/browser', [
  '--user-data-dir=/absolute/path/to/profile',
  `--supervisor-process-id=${process.pid}`,
], { stdio: 'ignore' });
child.on('error', console.error);
```

Keep the launcher running. This snippet is external launcher code, not a Provision Worker script. `supervisorProcess` authorizes automatic shutdown; `processManagement` is only needed for explicit JS `process.exit()` calls.

## Presence-file contract

Create the file on local disk and close its handle **before** launching. Pass its absolute path; empty/relative paths and paths containing `..` are invalid. A directory does not count as a presence file. Deleting or renaming the file away, changing it into a directory, a missing initial file, or a watch failure invokes the configured supervisor-ended action. Editing file contents does not revoke presence.

The browser does not read file contents, lock the file, or recreate it. Your launcher is responsible for deletion on logout/revocation. On Windows, keeping a file handle open can postpone actual deletion. Use a local filesystem, not SMB/NFS, for reliable change notification.

## Notify instead of exiting

Set `exit_browser_on_exit` to `false` and also grant `messaging`. Register on every Provision Service Worker start:

```js
chrovia.messaging.on('chrovia.process.supervisor_exited', data => {
  console.log('Supervisor ended:', data);
});
```

PID notifications carry `{pid}`; file notifications carry `{path}`. If messaging is missing, non-exit mode logs a warning and cannot deliver the message. There is no automatic fallback to exit in that mode.

## Important limits

Neither switch is mandatory just because the entitlement is granted. With neither switch, supervision is not enabled. Invalid/unopenable PID values can only log and skip watching; do not treat the PID switch as a fail-closed launcher identity check. The file path's invalid/missing behavior is stricter, but file presence still does not authenticate a person or a launcher.

Test launcher exit and file deletion separately. Changing EP requires a restart and, for signed configuration, re-signing. See [process management](https://console.getchrovia.com/en/docs/sdk-process-management) for an explicit exit command and [messaging](https://console.getchrovia.com/en/docs/sdk-messaging) for event handling.