mcp-pacemaker 2.0.2 → 2.1.1

package/bin/windows-task-channel.mjs

@@ -0,0 +1,335 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, lstatSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const HELPER = fileURLToPath(new URL('./windows-task-channel/TaskChannelGuard.exe', import.meta.url));
+const METADATA = fileURLToPath(new URL('./windows-task-channel/TaskChannelGuard.build.json', import.meta.url));
+// A detached guard must not hold the caller's working directory open; that directory can be an
+// instance, config or staging path the caller is entitled to replace or remove. Its own packaged
+// directory is already locked while the running image is mapped, so it adds no new constraint.
+const HELPER_DIRECTORY = fileURLToPath(new URL('./windows-task-channel/', import.meta.url));
+
+function deferred() {
+  let resolve, reject;
+  const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+  promise.catch(() => {});
+  return { promise, resolve, reject };
+}
+
+class TaskChannel {
+  constructor() {
+    this.started = deferred();
+    this.worker = deferred();
+    this.completion = deferred();
+    this.pending = new Map();
+    this.frames = [];
+    this.waiters = [];
+    this.sequence = 0;
+    this.buffer = '';
+    this.failure = null;
+    this.intentionalClose = false;
+  }
+
+  verifyHelper() {
+    const metadataBytes = readFileSync(METADATA);
+    if (!lstatSync(METADATA).isFile() ||
+        lstatSync(METADATA).isSymbolicLink()) throw new Error('Invalid packaged task channel metadata path');
+    if (metadataBytes.length > 65536) throw new Error('Task channel metadata exceeds bounds');
+    const metadata = JSON.parse(metadataBytes);
+    const digest = metadata.binarySha256;
+    const valid = metadata.schemaVersion === 1 &&
+      metadata.binary === 'TaskChannelGuard.exe' &&
+      typeof digest === 'string' &&
+      digest.length === 64 &&
+      [...digest].every(character => '0123456789abcdef'.includes(character));
+    if (!valid) throw new Error('Invalid packaged task channel digest');
+    const stat = lstatSync(HELPER);
+    if (!stat.isFile() ||
+        stat.isSymbolicLink() ||
+        stat.size < 1 ||
+        stat.size > 4 * 1024 * 1024 ||
+        createHash('sha256').update(readFileSync(HELPER)).digest('hex') !== digest) {
+      throw new Error('Packaged task channel helper identity mismatch');
+    }
+  }
+
+  async start(request) {
+    if (process.platform !== 'win32') throw new Error('Task channel requires Windows');
+    this.verifyHelper();
+    const bytes = this.encode(request, 65536);
+    this.child = spawn(HELPER, [], {
+      cwd: HELPER_DIRECTORY, detached: true, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    this.child.stdout.setEncoding('utf8');
+    this.child.stderr.setEncoding('utf8');
+    this.child.on('error', error => this.fail(error));
+    this.child.stdin.on('error', error => this.fail(error));
+    this.child.stdout.on('error', error => this.fail(error));
+    this.child.stderr.on('error', error => this.fail(error));
+    let diagnosticBytes = 0;
+    this.child.stderr.on('data', text => {
+      diagnosticBytes += Buffer.byteLength(text);
+      if (diagnosticBytes > 2048) this.fail(new Error('Unexpected task guard diagnostics'));
+    });
+    this.child.stdout.on('data', text => this.consume(text));
+    this.child.on('close', (code, signal) => {
+      clearTimeout(this.timer);
+      const receipt = { code, signal,
+        reason: this.failure?.message ?? this.closeReason ?? (code === 0 ? 'completed' : `native-exit-${code}`) };
+      this.exited = true;
+      this.exitReceipt = receipt;
+      this.fail(this.failure ?? new Error(`Task channel closed (native exit ${code})`));
+      this.completion.resolve(receipt);
+    });
+    this.timer = setTimeout(() => this.fail(new Error('Task channel ready deadline exceeded')), 15000);
+    this.child.stdin.write(bytes);
+    try {
+      const ready = await this.started.promise;
+      clearTimeout(this.timer);
+      this.timer = setTimeout(() => this.fail(new Error('Task channel lifetime exceeded')),
+        (request.lifetimeMs ?? 60000) + 3000);
+      return ready;
+    } catch (error) {
+      error.guardIdentity ??= structuredClone(this.guardIdentity);
+      try {
+        error.helperExit = await this.close();
+        error.cleanupUnverified = false;
+      } catch (closeError) {
+        error.cleanupUnverified = true;
+        error.cleanupError = closeError.message;
+        error.message += `; ${closeError.message}`;
+      }
+      throw error;
+    }
+  }
+
+  encode(value, maximum = 16384) {
+    if (!value ||
+        typeof value !== 'object' ||
+        Array.isArray(value)) throw new Error('Task channel requires an object frame');
+    const bytes = Buffer.from(`${JSON.stringify(value)}\n`, 'utf8');
+    if (bytes.length > maximum) throw new Error('Task channel frame exceeds bounds');
+    return bytes;
+  }
+
+  consume(text) {
+    this.buffer += text;
+    if (Buffer.byteLength(this.buffer) > 131072) return this.fail(new Error('Task channel output exceeds bounds'));
+    let newline;
+    while ((newline = this.buffer.indexOf('\n')) >= 0) {
+      const line = this.buffer.slice(0, newline);
+      this.buffer = this.buffer.slice(newline + 1);
+      try { this.event(JSON.parse(line)); }
+      catch (error) { this.fail(error); return; }
+    }
+  }
+
+  event(message) {
+    if (!message ||
+        typeof message.type !== 'string') throw new Error('Invalid task channel event');
+    if (message.type === 'started') {
+      const identity = message.guardIdentity;
+      if (this.guardIdentity ||
+          identity?.pid !== this.child.pid ||
+          typeof identity.creationTime !== 'string') throw new Error('Invalid task guard startup identity');
+      this.guardIdentity = structuredClone(identity);
+    } else if (message.type === 'failed') {
+      const error = new Error(`Task channel refused: ${message.reason}`);
+      error.code = message.reason;
+      error.guardIdentity = message.guardIdentity;
+      error.detail = message;
+      this.fail(error);
+    } else if (message.type === 'ready' ||
+        message.type === 'result') {
+      if (this.ready) throw new Error('Duplicate task channel readiness');
+      if (message.guardIdentity?.pid !== this.child.pid) throw new Error('Task guard process binding mismatch');
+      this.ready = message;
+      this.started.resolve(structuredClone(message));
+    } else if (message.type === 'worker') {
+      if (!this.ready ||
+          this.peer) throw new Error('Unexpected task channel peer');
+      this.peer = structuredClone(message.peer);
+      this.workerSession = structuredClone(message.targetSession);
+      this.worker.resolve(structuredClone(this.peer));
+    } else if (message.type === 'frame') {
+      if (!this.peer ||
+          JSON.stringify(message.peer) !== JSON.stringify(this.peer)) throw new Error('Task channel peer changed');
+      const received = { peer: structuredClone(this.peer), frame: message.frame };
+      if (this.waiters.length) this.waiters.shift().resolve(received);
+      else {
+        if (this.frames.length >= 32) throw new Error('Task channel receive queue exceeds bounds');
+        this.frames.push(received);
+      }
+    } else if (message.type === 'sent' ||
+        message.type === 'authorized') {
+      const pending = this.pending.get(message.id);
+      if (!pending) throw new Error('Unexpected task channel acknowledgement');
+      this.pending.delete(message.id);
+      pending.resolve(structuredClone(message));
+    } else if (message.type === 'closed') {
+      this.closeReason = message.reason;
+    } else throw new Error('Unknown task channel event');
+  }
+
+  fail(error) {
+    this.failure ??= error;
+    this.failure.guardIdentity ??= structuredClone(this.guardIdentity);
+    this.started.reject(this.failure);
+    this.worker.reject(this.failure);
+    for (const pending of this.pending.values()) pending.reject(this.failure);
+    this.pending.clear();
+    for (const waiter of this.waiters) waiter.reject(this.failure);
+    this.waiters = [];
+    this.frames = [];
+    if (this.child?.stdin.writable) this.child.stdin.end();
+  }
+
+  request(action, frame) {
+    if (this.failure) return Promise.reject(this.failure);
+    if (!this.peer &&
+        action !== 'authorize') return Promise.reject(new Error('Task channel peer is not verified'));
+    if (this.pending.size >= 32) return Promise.reject(new Error('Task channel command queue exceeds bounds'));
+    if (frame !== undefined) this.encode(frame);
+    const id = ++this.sequence;
+    const pending = deferred();
+    this.pending.set(id, pending);
+    this.child.stdin.write(this.encode({ action, id, ...(frame === undefined ? {} : { frame }) }, 65536));
+    return pending.promise;
+  }
+
+  receive() {
+    if (this.failure) return Promise.reject(this.failure);
+    if (this.frames.length) return Promise.resolve(this.frames.shift());
+    if (this.waiters.length >= 32) return Promise.reject(new Error('Task channel waiter queue exceeds bounds'));
+    const pending = deferred();
+    this.waiters.push(pending);
+    return pending.promise;
+  }
+
+  async close() {
+    if (!this.child) return;
+    if (!this.exited &&
+        !this.intentionalClose) {
+      this.intentionalClose = true;
+      if (this.child.stdin.writable) this.child.stdin.write('{"action":"close"}\n');
+    }
+    let timer;
+    try {
+      return await Promise.race([this.completion.promise, new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          if (this.child.stdin.writable) this.child.stdin.end();
+          const error = new Error('Task guard exit unverified; retain owned cleanup evidence');
+          error.guardIdentity = structuredClone(this.guardIdentity);
+          error.cleanupUnverified = true;
+          reject(error);
+        }, 5000);
+      })]);
+    } finally { clearTimeout(timer); }
+  }
+}
+
+export async function createTaskChannel(options) {
+  const channel = new TaskChannel();
+  const { operationId, targetSid, sessionId, bootstrap, manifestParent, manifest,
+    expectedCreationTime, handshakeTimeoutMs = 30000, lifetimeMs = 900000 } = options;
+  const ready = await channel.start({
+    action: 'serve', operationId, targetSid, sessionId, bootstrap, manifestParent,
+    document: manifest, expectedCreationTime, handshakeTimeoutMs, lifetimeMs,
+  });
+  return {
+    ...ready,
+    pid: channel.child.pid,
+    awaitWorker: () => channel.worker.promise,
+    get workerSession() { return structuredClone(channel.workerSession); },
+    send: frame => channel.request('send', frame),
+    authorize: () => channel.request('authorize'),
+    receive: () => channel.receive(),
+    closed: channel.completion.promise,
+    close: () => channel.close(),
+  };
+}
+
+async function query(request) {
+  const channel = new TaskChannel();
+  const result = await channel.start(request);
+  const exit = await channel.completion.promise;
+  if (exit.code !== 0 ||
+      exit.signal !== null) throw new Error(`Task channel query failed: ${exit.reason}`);
+  return { ...result, helperExit: exit };
+}
+
+export function queryTaskChannelCaller() {
+  return query({ action: 'caller' });
+}
+
+export async function queryCliCallerContext() {
+  const result = await query({ action: 'cli-context' });
+  if (result.proofScope !== 'cli-effective-context-snapshot' ||
+      result.identity?.pid !== process.pid ||
+      typeof result.ordinaryEligible !== 'boolean') {
+    throw new Error('CLI context caller binding or proof scope is unverified');
+  }
+  return result;
+}
+
+export async function queryCurrentUserSession() {
+  const result = await query({ action: 'current-session' });
+  const session = result.session;
+  if (result.proofScope !== 'current-user-session-snapshot' ||
+      result.identity?.pid !== process.pid ||
+      typeof result.identity?.ownerSid !== 'string' ||
+      result.identity.ownerSid.length === 0 ||
+      !Number.isInteger(result.identity.sessionId) ||
+      result.identity.sessionId <= 0 ||
+      session?.ownerSid !== result.identity.ownerSid ||
+      session?.sessionId !== result.identity.sessionId ||
+      !['active', 'disconnected'].includes(session?.state) ||
+      typeof session?.logonTime !== 'string' ||
+      !/^[1-9][0-9]{0,18}$/.test(session.logonTime)) {
+    throw new Error('Current user session binding is unverified');
+  }
+  return result;
+}
+
+export async function requireOrdinaryUpgradeCaller() {
+  if (process.platform !== 'win32') return;
+  const caller = await queryCliCallerContext();
+  const facts = caller.actorFacts;
+  const observation = caller.observation;
+  const ordinary = caller.ordinaryEligible === true &&
+    facts?.ownerSid === caller.identity.ownerSid &&
+    facts?.sessionId === caller.identity.sessionId &&
+    facts?.elevated === false &&
+    facts?.enabledAdministrator === false &&
+    facts?.guardThreadImpersonating === false &&
+    facts?.parentThreadImpersonation === 'observed-none' &&
+    observation?.method === 'pss-threads-held-token-query' &&
+    observation?.processAccess === '0x101400' &&
+    observation?.captureFlags === '0x80' &&
+    observation?.threadContextFlags === 0 &&
+    observation?.completeStableThreadSet === true &&
+    observation?.primaryStable === true &&
+    observation?.atomicFutureProtection === false &&
+    Number.isInteger(observation?.threadCount) &&
+    observation.threadCount > 0 &&
+    observation.threadCount <= 128 &&
+    caller.helperExit?.code === 0 &&
+    caller.helperExit?.signal === null;
+  if (!ordinary) {
+    // Include the native reason: an ambiguous observation and a genuinely privileged caller are
+    // both refused, and without this they are indistinguishable after the fact.
+    const reason = typeof caller.reason === 'string' ? caller.reason : 'UNREPORTED';
+    throw new Error('Windows upgrade execution requires a verified ordinary caller; no elevation or runtime-authority fallback was attempted. ' +
+      `Observed: ${reason}.`);
+  }
+  return caller;
+}
+
+export function readProtectedManifest(path, { operationId, manifestParent }) {
+  return query({ action: 'read-manifest', path, operationId, manifestParent });
+}
+
+export function inspectTrustedCodeRoot(root) {
+  return query({ action: 'inspect-root', root });
+}

