mcp-pacemaker 2.0.1 → 2.1.0

package/bin/task-only-controller.mjs

@@ -0,0 +1,226 @@
+import { isDeepStrictEqual } from 'node:util';
+import { dirname } from 'node:path';
+import { durableJson } from './managed-state.mjs';
+import { canonicalJson, ControllerSignatures, operationDigest, peerBinding, taskRevision, validateTaskRequest, verifyTargetSession } from './task-transaction-protocol.mjs';
+import { authorizeTaskActor } from './task-scope.mjs';
+import { LEGACY_WARNING } from './legacy-installation.mjs';
+
+export function workerTaskRecord(record, targetSid) {
+  return { ...record, currentUserSid: targetSid };
+}
+
+export function minimalTaskRecord(record) {
+  return {
+    name: record.name, enabled: record.enabled, user: record.runAsName ?? record.userSid,
+    logonType: record.logonType, runLevel: record.runLevel, actions: record.actions,
+  };
+}
+
+export class TaskOnlyController {
+  constructor({ binding, original, initial = original, task, channel,
+    signatures = new ControllerSignatures(), confirm, journalPath }) {
+    this.binding = structuredClone(binding);
+    this.original = structuredClone(original);
+    this.current = structuredClone(initial);
+    this.initial = structuredClone(initial);
+    this.task = task;
+    this.channel = channel;
+    this.targetSession = verifyTargetSession(channel.targetSession, { ownerSid: binding.targetSid, sessionId: binding.sessionId });
+    this.signatures = signatures;
+    this.confirm = confirm;
+    this.journalPath = journalPath;
+    this.sequence = 0;
+    this.phase = 'new';
+    this.digest = operationDigest(binding);
+    this.stateDigest = this.digest;
+    this.history = [];
+  }
+
+  save(phase) {
+    this.phase = phase;
+    this.stateDigest = operationDigest({ operationId: this.binding.operationId, phase, sequence: this.sequence,
+      taskRevision: taskRevision(this.current) });
+    if (this.journalPath) durableJson(this.journalPath, {
+      protocol: 1, binding: this.binding, original: this.original, initial: this.initial, current: this.current,
+      phase, sequence: this.sequence, stateDigest: this.stateDigest, history: this.history, peer: this.peer ?? null,
+      targetSession: this.targetSession,
+    });
+  }
+
+  async verifyTask() {
+    const result = await this.channel.authorize();
+    authorizeTaskActor(result.actorFacts, this.binding.targetSid);
+    this.targetSession = verifyTargetSession(result.targetSession, this.targetSession);
+    const actual = (await this.task.inspect()).record;
+    if (taskRevision(actual) !== taskRevision(this.current)) throw new Error('Approved task revision or full security changed.');
+    return actual;
+  }
+
+  assertPreserved(record) {
+    if (record.path !== this.original.path ||
+        record.userSid !== this.binding.targetSid ||
+        record.logonType !== this.original.logonType ||
+        record.runLevel !== this.original.runLevel ||
+        !isDeepStrictEqual(record.security, this.original.security)) throw new Error('Task operation changed its sealed account or full security.');
+  }
+
+  async mutate(action, phase) {
+    await this.verifyTask();
+    this.save(`${phase}-intent`);
+    const args = [this.current, this.original];
+    if (action === 'bootstrap') args.push(this.binding.bootstrapTask);
+    if (action === 'repoint') args.push(this.binding.launcher);
+    const result = await this.task[action](...args);
+    this.assertPreserved(result);
+    this.current = result;
+    this.history.push({ phase, revision: taskRevision(result) });
+    if (this.history.length > 16) throw new Error('Task transaction exceeded its transition bound.');
+    this.save(phase);
+  }
+
+  async restoreInitial(phase) {
+    try {
+      await this.verifyTask();
+      this.save(`${phase}-intent`);
+      const restored = await this.task.restore(this.current, this.initial);
+      this.assertPreserved(restored);
+      if (taskRevision(restored) !== taskRevision(this.initial)) throw new Error('Pre-bootstrap task revision was not restored exactly.');
+      this.current = restored;
+      this.save(phase);
+    } catch (error) {
+      const evidence = this.journalPath ? dirname(this.journalPath) : this.binding.manifestPath;
+      throw new Error(`Automatic task restoration did not verify. Preserve the protected manifest and controller journal at ${JSON.stringify(evidence)}. ` +
+        `Manual verified restoration of ${JSON.stringify(this.initial.path)} to its saved pre-bootstrap revision is required. ` +
+        'There is no controller-operation-only recovery command: without a published instance, --instance cannot recover this state, and --task --recover is unsupported. ' +
+        'Do not create target state or relax task security/session checks. ' + error.message, { cause: error });
+    }
+  }
+
+  async accept(packet) {
+    if (canonicalJson(peerBinding(packet.peer)) !== canonicalJson(this.peer)) throw new Error('Worker connection identity changed.');
+    const request = validateTaskRequest(packet.frame, this.binding.operationId, this.sequence,
+      this.sequence === 0 ? this.digest : this.stateDigest);
+    let body;
+    switch (request.verb) {
+      case 'HELLO':
+        if (this.phase !== 'bootstrap' ||
+            canonicalJson(peerBinding(request.body.identity)) !== canonicalJson(this.peer)) throw new Error('Worker hello does not match its held OS identity.');
+        this.challenge = request.body.challenge;
+        await this.verifyTask();
+        this.save('authenticated');
+        body = { ok: true, original: workerTaskRecord(this.original, this.binding.targetSid) };
+        break;
+      case 'PLAN': {
+        if (this.phase !== 'authenticated') throw new Error('Plan approval cannot be repeated.');
+        const message = [
+          `Approve ${this.binding.recover ? 'recovery' : 'upgrade'} for the sealed task ${JSON.stringify(this.binding.taskPath)}?`,
+          `Original account: ${this.binding.targetSid}; port ${this.binding.port}; ${JSON.stringify(this.binding.from)} -> ${JSON.stringify(this.binding.to)}.`,
+          this.binding.kind === 'legacy' ? LEGACY_WARNING : 'Managed admission and verified shutdown remain required.',
+          `Worker plan digest: ${request.body.digest}`,
+        ].join('\n');
+        const approved = await this.confirm(message);
+        if (approved !== true) {
+          await this.restoreInitial('cancelled');
+          this.result = { status: 'cancelled', directory: this.binding.destination, port: this.binding.port };
+          body = { approved: false, digest: request.body.digest };
+          break;
+        }
+        await this.verifyTask();
+        this.approvedPlan = request.body.digest;
+        this.save('approved');
+        body = { approved: true, digest: request.body.digest };
+        break;
+      }
+      case 'INSPECT':
+        await this.verifyTask();
+        body = { record: workerTaskRecord(this.current, this.binding.targetSid), phase: this.phase };
+        break;
+      case 'HOLD':
+        if (!['approved', 'held', 'selected', 'released'].includes(this.phase)) throw new Error('Task hold is not authorized in this phase.');
+        if (this.phase === 'approved' || this.phase === 'held') {
+          await this.verifyTask();
+          this.save('held');
+        } else await this.mutate('hold', 'held');
+        body = { record: workerTaskRecord(this.current, this.binding.targetSid), holdKind: 'automatic-triggers' };
+        break;
+      case 'REPOINT':
+        if (this.phase !== 'held') throw new Error('Managed task selection requires a verified hold.');
+        await this.mutate('repoint', 'selected');
+        body = { record: workerTaskRecord(this.current, this.binding.targetSid) };
+        break;
+      case 'ENABLE':
+        if (this.phase !== 'selected') throw new Error('Task release requires the sealed managed launcher.');
+        await this.mutate('release', 'released');
+        body = { record: workerTaskRecord(this.current, this.binding.targetSid) };
+        break;
+      case 'RESTORE':
+        if (!['authenticated', 'approved', 'held', 'selected', 'released'].includes(this.phase)) throw new Error('Task restoration outcome is uncertain.');
+        await this.mutate('restore', 'restored');
+        body = { record: workerTaskRecord(this.current, this.binding.targetSid) };
+        break;
+      case 'RECORDS':
+        await this.verifyTask();
+        body = { records: [minimalTaskRecord(this.current)] };
+        break;
+      case 'DONE':
+        if (!['released', 'restored'].includes(this.phase) ||
+            request.body.directory !== this.binding.destination ||
+            request.body.port !== this.binding.port ||
+            ![this.binding.to, this.binding.from].includes(request.body.version)) throw new Error('Completion is outside the sealed installation.');
+        await this.verifyTask();
+        this.result = request.body;
+        this.save('completed');
+        body = { accepted: true };
+        break;
+      case 'FAILED':
+        if (['authenticated', 'approved'].includes(this.phase)) await this.restoreInitial('restored');
+        this.failure = new Error(`Original-account worker failed; ${this.phase === 'restored' ? 'original task restored' : 'explicit recovery required'}.`);
+        this.save(this.phase === 'restored' ? 'failed-restored' : 'uncertain');
+        body = { accepted: true };
+        break;
+      default: throw new Error('Unsupported task request.');
+    }
+    const response = this.signatures.response({
+      operationId: this.binding.operationId, digest: this.digest, challenge: this.challenge, peer: this.peer,
+      targetSession: this.targetSession,
+      sequence: this.sequence, request, stateDigest: this.stateDigest, body,
+    });
+    this.sequence++;
+    return response;
+  }
+
+  async run() {
+    let authenticated = false;
+    try {
+      await this.mutate('bootstrap', 'bootstrap');
+      await this.verifyTask();
+      const launch = await this.task.launch(this.current, this.binding.sessionId);
+      this.launchCorrelation = launch.instanceGuid;
+      this.peer = peerBinding(await this.channel.awaitWorker());
+      this.targetSession = verifyTargetSession(this.channel.workerSession, this.targetSession);
+      if (this.peer.ownerSid !== this.binding.targetSid ||
+          this.peer.sessionId !== this.binding.sessionId) throw new Error('Worker account/session did not verify.');
+      while (!this.result && !this.failure) {
+        const packet = await this.channel.receive();
+        const response = await this.accept(packet);
+        await this.channel.send(response);
+        authenticated = Boolean(this.challenge);
+      }
+      if (this.failure) throw this.failure;
+      return this.result;
+    } catch (error) {
+      let failure = error;
+      if (!authenticated && this.phase === 'bootstrap') {
+        try { await this.restoreInitial('restored-bootstrap'); }
+        catch (restoreError) {
+          this.save('uncertain');
+          failure = new AggregateError([error, restoreError], restoreError.message);
+        }
+      } else if (!['completed', 'failed-restored', 'restored', 'cancelled'].includes(this.phase)) this.save('uncertain');
+      throw failure;
+    } finally {
+      this.signatures.key = undefined;
+      await this.channel.close();
+    }
+  }
+}

