mcp-pacemaker 1.3.1

package/docs/shared-sessions.md

@@ -0,0 +1,181 @@
+# Shared stdio sessions
+
+Status: 1.3.0 implementation contract; not a claim that every server is compatible.
+
+## Configuration
+
+Add `"sharing": "shared"` to a stdio definition only after confirming the profile below.
+Use `/<name>/mcp`: classic SSE endpoints explicitly reject shared mode.
+Pooling buttons never enable shared mode or replace an existing shared policy.
+
+| Setting | Default | Purpose |
+|---|---|---|
+| `sharedLingerMs` | 1800000 | Keep the initialized child between compatible sessions. |
+| `sharedDrainTimeoutMs` | 30000 | Maximum drain time before terminating unresolved work. |
+| `sharedRetryDelayMs` | 1000 | Backoff after a failed generation. |
+| `sharedMaxSessions` | 128 | Virtual members plus joining clients per group. |
+| `sharedMaxInFlight` | 8 | Dispatched operations per child. |
+| `sharedMaxQueued` | 32 | Unsent operations waiting for dispatch. |
+| `sharedMaxIds` | 4096 | Retained request IDs per virtual session. |
+| `sharedMaxCursors` | 256 | Retained tools-list cursors per virtual session. |
+| `sharedMaxLineBytes` | 1048576 | Maximum JSON-line size, including translated fields. |
+| `sharedMaxBufferBytes` | 4194304 | Maximum buffered protocol data per stream. |
+
+All settings require bounded integers; invalid values fail explicitly. The bridge's existing
+session cap and request/initialization timeouts also apply. A slot is reserved before waiting
+for shared initialization or the spawn gate. Concurrent resumes of one external session ID
+share one handshake.
+Client and upstream JSON have a maximum depth of 64, counting the root as depth 0.
+An upstream depth violation terminates its generation with explicit failure metadata,
+not an uncaught serializer exception; no business call is replayed.
+
+## Purpose and approval
+
+`sharing: "shared"` reuses one initialized stdio child across compatible virtual HTTP sessions.
+This differs from `pool`: a pooled child is uninitialized and belongs exclusively to its first
+session. Both modes remain opt-in. No latency recommendation enables either mode automatically.
+
+Shared mode is for a stateless-tools profile: tools operate on explicit inputs, the configured
+credential context is common, and the server has no implicit per-client workspace, conversation,
+account or subscription state. Enabling the mode asserts that profile. Matching capabilities
+alone does not prove the implementation is stateless.
+
+The default remains `isolated`. Unsupported clients receive a clear compatibility error before
+their business request is dispatched. There is no silent sharing downgrade, guessed callback
+recipient, or automatic replay on another process.
+
+## Compatibility and initialization
+
+One group per configured server and configuration generation is allowed. Its compatibility key
+contains the complete, canonically ordered initialization parameters and configuration. Preserve
+array order, absent properties and all client identity fields. The JSON-RPC request ID is not
+part of the initialization parameters.
+
+For the first profile:
+
+- Support released protocol versions `2025-03-26`, `2025-06-18` and `2025-11-25`.
+- Require empty client capabilities. Roots, sampling, elicitation, tasks and unknown extensions
+  cannot safely be routed from an arbitrary stdio callback to an individual client.
+- Support `tools/list`, `tools/call` and `ping`.
+- Reject stateful protocol methods, subscriptions, logging changes and task-augmented calls.
+- Do not interpret arbitrary tool argument/result fields as request IDs or state handles.
+- Bind tools-list cursors to their originating virtual session and child generation.
+- Retain the actual upstream protocol version, instructions and implementation metadata.
+  The upstream may negotiate any of the three supported versions.
+- Expose only the upstream's actual `tools` capability, without inventing flags. This
+  explicitly tools-only surface does not advertise optional prompts, resources, logging,
+  completions or tasks even if the upstream supports them. An empty `experimental` object
+  is harmless; unknown or nonempty experimental extensions are incompatible.
+
+Concurrent compatible arrivals share a creation promise installed before awaiting process
+creation. Exactly one upstream `initialize` and one `notifications/initialized` are sent.
+Each virtual session receives the result with its own request ID and must complete its own
+initialized notification before dispatching tools.
+
+An incompatible client does not replace or disturb the established group. Failed initialization
+fails all waiters, removes the failed creation promise, and terminates the candidate. A later
+attempt may start a new group with bounded retry behavior.
+
+## Routing
+
+Use distinct typed keys: integer `1` and string `"1"` are different client IDs.
+
+| Message | Required behavior |
+|---|---|
+| Client request | Translate to a generation-unique upstream ID and retain owner plus original ID. |
+| Child response | Deliver only to its mapped owner, restoring the original ID. |
+| Client progress token | Translate only `_meta.progressToken`; restore it on the owner's progress notifications. |
+| Client cancellation | Translate only that session's request ID. Never cancel another client's request. |
+| Child `ping` | Answer as the bridge peer. It is not a response even if its ID matches an operation. |
+| Other child requests | Reject explicitly; never select the first/recent client or broadcast callbacks. |
+| Tools-list changes | Fan out to members only when the common catalog contract permits it. |
+| Other notifications | Drop unowned logs and unexposed catalog changes with diagnostics. Never broadcast their data; reject unknown extensions. |
+
+Classify messages by category (`method`, `result`, `error`) before consulting ID maps. Unknown
+or late responses must not become notifications. Progress associated with a POST must be
+delivered on its originating POST stream; an unrelated GET stream is not a replacement.
+
+Bound operations, queued work, input lines, retained IDs/cursors and stream buffers. Reject
+overflow explicitly instead of allocating without limit or silently truncating protocol data.
+
+## Virtual child adapter
+
+`bin/shared-sessions.mjs` exports `SharedSessionManager`. It takes:
+
+```js
+{
+  spawn: async (name, definition) => actualChild,
+  kill: (actualChild) => {},
+  onFailure: (name, detail) => {},
+  onInitialized: (name, elapsedMs) => {},
+  onResponse: (name) => {},
+  log: (name, text) => {},
+  initTimeoutMs,
+  requestTimeoutMs
+}
+```
+
+`await manager.acquire(name, definition, initializeParams)` returns an EventEmitter-compatible
+virtual child with `stdin` accepting newline-delimited JSON-RPC, readable `stdout`, the actual
+group `pid`, `exitCode`, `signalCode`, `__spawnedAt`, `__sharedSession: true`, and `detach()`.
+It plugs into the existing Streamable HTTP per-session response parser without spawning again.
+One actual child owns one stdout parser; virtual stdout contains only that session's messages.
+For already-parsed HTTP JSON, use `child.writeMessage(message)`. It applies the same input,
+depth, ID and ownership guards before serialization. Calling it after detachment throws an
+explicit `SHARED_DETACHED` admission error instead of leaving a request waiting indefinitely.
+
+The bridge's process-kill helper must detect a virtual child and detach it instead of killing
+its shared PID. Actual group creation goes through the existing spawn gate and B21 counter.
+Virtual session attachment is not an OS spawn or a cold-initialization sample.
+`onResponse` reports actual upstream responses, not locally generated rejections. Health must
+not classify errors by a numeric JSON-RPC code that an upstream can also legitimately use.
+
+Provide `recycle(name)`, `remove(name)`, `shutdown()` and `inspect(name)` methods. Inspection
+exposes only lifecycle facts such as generation, state, members and unresolved operations.
+
+## Lifetime, drain and credentials
+
+Deleting one session forgets and tombstones only that session. Remove its unsent work and send
+owner-scoped cancellation for dispatched work. Other clients and their operations remain alive.
+The actual child lingers between compatible sessions, bounded by `sharedLingerMs` (default
+30 minutes). Unresolved work prevents idle eviction.
+
+Cancellation is not proof that execution stopped. Retain execution ownership until the
+response arrives or a bounded failure/drain policy terminates the generation.
+
+Recycling marks the generation draining and stops new dispatch to it. Existing work gets a
+bounded opportunity to finish; once drained, terminate promptly rather than waiting for the
+next full recycle interval. A drain deadline fails unresolved work explicitly as potentially
+executed, terminates that generation, and permits a later fresh generation. Never replay those
+business calls. Fence old exit handlers and timers so they cannot delete a replacement.
+
+The server retains its existing credential mechanism. The bridge does not freeze a token in
+the shared initialization, infer renewal from a generic cache, or substitute an auth provider.
+Keep configured credential recycling. A synthetic short-expiry test must show: expired call
+fails unchanged; draining/replacement creates a fresh generation; a new call succeeds; the
+failed call was dispatched once. Real provider renewal still requires its own canary.
+
+Resume reattaches only compatible stateless sessions. It is not restoration of arbitrary
+application state and does not preserve TCP connections across a bridge restart; that is B14.
+
+## Acceptance gates
+
+1. More than fifty compatible initialize/DELETE cycles reuse one actual child and one upstream
+   initialization. Two simultaneously active sessions must also share that same generation.
+2. Concurrent numeric/string ID collisions, out-of-order results, progress and cancellation
+   route to the correct owner. Forged or late messages cannot cross sessions.
+3. Delete one client while another works, kill a child during a request, and recycle while busy.
+   Pending callers fail promptly and dispatched tool calls are never replayed.
+4. Incompatible initialization and unsupported callbacks/methods fail explicitly. Isolation
+   defaults and existing HTTP proxy behavior remain unchanged.
+5. Counter deltas for identical isolated and shared workloads show actual reduced launches,
+   not merely fewer latency samples or a lower instant process count.
+6. Use an isolated config directory and spare port for real-server and browser/CLI canaries.
+   Do not alter another project's client or orchestration configuration.
+
+Reference: released MCP
+[lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle),
+[transports](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports),
+[progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress), and
+[cancellation](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation).
+Draft transport changes are not applied to clients speaking released versions.

