# Viewer manager

DocForge graph viewers are owned by one local, per-user viewer-manager service. The MCP server
does not own browser workers. This prevents normal stdio MCP turnover from closing a page while it
is in use.

The manager listens only on `127.0.0.1` and chooses an ephemeral port. Its private state record
contains that port and a high-entropy capability token. The record lives in the current user's
runtime directory on Linux, Application Support directory on macOS, or Local AppData directory on
Windows. The manager starts no network listener beyond loopback.

One worker is reused per project binding and validated index snapshot. `docforge_visualize` replaces
the worker only after the snapshot changes. `docforge_visualization_status` reports its state, and
`docforge_stop_visualization` explicitly stops it.

The default one-hour idle policy is intentional. Browser requests, including the existing visible
page heartbeat, renew activity. A page is never tied to the lifetime of one MCP request or host
process. The manager stops genuinely abandoned workers after an hour without activity. Stopping the
manager also stops all of its workers.

## Install the user service

Run this once in the same DocForge environment that will run the MCP server:

```bash
docforge-viewer-manager install-user-service
```

The command installs and starts the native user-level supervisor:

- Linux uses a `systemd --user` service with `Restart=on-failure` and `KillMode=control-group`.
- macOS uses a LaunchAgent under `~/Library/LaunchAgents`.
- Windows uses a per-user Task Scheduler entry named `DocForgeViewerManager`.

Use `docforge-viewer-manager uninstall-user-service` to stop and remove it. For development or a
nonstandard supervisor, run this foreground command instead:

```bash
docforge-viewer-manager serve
```

The service command intentionally uses the Python interpreter that installed it. After moving or
recreating the DocForge virtual environment, run the install command again so the native service
points at the new interpreter.

## Operational behavior

The manager is a small, long-lived control service. Its worker count is bounded by the number of
currently viewed project snapshots, not the number of MCP requests. A crashed manager is restarted
by the native supervisor. The supervisor stops child workers as one unit, avoiding orphan listeners.

MCP only receives a loopback URL after the manager has accepted the exact validated snapshot. If the
manager is unavailable, DocForge returns `visualization_manager_unavailable` with the state path so
the integration can be repaired without falling back to an unmanaged worker.