mcp-pacemaker 2.1.0 → 2.1.2

package/bin/windows-legacy-process.mjs

@@ -6,6 +6,13 @@ import { fileURLToPath } from 'node:url';
 
 const HELPER = fileURLToPath(new URL('./windows-legacy/LegacyProcessBroker.exe', import.meta.url));
 const METADATA = fileURLToPath(new URL('./windows-legacy/LegacyProcessBroker.build.json', import.meta.url));
+// Each wait outlasts the broker's own limit. The broker may take 15 s to read a request,
+// then has a 120 s capture or verification phase, or a 120 s revalidation and a 20 s stop,
+// each with a 10 s watchdog margin. MESSAGE_BYTES equals the broker's request limit.
+const MESSAGE_BYTES = 262144;
+const PREPARE_TIMEOUT_MS = 150000;
+const VERIFY_TIMEOUT_MS = 150000;
+const STOP_TIMEOUT_MS = 170000;
 
 class LegacyBroker {
   constructor() {
@@ -62,7 +69,7 @@ class LegacyBroker {
     });
     this.child.stdout.on('data', (chunk) => {
       this.buffer += chunk;
-      if (this.buffer.length > 262144) {
+      if (this.buffer.length > MESSAGE_BYTES) {
         this.failure(new Error('Legacy broker response exceeded bounds'));
         this.child.kill();
         return;
@@ -128,7 +135,7 @@ class LegacyBroker {
 
   encode(value) {
     const bytes = Buffer.from(`${JSON.stringify(value)}\n`, 'utf8');
-    if (bytes.length > 262144) throw new Error('Legacy broker request exceeded bounds');
+    if (bytes.length > MESSAGE_BYTES) throw new Error('Legacy broker request exceeded bounds');
     return bytes;
   }
 
@@ -143,7 +150,7 @@ class LegacyBroker {
     this.encode(request);
     this.start();
     try {
-      const result = await this.request(request, 20000);
+      const result = await this.request(request, PREPARE_TIMEOUT_MS);
       const plan = result.plan;
       if (plan?.kind !== 'legacy-observed-process-set' ||
           plan.protocol !== 1 ||
@@ -183,7 +190,7 @@ class LegacyBroker {
     try {
       const response = await this.request({
         action: 'stop', token: this.token, planSha256: this.plan.planSha256,
-      }, 30000);
+      }, STOP_TIMEOUT_MS);
       const receipt = this.receipt(response.receipt);
       const exit = await this.finish();
       if (exit.code !== 0 ||
@@ -223,7 +230,7 @@ class LegacyBroker {
     this.encode({ action: 'verify', expected: plan });
     this.start();
     try {
-      const response = await this.request({ action: 'verify', expected: plan }, 20000);
+      const response = await this.request({ action: 'verify', expected: plan }, VERIFY_TIMEOUT_MS);
       const receipt = this.receipt(response.receipt);
       const exit = await this.finish();
       if (exit.code !== 0) throw new Error('Legacy verification broker exit failed');

package/docs/account-upgrades.md

@@ -46,7 +46,11 @@ Administrators membership, and complete native authorization checks. Restricted,
 AppContainer, impersonating or unverified cross-account contexts refuse.
 No account label, saved administrator flag or group membership alone grants
 authority. The product does not request UAC, enable privileges, impersonate,
-supply passwords, create accounts or change existing permissions.
+supply passwords, create accounts or change existing permissions. The one
+exception is outside this path: the default-scope `upgrade --fix-legacy-access`
+step, which an administrator runs explicitly for a 1.3 install that was set up
+from an administrator terminal. It changes only that task's run-as user entry and
+the owner of that install's `bin\cli.mjs`.
 
 ## Where code executes
 
@@ -122,9 +126,11 @@ possible. Manual/external task starts are not claimed suppressed. Conflicting
 generations or revisions refuse. Because `IgnoreNew` can block a second task run
 while the worker is active, verified legacy rollback launches the original
 supervisor locally **inside the original-user worker**, not as the administrator.
-Legacy captured roots and observed descendants are checked for the worker's
-session before stop; native held-generation revalidation remains stop authority.
-Excluded or unattributed historical processes are never session-query or kill targets.
+Legacy captured roots are checked for the worker's session before stop; native
+held-generation revalidation remains stop authority. Plans no longer list
+descendants: the processes the 1.3 bridge started are found and stopped by the
+broker during the stop, through the same handles, without a separate session query.
+Processes that cannot be traced to the bridge are never session-query or kill targets.
 The compact session request accepts at most 512 unique captured identities and
 128 KiB of UTF-8. PID, FILETIME and current-account/session fields are checked
 before discovery. Session queries use at most 32 exact IDs per batch and four
@@ -138,6 +144,13 @@ pre-bootstrap task revision after fresh authorization. No staging or stop is
 authorized by that decline. Failed authorization or restoration remains an
 explicit uncertain outcome.
 
+An upgrade refused before anything stops, for example because `servers.json`
+changed while the target downloaded, puts the current version back in service
+and restores the original task before its journal settles, so a later
+`--recover` changes nothing. If the current version could not be resumed or the
+task could not be restored, the journal stays open and `--recover` finishes the
+job.
+
 ### Controller-only failure before instance publication
 
 If bootstrap happened but automatic restoration failed before any managed

package/docs/comparison.md

@@ -0,0 +1,167 @@
+# How mcp-pacemaker compares
+
+Checked on October 16, 2026, from each project's documentation and source. We did not run the
+other tools. Corrections are welcome: open an issue with a link.
+
+| Project | Release checked |
+|---|---|
+| [Supergateway](https://github.com/supercorp-ai/supergateway) | v4.2.0 (2026-10-15) |
+| [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) | v0.13.0 (2026-10-10) |
+| [MCP Hub](https://github.com/ravitemer/mcp-hub) | v4.2.1 (2025-08-22, no later commits) |
+| [ToolHive](https://github.com/stacklok/toolhive) | v0.54.0 (2026-10-14), desktop app v0.40.2 |
+
+✅ means documented or implemented. ❌ means we did not find it in the README, docs, CLI options
+or source; it does not mean the feature is impossible. Text in a cell describes partial support.
+ToolHive's desktop app counts as part of ToolHive.
+
+| | Supergateway | mcp-proxy | MCP Hub | ToolHive | **mcp-pacemaker** |
+|---|---|---|---|---|---|
+| Serves stdio servers over Streamable HTTP | ✅ | ✅ | ❌ | ✅ | ✅ |
+| Serves stdio servers over SSE (legacy) | ✅ | ✅ | ✅ | ✅ (deprecated) | ✅ |
+| What you install | npm, binary or Docker | PyPI or Docker | npm or Nix | Go binary + Docker or Podman | npm; the bridge has **zero** dependencies |
+| Restarts crashed processes automatically | new child per connection | ❌ | manual restart (API) | ✅ | ✅ bridge and warm pools |
+| Starts at OS logon | ❌ | ❌ | ❌ | desktop app only | ✅ Windows, macOS, Linux |
+| Starts again after unlock or wake | ❌ | ❌ | ❌ | ❌ | ✅ Windows |
+| Auth header from your own command, auto-refreshed | ❌ | ❌ | at connect only | ❌ | ✅ |
+| Sessions survive a bridge restart without re-initializing | ❌ | ❌ | ❌ | Kubernetes with Redis only | ✅ |
+| Timed restart to refresh an interactive login | ❌ | ❌ | ❌ | ❌ | ✅ |
+| Reuses existing client MCP config files | ✅ | stdio entries only | ✅ | ❌ | ✅ |
+| Wires editors and CLIs for you | ❌ | ❌ | ❌ | ✅ | ✅ |
+| Web dashboard | ❌ | ❌ | ❌ | desktop app instead | ✅ |
+| Terminal dashboard | ❌ | ❌ | ❌ | ✅ (experimental) | ✅ |
+| HTTP control API | health checks only | `/status` only | ✅ | ✅ | ✅ |
+
+## Sources
+
+### Supergateway v4.2.0
+
+- **Transports:** stdio → SSE is the default output
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L50-L63)); stdio →
+  Streamable HTTP in both directions
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L84-L130)).
+- **Install:** npm, standalone executables
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L258-L294)) or Docker
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L334-L380)).
+- **Crashed processes:** each SSE/WebSocket connection gets its own child and a reconnecting client
+  gets a fresh one ([CHANGELOG](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/CHANGELOG.md#L83));
+  when a child exits, its calls fail and the session ends
+  ([source](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/src/gateways/sseSession.ts#L120-L170)).
+- **Logon start, unlock, timed restart:** not in the option list
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L13-L48),
+  [options](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/src/cliOptions.ts)); the only
+  related option, `--sessionTimeout`, expires idle sessions.
+- **Auth:** static `--header` and `--oauth2Bearer`
+  ([options](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/src/cliOptions.ts#L106-L117));
+  `${VAR}` in the config file is expanded once at load
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L209)).
+- **Sessions:** stateful sessions are kept in memory, and an unknown session ID after a restart gets
+  404 ([source](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/src/gateways/statefulSessions.ts#L211-L232)).
+  Stateless mode has no session to lose
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L107-L129)).
+- **Config reuse and wiring:** `--config` reads a Claude Desktop `mcpServers` file
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L179-L218)); client
+  entries are written by hand
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L382-L467)).
+- **Dashboards and API:** health endpoints only
+  ([README](https://github.com/supercorp-ai/supergateway/blob/v4.2.0/README.md#L39-L40)).
+
+### mcp-proxy v0.13.0
+
+- **Transports:** `/sse` and `/mcp` server routes
+  ([source](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/src/mcp_proxy/mcp_server.py#L89-L93));
+  stdio → SSE server mode
+  ([README](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/README.md#L98-L170)).
+- **Install:** uv, pipx or Docker, Python 3.10 or newer
+  ([README](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/README.md#L222-L261)).
+- **Crashed processes, logon start, timed restart:** not in the option list
+  ([README](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/README.md#L318-L398)). The Docker
+  Compose example relies on Docker's `restart: unless-stopped`
+  ([README](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/README.md#L297-L316)).
+- **Auth:** static headers, `API_ACCESS_TOKEN`, OAuth2 client credentials and Basic/Digest
+  ([README](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/README.md#L56-L74)). OAuth2 tokens
+  refresh, but no user command produces the header.
+- **Sessions:** kept in memory (`event_store=None`)
+  ([source](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/src/mcp_proxy/mcp_server.py#L89-L93));
+  `--stateless` avoids sessions.
+- **Config reuse and wiring:** `--named-server-config` reads the stdio entries of an `mcpServers` file
+  ([source](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/src/mcp_proxy/config_loader.py#L15-L70));
+  client entries are written by hand
+  ([README](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/README.md#L76-L96)).
+- **Dashboards and API:** a read-only `/status` JSON
+  ([source](https://github.com/sparfenyuk/mcp-proxy/blob/v0.13.0/src/mcp_proxy/mcp_server.py#L48-L73)).
+
+### MCP Hub v4.2.1
+
+- **Transports:** its single `/mcp` endpoint is SSE
+  ([source](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/src/server.js#L345-L372)); Streamable HTTP
+  is only used to connect to remote servers
+  ([README](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/README.md#L19-L20)).
+- **Install:** npm (one bundled file) or a Nix flake
+  ([README](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/README.md#L136-L140)).
+- **Crashed processes:** restart is manual through `POST /api/restart`
+  ([README](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/README.md#L791)); we did not find an
+  automatic restart of a local server in the source
+  ([source](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/src/MCPConnection.js#L626-L631)).
+- **Logon start:** not documented; the 2.2.0 notes suggest running it under systemd yourself
+  ([CHANGELOG](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/CHANGELOG.md#L430-L436)).
+- **Auth:** headers accept `${cmd: …}`, which runs when the server connects
+  ([README](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/README.md#L255-L262),
+  [source](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/src/MCPConnection.js#L161-L164)).
+- **Sessions:** SSE sessions are kept in memory
+  ([source](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/src/mcp/server.js#L473-L490)).
+- **Config reuse and wiring:** existing `.vscode/mcp.json` and `mcpServers` files work directly
+  ([README](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/README.md#L168-L253)); clients are
+  pointed at the hub by hand
+  ([README](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/README.md#L51-L60)).
+- **Dashboards and API:** REST API
+  ([README](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/README.md#L422-L800)); a web UI and TUI
+  are listed as to-do items
+  ([README](https://github.com/ravitemer/mcp-hub/blob/v4.2.1/README.md#L1262-L1266)).
+
+### ToolHive v0.54.0 and desktop app v0.40.2
+
+- **Transports:** `--proxy-mode` is Streamable HTTP by default; SSE is deprecated
+  ([CLI docs](https://docs.stacklok.com/toolhive/reference/cli/thv_run)).
+- **Install:** a Go binary that needs a container runtime
+  ([install](https://docs.stacklok.com/toolhive/guides-cli/install#prerequisites)), or the desktop app
+  ([install](https://docs.stacklok.com/toolhive/guides-ui/install)).
+- **Crashed processes:** exited containers restart with backoff
+  ([source](https://github.com/stacklok/toolhive/blob/v0.54.0/pkg/workloads/manager.go#L534-L640)).
+- **Logon start:** the desktop app's "Start on login" setting
+  ([docs](https://docs.stacklok.com/toolhive/guides-ui/install#application-settings)); the CLI has no
+  autostart command.
+- **Auth:** OAuth/OIDC with automatic refresh, a static bearer token read once, forwarded headers
+  and token exchange
+  ([CLI docs](https://docs.stacklok.com/toolhive/reference/cli/thv_run)).
+- **Sessions:** with Redis session storage, clients can reconnect and resume; with local storage
+  they re-initialize
+  ([architecture](https://github.com/stacklok/toolhive/blob/v0.54.0/docs/arch/13-vmcp-scalability.md#L193-L210)).
+- **Timed restart:** restarts are on demand only
+  ([docs](https://docs.stacklok.com/toolhive/guides-cli/manage-mcp-servers#lifecycle-management)).
+- **Config reuse and wiring:** `thv client setup` and `thv client register` configure 26 clients
+  ([CLI docs](https://github.com/stacklok/toolhive/blob/v0.54.0/docs/cli/thv_client_register.md#L20-L46));
+  import and export cover only ToolHive's own run configuration
+  ([CLI docs](https://github.com/stacklok/toolhive/blob/v0.54.0/docs/cli/thv_export.md#L20-L24)).
+- **Dashboards and API:** `thv tui` (experimental)
+  ([CLI docs](https://github.com/stacklok/toolhive/blob/v0.54.0/docs/cli/thv_tui.md#L14-L20)) and
+  `thv serve`
+  ([CLI docs](https://github.com/stacklok/toolhive/blob/v0.54.0/docs/cli/thv_serve.md#L18-L36)); the
+  web console is in the enterprise edition only
+  ([platform](https://docs.stacklok.com/platform)).
+
+### mcp-pacemaker
+
+- **Transports and hosts:** see [Supported hosts](../README.md#supported-hosts).
+- **Install:** the npm dependencies belong to the setup CLI and terminal dashboard; the bridge
+  imports only Node.js built-ins.
+- **Crashed processes:** the supervisor restarts the bridge, and warm-pool children are replaced
+  with backoff. See [configuration](configuration.md).
+- **Logon and unlock:** a Windows scheduled task starts at logon and on workstation unlock, which
+  also covers wake from sleep; macOS uses a launchd agent and Linux a systemd user unit.
+- **Auth:** `auth.type: "command"` runs your command and refreshes the token on a schedule
+  ([configuration](configuration.md#serversjson)).
+- **Sessions and timed restart:** session resume (`MCP_RESUME`) and scheduled recycle
+  (`recycleMinutes`) in [configuration](configuration.md).
+- **Config reuse and wiring:** `import --from` and `install --client`; see the
+  [command reference](operations.md#command-reference).
+- **Dashboards and API:** [dashboards](dashboards.md) and [HTTP API](http-api.md).

package/docs/compatibility.md

@@ -0,0 +1,39 @@
+# Version compatibility
+
+How the 1.3.x and 2.x lines work together. For npm channels and exact-version installs, see
+[install details](install.md). To replace a running installation, see
+[upgrades and rollback](upgrades.md).
+
+This documentation describes **2.1.2**. For 1.3.x immediate-save behavior, see the
+[legacy documentation](https://github.com/girishkvs/mcp-pacemaker/blob/v1.3.1/README.md)
+and [support policy](../SECURITY.md#supported-versions). Those documents do not establish
+that a legacy version is available on npm.
+
+The historical baselines remain **1.3.0 / 2.0.0**. The earlier **1.3.1 / 2.0.1** and
+**1.3.1 / 2.0.2** patch-pair evidence is not transferable to a new release. The **2.1.2**
+candidate requires fresh exact-byte compatibility and service-replacement gates.
+A 2.x client handles legacy immediate saves. A 1.x client cannot write pooling settings to a
+2.x bridge: update the CLI and refresh old dashboard tabs. Before downgrading, settle pending
+or interrupted transactions with 2.x. See the [real-version gates](../CONTRIBUTING.md#real-version-compatibility-gates)
+for exact pairs; only the exact executed pairs are covered.
+
+## Upgrading from 1.3.0
+
+Version 2.0.0 changes the configuration-save protocol; it does not require a new `servers.json`
+format. Update the bridge and CLI together, then reload any open dashboard pages. A 1.3.0
+client with a current nonce gets HTTP 409 before staging, with an instruction to update the
+client. An already-open tab retains the old nonce after a bridge restart and gets HTTP 401;
+refresh it to load the new dashboard and admin session.
+
+Custom API clients must send `x-mcp-pooling-batch: 1`. Treat HTTP 202 as acceptance, not
+completion, and follow the returned batch ID in `prewarm.batches` until it is applied,
+cancelled or failed. CLI scripts must likewise wait for application before relying on new
+settings. Undo now restores the complete batch and may affect several servers.
+Updated clients still understand the immediate HTTP 200 response from a 1.3.0 bridge.
+
+Before downgrading, cancel or apply pending changes with 2.0 and resolve any interrupted
+transaction using 2.0 recovery. Stop that bridge before starting 1.3.0 with the active config.
+Do not use a 1.3.0 binary to recover 2.0 transaction files or delete those files to bypass a
+recovery error. Keep a protected backup of the configuration before changing versions.
+If the writer worker exits, further automatic edits are refused until the bridge restarts;
+existing MCP sessions continue.

package/docs/configuration.md

@@ -0,0 +1,146 @@
+# Configuration
+
+How to define servers in `servers.json`, how live edits are applied, and the controls for
+sessions, resources and sharing.
+
+## servers.json
+
+Config lives at `~/.mcp-pacemaker/servers.json`. `import` fills it from your existing client
+config and **carries over `audience`/`auth`/`headers`**, so HTTP servers usually need no hand-editing.
+See [`examples/servers.example.json`](../examples/servers.example.json).
+
+```jsonc
+{
+  "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
+
+  "my-api": {
+    "type": "http",
+    "url": "https://my-service.example.com/mcp",
+    "auth": { "type": "command", "command": "my-cli print-token", "refreshMinutes": 50 }
+  }
+}
+```
+
+**Auth options** (per HTTP server):
+
+| `auth.type` | Behavior |
+|---|---|
+| `command` | Runs any command that prints a token on stdout; the result is cached and auto-refreshed (`refreshMinutes`). Provider-agnostic — see below. |
+| `env` | Uses `process.env[var]`. |
+| `static` | Fixed `header` + `value`. |
+| `none` | No header is added — the **client** authenticates, and the bridge relays OAuth discovery and challenges for it. |
+
+`auth.type: "command"` is deliberately just "run this and use what it prints", so it works with
+whatever issues tokens in your environment. Some examples — none of these are special-cased:
+
+```jsonc
+// Azure
+{ "type": "command", "command": "az account get-access-token --resource api://<id> --query accessToken -o tsv" }
+// Google Cloud
+{ "type": "command", "command": "gcloud auth print-access-token" }
+// AWS (e.g. a signed token from your own helper)
+{ "type": "command", "command": "aws-token-helper --profile prod" }
+// HashiCorp Vault
+{ "type": "command", "command": "vault read -field=token secret/my-api" }
+// 1Password / any secret manager
+{ "type": "command", "command": "op read op://vault/my-api/token" }
+// A plain script
+{ "type": "command", "command": "./scripts/get-token.sh" }
+```
+
+By default the token is sent as `Authorization: Bearer <token>`; set `header` to send it
+somewhere else (for example `{ "header": "X-Api-Key" }`).
+
+**How long a credential is cached.** If the command returns a JWT, its `exp` claim decides —
+`refreshMinutes` is only an upper bound and a fallback for opaque credentials. This matters
+because token CLIs serve from their own cache: `az account get-access-token` will hand back a
+token it minted earlier that may be nearly spent, and trusting a flat window would keep a dead
+token in play. If the upstream rejects a credential the bridge supplied, that 401 is reported on
+the server (`doctor`, `/api/status` → `lastError`) and the credential is discarded rather than
+reused — the client is never asked to log in for a server the bridge authenticates.
+
+> **Azure shorthand.** A bare `"audience": "<res>"` expands to
+> `az account get-access-token --resource <res> …`. That is a convenience for Azure users only —
+> every other provider uses `auth.command` above.
+
+## Editing servers.json while it runs
+
+Save the file and the bridge picks it up. Servers whose definition did not change are left
+completely alone — same processes, same live sessions — so adding one server does not cost you the
+fourteen that were already working:
+
+```bash
+$ mcp-pacemaker reload           # or just save the file; the bridge watches it
+✓ reloaded /Users/you/.mcp-pacemaker/servers.json on :8850
+·   added:   postgres
+·   changed: github
+·   2 session(s) restarted; untouched servers kept theirs
+```
+
+A file that does not parse, or a server with neither `command` nor `url`, is **rejected whole** —
+the bridge logs why and keeps serving the last good config, so a half-written save cannot take your
+servers down. Set `MCP_CONFIG_WATCH=0` to require an explicit `reload` instead of watching.
+
+## Multi-agent & resource controls
+
+Multiple hosts/agents can share one bridge — each gets its own isolated session by default,
+and HTTP servers share the cached token across all of them. The dashboard, `top`, and
+`mcp-pacemaker status` show **which agents are connected** to each server.
+
+| Control | Env / config | Default | Effect |
+|---|---|---|---|
+| Idle reaper | `MCP_IDLE_TIMEOUT_MS` | `1800000` (30 min) | free Streamable HTTP children idle past the timeout. Safe by default because a returning client's session is transparently re-established. `0` disables |
+| Concurrency cap | `MCP_MAX_SESSIONS_PER_SERVER`, or per-server `maxSessions` | `0` (unlimited) | reject new sessions past the cap (HTTP 503) |
+| Queue at the cap | `MCP_QUEUE_TIMEOUT_MS` | `10000` (10s) | at the cap, wait this long for a slot before returning 503, so a burst is absorbed rather than failed. `0` rejects immediately |
+| Sharing policy | per-server `sharing` (+ `minWarm`) | `isolated` | `isolated` = one child per session; `pool` pre-starts exclusive children; `shared` reuses one initialized child for compatible stateless tools sessions. Both alternatives require explicit activation |
+| Cold-start gate | `MCP_MAX_CONCURRENT_SPAWNS`, `MCP_SPAWN_GATE_WAIT_MS` | `2`, `15000` | how many package-manager-backed servers may cold-start at once. `npx`, `uvx`, `dnx` and friends share one cache, and starting several together can corrupt it — this queues them. Detected from the command, or forced either way with per-server `sharedPackageCache`. Servers that use no package manager are never gated. If no slot frees within the wait, the spawn proceeds ungated rather than hold a client request. `0` disables |
+| Pooling advice | `MCP_POOL_ADVICE_MS`, `MCP_WARM_MAX` | 2s, 8 | recommend pooling once a server's measured cold start passes this, and cap the suggested (and auto-sized) pool here. Advice only — the bridge never enables pooling on its own |
+| Session resume | `MCP_RESUME`, `MCP_RESUME_TTL_MS` | on, 24h | re-establish a session id the bridge has not seen — after a restart, recycle or idle reap. `MCP_RESUME=0` disables |
+| Scheduled recycle | per-server `recycleMinutes`, or `MCP_RECYCLE_MINUTES` | off | restart a server periodically, for servers holding a credential they can only refresh interactively |
+| Request timeouts | `MCP_REQUEST_TIMEOUT_MS` / `MCP_INIT_TIMEOUT_MS` | 30s / 180s | `initialize` also pays for spawning the server, so it gets a longer budget than ordinary calls |
+| Credential refresh | `MCP_TOKEN_REFRESH_LEAD_MS` | `300000` (5 min) | renew a cached token before it expires instead of discovering the expiry on a request. A JWT's own `exp` still caps how long it is cached |
+| Durable log | `MCP_LOG_MAX_BYTES` | `5242880` (5 MB) | `bridge.log` next to your config, rolled to `bridge.log.1` at this size. `0` disables. The dashboard only keeps the last few hundred lines in memory, which a chatty client fills in minutes |
+| Config watching | `MCP_CONFIG_WATCH` | on | reload `servers.json` when it is saved. `0` requires an explicit `mcp-pacemaker reload`. Either way, only servers whose definition changed are restarted, and an unparseable file is rejected without disturbing anything |
+| Health probing | `MCP_HEALTH_INTERVAL_MS`, or per-server `healthIntervalMinutes` | off | periodically call an HTTP server so it has a health verdict before a client needs it. Passive health from real traffic is always on and costs nothing |
+
+### Measuring process churn
+
+For stdio servers, `/api/status` reports `spawn.total` (successful process launches),
+`spawn.attempts`, `spawn.failures`, `spawn.warmAdoptions`, `spawn.sessionStarts`, and
+`spawn.sessionResumes`. Launches include classic SSE, Streamable HTTP, warm-pool refill,
+and replacements after recycle or resume. Adopting an existing warm child does not count
+as another launch. The unit is one bridge-launched process, not all of its descendants.
+
+These cumulative counters do not share the 50-sample latency limit. They reset when the
+bridge process restarts; compare snapshots only within the same `instanceId`. `startedAt`
+identifies that interval. Save the final snapshot before a planned restart for a before/after
+comparison. HTTP-proxied servers have no local process counters (`spawn: null`).
+
+`spawn.samples` and p50/p95/max still describe the latest 50 directly observed, successful
+cold initializations, not all launches. Latencies are `null` until observed; a warm child's
+idle lifetime is not a cold-start sample. The existing `requests` count covers routed HTTP
+requests, not just `tools/call`; do not label it as a tool-call count.
+
+### Shared mode
+
+Set `"sharing": "shared"` on a stdio server only when its tools are stateless, operate on
+explicit inputs and use one common credential context. This is an operator assertion, not
+something latency or matching capabilities can prove. Leave workspace-, conversation- or
+client-account-dependent servers isolated.
+
+Compatible sessions have identical full initialization parameters, including `clientInfo`,
+and empty client capabilities. One child receives one real initialization; each virtual session
+gets its own IDs, progress, cancellation and tools-list cursors. Only the upstream's actual
+tools capability is exposed. Roots, sampling, elicitation, tasks, resource subscriptions and
+other stateful methods are not supported. Incompatible clients fail explicitly, without
+silently falling back to a different mode.
+
+Deleting one session leaves the others running. The initialized child is retained between
+compatible reconnects for up to `sharedLingerMs` (30 minutes by default). Recycle drains work,
+then replaces the generation on later use. A timeout or child exit never triggers automatic
+replay of a potentially executed tool call.
+
+The server keeps its existing credential provider and configured `recycleMinutes`. Shared
+mode does not promise silent credential renewal. The dashboard and `prewarm` CLI show the
+actual shared-child state, members, queued work and cumulative process launches.
+See [the shared-session contract](shared-sessions.md) for limits and failure semantics.

package/docs/dashboards.md

@@ -0,0 +1,125 @@
+# Dashboards
+
+Two views of the same live state. Neither is required — the bridge runs headless — but both are
+useful for answering "is this server actually up, and who is using it?"
+
+## Web dashboard
+
+`mcp-pacemaker dashboard`, or open `http://127.0.0.1:<port>/ui`. It streams over SSE, so it
+updates on its own without polling or a refresh.
+
+![Web dashboard: one card per server, showing sessions, warm pool, pids and connected agents](images/dashboard.png)
+
+Per server it shows the transport (`stdio` / `http`), the sharing policy (`pool` when pre-warming),
+live sessions against the cap, request count, the actual OS pids, the warm-pool count, how long
+ago it was last used, and **which clients are connected** — above, one server is shared by
+VS Code and Claude Code while others are held by Copilot, Cursor and Codex. `Recycle` restarts
+that server's processes; it is disabled for servers with no session to restart. The live log at
+the bottom is the bridge's own log, filterable.
+
+## Pre-warming controls
+
+The **Pre-Warming** tab puts every stdio candidate, current pool and shared server in one table.
+It shows cold-start p50/p95, observed peak sessions, process starts, warm/target counts,
+shared-child state and pending work, and an action.
+HTTP proxies are excluded because the bridge does not launch their processes.
+
+Choose **Enable pre-warming (N)** on a slow-server card or in the table. The button shows
+the exact warm count and the extra resident-process cost before you click. Nothing enables
+it automatically. **Disable pre-warming** removes idle warm children without killing active
+sessions after the change is applied.
+
+Changes are batched in a **complete pending copy** of `servers.json`. Every accepted change
+resets a five-second countdown. When editing stops, reload validates the pending copy, retains
+the original as `servers.previous.json`, flips the pending file into place, and activates the
+new settings. The dashboard shows **Pending** or **Applying** until that succeeds; active
+mode and warm counts are not changed early. **Reload now** flushes the same batch immediately.
+
+**Cancel batch** discards a pending batch without changing active settings. **Undo batch**
+stages the full previous configuration for another five-second batch, only if no intervening
+active-file edit has occurred. These actions affect the entire batch; the dashboard names all
+affected servers. An unrelated pending batch must be cancelled or applied before Undo.
+
+The same controls are available without a browser:
+
+```sh
+mcp-pacemaker prewarm --port 8791
+mcp-pacemaker prewarm --port 8791 --enable filesystem --count 2
+mcp-pacemaker prewarm --port 8791 --disable filesystem
+# Changes are queued; the printed command cancels a pending batch or undoes it after application.
+```
+
+Use `--config <path>` when the bridge's config and admin nonce are outside the default
+directory. `--json` returns the measured snapshot. The CLI and UI use the same server
+eligibility and recommendation data; a missing latency sample is not reported as a zero-cost
+startup. The CLI returns after staging, so consecutive commands can join the same batch.
+`prewarm` shows pending settings separately from active values. Config remains strict JSON,
+not JSONC; the pending copy preserves unrelated JSON and requires a matching active revision.
+Conflicts are reported rather than overwriting someone else's edit.
+
+On Windows, saves run with the normal bridge account and use **directory-inherited auditing**.
+The dashboard gives a non-blocking notice: custom per-file audit rules may not carry forward
+to the new active copy. The retained original keeps its original metadata. No audit-read
+privilege, UAC prompt, or permanently elevated bridge is required.
+
+This does not permit broader access to configuration data. Candidates must have appropriate
+access restrictions before any configuration bytes are written, and supported integrity
+protections must be retained. Actual source write denial or unsupported protection remains
+an error. Configuration operations run in a serialized worker so file inspection does not
+block MCP traffic.
+
+Windows security inspection uses the bundled, own-source .NET Framework helper rather than
+starting PowerShell or compiling code on each write. Automatic edits require .NET Framework
+4.6.2 or later; modern Windows includes it. The helper's source, build instructions and
+integrity metadata are [included in the package](../tools/windows-security-helper/README.md).
+Windows ARM64 execution is not yet validated.
+
+Staging requests and file commits each have a bounded execution budget; the acknowledged
+five-second batching delay does not keep the original HTTP request open. A commit already in
+progress can finish after its deadline. The result distinguishes a pre-commit failure from
+a committed or unknown outcome; it never automatically retries or claims a timed-out write
+was rolled back.
+
+The two file moves are not an atomic exchange. Reload coordinates them with validated recovery
+state and non-replacing destination placement. Existing MCP traffic continues using the
+previous in-memory configuration during the flip; an external reader can briefly find the
+active path absent. Recovery must not overwrite a file created by an external editor.
+Reread the settings after an uncertain result.
+
+If you are upgrading from 1.3.0, see [upgrading from 1.3.0](compatibility.md#upgrading-from-130)
+for the configuration-save change and the reload that open dashboard tabs need.
+
+## Health
+
+The `Health` tab runs the same checks as `mcp-pacemaker doctor`, so you can see them without a
+terminal.
+
+![Health tab: Node version, config validity, per-server status and the admin nonce path](images/health.png)
+
+It checks the Node version, that the config parses, every server definition (including a stdio
+server whose relative path will not resolve from the directory it would run in — a failure that
+is otherwise silent until a client first calls it, and a server named after one of the bridge's
+own routes, which is unreachable), any server currently failing, and that the admin nonce file
+exists.
+
+## Terminal dashboard
+
+`mcp-pacemaker top` is the same data as an Ink TUI, for when a browser is inconvenient:
+
+```
+🫀 mcp-pacemaker top                                     ● :8850 · up 176s · v1.1.0
+SERVER            TYPE   HEALTH  SESS  WARM  REQ    PID       TOKEN   ERROR / CLIENTS
+filesystem        stdio  ok      2     1/1   8      186276,12 -       ⇄ Visual Studio Code,Claude Code
+github            stdio  ok      1     -     2      146436    -       ⇄ GitHub Copilot
+sqlite            stdio  ok      1     -     2      102108    -       ⇄ Cursor
+slow-tool         stdio  ok      1     -     2      103776    -       ⇄ Codex CLI
+search-api        http   FAIL×3  0     -     4      -         42m     upstream rejected the crede
+docs-api          http   ?       0     -     0      -         -
+↑↓ select · r recycle · q quit
+```
+
+`HEALTH` is `ok` when the last request to that server succeeded, `FAIL×n` after n consecutive
+failures, and `?` when nothing has called it yet — deliberately not `ok`, since no evidence is not
+the same as working. `WARM` shows `warm/minWarm` for pooled servers and `-` for the rest, `TOKEN`
+the time left on a cached credential, and the last column either the connected clients or the last
+error. `↑↓` selects a row and `r` recycles it.

package/docs/execution-context.md

@@ -71,7 +71,7 @@ The public workflow separates three roles rather than assuming an OS label impli
 | --- | --- | --- |
 | `test (ubuntu-latest\|macos-latest, 20\|22\|24)` | Stock hosted | Ordinary user-runtime source and compatibility suites |
 | `windows-ordinary (20\|22\|24)` | Stock hosted Windows | Install, syntax, pinned native toolchain, three reproducible native builds, the actual refusal of an elevated built-in Administrator, then the `source-ordinary` and `compatibility` contracts run as a provisioned disposable standard account |
-| Windows session lane | Ordinary interactive Windows session | The four `SESSION_REQUIRED_TESTS` files, through the local publication gate |
+| Windows session lane | Ordinary interactive Windows session | The four `SESSION_REQUIRED_TESTS` files, run on the publishing host by the local publication gate's host half |
 
 A stock hosted Windows runner signs in as the built-in Administrator with a full elevated token, and
 Task Scheduler ignores `RunLevel` for that account, so that account cannot host the ordinary
@@ -83,10 +83,16 @@ unexecuted.
 
 A provisioned account signs in with a password logon and has no interactive logon session, so the
 four `SESSION_REQUIRED_TESTS` files that bind one stay in the session lane. They are still required,
-not skipped: `tools/npm-publication/local-gate.mjs` runs the complete source suite for the current
-release and requires `role: user-runtime` with `sessionVerified: true`. A Windows container without a
-real logged-on account cannot satisfy that, and neither can a hosted job. `testContract` asserts the
-two Windows lanes cover every registered file exactly once, so no file can fall out of both.
+not skipped. The qualification container cannot host them either, because `ContainerUser` has no
+interactive logon session. The two halves of the local publication gate therefore split the suite.
+Inside the container, `tools/npm-publication/local-gate.mjs` verifies the `source-ordinary` contract,
+runs the contained source suite and records the session files in `sessionDeferredTests`. On the host,
+`tools/npm-publication/local-windows.mjs` runs the `session-required` contract through
+`tools/windows-ci/ordinary-run.mjs`, whose scheduled task supplies an ordinary, non-elevated caller
+inside a real interactive session, and writes `session-lane.json`. `verify-local.mjs` requires that
+receipt to report `role: user-runtime` with `sessionVerified: true`, zero failures, exactly the
+registered session files, and the same commit the contained cases qualified. `testContract` asserts
+the two Windows lanes cover every registered file exactly once, so no file can fall out of both.
 
 The CI provider bounds job lifetime and owns job teardown; the contract entry
 point does not claim to provide VM or network isolation.