package/bin/task-scope.mjs

@@ -0,0 +1,65 @@
+import { canonicalSid } from './task-transaction-protocol.mjs';
+
+export function managementScope(args) {
+  let targetSid;
+  let taskPath;
+  let instance;
+  let controllerRoot = false;
+  const remaining = [];
+  for (let index = 0; index < args.length; index++) {
+    const argument = args[index];
+    if (argument === '--') { remaining.push(...args.slice(index)); break; }
+    if (argument === '--all-users' || argument.startsWith('--all-users=')) {
+      throw new Error('--all-users is not implemented. Installation and implicit discovery default to the current user.');
+    }
+    const key = ['--user', '--task', '--instance'].find(option => argument === option || argument.startsWith(`${option}=`));
+    if (!key) {
+      if (argument === '--controller-root' || argument.startsWith('--controller-root=')) controllerRoot = true;
+      remaining.push(argument);
+      if (['--to', '--registry', '--port', '--config', '--from', '--client', '--grep', '--server', '--controller-root'].includes(argument) &&
+          index + 1 < args.length) {
+        if (args[index + 1] === '--') { remaining.push(...args.slice(index + 1)); break; }
+        remaining.push(args[++index]);
+      }
+      continue;
+    }
+    const value = argument === key ? args[++index] : argument.slice(key.length + 1);
+    if (!value || value.startsWith('-') || value.length > 4096 || /[\u0000-\u001f\u007f]/.test(value)) throw new Error(`Invalid ${key} selector.`);
+    if (key === '--user') {
+      canonicalSid(value);
+      if (targetSid && targetSid !== value) throw new Error('Conflicting target users.');
+      targetSid = value;
+    } else if (key === '--task') {
+      if (!value.startsWith('\\') || value.includes('/') || value.split('\\').some((part, i) => i > 0 && (!part || part === '.' || part === '..'))) {
+        throw new Error('An exact absolute Task Scheduler path is required.');
+      }
+      if (taskPath && taskPath !== value) throw new Error('Conflicting task selectors.');
+      taskPath = value;
+    } else {
+      if (instance && instance !== value) throw new Error('Conflicting instance selectors.');
+      instance = value;
+      remaining.push('--instance', value);
+    }
+  }
+  if (targetSid || taskPath) {
+    if (!targetSid || Boolean(taskPath) === Boolean(instance)) throw new Error('Explicit user management requires --user <SID> and exactly one --task <path> or --instance <directory>.');
+    if (remaining[0] !== 'upgrade' && !remaining.includes('upgrade')) throw new Error('Explicit user/task scope currently supports upgrade only.');
+    if (remaining.includes('--sxs') || remaining.includes('--self')) throw new Error('Explicit account management does not support SxS or guidance mode.');
+  }
+  if (controllerRoot && !targetSid) throw new Error('--controller-root is only for explicit account management.');
+  return { targetSid, taskPath, instance, explicit: targetSid !== undefined, args: remaining };
+}
+
+export function authorizeTaskActor(actor, targetSid) {
+  canonicalSid(targetSid);
+  canonicalSid(actor.ownerSid);
+  if (targetSid === actor.ownerSid) return 'current-user';
+  const admin = actor.elevated === true &&
+    actor.enabledAdministrator === true &&
+    actor.restricted === false &&
+    actor.appContainer === false &&
+    actor.guardThreadImpersonating === false &&
+    actor.parentThreadImpersonation === 'observed-none';
+  if (!admin) throw new Error('Another user requires an already-elevated administrator token with verified enabled membership and no restricted/AppContainer/observed impersonation context. No elevation or privilege change was attempted.');
+  return 'explicit-other-user';
+}

