mcp-pacemaker 2.1.0 → 2.1.2

package/bin/legacy-access.mjs

@@ -0,0 +1,73 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { durableJson } from './managed-state.mjs';
+import { WindowsLegacyTaskAdapter } from './legacy-task.mjs';
+import {
+  ACCESS_FIXES, legacyAccessProblems, legacyAccessReport, legacyStatePort, parseLegacyRegistration, verifyLegacyPackage,
+} from './legacy-installation.mjs';
+
+const NEXT = 'Run mcp-pacemaker upgrade --to <version> from a normal (non-administrator) terminal.';
+
+export async function inspectLegacyAccess(home, { task = new WindowsLegacyTaskAdapter() } = {}) {
+  if (process.platform !== 'win32') throw new Error('--fix-legacy-access applies only to the known Windows 1.3 registration. Nothing was changed.');
+  const { port } = legacyStatePort(home);
+  const { root, registration } = parseLegacyRegistration(await task.inspect(port), port);
+  verifyLegacyPackage(root);
+  const cliPath = join(root, 'bin', 'cli.mjs');
+  const report = legacyAccessReport(await task.access(port, cliPath), registration);
+  return { port, cliPath, registration, report };
+}
+
+export function describeLegacyAccessFix({ port, report }) {
+  return [
+    `Legacy 1.3 access fix for port ${port}. It will only:`,
+    ...report.fixable.map(id => `  - ${ACCESS_FIXES[id](report)}`),
+    'Unchanged: task XML, triggers and run-as account (it keeps running as you, not elevated), other permissions and file contents.',
+  ].join('\n');
+}
+
+// Elevated, explicit and bound to the inspected descriptors: makes an install done from an
+// administrator terminal look like one done from a normal terminal, so the ordinary upgrade can run.
+export async function fixLegacyAccess({
+  home, plan = false, yes = false, interactive = false, confirm,
+  task = new WindowsLegacyTaskAdapter(), log = console.log, now = () => new Date(),
+} = {}) {
+  const selected = await inspectLegacyAccess(home, { task });
+  const { port, cliPath, registration, report } = selected;
+  const summary = { port, task: registration.path, cli: cliPath };
+  if (!report.missing.length) return { status: 'unchanged', ...summary, next: NEXT };
+  if (!report.elevated) {
+    throw new Error('Run --fix-legacy-access from an administrator terminal (Run as administrator). Nothing was changed.');
+  }
+  const manual = report.missing.filter(id => !report.fixable.includes(id));
+  if (manual.length) {
+    throw new Error([
+      'These permissions need an administrator to change them by hand; --fix-legacy-access does not. Nothing was changed.',
+      ...legacyAccessProblems(report).map(problem => `  - ${problem}`),
+    ].join('\n'));
+  }
+  log(describeLegacyAccessFix(selected));
+  if (plan) return { status: 'planned', ...summary, changes: report.fixable };
+  if (!yes) {
+    if (!interactive) throw new Error('--fix-legacy-access needs an interactive confirmation or --yes. Nothing was changed.');
+    if (await confirm('Apply this access fix?') !== true) return { status: 'cancelled', ...summary };
+  }
+  const directory = join(home, 'legacy-upgrade');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const journal = join(directory, `access-${now().toISOString().replaceAll(':', '-')}.json`);
+  const record = {
+    protocol: 1, kind: 'legacy-access-fix', createdAt: now().toISOString(), ...summary,
+    changes: report.fixable, before: report.expected,
+  };
+  durableJson(journal, record);
+  let result;
+  try { result = await task.grantAccess(port, cliPath, report.expected); }
+  catch (error) {
+    durableJson(journal, { ...record, failed: error.message, changed: error.changed ?? [] });
+    throw new Error(`${error.message}\nRecorded before-state: ${journal}`, { cause: error });
+  }
+  durableJson(journal, { ...record, changed: result.changed, after: result.after });
+  const after = legacyAccessReport(await task.access(port, cliPath), registration);
+  if (after.missing.length) throw new Error(`Access is still missing after the fix: ${after.missing.join(', ')}. Recorded before-state: ${journal}`);
+  return { status: 'fixed', ...summary, changed: result.changed, journal, next: NEXT };
+}

package/bin/legacy-installation.mjs

