mcp-pacemaker 2.0.2 → 2.1.0

package/bin/mcp-bridge.mjs

@@ -32,6 +32,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve, extname } from 'node:path';
 import { homedir } from 'node:os';
 import { createInterface } from 'node:readline';
+import { isDeepStrictEqual } from 'node:util';
 import { checkServerPaths, checkReservedName } from './config-checks.mjs';
 import { ServerMetrics } from './server-metrics.mjs';
 import { MAX_MIN_WARM, hasPoolingTransaction, recoverPoolingConfig } from './pooling-config.mjs';
@@ -39,6 +40,28 @@ import { PoolingBatches } from './pooling-batches.mjs';
 import { POOLING_BUDGET_MS } from './pooling-execution.mjs';
 import { poolingTrace } from './pooling-trace.mjs';
 import { SharedSessionManager, SHARED_DEFAULTS } from './shared-sessions.mjs';
+import { ensureWindowsProcessLifetime } from './windows-process-lifetime.mjs';
+import { PoolingFiles } from './pooling-files.mjs';
+import { requireUserRuntimeContext } from './runtime-context.mjs';
+
+await requireUserRuntimeContext();
+// Assign the bridge before config can start pooled, shared, stdio or auth children.
+const windowsLifetime = await ensureWindowsProcessLifetime();
+if (windowsLifetime &&
+    process.connected &&
+    process.env.MCP_PACEMAKER_MANAGED_INSTANCE) {
+  await new Promise((resolveObserved, reject) => {
+    const timer = setTimeout(() => reject(new Error('Supervisor did not verify process lifetime ownership.')), 8000);
+    const observed = message => {
+      if (message !== 'upgrade-lifetime-observed') return;
+      clearTimeout(timer);
+      process.off('message', observed);
+      resolveObserved();
+    };
+    process.on('message', observed);
+    process.send({ type: 'upgrade-lifetime', lifetime: windowsLifetime });
+  });
+}
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const argv = process.argv.slice(2);
@@ -53,14 +76,25 @@ const defaultConfig = existsSync(localConfig) || hasPoolingTransaction(localConf
   ? resolve(process.cwd(), 'servers.json')
   : resolve(HOME, 'servers.json');
 const CONFIG = resolve(process.cwd(), getArg('--config', defaultConfig));
-const PORT = parseInt(getArg('--port', '8791'), 10);
+let PORT = Number(getArg('--port', '8791'));
 const HOST = getArg('--host', '127.0.0.1');
+let upgradeHeld = process.env.MCP_PACEMAKER_UPGRADE_PENDING === '1';
+let upgradeRequests = 0;
+let upgradeTraffic = false;
+let upgradeUncertain = false;
+if (PORT === 0 &&
+    (!process.connected || !process.env.MCP_PACEMAKER_MANAGED_INSTANCE || HOST !== '127.0.0.1')) {
+  throw new Error('Port 0 requires a managed loopback startup with actual-port readiness.');
+}
 const VERSION = (() => { try { return JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf8')).version; } catch { return '0'; } })();
 // Base working directory for relative server commands/args. Defaults to the config's folder.
 const BASE_CWD = resolve(getArg('--cwd', dirname(CONFIG)));
 
 /** @type {Record<string, any>} */
-if (hasPoolingTransaction(CONFIG)) recoverPoolingConfig(CONFIG);
+if (hasPoolingTransaction(CONFIG)) {
+  if (upgradeHeld) throw new Error('Unresolved config transaction blocks managed startup.');
+  recoverPoolingConfig(CONFIG);
+}
 const servers = JSON.parse(readFileSync(CONFIG, 'utf8'));
 const poolingConfig = new PoolingBatches({
   configPath: CONFIG,
@@ -1159,6 +1193,7 @@ function spawnWarm(name) {
   return child;
 }
 function refillPool(name) {
+  if (upgradeHeld) return;
   const target = poolTarget(name);
   if (!target ||
       shuttingDown) {
@@ -1224,7 +1259,8 @@ const resumable = new Map(); // sessionId -> { server, initialize, at }
 const resuming = new Map(); // sessionId -> handshake promise, before any asynchronous admission
 
 function saveResumable() {
-  if (!RESUME_ENABLED) return;
+  if (!RESUME_ENABLED ||
+      upgradeHeld) return;
   try { writeFileSync(RESUME_FILE, JSON.stringify(Object.fromEntries(resumable))); } catch { /* best effort */ }
 }
 // Records past the TTL are dropped. Without this the window was only ever applied when the file
@@ -1376,6 +1412,7 @@ function ensureRecycleTimer() {
   // Check often enough to honour the shortest configured period, but never busier than needed.
   const tick = Math.max(200, Math.min(30_000, (Math.min(...periods) * 60_000) / 2));
   recycleTimer = setInterval(() => {
+    if (upgradeHeld) return;
     const now = Date.now();
     for (const name of Object.keys(servers)) {
       const mins = recycleMinutesFor(name);
@@ -1515,6 +1552,7 @@ if (process.env.MCP_CONFIG_WATCH !== '0') {
       watcher = watch(CONFIG, () => {
         clearTimeout(timer);
         timer = setTimeout(() => {
+          if (upgradeHeld) { rearm(); return; }
           poolingConfig.reloadSaved('file changed')
             .catch(() => log('config watcher could not reload the saved configuration'))
             .finally(rearm);
@@ -1540,12 +1578,14 @@ if (process.env.MCP_CONFIG_WATCH !== '0') {
 const HEALTH_INTERVAL_MS = Number(process.env.MCP_HEALTH_INTERVAL_MS || 0);
 
 function probeServer(name) {
+  if (upgradeHeld) return;
   const def = servers[name];
   if (!def || def.type !== 'http' || !def.url) return;
   // A server the client authenticates cannot be probed usefully: the bridge holds no credential
   // for it, so every probe would 401 and report a working server as broken.
   if (!resolveAuth(def) && !def.headers) return;
   stat(name).lastProbe = Date.now();
+  upgradeRequests++;
   const body = JSON.stringify({
     jsonrpc: '2.0', id: `probe-${Date.now()}`, method: 'initialize',
     params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'mcp-pacemaker-health', version: VERSION } },
@@ -1568,7 +1608,8 @@ function probeServer(name) {
       r.setTimeout(10_000, () => { r.destroy(new Error('timed out')); });
       r.end(body);
     });
-  })().catch((e) => noteFailure(name, `health probe: ${e.message}`));
+  })().catch((e) => noteFailure(name, `health probe: ${e.message}`))
+    .finally(() => { upgradeRequests--; });
 }
 
 if (HEALTH_INTERVAL_MS > 0) {
@@ -1600,6 +1641,7 @@ if (TOKEN_REFRESH_LEAD_MS > 0) {
   // Check often enough to act inside the lead window, but no busier than that requires.
   const tick = Math.max(500, Math.min(60_000, TOKEN_REFRESH_LEAD_MS / 2));
   setInterval(() => {
+    if (upgradeHeld) return;
     const now = Date.now();
     for (const [name, def] of Object.entries(servers)) {
       const key = authCacheKey(def);
@@ -2046,6 +2088,24 @@ function proxyHttp(name, def, req, res) {
 const server = http.createServer((req, res) => {
   const url = new URL(req.url, `http://${req.headers.host}`);
   const [name, kind] = url.pathname.split('/').filter(Boolean);
+  const readOnlyStatus = (name === 'status' && !kind) ||
+    (name === 'api' && kind === 'status');
+  if (!readOnlyStatus) {
+    if (upgradeHeld) {
+      res.writeHead(503, { 'Retry-After': '2' }).end('Managed upgrade in progress; retry after the restart.');
+      return;
+    }
+    if (!['api', 'ui', '.well-known'].includes(name)) {
+      upgradeRequests++;
+      upgradeTraffic = true;
+      let finished = false;
+      res.once('finish', () => { finished = true; });
+      res.once('close', () => {
+        upgradeRequests--;
+        if (!finished) upgradeUncertain = true;
+      });
+    }
+  }
 
   if (name === 'status' && !kind) {
     res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -2133,12 +2193,80 @@ server.keepAliveTimeout = 65_000;
 server.headersTimeout = 70_000;
 
 server.listen(PORT, HOST, () => {
+  PORT = server.address().port;
   try { writeFileSync(NONCE_FILE, ADMIN_NONCE); } catch { /* noop */ }
   log(`listening on http://${HOST}:${PORT}  (config ${CONFIG}, base cwd ${BASE_CWD})`);
   log(`dashboard: http://${HOST}:${PORT}/ui  ·  api /api/status|/api/events|/api/logs  ·  admin nonce -> ${NONCE_FILE}`);
   for (const [n, d] of Object.entries(servers)) {
     log(`  ${n}  ->  ${d.type === 'http' ? `http proxy ${d.url}` : `stdio  /${n}/sse | /${n}/mcp`}`);
   }
+  if (process.connected) process.send({
+    type: 'upgrade-ready', protocol: 1, port: PORT, version: VERSION, instanceId, held: upgradeHeld,
+    lifetime: windowsLifetime,
+  });
+});
+
+function upgradeState() {
+  const pooling = poolingConfig.upgradeState();
+  const unsafe = upgradeUncertain ||
+    pooling.unsafe ||
+    hasPoolingTransaction(CONFIG);
+  const busy = pooling.busy ||
+    upgradeRequests > 0 ||
+    sessions.size > 0 ||
+    httpSessions.size > 0 ||
+    resuming.size > 0 ||
+    tokenInFlight.size > 0;
+  return { unsafe, busy, configBusy: pooling.busy, held: upgradeHeld, traffic: upgradeTraffic, port: PORT, version: VERSION, instanceId };
+}
+
+let upgradeControlBusy = false;
+process.on('message', async (message) => {
+  if (message?.type !== 'upgrade-control') return;
+  const reply = (result) => {
+    if (process.connected) process.send({ type: 'upgrade-result', requestId: message.requestId, ...result });
+  };
+  if (upgradeControlBusy) { reply({ ok: false, error: 'Admission operation already in progress.' }); return; }
+  upgradeControlBusy = true;
+  try {
+    if (message.action === 'quiesce') {
+      upgradeHeld = true;
+      const deadline = Date.now() + Math.min(8000, Math.max(0, message.timeoutMs ?? 8000));
+      while (upgradeState().busy &&
+          !upgradeState().unsafe &&
+          Date.now() < deadline) {
+        await new Promise(resolveWait => setTimeout(resolveWait, 25));
+      }
+      const state = upgradeState();
+      if (state.busy ||
+          state.unsafe) {
+        throw new Error('Active work or unresolved config transaction blocks upgrade. Settle work and retry; nothing was replayed.');
+      }
+    } else if (message.action === 'activate' ||
+        message.action === 'resume') {
+      if (upgradeState().unsafe) throw new Error('Unresolved config transaction prevents admission.');
+      if (message.action === 'activate') {
+        const files = new PoolingFiles(CONFIG);
+        const sessions = existsSync(RESUME_FILE) ? files.inspect(RESUME_FILE) : null;
+        if (!isDeepStrictEqual(files.inspect(CONFIG), message.expectedAuthority) ||
+            !isDeepStrictEqual(sessions, message.expectedSessionState)) {
+          throw new Error('Configuration or persisted session state changed before admission; the bridge remains held.');
+        }
+      } else {
+        await poolingConfig.reloadSaved('upgrade resumed');
+      }
+      upgradeHeld = false;
+      for (const name of Object.keys(servers)) refillPool(name);
+    } else if (message.action !== 'inspect') {
+      throw new Error('Unknown upgrade action.');
+    }
+    const authority = new PoolingFiles(CONFIG).inspect(CONFIG);
+    reply({ ok: true, ...upgradeState(), authority });
+  } catch (error) {
+    reply({ ok: false, error: error.message, ...upgradeState() });
+  } finally {
+    upgradeControlBusy = false;
+  }
 });
 
 // Ending the streams before exiting matters: a client that sees its SSE stream close cleanly

package/bin/pooling-batches.mjs

@@ -47,6 +47,19 @@ export class PoolingBatches {
     };
   }
 
+  upgradeState() {
+    const writer = this.#writer.upgradeState();
+    return {
+      busy: this.#queued > 0 ||
+        Boolean(this.#applying) ||
+        Boolean(this.#watchReload) ||
+        writer.pending > 0,
+      unsafe: writer.failed ||
+        Boolean(this.#pending) ||
+        [...this.#records.values()].some(record => !['applied', 'cancelled'].includes(record.status)),
+    };
+  }
+
   stage(request, options = {}) {
     if (this.#closed) return Promise.reject(this.#closedError());
     if (this.#queued >= 16) {

package/bin/pooling-writer.mjs

@@ -65,6 +65,10 @@ export class PoolingConfigWriter {
     this.#configPath = configPath;
   }
 
+  upgradeState() {
+    return { pending: this.#pending.size, failed: Boolean(this.#failure) };
+  }
+
   apply(request, options = {}) {
     return this.#send('apply', request, options);
   }

package/bin/prewarm.mjs

@@ -1,16 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-
-function portNumber(value) {
-  const port = Number(value);
-  if (!Number.isInteger(port) ||
-      port < 1 ||
-      port > 65535) {
-    throw new Error('Port must be an integer between 1 and 65535');
-  }
-  return port;
-}
+import { canonicalPort } from './cli-selection.mjs';
 
 async function jsonRequest(port, path, options = {}) {
   const response = await fetch(`http://127.0.0.1:${port}${path}`, {
@@ -118,25 +109,45 @@ function shellArgument(text) {
   return `'${text.replaceAll("'", "'\\''")}'`;
 }
 
-export function formatUndoCommand(port, name, undoId, config) {
+function windowsArgument(value) {
+  let result = '"';
+  let slashes = 0;
+  for (const character of value) {
+    if (character === '\\') {
+      slashes++;
+      continue;
+    }
+    result += '\\'.repeat(character === '"' ? slashes * 2 + 1 : slashes) + character;
+    slashes = 0;
+  }
+  return result + '\\'.repeat(slashes * 2) + '"';
+}
+
+export function formatUndoCommand(port, name, undoId, config, instance) {
+  port = canonicalPort(port);
   const executable = process.execPath;
   const entry = fileURLToPath(new URL('./cli.mjs', import.meta.url));
-  const values = [executable, entry, name, undoId, ...(config ? [config] : [])];
+  const values = [executable, entry, name, undoId, ...(config ? [config] : []), ...(instance ? [instance] : [])];
   const needsExplicitShell = process.platform === 'win32' &&
-    values.some((value) => /[%!$`"^\r\n]|\\$/.test(value));
+    (Boolean(instance) || values.some((value) => /[%!$`"^\r\n]|\\$/.test(value)));
   if (needsExplicitShell) {
     const quote = (value) => `'${value.replaceAll("'", "''")}'`;
-    const configArg = config ? ` --config ${quote(config)}` : '';
-    const command = `& ${quote(executable)} ${quote(entry)} prewarm --port ${port}${configArg} --server ${quote(name)} --undo ${quote(undoId)}`;
+    const argumentsList = [entry, ...(instance ? ['--instance', instance] : []),
+      'prewarm', '--port', String(port), ...(config ? ['--config', config] : []), '--server', name, '--undo', undoId];
+    const commandLine = argumentsList.map(windowsArgument).join(' ');
+    const command = `$info = New-Object System.Diagnostics.ProcessStartInfo; $info.FileName = ${quote(executable)}; ` +
+      `$info.UseShellExecute = $false; $info.Arguments = ${quote(commandLine)}; ` +
+      '$child = [System.Diagnostics.Process]::Start($info); $child.WaitForExit(); exit $child.ExitCode';
     return `powershell.exe -NoProfile -NonInteractive -EncodedCommand ${Buffer.from(command, 'utf16le').toString('base64')}`;
   }
   const configArg = config ? ` --config ${shellArgument(config)}` : '';
+  const instanceArg = instance ? ` --instance ${shellArgument(instance)}` : '';
   const node = process.platform === 'win32' ? 'node.exe' : shellArgument(executable);
-  return `${node} ${shellArgument(entry)} prewarm --port ${port}${configArg} --server ${shellArgument(name)} --undo ${undoId}`;
+  return `${node} ${shellArgument(entry)}${instanceArg} prewarm --port ${port}${configArg} --server ${shellArgument(name)} --undo ${instance ? shellArgument(undoId) : undoId}`;
 }
 
-export async function runPrewarm(options, { configPath, ports, write = console.log } = {}) {
-  const selectedPorts = options.port ? [portNumber(options.port)] : ports.map(portNumber);
+export async function runPrewarm(options, { configPath, ports, instance, write = console.log } = {}) {
+  const selectedPorts = options.port === undefined ? ports.map(canonicalPort) : [canonicalPort(options.port)];
   const actionCount = [options.enable, options.disable, options.undo].filter(Boolean).length;
   if (actionCount > 1) throw new Error('Choose only one of --enable, --disable or --undo');
   if (actionCount &&
@@ -156,6 +167,7 @@ export async function runPrewarm(options, { configPath, ports, write = console.l
   for (const port of selectedPorts) {
     const { body: snapshot } = await jsonRequest(port, '/api/status');
     if (snapshot.service !== 'mcp-pacemaker') throw new Error(`:${port} is not a pacemaker bridge`);
+    if (snapshot.port !== port) throw new Error('Bridge reported a different port; no admin nonce was sent.');
     snapshots.push(snapshot);
   }
 
@@ -194,7 +206,7 @@ export async function runPrewarm(options, { configPath, ports, write = console.l
       typeof snapshot.prewarm.saveWarning === 'string') {
     write(`File save notice: ${snapshot.prewarm.saveWarning}`);
   }
-  const response = await jsonRequest(snapshot.port, `/admin/servers/${encodeURIComponent(name)}/pooling`, {
+  const response = await jsonRequest(selectedPorts[0], `/admin/servers/${encodeURIComponent(name)}/pooling`, {
     method: 'POST',
     headers: { 'content-type': 'application/json', 'x-mcp-nonce': nonce, 'x-mcp-pooling-batch': '1' },
     body: JSON.stringify(body),
@@ -220,14 +232,14 @@ export async function runPrewarm(options, { configPath, ports, write = console.l
     else action = 'pre-warming disable staged';
     write(`${name}: ${action}. Pending reload${timing}; not active yet.`);
     if (result.undoId) {
-      write(`Cancel while pending / undo after apply (entire batch: ${scope}): ${formatUndoCommand(snapshot.port, name, result.undoId, options.config)}`);
+      write(`Cancel while pending / undo after apply (entire batch: ${scope}): ${formatUndoCommand(selectedPorts[0], name, result.undoId, options.config, instance)}`);
     }
   } else if (result.cancelled) {
     write(`${name}: pending batch cancelled. Active settings were not changed.`);
   } else {
     write(`${name}: ${options.undo ? 'restored previous pooling settings' : body.mode === 'pool' ? `enabled ${body.minWarm} warm slot(s)` : 'disabled pre-warming'}`);
     if (result.undoId) {
-      write(`Undo: ${formatUndoCommand(snapshot.port, name, result.undoId, options.config)}`);
+      write(`Undo: ${formatUndoCommand(selectedPorts[0], name, result.undoId, options.config, instance)}`);
     }
   }
 }

package/bin/runtime-context.mjs

@@ -0,0 +1,100 @@
+import { closeSync, openSync, readSync } from 'node:fs';
+import { requireOrdinaryUpgradeCaller } from './windows-task-channel.mjs';
+
+export class UserRuntimeContext {
+  constructor({ host = process, linuxStatus, windowsCheck = requireOrdinaryUpgradeCaller } = {}) {
+    this.host = host;
+    this.linuxStatus = linuxStatus ?? (() => this.readLinuxStatus());
+    this.windowsCheck = windowsCheck;
+  }
+
+  refuse(reason, code = 'USER_RUNTIME_CONTEXT_UNVERIFIED') {
+    throw Object.assign(new Error(`User-runtime execution refused: ${reason}. No identity or privilege change was attempted.`),
+      { code });
+  }
+
+  identity() {
+    const value = {};
+    for (const [name, method] of [['uid', 'getuid'], ['euid', 'geteuid'], ['gid', 'getgid'], ['egid', 'getegid']]) {
+      if (typeof this.host[method] !== 'function') this.refuse('effective identity is unavailable');
+      value[name] = this.host[method]();
+      if (!Number.isSafeInteger(value[name]) ||
+          value[name] < 0 ||
+          value[name] > 0xffffffff) this.refuse('effective identity is invalid');
+    }
+    if (value.uid === 0 ||
+        value.euid === 0) this.refuse("run this operation from the installation owner's non-root session", 'USER_RUNTIME_PRIVILEGED');
+    if (value.uid !== value.euid ||
+        value.gid !== value.egid) this.refuse('real and effective identities differ', 'USER_RUNTIME_PRIVILEGED');
+    return value;
+  }
+
+  readLinuxStatus() {
+    const buffer = Buffer.alloc(16385);
+    const file = openSync('/proc/self/status', 'r');
+    try {
+      let length = 0;
+      while (length < buffer.length) {
+        const read = readSync(file, buffer, length, buffer.length - length, null);
+        if (read === 0) break;
+        length += read;
+      }
+      if (length > 16384) this.refuse('Linux process status exceeds its bound');
+      return buffer.toString('utf8', 0, length);
+    } finally { closeSync(file); }
+  }
+
+  capabilities(status, identity) {
+    if (typeof status !== 'string' ||
+        Buffer.byteLength(status) > 16384) this.refuse('Linux process status is invalid');
+    const lines = status.split('\n');
+    for (const [name, expected] of [['Uid', identity.uid], ['Gid', identity.gid]]) {
+      const selected = lines.filter(line => line.startsWith(`${name}:`));
+      if (selected.length !== 1) this.refuse(`Linux ${name} observation is unavailable`);
+      const fields = selected[0].slice(name.length + 1).trim().split(/\s+/);
+      if (fields.length !== 4 ||
+          fields.some(field => !/^(0|[1-9][0-9]*)$/.test(field) || Number(field) !== expected)) {
+        this.refuse(`Linux real, effective, saved or filesystem ${name} differs`, 'USER_RUNTIME_PRIVILEGED');
+      }
+    }
+    const capabilities = {};
+    for (const name of ['CapInh', 'CapPrm', 'CapEff', 'CapAmb']) {
+      const selected = lines.filter(line => line.startsWith(`${name}:`));
+      if (selected.length !== 1) this.refuse(`Linux ${name} observation is unavailable`);
+      const value = selected[0].slice(name.length + 1).trim();
+      if (!/^[0-9a-fA-F]{16}$/.test(value)) this.refuse(`Linux ${name} observation is invalid`);
+      if (BigInt(`0x${value}`) !== 0n) this.refuse(`Linux ${name} contains privileges`, 'USER_RUNTIME_PRIVILEGED');
+      capabilities[name] = value.toLowerCase();
+    }
+    return capabilities;
+  }
+
+  async require() {
+    if (this.host.platform === 'win32') {
+      const proof = await this.windowsCheck();
+      if (proof?.ordinaryEligible !== true ||
+          proof.proofScope !== 'cli-effective-context-snapshot') this.refuse('Windows caller proof is unavailable');
+      return { platform: 'win32', proofScope: 'user-runtime-context-snapshot', ordinary: true,
+        native: proof, atomicFutureProtection: false };
+    }
+    if (!['linux', 'darwin'].includes(this.host.platform)) this.refuse('this platform has no supported identity observer');
+    const before = this.identity();
+    let capabilities;
+    if (this.host.platform === 'linux') {
+      try { capabilities = this.capabilities(this.linuxStatus(), before); }
+      catch (error) {
+        if (error.code?.startsWith('USER_RUNTIME_')) throw error;
+        throw Object.assign(new Error('User-runtime execution refused: Linux process status could not be read.', { cause: error }),
+          { code: 'USER_RUNTIME_CONTEXT_UNVERIFIED' });
+      }
+    }
+    const after = this.identity();
+    if (Object.keys(before).some(name => before[name] !== after[name])) this.refuse('effective identity changed during observation');
+    return { platform: this.host.platform, proofScope: 'user-runtime-context-snapshot', ordinary: true,
+      identity: after, ...(capabilities ? { capabilities } : {}), atomicFutureProtection: false };
+  }
+}
+
+export async function requireUserRuntimeContext() {
+  return new UserRuntimeContext().require();
+}

package/bin/service-control.mjs

@@ -21,6 +21,7 @@ export function servicePaths(config, port) {
   return {
     record: join(directory, `service-${port}.json`),
     hold: join(directory, `service-${port}.stopped`),
+    admissionHold: join(directory, `service-${port}.admission-held`),
     socket,
   };
 }
@@ -90,7 +91,7 @@ export function requestService(socket, request) {
   });
 }
 
-export async function stopManagedService({ root, config, port, request = requestService }) {
+export async function stopManagedService({ root, config, port, quiescedInstanceId, request = requestService }) {
   const paths = servicePaths(config, port);
   let record;
   try {
@@ -99,6 +100,7 @@ export async function stopManagedService({ root, config, port, request = request
     if (error.code !== 'ENOENT') throw error;
     throw new Error(`No managed supervisor record for :${port}. Older or direct bridges require verified OS-service shutdown and disabled autostart; no process was stopped.`);
   }
+
   validateServiceRecord(record, { root, config, port });
   let receipt;
   try {
@@ -110,15 +112,36 @@ export async function stopManagedService({ root, config, port, request = request
     receipt.id === record.id &&
     receipt.root === record.root &&
     receipt.config === record.config &&
-    receipt.port === record.port;
+    receipt.port === record.port &&
+    (quiescedInstanceId === undefined || receipt.quiescedInstanceId === quiescedInstanceId);
   if (completed) {
     return { root: record.root, config: record.config, port, supervisorId: record.id, alreadyStopped: true };
   }
-  const response = await request(paths.socket, { action: 'stop', id: record.id, token: record.token });
+  const response = await request(paths.socket, { action: 'stop', id: record.id, token: record.token,
+    ...(quiescedInstanceId ? { quiescedInstanceId } : {}) });
   if (response?.id !== record.id ||
       response.stopped !== true ||
-      response.autostartHeld !== true) {
+      response.autostartHeld !== true ||
+      (quiescedInstanceId !== undefined && response.quiescedInstanceId !== quiescedInstanceId)) {
     throw new Error('Supervisor did not verify shutdown and its autostart hold. Do not replace the installation root.');
   }
   return { root: record.root, config: record.config, port, supervisorId: record.id };
 }
+
+export async function controlManagedService({ root, config, port }, action, expected = {}) {
+  const record = validateServiceRecord(
+    JSON.parse(readFileSync(servicePaths(config, port).record, 'utf8')), { root, config, port });
+  if (record.upgradeProtocol !== 1) {
+    throw new Error('This supervisor has no managed admission protocol. Legacy migration requires exact OS-service inspection; no process was stopped.');
+  }
+  const response = await requestService(record.socket, {
+    id: record.id, token: record.token, action,
+    expectedAuthority: expected.authority, expectedSessionState: expected.sessionState,
+  });
+  if (response.id !== record.id ||
+      response.ok !== true ||
+      response.instanceId !== record.instanceId ||
+      response.version !== record.version ||
+      response.port !== port) throw new Error(response.error || 'Managed bridge identity/admission could not be verified.');
+  return response;
+}

package/bin/stable-launcher.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { fork } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { durableJson, loadInstance, readManagedJson } from './managed-state.mjs';
+
+const directory = dirname(fileURLToPath(import.meta.url));
+const instance = loadInstance(directory);
+let boundPort = instance.port;
+const journalPath = join(directory, 'journal.json');
+if (existsSync(journalPath)) {
+  const journal = readManagedJson(journalPath);
+  const legacyStart = journal.phase === 'legacy-launching' &&
+    journal.legacy?.protocol === 1 &&
+    journal.legacy.acknowledged === 'restart-with-uncertain-http-and-partial-tree-v1';
+  const authorizedStart = (['launching', 'rollback-launching'].includes(journal.phase) || legacyStart) &&
+    journal.launchToken === process.env.MCP_PACEMAKER_UPGRADE_TOKEN &&
+    process.env.MCP_PACEMAKER_UPGRADE_PENDING === '1';
+  if (!['committed', 'rolled-back', 'aborted'].includes(journal.phase) &&
+      !authorizedStart) {
+    throw new Error('Upgrade recovery required; stable autostart remains held. Run upgrade --recover --instance <directory>.');
+  }
+}
+if (existsSync(join(directory, 'stopped'))) {
+  console.log('Managed instance is held stopped. Use an explicit start.');
+} else {
+  const child = fork(join(instance.active.root, 'supervisor', 'supervise.mjs'), [
+    '--port', String(instance.port), '--config', instance.config, '--cwd', instance.cwd,
+  ], {
+    execPath: instance.node, execArgv: [], windowsHide: true,
+    stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+    env: { ...process.env, MCP_PACEMAKER_MANAGED_INSTANCE: directory },
+  });
+  child.on('message', (message) => {
+    if (message?.type === 'supervisor-ready' &&
+        boundPort === 0) {
+      const current = readManagedJson(join(directory, 'instance.json'));
+      if (current.id !== instance.id ||
+          current.port !== 0) throw new Error('Managed port identity changed during allocation.');
+      durableJson(join(directory, 'instance.json'), { ...current, port: message.port });
+      boundPort = message.port;
+    }
+    if (message?.type === 'supervisor-ready' &&
+        message.port !== boundPort) throw new Error('Managed restart changed the persisted listener port.');
+    if (process.connected) process.send(message);
+  });
+  process.on('message', (message) => { if (child.connected) child.send(message); });
+  const shutdown = () => { if (child.connected) child.send('stop'); };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+  child.on('error', (error) => { console.error(error.message); process.exitCode = 1; });
+  child.on('exit', (code) => { process.exitCode = code ?? 1; if (process.connected) process.disconnect(); });
+}