mcp-pacemaker 1.3.1 → 2.0.2

package/README.md

@@ -26,58 +26,42 @@ is separate planned work.
 
 ## Quick start
 
-This README describes **1.3.x legacy behavior**. New installations should use the current
-[2.0.x documentation](https://github.com/girishkvs/mcp-pacemaker/blob/v2.0.1/README.md).
-See the [support policy](SECURITY.md#supported-versions) for the legacy maintenance window.
-
-Use a maintained **Node.js 22 or 24** release; see [installation requirements](#install)
-before setup. `2.0.1` is available from the official npm package linked above.
-
-The compatibility checks cover **1.3.0 / 2.0.0** and the **1.3.1 / 2.0.1** patch pair.
-This describes tested version pairs, not npm publication status.
-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.
+Install **mcp-pacemaker 2.0.2** 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.
 
 ```bash
-# Current line for new installations:
-npm install -g mcp-pacemaker@2.0.1
+npm install -g mcp-pacemaker@2.0.2
 mcp-pacemaker --version
 ```
 
-The version check prints `2.0.1` and does not run setup. Before setup, have a readable
-JSON host configuration containing server definitions, or prepare
-[`~/.mcp-pacemaker/servers.json`](#serversjson). Import sources are `vscode`, `cursor`,
-`claude` (Claude Desktop), `copilot-cli` and `gemini`. Codex and Claude Code are wiring
-destinations, not supported import sources.
+The version check prints `2.0.2` without running setup.
+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 start interactive setup:
+Then run interactive setup:
 
 ```bash
 mcp-pacemaker init
 ```
 
-`init` does the setup:
-
-1. **detects** every MCP host you have installed — editors and CLIs,
-2. **imports one source host** into `~/.mcp-pacemaker/servers.json`, or reuses that file if it already exists,
-3. asks for confirmation, then **wires** the selected hosts to the bridge,
-4. **registers** OS auto-start so the bridge returns after a reboot,
-5. **starts** the bridge and prints what it wired.
+`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.
 
 **Setup changes local configuration and auto-start.** Importing can create or update
-`~/.mcp-pacemaker/servers.json` before the wiring confirmation. To inspect host changes,
-use the manual import/plan steps below before running `install`. Existing JSON/TOML host
-files get a `.bak` before replacement; Claude Code is configured through its native CLI.
-Keep your own protected configuration backup, especially before repeating setup.
+`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.
 
-`--from` selects the import source; `--client` selects wiring destinations. For example,
-`mcp-pacemaker init --from vscode --client codex` imports VS Code's server definitions and
-wires Codex. Without `--from`, setup prefers the first detected JSON host when importing;
-it does not merge every detected host. Omit `--yes` when you want the confirmation prompt.
+`--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     # status without entering first-run setup
@@ -169,16 +153,15 @@ the setup CLI and dashboard have their own dependencies.
 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).
-For new installations, use the current line rather than this branch's legacy save behavior:
+Use an exact version for a repeatable installation:
 
 ```bash
-npm install -g mcp-pacemaker@2.0.1
+npm install -g mcp-pacemaker@2.0.2
 mcp-pacemaker --version
 ```
 
 The current line uses the `latest` npm channel; the maintenance line uses `legacy` when that
-channel has been published. Before deliberately choosing legacy behavior, check that channel
-and choose its exact published version:
+channel has been published. Check the actual registry values before choosing a channel:
 
 ```bash
 npm view mcp-pacemaker dist-tags --json
@@ -197,14 +180,28 @@ 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. Legacy automatic edits still fail closed when the caller
-cannot read the audit policy; this patch does not adopt 2.x Windows save behavior.
+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 |
@@ -295,7 +292,18 @@ 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; **Undo** restores the prior config only if no intervening edit has occurred.
+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:
 
@@ -303,20 +311,27 @@ The same controls are available without a browser:
 mcp-pacemaker prewarm --port 8791
 mcp-pacemaker prewarm --port 8791 --enable filesystem --count 2
 mcp-pacemaker prewarm --port 8791 --disable filesystem
-# An applied change prints its own --server / --undo command.
+# 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. Config writes preserve unrelated JSON and permissions, create `.bak`, and require
-a matching content revision. Conflicts are shown rather than retried over someone else's edit.
-Config remains strict JSON, not JSONC.
-
-On Windows, automatic edits require readable audit policy as well as ordinary file access.
-If security cannot be verified or preserved, the action is refused before config data is written;
-the bridge does not elevate itself. Existing sessions keep running. Configuration writes run in
-a serialized worker so permission inspection does not block MCP traffic.
+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
@@ -324,11 +339,36 @@ starting PowerShell or compiling code on each write. Automatic edits require .NE
 integrity metadata are [included in the package](tools/windows-security-helper/README.md).
 Windows ARM64 execution is not yet validated.
 
-Pooling writes have a nine-second budget, including queueing and permission inspection.
-Expired or cancelled work cannot start a file replacement. A replacement already in progress
-can finish after the deadline: the action reports an unknown or late-committed outcome, and
-the bridge reloads the saved configuration. It never automatically retries or claims that a
-timed-out write was rolled back. Reread the settings before taking another action.
+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.
+
+### 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.
 
@@ -434,7 +474,7 @@ than the request it is meant to pre-empt.
 ## HTTP API
 
 Everything the dashboards show is plain HTTP on the same loopback port, so you can script it.
-Read endpoints need no auth; the one state-changing endpoint requires a nonce.
+Read endpoints need no auth; administrative writes require a nonce.
 
 | Endpoint | Method | Returns |
 |---|---|---|
@@ -444,12 +484,21 @@ Read endpoints need no auth; the one state-changing endpoint requires a nonce.
 | `/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 | Re-read `servers.json`. Only servers whose definition changed are restarted |
-| `/admin/servers/<name>/pooling` | POST | Explicit enable/disable/undo with admin nonce, bounded input and a matching config revision |
+| `/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}'
@@ -609,6 +658,12 @@ It is not scoped to one port; review [replacement and rollback](#replacing-or-ro
 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
 
 - [CHANGELOG.md](CHANGELOG.md) — release notes

package/SECURITY.md

@@ -44,30 +44,40 @@ so a few properties matter more than usual:
   buttons and the equivalent CLI actions require the admin nonce. Browser writes also require
   a matching Origin when provided. Only `sharing` and `minWarm` can be changed; commands,
   environment and auth settings are not accepted. Requests are bounded to 4 KiB.
-  Edits require a content revision, preserve unrelated JSON, keep a backup and replace the file
-  atomically. Undo restores the previous bytes only while that revision is still current.
-  These checks detect stale clients and observed editor changes; a non-cooperating external
-  writer can still race the final filesystem check/rename because portable filesystem CAS
-  is unavailable. Do not edit the file concurrently with an admin action.
-- **Timeout is not proof of rollback.** Pooling operations have a nine-second budget and
-  shared cancellation before file-replacement ownership. Once replacement has started, it
-  can finish after cancellation or timeout. Uncertain and late-committed outcomes are reported
-  explicitly; saved state is reloaded, including after worker failure with config watching off.
-  Reconciliation failures are logged, not treated as success. Operations are never replayed,
-  and a failed worker refuses subsequent writes until the bridge restarts.
-- **Config backups and Undo contain config data.** `servers.json.bak` has the previous config
-  and is protected like the source file, including its Windows DACL. Temporary files are given
-  the same permissions before data is written. Bounded in-memory Undo records can include
-  credential-bearing configuration; they are not returned to the browser or written elsewhere.
-- **Windows timestamp changes are not permission changes by themselves.** Automatic writes
-  capture native non-audit security sections, audit policy and file attributes. A changed
-  timestamp is accepted only when that verified state, content and file identity still match.
-  Unreadable audit policy is refused before staging; security that cannot be preserved on both
-  replacement and backup files is also refused. No automatic elevation or security-policy
-  changes are performed. The built-in audit-read API uses only rights assigned to the account.
-  Inspection uses the bundled own-source .NET Framework helper, with no runtime compilation,
-  download or PowerShell fallback. Build metadata checks source/binary consistency; it is not
-  code signing or protection against replacement of the entire package.
+  Edits require a content revision and accumulate in a complete pending copy, preserving
+  unrelated JSON. Five seconds after the last accepted change, reload validates and flips the
+  files. HTTP 202 means staged, not applied. A batch-capable client header is required so an
+  older client cannot mistake acceptance for activation. Cancel and Undo affect a whole batch;
+  stale receipts cannot overwrite intervening active-file edits.
+- **File flipping is recoverable, not an atomic two-file exchange.** The original is retained
+  as the previous file. Destination placement must not overwrite an unexpected contender.
+  Recovery uses validated transaction state and object/content checks, not blind renames or
+  deletion of unknown files. There can be a brief absent-active-path interval between moves.
+  These checks are not a universal filesystem compare-and-swap guarantee; avoid concurrent
+  manual edits during activation.
+- **Timeout is not proof of rollback.** Staging and commit operations have bounded execution
+  budgets; the acknowledged debounce wait is separate. Once a commit starts, it can finish
+  after cancellation or timeout. Failed outcomes distinguish not-committed, committed and
+  unknown states. Reconciliation failures are surfaced, not treated as success, and uncertain
+  writes are never replayed automatically.
+- **Pending files, previous files and Undo contain config data.** Complete copies must not
+  broaden access to credential-bearing bytes. The retained original keeps its original
+  security metadata. Bounded Undo records are internal; public batch summaries contain only
+  status and requested pooling settings. Receipt tokens are delivered only in authorized
+  responses, not broadcast in snapshots.
+- **Windows saves do not require audit-read privilege.** New copies use directory-inherited
+  auditing. Explicit per-file audit rules are not guaranteed to carry forward to the new active
+  copy, and the UI displays this as a non-blocking notice. This is not a claim that custom rules
+  were detected or that the complete original security descriptor was cloned.
+  Ordinary data-access restrictions and supported integrity protections must be established
+  before writing candidate contents. Source write denial cannot be bypassed using parent
+  directory replacement rights. Unsupported protections are refused rather than weakened.
+  A source owner matching the caller's user or token default owner is retained. Other owners
+  require the existing checked transfer to the caller's user; source write access is still
+  required in either case.
+  The bundled own-source helper does not elevate the bridge, change account privileges, compile
+  at runtime, download code or use a PowerShell fallback. Build metadata checks consistency,
+  not code signing or protection against replacement of the entire package.
 - **Shared mode is not a user-security boundary.** It is opt-in for stateless tools with one
   common credential context. Only a tools capability derived from the real upstream is exposed;
   unsupported client capabilities and protocol methods fail explicitly. IDs, progress,

package/bin/mcp-bridge.mjs

@@ -34,9 +34,10 @@ import { homedir } from 'node:os';
 import { createInterface } from 'node:readline';
 import { checkServerPaths, checkReservedName } from './config-checks.mjs';
 import { ServerMetrics } from './server-metrics.mjs';
-import { MAX_MIN_WARM } from './pooling-config.mjs';
-import { PoolingConfigWriter } from './pooling-writer.mjs';
+import { MAX_MIN_WARM, hasPoolingTransaction, recoverPoolingConfig } from './pooling-config.mjs';
+import { PoolingBatches } from './pooling-batches.mjs';
 import { POOLING_BUDGET_MS } from './pooling-execution.mjs';
+import { poolingTrace } from './pooling-trace.mjs';
 import { SharedSessionManager, SHARED_DEFAULTS } from './shared-sessions.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -47,7 +48,8 @@ const getArg = (name, def) => {
 };
 
 const HOME = resolve(homedir(), '.mcp-pacemaker');
-const defaultConfig = existsSync(resolve(process.cwd(), 'servers.json'))
+const localConfig = resolve(process.cwd(), 'servers.json');
+const defaultConfig = existsSync(localConfig) || hasPoolingTransaction(localConfig)
   ? resolve(process.cwd(), 'servers.json')
   : resolve(HOME, 'servers.json');
 const CONFIG = resolve(process.cwd(), getArg('--config', defaultConfig));
@@ -58,12 +60,21 @@ const VERSION = (() => { try { return JSON.parse(readFileSync(resolve(__dirname,
 const BASE_CWD = resolve(getArg('--cwd', dirname(CONFIG)));
 
 /** @type {Record<string, any>} */
+if (hasPoolingTransaction(CONFIG)) recoverPoolingConfig(CONFIG);
 const servers = JSON.parse(readFileSync(CONFIG, 'utf8'));
-const poolingConfig = new PoolingConfigWriter(CONFIG);
+const poolingConfig = new PoolingBatches({
+  configPath: CONFIG,
+  reload: reloadConfig,
+  revision: () => createHash('sha256').update(lastConfigText ?? '').digest('hex'),
+  notify: publishSnapshot,
+  captureSnapshot: richSnapshot,
+  onError: (error) => log(`pooling reload failed (${error.code || 'IO_ERROR'}); reread batch status`),
+});
 
 /* ----------------------------- dashboard backbone --------------------------- */
 const startedAt = Date.now();
 const instanceId = randomUUID();
+let snapshotVersion = 0;
 const serverMetrics = new ServerMetrics();
 const ADMIN_NONCE = randomUUID();
 const NONCE_FILE = resolve(dirname(CONFIG), 'admin.nonce');
@@ -185,8 +196,20 @@ function richSnapshot() {
   // breached. Report the number the cap actually counts alongside it.
   for (const s of sessions.values()) { const b = byName[s.name]; if (b) { b.sessions++; if (s.child?.pid) b.pids.push(s.child.pid); } }
   for (const s of httpSessions.values()) { const b = byName[s.name]; if (b) { b.sessions++; b.cappedSessions++; if (s.child?.pid && !b.pids.includes(s.child.pid)) b.pids.push(s.child.pid); if (s.clientInfo && s.clientInfo.name && !b.clients.includes(s.clientInfo.name)) b.clients.push(s.clientInfo.name); } }
-  const prewarm = { revision: createHash('sha256').update(lastConfigText ?? '').digest('hex'), maxWarm: MAX_MIN_WARM };
-  return { ok: true, service: 'mcp-pacemaker', version: VERSION, port: PORT, instanceId, startedAt: new Date(startedAt).toISOString(), prewarm, uptimeSec: Math.round((Date.now() - startedAt) / 1000), sessions: sessions.size + httpSessions.size, restart: restartStatus(), servers: Object.values(byName) };
+  const prewarm = {
+    revision: createHash('sha256').update(lastConfigText ?? '').digest('hex'),
+    maxWarm: MAX_MIN_WARM, ...poolingConfig.snapshot(),
+  };
+  snapshotVersion++;
+  return { ok: true, service: 'mcp-pacemaker', version: VERSION, port: PORT, instanceId, snapshotVersion, startedAt: new Date(startedAt).toISOString(), prewarm, uptimeSec: Math.round((Date.now() - startedAt) / 1000), sessions: sessions.size + httpSessions.size, restart: restartStatus(), servers: Object.values(byName) };
+}
+
+function publishSnapshot() {
+  if (!snapClients.size) return;
+  const frame = `data: ${JSON.stringify(richSnapshot())}\n\n`;
+  for (const client of snapClients) {
+    try { client.write(frame); } catch { /* disconnected */ }
+  }
 }
 
 function prewarmingState(name) {
@@ -298,9 +321,20 @@ function handleAdmin(url, req, res) {
     return;
   }
   if (req.method === 'POST' && parts[1] === 'reload') {
-    const r = reloadConfig('admin request');
-    res.writeHead(r.ok ? 200 : 400, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify(r));
+    poolingConfig.reloadNow().then((result) => {
+      if (res.destroyed) return;
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ...result, snapshot: richSnapshot() }));
+    }).catch((error) => {
+      if (res.destroyed) return;
+      res.writeHead(error.statusCode ?? 500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        ok: false, error: error.statusCode ? error.message : 'Unable to reload the saved config.',
+        code: error.statusCode ? error.code : 'RELOAD_FAILED',
+        ...(error.commitState ? { commitState: error.commitState } : {}),
+        snapshot: richSnapshot(),
+      }));
+    });
     return;
   }
   if (req.method === 'POST' && parts[1] === 'recycle') {
@@ -314,9 +348,11 @@ function handleAdmin(url, req, res) {
 }
 
 function handlePoolingChange(encodedName, req, res) {
+  let trace;
   const reply = (status, body) => {
     if (res.destroyed ||
         res.writableEnded) return;
+    trace?.record('response', { status });
     res.writeHead(status, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify(body));
   };
@@ -332,6 +368,11 @@ function handlePoolingChange(encodedName, req, res) {
     req.resume();
     return;
   }
+  if (req.headers['x-mcp-pooling-batch'] !== '1') {
+    reply(409, { error: 'Reload the dashboard or update the CLI before changing pooling settings.' });
+    req.resume();
+    return;
+  }
   const chunks = [];
   let bytes = 0;
   let rejected = false;
@@ -339,18 +380,10 @@ function handlePoolingChange(encodedName, req, res) {
   const execution = {
     signal: controller.signal,
     deadline: process.hrtime.bigint() + BigInt(POOLING_BUDGET_MS) * 1000000n,
-    onLateSettlement: ({ error, committed, commitStarted }) => {
-      if (error &&
-          error.code !== 'WRITER_CANCELLED' &&
-          error.code !== 'WRITER_DEADLINE') {
-        log(`pooling operation settled without a normal result (${error.code}); reread the config`);
-      }
-      if (!committed &&
-          !commitStarted) return;
-      const reloaded = reloadConfig('pooling commit settled without a normal result');
-      if (!reloaded.ok) log('pooling commit settled but reload failed; reread the config');
-    },
   };
+  trace = poolingTrace.operation(execution.deadline);
+  execution.trace = trace;
+  trace?.record('request-start');
   const bodyTimer = setTimeout(() => {
     rejected = true;
     chunks.length = 0;
@@ -380,6 +413,7 @@ function handlePoolingChange(encodedName, req, res) {
     chunks.push(chunk);
   });
   req.on('end', async () => {
+    trace?.record('body-end', { bytes });
     clearTimeout(bodyTimer);
     if (rejected) return;
     let body;
@@ -399,21 +433,16 @@ function handlePoolingChange(encodedName, req, res) {
       return;
     }
     try {
-      const result = Object.hasOwn(body, 'undoId')
-        ? await poolingConfig.undo({ ...body, name }, execution)
-        : await poolingConfig.apply({ ...body, name }, execution);
-      const reloaded = reloadConfig('pooling action');
-      if (!reloaded.ok) {
-        log(`[${name}] pooling settings saved but reload failed`);
-        reply(500, { error: 'Settings were saved, but could not be activated. Reread the config before retrying.', revision: result.revision });
-        return;
-      }
-      log(`[${name}] pooling ${Object.hasOwn(body, 'undoId') ? 'undo' : result.mode} applied`);
-      reply(200, { ...result, snapshot: richSnapshot() });
+      const result = await poolingConfig.stage({ ...body, name }, execution);
+      log(`[${name}] pooling ${result.pending ? 'batch staged' : result.cancelled ? 'batch cancelled' : 'unchanged'}`);
+      reply(result.pending ? 202 : 200, result);
     } catch (error) {
       const status = Number.isInteger(error.statusCode) ? error.statusCode : 500;
       log(`pooling action rejected (${error.code || 'IO_ERROR'})`);
-      reply(status, { error: error.statusCode ? error.message : 'Unable to apply pooling settings.' });
+      reply(status, {
+        error: error.statusCode ? error.message : 'Unable to stage pooling settings.',
+        ...(error.commitState ? { commitState: error.commitState } : {}),
+      });
     }
   });
 }
@@ -435,7 +464,7 @@ function handleUi(pathname, res) {
 }
 
 // Push snapshots to /api/events subscribers on an interval.
-setInterval(() => { if (!snapClients.size) return; const p = `data: ${JSON.stringify(richSnapshot())}\n\n`; for (const c of snapClients) { try { c.write(p); } catch { /* gone */ } } }, 2000).unref();
+setInterval(publishSnapshot, 2000).unref();
 
 /* ------------------------------ pluggable auth ------------------------------ */
 const tokenCache = new Map(); // key -> { value, exp }
@@ -619,6 +648,8 @@ function killTree(child, sync = false) {
     child.detach();
     return;
   }
+  if (child.exitCode != null ||
+      child.signalCode != null) return;
   // Teardown we initiated. taskkill /F reports exit code 1, so without this every recycle,
   // idle reap and session close would be recorded as a crash.
   child.__bridgeKilled = true;
@@ -1427,22 +1458,36 @@ let lastConfigText = (() => { try { return readFileSync(CONFIG, 'utf8'); } catch
 function reloadConfig(reason) {
   let text;
   try { text = readFileSync(CONFIG, 'utf8'); }
-  catch (e) { return { ok: false, error: `cannot read ${CONFIG}: ${e.message}` }; }
+  catch {
+    return { ok: false, statusCode: 500, code: 'CONFIG_READ_FAILED',
+      publicError: 'Unable to read the saved configuration.' };
+  }
   if (text === lastConfigText) return { ok: true, unchanged: true, added: [], removed: [], changed: [], restarted: 0 };
 
   // An invalid file must never take working servers down — a half-written save from an editor
   // looks exactly like this. Keep serving what is already in memory and report the problem.
   let next;
   try { next = JSON.parse(text); }
-  catch (e) { log(`config reload rejected: invalid JSON (${e.message})`); return { ok: false, error: `invalid JSON: ${e.message}` }; }
-  if (!next || typeof next !== 'object' || Array.isArray(next)) {
+  catch {
+    log('config reload rejected: invalid JSON');
+    return { ok: false, statusCode: 400, code: 'INVALID_CONFIG_JSON',
+      publicError: 'Saved config contains invalid JSON.' };
+  }
+  if (!next ||
+      typeof next !== 'object' ||
+      Array.isArray(next)) {
     log('config reload rejected: top level must be an object of server definitions');
-    return { ok: false, error: 'top level must be an object of server definitions' };
+    return { ok: false, statusCode: 400, code: 'INVALID_CONFIG_ROOT',
+      publicError: 'Config top level must be an object of server definitions.' };
   }
-  for (const [n, d] of Object.entries(next)) {
-    if (!d || typeof d !== 'object' || (!d.command && !d.url)) {
-      log(`config reload rejected: "${n}" has neither "command" nor "url"`);
-      return { ok: false, error: `server "${n}" has neither "command" nor "url"` };
+  for (const d of Object.values(next)) {
+    if (!d ||
+        typeof d !== 'object' ||
+        (!d.command &&
+         !d.url)) {
+      log('config reload rejected: a server has neither "command" nor "url"');
+      return { ok: false, statusCode: 400, code: 'INVALID_SERVER_DEFINITION',
+        publicError: 'A server definition has neither "command" nor "url".' };
     }
   }
 
@@ -1469,7 +1514,11 @@ if (process.env.MCP_CONFIG_WATCH !== '0') {
     try {
       watcher = watch(CONFIG, () => {
         clearTimeout(timer);
-        timer = setTimeout(() => { reloadConfig('file changed'); rearm(); }, 300);
+        timer = setTimeout(() => {
+          poolingConfig.reloadSaved('file changed')
+            .catch(() => log('config watcher could not reload the saved configuration'))
+            .finally(rearm);
+        }, 300);
       });
       watcher.unref?.();
     } catch { /* watching is best effort; /admin/reload still works */ }