@@ -13,12 +13,21 @@ import { assertDurableRoot } from './service-control.mjs';
 const approved = new WeakMap();
 const inventory = readManagedJson(new URL('./legacy-1.3.json', import.meta.url));
 const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const ACCESS_PROBLEMS = {
+  'task-write': report => `Task ${report.task.path} (owner ${report.task.ownerName}): your account can only read it.`,
+  'cli-owner': report => `${report.cli.path} (owner ${report.cli.ownerName}): your account cannot copy it with its permissions.`,
+  'cli-write': report => `${report.cli.path}: your account cannot write it.`,
+  'cli-delete': report => `${report.cli.path}: your account cannot rename it.`,
+  'bin-add-file': report => `${report.cli.directory}: your account cannot create files in it.`,
+};
+export const ACCESS_FIXES = {
+  'task-write': report => `give your account full control of task ${report.task.path}`,
+  'cli-owner': report => `make your account the owner of ${report.cli.path}`,
+};
 export const LEGACY_WARNING = [
-  'Restart this legacy Pacemaker installation? Pause its callers before confirming.',
-  'Clients will disconnect. Legacy 1.3 cannot drain or certify every in-flight HTTP outcome.',
-  'Only the selected supervisor, bridge and captured provably owned descendants will be verified stopped.',
-  'Historical orphan coverage remains unproven; uncaptured or unattributed processes are left untouched and are not enumerated as a complete set.',
-  'No unknown call is automatically replayed. The new managed runtime contains future children from birth.',
+  'Upgrade this 1.3 installation? Its supervisor, its bridge and the processes the bridge started will be stopped.',
+  'Open sessions and calls in progress end, and clients reconnect to the new version. No call is retried.',
+  'servers.json, every server setting in it and your client setup are kept as they are.',
 ].join('\n');
 
 export function legacyPlanDigest(plan) {
@@ -30,18 +39,19 @@ export function legacyPlanDigest(plan) {
 
 export async function confirmLegacyUpgrade(plan, { yes = false, interactive = false, confirm } = {}) {
   if (!plan.legacy) throw new Error('Expected a legacy restart plan.');
-  if (yes ||
-      !interactive) throw new Error('Legacy migration requires interactive acknowledgement of this exact restart/uncertain-HTTP/partial-tree plan. Run upgrade --to <version> without --yes in an interactive terminal; pause callers before confirming.');
   const digest = legacyPlanDigest(plan);
-  const answer = await confirm(`${LEGACY_WARNING}\nPlan: ${digest}`);
-  if (answer !== true) return false;
+  if (!yes) {
+    if (!interactive) throw new Error('Legacy migration needs confirmation. Run upgrade --to <version> in an interactive terminal, or add --yes to confirm the plan shown.');
+    const answer = await confirm(`${LEGACY_WARNING}\nPlan: ${digest}`);
+    if (answer !== true) return false;
+  }
   if (legacyPlanDigest(plan) !== digest) throw new Error('Legacy plan changed during confirmation.');
   approved.set(plan, digest);
   return true;
 }
 
 export function requireLegacyApproval(plan) {
-  if (approved.get(plan) !== legacyPlanDigest(plan)) throw new Error('This legacy plan has no matching interactive acknowledgement.');
+  if (approved.get(plan) !== legacyPlanDigest(plan)) throw new Error('This legacy plan has no matching confirmation.');
   approved.delete(plan);
 }
 
@@ -132,10 +142,58 @@ export function legacySessionState(config) {
   return existsSync(path) ? new PoolingFiles(config).inspect(path) : null;
 }
 
+export function legacyStatePort(home) {
+  const statePath = join(home, 'state.json');
+  if (!existsSync(statePath)) throw new Error('No stable managed installation or exact legacy install state was found. Nothing was changed.');
+  const state = readManagedJson(statePath);
+  const ports = [...new Set((state.hosts ?? []).map(host => canonicalPort(host.port)))];
+  if (ports.length !== 1) throw new Error('Legacy migration requires exactly one selected port in existing install state.');
+  return { statePath, port: ports[0] };
+}
+
+export function legacyAccessReport(report, registration) {
+  const bound = report?.protocol === 1 &&
+    report.task?.path === registration.path &&
+    report.expected?.xmlSha256 === registration.xmlSha256 &&
+    Array.isArray(report.missing) &&
+    Array.isArray(report.fixable) &&
+    report.missing.every(id => Object.hasOwn(ACCESS_PROBLEMS, id)) &&
+    report.fixable.every(id => Object.hasOwn(ACCESS_FIXES, id) && report.missing.includes(id));
+  if (!bound) throw new Error('Legacy access check did not match the selected registration. Nothing was changed.');
+  return report;
+}
+
+export function legacyAccessProblems(report) {
+  return report.missing.map(id => ACCESS_PROBLEMS[id](report));
+}
+
+// A certain gap here would otherwise fail after the journal is published (task hold) or after staging (CLI copy).
+export function assertLegacyAccess(report, registration) {
+  legacyAccessReport(report, registration);
+  if (!report.missing.length) return;
+  const lines = [
+    'Your account cannot make the changes this upgrade needs. Nothing was changed.',
+    ...legacyAccessProblems(report).map(problem => `  - ${problem}`),
+  ];
+  if (report.fixable.length) {
+    lines.push(
+      'This usually means 1.3 was set up from an administrator terminal.',
+      `Run this once from ${report.elevated ? 'this' : 'an'} administrator terminal. It will only ${report.fixable.map(id => ACCESS_FIXES[id](report)).join(' and ')}:`,
+      '  mcp-pacemaker upgrade --fix-legacy-access',
+      'Then run this upgrade again from a normal (non-administrator) terminal.',
+    );
+  }
+  if (report.missing.some(id => !report.fixable.includes(id))) {
+    lines.push('--fix-legacy-access does not change the other permissions listed; an administrator must grant them.');
+  }
+  throw Object.assign(new Error(lines.join('\n')), { code: 'LEGACY_ACCESS_MISSING' });
+}
+
+// 1.3 rewrites sessions.json whenever a session starts or ends, and an upgrade may end
+// sessions, so only the config is compared.
 export function verifyLegacyConfig(config, legacy) {
   new PoolingFiles(config).verify(config, legacy.authority);
-  if (!isDeepStrictEqual(legacySessionState(config), legacy.sessions) ||
-      hasPoolingTransaction(config)) throw new Error('Legacy configuration/session state changed or has an unresolved transaction.');
+  if (hasPoolingTransaction(config)) throw new Error('Legacy configuration has an unresolved transaction.');
 }
 
 async function nonceChallenge(port, nonce) {
@@ -183,21 +241,19 @@ export async function verifyLegacyListener(instance, legacy, { sameGeneration =
 export async function prepareLegacyPlan(options, { home, task = new WindowsLegacyTaskAdapter(), processes } = {}) {
   if (process.platform !== 'win32') throw new Error('Legacy restart migration has no supported adapter on this OS. Nothing was changed.');
   if (options.sxs) throw new Error('Legacy-source SxS is not supported; no existing service was changed.');
-  const statePath = join(home, 'state.json');
-  if (!existsSync(statePath)) throw new Error('No stable managed installation or exact legacy install state was found. Nothing was changed.');
-  const state = readManagedJson(statePath);
-  const ports = [...new Set((state.hosts ?? []).map(host => canonicalPort(host.port)))];
-  if (ports.length !== 1) throw new Error('Legacy migration requires exactly one selected port in existing install state.');
-  const port = ports[0];
+  const { statePath, port } = legacyStatePort(home);
   const records = task.inspectLegacySource ? await task.inspectLegacySource(port) : await task.inspect(port);
   const { root, registration } = parseLegacyRegistration(records, port);
   const rootIdentity = verifyLegacyPackage(root);
+  if (typeof task.access === 'function') assertLegacyAccess(await task.access(port, join(root, 'bin', 'cli.mjs')), registration);
   const config = realpathSync.native(join(home, 'servers.json'));
   const files = new PoolingFiles(config);
+  // 1.3 rewrites sessions.json on every session start and end, so it is read only after the
+  // old bridge has stopped.
   const legacy = {
     protocol: 1, root, rootIdentity, registration,
     stateAuthority: files.inspect(statePath),
-    authority: files.inspect(config), sessions: legacySessionState(config),
+    authority: files.inspect(config), sessions: null,
   };
   const instance = {
     id: randomUUID(), directory: join(home, 'managed', `legacy-${port}-${randomUUID()}`),

package/bin/legacy-task.mjs

@@ -33,6 +33,30 @@ export class WindowsLegacyTaskAdapter {
   repoint(port, expected, launcher) { return this.call('repoint', port, { expected, launcher }); }
   enable(port, expected) { return this.call('enable', port, { expected }); }
   restore(port, expected, original) { return this.call('restore', port, { expected, original }); }
+
+  callAccess(operation, port, cliPath, input) {
+    if (process.platform !== 'win32') throw new Error('Legacy access checks are supported only for the known Windows 1.3 registration.');
+    const script = fileURLToPath(new URL('../autostart/windows/legacy-access.ps1', import.meta.url));
+    let output;
+    try {
+      output = execFileSync('pwsh', [
+        '-NoProfile', '-NonInteractive', '-File', script, '-Operation', operation, '-Port', String(port), '-CliPath', cliPath,
+      ], {
+        input: input ? JSON.stringify(input) : '', encoding: 'utf8',
+        windowsHide: true, timeout: 30000, maxBuffer: 1024 * 1024,
+      });
+    } catch (error) {
+      let reply;
+      try { reply = JSON.parse(String(error.stdout ?? '')); } catch { throw error; }
+      throw Object.assign(new Error(String(reply.error)), { changed: Array.isArray(reply.changed) ? reply.changed : [] });
+    }
+    return JSON.parse(output);
+  }
+
+  // Read-only: what the ordinary runtime user cannot do to the task and bin/cli.mjs.
+  access(port, cliPath) { return this.callAccess('inspect', port, cliPath); }
+  // Elevated only: fixes the gaps reported by access(), bound to its returned descriptors.
+  grantAccess(port, cliPath, expected) { return this.callAccess('grant', port, cliPath, { expected }); }
   assertRestored(port, actual, original) {
     const { xml: actualXml, xmlSha256: actualHash, ...actualFields } = actual;
     const { xml: originalXml, xmlSha256: originalHash, ...originalFields } = original;

package/bin/legacy-upgrade.mjs

@@ -1,21 +1,22 @@
 import { randomUUID } from 'node:crypto';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isDeepStrictEqual } from 'node:util';
+import semver from 'semver';
 import {
   acquireInstanceLock, createInstance, directoryIdentity, durableJson,
   readInstanceState, readManagedJson, readRecoveryContext, snapshotPackage, verifySelection,
   legacyMigrationPhases,
 } from './managed-state.mjs';
 import { inspectInstance, listenerOpen, startInstance, stopInstance } from './managed-runtime.mjs';
-import { PoolingFiles } from './pooling-files.mjs';
+import { MAX_CONFIG_BYTES, PoolingFiles } from './pooling-files.mjs';
 import { registerDefaultCli } from './cli-dispatch.mjs';
 import { servicePaths } from './service-control.mjs';
 import { WindowsLegacyTaskAdapter } from './legacy-task.mjs';
 import { requireUserRuntimeContext } from './runtime-context.mjs';
 import {
-  legacyPlanDigest, parseLegacyRegistration, requireLegacyApproval, verifyLegacyConfig, verifyLegacyListener, verifyLegacyPackage,
+  legacyPlanDigest, legacySessionState, parseLegacyRegistration, requireLegacyApproval, verifyLegacyConfig, verifyLegacyListener, verifyLegacyPackage,
 } from './legacy-installation.mjs';
 
 export const legacyPhases = legacyMigrationPhases;
@@ -148,6 +149,7 @@ export class LegacyUpgrader {
     await requireUserRuntimeContext();
     const approvalDigest = legacyPlanDigest(plan);
     requireLegacyApproval(plan);
+    this.requireSessionRecords(plan.instance.config, plan.to);
     this.verifySource(plan.instance, plan.legacy);
     await this.taskMatches(plan.instance, plan.legacy.registration);
     const operation = randomUUID();
@@ -174,6 +176,8 @@ export class LegacyUpgrader {
       const target = await this.stage({ ...plan, instance: { ...plan.instance, directory: work } }, operation);
       const capability = readManagedJson(join(target.root, 'bin', 'upgrade-capability.json'));
       if (capability.legacyRestartProtocol !== 1) throw new Error('Target does not support legacy restart recovery; old service was not touched.');
+      // The records can grow while the target downloads, so their size is checked again.
+      this.requireSessionRecords(plan.instance.config, target.version);
       const recovery = snapshotPackage(target.root, join(work, 'recovery'));
       verifySelection(recovery);
       this.verifySource(plan.instance, plan.legacy);
@@ -247,7 +251,12 @@ export class LegacyUpgrader {
       const legacyStop = await session.stop();
       this.transition(instance, journal, 'legacy-stopping', { legacyStop });
       this.assertPartialStop(legacyStop);
-      this.transition(instance, journal, 'legacy-stopped', { legacyStop });
+      // The 1.3 bridge has stopped, so its session records no longer change. An older target
+      // still compares them at admission.
+      const sessions = this.sessionRecords(instance.config);
+      this.transition(instance, journal, 'legacy-stopped', {
+        legacyStop, sessionState: sessions, legacy: { ...journal.legacy, sessions },
+      });
       return await this.activate(instance, journal);
     } catch (error) {
       if (journal &&
@@ -268,14 +277,53 @@ export class LegacyUpgrader {
     }
   }
 
+  // Targets before 2.1.1 compare session records when they start, reading at most 1 MiB of them.
+  comparesSessionRecords(version) {
+    const ignoresRecords = semver.valid(version) &&
+      semver.gte(version, '2.1.1');
+    return !ignoresRecords;
+  }
+
+  // Refuse such a target before anything is downloaded or stopped instead of restarting into a
+  // rollback. Only the size is checked, so a session starting or ending meanwhile cannot make
+  // this refuse.
+  requireSessionRecords(config, version) {
+    if (!this.comparesSessionRecords(version)) return;
+    const path = join(dirname(config), 'sessions.json');
+    const size = statSync(path, { throwIfNoEntry: false })?.size ?? 0;
+    if (size > MAX_CONFIG_BYTES) {
+      throw new Error(`Session records in ${path} are over 1 MiB, more than ${version} can compare when it starts. Upgrade to 2.1.1 or newer instead. Nothing was stopped.`);
+    }
+  }
+
+  // Records that could not be read after the stop would make such a target refuse admission,
+  // where rollback is no longer automatic. Refusing here, while the journal is still at
+  // `legacy-stopped`, restarts 1.3.
+  requireReadSessionRecords(config, journal) {
+    const unread = this.comparesSessionRecords(journal.target.version) &&
+      journal.sessionState === null &&
+      existsSync(join(dirname(config), 'sessions.json'));
+    if (unread) {
+      throw new Error(`Session records could not be read after the old version stopped, and ${journal.target.version} compares them when it starts.`);
+    }
+  }
+
+  // Read once the 1.3 bridge has stopped. A file the integrity helper refuses, such as one
+  // over 1 MiB, must not strand an upgrade whose old version is already down.
+  sessionRecords(config) {
+    try { return legacySessionState(config); }
+    catch { return null; }
+  }
+
+  // An upgrade may end the old bridge's sessions; only the supervisor and bridge must be proven
+  // stopped. A process the bridge started that could not be stopped is reported, not a refusal.
   assertPartialStop(receipt) {
     if (receipt?.legacyRootStopVerified !== true ||
-        receipt.observedDescendantsStopped !== true ||
+        typeof receipt.observedDescendantsStopped !== 'boolean' ||
         receipt.treeCompleteness !== 'unproven' ||
         !Array.isArray(receipt.errors) ||
-        receipt.errors.length ||
         'stopped' in receipt ||
-        'activeProcesses' in receipt) throw new Error('Legacy root/observed-set shutdown is incomplete. Registration remains held; no activation was authorized.');
+        'activeProcesses' in receipt) throw new Error('Legacy supervisor and bridge shutdown is not verified. Registration remains held; no activation was authorized.');
   }
 
   async verifyOldStopped(instance, journal) {
@@ -286,6 +334,7 @@ export class LegacyUpgrader {
   }
 
   async activate(instance, journal) {
+    this.requireReadSessionRecords(instance.config, journal);
     await this.verifyOldStopped(instance, journal);
     this.verifySource(instance, journal.legacy);
     await this.taskMatches(instance, journal.legacy.taskCurrent);
@@ -317,10 +366,16 @@ export class LegacyUpgrader {
     return {
       status: 'upgraded', directory: instance.directory, port: instance.port, version: journal.target.version,
       legacyStop: journal.legacyStop,
-      warning: 'Legacy HTTP outcomes were not certified or replayed. Historical orphan coverage is unproven; unattributed processes were left untouched.',
+      warning: this.stopWarning(journal.legacyStop),
     };
   }
 
+  stopWarning(receipt) {
+    const ended = 'Open 1.3 sessions and calls in progress were ended; clients reconnect. No call was retried.';
+    if (receipt.observedDescendantsStopped) return ended;
+    return `${ended} Not every process the 1.3 bridge started could be confirmed stopped; see legacyStop.errors.`;
+  }
+
   selectCli(instance, journal) {
     const cli = journal.legacy.cli;
     const files = new PoolingFiles(cli.path);
@@ -407,7 +462,8 @@ export class LegacyUpgrader {
     this.assertRestoredTask(instance.port, journal.legacy.taskCurrent, journal.legacy.registration);
     this.transition(instance, journal, 'legacy-rollback-launching');
     await this.task.start(instance.port, journal.legacy.taskCurrent);
-    const deadline = Date.now() + RESTART_OBSERVATION_MS;
+    const started = Date.now();
+    const deadline = started + RESTART_OBSERVATION_MS;
     let lastError;
     while (Date.now() < deadline) {
       try {
@@ -424,7 +480,7 @@ export class LegacyUpgrader {
       await new Promise(resolveWait => setTimeout(resolveWait, 100));
     }
     throw new Error('Legacy restart outcome is uncertain; retained code, task and journal require inspection.' +
-      (lastError ? ` Last observation after ${RESTART_OBSERVATION_MS} ms: ${lastError.message}` : ''),
+      (lastError ? ` Last observation after ${Date.now() - started} ms: ${lastError.message}` : ''),
       { cause: lastError });
   }
 

package/bin/managed-upgrade.mjs

@@ -1,15 +1,16 @@
 import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
+import semver from 'semver';
 import {
   acquireInstanceLock, createInstance, directoryIdentity, durableJson,
   loadInstance, readInstanceState, readRecoveryContext, readManagedJson, verifySelection,
 } from './managed-state.mjs';
 import { acquireUpgrade, configuredRegistry, exactVersion, unpackUpgrade, verifyArchive } from './upgrade-package.mjs';
 import { inspectInstance, listenerOpen, startInstance, stopInstance } from './managed-runtime.mjs';
-import { PoolingFiles, hasPoolingTransaction } from './pooling-files.mjs';
+import { MAX_CONFIG_BYTES, PoolingFiles, hasPoolingTransaction } from './pooling-files.mjs';
 import { inspectAutostart } from './upgrade-autostart.mjs';
 import { validateRegistry } from './update-check.mjs';
 import { servicePaths } from './service-control.mjs';
@@ -26,9 +27,10 @@ function sessionState(config) {
   return existsSync(path) ? new PoolingFiles(config).inspect(path) : null;
 }
 
+// Session records change whenever a client connects. An upgrade may end sessions, so only
+// the config is protected here.
 function verifyRollbackState(instance, journal) {
   new PoolingFiles(instance.config).verify(instance.config, journal.authority);
-  if (!same(sessionState(instance.config), journal.sessionState)) throw new Error('Persisted session state changed; rollback/activation refused.');
   if (hasPoolingTransaction(instance.config)) throw new Error('Config outcome is uncertain; automatic rollback refused.');
 }
 
@@ -105,9 +107,9 @@ export async function planUpgrade(options, { home, legacy, autostart: inspectSta
       affectedInstances: [prepared.legacy.backendInstanceId],
       autostart: { kind: 'legacy', name: prepared.legacy.registration.name },
       downtime: LEGACY_WARNING,
-      rollback: 'Only before target admission, with unchanged config/session authority and verified captured-root/observed-set stop. Uncertain launch, task or HTTP outcomes require explicit recovery.',
+      rollback: 'Only before target admission, with unchanged config and a verified supervisor and bridge stop. Uncertain launch or task outcomes require explicit recovery.',
       hostWiring: 'Unchanged. The same installed CLI entry will dispatch the selected managed version.',
-      legacyAdoption: 'One-time restart; tree completeness stays unproven. Unattributed historical processes are left untouched.',
+      legacyAdoption: 'One-time restart. A process the 1.3 bridge started that cannot be stopped is reported and left running.',
     };
   }
   if (instances.length !== 1) {
@@ -153,7 +155,7 @@ export function describeUpgrade(plan) {
 export class ManagedUpgrader {
   constructor({ acquire = acquireUpgrade, dependencies = stageCliDependencies, checkpoint = () => {}, legacy,
     autostart = inspectAutostart, beforeInterruption = async () => {},
-    beforeStop = async () => {}, beforeAdmission = async () => {} } = {}) {
+    beforeStop = async () => {}, beforeAdmission = async () => {}, afterRefusal = async () => {} } = {}) {
     this.acquire = acquire;
     this.dependencies = dependencies;
     this.checkpoint = checkpoint;
@@ -162,6 +164,7 @@ export class ManagedUpgrader {
     this.beforeInterruption = beforeInterruption;
     this.beforeStop = beforeStop;
     this.beforeAdmission = beforeAdmission;
+    this.afterRefusal = afterRefusal;
   }
 
   transition(directory, journal, phase, changes = {}) {
@@ -246,10 +249,10 @@ export class ManagedUpgrader {
         same(instanceBinding(source), instanceBinding(plan.instance));
       if (!matchesPlan) throw new Error('Managed selection changed after the plan; create a new plan.');
       assertNoPendingJournal(source);
+      if (!plan.options.sxs) this.requireSessionRecords(source.config, plan.to);
       await this.autostart(source);
       const current = await inspectInstance(source);
       if (current.unsafe) throw new Error('Unresolved transaction blocks upgrade.');
-      const sessions = sessionState(source.config);
       const target = await this.stage(plan, operation);
       verifySelection(target);
       const reloaded = loadInstance(source.directory, { verifyFiles: false });
@@ -259,11 +262,15 @@ export class ManagedUpgrader {
       if (plan.options.sxs) {
         return await this.startSxs(source, plan, target, operation);
       }
+      // The records can grow while the target downloads, so their size is checked again.
+      this.requireSessionRecords(source.config, target.version);
+      // Session records are read only after the old bridge stops; while it runs, every session
+      // start and end rewrites them.
       journal = {
         protocol: 1, operation, instanceId: source.id, previous: source.active, target,
         binding: instanceBinding(source),
         authority: current.authority, originalInstanceId: current.instanceId,
-        sessionState: sessions, launchToken: randomUUID(), phase: 'prepared',
+        sessionState: null, launchToken: randomUUID(), phase: 'prepared',
       };
       const backup = join(source.directory, 'staging', operation, 'servers.backup.json');
       new PoolingFiles(source.config).stage(backup, source.config, current.authority, readFileSync(source.config));
@@ -271,13 +278,12 @@ export class ManagedUpgrader {
       await this.beforeInterruption(source, journal);
       this.transition(destination, journal, 'prepared');
       this.transition(destination, journal, 'quiescing');
-      const drained = await inspectInstance(source, 'quiesce');
-      if (!same(drained.authority, journal.authority)) throw new Error('Configuration changed while staging; retry from a new plan.');
+      const drained = await this.quiesce(source, destination, journal);
       verifyRollbackState(source, journal);
       await this.beforeStop(source, journal);
       this.transition(destination, journal, 'stopping', { quiescedInstanceId: drained.instanceId });
       const stoppedProof = await stopInstance(source, drained.instanceId);
-      this.transition(destination, journal, 'stopped', { stoppedProof });
+      this.transition(destination, journal, 'stopped', { stoppedProof, sessionState: this.sessionRecords(source.config) });
       return await this.activate(destination, journal);
     } catch (error) {
       if (journal) {
@@ -294,6 +300,89 @@ export class ManagedUpgrader {
     }
   }
 
+  // A definite refusal releases the hold at once, as recovery would. Only an uncertain
+  // outcome, such as a lost reply, keeps admission held for explicit recovery.
+  async quiesce(source, destination, journal) {
+    try {
+      const drained = await inspectInstance(source, 'quiesce');
+      if (!same(drained.authority, journal.authority)) {
+        throw Object.assign(new Error('Configuration changed while staging; retry from a new plan.'), { refused: true });
+      }
+      return drained;
+    } catch (error) {
+      if (!error.refused) throw error;
+      await this.resumeRefused(source, error);
+      await this.releaseRefused(source, journal, error);
+      this.transition(destination, journal, 'aborted', { error: error.message });
+      throw new Error(`${error.message} Nothing was stopped; the current version is serving again.`, { cause: error });
+    }
+  }
+
+  // Config work that blocked the drain can still be settling, and resume refuses until it has,
+  // so resume is retried briefly. If it still refuses, admission stays held for recovery.
+  async resumeRefused(source, refusal) {
+    const deadline = Date.now() + 10000;
+    for (;;) {
+      try { return await inspectInstance(source, 'resume'); }
+      catch (error) {
+        if (!error.refused ||
+            Date.now() >= deadline) {
+          const state = error.refused ? 'stays paused' : 'may still be paused';
+          throw new Error(`${refusal.message} The current version ${state} until \`mcp-pacemaker upgrade --recover --instance ${source.directory} --yes\` succeeds.`, { cause: error });
+        }
+        await new Promise(resolveWait => setTimeout(resolveWait, 500));
+      }
+    }
+  }
+
+  // Whatever the caller held for the upgrade, such as an account's task, is released before the
+  // journal settles. If that fails, the journal stays at `quiescing` and recovery finishes it.
+  async releaseRefused(source, journal, refusal) {
+    try { await this.afterRefusal(source, journal); }
+    catch (error) {
+      throw new Error(`${refusal.message} Nothing was stopped and the current version is serving again. ${error.message} Run recovery to finish.`,
+        { cause: new AggregateError([refusal, error], refusal.message) });
+    }
+  }
+
+  // Targets before 2.1.1 compare session records when they start, reading at most 1 MiB of them.
+  comparesSessionRecords(version) {
+    const ignoresRecords = semver.valid(version) &&
+      semver.gte(version, '2.1.1');
+    return !ignoresRecords;
+  }
+
+  // Refuse such a target before anything is downloaded or stopped instead of restarting into a
+  // rollback. Only the size is checked, so a session starting or ending meanwhile cannot make
+  // this refuse.
+  requireSessionRecords(config, version) {
+    if (!this.comparesSessionRecords(version)) return;
+    const path = join(dirname(config), 'sessions.json');
+    const size = statSync(path, { throwIfNoEntry: false })?.size ?? 0;
+    if (size > MAX_CONFIG_BYTES) {
+      throw new Error(`Session records in ${path} are over 1 MiB, more than ${version} can compare when it starts. Upgrade to 2.1.1 or newer instead. Nothing was stopped.`);
+    }
+  }
+
+  // Records that could not be read after the stop would make such a target refuse admission,
+  // where rollback is no longer automatic. Refusing here, while the journal is still at
+  // `stopped`, rolls back to the previous version.
+  requireReadSessionRecords(config, journal) {
+    const unread = this.comparesSessionRecords(journal.target.version) &&
+      journal.sessionState === null &&
+      existsSync(join(dirname(config), 'sessions.json'));
+    if (unread) {
+      throw new Error(`Session records could not be read after the old version stopped, and ${journal.target.version} compares them when it starts.`);
+    }
+  }
+
+  // Read once the old bridge has stopped. A file the integrity helper refuses, such as one
+  // over 1 MiB, must not strand an upgrade whose old version is already down.
+  sessionRecords(config) {
+    try { return sessionState(config); }
+    catch { return null; }
+  }
+
   async startSxs(source, plan, target, operation) {
     const current = await inspectInstance(source);
     if (current.unsafe ||
@@ -340,6 +429,7 @@ export class ManagedUpgrader {
 
   async activate(directory, journal) {
     const instance = loadInstance(directory, { verifyFiles: false });
+    this.requireReadSessionRecords(instance.config, journal);
     verifyRollbackState(instance, journal);
     verifySelection(journal.target);
     this.transition(directory, journal, 'selecting');
@@ -479,7 +569,7 @@ export class ManagedUpgrader {
       if (journal.phase === 'stopping') {
         await this.beforeStop(instance, journal);
         const stoppedProof = await stopInstance(instance, journal.quiescedInstanceId);
-        this.transition(instance.directory, journal, 'stopped', { stoppedProof });
+        this.transition(instance.directory, journal, 'stopped', { stoppedProof, sessionState: this.sessionRecords(instance.config) });
       }
       if (['stopped', 'selecting', 'selected', 'launching',
         'rollback-selecting', 'rollback-selected', 'rollback-launching'].includes(journal.phase)) {