package/examples/servers.example.json

@@ -0,0 +1,31 @@
+{
+  "filesystem": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+  },
+  "github": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "REPLACE_WITH_YOUR_PAT" }
+  },
+  "example-http-static-token": {
+    "type": "http",
+    "url": "https://example.com/mcp",
+    "auth": { "type": "env", "var": "EXAMPLE_TOKEN" }
+  },
+  "example-http-cli-token": {
+    "type": "http",
+    "url": "https://your-service.example.com/mcp",
+    "auth": {
+      "type": "command",
+      "command": "az account get-access-token --resource api://your-resource-id --query accessToken -o tsv",
+      "refreshMinutes": 50
+    },
+    "headers": { "x-example-header": "value" }
+  },
+  "example-http-no-auth": {
+    "type": "http",
+    "url": "https://open.example.com/mcp",
+    "auth": { "type": "none" }
+  }
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "mcp-pacemaker",
+  "version": "1.3.1",
+  "description": "Keeps your MCP servers alive across editor restarts, reboots, and token expiry — pluggable auth, cross-platform auto-start, one-command setup. Zero-dependency bridge; a small CLI for setup.",
+  "type": "module",
+  "bin": {
+    "mcp-pacemaker": "bin/cli.mjs",
+    "mcp-bridge": "bin/mcp-bridge.mjs"
+  },
+  "files": [
+    "bin/",
+    "autostart/",
+    "supervisor/",
+    "tools/windows-security-helper/",
+    "examples/",
+    "ui/dist/",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "docs/shared-sessions.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.txt",
+    "CONTRIBUTING.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "Girish Konda",
+  "homepage": "https://github.com/girishkvs/mcp-pacemaker#readme",
+  "bugs": {
+    "url": "https://github.com/girishkvs/mcp-pacemaker/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/girishkvs/mcp-pacemaker.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sse",
+    "bridge",
+    "proxy",
+    "vscode",
+    "cursor",
+    "claude-desktop",
+    "supervisor",
+    "keep-alive"
+  ],
+  "scripts": {
+    "bridge": "node bin/mcp-bridge.mjs",
+    "cli": "node bin/cli.mjs",
+    "consumer:check": "node tools/npm-consumer/check.mjs",
+    "compat:prepare": "node tools/compatibility/prepare.mjs",
+    "compat:prepare:baseline": "node tools/compatibility/prepare.mjs --historical",
+    "compat:clean": "node tools/compatibility/prepare.mjs --clean",
+    "test:compat": "node --test --test-concurrency=1 test/compat/gates.test.mjs test/compat/cli-api.test.mjs",
+    "test:compat:browser": "node --test --test-concurrency=1 test/compat/browser.test.mjs",
+    "test": "node --test test/bridge.test.mjs test/bridge-controls.test.mjs test/kill-tree.test.mjs test/keepalive.test.mjs test/auth-token.test.mjs test/cold-start.test.mjs test/crash-report.test.mjs test/resume.test.mjs test/config-checks.test.mjs test/config-reload.test.mjs test/health.test.mjs test/cli.test.mjs test/logs.test.mjs test/prewarm.test.mjs test/pooling-config.test.mjs test/pooling-writer.test.mjs test/pooling-api.test.mjs test/pooling-deadlines.test.mjs test/pooling-queue-budget.test.mjs test/windows-security-helper.test.mjs test/tui.test.mjs test/warm-pool.test.mjs test/server-metrics.test.mjs test/admission.test.mjs test/shared-sessions.test.mjs test/shared-http.test.mjs test/cross-host.test.mjs test/suite-integrity.test.mjs test/consumer-package.test.mjs test/notices.test.mjs test/notices-runtime.test.mjs test/npm-publication.test.mjs test/npm-publication-proof.test.mjs test/update-check.test.mjs test/service-lifecycle.test.mjs test/service-supervisor.test.mjs test/npm-publication-gates.test.mjs test/publication-scanners-advisories.test.mjs test/publication-scanners.test.mjs test/service-replacement.test.mjs test/consumer-environment.test.mjs test/npm-publication-external.test.mjs test/npm-publication-matrix.test.mjs test/npm-publication-peer.test.mjs test/publication-scanners-diagnostics.test.mjs test/publication-scanners-publication.test.mjs test/publication-scanners-paths.test.mjs test/npm-publication-local-enforcement.test.mjs test/publication-scanners-admission.test.mjs",
+    "notices:check": "node tools/third-party-notices/check.mjs",
+    "publication:source-gates": "node tools/npm-publication/source-gates.mjs",
+    "publication:artifact-gates": "node tools/npm-publication/artifact-gates.mjs",
+    "service:replacement:check": "node tools/service-replacement/check.mjs",
+    "publication:external-gates": "node tools/npm-publication/external-gates.mjs",
+    "publication:local-gate": "node tools/npm-publication/local-windows.mjs",
+    "publication:verify-local": "node tools/npm-publication/verify-local.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "commander": "^15.0.0",
+    "ink": "^7.1.1",
+    "picocolors": "^1.1.1",
+    "react": "^19.2.7",
+    "semver": "^7.7.3",
+    "smol-toml": "^1.8.0"
+  }
+}