package/docs/account-upgrades.md

@@ -0,0 +1,218 @@
+# Explicit original-account upgrades on Windows
+
+The default scope is **the current user**, even from an elevated terminal.
+Scope does not authorize elevated runtime execution: without `--user`, Windows
+upgrade and recovery require a freshly verified ordinary caller before staging
+or mutation. Read-only planning remains available from an elevated terminal.
+The shared [user-runtime contract](execution-context.md) also applies to normal
+startup and to non-root Linux/macOS runtime operations.
+`--all-users` is not implemented. Selecting every host in `init` is not an
+all-users installation, and managing one other user's instance does not convert
+it into a machine service or LocalSystem service.
+
+An explicit account operation requires a canonical numeric SID and exactly one
+existing task or managed-instance selector:
+
+```text
+mcp-pacemaker --user <SID> --task <exact-task-path> upgrade --to <version> --plan
+mcp-pacemaker --user <SID> --task <exact-task-path> upgrade --to <version>
+mcp-pacemaker --user <SID> --instance <directory> upgrade --recover
+```
+
+### Supported option combinations
+
+These limits apply whenever `--user` selects the task-controller path, including
+an explicit selection of the current user's SID.
+
+| Form | Explicit account behavior |
+|---|---|
+| `--user SID --task PATH upgrade --to VERSION [--plan]` | One existing legacy task; preserve its account and port |
+| `--user SID --instance DIR upgrade --to VERSION [--plan]` | One registered managed instance |
+| `--user SID --instance DIR upgrade --recover` | Recover only its recorded operation; interactive authorization remains required |
+| `--sxs`, with or without `--port` | Unsupported; refuse before native/task discovery |
+| `--port` without SxS | Unsupported; normal replacement preserves the selected port |
+| Bare `upgrade` or `upgrade --self` | Unsupported in explicit account scope; select `--to` or `--recover` |
+| Recovery with `--task`, `--to`, `--plan` or `--registry` | Unsupported; refuse rather than ignore or override an option |
+| Both `--task` and `--instance`, `--config`, or `--all-users` | Refuse; no scope conversion or new registration is inferred |
+| Execution with `--yes` | Refuse; it cannot replace the two interactive confirmations. With read-only `--to ... --plan`, it authorizes no write |
+
+Selectors accept separate or equals syntax before or after `upgrade`.
+Without `--user`, current-user commands include bare repair,
+`--self` guidance, managed SxS with optional port, and selected-instance recovery.
+No machine-wide or cross-account SxS task-creation path is added.
+
+Another user requires an **already-elevated** administrator token, enabled
+Administrators membership, and complete native authorization checks. Restricted,
+AppContainer, impersonating or unverified cross-account contexts refuse.
+No account label, saved administrator flag or group membership alone grants
+authority. The product does not request UAC, enable privileges, impersonate,
+supply passwords, create accounts or change existing permissions. The one
+exception is outside this path: the default-scope `upgrade --fix-legacy-access`
+step, which an administrator runs explicitly for a 1.3 install that was set up
+from an administrator terminal. It changes only that task's run-as user entry and
+the owner of that install's `bin\cli.mjs`.
+
+## Where code executes
+
+Invoke the management CLI from an independently trusted installation. The
+elevated controller never imports the target's CLI or recovery code and never
+runs its Node/npm, dependency hooks, authentication commands or workloads.
+Target records are bounded data. Elevated code roots with untrusted writers or
+redirectable ancestors refuse; a hash does not turn writable code into trusted code.
+
+Ordinary selected-CLI commands use a fresh native effective-context observation.
+Only a non-elevated, non-administrator primary token plus a complete stable set
+of held parent threads with no observed impersonation token can avoid the
+administrator-path recursive root checks. Primary-token elevation alone is not
+enough. Unknown, denied, changed or impersonating observations retain the strict
+checks with a reason; unverified helper exit is fatal. Target JSON cannot select
+this path. Package inventory verification still runs, and the observation does
+not promise that the process can never change context afterward.
+
+The existing task launches a bounded worker under its **unchanged original
+principal, InteractiveToken logon type and run level**. That worker performs
+staging, dependency acquisition, preflight, the existing same-user stop protocol,
+runtime startup and rollback. Task Scheduler success is only correlation:
+disabled tasks and `AllowDemandStart=false` do not prove a worker ran.
+An eligible existing interactive session and actual authenticated worker are required.
+Explicit account inspection also requires the selected user's profile facts from
+`Win32_UserProfile`. An unavailable provider or unreadable profile stops the operation;
+the adapter does not infer another user's profile from environment variables or repair WMI.
+Only non-elevated (`RunLevel=0`) InteractiveToken registrations are supported;
+other logon/run-level choices refuse rather than being converted.
+
+The guard queries only the selected session. Full account-name resolution must
+match the target SID; the session must be active or disconnected but still logged
+on. Stable WTS snapshots bind its logon generation before bootstrap, after worker
+connection and at each authorization. Missing, denied, changed or unmapped facts
+refuse. The approval prompt is followed by another check before staging.
+These are **point-in-time eligibility checks**, not held session ownership:
+Windows does not atomically reserve that desktop across `RunEx`. Detected drift
+aborts; no session is created, switched, disconnected or impersonated.
+
+The selected task's owner may be its runtime user or canonical
+`BUILTIN\Administrators` (`S-1-5-32-544`). Other accounts called “Administrator”
+are not assumed privileged. Owner, group, DACL, SACL and integrity are captured,
+bound and preserved independently from run-as identity. Missing, denied or
+changed full security refuses; it is never repaired or relaxed.
+
+## Controller capability and channel
+
+The controller can only inspect/hold/repoint/restore/release the exact approved
+registration. Paths, account, original XML/security and allowed variants are
+sealed before worker requests. Worker data cannot select a different task,
+executable, principal or privileged configuration write.
+
+A separate query-only native guard owns one local pipe connection and retains
+the actual worker PID/creation/token/session identity. It has no process-kill
+interface. A protected per-operation manifest carries an ephemeral public key;
+Node's built-in Ed25519 signatures bind a fresh challenge, operation digest,
+guard-observed peer and monotonic request/response transcript. Private keys stay
+in controller memory. There is no reconnect-by-PID or nonce-only fallback.
+Signed replies also bind the checked session SID, ID and logon generation.
+Peer identity is not loaded-code attestation; the fixed capability remains safe
+even if an authenticated target-user worker lies.
+
+Only new operation-directory/file/pipe security is established at creation.
+The target must already be able to read the trusted bootstrap and traverse/read
+the protected operation store. `--controller-root <existing-directory>` selects
+an already suitable store; it does not install into Program Files or repair ACLs.
+The default store parent is the controller's local application-data directory.
+If its existing ancestors do not support the required target access/protection,
+the operation refuses before stopping the backend.
+
+Automatic triggers/restarts are held while deliberate demand start remains
+possible. Manual/external task starts are not claimed suppressed. Conflicting
+generations or revisions refuse. Because `IgnoreNew` can block a second task run
+while the worker is active, verified legacy rollback launches the original
+supervisor locally **inside the original-user worker**, not as the administrator.
+Legacy captured roots are checked for the worker's session before stop; native
+held-generation revalidation remains stop authority. Plans no longer list
+descendants: the processes the 1.3 bridge started are found and stopped by the
+broker during the stop, through the same handles, without a separate session query.
+Processes that cannot be traced to the bridge are never session-query or kill targets.
+The compact session request accepts at most 512 unique captured identities and
+128 KiB of UTF-8. PID, FILETIME and current-account/session fields are checked
+before discovery. Session queries use at most 32 exact IDs per batch and four
+separate local CIM sessions, within the unchanged 15-second caller bound.
+Missing, duplicate, stale or unexpected results refuse the whole operation.
+
+## Failure and recovery
+
+Declining the runtime-upgrade prompt after worker bootstrap restores the exact
+pre-bootstrap task revision after fresh authorization. No staging or stop is
+authorized by that decline. Failed authorization or restoration remains an
+explicit uncertain outcome.
+
+An upgrade refused before anything stops, for example because `servers.json`
+changed while the target downloaded, puts the current version back in service
+and restores the original task before its journal settles, so a later
+`--recover` changes nothing. If the current version could not be resumed or the
+task could not be restored, the journal stays open and `--recover` finishes the
+job.
+
+### Controller-only failure before instance publication
+
+If bootstrap happened but automatic restoration failed before any managed
+instance was published, **there is no automatic CLI recovery command for that
+state**. `--instance <missing-directory>` cannot work, and explicit-account
+`--task ... upgrade --recover` is unsupported. Do not create an instance record,
+guess an operation, or edit target configuration to make either command run.
+
+The error and `Recovery evidence:` output name the exact protected operation
+directory. Keep both files:
+
+- `manifest.json`: `document.initialTask` is the pre-bootstrap task snapshot;
+  `document.binding.initialTaskRevision` binds it.
+- `controller-journal.json`: `initial`, the last verified `current` revision,
+  full task security, and the uncertain phase.
+
+The supported path is **manual verified restoration of that exact task** by an
+authorized operator using the existing Task Scheduler COM adapter/tooling:
+
+1. Verify the protected evidence, task path, SID and initial revision agree.
+   Missing or inconsistent evidence is a refusal, not permission to reconstruct it.
+2. Re-establish the controller's required actual authority and fresh target
+   SID/session/logon-generation eligibility. Saved token/session facts are not
+   authorization; denied or changed checks remain blocking.
+3. Read the actual task XML and complete security descriptor again. Reconcile
+   it with the captured revisions before any write; do not overwrite an unknown
+   intervening change.
+4. Restore the saved initial definition using update-only registration while
+   preserving the principal, logon type, run level and raw full descriptor.
+   Re-read and verify the result. Importing XML alone or repairing permissions
+   is not this procedure.
+
+This manual path restores task registration only. It does not authorize runtime
+stop/start, replay, account/session changes, or administrator writes to target
+state. If those checks cannot be completed, retain the evidence and leave the
+operation blocked.
+
+Controller and worker journals share an operation ID but have separate authority.
+Loss of the peer/channel ends privileged RPC; it does not authorize killing an
+orphan worker. Uncertain task, stop, launch or admission outcomes remain explicit.
+No unknown tool outcome is replayed.
+
+Recovery requires the exact managed instance and its protected prior controller
+record, fresh actor/task/account authorization and a new bootstrap/handshake.
+The initial published legacy instance already contains that operation reference;
+recovery does not depend on a later HOLD acknowledgement or administrator edits
+to target state. The reference, protected manifest, controller record and target
+config/port must agree. Settled committed, aborted and rolled-back transactions,
+including their legacy forms, return without another worker or task mutation.
+An old authorization flag is never reused. Existing stale-lock and uncertain-
+admission refusals still apply; the controller does not edit target configuration
+or force-remove its locks.
+
+## Qualification boundary
+
+Owned same-user pipe/process tests exercise the real query-only guard and worker.
+The production Task Scheduler adapters are separately exercised against injected
+COM objects. Neither establishes successful elevated **two-account** task/runtime
+behavior. Real task security visibility does not establish mutation preservation.
+
+`tools/account-upgrade/qualify-two-account.ps1` is a runnable qualification entry
+for a separately authorized Windows environment with pre-existing accounts,
+session, task, protected toolchain and operation store. It defaults to read-only
+planning; `-Execute` still requires the product's interactive confirmations.
+It must not be run on a live installation merely because the code is present.

package/docs/compatibility.md

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