Keep visualization worker alive until explicit stop

docs/CONTRACT.md

@@ -1,4 +1,4 @@
-# DocForge 0.10 contract
+# DocForge 0.11 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.10.0.
+- Core, CLI, and MCP server: version 0.11.0.
 
 Schema files describe the generic interchange contract. Runtime validation remains responsible for
 path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@@ -86,7 +86,7 @@ deployment, or publication.
 
 ## Project-bound graph visualization
 
-The fixed `docforge_visualize` MCP tool starts one leased read-only graph browser for the
+The fixed `docforge_visualize` MCP tool starts one persistent read-only graph browser for the
 server's already-configured project. It accepts only an optional stable node ID, an optional lexical
 query, and a bounded traversal depth. It does not accept a project root, database path, SQL,
 template path, bind address, command, or renderer.
@@ -102,10 +102,9 @@ random token is part of every accepted URL path. Only `GET` and `HEAD` are suppo
 no-store caching, a restrictive content-security policy, frame denial, MIME sniffing protection,
 and no-referrer policy. The built-in template uses only same-origin JSON endpoints for graph
 overview, bounded search, exact descriptor-category filtering, exact node content, bounded
-incoming-and-outgoing neighborhoods, and one lease heartbeat. Descriptor filtering accepts only
-family, authority, status, or tag plus one exact value. The heartbeat changes no project or index
-state. There is no write endpoint, arbitrary query endpoint, static filesystem handler, external
-asset, or project-selection control.
+incoming-and-outgoing neighborhoods. Descriptor filtering accepts only
+family, authority, status, or tag plus one exact value. There is no write endpoint, arbitrary query
+endpoint, static filesystem handler, external asset, or project-selection control.
 
 The `graph-browser@8` template provides mouse-wheel zoom centered on the pointer, left-button drag
 pan, explicit zoom-in and zoom-out buttons, a reset-view button, and a live zoom percentage. A
@@ -148,17 +147,16 @@ 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 launches the validated snapshot in a detached local worker. The worker is outside
-the short-lived MCP transport process, so transport teardown cannot close an active browser. It
-tracks the longer-lived MCP client host and closes when that owner process exits. A repeated
-invocation in the same MCP process replaces its tracked worker after a fresh index check.
+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.
 
-The page renews a 180-second lease every 15 seconds and when it becomes visible; a link never opened
-receives a 120-second startup grace. An abandoned page stops renewing and the detached worker closes
-after the bounded lease. Explicit service shutdown closes the worker tracked by that service
-immediately. Project-specific integrations receive the same tool because the parent validates and
-serializes only the supplied `ProjectService` and `ProjectIndex` snapshot; the detached worker does
-not discover projects or load canonical sources.
+`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.
 
 ## Project adapter boundary
 

docs/MCP_CONTRACT.md

@@ -20,6 +20,7 @@ same immutable project binding.
 - `docforge_validate_project`
 - `docforge_render_status`
 - `docforge_visualize`
+- `docforge_stop_visualization`
 
 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.
@@ -67,8 +68,8 @@ project overview. The tool returns a loopback URL and exact snapshot identity.
 
 The tool cannot select a project, database, template, host, port, filesystem path, or SQL
 expression. Its HTTP surface is token-bound, read-only, same-origin, and limited to overview,
-search, exact family/authority/status/tag filtering, node-neighborhood JSON, and a read-only
-browser-lease heartbeat. The browser exposes an exact validated index snapshot. It rejects index
+search, exact family/authority/status/tag filtering, and node-neighborhood JSON. The browser
+exposes an exact validated index snapshot. It rejects index
 replacement or alteration and requires another MCP invocation to refresh.
 Viewport interaction is entirely client-side: fitted neighborhood framing, wheel zoom, left-button
 drag pan, explicit zoom buttons, reset, and Space-to-center selection never request or mutate
@@ -81,10 +82,11 @@ 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 open browser renews a bounded lease in a
-detached local worker, so standard-input transaction completion does not close the listener. The
-worker tracks the longer-lived MCP client host and closes when that owner exits.
-Explicit service shutdown closes its tracked worker, and abandoned pages expire.
+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.
 
 ## Excluded tools
 

docs/NEW_PROJECT_QUICKSTART.md

@@ -23,6 +23,7 @@ The DocForge repository contains the complete generic CLI and stdio MCP server.
   multi-node framing, visible node selection, Space-to-center, mouse-wheel zoom, left-button drag
   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.
 - Isolated documentation changesets, proposal validation, diffs, and escaped HTML previews when a
   proposal writer and render view are configured.
 
@@ -184,7 +185,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_create_changeset`.
+`docforge_stop_visualization`, and `docforge_create_changeset`.
 
 Omit `--proposal-writer` for a read-only integration.
 
@@ -290,7 +291,8 @@ Require these adapter acceptance checks:
 - Missing targets, duplicate IDs, unsafe paths, unsorted metadata, and invalid hashes fail closed.
 - Building the graph does not import the application or cause runtime, network, database, or
   filesystem side effects.
-- Read-only MCP exposes only the fixed DocForge read surface, including `docforge_visualize`.
+- Read-only MCP exposes only the fixed DocForge read surface, including visualization start and
+  explicit viewer shutdown.
 - Proposal-enabled MCP cannot modify derived source facts or write outside confined changeset and
   preview roots.
 - Build, check, MCP protocol tests, adapter tests, and the owning project's full test gate pass.
@@ -337,8 +339,7 @@ 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 and read-only. An open page renews its bounded lease across short MCP transactions;
-  explicit process termination closes it, and an abandoned page expires automatically.
+  loopback-only, read-only, and persists until `docforge_stop_visualization` explicitly stops it.
 ```
 
 The policy is what makes DocForge part of normal development rather than an optional lookup tool.