package/bin/task-transaction-protocol.mjs

@@ -0,0 +1,173 @@
+import { createHash, createPublicKey, generateKeyPairSync, randomBytes, sign, verify } from 'node:crypto';
+
+const domain = 'mcp-pacemaker/task-only-controller/v1';
+const verbs = new Set(['HELLO', 'PLAN', 'INSPECT', 'HOLD', 'REPOINT', 'RESTORE', 'ENABLE', 'RECORDS', 'DONE', 'FAILED']);
+export const accountRecoveryTerminalPhases = Object.freeze(['committed', 'rolled-back', 'aborted', 'legacy-rolled-back', 'legacy-aborted']);
+const exact = (value, keys) => value &&
+  typeof value === 'object' &&
+  !Array.isArray(value) &&
+  Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+
+export function canonicalJson(value, depth = 0) {
+  if (depth > 16) throw new Error('Protocol nesting exceeds its bound.');
+  if (value === null || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'string') {
+    if (value.length > 16384) throw new Error('Protocol string exceeds its bound.');
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'number' && Number.isSafeInteger(value)) return String(value);
+  if (Array.isArray(value)) {
+    if (value.length > 128) throw new Error('Protocol array exceeds its bound.');
+    return `[${value.map(item => canonicalJson(item, depth + 1)).join(',')}]`;
+  }
+  if (!value ||
+      typeof value !== 'object' ||
+      Object.getPrototypeOf(value) !== Object.prototype) throw new Error('Unsupported protocol value.');
+  const keys = Object.keys(value).sort();
+  if (keys.length > 128 ||
+      keys.some(key => ['__proto__', 'constructor', 'prototype'].includes(key))) throw new Error('Invalid protocol keys.');
+  return `{${keys.map(key => `${JSON.stringify(key)}:${canonicalJson(value[key], depth + 1)}`).join(',')}}`;
+}
+
+export function operationDigest(value) {
+  return createHash('sha256').update(`${domain}/operation\0${canonicalJson(value)}`).digest('hex');
+}
+
+export function taskRevision(record) {
+  const value = { ...record };
+  delete value.currentUserSid;
+  return operationDigest(value);
+}
+
+export function accountOperationReference(binding) {
+  return { manifestPath: binding.manifestPath, operationId: binding.operationId,
+    taskPath: binding.taskPath, targetSid: binding.targetSid };
+}
+
+export function canonicalSid(value) {
+  if (typeof value !== 'string' ||
+      value.length > 184 ||
+      !value.startsWith('S-1-')) throw new Error('A canonical numeric Windows SID is required.');
+  const parts = value.slice(4).split('-');
+  if (parts.length < 2 ||
+      parts.length > 16 ||
+      parts.some(part => !part ||
+        part.length > 15 ||
+        (part.length > 1 && part[0] === '0') ||
+        [...part].some(character => character < '0' || character > '9'))) throw new Error('A canonical numeric Windows SID is required.');
+  return value;
+}
+
+export function validateTaskRequest(value, operationId, sequence, stateDigest) {
+  if (!exact(value, ['protocol', 'operationId', 'sequence', 'stateDigest', 'verb', 'body']) ||
+      value.protocol !== 1 ||
+      value.operationId !== operationId ||
+      value.sequence !== sequence ||
+      value.stateDigest !== stateDigest ||
+      !verbs.has(value.verb) ||
+      Buffer.byteLength(canonicalJson(value)) > 16384) throw new Error('Invalid, stale or out-of-order task request.');
+  if (['INSPECT', 'HOLD', 'REPOINT', 'RESTORE', 'ENABLE', 'RECORDS'].includes(value.verb) &&
+      value.body !== null) throw new Error('Task requests cannot select a path, principal or definition.');
+  if (value.verb === 'HELLO' &&
+      (!exact(value.body, ['challenge', 'identity']) ||
+        typeof value.body.challenge !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(value.body.challenge))) throw new Error('Invalid worker challenge.');
+  if (value.verb === 'PLAN' &&
+      (!exact(value.body, ['digest', 'summary']) ||
+        !/^[a-f0-9]{64}$/.test(value.body.digest) ||
+        typeof value.body.summary !== 'string' ||
+        value.body.summary.length > 4096)) throw new Error('Invalid worker plan.');
+  if (value.verb === 'DONE' &&
+      !exact(value.body, ['status', 'directory', 'port', 'version'])) throw new Error('Invalid worker completion.');
+  if (value.verb === 'FAILED' &&
+      (!exact(value.body, ['message']) || typeof value.body.message !== 'string' || value.body.message.length > 512)) {
+    throw new Error('Invalid worker failure.');
+  }
+  return value;
+}
+
+export function peerBinding(identity) {
+  if (!identity ||
+      !Number.isSafeInteger(identity.pid) ||
+      identity.pid < 1 ||
+      typeof identity.creationTime !== 'string' ||
+      !/^[1-9][0-9]{0,19}$/.test(identity.creationTime) ||
+      !Number.isSafeInteger(identity.sessionId) ||
+      identity.sessionId < 1) throw new Error('Incomplete observed worker identity.');
+  return { pid: identity.pid, creationTime: identity.creationTime,
+    ownerSid: canonicalSid(identity.ownerSid), sessionId: identity.sessionId };
+}
+
+export function verifyTargetSession(value, expected) {
+  if (!value ||
+      value.source !== 'wts-account-sid-snapshot' ||
+      value.atomicRunExBinding !== false ||
+      !['active', 'disconnected'].includes(value.state) ||
+      value.ownerSid !== expected.ownerSid ||
+      value.sessionId !== expected.sessionId ||
+      typeof value.logonTime !== 'string' ||
+      !/^[1-9][0-9]{0,19}$/.test(value.logonTime) ||
+      (expected.logonTime !== undefined && value.logonTime !== expected.logonTime) ||
+      typeof value.observedAt !== 'string' ||
+      !Number.isFinite(Date.parse(value.observedAt))) {
+    throw new Error('Original-account session eligibility is missing, stale or changed; no atomic desktop reservation is claimed.');
+  }
+  return value;
+}
+
+export class ControllerSignatures {
+  constructor() {
+    const keys = generateKeyPairSync('ed25519');
+    this.key = keys.privateKey;
+    this.publicKey = keys.publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+  }
+
+  response({ operationId, digest, challenge, peer, targetSession, sequence, request, stateDigest, body }) {
+    const value = { protocol: 1, operationId, digest, challenge, peer: peerBinding(peer),
+      targetSession, sequence, requestDigest: operationDigest(request), stateDigest, body };
+    const bytes = Buffer.from(`${domain}/response\0${canonicalJson(value)}`);
+    return { ...value, signature: sign(null, bytes, this.key).toString('base64') };
+  }
+}
+
+export class WorkerSignatures {
+  constructor({ publicKey, operationId, digest, identity, targetSession }) {
+    this.key = createPublicKey({ key: Buffer.from(publicKey, 'base64'), type: 'spki', format: 'der' });
+    if (this.key.asymmetricKeyType !== 'ed25519') throw new Error('Unsupported controller signature key.');
+    this.operationId = operationId;
+    this.digest = digest;
+    this.identity = peerBinding(identity);
+    this.targetSession = verifyTargetSession(targetSession, this.identity);
+    this.challenge = randomBytes(32).toString('hex');
+    this.sequence = 0;
+    this.stateDigest = digest;
+  }
+
+  request(verb, body = null) {
+    return { protocol: 1, operationId: this.operationId, sequence: this.sequence,
+      stateDigest: this.stateDigest, verb, body };
+  }
+
+  accept(response, request) {
+    if (!exact(response, ['protocol', 'operationId', 'digest', 'challenge', 'peer', 'targetSession', 'sequence',
+      'requestDigest', 'stateDigest', 'body', 'signature'])) throw new Error('Malformed controller response.');
+    const { signature, ...value } = response;
+    if (value.protocol !== 1 ||
+        value.operationId !== this.operationId ||
+        value.digest !== this.digest ||
+        value.challenge !== this.challenge ||
+        value.sequence !== this.sequence ||
+        value.requestDigest !== operationDigest(request) ||
+        canonicalJson(value.peer) !== canonicalJson(this.identity) ||
+        !/^[a-f0-9]{64}$/.test(value.stateDigest) ||
+        typeof signature !== 'string' ||
+        signature.length !== 88 ||
+        !verify(null, Buffer.from(`${domain}/response\0${canonicalJson(value)}`), this.key, Buffer.from(signature, 'base64'))) {
+      throw new Error('Controller authentication or transcript binding failed.');
+    }
+    verifyTargetSession(value.targetSession, this.targetSession);
+    this.sequence++;
+    this.stateDigest = value.stateDigest;
+    return value.body;
+  }
+}