package/supervisor/bridge-child.mjs

@@ -0,0 +1,14 @@
+// IPC reaches the bridge's existing graceful shutdown handler on Windows too.
+let loaded = false;
+let stopRequested = false;
+function shutdown() {
+  stopRequested = true;
+  if (loaded) process.emit('SIGTERM');
+}
+process.on('message', (message) => {
+  if (message === 'stop') shutdown();
+});
+process.on('disconnect', shutdown);
+await import('../bin/mcp-bridge.mjs');
+loaded = true;
+if (stopRequested) shutdown();

package/supervisor/supervise.mjs

@@ -0,0 +1,172 @@
+import { fork } from 'node:child_process';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { homedir } from 'node:os';
+import { dirname, resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { servicePaths, assertDurableRoot } from '../bin/service-control.mjs';
+
+const { values } = parseArgs({
+  options: { port: { type: 'string', default: '8791' }, config: { type: 'string' } },
+});
+const port = Number(values.port);
+const root = realpathSync(resolve(dirname(fileURLToPath(import.meta.url)), '..'));
+const config = resolve(values.config || join(homedir(), '.mcp-pacemaker', 'servers.json'));
+const paths = servicePaths(config, port);
+assertDurableRoot(root);
+if (Number(process.versions.node.split('.')[0]) < 20) throw new Error('Node.js >=20 is required.');
+
+if (existsSync(paths.hold)) {
+  console.log(`Service :${port} is held stopped. Use the matching CLI start --port ${port} to resume deliberately.`);
+} else {
+  await supervise();
+}
+
+async function supervise() {
+  const identity = {
+    protocol: 1, root, config, port, socket: paths.socket, pid: process.pid, execPath: process.execPath,
+    id: randomUUID(), token: randomBytes(32).toString('hex'),
+    version: JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version,
+  };
+  let child;
+  let childExit;
+  let retry;
+  let stopping;
+  let stopRequested = false;
+  let holdRequested = false;
+  const clients = new Set();
+  const server = createServer((socket) => {
+    clients.add(socket);
+    socket.on('close', () => clients.delete(socket));
+    socket.on('error', () => socket.destroy());
+    socket.setTimeout(15000, () => socket.destroy());
+    let data = '';
+    let handled = false;
+    socket.on('data', (chunk) => {
+      if (handled) return;
+      data += chunk;
+      if (data.length > 4096) { socket.destroy(); return; }
+      if (!data.includes('\n')) return;
+      handled = true;
+      let request;
+      try { request = JSON.parse(data.slice(0, data.indexOf('\n'))); }
+      catch { socket.destroy(); return; }
+      if (request.id !== identity.id ||
+          request.token !== identity.token ||
+          request.action !== 'stop') {
+        socket.destroy();
+        return;
+      }
+      stop().then(() => {
+        socket.end(JSON.stringify({ id: identity.id, stopped: true, autostartHeld: true }) + '\n');
+      }, (error) => {
+        console.error(error.message);
+        socket.end(JSON.stringify({ id: identity.id, stopped: false }) + '\n');
+      });
+    });
+  });
+
+  mkdirSync(dirname(config), { recursive: true, mode: 0o700 });
+  await new Promise((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(paths.socket, resolveListen);
+  });
+  server.on('error', (error) => { console.error(error.message); process.exitCode = 1; });
+  try {
+    writeFileSync(paths.record, JSON.stringify(identity) + '\n', { mode: 0o600 });
+    if (existsSync(paths.hold)) {
+      server.close();
+      return;
+    }
+    launch();
+  } catch (error) {
+    server.close();
+    throw error;
+  }
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+
+  function launch() {
+    if (stopRequested ||
+        existsSync(paths.hold)) {
+      server.close();
+      return;
+    }
+    child = fork(join(root, 'supervisor', 'bridge-child.mjs'), ['--port', String(port), '--config', config], {
+      execPath: process.execPath, execArgv: [], stdio: ['ignore', 'inherit', 'inherit', 'ipc'], windowsHide: true,
+    });
+    childExit = new Promise((resolveExit, reject) => {
+      child.once('error', reject);
+      child.once('exit', (code) => {
+        child = undefined;
+        resolveExit();
+        if (stopRequested) return;
+        if (code === 3) server.close();
+        else retry = setTimeout(launch, 2000);
+      });
+    });
+    childExit.catch((error) => {
+      console.error(`Bridge launch failed: ${error.message}`);
+      process.exitCode = 1;
+      server.close();
+    });
+  }
+
+  async function stop(hold = true) {
+    // Persist before touching the child so logon/unlock and OS retries cannot restart it.
+    if (hold &&
+        !holdRequested) {
+      writeFileSync(paths.hold, JSON.stringify({ id: identity.id, root, config, port }) + '\n', { mode: 0o600 });
+      holdRequested = true;
+    }
+    if (stopping) return stopping;
+    stopRequested = true;
+    clearTimeout(retry);
+    stopping = (async () => {
+      if (child) {
+        if (child.connected) {
+          try {
+            await new Promise((resolveSend, reject) => child.send('stop', (error) => error ? reject(error) : resolveSend()));
+          } catch (error) {
+            if (error.code !== 'ERR_IPC_CHANNEL_CLOSED' &&
+                error.code !== 'EPIPE') throw error;
+          }
+        }
+        let timeout;
+        try {
+          await Promise.race([
+            childExit,
+            new Promise((_, reject) => {
+              timeout = setTimeout(() => reject(new Error('Bridge did not exit; do not replace its root. No force-kill attempted.')), 10000);
+            }),
+          ]);
+        } finally {
+          clearTimeout(timeout);
+        }
+      }
+      if (holdRequested) {
+        writeFileSync(paths.hold, JSON.stringify({ id: identity.id, root, config, port, stopped: true }) + '\n', { mode: 0o600 });
+      }
+      server.close();
+      process.removeListener('SIGINT', onSignal);
+      process.removeListener('SIGTERM', onSignal);
+    })().catch((error) => {
+      // Keep restart suppressed, but let a later explicit stop verify the real child exit.
+      // A timeout must not write a completed receipt or permanently poison reconciliation.
+      stopping = undefined;
+      throw error;
+    });
+    return stopping;
+  }
+
+  function onSignal() {
+    stop(false).then(() => {
+      for (const socket of clients) socket.destroy();
+    }, (error) => {
+      console.error(error.message);
+      process.exitCode = 1;
+    });
+  }
+}

package/supervisor/supervise.ps1

@@ -0,0 +1,23 @@
+<#
+.SYNOPSIS  Supervisor for the mcp-pacemaker bridge (Windows). Keeps it alive across crashes.
+.DESCRIPTION
+  Runs the managed supervisor. A targeted CLI stop holds automatic restarts until an
+  explicit CLI start. Node.js 20 or newer must be on PATH.
+.PARAMETER Port  Port the bridge listens on (default 8791). Must match your client config.
+.OUTPUTS
+  Supervisor diagnostics.
+.EXAMPLE
+  .\supervise.ps1 -Port 8791
+#>
+[CmdletBinding()]
+param([ValidateRange(1, 65535)][int]$Port = 8791)
+
+$ErrorActionPreference = 'Stop'
+$supervisor = Join-Path -Path $PSScriptRoot -ChildPath 'supervise.mjs'
+
+if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+  throw "node is not on PATH. Install Node.js (>=20) and retry."
+}
+
+& node $supervisor --port $Port
+exit $LASTEXITCODE

