mcp-pacemaker 2.0.2 → 2.1.1

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

@@ -0,0 +1,119 @@
+# User-runtime execution contracts
+
+The default runtime is an ordinary process belonging to its user. Starting the
+bridge or supervisor, registering autostart, upgrading and recovering do not
+silently elevate, demote, impersonate or select another account. An unavailable
+or privileged context refuses before runtime work. Read-only planning and
+installation with both `--no-start` and `--no-autostart` remain separate.
+
+`bin/runtime-context.mjs` is the shared observation boundary:
+
+| Platform | Required effective context |
+| --- | --- |
+| Windows | The existing native ordinary-caller proof: no elevation, enabled administrator membership or observed thread impersonation |
+| Linux | Stable non-root real/effective IDs, matching saved/filesystem IDs, and zero inherited/permitted/effective/ambient capabilities |
+| macOS | Stable non-root real/effective user IDs and matching real/effective group IDs |
+
+These are snapshots, not a promise that a process can never change context.
+The guard does not grant access to an arbitrary installation. Existing instance,
+file-security, service-registration and account-authorization checks still apply.
+Explicit original-account administration remains the separate Windows-only
+capability described in [account upgrades](account-upgrades.md).
+
+## Test contracts
+
+`tools/ci/test-contracts.mjs` declares the execution role, command and required
+capabilities. It verifies that the source contract includes every registered
+source test and preserves the declared test concurrency.
+
+| Contract | Required role and coverage |
+| --- | --- |
+| `source` | Ordinary runtime; complete registered source suite. Windows also needs the real caller's WTS logon because its account/session tests use that API. |
+| `source-ordinary` | Windows only. Ordinary runtime without a logon session; every registered file except the four in `SESSION_REQUIRED_TESTS`. The two Windows lanes must together cover every registered file exactly once. |
+| `compatibility` | Ordinary runtime; complete CLI/API compatibility command |
+| `browser` | Ordinary runtime; declared browser compatibility command |
+| `audit` | Verified privileged Windows fixture; the unchanged mandatory audit test, including its ordinary worker and complete result checks |
+| `service-context` | Read-only capability observation; **not** test coverage |
+
+Run the same entry point locally or in CI:
+
+```text
+npm run test:contract -- plan
+npm run test:contract -- source --check
+npm run test:contract -- source
+npm run test:contract -- compatibility
+npm run test:contract -- service-context --check
+```
+
+The service-context observation uses the current user's WTS session on Windows,
+owned `/run/user/<uid>` and user `systemd` manager on Linux, or the caller's `gui`
+launchd domain on macOS. A CLI-only or browser contract does not require a desktop
+merely for consistency with Windows.
+
+No adapter creates a user or session, changes UAC, edits privileges, rewrites a
+token, or falls back to another identity. Setup capability and ordinary runtime
+capability are not interchangeable. A missing required capability is a blocked
+qualification, not a successful skip.
+
+Windows integration fixtures also need a private checkout, home and temporary
+tree whose ancestors satisfy the existing path-security checks. A shared writable
+drive can correctly fail with `UNTRUSTED_PATH_WRITER` even when the process is
+ordinary. Use short, trusted profile-owned test roots: the nested upgrade packages
+must remain within the native .NET executable path limits, not just Node's file
+API limits. Do not change drive ACLs, enable long-path policy or relax the native
+checks to make an unsuitable test root pass.
+
+## CI and release boundaries
+
+The public workflow separates three roles rather than assuming an OS label implies a runtime.
+
+| Lane | Runner | What it proves |
+| --- | --- | --- |
+| `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, 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
+user-runtime contract. The lane therefore does not try to demote it. It provisions a disposable
+standard account, which is never an administrator, and runs the suite as that account. It also
+proves the elevated refusal itself, and `tools/ci/windows-runner-role.mjs` fails loudly if a Windows
+runner ever does satisfy the ordinary contract, so real coverage is promoted rather than left
+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. 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.
+
+The local command forwards cancellation to its owned test child and waits for
+exit/output closure, escalating termination after five seconds. Unverified
+closure after another five seconds is an error, not successful cleanup. Source
+tests retain a 60-minute command budget and compatibility tests a 45-minute budget;
+the audit keeps its existing 210-second budget and a 16 MiB output limit.
+Windows commands also use the existing native process-lifetime mechanism.
+None of these command bounds changes application startup or shutdown deadlines.
+
+No integration runner is provisioned by this change. An approved environment
+must already supply the required ordinary identity and session. Do not attach a
+personal workstation or unrestricted persistent runner to public pull requests.
+Runner admission, trusted-source selection, disposable-machine isolation and
+credential policy require independent infrastructure approval.
+
+The existing exact-source CI and local publication requirements remain enforced.
+The local source gate invokes the same read-only preflight and its verifier
+requires that original command receipt. A Windows container without WTS cannot
+stand in for an interactive user session. The privileged audit companion remains
+required and cannot replace the source suite. No missing integration result is
+relabelled as a pass.

package/docs/http-api.md

@@ -0,0 +1,47 @@
+# HTTP API
+
+Everything the dashboards show is plain HTTP on the same loopback port, so you can script it.
+Read endpoints need no auth; administrative writes require a nonce.
+
+| Endpoint | Method | Returns |
+|---|---|---|
+| `/status` | GET | Tiny liveness probe: `ok`, `service`, `version`, `port` and the server names. Used to tell a pacemaker bridge apart from a foreign service on the same port |
+| `/api/status` | GET | Full snapshot — every server with sessions, pids, warm count, request count, `health`, `lastError`, connected clients |
+| `/api/doctor` | GET | The health checks, as JSON |
+| `/api/events` | GET (SSE) | The same snapshot pushed every 2s — what the dashboard consumes |
+| `/api/logs` | GET (SSE) | Bridge log: replays the last 100 lines, then streams. For anything older, read `bridge.log` next to your config |
+| `/admin/recycle/<name>` | POST | Restart a server's processes. Omit `<name>` to recycle everything |
+| `/admin/reload` | POST | Flush a pending configuration batch, or re-read an externally edited `servers.json`. Only changed definitions are reconfigured |
+| `/admin/servers/<name>/pooling` | POST | Stage enable/disable or batch cancel/undo with admin nonce, bounded input and a matching config revision |
+| `/<name>/mcp` | POST/GET/DELETE | Streamable HTTP transport for that server |
+| `/<name>/sse` | GET | HTTP+SSE transport for that server |
+| `/.well-known/oauth-protected-resource/<name>` | GET | OAuth discovery relayed from the upstream, for HTTP servers where the client authenticates |
+
+Pooling mutations require `x-mcp-pooling-batch: 1`. A staged change returns **HTTP 202** with
+`pending: true`, a batch ID, a private cancel/undo receipt, and the public snapshot. Acceptance
+is not activation. `prewarm.batches` in the snapshot reports bounded pending, applying and
+completed outcomes; it does not expose receipt tokens or full configurations.
+Clients without the batch header are rejected before a change is queued, rather than letting
+an older client report a queued save as already enabled.
+Rich snapshots carry an instance-scoped `snapshotVersion` so a delayed HTTP response or older
+SSE frame cannot replace newer active settings or prematurely expire a batch receipt.
+
+```bash
+# is a server actually running, and who is using it?
+curl -s http://127.0.0.1:8850/api/status | jq '.servers[] | {name, sessions, pids, clients}'
+
+# watch the bridge log
+curl -N http://127.0.0.1:8850/api/logs
+
+# force a restart of one server (nonce is written next to servers.json)
+curl -X POST http://127.0.0.1:8850/admin/recycle/filesystem \
+  -H "x-mcp-nonce: $(cat ~/.mcp-pacemaker/admin.nonce)"
+```
+
+`/admin/*` is guarded twice: the request must arrive on loopback, **and** carry the nonce that the
+bridge writes to `admin.nonce` next to your config at startup. The nonce is new on every start, so
+only same-box tooling that can read that file — the CLI, and the dashboard the bridge itself
+served — can change anything.
+
+The [dashboards](dashboards.md) use these same endpoints. Custom clients written for 1.3.0 need
+the changes in [upgrading from 1.3.0](compatibility.md#upgrading-from-130).

package/docs/install.md

@@ -0,0 +1,52 @@
+# Install details
+
+The [quick start](../README.md#quick-start) has the short version. This page has the full
+requirements, the ordinary-user rule, npm channels and where to install.
+
+Use a maintained **Node.js 22 or 24** release. Node 20 remains a compatibility target but is
+end-of-life, not a recommended secure runtime. The bridge has no npm runtime dependencies;
+the setup CLI and dashboard have their own dependencies.
+
+**Run as an ordinary user.** From 2.1.0 the bridge, supervisor and default upgrades verify the
+caller before any runtime work and refuse elevated or root callers at startup with
+`User-runtime execution refused: …`. On Linux and macOS that includes `root`, which is the
+default user in most container images, so run the bridge as a normal account there. The
+[user-runtime contract](execution-context.md) describes what is checked and why; explicit
+Windows account administration has a separate
+[controller/worker path](account-upgrades.md).
+
+Install the released package from [npm](https://www.npmjs.com/package/mcp-pacemaker).
+Its repository link should point to
+[`girishkvs/mcp-pacemaker`](https://github.com/girishkvs/mcp-pacemaker).
+Use an exact version for a repeatable installation:
+
+```bash
+npm view mcp-pacemaker@2.1.1 version
+npm install -g mcp-pacemaker@2.1.1
+mcp-pacemaker --version
+```
+
+The current line uses the `latest` npm channel; the maintenance line uses `legacy` when that
+channel has been published. Check the actual registry values before choosing a channel:
+
+```bash
+npm view mcp-pacemaker dist-tags --json
+```
+
+GitHub tags and npm publication are separate: a tag does not establish that the same
+version or channel is available on npm, or that its package bytes are identical.
+`@1` and `@2` are version ranges, not the maintained channels. They can select a version
+withdrawn from a channel. `upgrade --self` resolves the installed major's channel and prints
+an exact-version command; it never installs or downgrades anything.
+
+Use a durable installation directory for a long-running service. Do not register autostart
+from an `npx` cache: that cache may be removed later. Bare CLI invocation can enter the setup
+wizard; use `--version` for a read-only installation check.
+
+Windows setup also needs PowerShell 7 (`pwsh`) and Windows Script Host for its launcher.
+Automatic configuration edits need .NET Framework 4.6.2 or newer. The bundled helper is
+unsigned; npm provenance is not Authenticode signing or an application-control allowlist.
+Windows ARM64 is not validated.
+
+For version pairs and downgrades, see [version compatibility](compatibility.md). To replace a
+running installation, see [upgrades and rollback](upgrades.md).

package/docs/operations.md

@@ -0,0 +1,99 @@
+# Commands and operations
+
+Every command, how start and stop behave, durable logs and server health. The
+[README](../README.md) covers setup and everyday use.
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `init [--from source] [--client a,b] [--yes]` | Interactive setup: import one source, wire selected hosts, auto-start, launch |
+| `status` | Bridges, wired hosts, servers, and any server currently failing |
+| `reload` | Re-read `servers.json` into the running bridge without restarting it |
+| `doctor` | Diagnose config, bridge reachability, host wiring |
+| `prewarm [--port N] [--json]` | One view of stdio candidates, pools, shared-child state and measured process starts |
+| `prewarm --enable <server> [--count N]` | Explicitly enable warm slots; `--disable <server>` turns them off |
+| `logs [--follow] [--since 2h] [--server name] [--grep text]` | Read and filter durable logs, including retained rotation |
+| `top` / `dashboard` | Live terminal UI / web dashboard |
+| `plan --client <host>` | Dry run — show exactly what `install` would change |
+| `import --from <source>` | Build `~/.mcp-pacemaker/servers.json` from one supported JSON host config |
+| `install --client <host> [--port N]` | Wire one host (its own `--port` gives it its own bridge) |
+| `emit --client <host>` | Print the config entries without writing anything |
+| `start` / `stop` | Start or stop bridges (`--port` for one, else all) |
+| `upgrade --to <version> [--plan] [--yes]` | Stage and replace one managed installation, including its CLI, preserving port/config/host wiring |
+| `upgrade --to <version> --sxs [--port N]` | Keep the old instance and start an isolated new one; omitted port is OS-assigned |
+| `upgrade --recover` | Resume or roll back an interrupted managed replacement from its durable journal |
+| `upgrade --fix-legacy-access [--plan] [--yes]` | Administrator terminal, Windows: one-time fix for a 1.3 install set up as administrator; changes only that task's run-as user entry and the owner of its `bin\cli.mjs` |
+| `[--instance <directory>]` | Select one installation when discovery finds several; valid before or after the command |
+| `upgrade [--self]` | Legacy host repair; `--self` still prints same-major installation guidance only |
+| `update-check [--json]` | Compare the installed version with its maintained npm channel |
+| `uninstall` | Stop managed bridges, remove auto-start, restore available host-file `.bak` copies; native entries are not restored |
+
+> Package installation alone does not upgrade a running backend. Use explicit `upgrade --to`
+> for managed replacement. Bare `upgrade` retains the older host-repair behavior.
+
+> On start, pacemaker **probes the port**: it *adopts* an existing pacemaker bridge and *refuses to collide* with a foreign service (the wizard offers another port).
+
+For a supervisor created by these patch releases, `stop --port N` verifies the matching
+installation/configuration identity, waits for shutdown, and holds managed autostart until an
+explicit `start --port N`. Normal OS shutdown does not create that hold. Use the matching
+installation's CLI. Older or directly launched bridges have no managed stop record and are
+refused rather than reported as stopped; disable their OS autostart and verify shutdown first.
+
+On Linux/macOS the control socket lives beside the configuration, independent of `TMPDIR`.
+Its complete path must fit within 103 UTF-8 bytes. `install` and `init` check this before
+changing configuration or autostart; use a shorter configuration location rather than
+relying on an implicit socket-location fallback.
+
+Isolated and pooled stdio servers support HTTP+SSE (`/<name>/sse`) and Streamable HTTP
+(`/<name>/mcp`). Shared mode requires Streamable HTTP.
+
+Host-file `.bak` backups and what `uninstall` restores are described under
+[Uninstall](../README.md#uninstall) in the README. Managed upgrades, `--sxs` and `--instance`
+are described in [upgrades and rollback](upgrades.md).
+
+## Reading durable logs
+
+```sh
+mcp-pacemaker logs --since 2h --server filesystem
+mcp-pacemaker logs --follow --grep timeout
+mcp-pacemaker logs --config /path/to/servers.json --since 2026-09-07T12:00:00Z
+```
+
+`logs` reads `bridge.log.1` then `bridge.log` beside the selected config, including when
+the bridge is stopped. `--since` accepts durations in seconds/minutes/hours/days or an ISO
+timestamp with timezone. `--server` matches the exact log-header server name; `--grep` is
+a case-insensitive literal match, not a regular expression. Matching multiline records retain
+their header and context.
+
+`--follow` handles complete new lines, split UTF-8 writes, truncation and rollover until
+interrupted. It warns if rotation has already discarded an unread generation. Only retained
+history is available; it cannot recover logs the bridge has deleted. Individual lines over
+1 MiB fail explicitly rather than being silently truncated.
+
+## Server health
+
+Every server carries a health verdict in `/api/status`, `doctor`, `top` and the dashboard:
+
+| State | Meaning |
+|---|---|
+| `ok` | The last request to this server succeeded |
+| `failing` | Recent requests are failing, with a count of how many in a row |
+| `unknown` | Nothing has called it yet |
+
+This is passive and free — it is derived from traffic the bridge is already proxying. A JSON-RPC
+error *from* the server counts as healthy (it answered); a 401/403, a 5xx, a spawn failure or a
+non-zero exit counts as failing, and the state clears the moment a request succeeds again.
+
+A server nobody calls stays `unknown` forever, which is honest but not much help if its credential
+quietly expires overnight. `MCP_HEALTH_INTERVAL_MS` adds a periodic probe for HTTP servers so they
+get a verdict without waiting for a client:
+
+```bash
+MCP_HEALTH_INTERVAL_MS=300000 mcp-pacemaker start    # probe every 5 minutes
+```
+
+It is off by default because a probe is a real request to somebody else's service. Set
+`"healthIntervalMinutes": 0` on a server to exclude just that one, or a number to give it its own
+interval. stdio servers are not probed: a probe would mean spawning a process, which costs more
+than the request it is meant to pre-empt.