mcp-pacemaker 2.0.1 → 2.1.0

package/README.md

@@ -1,6 +1,17 @@
 # mcp-pacemaker
 
-**Keep your MCP servers alive across editor restarts, reboots, and token expiry.** The long-running bridge is dependency-free; a small CLI (commander · clack · picocolors) handles setup.
+**A local process supervisor and transport bridge for your MCP servers.** Manage server
+lifetime outside your editor or CLI, with opt-in pre-warming and compatible session sharing.
+The long-running bridge has no third-party runtime dependencies; the setup CLI and dashboards
+have their own dependencies.
+
+[Install from npm](https://www.npmjs.com/package/mcp-pacemaker) ·
+[Report a problem](https://github.com/girishkvs/mcp-pacemaker/issues) ·
+[Release notes](https://github.com/girishkvs/mcp-pacemaker/releases)
+
+> This README describes **2.1.0**. Verify its npm availability before installing;
+> a source branch or GitHub tag is not proof of publication.
+> See the [release changes](CHANGELOG.md).
 
 MCP hosts — editors (VS Code, Cursor, Claude Desktop) **and** CLIs (Claude Code, Copilot CLI,
 Codex, Gemini) — run stdio MCP servers as child processes. When the host restarts, crashes, or
@@ -19,36 +30,53 @@ is separate planned work.
 
 ## Quick start
 
-This README describes **2.0.x**. The current line is 2.x; the explicit maintenance line is
-1.3.x. See the [legacy documentation](https://github.com/girishkvs/mcp-pacemaker/blob/v1.3.1/README.md)
-for its immediate-save behavior and [support policy](SECURITY.md#supported-versions).
+Install **mcp-pacemaker 2.1.0** from npm. Use a maintained **Node.js 22 or 24**
+release; Windows also needs PowerShell 7 and Windows Script Host.
+See [installation requirements](#install) before setup.
 
-Compatibility gates distinguish immutable **1.3.0 / 2.0.0** from the **1.3.1 / 2.0.1** candidates.
-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; other minor versions are not covered.
+```bash
+npm view mcp-pacemaker@2.1.0 version
+npm install -g mcp-pacemaker@2.1.0
+mcp-pacemaker --version
+```
+
+The version check prints `2.1.0` without running setup.
+
+> **Run it as an ordinary user.** From 2.1.0 the bridge, supervisor and default upgrades
+> refuse a privileged caller *at startup* — a non-administrator terminal on Windows and a
+> **non-root** session on Linux/macOS, including the default `root` user in most containers.
+> A refused start prints `User-runtime execution refused: …`. There is no override; run as a
+> normal user instead. See the [user-runtime contract](docs/execution-context.md).
+
+Before setup, have a readable JSON host configuration containing server definitions, or
+prepare [`~/.mcp-pacemaker/servers.json`](#serversjson). Supported import sources are
+`vscode`, `cursor`, `claude` (Claude Desktop), `copilot-cli` and `gemini`.
+Codex and Claude Code are wiring destinations, not import sources.
+
+Then run interactive setup:
 
 ```bash
-npm i -g github:girishkvs/mcp-pacemaker#v2.0.1
 mcp-pacemaker init
 ```
 
-That one command does the whole setup:
+`init` detects supported hosts, imports **one source host** (or reuses `servers.json`),
+asks for confirmation before wiring the selected hosts, registers OS auto-start and
+starts the bridge. Reload or restart the selected hosts afterward.
 
-1. **detects** every MCP host you have installed — editors and CLIs,
-2. **imports** the servers already configured in them into `~/.mcp-pacemaker/servers.json`,
-3. **rewrites** each host's config to point at the bridge (backing every file up first),
-4. **registers** OS auto-start so the bridge returns after a reboot,
-5. **starts** the bridge and prints what it wired.
+**Setup changes local configuration and auto-start.** Importing can create or update
+`servers.json` before the wiring confirmation. Existing JSON/TOML host files get a `.bak`
+before replacement; native Claude Code registrations do not. Keep your own protected
+configuration backup, especially before repeating setup.
 
-Nothing is written before you see it: `mcp-pacemaker plan --client <host>` shows the exact
-changes, every config write leaves a `.bak`, and `mcp-pacemaker uninstall` restores them.
+`--from` chooses the import source; `--client` chooses wiring destinations. For example,
+`mcp-pacemaker init --from vscode --client codex` imports VS Code's definitions and wires
+Codex. Without `--from`, setup prefers the first detected JSON host; it does not merge
+every detected host. Omit `--yes` to keep the confirmation prompt.
 
-After setup, bare `mcp-pacemaker` reports status:
+Check the running bridge:
 
 ```bash
-mcp-pacemaker            # status: bridges, wired hosts, servers
+mcp-pacemaker status     # status without entering first-run setup
 mcp-pacemaker top        # live terminal dashboard
 mcp-pacemaker doctor     # diagnose config, reachability, wiring
 ```
@@ -56,12 +84,12 @@ mcp-pacemaker doctor     # diagnose config, reachability, wiring
 <details>
 <summary>Prefer to drive it yourself? The same steps, one at a time</summary>
 
-Every command takes any host id — `vscode`, `cursor`, `claude`, `claude-code`, `copilot-cli`,
-`codex`, `gemini` (see [Supported hosts](#supported-hosts)). `--from` / `--client` below are
-just examples; substitute whichever you use.
+`plan`, `install` and `emit` accept any [supported host](#supported-hosts) as a wiring target.
+`import --from` accepts the five JSON import sources listed above. Run import first unless
+you already have `servers.json`; `plan` needs that file.
 
 ```bash
-mcp-pacemaker import  --from <host>            # build servers.json from an existing host
+mcp-pacemaker import  --from <source>          # write servers.json from one JSON host config
 mcp-pacemaker plan    --client <host>          # dry run: show what install would change
 mcp-pacemaker install --client <host>          # wire one host (--port N gives it its own bridge)
 mcp-pacemaker start                            # start the bridge
@@ -81,23 +109,32 @@ them in.
 
 </details>
 
-## Why not just use supergateway / mcp-proxy?
+## Which process-sharing mode?
 
-Those are great, mature stdio↔SSE bridges. `mcp-pacemaker` targets a different problem —
-*durable local hosting on a dev workstation* — and adds things they don't:
+Sharing a bridge does not automatically share a server process.
 
-| | supergateway | mcp-proxy | **mcp-pacemaker** |
-|---|---|---|---|
-| stdio → SSE | ✅ | ✅ | ✅ |
-| Streamable HTTP | ✅ | ✅ | ✅ |
-| Dependencies | npm tree | PyPI tree | **bridge: zero** · tiny setup CLI |
-| Process supervision | ❌ | ❌ | ✅ |
-| OS auto-start (logon / unlock / boot) | ❌ | ❌ | ✅ (Windows / macOS / Linux) |
-| Dynamic per-request token (from a CLI, auto-refresh) | ❌ (static) | ❌ (static/OAuth2) | ✅ |
-| Sessions survive the bridge restarting | ❌ | ❌ | ✅ |
-| Scheduled recycle for interactively-authenticated servers | ❌ | ❌ | ✅ |
-| One-command import + client wiring | ❌ | ❌ | ✅ |
-| Web + terminal dashboard, HTTP API | ❌ | ❌ | ✅ |
+| Mode | Process behavior | Use when |
+|---|---|---|
+| `isolated` (default) | One child per session | The server needs per-client workspace, account or conversation state |
+| `pool` (opt-in) | Pre-started, uninitialized children; each is assigned exclusively to one session | Startup is slow but sessions must remain separate |
+| `shared` (opt-in) | One initialized child for compatible sessions | Tools are stateless, inputs are explicit and the credential context is common |
+
+Shared clients must send identical initialization parameters, including `clientInfo`, and
+empty client capabilities. It is not automatic cross-editor sharing. See
+[shared-mode limits](#shared-mode) before enabling it.
+
+## Choosing a transport tool
+
+Documentation checked September 27, 2026; this is a use-case guide, not a feature benchmark.
+
+| Tool | Consider it when |
+|---|---|
+| [Supergateway](https://github.com/supercorp-ai/supergateway) | You want command-line conversion between stdio and HTTP/SSE/WebSocket transports |
+| [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) | You want a Python-based adapter between local stdio clients/servers and remote MCP transports |
+| **mcp-pacemaker** | You want workstation process supervision, host wiring, auto-start, lifecycle diagnostics and explicit isolation/pooling/sharing policies |
+
+These projects have overlapping capabilities. Reconnecting to a fresh server is not recovery
+of arbitrary application state, and a transport bridge is not a sandbox for untrusted tools.
 
 ## Supported hosts
 
@@ -125,26 +162,34 @@ Use a maintained **Node.js 22 or 24** release. Node 20 remains a compatibility t
 end-of-life, not a recommended secure runtime. The bridge has no npm runtime dependencies;
 the setup CLI and dashboard have their own dependencies.
 
-GitHub and npm publication are separate. Until the npm release is announced from
-[this repository](https://github.com/girishkvs/mcp-pacemaker/releases), use the pinned GitHub
-release. Do not assume that an npm package with a matching name is this project.
+**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](docs/execution-context.md) describes what is checked and why; explicit
+Windows account administration has a separate
+[controller/worker path](docs/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 i -g github:girishkvs/mcp-pacemaker#v2.0.1
-# Deliberate legacy installation instead:
-npm i -g github:girishkvs/mcp-pacemaker#v1.3.1
+npm view mcp-pacemaker@2.1.0 version
+npm install -g mcp-pacemaker@2.1.0
+mcp-pacemaker --version
 ```
 
-After npm publication, `mcp-pacemaker@latest` selects the current 2.x line and
-`mcp-pacemaker@legacy` selects maintained 1.3.x. Verify the official listing's repository and
-maintainer before installing. For a repeatable installation, choose an exact released 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 i -g mcp-pacemaker@2.0.1
-# Or, deliberately:
-npm i -g mcp-pacemaker@1.3.1
+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.
@@ -158,11 +203,26 @@ Automatic configuration edits need .NET Framework 4.6.2 or newer. The bundled he
 unsigned; npm provenance is not Authenticode signing or an application-control allowlist.
 Windows ARM64 is not validated.
 
+### Version compatibility
+
+This README describes **2.0.x**. 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**
+patch-pair evidence is not transferable to a new release. The selected **1.3.1 / 2.0.2**
+pair 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.
+
 ### Command reference
 
 | Command | What it does |
 |---|---|
-| `init [--client a,b] [--yes]` | **The one you want.** Detect hosts, import, wire, auto-start, launch |
+| `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 |
@@ -171,16 +231,20 @@ Windows ARM64 is not validated.
 | `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 <host>` | Build `~/.mcp-pacemaker/servers.json` from an existing host |
+| `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 [--self]` | Re-wire hosts; `--self` only prints same-major, exact-version installation guidance |
+| `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 |
+| `[--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 the bridge, remove auto-start, restore configs from `.bak` |
+| `uninstall` | Stop managed bridges, remove auto-start, restore available host-file `.bak` copies; native entries are not restored |
 
-> Package installation does not upgrade a running backend. `upgrade` rewires host configuration;
-> it does not replace package files, restart an adopted backend, or update its autostart path.
+> 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).
 
@@ -198,10 +262,234 @@ 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.
 
-`install` writes a `.bak` of your client config before touching it, and `uninstall` restores it.
+`install` backs up an existing JSON/TOML host file to `.bak`; repeating it replaces that backup.
+`uninstall` restores available host-file backups, leaves files without backups as-is, and
+keeps `servers.json`. Native Claude Code registrations are not backed up or automatically
+restored; record their original definitions separately and restore them through Claude Code.
 
 ### Replacing or rolling back a running installation
 
+These managed-upgrade commands require **2.1.0 or newer**.
+Version 2.0.2 does not include them.
+
+Run the bridge, supervisor, default upgrades and recovery as an **ordinary user**:
+a normal, non-administrator terminal on Windows and a non-root session on Linux/macOS.
+The [user-runtime contract](docs/execution-context.md) rejects privileged or
+unverified callers before runtime work, so a replacement does not inherit different
+authority. Read-only plans remain available. Explicit Windows account administration has a separate
+[controller/worker path and qualification requirements](docs/account-upgrades.md).
+
+For a **stable managed instance created by this implementation**:
+
+```bash
+mcp-pacemaker upgrade --to <exact-version> --plan
+mcp-pacemaker upgrade --to <exact-version>
+# Noninteractive confirmation of the displayed local plan:
+mcp-pacemaker upgrade --to <exact-version> --yes
+
+# Keep the existing service and host wiring:
+mcp-pacemaker upgrade --to <exact-version> --sxs
+mcp-pacemaker upgrade --to <exact-version> --sxs --port 9001
+```
+
+`--to` requires canonical stable SemVer, not `latest`, a range, or a Git/file spec.
+Selecting another major is explicit and printed in the plan; it is not a compatibility
+claim. The target must ship the managed admission/readiness protocol. Older targets
+without that protocol are rejected before interruption, including for automatic SxS ports.
+
+Normal upgrades preserve the selected port: `--port` is valid **only with `--sxs`**.
+Without an SxS port, the actual new loopback listener binds port 0 and stays open;
+the OS-selected port is displayed and saved for later starts. The read-only plan says
+“OS-assigned,” not a guessed port. An explicitly requested busy port fails without adoption.
+SxS gets separate config, nonce, logs and session files. It preserves the source working
+directory for relative server commands and does not rewire any host or enable pooling.
+
+When discovery finds multiple instances, use the exact directory printed by setup/upgrade:
+
+```bash
+mcp-pacemaker upgrade --instance <directory> --to <exact-version> --plan
+mcp-pacemaker start --instance <directory>
+mcp-pacemaker stop --instance <directory>
+```
+
+`--instance <directory>` and `--instance=<directory>` work before or after the
+command. Selection is normalized once, including paths with spaces; conflicting
+selectors or port/config overrides are rejected before an action. Text after `--`
+is not interpreted as a selector. An invalid explicit selection never falls back
+to the default instance.
+CLI port options use canonical decimal integers from 1 to 65535; scientific notation, hex,
+signs, surrounding whitespace and zero-padded spellings are rejected before requests.
+
+Selected `start`, `stop`, `reload`, `prewarm`, `status`, `doctor`, `top`, `logs`,
+`dashboard`, version/help, and upgrade commands use the same instance context.
+The TUI's recycle key uses that instance's port **and nonce directory**; logs use
+its config directory. Bare `mcp-pacemaker --instance <directory>` shows status
+even when SxS has no host-wiring state. Host setup/removal commands (`init`,
+`import`, `install`, `uninstall`) are refused with `--instance`; selection alone
+does not authorize rewriting host configuration or changing autostart.
+Generated prewarm Cancel/Undo commands retain the selected instance and config,
+so they resolve the same CLI version and nonce directory. Windows commands use
+an encoded PowerShell launcher with an explicit native argument list to preserve
+spaces, quotes and shell characters; unmanaged `--config` commands remain supported.
+
+The stable per-instance launcher selects checked version directories. Upgrades never
+overwrite a running package or rewrite per-version autostart tasks. The previous selection
+and package are retained. The existing command entry point dispatches to the committed
+version's CLI and its own dependencies: ordinary `--version`, `status`, `update-check`
+and the next `upgrade` use that version. An unfinished activation keeps the previous
+CLI available for recovery; rollback restores that CLI selection. SxS does not change
+the default CLI. Use `--instance <directory>` to select its CLI explicitly.
+
+Target dependencies are resolved into a private lock and restored with npm's archive
+integrity checks before interruption. Both the lock and installed dependency files enter
+the checked version inventory. Target CLI startup and version are checked before quiescing.
+The target archive and resolved CLI dependencies require SHA-512 integrity metadata.
+SHA-1-only or missing integrity information is rejected before interruption; the
+upgrader does not downgrade its checks to accommodate a registry.
+Acquisition uses the configured npm registry, or explicit
+`--registry`, with no registry fallback or global npm changes. Existing npm permissions,
+TLS, release-age policy and URL-prefix mapping remain in effect; lifecycle scripts are
+disabled for acquisition. For npm 12 mirrors, use your approved command-local
+`replace-registry-host` full-URL-prefix mapping back through that registry—not a
+hard-coded mirror URL or public-registry bypass.
+
+Download, archive integrity, package/engine/native-binary checks and an owned packaged
+startup check finish before interruption. Admission then closes and waits up to eight
+seconds for safe work to drain. Open MCP sessions and unresolved config transactions
+currently cause a refusal; close/settle them and retry. No uncertain tool call or failed
+configuration commit is replayed. This is a **short restart**, not socket handoff or
+zero downtime. Clients and dashboard tabs may need a reload.
+
+The supervisor persists admission hold **before** forwarding quiesce. A lost reply,
+failed drain, bridge crash or replacement child does not release it. Only explicit
+resume/recovery or a verified activation opens admission again. Upgrade stop is tied to
+the drained generation; any replacement generation must remain held.
+
+The activation journal blocks unattended starts after an interrupted transition.
+Selection and launch intent are separate durable transitions. A selected target that
+was provably never launched can recover using the exact previous stopped-generation
+receipt. After launch intent, an empty port alone is not shutdown proof.
+Recovery parses bounded instance/journal identities before checking executable
+bytes. It fully verifies and runs the retained recovery CLI, so a damaged or
+missing target file cannot prevent a safe pre-launch rollback. A damaged previous
+package, stale identity or unknown journal still causes a refusal.
+
+| Journal state | Recovery boundary |
+|---|---|
+| Prepared / quiescing | Explicitly resume the matching previous service |
+| Stopping | Reconcile the exact drained generation |
+| Stopped / selecting / selected | Require the previous completed-stop receipt; the target has no launch intent |
+| Launching | Require a new held generation and verified shutdown; no empty-port inference |
+| Rollback-selecting / rollback-selected | Require the durable rollback stop proof before selecting/restarting previous code |
+| Rollback-launching | Require proof for the newly launched previous generation; otherwise refuse |
+| Admitting / admitting-rollback | Admission may have occurred; no automatic rollback |
+| Committed / rolled-back / aborted | No interrupted activation remains |
+
+Automatic rollback is restricted to startup failure before target admission, with
+unchanged configuration bytes, identity and security and verified shutdown. If admission
+may have occurred, recovery refuses rather than overwriting user state.
+
+```bash
+mcp-pacemaker upgrade --recover --instance <directory> --yes
+```
+
+A crash can leave `upgrade.lock`. Recovery does not steal it based on a reusable PID.
+Verify the original upgrader has exited, preserve the journal, and remove only that
+instance's lock before recovery. Keep packages, configuration and transaction files.
+Journal writes are file-flushed and atomically renamed; Windows directory-entry
+durability across power loss is not claimed.
+
+### One-time Windows 1.3 restart migration
+
+The normal `upgrade --to <exact-version>` confirmation also supports the exact known
+**1.3.0 Windows supervisor/launcher and per-user task shape**, with one port in the
+existing install state. Invoke an upgrade-capable CLI from a separate durable package;
+do not overwrite the running 1.3 package first. `--plan` remains read-only.
+
+This transition restarts **Pacemaker, not Windows**. Pause callers before confirming.
+The interactive confirmation states that clients will disconnect and 1.3 cannot drain
+or certify every in-flight HTTP outcome. Zero reported sessions or child PIDs does not
+prove that HTTP calls finished. Ordinary `--yes` and unattended invocation refuse this
+transition; there is no separate maintenance flag and no automatic call replay.
+
+Target package, CLI dependencies, native identities and packaged startup are verified
+before downtime. A separate broker retains handles for the selected supervisor, bridge
+and a bounded set of provably owned descendants. Only the verified selected task is
+held. Stop uses those handles and verifies their exit before starting the held target
+on the same port. It does not use a name/PID kill or assume task disable stopped the
+running supervisor. Configuration, host wiring and port remain unchanged; the existing
+CLI entry dispatches the newly selected managed CLI.
+
+Preparation stays outside managed discovery until the instance identity and recovery
+journal are durable; the prepared directory is then published together. A pre-journal
+I/O failure leaves the old installation discoverable. Failed preparation is retained,
+not guessed safe to delete. A terminal rolled-back/aborted candidate is excluded only
+after its bounded journal and legacy-source binding validate, so damaged target files
+do not prevent retrying the still-running legacy installation.
+
+The task's **resource owner and full security descriptor** are separate from its run-as
+account. Planning and every task operation require owner/group/DACL/SACL/integrity
+inspection through Task Scheduler. If the required security read is denied or unsupported,
+migration refuses before touching the task; it does not enable privileges or elevate.
+Existing-task updates preserve security rather than reassigning its owner: they clear
+only the temporary definition's embedded descriptor, pass no replacement security
+descriptor, disable automatic principal-ACE edits, and verify the complete raw resource
+descriptor again afterward. Protected backups retain the original raw descriptor and XML.
+Restoration requires exact equality of all non-XML registration/security fields and
+Task Scheduler-normalized XML, ignoring only the exact embedded
+`Task/RegistrationInfo/SecurityDescriptor` representation. Raw revision preconditions,
+backups and the actual returned XML/hash are not rewritten; other metadata or XML drift refuses.
+Concurrent or uncertain security changes require inspection, not permission repair.
+The resource owner may be the runtime user or canonical builtin Administrators;
+that does not change the run-as account. Default scope remains **current user**,
+but Windows execution and recovery require a freshly verified ordinary caller
+before staging or mutation; an elevated or unverified caller refuses rather than
+launching a runtime with different authority. Read-only planning is unchanged.
+Explicit original-account administration uses a task-only
+trusted controller and an original-user worker; see
+[account upgrade scope and qualification](docs/account-upgrades.md).
+`--all-users` is explicitly unsupported.
+
+The legacy receipt reports `legacyRootStopVerified`, `observedDescendantsStopped` and
+`treeCompleteness: "unproven"` separately. This is **not** the modern Job Object
+complete-descendant proof. Historical or uncaptured orphan processes cannot be fully
+attributed; they are left untouched and the limitation is reported without claiming an
+orphan count. The new managed runtime contains future children from birth.
+
+Unknown package/task shapes, changed owner/generation/configuration, a failed captured
+process stop, or a foreign listener prevent activation. A foreign listener is never
+stopped. Original code and protected configuration/task backups are retained. A verified
+pre-admission target failure can restore the original CLI and scoped task and verify a
+fresh legacy backend; uncertain launch, registration or admission outcomes require
+explicit recovery. No configuration is deleted or replayed.
+
+| Legacy journal phase | Recovery boundary |
+|---|---|
+| `legacy-prepared` / `legacy-held` | Verify the original generations and unchanged state; restore only the recorded task hold |
+| `legacy-holding` | Task write outcome may be unknown; inspect before recovery |
+| `legacy-stopping` | Read-only captured-generation absence check; an incomplete observed set refuses recovery |
+| `legacy-stopped` | Revalidate partial stop and free port before safe old-version rollback |
+| `legacy-launching` / `legacy-wiring` | Require modern held-target shutdown proof; a closed port alone is insufficient |
+| `legacy-admitting` | Traffic may have entered; no automatic rollback |
+| Legacy rollback intent phases | An interrupted task/CLI/launch outcome is reported as uncertain, not retried blindly |
+| `legacy-rolled-back` / `legacy-aborted` | Original installation remains selected; the staged managed candidate stays dormant |
+
+A killed migration can also leave the profile's `legacy-upgrade/upgrade.lock`.
+Verify that exact upgrader has exited before removing its lock; never steal it by PID
+guessing. Preserve the journal and backup files.
+
+This adapter does not support direct unregistered bridges, other legacy versions,
+multiple legacy ports, Linux/macOS registrations, or legacy-source SxS. Targets must
+declare `legacyRestartProtocol: 1`; older published targets without it refuse before
+legacy downtime.
+
+Managed SxS keeps its own verified package copy as well as separate runtime state.
+If a crash happens during port-0 startup before the port is durably recorded, recovery
+reports an unknown launch outcome rather than marking it safely aborted. Preserve
+that instance and its journal until readiness or shutdown can be verified.
+
+For an older installation requiring a separately verified manual migration:
+
 Do not overwrite a package directory while its supervisor or bridge is running. Workers and
 native helpers can load later, and dashboard assets are read from disk: replacement can mix
 old and new code even when the original process still reports its old version.
@@ -218,7 +506,8 @@ other major there replaces it. Separate ports do not isolate credentials, nonces
 session files: manual side-by-side operation needs separate durable code roots and separate
 configuration directories, plus separate host/HOME state for CLI-managed setup.
 `init/import --config` selects a source host configuration, not an isolated runtime profile.
-There is no package `--profile` or `MCP_HOME` switch. Do not use an unscoped stop/uninstall
+There is no package `--profile` or `MCP_HOME` switch; managed SxS uses explicit instance
+directories instead. Do not use an unscoped stop/uninstall
 operation when another instance must remain running.
 
 ## Dashboards
@@ -607,7 +896,19 @@ See [the shared-session contract](docs/shared-sessions.md) for limits and failur
 ## Uninstall
 
 ```bash
-npx mcp-pacemaker uninstall   # stop bridge, remove auto-start, restore client config from .bak
+mcp-pacemaker uninstall      # use the CLI from the matching installed version
+```
+
+This stops managed bridges, removes auto-start entries and restores available host-file
+backups. It leaves files without backups and native Claude Code registrations unchanged.
+It is not scoped to one port; review [replacement and rollback](#replacing-or-rolling-back-a-running-installation)
+first if another instance must remain running. Do not fetch a different CLI with `npx`
+to remove an existing installation.
+
+After the installed service has been removed successfully, remove the global npm package:
+
+```bash
+npm uninstall -g mcp-pacemaker
 ```
 
 ## Project

package/THIRD_PARTY_NOTICES.txt

@@ -192,7 +192,7 @@ SOFTWARE.
  */
 
 ==============================================================================
-tailwindcss@3.4.19
+tailwindcss@4.3.3
 Declared license: MIT
 
 --- LICENSE ---
@@ -218,33 +218,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
---- lib/css/LICENSE ---
-MIT License
-
-Copyright (c) Nicolas Gallagher
-Copyright (c) Jonathan Neal
-Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
-Copyright (c) Adam Wathan
-Copyright (c) Jonathan Reinink
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
 ==============================================================================
 vite@7.3.6
 Declared license: MIT