package/bin/top.mjs

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 /**
  * mcp-pacemaker top — live terminal dashboard (Ink). Same data as the web /ui.
- * Reads the bridge port from ~/.mcp-pacemaker/state.json (or --port) and the admin
- * nonce from ~/.mcp-pacemaker/admin.nonce for the Recycle keybind. No JSX (uses createElement).
+ * Explicit instance calls supply both port and config; otherwise reads the default
+ * HOME state and nonce for the Recycle keybind. No JSX (uses createElement).
  */
 import { createElement as h, useState, useEffect } from 'react';
 import { render, Box, Text, useApp, useInput } from 'ink';
 import http from 'node:http';
 import { readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
 
 const HOME = resolve(homedir(), '.mcp-pacemaker');
@@ -34,7 +34,10 @@ export function recycleServer(port, name, nonce) {
   });
 }
 
-const readNonce = () => { try { return readFileSync(resolve(HOME, 'admin.nonce'), 'utf8').trim(); } catch { return ''; } };
+const readNonce = (config) => {
+  try { return readFileSync(resolve(config ? dirname(config) : HOME, 'admin.nonce'), 'utf8').trim(); }
+  catch { return ''; }
+};
 // Pure: pick the bridge port from a parsed state object (list shape wins, legacy {port} fallback).
 export function portFromState(state) {
   if (state && Array.isArray(state.hosts)) return state.hosts[0]?.port || 8791;
@@ -56,7 +59,16 @@ const healthCell = (s) => {
   return { text: st === 'failing' && s.health.consecutiveFailures > 1 ? `FAIL×${s.health.consecutiveFailures}` : h.text, color: h.color };
 };
 
-function App({ port }) {
+export function topClient(port, config) {
+  const selectedPort = resolvePort(port);
+  const selectedConfig = config ? resolve(config) : undefined;
+  return {
+    snapshot: () => fetchSnapshot(selectedPort),
+    recycle: name => recycleServer(selectedPort, name, readNonce(selectedConfig)),
+  };
+}
+
+function App({ client }) {
   const { exit } = useApp();
   const [snap, setSnap] = useState(null);
   const [sel, setSel] = useState(0);
@@ -64,11 +76,11 @@ function App({ port }) {
 
   useEffect(() => {
     let alive = true;
-    const tick = async () => { const s = await fetchSnapshot(port); if (alive) setSnap(s); };
+    const tick = async () => { const s = await client.snapshot(); if (alive) setSnap(s); };
     tick();
     const t = setInterval(tick, 1500);
     return () => { alive = false; clearInterval(t); };
-  }, [port]);
+  }, [client]);
 
   const servers = snap?.servers ?? [];
 
@@ -81,7 +93,7 @@ function App({ port }) {
       if (!s) return;
       if (s.type === 'http') { setMsg('http servers have no child to recycle'); return; }
       setMsg(`recycling ${s.name}…`);
-      recycleServer(port, s.name, readNonce()).then((r) =>
+      client.recycle(s.name).then((r) =>
         setMsg(r && r.status === 200 ? `recycled ${s.name} (${r.body?.recycled ?? 0})` : `recycle failed (${r?.status ?? 'no nonce/bridge'})`),
       );
     }
@@ -110,6 +122,6 @@ function App({ port }) {
   );
 }
 
-export function runTop(port) {
-  render(h(App, { port: resolvePort(port) }));
+export function runTop(port, config, options) {
+  return render(h(App, { client: topClient(port, config) }), options);
 }

package/bin/update-check.mjs

@@ -75,7 +75,7 @@ export function validateRegistry(registry) {
   return url.href;
 }
 
-function npmCliPath() {
+export function npmCliPath() {
   const candidates = [];
   if (process.env.npm_execpath) candidates.push(process.env.npm_execpath);
   candidates.push(join(dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'));
@@ -105,12 +105,23 @@ export async function readNpmMetadata(spec, field, { registry, cache, run = runF
     throw new Error('Registry metadata unavailable (offline, denied, missing, or npm failed). Check your approved npm configuration; no fallback selected.');
   }
   try {
-    return JSON.parse(stdout);
+    return normalizeNpmMetadata(JSON.parse(stdout));
   } catch {
     throw new Error('npm returned invalid metadata. No fallback selected.');
   }
 }
 
+export function normalizeNpmMetadata(value) {
+  if (Array.isArray(value)) {
+    if (value.length !== 1) throw new Error('Expected one exact npm metadata result.');
+    value = value[0];
+  }
+  if (!value ||
+      typeof value !== 'object' ||
+      Array.isArray(value)) throw new Error('Expected an npm metadata object.');
+  return value;
+}
+
 export async function checkForUpdate(pkg, { registry, read = readNpmMetadata } = {}) {
   updateChannel(pkg);
   registry = validateRegistry(registry);

package/bin/upgrade-autostart.mjs

@@ -0,0 +1,47 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+
+export function readAutostart(port) {
+  if (port === 0) return [];
+  if (process.platform === 'win32') {
+    const script = fileURLToPath(new URL('../autostart/windows/inspect-task.ps1', import.meta.url));
+    let stdout;
+    try {
+      stdout = execFileSync('pwsh', ['-NoProfile', '-File', script, '-Port', String(port)], {
+        encoding: 'utf8', windowsHide: true, timeout: 10000,
+      });
+    } catch {
+      throw new Error('Selected Windows autostart could not be inspected. No migration or stop was attempted.');
+    }
+    const result = JSON.parse(stdout);
+    if (!Array.isArray(result)) throw new Error('Invalid Windows autostart inspection.');
+    return result;
+  }
+  const paths = process.platform === 'darwin'
+    ? [
+      join(homedir(), 'Library', 'LaunchAgents', `io.github.girishkvs.mcp-pacemaker.${port}.plist`),
+      join(homedir(), 'Library', 'LaunchAgents', 'io.github.girishkvs.mcp-pacemaker.plist'),
+    ]
+    : [
+      join(homedir(), '.config', 'systemd', 'user', `mcp-pacemaker-${port}.service`),
+      join(homedir(), '.config', 'systemd', 'user', 'mcp-pacemaker.service'),
+    ];
+  return paths.filter(existsSync).map(path => ({ path, content: readFileSync(path, 'utf8') }));
+}
+
+export function inspectAutostart(instance) {
+  const actual = readAutostart(instance.port);
+  if (instance.autostart?.kind === 'none') {
+    if (actual.length) throw new Error('Unknown OS autostart registration exists. Exact legacy migration is required before upgrade.');
+    return { kind: 'none' };
+  }
+  if (instance.autostart?.kind !== 'stable' ||
+      !isDeepStrictEqual(actual, instance.autostart.records)) {
+    throw new Error('Selected autostart registration changed or is unknown; refusing before stop.');
+  }
+  return { kind: 'stable', launcher: join(instance.directory, 'stable-launcher.mjs') };
+}

package/bin/upgrade-capability.json

@@ -0,0 +1,8 @@
+{
+  "protocol": 1,
+  "portZero": true,
+  "admission": true,
+  "cli": true,
+  "legacyRestartProtocol": 1,
+  "accountWorkerProtocol": 1
+}