package/supervisor/supervise.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Starts the managed supervisor. Arg 1 = port.
+PORT="${1:-8791}"
+DIR="$(cd "$(dirname "$0")/.." && pwd)"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "node is not on PATH. Install Node.js (>=20) and retry." >&2
+  exit 1
+fi
+
+exec node "$DIR/supervisor/supervise.mjs" --port "$PORT"

package/tools/windows-security-helper/README.md

@@ -0,0 +1,95 @@
+# Windows security helper
+
+`bin/windows/PoolingSecurityHelper.exe` is an own-source, AnyCPU .NET Framework
+console program. It contains both the native security reader and the operation
+code; there is no companion reader DLL or third-party runtime dependency.
+The `bin/windows/src/` source and build metadata ship alongside the executable.
+
+## Runtime
+
+Requires Windows with .NET Framework 4.6.2 or later. Windows 10 1607+, Windows 11,
+and Windows Server 2016+ include that version or newer. Windows PowerShell 5.1
+alone on older Windows does not establish this prerequisite.
+PowerShell is **not** launched by the helper.
+There is no runtime compilation, download, elevation, or policy change.
+AnyCPU uses the installed Framework's process architecture; native calls use
+pointer-sized handles. Windows ARM64 execution has not been validated.
+
+The Node caller must launch the package-relative executable directly (no shell)
+with exactly one argument, `inspect` or `copy`, and supply:
+
+| Environment variable | Used by | Value |
+| --- | --- | --- |
+| `MCP_POOL_SOURCE` | Both | Source config path |
+| `MCP_POOL_SECURITY` | Copy | Previously inspected fingerprint |
+| `MCP_POOL_TEMP` | Copy | Existing empty replacement file |
+| `MCP_POOL_BACKUP` | Copy | Existing empty backup file |
+
+`inspect` writes one line: `F:<base64 SHA256>` for complete security or
+`P:<base64 SHA256>` when audit read is denied. These are comparison values,
+not log fields. The caller must refuse automatic writes for partial (`P:`)
+state. Successful `copy` writes nothing to stdout.
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Inspection or copy/verification succeeded |
+| 3 | Source fingerprint changed before or after copy; caller reports conflict |
+| 1 | Invalid input, I/O failure, or security cannot be preserved |
+
+On failure, stderr contains only `MCPERR type=<exception type>` and, for native
+errors, `MCPERR nativeError=<integer>`. No path, descriptor, token, config bytes,
+or exception message is logged. Caller owns process timeout and error mapping.
+
+Fingerprint framing is unchanged: canonical native descriptor (mask `0x1f7`),
+separate managed audit descriptor, and integer file attributes, written with
+`BinaryWriter` length prefixes before SHA256. Copy preserves owner/group/DACL
+through SDDL and verifies the entire fingerprint on both staging files, then
+rechecks the source. It does not copy unsupported audit/integrity/attribute
+state or weaken it to force success. It never writes config contents.
+
+## Build and verify
+
+Prerequisites, installed by the developer or CI image:
+
+1. Visual Studio or Build Tools with MSBuild and its Roslyn `csc.exe`, supporting
+   `/deterministic` and `/pathmap`. `vswhere` discovers current releases, including
+   Visual Studio 2026; an explicit compiler path is also supported.
+2. The .NET Framework **4.6.2 targeting pack** (reference assemblies, not a new
+   runtime). The script reports missing prerequisites; it installs nothing.
+3. Windows PowerShell 5.1 or PowerShell 7 for the build script only.
+
+From the repository root:
+
+```powershell
+# Update executable and metadata after source changes.
+.\tools\windows-security-helper\build.ps1
+
+# Read-only source/toolchain/hash check plus byte-for-byte rebuild.
+.\tools\windows-security-helper\build.ps1 -Verify
+
+# Select an already-installed compiler explicitly when reproducing recorded bytes.
+.\tools\windows-security-helper\build.ps1 -Verify -CompilerPath 'C:\path\to\Roslyn\csc.exe'
+```
+
+The build uses `/noconfig /nostdlib+` with explicit `mscorlib.dll` and `System.dll`
+references, fixed options, LF-normalized UTF-8 source, and mapped source paths.
+It compiles twice under different temporary paths and refuses unequal bytes.
+Temporary build files are removed by explicit path. No `dotnet build`, runtime
+Framework compiler, NuGet restore, or external binary is involved.
+
+`PoolingSecurityHelper.build.json` records compiler version/hash, reference
+hashes, options, normalized source/build-script hashes, and executable SHA256.
+`-Verify` checks all inputs and requires rebuilt bytes to match the packaged
+binary. Verification never updates the binary or metadata.
+
+Reproducibility is scoped to the **recorded compiler and references**. A newer
+CI image/compiler may produce different bytes; do not treat a changed toolchain
+as verification of the old binary. Use the recorded installed toolchain or
+explicitly rebuild, review, and validate the updated assets. This is integrity
+checking, not code signing or protection against someone replacing all assets.
+
+The published executable must contain only the production sources above.
+Audit-denial/delay test variants belong in disposable directories outside `bin/`
+and must never be included in an npm tarball. Release validation must also run
+the real package on supported Windows/Node versions and verify packaged file
+inclusion. This build alone does not establish those platform results.