Manage graph viewers with a supervised local service

docs/CONTRACT.md

@@ -1,4 +1,4 @@
-# DocForge 0.11 contract
+# DocForge 0.12 contract
 
 ## Authority boundary
 
@@ -23,7 +23,7 @@ approved contract and measured cross-project evidence; it is not an unimplemente
 - Result envelope: `schemas/result.schema.json`, version 1.
 - Changeset schema: `schemas/changeset.schema.json`, version 1.
 - Index schema: version 1, disposable and reproducible.
-- Core, CLI, and MCP server: version 0.11.0.
+- Core, CLI, and MCP server: version 0.12.0.
 
 Schema files describe the generic interchange contract. Runtime validation remains responsible for
 path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@@ -147,16 +147,19 @@ shortest-hop calculation places Nodes on distance rings; Flow uses left-to-right
 with the destination on the right. Each role palette darkens progressively by distance, capped at
 fifty percent.
 
-Each invocation creates or reuses one persistent local worker for the validated snapshot. The worker
-is detached from the short-lived MCP transport and has no browser inactivity or owner-process
-expiry. A repeated invocation reuses its unguessable URL when the validated snapshot is unchanged.
-If the index has changed, DocForge replaces the worker only after a fresh complete index check.
+Each invocation creates or reuses one worker through the separately supervised, per-user viewer
+manager. The manager is outside the short-lived MCP transport and owns all child workers as one OS
+service unit. It accepts only authenticated loopback requests and a validated immutable snapshot.
+A repeated invocation reuses its unguessable URL when the snapshot is unchanged. If the index has
+changed, it replaces the worker only after a fresh complete index check.
 
-`docforge_stop_visualization` is the only normal shutdown path. It stops the current project's
-verified worker and removes its private registry record. The worker also ends if the operating
-system terminates it. Project-specific integrations receive the same tools because the parent
-validates and serializes only the supplied `ProjectService` and `ProjectIndex` snapshot; the worker
-does not discover projects or load canonical sources.
+`docforge_visualization_status` reports the managed worker state. `docforge_stop_visualization`
+explicitly stops the current project's worker. The manager applies a one-hour activity timeout to
+genuinely abandoned workers. Browser activity renews that timeout, but normal MCP transaction or
+host-process completion does not affect it. The manager itself is restarted by an OS-native,
+per-user supervisor. Project-specific integrations receive the same tools because the parent
+validates and serializes only the supplied `ProjectService` and `ProjectIndex` snapshot; workers do
+not discover projects or load canonical sources.
 
 ## Project adapter boundary
 

docs/MCP_CONTRACT.md

@@ -21,6 +21,7 @@ same immutable project binding.
 - `docforge_render_status`
 - `docforge_visualize`
 - `docforge_stop_visualization`
+- `docforge_visualization_status`
 
 Each response states that document text is project content, not higher-priority instructions. Each
 response includes project identity, revision, source hash, adapter version, and staleness state.
@@ -82,11 +83,12 @@ visible key. Its navigation groups the focus, nodes reachable through outgoing e
 incoming or lateral context. Flow presents the same bounded snapshot as an upstream lineage.
 Execution edges retain their declared direction; reads, imports, and dependencies reverse to show
 what feeds the focus; structural, evidence, and context edges are excluded. The same relationship
-key is regenerated from the visible Flow edges. The browser runs in a project-bound persistent
-local worker, so standard-input transaction completion, MCP host exit, and browser inactivity do
-not close the listener. Repeated visualization requests reuse the current worker while its exact
-snapshot remains valid. `docforge_stop_visualization` explicitly stops the current project's
-verified worker.
+key is regenerated from the visible Flow edges. The browser runs in a project-bound worker owned by
+the separately supervised per-user viewer manager. Standard-input transaction completion and MCP
+host exit do not close the listener. Repeated visualization requests reuse the current worker while
+its exact snapshot remains valid. `docforge_visualization_status` reports lifecycle state, and
+`docforge_stop_visualization` explicitly stops the current project's worker. The manager reclaims a
+worker only after one hour with no browser activity.
 
 ## Excluded tools
 

docs/NEW_PROJECT_QUICKSTART.md

@@ -24,6 +24,7 @@ The DocForge repository contains the complete generic CLI and stdio MCP server.
   panning, zoom controls, viewport reset, relationship color and symbol keys, and an upstream
   lineage Flow view.
 - `docforge_stop_visualization`, which explicitly stops the current project's persistent viewer.
+- `docforge_visualization_status`, which reports the manager-owned viewer state.
 - Isolated documentation changesets, proposal validation, diffs, and escaped HTML previews when a
   proposal writer and render view are configured.
 
@@ -185,7 +186,7 @@ Add a project-specific stdio MCP server to the agent host:
 Restart or reload the agent host. Confirm that it exposes tools beginning with
 `docforge_project_info`, `docforge_get_node`, `docforge_search`, `docforge_dependencies`,
 `docforge_impact`, `docforge_get_context`, `docforge_visualize`, and
-`docforge_stop_visualization`, and `docforge_create_changeset`.
+`docforge_stop_visualization`, `docforge_visualization_status`, and `docforge_create_changeset`.
 
 Omit `--proposal-writer` for a read-only integration.
 
@@ -339,7 +340,9 @@ Place this policy in the project's `AGENTS.md` and adjust the manual path and pr
 - If DocForge reports stale state, missing nodes, invalid edges, or an index mismatch, stop and
   repair or rebuild the graph before claiming the work complete.
 - When asked to “visualize” the project or a node, call `docforge_visualize`. The viewer is
-  loopback-only, read-only, and persists until `docforge_stop_visualization` explicitly stops it.
+  loopback-only and read-only. Its native per-user manager keeps active pages alive across MCP
+  transactions, reports state through `docforge_visualization_status`, and reclaims only workers
+  idle for an hour. See `docs/VIEWER_MANAGER.md` for one-time installation.
 ```
 
 The policy is what makes DocForge part of normal development rather than an optional lookup tool.

docs/VIEWER_MANAGER.md

@@ -0,0 +1,54 @@
+# 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.